11
/* default fontpath for unix systems */
12
#define DEFAULT_FONTPATH "/usr/share/fonts/truetype"
13
#define PATHSEPARATOR ":"
16
/* gd.h: declarations file for the graphic-draw module.
17
* Permission to use, copy, modify, and distribute this software and its
18
* documentation for any purpose and without fee is hereby granted, provided
19
* that the above copyright notice appear in all copies and that both that
20
* copyright notice and this permission notice appear in supporting
21
* documentation. This software is provided "AS IS." Thomas Boutell and
22
* Boutell.Com, Inc. disclaim all warranties, either express or implied,
23
* including but not limited to implied warranties of merchantability and
24
* fitness for a particular purpose, with respect to this code and accompanying
27
/* stdio is needed for file I/O. */
31
/* The maximum number of palette entries in palette-based images.
32
In the wonderful new world of gd 2.0, you can of course have
33
many more colors when using truecolor mode. */
35
#define gdMaxColors 256
37
/* Image type. See functions below; you will not need to change
38
the elements directly. Use the provided macros to
39
access sx, sy, the color table, and colorsTotal for
40
read-only purposes. */
42
/* If 'truecolor' is set true, the image is truecolor;
43
pixels are represented by integers, which
44
must be 32 bits wide or more.
46
True colors are repsented as follows:
50
Where 'A' (alpha channel) occupies only the
51
LOWER 7 BITS of the MSB. This very small
52
loss of alpha channel resolution allows gd 2.x
53
to keep backwards compatibility by allowing
54
signed integers to be used to represent colors,
55
and negative numbers to represent special cases,
58
#define gdAlphaMax 127
59
#define gdAlphaOpaque 0
60
#define gdAlphaTransparent 127
62
#define gdGreenMax 255
64
#define gdTrueColorGetAlpha(c) (((c) & 0x7F000000) >> 24)
65
#define gdTrueColorGetRed(c) (((c) & 0xFF0000) >> 16)
66
#define gdTrueColorGetGreen(c) (((c) & 0x00FF00) >> 8)
67
#define gdTrueColorGetBlue(c) ((c) & 0x0000FF)
69
/* This function accepts truecolor pixel values only. The
70
source color is composited with the destination color
71
based on the alpha channel value of the source color.
72
The resulting color is opaque. */
74
int gdAlphaBlend(int dest, int src);
76
typedef struct gdImageStruct {
77
/* Palette-based image pixels */
78
unsigned char ** pixels;
81
/* These are valid in palette images only. See also
82
'alpha', which appears later in the structure to
83
preserve binary backwards compatibility */
86
int green[gdMaxColors];
87
int blue[gdMaxColors];
88
int open[gdMaxColors];
89
/* For backwards compatibility, this is set to the
90
first palette entry with 100% transparency,
91
and is also set and reset by the
92
gdImageColorTransparent function. Newer
93
applications can allocate palette entries
94
with any desired level of transparency; however,
95
bear in mind that many viewers, notably
96
many web browsers, fail to implement
97
full alpha channel for PNG and provide
98
support for full opacity or transparency only. */
102
struct gdImageStruct *brush;
103
struct gdImageStruct *tile;
104
int brushColorMap[gdMaxColors];
105
int tileColorMap[gdMaxColors];
110
/* New in 2.0: thickness of line. Initialized to 1. */
112
/* New in 2.0: alpha channel for palettes. Note that only
113
Macintosh Internet Explorer and (possibly) Netscape 6
114
really support multiple levels of transparency in
115
palettes, to my knowledge, as of 2/15/01. Most
116
common browsers will display 100% opaque and
117
100% transparent correctly, and do something
118
unpredictable and/or undesirable for levels
120
int alpha[gdMaxColors];
121
/* Truecolor flag and pixels. New 2.0 fields appear here at the
122
end to minimize breakage of existing object code. */
125
/* Should alpha channel be copied, or applied, each time a
126
pixel is drawn? This applies to truecolor images only.
127
No attempt is made to alpha-blend in palette images,
128
even if semitransparent palette entries exist.
129
To do that, build your image as a truecolor image,
130
then quantize down to 8 bits. */
131
int alphaBlendingFlag;
132
/* Should the alpha channel of the image be saved? This affects
133
PNG at the moment; other future formats may also
134
have that capability. JPEG doesn't. */
138
typedef gdImage * gdImagePtr;
141
/* # of characters in font */
143
/* First character is numbered... (usually 32 = space) */
145
/* Character width and height */
148
/* Font data; array of characters, one row after another.
149
Easily included in code, also easily loaded from
154
/* Text functions take these. */
155
typedef gdFont *gdFontPtr;
157
/* For backwards compatibility only. Use gdImageSetStyle()
158
for MUCH more flexible line drawing. Also see
159
gdImageSetBrush(). */
162
/* Special colors. */
164
#define gdStyled (-2)
165
#define gdBrushed (-3)
166
#define gdStyledBrushed (-4)
169
/* NOT the same as the transparent color index.
170
This is used in line styles only. */
171
#define gdTransparent (-6)
173
/* Functions to manipulate images. */
175
/* Creates a palette-based image (up to 256 colors). */
176
gdImagePtr gdImageCreate(int sx, int sy);
178
/* An alternate name for the above (2.0). */
179
#define gdImageCreatePalette gdImageCreate
181
/* Creates a truecolor image (millions of colors). */
182
gdImagePtr gdImageCreateTrueColor(int sx, int sy);
184
/* Creates an image from various file types. These functions
185
return a palette or truecolor image based on the
186
nature of the file being loaded. Truecolor PNG
187
stays truecolor; palette PNG stays palette-based;
188
JPEG is always truecolor. */
189
gdImagePtr gdImageCreateFromPng(FILE *fd);
190
gdImagePtr gdImageCreateFromPngCtx(gdIOCtxPtr in);
191
gdImagePtr gdImageCreateFromGif(FILE *fd);
192
gdImagePtr gdImageCreateFromGifCtx(gdIOCtxPtr in);
193
gdImagePtr gdImageCreateFromWBMP(FILE *inFile);
194
gdImagePtr gdImageCreateFromWBMPCtx(gdIOCtx *infile);
195
gdImagePtr gdImageCreateFromJpeg(FILE *infile);
196
gdImagePtr gdImageCreateFromJpegCtx(gdIOCtx *infile);
198
/* A custom data source. */
199
/* The source function must return -1 on error, otherwise the number
200
of bytes fetched. 0 is EOF, not an error! */
201
/* context will be passed to your source function. */
204
int (*source) (void *context, char *buffer, int len);
206
} gdSource, *gdSourcePtr;
208
gdImagePtr gdImageCreateFromPngSource(gdSourcePtr in);
210
gdImagePtr gdImageCreateFromGd(FILE *in);
211
gdImagePtr gdImageCreateFromGdCtx(gdIOCtxPtr in);
213
gdImagePtr gdImageCreateFromGd2(FILE *in);
214
gdImagePtr gdImageCreateFromGd2Ctx(gdIOCtxPtr in);
216
gdImagePtr gdImageCreateFromGd2Part(FILE *in, int srcx, int srcy, int w, int h);
217
gdImagePtr gdImageCreateFromGd2PartCtx(gdIOCtxPtr in, int srcx, int srcy, int w, int h);
219
gdImagePtr gdImageCreateFromXbm(FILE *fd);
221
void gdImageDestroy(gdImagePtr im);
223
/* Replaces or blends with the background depending on the
224
most recent call to gdImageAlphaBlending and the
225
alpha channel value of 'color'; default is to overwrite.
226
Tiling and line styling are also implemented
227
here. All other gd drawing functions pass through this call,
228
allowing for many useful effects. */
230
void gdImageSetPixel(gdImagePtr im, int x, int y, int color);
232
int gdImageGetPixel(gdImagePtr im, int x, int y);
234
void gdImageLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color);
236
/* For backwards compatibility only. Use gdImageSetStyle()
237
for much more flexible line drawing. */
238
void gdImageDashedLine(gdImagePtr im, int x1, int y1, int x2, int y2, int color);
239
/* Corners specified (not width and height). Upper left first, lower right
241
void gdImageRectangle(gdImagePtr im, int x1, int y1, int x2, int y2, int color);
242
/* Solid bar. Upper left corner first, lower right corner second. */
243
void gdImageFilledRectangle(gdImagePtr im, int x1, int y1, int x2, int y2, int color);
244
int gdImageBoundsSafe(gdImagePtr im, int x, int y);
245
void gdImageChar(gdImagePtr im, gdFontPtr f, int x, int y, int c, int color);
246
void gdImageCharUp(gdImagePtr im, gdFontPtr f, int x, int y, int c, int color);
247
void gdImageString(gdImagePtr im, gdFontPtr f, int x, int y, unsigned char *s, int color);
248
void gdImageStringUp(gdImagePtr im, gdFontPtr f, int x, int y, unsigned char *s, int color);
249
void gdImageString16(gdImagePtr im, gdFontPtr f, int x, int y, unsigned short *s, int color);
250
void gdImageStringUp16(gdImagePtr im, gdFontPtr f, int x, int y, unsigned short *s, int color);
252
/* Calls gdImageStringFT. Provided for backwards compatibility only. */
253
char *gdImageStringTTF(gdImage *im, int *brect, int fg, char *fontlist,
254
double ptsize, double angle, int x, int y, char *string);
256
/* FreeType 2 text output */
257
char *gdImageStringFT(gdImage *im, int *brect, int fg, char *fontlist,
258
double ptsize, double angle, int x, int y, char *string);
260
/* Point type for use in polygon drawing. */
263
} gdPoint, *gdPointPtr;
265
void gdImagePolygon(gdImagePtr im, gdPointPtr p, int n, int c);
266
void gdImageFilledPolygon(gdImagePtr im, gdPointPtr p, int n, int c);
268
/* These functions still work with truecolor images,
269
for which they never return error. */
270
int gdImageColorAllocate(gdImagePtr im, int r, int g, int b);
271
/* gd 2.0: palette entries with non-opaque transparency are permitted. */
272
int gdImageColorAllocateAlpha(gdImagePtr im, int r, int g, int b, int a);
273
/* Assumes opaque is the preferred alpha channel value */
274
int gdImageColorClosest(gdImagePtr im, int r, int g, int b);
275
/* Closest match taking all four parameters into account.
276
A slightly different color with the same transparency
277
beats the exact same color with radically different
279
int gdImageColorClosestAlpha(gdImagePtr im, int r, int g, int b, int a);
280
/* Returns exact, 100% opaque matches only */
281
int gdImageColorExact(gdImagePtr im, int r, int g, int b);
282
/* Returns an exact match only, including alpha */
283
int gdImageColorExactAlpha(gdImagePtr im, int r, int g, int b, int a);
285
int gdImageColorResolve(gdImagePtr im, int r, int g, int b);
286
/* Based on gdImageColorExactAlpha and gdImageColorClosestAlpha */
287
int gdImageColorResolveAlpha(gdImagePtr im, int r, int g, int b, int a);
289
/* A simpler way to obtain an opaque truecolor value for drawing on a
290
truecolor image. Not for use with palette images! */
292
#define gdTrueColor(r, g, b) (((r) << 16) + \
296
/* Returns a truecolor value with an alpha channel component.
297
gdAlphaMax (127, **NOT 255**) is transparent, 0 is completely
300
#define gdTrueColorAlpha(r, g, b, a) (((a) << 24) + \
305
void gdImageColorDeallocate(gdImagePtr im, int color);
307
/* Converts a truecolor image to a palette-based image,
308
using a high-quality two-pass quantization routine
309
which attempts to preserve alpha channel information
310
as well as R/G/B color information when creating
311
a palette. If ditherFlag is set, the image will be
312
dithered to approximate colors better, at the expense
313
of some obvious "speckling." colorsWanted can be
314
anything up to 256. If the original source image
315
includes photographic information or anything that
316
came out of a JPEG, 256 is strongly recommended.
318
Better yet, don't use this function -- write real
319
truecolor PNGs and JPEGs. The disk space gain of
320
conversion to palette is not great (for small images
321
it can be negative) and the quality loss is ugly. */
323
void gdImageTrueColorToPalette(gdImagePtr im, int ditherFlag, int colorsWanted);
325
/* Specifies a color index (if a palette image) or an
326
RGB color (if a truecolor image) which should be
327
considered 100% transparent. FOR TRUECOLOR IMAGES,
328
THIS IS IGNORED IF AN ALPHA CHANNEL IS BEING
329
SAVED. Use gdImageSaveAlpha(im, 0); to
330
turn off the saving of a full alpha channel in
331
a truecolor image. Note that gdImageColorTransparent
332
is usually compatible with older browsers that
333
do not understand full alpha channels well. TBB */
334
void gdImageColorTransparent(gdImagePtr im, int color);
336
void gdImagePaletteCopy(gdImagePtr dst, gdImagePtr src);
337
void gdImagePng(gdImagePtr im, FILE *out);
338
void gdImagePngCtx(gdImagePtr im, gdIOCtx *out);
340
void gdImageWBMP(gdImagePtr image, int fg, FILE *out);
341
void gdImageWBMPCtx(gdImagePtr image, int fg, gdIOCtx *out);
343
/* Guaranteed to correctly free memory returned
344
by the gdImage*Ptr functions */
345
void gdFree(void *m);
347
/* Best to free this memory with gdFree(), not free() */
348
void *gdImageWBMPPtr(gdImagePtr im, int *size, int fg);
350
void gdImageGif(gdImagePtr im, FILE *outFile);
351
void gdImageGifCtx(gdImagePtr im, gdIOCtx *out);
353
void gdImageJpeg(gdImagePtr im, FILE *out, int quality);
354
void gdImageJpegCtx(gdImagePtr im, gdIOCtx *out, int quality);
356
/* Best to free this memory with gdFree(), not free() */
357
void *gdImageJpegPtr(gdImagePtr im, int *size, int quality);
359
/* A custom data sink. For backwards compatibility. Use
361
/* The sink function must return -1 on error, otherwise the number
362
of bytes written, which must be equal to len. */
363
/* context will be passed to your sink function. */
365
int (*sink) (void *context, const char *buffer, int len);
367
} gdSink, *gdSinkPtr;
369
void gdImagePngToSink(gdImagePtr im, gdSinkPtr out);
371
void gdImageGd(gdImagePtr im, FILE *out);
372
void gdImageGd2(gdImagePtr im, FILE *out, int cs, int fmt);
374
/* Best to free this memory with gdFree(), not free() */
375
void* gdImagePngPtr(gdImagePtr im, int *size);
377
/* Best to free this memory with gdFree(), not free() */
378
void* gdImageGdPtr(gdImagePtr im, int *size);
380
/* Best to free this memory with gdFree(), not free() */
381
void* gdImageGd2Ptr(gdImagePtr im, int cs, int fmt, int *size);
383
void gdImageEllipse(gdImagePtr im, int cx, int cy, int w, int h, int color);
385
/* Style is a bitwise OR ( | operator ) of these.
386
gdArc and gdChord are mutually exclusive;
387
gdChord just connects the starting and ending
388
angles with a straight line, while gdArc produces
389
a rounded edge. gdPie is a synonym for gdArc.
390
gdNoFill indicates that the arc or chord should be
391
outlined, not filled. gdEdged, used together with
392
gdNoFill, indicates that the beginning and ending
393
angles should be connected to the center; this is
394
a good way to outline (rather than fill) a
402
void gdImageFilledArc(gdImagePtr im, int cx, int cy, int w, int h, int s, int e, int color, int style);
403
void gdImageArc(gdImagePtr im, int cx, int cy, int w, int h, int s, int e, int color);
404
void gdImageFilledEllipse(gdImagePtr im, int cx, int cy, int w, int h, int color);
405
void gdImageFillToBorder(gdImagePtr im, int x, int y, int border, int color);
406
void gdImageFill(gdImagePtr im, int x, int y, int color);
407
void gdImageCopy(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int w, int h);
408
void gdImageCopyMerge(gdImagePtr dst, gdImagePtr src, int dstX, int dstY,
409
int srcX, int srcY, int w, int h, int pct);
410
void gdImageCopyMergeGray(gdImagePtr dst, gdImagePtr src, int dstX, int dstY,
411
int srcX, int srcY, int w, int h, int pct);
413
/* Stretches or shrinks to fit, as needed. Does NOT attempt
414
to average the entire set of source pixels that scale down onto the
415
destination pixel. */
416
void gdImageCopyResized(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int dstW, int dstH, int srcW, int srcH);
418
/* gd 2.0: stretches or shrinks to fit, as needed. When called with a
419
truecolor destination image, this function averages the
420
entire set of source pixels that scale down onto the
421
destination pixel, taking into account what portion of the
422
destination pixel each source pixel represents. This is a
423
floating point operation, but this is not a performance issue
424
on modern hardware, except for some embedded devices. If the
425
destination is a palette image, gdImageCopyResized is
426
substituted automatically. */
427
void gdImageCopyResampled(gdImagePtr dst, gdImagePtr src, int dstX, int dstY, int srcX, int srcY, int dstW, int dstH, int srcW, int srcH);
429
void gdImageSetBrush(gdImagePtr im, gdImagePtr brush);
430
void gdImageSetTile(gdImagePtr im, gdImagePtr tile);
431
void gdImageSetStyle(gdImagePtr im, int *style, int noOfPixels);
432
/* Line thickness (defaults to 1). Affects lines, ellipses,
433
rectangles, polygons and so forth. */
434
void gdImageSetThickness(gdImagePtr im, int thickness);
435
/* On or off (1 or 0) for all three of these. */
436
void gdImageInterlace(gdImagePtr im, int interlaceArg);
437
void gdImageAlphaBlending(gdImagePtr im, int alphaBlendingArg);
438
void gdImageSaveAlpha(gdImagePtr im, int saveAlphaArg);
440
/* Macros to access information about images. */
442
/* Returns nonzero if the image is a truecolor image,
443
zero for a palette image. */
445
#define gdImageTrueColor(im) ((im)->trueColor)
447
#define gdImageSX(im) ((im)->sx)
448
#define gdImageSY(im) ((im)->sy)
449
#define gdImageColorsTotal(im) ((im)->colorsTotal)
450
#define gdImageRed(im, c) ((im)->trueColor ? gdTrueColorGetRed(c) : \
452
#define gdImageGreen(im, c) ((im)->trueColor ? gdTrueColorGetGreen(c) : \
454
#define gdImageBlue(im, c) ((im)->trueColor ? gdTrueColorGetBlue(c) : \
456
#define gdImageAlpha(im, c) ((im)->trueColor ? gdTrueColorGetAlpha(c) : \
458
#define gdImageGetTransparent(im) ((im)->transparent)
459
#define gdImageGetInterlaced(im) ((im)->interlace)
461
/* These macros provide direct access to pixels in
462
palette-based and truecolor images, respectively.
463
If you use these macros, you must perform your own
464
bounds checking. Use of the macro for the correct type
465
of image is also your responsibility. */
466
#define gdImagePalettePixel(im, x, y) (im)->pixels[(y)][(x)]
467
#define gdImageTrueColorPixel(im, x, y) (im)->tpixels[(y)][(x)]
469
/* I/O Support routines. */
471
gdIOCtx* gdNewFileCtx(FILE*);
472
gdIOCtx* gdNewDynamicCtx(int, void*);
473
gdIOCtx* gdNewSSCtx(gdSourcePtr in, gdSinkPtr out);
474
void* gdDPExtractData(struct gdIOCtx* ctx, int *size);
476
#define GD2_CHUNKSIZE 128
477
#define GD2_CHUNKSIZE_MIN 64
478
#define GD2_CHUNKSIZE_MAX 4096
482
#define GD2_FMT_RAW 1
483
#define GD2_FMT_COMPRESSED 2
485
/* Image comparison definitions */
486
int gdImageCompare(gdImagePtr im1, gdImagePtr im2);
488
#define GD_CMP_IMAGE 1 /* Actual image IS different */
489
#define GD_CMP_NUM_COLORS 2 /* Number of Colours in pallette differ */
490
#define GD_CMP_COLOR 4 /* Image colours differ */
491
#define GD_CMP_SIZE_X 8 /* Image width differs */
492
#define GD_CMP_SIZE_Y 16 /* Image heights differ */
493
#define GD_CMP_TRANSPARENT 32 /* Transparent colour */
494
#define GD_CMP_BACKGROUND 64 /* Background colour */
495
#define GD_CMP_INTERLACE 128 /* Interlaced setting */
496
#define GD_CMP_TRUECOLOR 256 /* Truecolor vs palette differs */
498
/* resolution affects ttf font rendering, particularly hinting */
499
#define GD_RESOLUTION 96 /* pixels per inch */
added
removed
gd/gd.h
