1.. -*- mode: rst -*- 2.. This text is in reStucturedText format, so it may look a bit odd. 3.. See http://docutils.sourceforge.net/rst.html for details. 4 5========================= 6GraphicsMagick Core C API 7========================= 8 9.. _Animate : animate.html 10.. _Annotate : annotate.html 11.. _Attribute : attribute.html 12.. _Average : average.html 13.. _`ASC CDL` : cdl.html 14.. _Blob : blob.html 15.. _Channel : channel.html 16.. _Color : color.html 17.. _Colormap : colormap.html 18.. _Compare : compare.html 19.. _Composite : composite.html 20.. _Confirm Access : confirm_access.html 21.. _Constitute : constitute.html 22.. _Decorate : decorate.html 23.. _Describe : describe.html 24.. _Display : display.html 25.. _Draw : draw.html 26.. _Effect : effect.html 27.. _Enhance : enhance.html 28.. _Error : error.html 29.. _Export : export.html 30.. _FX : fx.html 31.. _`Hald CLUT` : hclut.html 32.. _Image : image.html 33.. _Import : import.html 34.. _List : list.html 35.. _Log : log.html 36.. _Magick : magick.html 37.. _Memory : memory.html 38.. _Monitor : monitor.html 39.. _Montage : montage.html 40.. _Operator : operator.html 41.. _Paint : paint.html 42.. _Pixel Cache : pixel_cache.html 43.. _Pixel Iterator : pixel_iterator.html 44.. _Plasma : plasma.html 45.. _Profile : profile.html 46.. _Quantize : quantize.html 47.. _Registry : registry.html 48.. _Render : render.html 49.. _Resize : resize.html 50.. _Resource : resource.html 51.. _Segment : segment.html 52.. _Shear : shear.html 53.. _Signature : signature.html 54.. _Statistics : statistics.html 55.. _Texture : texture.html 56.. _Transform : transform.html 57.. _types: types.html 58 59The GraphicsMagick core C library constitutes the implementation of 60GraphicsMagick and provides the lowest-level C language programming 61interface for GraphicsMagick. The core C API provides many functions 62to read, manipulate, write, or display an image. To invoke the 63functions, write your program in C (or C++) language while making 64calls to the core library functions and link with libGraphicsMagick.a, 65libGraphicsMagick.so, or GraphicsMagick.dll depending on your system. 66 67The API is divided into a number of categories. While reading this 68documentation, please reference the types_ documentation as required: 69 70 * Animate_: Interactively animate an image sequence 71 * Annotate_: Annotate an image with text 72 * Attribute_: Access key, value image attributes 73 * Average_: Average several images together 74 * `ASC CDL`_ : Apply ASC CDL to image 75 * Blob_: Read and write images to memory 76 * Channel_: Import and export image channels as well as compute channel depth 77 * Color_: Methods to deal with image colors 78 * Colormap_: Methods to deal with image colormaps 79 * Compare_: Compare images 80 * Composite_: Composite images 81 * `Confirm Access`_ : Confirm access to files and URLs. 82 * Constitute_: Read, write, import, and export images 83 * Decorate_: Add fancy borders to images 84 * Describe_: Describe an image 85 * Display_: Interactively display and edit an image 86 * Draw_: Convenient methods to draw vectors and text 87 * Effect_:Threshold (various), blur, despeckle, edge, emboss, enhance, 88 gaussian blur ... 89 * Enhance_: Contrast, equalize, gamma, level, level channel, modulate, negate, 90 and normalize 91 * Error_: Error reporting methods 92 * Export_ : Export image pixels to common representations 93 * FX_: Special effects methods 94 * `Hald CLUT`_ : Apply Hald CLUT to image 95 * Image_: Miscellaneous image methods 96 * Import_ : Import image pixels from common representations 97 * List_: Manage image lists 98 * Log_: Event logging support 99 * Magick_: Image format support interfaces 100 * Memory_: Memory allocation methods 101 * Monitor_: Progress monitor callbacks 102 * Montage_: Create a montage of image thumbnails 103 * Operator_: Methods to apply mathematic or boolean operators to pixels 104 * Paint_: Fill pixel regions 105 * `Pixel Cache`_: Low-level access to image pixels 106 * `Pixel Iterator`_: Pixel iterator design pattern support functions 107 * Plasma_: Plasma fractal image generator 108 * Profile_: Attached profile access 109 * Quantize_: Reduce image colors or assign image colors from colormap 110 * Registry_: Store and retrieve images in memory by ID 111 * Render_: Render vector graphics 112 * Resize_: Resize an Image 113 * Resource_: Set and get resource limits 114 * Segment_: Coalese similar image colors 115 * Shear_: Rotate image, shear image, or apply a 2D affine transformation 116 * Signature_: Compute an image signature (checksum) 117 * Statistics_: Compute image statistics 118 * Texture_: Create a tiled texture image or tile an image with a texture. 119 * Transform_: Chop, coalesce, deconstruct, flatten, flip, flop, mosiac, roll, 120 or shave image 121 122Here are a few sample programs to get you started. 123 124This example program (convert.c) simply converts from one file name to 125another (and will automatically change formats based on file 126extension):: 127 128 #include <stdio.h> 129 #include <stdlib.h> 130 #include <string.h> 131 #include <time.h> 132 #include <sys/types.h> 133 #include <magick/api.h> 134 135 int main ( int argc, char **argv ) 136 { 137 Image 138 *image = (Image *) NULL; 139 140 char 141 infile[MaxTextExtent], 142 outfile[MaxTextExtent]; 143 144 int 145 arg = 1, 146 exit_status = 0; 147 148 ImageInfo 149 *imageInfo; 150 151 ExceptionInfo 152 exception; 153 154 InitializeMagick(NULL); 155 imageInfo=CloneImageInfo(0); 156 GetExceptionInfo(&exception); 157 158 if (argc != 3) 159 { 160 (void) fprintf ( stderr, "Usage: %s infile outfile\n", argv[0] ); 161 (void) fflush(stderr); 162 exit_status = 1; 163 goto program_exit; 164 } 165 166 (void) strncpy(infile, argv[arg], MaxTextExtent-1 ); 167 arg++; 168 (void) strncpy(outfile, argv[arg], MaxTextExtent-1 ); 169 170 (void) strcpy(imageInfo->filename, infile); 171 image = ReadImage(imageInfo, &exception); 172 if (image == (Image *) NULL) 173 { 174 CatchException(&exception); 175 exit_status = 1; 176 goto program_exit; 177 } 178 179 (void) strcpy(image->filename, outfile); 180 if (!WriteImage (imageInfo,image)) 181 { 182 CatchException(&image->exception); 183 exit_status = 1; 184 goto program_exit; 185 } 186 187 program_exit: 188 189 if (image != (Image *) NULL) 190 DestroyImage(image); 191 192 if (imageInfo != (ImageInfo *) NULL) 193 DestroyImageInfo(imageInfo); 194 DestroyMagick(); 195 196 return exit_status; 197 } 198 199This example program (demo.c) which reads multiple input files 200(possibly animation files) specified on the command line, resizes the 201image frames to 106x80, and writes the resulting animation to disk:: 202 203 #include <stdio.h> 204 #include <string.h> 205 #include <time.h> 206 #include <sys/types.h> 207 #include <magick/api.h> 208 209 int main(int argc,char **argv) 210 { 211 ExceptionInfo 212 exception; 213 214 Image 215 *image, 216 *images, 217 *resize_image, 218 *thumbnails; 219 220 ImageInfo 221 *image_info; 222 223 int 224 i; 225 226 /* 227 Initialize the image info structure and read the list of files 228 provided by the user as a image sequence 229 */ 230 InitializeMagick(*argv); 231 GetExceptionInfo(&exception); 232 image_info=CloneImageInfo((ImageInfo *) NULL); 233 images=NewImageList(); 234 for (i=1; i< argc-1; i++) 235 { 236 (void) strcpy(image_info->filename,argv[i]); 237 printf("Reading %s ...", image_info->filename); 238 image=ReadImage(image_info,&exception); 239 printf(" %lu frames\n", GetImageListLength(image)); 240 if (exception.severity != UndefinedException) 241 CatchException(&exception); 242 if (image) 243 (void) AppendImageToList(&images,image); 244 } 245 246 if (!images) 247 { 248 printf("Failed to read any images!\n"); 249 exit(1); 250 } 251 /* 252 Create a thumbnail image sequence 253 */ 254 thumbnails=NewImageList(); 255 while ((image=RemoveFirstImageFromList(&images)) != (Image *) NULL) 256 { 257 resize_image=ResizeImage(image,106,80,LanczosFilter,1.0,&exception); 258 DestroyImage(image); 259 if (resize_image == (Image *) NULL) 260 { 261 CatchException(&exception); 262 continue; 263 } 264 (void) AppendImageToList(&thumbnails,resize_image); 265 } 266 /* 267 Write the thumbnail image sequence to file 268 */ 269 if (thumbnails) 270 { 271 (void) strcpy(thumbnails->filename,argv[argc-1]); 272 image_info->adjoin=MagickTrue; 273 printf("Writing %s ... %lu frames\n", thumbnails->filename, 274 GetImageListLength(thumbnails)); 275 WriteImage(image_info,thumbnails); 276 } 277 278 /* 279 Release resources 280 */ 281 DestroyImageList(thumbnails); 282 DestroyImageInfo(image_info); 283 DestroyExceptionInfo(&exception); 284 DestroyMagick(); 285 return(0); 286 } 287 288To compile on Unix, the command would look something like this:: 289 290 gcc -o demo demo.c -O `GraphicsMagick-config --cppflags --ldflags --libs` 291 292As a usage example, with the input files in1.gif, in2.png, and in3.jpg, create 293the animation file out.miff:: 294 295 demo in1.gif in2.png in3.jpg out.miff 296 297The resulting animation may be played on an X11 display using 'gm animate 298out.miff'. 299 300The GraphicsMagick-config script reproduces the options which were used to 301compile the GraphicsMagick utilities. Using compatible options ensures that 302your program will compile and run. 303