gd.h

Summary
gd.h
Color Decomposition
gdTrueColorGetAlphaGets the alpha channel value
gdTrueColorGetRedGets the red channel value
gdTrueColorGetGreenGets the green channel value
gdTrueColorGetBlueGets the blue channel value
EffectsThe layering effect
Color Quantization
gdPaletteQuantizationMethod
Transform
gdInterpolationMethod
Types
gdImage
gdImagePtrThe data structure in which gd stores images.
Types
gdPointFDefines a point in a 2D coordinate system using floating point values.
gdPointFPtrPointer to a gdPointF
Types
gdFont
gdFontPtrA font structure, containing the bitmaps of all characters in a font.
ColorsColors are always of type int which is supposed to be at least 32 bit large.
Special Colors
Types
gdSource
gdSourcePtrNote: This interface is obsolete and kept only for *compatibility.
Types
gdFTStringExtra
gdFTStringExtraPtrA structure and associated pointer type used to pass additional parameters to the gdImageStringFTEx function.
Types
gdPoint
gdPointPtrRepresents a point in the coordinate space of the image; used by gdImagePolygon, gdImageOpenPolygon and gdImageFilledPolygon for polygon drawing.
gdRectA rectangle in the coordinate space of the image
gdRectPtrA pointer to a gdRect
Color Composition
gdTrueColorAlphaCompose a truecolor value from its components
GifAnimLegal values for Disposal.
gdImageGifAnim
Types
gdSink
gdSinkPtrNote: This interface is obsolete and kept only for compatibility.
Accessor Macros
gdImageTrueColorWhether an image is a truecolor image.
gdImageSXGets the width (in pixels) of an image.
gdImageSYGets the height (in pixels) of an image.
gdImageColorsTotalGets the number of colors in the palette.
gdImageRedGets the red component value of a given color.
gdImageGreenGets the green component value of a given color.
gdImageBlueGets the blue component value of a given color.
gdImageAlphaGets the alpha component value of a given color.
gdImageGetTransparentGets the transparent color of the image.
gdImageGetInterlacedWhether an image is interlaced.
gdImagePalettePixelGets the color of a pixel.
gdImageTrueColorPixelGets the color of a pixel.
gdImageResolutionXGets the horizontal resolution in DPI.
gdImageResolutionYGets the vertical resolution in DPI.
Crop
gdCropMode
Image Comparison

Color Decomposition

gdTrueColorGetAlpha

Gets the alpha channel value

Parameters

cThe color

See also

gdTrueColorGetRed

Gets the red channel value

Parameters

cThe color

See also

gdTrueColorGetGreen

Gets the green channel value

Parameters

cThe color

See also

gdTrueColorGetBlue

Gets the blue channel value

Parameters

cThe color

See also

Effects

The layering effect

When pixels are drawn the new colors are “mixed” with the background depending on the effect.

Note that the effect does not apply to palette images, where pixels are always replaced.

Modes

gdEffectReplacereplace pixels
gdEffectAlphaBlendblend pixels, see gdAlphaBlend
gdEffectNormaldefault mode; same as gdEffectAlphaBlend
gdEffectOverlayoverlay pixels, see gdLayerOverlay
gdEffectMultiplyoverlay pixels with multiply effect, see gdLayerMultiply

See also

Color Quantization

gdPaletteQuantizationMethod

Constants

GD_QUANT_DEFAULTGD_QUANT_LIQ if libimagequant is available, GD_QUANT_JQUANT otherwise.
GD_QUANT_JQUANTlibjpeg’s old median cut.  Fast, but only uses 16-bit color.
GD_QUANT_NEUQUANTNeuQuant - approximation using Kohonen neural network.
GD_QUANT_LIQA combination of algorithms used in libimagequant aiming for the highest quality at cost of speed.

Note that GD_QUANT_JQUANT does not retain the alpha channel, and GD_QUANT_NEUQUANT does not support dithering.

See also

Transform

gdInterpolationMethod

GD_BELLBell
GD_BESSELBessel
GD_BILINEAR_FIXEDfixed point bilinear
GD_BICUBICBicubic
GD_BICUBIC_FIXEDfixed point bicubic integer
GD_BLACKMANBlackman
GD_BOXBox
GD_BSPLINEBSpline
GD_CATMULLROMCatmullrom
GD_GAUSSIANGaussian
GD_GENERALIZED_CUBICGeneralized cubic
GD_HERMITEHermite
GD_HAMMINGHamming
GD_HANNINGHannig
GD_MITCHELLMitchell
GD_NEAREST_NEIGHBOURNearest neighbour interpolation
GD_POWERPower
GD_QUADRATICQuadratic
GD_SINCSinc
GD_TRIANGLETriangle
GD_WEIGHTED44 pixels weighted bilinear interpolation
GD_LINEARbilinear interpolation

