GraphicsMagick Core C API

The GraphicsMagick core C library constitutes the implementation of GraphicsMagick and provides the lowest-level C language programming interface for GraphicsMagick. The core C API provides many functions to read, manipulate, write, or display an image. To invoke the functions, write your program in C (or C++) language while making calls to the core library functions and link with libGraphicsMagick.a, libGraphicsMagick.so, or GraphicsMagick.dll depending on your system.

The API is divided into a number of categories. While reading this documentation, please reference the types documentation as required:

Here is a sample program to get you started. To find out about all the functions that are available, read the source code. Each function is delineated with a full rows of percent signs with comments describing the parameters required for the function and what it does. For ease in finding a function, they are sorted in alphabetical order.

Here is a full example of a program, demo.c, which reads multiple input files (possibly animation files) specified on the command line, resizes the image frames to 106x80, and writes the resulting animation to disk:

#include <stdio.h>
#include <string.h>
#include <time.h>
#include <sys/types.h>
#include <magick/api.h>

int main(int argc,char **argv)
{
  ExceptionInfo
    exception;

  Image
    *image,
    *images,
    *resize_image,
    *thumbnails;

  ImageInfo
    *image_info;

  int
    i;

  /*
    Initialize the image info structure and read the list of files
    provided by the user as a image sequence
  */
  InitializeMagick(*argv);
  GetExceptionInfo(&exception);
  image_info=CloneImageInfo((ImageInfo *) NULL);
  images=NewImageList();
  for (i=1; i< argc-1; i++)
    {
      (void) strcpy(image_info->filename,argv[i]);
      printf("Reading %s ...", image_info->filename);
      image=ReadImage(image_info,&exception);
      printf(" %lu frames\n", GetImageListLength(image));
      if (exception.severity != UndefinedException)
        CatchException(&exception);
      if (image)
        (void) AppendImageToList(&images,image);
    }

  if (!images)
    {
      printf("Failed to read any images!\n");
      exit(1);
    }
  /*
    Create a thumbnail image sequence
  */
  thumbnails=NewImageList();
  while ((image=RemoveFirstImageFromList(&images)) != (Image *) NULL)
    {
      resize_image=ResizeImage(image,106,80,LanczosFilter,1.0,&exception);
      DestroyImage(image);
      if (resize_image == (Image *) NULL)
        {
          CatchException(&exception);
          continue;
        }
      (void) AppendImageToList(&thumbnails,resize_image);
    }
  /*
    Write the thumbnail image sequence to file
  */
  if (thumbnails)
    {
      (void) strcpy(thumbnails->filename,argv[argc-1]);
      printf("Writing %s ... %lu frames\n", thumbnails->filename,
             GetImageListLength(thumbnails));
      WriteImage(image_info,thumbnails);
    }

  /*
    Release resources
  */
  DestroyImageList(thumbnails);
  DestroyImageInfo(image_info);
  DestroyExceptionInfo(&exception);
  DestroyMagick();
  return(0);
}

Now we need to compile. On Unix, the command would look something like this:

gcc -o demo demo.c -O `GraphicsMagick-config --cppflags --ldflags --libs`

As a usage example, with the input files in1.gif, in2.png, and in3.jpg, create the animation file out.miff:

demo in1.gif in2.png in3.jpg out.miff

The resulting animation may be played on an X11 display using 'gm animate out.miff'.

The GraphicsMagick-config script reproduces the options which were used to compile the GraphicsMagick utilities. Using compatible options ensures that your program will compile and run.

Another example is smile.c. Compile and execute it to display a smiley face on your X server.


Copyright © GraphicsMagick Group 2002 - 2012