From LibGD

Table of Contents

Image creation, destruction, loading and saving

Contents 1 Types 1.1 gdImage(TYPE) 1.2 gdImagePtr (TYPE) 1.3 gdIOCtx (TYPE) 1.4 gdFont (TYPE) 1.5 gdFontPtr (TYPE) 1.6 gdPointPtr (TYPE) 1.7 gdFTStringExtra (TYPE) 1.8 gdFTStringExtraPtr (TYPE) 1.9 gdSource (TYPE)

Types

gdImage(TYPE)

The data structure in which gd stores images. gdImageCreate, gdImageCreateTrueColor and the various image file-loading functions return a pointer to this type, and the other functions expect to receive a pointer to this type as their first argument. It is reasonably safe to examine any of the members of this structure. It is also reasonably safe to modify individual pixels within the pixels or tpixels arrays. If the trueColor flag is set, the tpixels array is valid; otherwise the pixels array is invalid.

The colorsTotal, red, green, blue, alpha and open arrays manage the palette. They are valid only when the trueColor flag is not set. The transparent value contains the palette index of the first transparent color as read-only information for backwards compatibility; gd 2.0 stores this information in the alpha array so that variable transparency can be supported for each palette entry. However, for truecolor images, transparent represents a single RGB color which is always 100% transparent, and this feature is generally supported by browsers which do not support full alpha channels.

typedef struct {
      /* Palette-based image pixels */
      unsigned char ** pixels;
      int sx;
      int sy;
      /* These are valid in palette images only. See also
      /* 'alpha', which appears later in the structure to
        preserve binary backwards compatibility */
      int colorsTotal;
      int red[gdMaxColors];
      int green[gdMaxColors];
      int blue[gdMaxColors]; 
      int open[gdMaxColors];
      /* For backwards compatibility, this is set to the
        first palette entry with 100% transparency,
        and is also set and reset by the 
        gdImageColorTransparent function. Newer
        applications can allocate palette entries
        with any desired level of transparency; however,
        bear in mind that many viewers, notably
        many web browsers, fail to implement
        full alpha channel for PNG and provide
        support for full opacity or transparency only. */
      int transparent;
      int *polyInts;
      int polyAllocated;
      struct gdImageStruct *brush;
      struct gdImageStruct *tile;  
      int brushColorMap[gdMaxColors];
      int tileColorMap[gdMaxColors];
      int styleLength;
      int stylePos;
      int *style;
      int interlace;
      /* New in 2.0: alpha channel for palettes. Note that only
        Macintosh Internet Explorer and (possibly) Netscape 6
        really support multiple levels of transparency in
        palettes, to my knowledge, as of 2/15/01. Most
        common browsers will display 100% opaque and
        100% transparent correctly, and do something 
        unpredictable and/or undesirable for levels
        in between. TBB */
      int alpha[gdMaxColors]; 
      /* Truecolor flag and pixels. New 2.0 fields appear here at the
        end to minimize breakage of existing object code. */
      int trueColor;
      int ** tpixels;
      /* Should alpha channel be copied, or applied, each time a
        pixel is drawn? This applies to truecolor images only.
        No attempt is made to alpha-blend in palette images,
        even if semitransparent palette entries exist. 
        To do that, build your image as a truecolor image,
        then quantize down to 8 bits. */
      int alphaBlendingFlag;
      /* Should the alpha channel of the image be saved? This affects
        PNG at the moment; other future formats may also
        have that capability. JPEG doesn't. */
      int saveAlphaFlag;
    } gdImage;

The order of the structure members may appear confusing, but was chosen deliberately to increase backwards compatibility with existing gd 1.x-based binary code that references particular structure members.

gdImagePtr (TYPE)

A pointer to an image structure. gdImageCreate returns this type, and the other functions expect it as the first argument.

gdIOCtx (TYPE)

Most of the gd functions that read and write files, such as gdImagePng and , 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;

gdFont (TYPE)

A font structure. Used to declare the characteristics of a font. Please see the files gdfontl.c and gdfontl.h for an example of the proper declaration of this structure. 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.

    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 (TYPE)

A pointer to a font structure. Text-output functions expect these as their second argument, following the gdImagePtr argument. Two such pointers are declared in the provided include files gdfonts.h and gdfontl.h. gdPoint (TYPE) Represents a point in the coordinate space of the image; used by gdImagePolygon, gdImageOpenPolygon and gdImageFilledPolygon.

    typedef struct {
            int x, y;
    } gdPoint, *gdPointPtr;

gdPointPtr (TYPE)

A pointer to a gdPoint structure; passed as an argument to gdImagePolygon, gdImageOpenPolygon and gdImageFilledPolygon.

gdFTStringExtra (TYPE)

A structure used to pass additional parameters to the gdImageStringFTEx function. See gdImageStringFTEx for the structure definition.

gdFTStringExtraPtr (TYPE)

A pointer to a structure used to pass additional parameters to the gdImageStringFTEx function. See gdImageStringFTEx for the structure definition.

gdSource (TYPE)

    typedef struct {
            int (*source) (void *context, char *buffer, int len);
            void *context;
    } gdSource, *gdSourcePtr;

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. gdSink (TYPE)

    typedef struct {
            int (*sink) (void *context, char *buffer, int len);
            void *context;
    } gdSink, *gdSinkPtr;

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.