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