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 are a few sample programs to get you started.

This example program (convert.c) simply converts from one file name to another (and will automatically change formats based on file extension):

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

int main ( int argc, char **argv )
{
  Image
    *image = (Image *) NULL;

  char
    infile[MaxTextExtent],
    outfile[MaxTextExtent];

  int
    arg = 1,
    exit_status = 0;

  ImageInfo
    *imageInfo;

  ExceptionInfo
    exception;

  InitializeMagick(NULL);
  imageInfo=CloneImageInfo(0);
  GetExceptionInfo(&exception);

  if (argc != 3)
    {
      (void) fprintf ( stderr, "Usage: %s infile outfile\n", argv[0] );
      (void) fflush(stderr);
      exit_status = 1;
      goto program_exit;
    }

  (void) strncpy(infile, argv[arg], MaxTextExtent-1 );
  arg++;
  (void) strncpy(outfile, argv[arg], MaxTextExtent-1 );

  (void) strcpy(imageInfo->filename, infile);
  image = ReadImage(imageInfo, &exception);
  if (image == (Image *) NULL)
    {
      CatchException(&exception);
      exit_status = 1;
      goto program_exit;
    }

  (void) strcpy(image->filename, outfile);
  if (!WriteImage (imageInfo,image))
    {
      CatchException(&image->exception);
      exit_status = 1;
      goto program_exit;
    }

 program_exit:

  if (image != (Image *) NULL)
    DestroyImage(image);

  if (imageInfo != (ImageInfo *) NULL)
    DestroyImageInfo(imageInfo);
  DestroyMagick();

  return exit_status;
}

This example 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]);
      image_info->adjoin=MagickTrue;
      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);
}

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.

Copyright © GraphicsMagick Group 2002 - 2023