See also

Types

gdImage

gdImagePtr

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.

gdImagePtr is a pointer to gdImage.

See also

Accessor Macros

(Previous versions of this library encouraged directly manipulating the contents ofthe struct but we are attempting to move away from this practice so the fields are no longer documented here.  If you need to poke at the internals of this struct, feel free to look at gd.h.)

Types

gdPointF

Defines a point in a 2D coordinate system using floating point values. x - Floating point position (increase from left to right) y - Floating point Row position (increase from top to bottom)

gdPointFPtr

Types

gdFont

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.  gdFontGetSmall 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.

Colors

Colors are always of type int which is supposed to be at least 32 bit large.

Kinds of colors

true colorsARGB values where the alpha channel is stored as most significant, and the blue channel as least significant byte.  Note that the alpha channel only uses the 7 least significant bits.  Don’t rely on the internal representation, though, and use gdTrueColorAlpha to compose a truecolor value, and gdTrueColorGetAlpha, gdTrueColorGetRed, gdTrueColorGetGreen and gdTrueColorGetBlue to access the respective channels.
palette indexesThe index of a color palette entry (0-255).
special colorsAs listed in the following section.

Special Colors

gdStyleduse the current style, see gdImageSetStyle
gdBrusheduse the current brush, see gdImageSetBrush
gdStyledBrusheduse the current style and brush
gdTileduse the current tile, see gdImageSetTile
gdTransparentindicate transparency, what is not the same as the transparent color index; used for lines only
gdAntiAliaseddraw anti aliased

Types

gdSource

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.

Types

gdFTStringExtra

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.

Types

gdPoint

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;

gdRect

A rectangle in the coordinate space of the image

Members

xThe x-coordinate of the upper left corner.
yThe y-coordinate of the upper left corner.
widthThe width.
heightThe height.

gdRectPtr

A pointer to a gdRect

Color Composition

gdTrueColorAlpha

Compose a truecolor value from its components

Parameters

rThe red channel (0-255)
gThe green channel (0-255)
bThe blue channel (0-255)
aThe alpha channel (0-127, where 127 is fully transparent, and 0 is completely opaque).

See also

GifAnim

Legal values for Disposal. gdDisposalNone is always used by the built-in optimizer if previm is passed.

gdImageGifAnim

gdDisposalUnknownNot recommended
gdDisposalNonePreserve previous frame
gdDisposalRestoreBackgroundFirst allocated color of palette
gdDisposalRestorePreviousRestore to before start of frame

See also

Types

gdSink

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.

Accessor Macros

gdImageTrueColor

Whether an image is a truecolor image.

Parameters

imThe image.

Returns

Non-zero if the image is a truecolor image, zero for palette images.

gdImageSX

Gets the width (in pixels) of an image.

Parameters

imThe image.

gdImageSY

Gets the height (in pixels) of an image.

Parameters

imThe image.

gdImageColorsTotal

Gets the number of colors in the palette.

This macro is only valid for palette images.

Parameters

imThe image

gdImageRed

Gets the red component value of a given color.

Parameters

imThe image.
cThe color.

gdImageGreen

Gets the green component value of a given color.

Parameters

imThe image.
cThe color.

gdImageBlue

Gets the blue component value of a given color.

Parameters

imThe image.
cThe color.

gdImageAlpha

Gets the alpha component value of a given color.

Parameters

imThe image.
cThe color.

gdImageGetTransparent

Gets the transparent color of the image.

Parameters

imThe image.

See also

gdImageGetInterlaced

Whether an image is interlaced.

Parameters

imThe image.

Returns

Non-zero for interlaced images, zero otherwise.

See also

gdImagePalettePixel

Gets the color of a pixel.

Calling this macro is only valid for palette images.  No bounds checking is done for the coordinates.

Parameters

imThe image.
xThe x-coordinate.
yThe y-coordinate.

See also

gdImageTrueColorPixel

Gets the color of a pixel.

Calling this macro is only valid for truecolor images.  No bounds checking is done for the coordinates.

Parameters

imThe image.
xThe x-coordinate.
yThe y-coordinate.

See also

gdImageResolutionX

Gets the horizontal resolution in DPI.

Parameters

imThe image.

See also

gdImageResolutionY

Gets the vertical resolution in DPI.

Parameters

imThe image.

See also

Crop

gdCropMode

