diff options
| -rw-r--r-- | docs/naturaldocs/project/Menu.txt | 66 | ||||
| -rw-r--r-- | src/gd.c | 80 | ||||
| -rw-r--r-- | src/gd.h | 156 | ||||
| -rw-r--r-- | src/gd_gd.c | 59 | ||||
| -rw-r--r-- | src/gd_gd2.c | 119 | ||||
| -rw-r--r-- | src/gd_gif_in.c | 58 | ||||
| -rw-r--r-- | src/gd_gif_out.c | 448 | ||||
| -rw-r--r-- | src/gd_interpolation.c | 2 | ||||
| -rw-r--r-- | src/gd_io.h | 114 | ||||
| -rw-r--r-- | src/gd_jpeg.c | 201 | ||||
| -rw-r--r-- | src/gd_matrix.c | 20 | ||||
| -rw-r--r-- | src/gd_png.c | 221 | ||||
| -rw-r--r-- | src/gd_ss.c | 6 | ||||
| -rw-r--r-- | src/gd_wbmp.c | 67 | ||||
| -rw-r--r-- | src/gd_xbm.c | 37 | ||||
| -rw-r--r-- | src/gdft.c | 124 | ||||
| -rw-r--r-- | src/gdxpm.c | 34 |
17 files changed, 1666 insertions, 146 deletions
diff --git a/docs/naturaldocs/project/Menu.txt b/docs/naturaldocs/project/Menu.txt deleted file mode 100644 index 2db47b0..0000000 --- a/docs/naturaldocs/project/Menu.txt +++ /dev/null @@ -1,66 +0,0 @@ -Format: 1.51 - - -# You can add a title and sub-title to your menu like this: -# Title: [project name] -# SubTitle: [subtitle] - -# You can add a footer to your documentation like this: -# Footer: [text] -# If you want to add a copyright notice, this would be the place to do it. - -# You can add a timestamp to your documentation like one of these: -# Timestamp: Generated on month day, year -# Timestamp: Updated mm/dd/yyyy -# Timestamp: Last updated mon day -# -# m - One or two digit month. January is "1" -# mm - Always two digit month. January is "01" -# mon - Short month word. January is "Jan" -# month - Long month word. January is "January" -# d - One or two digit day. 1 is "1" -# dd - Always two digit day. 1 is "01" -# day - Day with letter extension. 1 is "1st" -# yy - Two digit year. 2006 is "06" -# yyyy - Four digit year. 2006 is "2006" -# year - Four digit year. 2006 is "2006" - - -# -------------------------------------------------------------------------- -# -# Cut and paste the lines below to change the order in which your files -# appear on the menu. Don't worry about adding or removing files, Natural -# Docs will take care of that. -# -# You can further organize the menu by grouping the entries. Add a -# "Group: [name] {" line to start a group, and add a "}" to end it. -# -# You can add text and web links to the menu by adding "Text: [text]" and -# "Link: [name] ([URL])" lines, respectively. -# -# The formatting and comments are auto-generated, so don't worry about -# neatness when editing the file. Natural Docs will clean it up the next -# time it is run. When working with groups, just deal with the braces and -# forget about the indentation and comments. -# -# -------------------------------------------------------------------------- - - -File: About LibGD 2.1.1-dev (preamble.txt) -File: gd.h (gd.h) -File: gd_filename.c (gd_filename.c) -File: gd_filter.c (gd_filter.c) -File: gd_interpolation.c (gd_interpolation.c) -File: gdImageCreate (gd.c) -File: License (license.txt) -File: Matrix (gd_matrix.c) - -Group: Index { - - Index: Everything - Constant Index: Constants - File Index: Files - Function Index: Functions - Type Index: Types - } # Group: Index - @@ -133,15 +133,9 @@ BGD_DECLARE(int) gdImageGetTrueColorPixel (gdImagePtr im, int x, int y); /* Function: gdImageCreate - gdImageCreate is called to create palette-based images, with no - more than 256 colors. The image must eventually be destroyed using - gdImageDestroy(). - - > ... inside a function ... - > gdImagePtr im; - > im = gdImageCreate(64, 64); - > // ... Use the image ... - > gdImageDestroy(im); + gdImageCreate is called to create palette-based images, with no + more than 256 colors. The image must eventually be destroyed using + gdImageDestroy(). Parameters: @@ -152,6 +146,13 @@ BGD_DECLARE(int) gdImageGetTrueColorPixel (gdImagePtr im, int x, int y); A pointer to the new image or NULL if an error occurred. + Example: + + > gdImagePtr im; + > im = gdImageCreate(64, 64); + > // ... Use the image ... + > gdImageDestroy(im); + See Also: <gdImageCreateTrueColor> @@ -222,6 +223,42 @@ BGD_DECLARE(gdImagePtr) gdImageCreate (int sx, int sy) return im; } + + +/* + Function: gdImageCreateTrueColor + + <gdImageCreateTrueColor> is called to create truecolor images, + with an essentially unlimited number of colors. Invoke + <gdImageCreateTrueColor> with the x and y dimensions of the + desired image. <gdImageCreateTrueColor> returns a <gdImagePtr> + to the new image, or NULL if unable to allocate the image. The + image must eventually be destroyed using <gdImageDestroy>(). + + Truecolor images are always filled with black at creation + time. There is no concept of a "background" color index. + + Parameters: + + sx - The image width. + sy - The image height. + + Returns: + + A pointer to the new image or NULL if an error occurred. + + Example: + + > gdImagePtr im; + > im = gdImageCreateTrueColor(64, 64); + > // ... Use the image ... + > gdImageDestroy(im); + + See Also: + + <gdImageCreateTrueColor> + +*/ BGD_DECLARE(gdImagePtr) gdImageCreateTrueColor (int sx, int sy) { int i; @@ -294,6 +331,31 @@ BGD_DECLARE(gdImagePtr) gdImageCreateTrueColor (int sx, int sy) return im; } +/* + Function: gdImageDestroy + + <gdImageDestroy> is used to free the memory associated with an + image. It is important to invoke <gdImageDestroy> before exiting + your program or assigning a new image to a <gdImagePtr> variable. + + Parameters: + + im - Pointer to the gdImage to delete. + + Returns: + + Nothing. + + Example: + + > gdImagePtr im; + > im = gdImageCreate(10, 10); + > // ... Use the image ... + > // Now destroy it + > gdImageDestroy(im); + +*/ + BGD_DECLARE(void) gdImageDestroy (gdImagePtr im) { int i; @@ -368,6 +368,47 @@ typedef struct } gdPointF, *gdPointFPtr; + +/* + Group: Types + + typedef: gdFont + + typedef: gdFontPtr + + A font structure, containing the bitmaps of all characters in a + font. Used to declare the characteristics of a font. Text-output + functions expect these as their second argument, following the + <gdImagePtr> argument. <gdFontSmall> and <gdFontGetLarge> both + return one. + + You can provide your own font data by providing such a structure and + the associated pixel array. You can determine the width and height + of a single character in a font by examining the w and h members of + the structure. If you will not be creating your own fonts, you will + not need to concern yourself with the rest of the components of this + structure. + + Please see the files gdfontl.c and gdfontl.h for an example of + the proper declaration of this structure. + + > typedef struct { + > // # of characters in font + > int nchars; + > // First character is numbered... (usually 32 = space) + > int offset; + > // Character width and height + > int w; + > int h; + > // Font data; array of characters, one row after another. + > // Easily included in code, also easily loaded from + > // data files. + > char *data; + > } gdFont; + + gdFontPtr is a pointer to gdFont. + +*/ typedef struct { /* # of characters in font */ int nchars; @@ -459,11 +500,34 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromBmpPtr (int size, void *data); BGD_DECLARE(gdImagePtr) gdImageCreateFromBmpCtx (gdIOCtxPtr infile); BGD_DECLARE(gdImagePtr) gdImageCreateFromFile(const char *filename); -/* A custom data source. */ -/* The source function must return -1 on error, otherwise the number - of bytes fetched. 0 is EOF, not an error! */ -/* context will be passed to your source function. */ +/* + Group: Types + + typedef: gdSource + + typedef: gdSourcePtr + + *Note:* This interface is *obsolete* and kept only for + *compatibility. Use <gdIOCtx> instead. + + Represents a source from which a PNG can be read. Programmers who + do not wish to read PNGs from a file can provide their own + alternate input mechanism, using the <gdImageCreateFromPngSource> + function. See the documentation of that function for an example of + the proper use of this type. + + > typedef struct { + > int (*source) (void *context, char *buffer, int len); + > void *context; + > } gdSource, *gdSourcePtr; + + The source function must return -1 on error, otherwise the number + of bytes fetched. 0 is EOF, not an error! + + 'context' will be passed to your source function. + +*/ typedef struct { int (*source) (void *context, char *buffer, int len); void *context; @@ -566,9 +630,23 @@ BGD_DECLARE(char *) gdImageStringFT (gdImage * im, int *brect, int fg, char *fon double ptsize, double angle, int x, int y, char *string); + +/* + Group: Types + + typedef: gdFTStringExtra + + typedef: gdFTStringExtraPtr + + A structure and associated pointer type used to pass additional + parameters to the <gdImageStringFTEx> function. See + <gdImageStringFTEx> for the structure definition. + + Thanks to Wez Furlong. +*/ + /* 2.0.5: provides an extensible way to pass additional parameters. Thanks to Wez Furlong, sorry for the delay. */ - typedef struct { int flags; /* Logical OR of gdFTEX_ values */ double linespacing; /* fine tune line spacing for '\n' */ @@ -636,7 +714,23 @@ BGD_DECLARE(char *) gdImageStringFTEx (gdImage * im, int *brect, int fg, char *f double ptsize, double angle, int x, int y, char *string, gdFTStringExtraPtr strex); -/* Point type for use in polygon drawing. */ + +/* + Group: Types + + typedef: gdPoint + + typedef: gdPointPtr + + Represents a point in the coordinate space of the image; used by + <gdImagePolygon>, <gdImageOpenPolygon> and <gdImageFilledPolygon> + for polygon drawing. + + > typedef struct { + > int x, y; + > } gdPoint, *gdPointPtr; + +*/ typedef struct { int x, y; } @@ -816,9 +910,22 @@ BGD_DECLARE(void *) gdImageWebpPtr (gdImagePtr im, int *size); BGD_DECLARE(void *) gdImageWebpPtrEx (gdImagePtr im, int *size, int quantization); BGD_DECLARE(void) gdImageWebpCtx (gdImagePtr im, gdIOCtx * outfile, int quantization); -/* Legal values for Disposal. gdDisposalNone is always used by - the built-in optimizer if previm is passed. */ +/** + * Group: GifAnim + * + * Legal values for Disposal. gdDisposalNone is always used by + * the built-in optimizer if previm is passed. + * + * Constants: gdImageGifAnim + * + * gdDisposalUnknown - Not recommended + * gdDisposalNone - Preserve previous frame + * gdDisposalRestoreBackground - First allocated color of palette + * gdDisposalRestorePrevious - Restore to before start of frame + * + * See also: <gdImageGifAnimAdd> + */ enum { gdDisposalUnknown, gdDisposalNone, @@ -836,11 +943,36 @@ BGD_DECLARE(void *) gdImageGifAnimBeginPtr(gdImagePtr im, int *size, int GlobalC BGD_DECLARE(void *) gdImageGifAnimAddPtr(gdImagePtr im, int *size, int LocalCM, int LeftOfs, int TopOfs, int Delay, int Disposal, gdImagePtr previm); BGD_DECLARE(void *) gdImageGifAnimEndPtr(int *size); -/* A custom data sink. For backwards compatibility. Use gdIOCtx - instead. The sink function must return -1 on error, otherwise the - number of bytes written, which must be equal to len. Context will - be passed to your sink function. + + +/* + Group: Types + + typedef: gdSink + + typedef: gdSinkPtr + + *Note:* This interface is *obsolete* and kept only for + *compatibility. Use <gdIOCtx> instead. + + Represents a "sink" (destination) to which a PNG can be + written. Programmers who do not wish to write PNGs to a file can + provide their own alternate output mechanism, using the + <gdImagePngToSink> function. See the documentation of that + function for an example of the proper use of this type. + + > typedef struct { + > int (*sink) (void *context, char *buffer, int len); + > void *context; + > } gdSink, *gdSinkPtr; + + The _sink_ function must return -1 on error, otherwise the number of + bytes written, which must be equal to len. + + _context_ will be passed to your sink function. + */ + typedef struct { int (*sink) (void *context, const char *buffer, int len); void *context; diff --git a/src/gd_gd.c b/src/gd_gd.c index 3cdfd58..f8d39cb 100644 --- a/src/gd_gd.c +++ b/src/gd_gd.c @@ -139,6 +139,49 @@ fail1: return 0; } +/* + Function: gdImageCreateFromGd + + <gdImageCreateFromGd> is called to load images from gd format + files. Invoke <gdImageCreateFromGd> with an already opened pointer + to a file containing the desired image in the gd file format, + which is specific to gd and intended for very fast loading. (It is + not intended for compression; for compression, use PNG or JPEG.) + + <gdImageCreateFromGd> returns a <gdImagePtr> to the new image, or + NULL if unable to load the image (most often because the file is + corrupt or does not contain a gd format + image). <gdImageCreateFromGd> does not close the file. You can + inspect the sx and sy members of the image to determine its + size. The image must eventually be destroyed using + <gdImageDestroy>. + + Variants: + + <gdImageCreateFromGdPtr> creates an image from GD data (i.e. the + contents of a GD file) already in memory. + + <gdImageCreateFromGdCtx> reads in an image using the functions in + a <gdIOCtx> struct. + + Parameters: + + infile - The input FILE pointer + + Returns: + + A pointer to the new image or NULL if an error occurred. + + Example: + + > gdImagePtr im; + > FILE *in; + > in = fopen("mygd.gd", "rb"); + > im = gdImageCreateFromGd(in); + > fclose(in); + > // ... Use the image ... + > gdImageDestroy(im); +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromGd (FILE * inFile) { gdImagePtr im; @@ -153,6 +196,16 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromGd (FILE * inFile) return im; } +/* + Function: gdImageCreateFromGdPtr + + Parameters: + + size - size of GD data in bytes. + data - GD data (i.e. contents of a GIF file). + + Reads in GD data from memory. See <gdImageCreateFromGd>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromGdPtr (int size, void *data) { gdImagePtr im; @@ -164,6 +217,12 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromGdPtr (int size, void *data) return im; } +/* + Function: gdImageCreateFromGdCtx + + Reads in a GD image via a <gdIOCtx> struct. See + <gdImageCreateFromGd>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromGdCtx (gdIOCtxPtr in) { int sx, sy; diff --git a/src/gd_gd2.c b/src/gd_gd2.c index e7207f9..3e70bfa 100644 --- a/src/gd_gd2.c +++ b/src/gd_gd2.c @@ -250,6 +250,52 @@ _gd2ReadChunk (int offset, char *compBuf, int compSize, char *chunkBuf, return TRUE; } + +/* + Function: gdImageCreateFromGd2 + + <gdImageCreateFromGd2> is called to load images from gd2 format + files. Invoke <gdImageCreateFromGd2> with an already opened + pointer to a file containing the desired image in the gd2 file + format, which is specific to gd2 and intended for fast loading of + parts of large images. (It is a compressed format, but generally + not as good as maximum compression of the entire image would be.) + + <gdImageCreateFromGd2> returns a <gdImagePtr> to the new image, or + NULL if unable to load the image (most often because the file is + corrupt or does not contain a gd format + image). <gdImageCreateFromGd2> does not close the file. You can + inspect the sx and sy members of the image to determine its + size. The image must eventually be destroyed using + <gdImageDestroy>. + + + Variants: + + <gdImageCreateFromGd2Ptr> creates an image from GD data (i.e. the + contents of a GD2 file) already in memory. + + <gdImageCreateFromGd2Ctx> reads in an image using the functions in + a <gdIOCtx> struct. + + Parameters: + + infile - The input FILE pointer + + Returns: + + A pointer to the new image or NULL if an error occurred. + + Example: + + > gdImagePtr im; + > FILE *in; + > in = fopen("mygd.gd2", "rb"); + > im = gdImageCreateFromGd2(in); + > fclose(in); + > // ... Use the image ... + > gdImageDestroy(im); +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromGd2 (FILE * inFile) { gdIOCtx *in = gdNewFileCtx (inFile); @@ -263,6 +309,16 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromGd2 (FILE * inFile) return im; } +/* + Function: gdImageCreateFromGd2Ptr + + Parameters: + + size - size of GD2 data in bytes. + data - GD2 data (i.e. contents of a GIF file). + + See <gdImageCreateFromGd2>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromGd2Ptr (int size, void *data) { gdImagePtr im; @@ -274,6 +330,12 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromGd2Ptr (int size, void *data) return im; } +/* + Function: gdImageCreateFromGd2Ctx + + Reads in a GD2 image via a <gdIOCtx> struct. See + <gdImageCreateFromGd2>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromGd2Ctx (gdIOCtxPtr in) { int sx, sy; @@ -438,6 +500,37 @@ fail: return 0; } + +/* + Function: gdImageCreateFromGd2Part + + <gdImageCreateFromGd2Part> is called to load parts of images from + gd2 format files. Invoked in the same way as <gdImageCreateFromGd2>, + but with extra parameters indicating the source (x, y) and + width/height of the desired image. <gdImageCreateFromGd2Part> + returns a <gdImagePtr> to the new image, or NULL if unable to load + the image. The image must eventually be destroyed using + <gdImageDestroy>. + + Variants: + + <gdImageCreateFromGd2PartPtr> creates an image from GD2 data + (i.e. the contents of a GD2 file) already in memory. + + <gdImageCreateFromGd2Ctx> reads in an image using the functions in + a <gdIOCtx> struct. + + Parameters: + + infile - The input FILE pointer + srcx, srcy - The source X and Y coordinates + w, h - The resulting image's width and height + + Returns: + + A pointer to the new image or NULL if an error occurred. + +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromGd2Part (FILE * inFile, int srcx, int srcy, int w, int h) { gdImagePtr im; @@ -451,6 +544,19 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromGd2Part (FILE * inFile, int srcx, int s return im; } +/* + Function: gdImageCreateFromGd2PartPtr + + Parameters: + + size - size of GD data in bytes. + data - GD data (i.e. contents of a GIF file). + srcx, srcy - The source X and Y coordinates + w, h - The resulting image's width and height + + Reads in part of a GD2 image file stored from memory. See + <gdImageCreateFromGd2Part>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromGd2PartPtr (int size, void *data, int srcx, int srcy, int w, int h) { @@ -463,6 +569,19 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromGd2PartPtr (int size, void *data, int s return im; } + +/* + Function: gdImageCreateFromGd2PartCtx + + Parameters: + + in - The data source. + srcx, srcy - The source X and Y coordinates + w, h - The resulting image's width and height + + Reads in part of a GD2 data image file via a <gdIOCtx> struct. See + <gdImageCreateFromGd2Part>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromGd2PartCtx (gdIOCtx * in, int srcx, int srcy, int w, int h) { int scx, scy, ecx, ecy, fsx, fsy; diff --git a/src/gd_gif_in.c b/src/gd_gif_in.c index 68cdd32..b3b4ca3 100644 --- a/src/gd_gif_in.c +++ b/src/gd_gif_in.c @@ -102,6 +102,49 @@ static int LWZReadByte (gdIOCtx *fd, LZW_STATIC_DATA *sd, char flag, int input_c static void ReadImage (gdImagePtr im, gdIOCtx *fd, int len, int height, unsigned char (*cmap)[256], int interlace, int *ZeroDataBlockP); /*1.4//, int ignore); */ +/* + Function: gdImageCreateFromGif + + <gdImageCreateFromGif> is called to load images from GIF format + files. Invoke <gdImageCreateFromGif> with an already opened + pointer to a file containing the desired + image. + + <gdImageCreateFromGif> returns a <gdImagePtr> to the new image, or + NULL if unable to load the image (most often because the file is + corrupt or does not contain a GIF image). <gdImageCreateFromGif> + does not close the file. You can inspect the sx and sy members of + the image to determine its size. The image must eventually be + destroyed using <gdImageDestroy>. + + Variants: + + <gdImageCreateFromGifPtr> creates an image from GIF data (i.e. the + contents of a GIF file) already in memory. + + <gdImageCreateFromGifCtx> reads in an image using the functions in + a <gdIOCtx> struct. + + Parameters: + + infile - The input FILE pointer + + Returns: + + A pointer to the new image or NULL if an error occurred. + + Example: + + > gdImagePtr im; + > ... inside a function ... + > FILE *in; + > in = fopen("mygif.gif", "rb"); + > im = gdImageCreateFromGif(in); + > fclose(in); + > // ... Use the image ... + > gdImageDestroy(im); + +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromGif(FILE *fdFile) { gdIOCtx *fd = gdNewFileCtx(fdFile); @@ -115,6 +158,16 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromGif(FILE *fdFile) return im; } +/* + Function: gdImageCreateFromGifPtr + + Parameters: + + size - size of GIF data in bytes. + data - GIF data (i.e. contents of a GIF file). + + See <gdImageCreateFromGif>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromGifPtr (int size, void *data) { gdImagePtr im; @@ -127,6 +180,11 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromGifPtr (int size, void *data) return im; } +/* + Function: gdImageCreateFromGifCtx + + See <gdImageCreateFromGif>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromGifCtx(gdIOCtxPtr fd) { int BitPixel; diff --git a/src/gd_gif_out.c b/src/gd_gif_out.c index c863172..51ceb75 100644 --- a/src/gd_gif_out.c +++ b/src/gd_gif_out.c @@ -93,6 +93,33 @@ static void char_init(GifCtx *ctx); static void char_out(int c, GifCtx *ctx); static void flush_char(GifCtx *ctx); + + + +/* + Function: gdImageGifPtr + + Identical to <gdImageGif> except that it returns a pointer to a + memory area with the GIF data. This memory must be freed by the + caller when it is no longer needed. + + The caller *must* invoke <gdFree>, not _free()_. This is because + it is not guaranteed that libgd will use the same implementation + of malloc, free, etc. as your proggram. + + The 'size' parameter receives the total size of the block of + memory. + + Parameters: + + im - The image to write + size - Output: the size of the resulting image. + + Returns: + + A pointer to the GIF data or NULL if an error occurred. + +*/ BGD_DECLARE(void *) gdImageGifPtr(gdImagePtr im, int *size) { void *rv; @@ -104,6 +131,65 @@ BGD_DECLARE(void *) gdImageGifPtr(gdImagePtr im, int *size) return rv; } +/* + Function: gdImageGif + + <gdImageGif> outputs the specified image to the specified file in + GIF format. The file must be open for binary writing. (Under MSDOS + and all versions of Windows, it is important to use "wb" as + opposed to simply "w" as the mode when opening the file; under + Unix there is no penalty for doing so). <gdImageGif> does not close + the file; your code must do so. + + GIF does not support true color; GIF images can contain a maximum + of 256 colors. If the image to be written is a truecolor image, + such as those created with gdImageCreateTrueColor or loaded from a + JPEG or a truecolor PNG image file, a palette-based temporary + image will automatically be created internally using the + <gdImageCreatePaletteFromTrueColor> function. The original image + pixels are not modified. This conversion produces high quality + palettes but does require some CPU time. If you are regularly + converting truecolor to palette in this way, you should consider + creating your image as a palette-based image in the first place. + + Variants: + + <gdImageGifCtx> outputs the image via a <gdIOCtx> struct. + + <gdImageGifPtr> stores the image in a large array of bytes. + + Parameters: + + im - The image to write + outFile - The FILE pointer to write the image to. + + Returns: + + Nothing + + Example: + + > gdImagePtr im; + > int black, white; + > FILE *out; + > // Create the image + > im = gdImageCreate(100, 100); + > // Allocate background + > white = gdImageColorAllocate(im, 255, 255, 255); + > // Allocate drawing color + > black = gdImageColorAllocate(im, 0, 0, 0); + > // Draw rectangle + > gdImageRectangle(im, 0, 0, 99, 99, black); + > // Open output file in binary mode + > out = fopen("rect.gif", "wb"); + > // Write GIF + > gdImageGif(im, out); + > // Close file + > fclose(out); + > // Destroy image + > gdImageDestroy(im); + +*/ BGD_DECLARE(void) gdImageGif(gdImagePtr im, FILE *outFile) { gdIOCtx *out = gdNewFileCtx(outFile); @@ -112,6 +198,21 @@ BGD_DECLARE(void) gdImageGif(gdImagePtr im, FILE *outFile) out->gd_free(out); } +/* + Function: gdImageGifCtx + + Writes a GIF image via a <gdIOCtx>. See <gdImageGif>. + + Parameters: + + im - The image to write + out - The <gdIOCtx> struct used to do the writing. + + Returns: + + Nothing. + +*/ BGD_DECLARE(void) gdImageGifCtx(gdImagePtr im, gdIOCtxPtr out) { gdImagePtr pim = 0, tim = im; @@ -142,6 +243,37 @@ BGD_DECLARE(void) gdImageGifCtx(gdImagePtr im, gdIOCtxPtr out) } } + +/* + Function: gdImageGifAnimBeginPtr + + Like <gdImageGifAnimBegin> except that it outputs to a memory + buffer. See <gdImageGifAnimBegin>. + + The returned memory must be freed by the caller when it is no + longer needed. **The caller must invoke <gdFree>(), not free()**, + unless the caller is absolutely certain that the same + implementations of malloc, free, etc. are used both at library + build time and at application build time (but don't; it could + always change). + + The 'size' parameter receives the total size of the block of + memory. + + Parameters: + + im - The reference image + size - Output: the size in bytes of the result. + GlobalCM - Global colormap flag: 1 -> yes, 0 -> no, -1 -> do default + Loops - Loop count; 0 -> infinite, -1 means no loop + + Returns: + + A pointer to the resulting data (the contents of the start of the + GIF) or NULL if an error occurred. + +*/ + BGD_DECLARE(void *) gdImageGifAnimBeginPtr(gdImagePtr im, int *size, int GlobalCM, int Loops) { void *rv; @@ -153,6 +285,57 @@ BGD_DECLARE(void *) gdImageGifAnimBeginPtr(gdImagePtr im, int *size, int GlobalC return rv; } + +/* + Function: gdImageGifAnimBegin + + This function must be called as the first function when creating a + GIF animation. It writes the correct GIF file headers to selected + file output, and prepares for frames to be added for the + animation. The image argument is not used to produce an image + frame to the file, it is only used to establish the GIF animation + frame size, interlacing options and the color + palette. <gdImageGifAnimAdd> is used to add the first and + subsequent frames to the animation, and the animation must be + terminated by writing a semicolon character (;) to it or by using + gdImageGifAnimEnd to do that. + + The GlobalCM flag indicates if a global color map (or palette) is + used in the GIF89A header. A nonzero value specifies that a global + color map should be used to reduce the size of the animation. Of + course, if the color maps of individual frames differ greatly, a + global color map may not be a good idea. GlobalCM=1 means write + global color map, GlobalCM=0 means do not, and GlobalCM=-1 means + to do the default, which currently is to use a global color map. + + If Loops is 0 or greater, the Netscape 2.0 extension for animation + loop count is written. 0 means infinite loop count. -1 means that + the extension is not added which results in no looping. -1 is the + default. + + Variants: + + <gdImageGifAnimBeginCtx> outputs the image via a <gdIOCtx> struct. + + <gdImageGifAnimBeginPtr> stores the image in a large array of bytes. + + Parameters: + + im - The reference image + outfile - The output FILE*. + GlobalCM - Global colormap flag: 1 -> yes, 0 -> no, -1 -> do default + Loops - Loop count; 0 -> infinite, -1 means no loop + + Returns: + + Nothing. + + Example: + + See <gdImageGifAnimBegin>. + +*/ + BGD_DECLARE(void) gdImageGifAnimBegin(gdImagePtr im, FILE *outFile, int GlobalCM, int Loops) { gdIOCtx *out = gdNewFileCtx(outFile); @@ -161,6 +344,26 @@ BGD_DECLARE(void) gdImageGifAnimBegin(gdImagePtr im, FILE *outFile, int GlobalCM out->gd_free(out); } + + +/* + Function: gdImageGifAnimBeginCtx + + Like <gdImageGifAnimBegin> except that it outputs to <gdIOCtx>. + See <gdImageGifAnimBegin>. + + Parameters: + + im - The reference image + out - Pointer to the output <gdIOCtx>. + GlobalCM - Global colormap flag: 1 -> yes, 0 -> no, -1 -> do default + Loops - Loop count; 0 -> infinite, -1 means no loop + + Returns: + + Nothing. + +*/ BGD_DECLARE(void) gdImageGifAnimBeginCtx(gdImagePtr im, gdIOCtxPtr out, int GlobalCM, int Loops) { int B; @@ -225,7 +428,43 @@ BGD_DECLARE(void) gdImageGifAnimBeginCtx(gdImagePtr im, gdIOCtxPtr out, int Glob } } -BGD_DECLARE(void *) gdImageGifAnimAddPtr(gdImagePtr im, int *size, int LocalCM, int LeftOfs, int TopOfs, int Delay, int Disposal, gdImagePtr previm) + + +/* + Function: gdImageGifAnimAddPtr + + Like <gdImageGifAnimAdd> (which contains more information) except + that it stores the data to write into memory and returns a pointer + to it. + + This memory must be freed by the caller when it is no longer + needed. **The caller must invoke <gdFree>(), not free(),** unless + the caller is absolutely certain that the same implementations of + malloc, free, etc. are used both at library build time and at + application build time (but don't; it could always change). + + The 'size' parameter receives the total size of the block of + memory. + + Parameters: + + im - The image to add. + size - Output: the size of the resulting buffer. + LocalCM - Flag. If 1, use a local color map for this frame. + LeftOfs - Left offset of image in frame. + TopOfs - Top offset of image in frame. + Delay - Delay before next frame (in 1/100 seconds) + Disposal - MODE: How to treat this frame when the next one loads. + previm - NULL or a pointer to the previous image written. + + Returns: + + Pointer to the resulting data or NULL if an error occurred. + +*/ +BGD_DECLARE(void *) gdImageGifAnimAddPtr(gdImagePtr im, int *size, int LocalCM, + int LeftOfs, int TopOfs, int Delay, + int Disposal, gdImagePtr previm) { void *rv; gdIOCtx *out = gdNewDynamicCtx(2048, NULL); @@ -236,7 +475,114 @@ BGD_DECLARE(void *) gdImageGifAnimAddPtr(gdImagePtr im, int *size, int LocalCM, return rv; } -BGD_DECLARE(void) gdImageGifAnimAdd(gdImagePtr im, FILE *outFile, int LocalCM, int LeftOfs, int TopOfs, int Delay, int Disposal, gdImagePtr previm) + +/* + Function: gdImageGifAnimAdd + + This function writes GIF animation frames to GIF animation, which + was initialized with <gdImageGifAnimBegin>. With _LeftOfs_ and + _TopOfs_ you can place this frame in different offset than (0,0) + inside the image screen as defined in <gdImageGifAnimBegin>. Delay + between the previous frame and this frame is in 1/100s + units. _Disposal_ is usually <gdDisposalNone>, meaning that the + pixels changed by this frame should remain on the display when the + next frame begins to render, but can also be <gdDisposalUnknown> + (not recommended), <gdDisposalRestoreBackground> (restores the + first allocated color of the global palette), or + <gdDisposalRestorePrevious> (restores the appearance of the + affected area before the frame was rendered). Only + <gdDisposalNone> is a sensible choice for the first frame. If + _previm_ is passed, the built-in GIF optimizer will always use + <gdDisposalNone> regardless of the Disposal parameter. + + Setting the _LocalCM_ flag to 1 adds a local palette for this + image to the animation. Otherwise the global palette is assumed + and the user must make sure the palettes match. Use + <gdImagePaletteCopy> to do that. + + Automatic optimization is activated by giving the previous image + as a parameter. This function then compares the images and only + writes the changed pixels to the new frame in animation. The + _Disposal_ parameter for optimized animations must be set to 1, + also for the first frame. _LeftOfs_ and _TopOfs_ parameters are + ignored for optimized frames. To achieve good optimization, it is + usually best to use a single global color map. To allow + <gdImageGifAnimAdd> to compress unchanged pixels via the use of a + transparent color, the image must include a transparent color. + + + Variants: + + <gdImageGifAnimAddCtx> outputs its data via a <gdIOCtx> struct. + + <gdImageGifAnimAddPtr> outputs its data to a memory buffer which + it returns. + + Parameters: + + im - The image to add. + outfile - The output FILE* being written. + LocalCM - Flag. If 1, use a local color map for this frame. + LeftOfs - Left offset of image in frame. + TopOfs - Top offset of image in frame. + Delay - Delay before next frame (in 1/100 seconds) + Disposal - MODE: How to treat this frame when the next one loads. + previm - NULL or a pointer to the previous image written. + + Returns: + + Nothing. + + Example: + + > { + > gdImagePtr im, im2, im3; + > int black, white, trans; + > FILE *out; + > + > im = gdImageCreate(100, 100); // Create the image + > white = gdImageColorAllocate(im, 255, 255, 255); // Allocate background + > black = gdImageColorAllocate(im, 0, 0, 0); // Allocate drawing color + > trans = gdImageColorAllocate(im, 1, 1, 1); // trans clr for compression + > gdImageRectangle(im, 0, 0, 10, 10, black); // Draw rectangle + > + > out = fopen("anim.gif", "wb");// Open output file in binary mode + > gdImageGifAnimBegin(im, out, 1, 3);// Write GIF hdr, global clr map,loops + > // Write the first frame. No local color map. Delay = 1s + > gdImageGifAnimAdd(im, out, 0, 0, 0, 100, 1, NULL); + > + > // construct the second frame + > im2 = gdImageCreate(100, 100); + > (void)gdImageColorAllocate(im2, 255, 255, 255); // White background + > gdImagePaletteCopy (im2, im); // Make sure the palette is identical + > gdImageRectangle(im2, 0, 0, 15, 15, black); // Draw something + > // Allow animation compression with transparent pixels + > gdImageColorTransparent (im2, trans); + > gdImageGifAnimAdd(im2, out, 0, 0, 0, 100, 1, im); // Add second frame + > + > // construct the third frame + > im3 = gdImageCreate(100, 100); + > (void)gdImageColorAllocate(im3, 255, 255, 255); // white background + > gdImagePaletteCopy (im3, im); // Make sure the palette is identical + > gdImageRectangle(im3, 0, 0, 15, 20, black); // Draw something + > // Allow animation compression with transparent pixels + > gdImageColorTransparent (im3, trans); + > // Add the third frame, compressing against the second one + > gdImageGifAnimAdd(im3, out, 0, 0, 0, 100, 1, im2); + > gdImageGifAnimEnd(out); // End marker, same as putc(';', out); + > fclose(out); // Close file + > + > // Destroy images + > gdImageDestroy(im); + > gdImageDestroy(im2); + > gdImageDestroy(im3); + > } + +*/ + +BGD_DECLARE(void) gdImageGifAnimAdd(gdImagePtr im, FILE *outFile, int LocalCM, + int LeftOfs, int TopOfs, int Delay, + int Disposal, gdImagePtr previm) { gdIOCtx *out = gdNewFileCtx(outFile); if (out == NULL) return; @@ -257,7 +603,31 @@ static int comparewithmap(gdImagePtr im1, gdImagePtr im2, int c1, int c2, int *c return (colorMap[c1] = gdImageColorExactAlpha(im2, im1->red[c1], im1->green[c1], im1->blue[c1], im1->alpha[c1])) == c2; } -BGD_DECLARE(void) gdImageGifAnimAddCtx(gdImagePtr im, gdIOCtxPtr out, int LocalCM, int LeftOfs, int TopOfs, int Delay, int Disposal, gdImagePtr previm) +/* + Function: gdImageGifAnimAddCtx + + Adds an animation frame via a <gdIOCtxPtr>. See gdImageGifAnimAdd>. + + Parameters: + + im - The image to add. + out - The output <gdIOCtxPtr>. + LocalCM - Flag. If 1, use a local color map for this frame. + LeftOfs - Left offset of image in frame. + TopOfs - Top offset of image in frame. + Delay - Delay before next frame (in 1/100 seconds) + Disposal - MODE: How to treat this frame when the next one loads. + previm - NULL or a pointer to the previous image written. + + Returns: + + Nothing. + +*/ +BGD_DECLARE(void) gdImageGifAnimAddCtx(gdImagePtr im, gdIOCtxPtr out, + int LocalCM, int LeftOfs, int TopOfs, + int Delay, int Disposal, + gdImagePtr previm) { gdImagePtr pim = NULL, tim = im; int interlace, transparent, BitsPerPixel; @@ -456,6 +826,37 @@ fail_end: } } + + +/* + Function: gdImageGifAnimEnd + + Terminates the GIF file properly. + + (Previous versions of this function's documentation suggested just + manually writing a semicolon (';') instead since that is all this + function does. While that has no longer changed, we now suggest + that you do not do this and instead always call + <gdImageGifAnimEnd> (or equivalent) since later versions could + possibly do more or different things.) + + Variants: + + <gdImageGifAnimEndCtx> outputs its data via a <gdIOCtx> struct. + + <gdImageGifAnimEndPtr> outputs its data to a memory buffer which + it returns. + + Parameters: + + outfile - the destination FILE*. + + Returns: + + Nothing. + +*/ + BGD_DECLARE(void) gdImageGifAnimEnd(FILE *outFile) { #if 1 @@ -468,6 +869,32 @@ BGD_DECLARE(void) gdImageGifAnimEnd(FILE *outFile) #endif } +/* + Function: gdImageGifAnimEndPtr + + Like <gdImageGifAnimEnd> (which contains more information) except + that it stores the data to write into memory and returns a pointer + to it. + + This memory must be freed by the caller when it is no longer + needed. **The caller must invoke <gdFree>(), not free(),** unless + the caller is absolutely certain that the same implementations of + malloc, free, etc. are used both at library build time and at + application build time (but don't; it could always change). + + The 'size' parameter receives the total size of the block of + memory. + + Parameters: + + size - Output: the size of the resulting buffer. + + Returns: + + Pointer to the resulting data or NULL if an error occurred. + +*/ + BGD_DECLARE(void *) gdImageGifAnimEndPtr(int *size) { char *rv = (char *) gdMalloc(1); @@ -479,6 +906,21 @@ BGD_DECLARE(void *) gdImageGifAnimEndPtr(int *size) return (void *)rv; } +/* + Function: gdImageGifAnimEndCtx + + Like <gdImageGifAnimEnd>, but writes its data via a <gdIOCtx>. + + Parameters: + + out - the destination <gdIOCtx>. + + Returns: + + Nothing. + +*/ + BGD_DECLARE(void) gdImageGifAnimEndCtx(gdIOCtx *out) { /* diff --git a/src/gd_interpolation.c b/src/gd_interpolation.c index 637a2b2..cf8012d 100644 --- a/src/gd_interpolation.c +++ b/src/gd_interpolation.c @@ -795,7 +795,7 @@ static int getPixelInterpolateWeight(gdImagePtr im, const double x, const double } /** - * Function: getPixelInterpolated + * InternalFunction: getPixelInterpolated * Returns the interpolated color value using the default interpolation * method. The returned color is always in the ARGB format (truecolor). * diff --git a/src/gd_io.h b/src/gd_io.h index ed02d25..1039d59 100644 --- a/src/gd_io.h +++ b/src/gd_io.h @@ -11,39 +11,87 @@ extern "C" { # define Putchar gdPutchar #endif - typedef struct gdIOCtx { - int (*getC)(struct gdIOCtx *); - int (*getBuf)(struct gdIOCtx *, void *, int); - void (*putC)(struct gdIOCtx *, int); - int (*putBuf)(struct gdIOCtx *, const void *, int); - /* seek must return 1 on SUCCESS, 0 on FAILURE. Unlike fseek! */ - int (*seek)(struct gdIOCtx *, const int); - long (*tell)(struct gdIOCtx *); - void (*gd_free)(struct gdIOCtx *); - void *data; - } - gdIOCtx; - - typedef struct gdIOCtx *gdIOCtxPtr; - - void Putword(int w, gdIOCtx *ctx); - void Putchar(int c, gdIOCtx *ctx); - - void gdPutC(const unsigned char c, gdIOCtx *ctx); - int gdPutBuf(const void *, int, gdIOCtx *); - void gdPutWord(int w, gdIOCtx *ctx); - void gdPutInt(int w, gdIOCtx *ctx); - - int gdGetC(gdIOCtx *ctx); - int gdGetBuf(void *, int, gdIOCtx *); - int gdGetByte(int *result, gdIOCtx *ctx); - int gdGetWord(int *result, gdIOCtx *ctx); - int gdGetWordLSB(signed short int *result, gdIOCtx *ctx); - int gdGetInt(int *result, gdIOCtx *ctx); - int gdGetIntLSB(signed int *result, gdIOCtx *ctx); - - int gdSeek(gdIOCtx *ctx, const int offset); - long gdTell(gdIOCtx *ctx); +/* + Group: Types + + typedef: gdIOCtx + + gdIOCtx structures hold function pointers for doing image IO. + + Most of the gd functions that read and write files, such as + <gdImagePng> also have variants that accept a <gdIOCtx> structure; + see <gdImagePngCtx> and <gdImageCreateFromJpegCtx>. + + Those who wish to provide their own custom routines to read and + write images can populate a gdIOCtx structure with functions of + their own devising to to read and write data. For image reading, the + only mandatory functions are getC and getBuf, which must return the + number of characters actually read, or a negative value on error or + EOF. These functions must read the number of characters requested + unless at the end of the file. + + For image writing, the only mandatory functions are putC and putBuf, + which return the number of characters written; these functions must + write the number of characters requested except in the event of an + error. The seek and tell functions are only required in conjunction + with the gd2 file format, which supports quick loading of partial + images. The gd_free function will not be invoked when calling the + standard Ctx functions; it is an implementation convenience when + adding new data types to gd. For examples, see gd_png.c, gd_gd2.c, + gd_jpeg.c, etc., all of which rely on gdIOCtx to implement the + standard image read and write functions. + + > typedef struct gdIOCtx + > { + > int (*getC) (struct gdIOCtx *); + > int (*getBuf) (struct gdIOCtx *, void *, int wanted); + > + > void (*putC) (struct gdIOCtx *, int); + > int (*putBuf) (struct gdIOCtx *, const void *, int wanted); + > + > // seek must return 1 on SUCCESS, 0 on FAILURE. Unlike fseek! + > int (*seek) (struct gdIOCtx *, const int); + > long (*tell) (struct gdIOCtx *); + > + > void (*gd_free) (struct gdIOCtx *); + > } gdIOCtx; + + + + + */ +typedef struct gdIOCtx { + int (*getC)(struct gdIOCtx *); + int (*getBuf)(struct gdIOCtx *, void *, int); + void (*putC)(struct gdIOCtx *, int); + int (*putBuf)(struct gdIOCtx *, const void *, int); + /* seek must return 1 on SUCCESS, 0 on FAILURE. Unlike fseek! */ + int (*seek)(struct gdIOCtx *, const int); + long (*tell)(struct gdIOCtx *); + void (*gd_free)(struct gdIOCtx *); + void *data; +} gdIOCtx; + +typedef struct gdIOCtx *gdIOCtxPtr; + +void Putword(int w, gdIOCtx *ctx); +void Putchar(int c, gdIOCtx *ctx); + +void gdPutC(const unsigned char c, gdIOCtx *ctx); +int gdPutBuf(const void *, int, gdIOCtx *); +void gdPutWord(int w, gdIOCtx *ctx); +void gdPutInt(int w, gdIOCtx *ctx); + +int gdGetC(gdIOCtx *ctx); +int gdGetBuf(void *, int, gdIOCtx *); +int gdGetByte(int *result, gdIOCtx *ctx); +int gdGetWord(int *result, gdIOCtx *ctx); +int gdGetWordLSB(signed short int *result, gdIOCtx *ctx); +int gdGetInt(int *result, gdIOCtx *ctx); +int gdGetIntLSB(signed int *result, gdIOCtx *ctx); + +int gdSeek(gdIOCtx *ctx, const int offset); +long gdTell(gdIOCtx *ctx); #endif diff --git a/src/gd_jpeg.c b/src/gd_jpeg.c index 73a3812..925b417 100644 --- a/src/gd_jpeg.c +++ b/src/gd_jpeg.c @@ -127,6 +127,71 @@ static void fatal_jpeg_error(j_common_ptr cinfo) * library documentation for more details. */ + +/* + Function: gdImageJpeg + + <gdImageJpeg> outputs the specified image to the specified file in + JPEG format. The file must be open for writing. Under MSDOS and + all versions of Windows, it is important to use "wb" as opposed to + simply "w" as the mode when opening the file, and under Unix there + is no penalty for doing so. <gdImageJpeg> does not close the file; + your code must do so. + + If _quality_ is negative, the default IJG JPEG quality value (which + should yield a good general quality / size tradeoff for most + situations) is used. Otherwise, for practical purposes, _quality_ + should be a value in the range 0-95, higher quality values usually + implying both higher quality and larger image sizes. + + If you have set image interlacing using <gdImageInterlace>, this + function will interpret that to mean you wish to output a + progressive JPEG. Some programs (e.g., Web browsers) can display + progressive JPEGs incrementally; this can be useful when browsing + over a relatively slow communications link, for + example. Progressive JPEGs can also be slightly smaller than + sequential (non-progressive) JPEGs. + + Variants: + + <gdImageJpegCtx> stores the image using a <gdIOCtx> struct. + + <gdImageJpegPtr> stores the image to RAM. + + Parameters: + + im - The image to save + outFile - The FILE pointer to write to. + quality - Compression quality (0-95, 0 means use the default). + + Returns: + + Nothing. + + Example: + + > gdImagePtr im; + > int black, white; + > FILE *out; + > // Create the image + > im = gdImageCreate(100, 100); + > // Allocate background + > white = gdImageColorAllocate(im, 255, 255, 255); + > // Allocate drawing color + > black = gdImageColorAllocate(im, 0, 0, 0); + > // Draw rectangle + > gdImageRectangle(im, 0, 0, 99, 99, black); + > // Open output file in binary mode + > out = fopen("rect.jpg", "wb"); + > // Write JPEG using default quality + > gdImageJpeg(im, out, -1); + > // Close file + > fclose(out); + > // Destroy image + > gdImageDestroy(im); + +*/ + BGD_DECLARE(void) gdImageJpeg(gdImagePtr im, FILE *outFile, int quality) { gdIOCtx *out = gdNewFileCtx(outFile); @@ -135,6 +200,31 @@ BGD_DECLARE(void) gdImageJpeg(gdImagePtr im, FILE *outFile, int quality) out->gd_free(out); } +/* + Function: gdImageJpegPtr + + Identical to <gdImageJpeg> except that it returns a pointer to a + memory area with the JPEG data. This memory must be freed by the + caller when it is no longer needed. + + The caller *must* invoke <gdFree>, not free(). This is because it + is not guaranteed that libgd will use the same implementation of + malloc, free, etc. as your proggram. + + The 'size' parameter receives the total size of the block of + memory. + + Parameters: + + im - The image to write + size - Output: the size of the resulting image. + quality - Compression quality. + + Returns: + + A pointer to the JPEG data or NULL if an error occurred. + +*/ BGD_DECLARE(void *) gdImageJpegPtr(gdImagePtr im, int *size, int quality) { void *rv; @@ -148,6 +238,19 @@ BGD_DECLARE(void *) gdImageJpegPtr(gdImagePtr im, int *size, int quality) void jpeg_gdIOCtx_dest(j_compress_ptr cinfo, gdIOCtx *outfile); +/* + Function: gdImageJpegCtx + + Write the image as JPEG data via a <gdIOCtx>. See <gdImageJpeg> + for more details. + + Parameters: + + im - The image to write. + outfile - The output sink. + quality - Image quality. + +*/ BGD_DECLARE(void) gdImageJpegCtx(gdImagePtr im, gdIOCtx *outfile, int quality) { struct jpeg_compress_struct cinfo; @@ -299,10 +402,73 @@ BGD_DECLARE(void) gdImageJpegCtx(gdImagePtr im, gdIOCtx *outfile, int quality) gdFree(row); } + + + +/* + Function: gdImageCreateFromJpeg + + See <gdImageCreateFromJpegEx>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromJpeg(FILE *inFile) { return gdImageCreateFromJpegEx(inFile, 1); } + + +/* + Function: gdImageCreateFromJpegEx + + <gdImageCreateFromJpegEx> is called to load truecolor images from + JPEG format files. Invoke <gdImageCreateFromJpegEx> with an + already opened pointer to a file containing the desired + image. <gdImageCreateFromJpegEx> returns a <gdImagePtr> to the new + truecolor image, or NULL if unable to load the image (most often + because the file is corrupt or does not contain a JPEG + image). <gdImageCreateFromJpegEx> does not close the file. + + You can inspect the sx and sy members of the image to determine + its size. The image must eventually be destroyed using + <gdImageDestroy>. + + *The returned image is always a truecolor image.* + + Variants: + + <gdImageCreateFromJpegPtrEx> creates an image from JPEG data + already in memory. + + <gdImageCreateFromJpegCtxEx> reads its data via the function + pointers in a <gdIOCtx> structure. + + <gdImageCreateFromJpeg>, <gdImageCreateFromJpegPtr> and + <gdImageCreateFromJpegCtx> are equivalent to calling their + _Ex_-named counterparts with an ignore_warning set to 1 + (i.e. TRUE). + + Parameters: + + infile - The input FILE pointer. + ignore_warning - Flag. If true, ignores recoverable warnings. + + Returns: + + A pointer to the new *truecolor* image. This will need to be + destroyed with <gdImageDestroy> once it is no longer needed. + + On error, returns NULL. + + Example: + + > gdImagePtr im; + > FILE *in; + > in = fopen("myjpeg.jpg", "rb"); + > im = gdImageCreateFromJpegEx(in, GD_TRUE); + > fclose(in); + > // ... Use the image ... + > gdImageDestroy(im); + +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromJpegEx(FILE *inFile, int ignore_warning) { gdImagePtr im; @@ -313,10 +479,32 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromJpegEx(FILE *inFile, int ignore_warning return im; } +/* + Function: gdImageCreateFromJpegPtr + + Parameters: + + size - size of JPEG data in bytes. + data - pointer to JPEG data. + + See <gdImageCreateFromJpegEx>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromJpegPtr(int size, void *data) { return gdImageCreateFromJpegPtrEx(size, data, 1); } + +/* + Function: gdImageCreateFromJpegPtrEx + + Parameters: + + size - size of JPEG data in bytes. + data - pointer to JPEG data. + ignore_warning - if true, ignore recoverable warnings + + See <gdImageCreateFromJpegEx>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromJpegPtrEx(int size, void *data, int ignore_warning) { gdImagePtr im; @@ -334,13 +522,20 @@ void jpeg_gdIOCtx_src(j_decompress_ptr cinfo, gdIOCtx *infile); static int CMYKToRGB(int c, int m, int y, int k, int inverted); /* - * Create a gd-format image from the JPEG-format INFILE. Returns the - * image, or NULL upon error. - */ + Function: gdImageCreateFromJpegCtx + + See <gdImageCreateFromJpeg>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromJpegCtx(gdIOCtx *infile) { return gdImageCreateFromJpegCtxEx(infile, 1); } + +/* + Function: gdImageCreateFromJpegCtxEx + + See <gdImageCreateFromJpeg>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromJpegCtxEx(gdIOCtx *infile, int ignore_warning) { struct jpeg_decompress_struct cinfo; diff --git a/src/gd_matrix.c b/src/gd_matrix.c index 3147dea..182ea35 100644 --- a/src/gd_matrix.c +++ b/src/gd_matrix.c @@ -92,7 +92,7 @@ BGD_DECLARE(int) gdAffineInvert (double dst[6], const double src[6]) * flip_v - Whether or not to flip vertically * * Returns: - * GD_SUCCESS on success or GD_FAILURE + * GD_TRUE on success or GD_FALSE */ BGD_DECLARE(int) gdAffineFlip (double dst[6], const double src[6], const int flip_h, const int flip_v) { @@ -120,7 +120,7 @@ BGD_DECLARE(int) gdAffineFlip (double dst[6], const double src[6], const int fli * m2 - Second affine matrix * * Returns: - * GD_SUCCESS on success or GD_FAILURE + * GD_TRUE on success or GD_FALSE */ BGD_DECLARE(int) gdAffineConcat (double dst[6], const double m1[6], const double m2[6]) { @@ -149,7 +149,7 @@ BGD_DECLARE(int) gdAffineConcat (double dst[6], const double m1[6], const double * dst - Where to store the resulting affine transform * * Returns: - * GD_SUCCESS on success or GD_FAILURE + * GD_TRUE on success or GD_FALSE */ BGD_DECLARE(int) gdAffineIdentity (double dst[6]) { @@ -171,7 +171,7 @@ BGD_DECLARE(int) gdAffineIdentity (double dst[6]) * scale_y - Y scale factor * * Returns: - * GD_SUCCESS on success or GD_FAILURE + * GD_TRUE on success or GD_FALSE */ BGD_DECLARE(int) gdAffineScale (double dst[6], const double scale_x, const double scale_y) { @@ -196,7 +196,7 @@ BGD_DECLARE(int) gdAffineScale (double dst[6], const double scale_x, const doubl * angle - Rotation angle in degrees * * Returns: - * GD_SUCCESS on success or GD_FAILURE + * GD_TRUE on success or GD_FALSE */ BGD_DECLARE(int) gdAffineRotate (double dst[6], const double angle) { @@ -221,7 +221,7 @@ BGD_DECLARE(int) gdAffineRotate (double dst[6], const double angle) * angle - Shear angle in degrees * * Returns: - * GD_SUCCESS on success or GD_FAILURE + * GD_TRUE on success or GD_FALSE */ BGD_DECLARE(int) gdAffineShearHorizontal(double dst[6], const double angle) { @@ -243,7 +243,7 @@ BGD_DECLARE(int) gdAffineShearHorizontal(double dst[6], const double angle) * angle - Shear angle in degrees * * Returns: - * GD_SUCCESS on success or GD_FAILURE + * GD_TRUE on success or GD_FALSE */ BGD_DECLARE(int) gdAffineShearVertical(double dst[6], const double angle) { @@ -266,7 +266,7 @@ BGD_DECLARE(int) gdAffineShearVertical(double dst[6], const double angle) * offset_y - Vertical translation amount * * Returns: - * GD_SUCCESS on success or GD_FAILURE + * GD_TRUE on success or GD_FALSE */ BGD_DECLARE(int) gdAffineTranslate (double dst[6], const double offset_x, const double offset_y) { @@ -288,7 +288,7 @@ BGD_DECLARE(int) gdAffineTranslate (double dst[6], const double offset_x, const * composed of scaling, rotation, shearing, and translation, returns * the amount of scaling. * - * GD_SUCCESS on success or GD_FAILURE + * GD_TRUE on success or GD_FALSE **/ BGD_DECLARE(double) gdAffineExpansion (const double src[6]) { @@ -322,7 +322,7 @@ BGD_DECLARE(int) gdAffineRectilinear (const double m[6]) * m2 - The first affine transformation * * Returns: - * GD_SUCCESS on success or GD_FAILURE + * GD_TRUE on success or GD_FALSE */ BGD_DECLARE(int) gdAffineEqual (const double m1[6], const double m2[6]) { diff --git a/src/gd_png.c b/src/gd_png.c index 3d381e9..71a3852 100644 --- a/src/gd_png.c +++ b/src/gd_png.c @@ -96,6 +96,64 @@ gdPngFlushData (png_structp png_ptr) (void)png_ptr; } +/* + Function: gdImageCreateFromPng + + <gdImageCreateFromPng> is called to load images from PNG format + files. Invoke <gdImageCreateFromPng> with an already opened + pointer to a FILE containing the desired + image. <gdImageCreateFromPng> returns a <gdImagePtr> to the new + image, or NULL if unable to load the image (most often because the + file is corrupt or does not contain a PNG + image). <gdImageCreateFromPng> does not close the file. You can + inspect the sx and sy members of the image to determine its + size. The image must eventually be destroyed using + gdImageDestroy(). + + If the PNG image being loaded is a truecolor image, the resulting + gdImagePtr will refer to a truecolor image. If the PNG image being + loaded is a palette or grayscale image, the resulting gdImagePtr + will refer to a palette image. gd retains only 8 bits of + resolution for each of the red, green and blue channels, and only + 7 bits of resolution for the alpha channel. The former restriction + affects only a handful of very rare 48-bit color and 16-bit + grayscale PNG images. The second restriction affects all + semitransparent PNG images, but the difference is essentially + invisible to the eye. 7 bits of alpha channel resolution is, in + practice, quite a lot. + + Variants: + + <gdImageCreateFromPngPtr> creates an image from PNG data (i.e. the + contents of a PNG file) already in memory. + + <gdImageCreateFromPngCtx> reads in an image using the functions in + a <gdIOCtx> struct. + + <gdImageCreateFromPngSource> is similar to + <gdImageCreateFromPngCtx> but uses the old <gdSource> interface. + It is *obsolete*. + + Parameters: + + infile - The input FILE pointer. + + Returns: + + A pointer to the new image or NULL if an error occurred. + + Example: + + > gdImagePtr im; + > ... inside a function ... + > FILE *in; + > in = fopen("mypng.png", "rb"); + > im = gdImageCreateFromPng(in); + > fclose(in); + > // ... Use the image ... + > gdImageDestroy(im); + + */ BGD_DECLARE(gdImagePtr) gdImageCreateFromPng (FILE * inFile) { gdImagePtr im; @@ -106,6 +164,11 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromPng (FILE * inFile) return im; } +/* + Function: gdImageCreateFromPngPtr + + See <gdImageCreateFromPng>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromPngPtr (int size, void *data) { gdImagePtr im; @@ -117,9 +180,17 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromPngPtr (int size, void *data) return im; } + + /* This routine is based in part on the Chapter 13 demo code in * "PNG: The Definitive Guide" (http://www.libpng.org/pub/png/book/). */ + +/* + Function: gdImageCreateFromPngCtx + + See <gdImageCreateFromPng>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromPngCtx (gdIOCtx * infile) { png_byte sig[8]; @@ -474,6 +545,61 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromPngCtx (gdIOCtx * infile) } +/* + Function: gdImagePngEx + + <gdImagePngEx> outputs the specified image to the specified file in + PNG format. The file must be open for writing. Under MSDOS and all + versions of Windows, it is important to use "wb" as opposed to + simply "w" as the mode when opening the file, and under Unix there + is no penalty for doing so. <gdImagePngEx> does not close the file; + your code must do so. + + In addition, <gdImagePngEx> allows the level of compression to be + specified. A compression level of 0 means "no compression." A + compression level of 1 means "compressed, but as quickly as + possible." A compression level of 9 means "compressed as much as + possible to produce the smallest possible file." A compression level + of -1 will use the default compression level at the time zlib was + compiled on your system. + + Variants: + + <gdImagePng> is equivalent to calling <gdImagePngEx> with + compression of -1. + + <gdImagePngCtx> and <gdImagePngCtxEx> write via a <gdIOCtx> + instead of a file handle. + + <gdImagePngPtr> and <gdImagePngPtrEx> store the image file to + memory. + + Parameters: + + im - the image to write + outFile - the output FILE* object. + level - compression level: 0 -> none, 1-9 -> level, -1 -> default + + Returns: + + Nothing. + + Example: + + > gdImagePtr im; + > int black, white; + > FILE *out; + > + > im = gdImageCreate(100, 100); // Create the image + > white = gdImageColorAllocate(im, 255, 255, 255); // Alloc background + > black = gdImageColorAllocate(im, 0, 0, 0); // Allocate drawing color + > gdImageRectangle(im, 0, 0, 99, 99, black); // Draw rectangle + > out = fopen("rect.png", "wb"); // Open output file (binary) + > gdImagePngEx(im, out, 9); // Write PNG, max compression + > fclose(out); // Close file + > gdImageDestroy(im); // Destroy image + +*/ BGD_DECLARE(void) gdImagePngEx (gdImagePtr im, FILE * outFile, int level) { gdIOCtx *out = gdNewFileCtx (outFile); @@ -482,6 +608,20 @@ BGD_DECLARE(void) gdImagePngEx (gdImagePtr im, FILE * outFile, int level) out->gd_free (out); } +/* + Function: gdImagePng + + Equivalent to calling <gdImagePngEx> with compression of -1. + + Parameters: + + im - the image to save. + outFile - the output FILE*. + + Returns: + + Nothing. +*/ BGD_DECLARE(void) gdImagePng (gdImagePtr im, FILE * outFile) { gdIOCtx *out = gdNewFileCtx (outFile); @@ -490,6 +630,24 @@ BGD_DECLARE(void) gdImagePng (gdImagePtr im, FILE * outFile) out->gd_free (out); } + +/* + Function: gdImagePngPtr + + Equivalent to calling <gdImagePngPtrEx> with compression of -1. + + See <gdImagePngEx> for more information. + + Parameters: + + im - the image to save. + size - Output: size in bytes of the result. + + Returns: + + A pointer to memory containing the image data or NULL on error. + +*/ BGD_DECLARE(void *) gdImagePngPtr (gdImagePtr im, int *size) { void *rv; @@ -501,6 +659,30 @@ BGD_DECLARE(void *) gdImagePngPtr (gdImagePtr im, int *size) return rv; } +/* + Function: gdImagePngPtrEx + + Identical to <gdImagePngEx> except that it returns a pointer to a + memory area with the PNG data. This memory must be freed by the + caller when it is no longer needed. **The caller must invoke + gdFree(), not free()** + + The 'size' parameter receives the total size of the block of + memory. + + See <gdImagePngEx> for more information. + + Parameters: + + im - the image to save. + size - Output: size in bytes of the result. + level - compression level: 0 -> none, 1-9 -> level, -1 -> default + + Returns: + + A pointer to memory containing the image data or NULL on error. + +*/ BGD_DECLARE(void *) gdImagePngPtrEx (gdImagePtr im, int *size, int level) { void *rv; @@ -512,12 +694,51 @@ BGD_DECLARE(void *) gdImagePngPtrEx (gdImagePtr im, int *size, int level) return rv; } + + +/* + Function: gdImagePngCtx + + Equivalent to calling <gdImagePngCtxEx> with compression of -1. + See <gdImagePngEx> for more information. + + Parameters: + + im - the image to save. + outfile - the <gdIOCtx> to write to. + + Returns: + + Nothing. + +*/ BGD_DECLARE(void) gdImagePngCtx (gdImagePtr im, gdIOCtx * outfile) { /* 2.0.13: 'return' here was an error, thanks to Kevin Smith */ gdImagePngCtxEx (im, outfile, -1); } + + + +/* + Function: gdImagePngCtxEx + + Outputs the given image as PNG data, but using a <gdIOCtx> instead + of a file. See <gdIamgePnEx>. + + Parameters: + + im - the image to save. + outfile - the <gdIOCtx> to write to. + level - compression level: 0 -> none, 1-9 -> level, -1 -> default + + Returns: + + Nothing. + +*/ + /* This routine is based in part on code from Dale Lutz (Safe Software Inc.) * and in part on demo code from Chapter 15 of "PNG: The Definitive Guide" * (http://www.libpng.org/pub/png/book/). diff --git a/src/gd_ss.c b/src/gd_ss.c index 702a917..9098c9b 100644 --- a/src/gd_ss.c +++ b/src/gd_ss.c @@ -25,6 +25,12 @@ BGD_DECLARE(void) gdImagePngToSink (gdImagePtr im, gdSinkPtr outSink) out->gd_free (out); } +/* + Function: gdImageCreateFromPngSource + + See <gdImageCreateFromPng> for documentation. This is obsolete; use + <gdImageCreateFromPngCtx> instead. + */ BGD_DECLARE(gdImagePtr) gdImageCreateFromPngSource (gdSourcePtr inSource) { gdIOCtx *in = gdNewSSCtx (inSource, NULL); diff --git a/src/gd_wbmp.c b/src/gd_wbmp.c index ef15418..53fbdc2 100644 --- a/src/gd_wbmp.c +++ b/src/gd_wbmp.c @@ -32,7 +32,7 @@ * *-------------------------------------------------------------------------- * - * Parts od this code are inspired by 'pbmtowbmp.c' and 'wbmptopbm.c' by + * Parts of this code are inspired by 'pbmtowbmp.c' and 'wbmptopbm.c' by * Terje Sannum <terje@looplab.com>. * ** Permission to use, copy, modify, and distribute this software and its @@ -122,10 +122,12 @@ BGD_DECLARE(void) gdImageWBMPCtx(gdImagePtr image, int fg, gdIOCtx *out) freewbmp(wbmp); } -/* gdImageCreateFromWBMPCtx - * ------------------------ - * Create a gdImage from a WBMP file input from an gdIOCtx - */ +/* + Function: gdImageCreateFromWBMPCtx + + Reads in a WBMP image via a <gdIOCtx> struct. See + <gdImageCreateFromWBMP>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromWBMPCtx(gdIOCtx *infile) { Wbmp *wbmp; @@ -165,8 +167,48 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromWBMPCtx(gdIOCtx *infile) } -/* gdImageCreateFromWBMP - */ +/* + Function: gdImageCreateFromWBMP + + <gdImageCreateFromWBMP> is called to load images from WBMP format + files. Invoke <gdImageCreateFromWBMP> with an already opened + pointer to a file containing the desired + image. <gdImageCreateFromWBMP> returns a gdImagePtr to the new + image, or NULL if unable to load the image (most often because the + file is corrupt or does not contain a WBMP + image). <gdImageCreateFromWBMP> does not close the file. You can + inspect the sx and sy members of the image to determine its + size. The image must eventually be destroyed using + <gdImageDestroy>. + + Variants: + + <gdImageCreateFromWBMPPtr> creates an image from WBMP data (i.e. the + contents of a WBMP file) already in memory. + + <gdImageCreateFromWBMPCtx> reads in an image using the functions in + a <gdIOCtx> struct. + + Parameters: + + infile - The input FILE pointer + + Returns: + + A pointer to the new image or NULL if an error occurred. + + Example: + + > gdImagePtr im; + > FILE *in; + > in = fopen("mywbmp.wbmp", "rb"); + > im = gdImageCreateFromWBMP(in); + > fclose(in); + > // ... Use the image ... + > gdImageDestroy(im); + +*/ + BGD_DECLARE(gdImagePtr) gdImageCreateFromWBMP(FILE *inFile) { gdImagePtr im; @@ -177,6 +219,17 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromWBMP(FILE *inFile) return im; } + +/* + Function: gdImageCreateFromWBMPPtr + + Parameters: + + size - size of WBMP data in bytes. + data - WBMP data (i.e. contents of a WBMP file). + + See <gdImageCreateFromWBMP>. +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromWBMPPtr(int size, void *data) { gdImagePtr im; diff --git a/src/gd_xbm.c b/src/gd_xbm.c index 612be47..74d839b 100644 --- a/src/gd_xbm.c +++ b/src/gd_xbm.c @@ -18,7 +18,40 @@ #define MAX_XBM_LINE_SIZE 255 -/* {{{ gdImagePtr gdImageCreateFromXbm */ + +/* + Function: gdImageCreateFromXbm + + <gdImageCreateFromXbm> is called to load images from X bitmap + format files. Invoke <gdImageCreateFromXbm> with an already opened + pointer to a file containing the desired + image. <gdImageCreateFromXbm> returns a <gdImagePtr> to the new + image, or NULL if unable to load the image (most often because the + file is corrupt or does not contain an X bitmap format + image). <gdImageCreateFromXbm> does not close the file. + + You can inspect the sx and sy members of the image to determine + its size. The image must eventually be destroyed using + <gdImageDestroy>. + + Parameters: + + fd - The input FILE pointer + + Returns: + + A pointer to the new image or NULL if an error occurred. + + Example: + + > gdImagePtr im; + > FILE *in; + > in = fopen("myxbm.xbm", "rb"); + > im = gdImageCreateFromXbm(in); + > fclose(in); + > // ... Use the image ... + > gdImageDestroy(im); +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromXbm(FILE * fd) { char fline[MAX_XBM_LINE_SIZE]; @@ -142,7 +175,7 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromXbm(FILE * fd) gdImageDestroy(im); return 0; } -/* }}} */ + /* {{{ gdCtxPrintf */ static void gdCtxPrintf(gdIOCtx * out, const char *format, ...) @@ -817,6 +817,130 @@ BGD_DECLARE(int) gdFontCacheSetup (void) return 0; } +/* + Function: gdImageStringFTEx + + gdImageStringFTEx extends the capabilities of gdImageStringFT by + providing a way to pass additional parameters. + + If the strex parameter is not null, it must point to a + gdFTStringExtra structure. As of gd 2.0.5, this structure is defined + as follows: + + > typedef struct { + > // logical OR of gdFTEX_ values + > int flags; + > + > // fine tune line spacing for '\n' + > double linespacing; + > + > // Preferred character mapping + > int charmap; + > + > // Rendering resolution + > int hdpi; + > int vdpi; + > char *xshow; + > char *fontpath; + > } gdFTStringExtra, *gdFTStringExtraPtr; + + To output multiline text with a specific line spacing, include + gdFTEX_LINESPACE in the setting of flags: + + > flags |= gdFTEX_LINESPACE; + + And also set linespacing to the desired spacing, expressed as a + multiple of the font height. Thus a line spacing of 1.0 is the + minimum to guarantee that lines of text do not collide. + + If gdFTEX_LINESPACE is not present, or strex is null, or + gdImageStringFT is called, linespacing defaults to 1.05. + + To specify a preference for Unicode, Shift_JIS Big5 character + encoding, set or To output multiline text with a specific line + spacing, include gdFTEX_CHARMAP in the setting of flags: + + > flags |= gdFTEX_CHARMAP; + + And set charmap to the desired value, which can be any of + gdFTEX_Unicode, gdFTEX_Shift_JIS, gdFTEX_Big5, or + gdFTEX_Adobe_Custom. If you do not specify a preference, Unicode + will be tried first. If the preferred character mapping is not found + in the font, other character mappings are attempted. + + GD operates on the assumption that the output image will be rendered + to a computer screen. By default, gd passes a resolution of 96 dpi + to the freetype text rendering engine. This influences the "hinting" + decisions made by the renderer. To specify a different resolution, + set hdpi and vdpi accordingly (in dots per inch) and add + gdFTEX_RESOLUTION to flags: + + > flags | gdFTEX_RESOLUTION; + + GD 2.0.29 and later will normally attempt to apply kerning tables, + if fontconfig is available, to adjust the relative positions of + consecutive characters more ideally for that pair of + characters. This can be turn off by specifying the + gdFTEX_DISABLE_KERNING flag: + + > flags | gdFTEX_DISABLE_KERNING; + + GD 2.0.29 and later can return a vector of individual character + position advances, occasionally useful in applications that must + know exactly where each character begins. This is returned in the + xshow element of the gdFTStringExtra structure if the gdFTEX_XSHOW + flag is set: + + > flags | gdFTEX_XSHOW; + + The caller is responsible for calling gdFree() on the xshow element + after the call if gdFTEX_XSHOW is set. + + GD 2.0.29 and later can also return the path to the actual font file + used if the gdFTEX_RETURNFONTPATHNAME flag is set. This is useful + because GD 2.0.29 and above are capable of selecting a font + automatically based on a fontconfig font pattern when fontconfig is + available. This information is returned in the fontpath element of + the gdFTStringExtra structure. + + > flags | gdFTEX_RETURNFONTPATHNAME; + + The caller is responsible for calling gdFree() on the fontpath + element after the call if gdFTEX_RETURNFONTPATHNAME is set. + + GD 2.0.29 and later can use fontconfig to resolve font names, + including fontconfig patterns, if the gdFTEX_FONTCONFIG flag is + set. As a convenience, this behavior can be made the default by + calling gdFTUseFontConfig with a nonzero value. In that situation it + is not necessary to set the gdFTEX_FONTCONFIG flag on every call; + however explicit font path names can still be used if the + gdFTEX_FONTPATHNAME flag is set: + + > flags | gdFTEX_FONTPATHNAME; + + Unless gdFTUseFontConfig has been called with a nonzero value, GD + 2.0.29 and later will still expect the fontlist argument to the + freetype text output functions to be a font file name or list + thereof as in previous versions. If you do not wish to make + fontconfig the default, it is still possible to force the use of + fontconfig for a single call to the freetype text output functions + by setting the gdFTEX_FONTCONFIG flag: + + > flags | gdFTEX_FONTCONFIG; + + GD 2.0.29 and above can use fontconfig to resolve font names, + including fontconfig patterns, if the gdFTEX_FONTCONFIG flag is + set. As a convenience, this behavior can be made the default by + calling gdFTUseFontConfig with a nonzero value. In that situation it + is not necessary to set the gdFTEX_FONTCONFIG flag on every call; + however explicit font path names can still be used if the + gdFTEX_FONTPATHNAME flag is set: + + > flags | gdFTEX_FONTPATHNAME; + + For more information, see <gdImageStringFT>. +*/ + /* the platform-independent resolution used for size and position calculations */ /* the size of the error introduced by rounding is affected by this number */ #define METRIC_RES 300 diff --git a/src/gdxpm.c b/src/gdxpm.c index bad4be3..ae6e336 100644 --- a/src/gdxpm.c +++ b/src/gdxpm.c @@ -28,6 +28,40 @@ BGD_DECLARE(gdImagePtr) gdImageCreateFromXpm(char *filename) #include <X11/xpm.h> +/* + Function: gdImageCreateFromXpm + + <gdImageCreateFromXbm> is called to load images from XPM X Window + System color bitmap format files. This function is available only + if HAVE_XPM is selected in the Makefile and the Xpm library is + linked with the application. Unlike most gd file functions, the + Xpm functions *require filenames*, not file + pointers. <gdImageCreateFromXpm> returns a <gdImagePtr> to the new + image, or NULL if unable to load the image (most often because the + file is corrupt or does not contain an XPM bitmap format + image). You can inspect the sx and sy members of the image to + determine its size. The image must eventually be destroyed using + <gdImageDestroy>. + + Parameters: + + filename - The input filename (*not* FILE pointer) + + Returns: + + A pointer to the new image or NULL if an error occurred. + + Example: + + > gdImagePtr im; + > FILE *in; + > in = fopen("myxpm.xpm", "rb"); + > im = gdImageCreateFromXpm(in); + > fclose(in); + > // ... Use the image ... + > gdImageDestroy(im); + +*/ BGD_DECLARE(gdImagePtr) gdImageCreateFromXpm(char *filename) { XpmInfo info; |