GD_CROP_DEFAULTDefault crop mode (4 corners or background)
GD_CROP_TRANSPARENTCrop using the transparent color
GD_CROP_BLACKCrop black borders
GD_CROP_WHITECrop white borders
GD_CROP_SIDESCrop using colors of the 4 corners

See also

Image Comparison

Constants

GD_CMP_IMAGEActual image IS different
GD_CMP_NUM_COLORSNumber of colors in pallette differ
GD_CMP_COLORImage colors differ
GD_CMP_SIZE_XImage width differs
GD_CMP_SIZE_YImage heights differ
GD_CMP_TRANSPARENTTransparent color differs
GD_CMP_BACKGROUNDBackground color differs
GD_CMP_INTERLACEInterlaced setting differs
GD_CMP_TRUECOLORTruecolor vs palette differs

See also

Defines a point in a 2D coordinate system using floating point values.
gdImageStringFTEx extends the capabilities of gdImageStringFT by providing a way to pass additional parameters.
void gdImagePolygon (gdImagePtr im,
gdPointPtr p,
int n,
int c)
Draws a closed polygon
void gdImageOpenPolygon (gdImagePtr im,
gdPointPtr p,
int n,
int c)
Draws an open polygon
void gdImageFilledPolygon (gdImagePtr im,
gdPointPtr p,
int n,
int c)
Draws a filled polygon
A rectangle in the coordinate space of the image
Compose a truecolor value from its components
int gdAlphaBlend (int dst,
int src)
Blend two colors
int gdLayerOverlay (int dst,
int src)
Overlay two colors
int gdLayerMultiply (int dst,
int src)
Overlay two colors with multiply effect
void gdImageAlphaBlending (gdImagePtr im,
int alphaBlendingArg)
Set the effect for subsequent drawing operations
int gdImageTrueColorToPaletteSetMethod (gdImagePtr im,
int method,
int speed)
Selects the quantization method
int gdImageSetInterpolationMethod(gdImagePtr im,
gdInterpolationMethod id)
Set the interpolation method for subsequent operations
gdInterpolationMethod gdImageGetInterpolationMethod(gdImagePtr im)
Get the current interpolation method
gdImagePtr gdImageCreate (int sx,
int sy)
gdImageCreate is called to create palette-based images, with no more than 256 colors.
gdImagePtr gdImageCreateTrueColor (int sx,
int sy)
gdImageCreateTrueColor is called to create truecolor images, with an essentially unlimited number of colors.
The data structure in which gd stores images.
gdFontPtr gdFontGetSmall (void)
Returns the built-in small font.
gdFontPtr gdFontGetLarge (void)
Returns the built-in large font.
Gets the alpha channel value
Gets the red channel value
Gets the green channel value
Gets the blue channel value
void gdImageSetStyle (gdImagePtr im,
int *style,
int noOfPixels)
Sets the style for following drawing operations
void gdImageSetBrush (gdImagePtr im,
gdImagePtr brush)
Sets the brush for following drawing operations
void gdImageSetTile (gdImagePtr im,
gdImagePtr tile)
gdIOCtx structures hold function pointers for doing image IO.
gdImagePtr gdImageCreateFromPngSource (gdSourcePtr inSource)
See gdImageCreateFromPng for documentation.
int gdImageColorExactAlpha (gdImagePtr im,
int r,
int g,
int b,
int a)
Gets the exact color of the image
void gdImageGifAnimAdd(gdImagePtr im,
FILE *outFile,
int LocalCM,
int LeftOfs,
int TopOfs,
int Delay,
int Disposal,
gdImagePtr previm)
This function writes GIF animation frames to GIF animation, which was initialized with gdImageGifAnimBegin.
void gdImagePngToSink (gdImagePtr im,
gdSinkPtr outSink)
void gdImageColorTransparent (gdImagePtr im,
int color)
Sets the transparent color of the image
void gdImageInterlace (gdImagePtr im,
int interlaceArg)
Sets whether an image is interlaced
Gets the color of a pixel.
int gdImageGetPixel (gdImagePtr im,
int x,
int y)
Gets a pixel color as stored in the image.
Gets the color of a pixel.
int gdImageGetTrueColorPixel (gdImagePtr im,
int x,
int y)
Gets a pixel color always as truecolor value.
Gets the vertical resolution in DPI.
void gdImageSetResolution(gdImagePtr im,
const unsigned int res_x,
const unsigned int res_y)
Sets the resolution of an image.
Gets the horizontal resolution in DPI.
gdImagePtr gdImageCropAuto(gdImagePtr im,
const unsigned int mode)
Crop an image automatically
int gdImageCompare (gdImagePtr im1,
gdImagePtr im2)
Compare two images
Close