/home/pierre/projects/libgd/releases/libgd_2.3.3/docs/naturaldocs/tmp/gd.h

# gd.h

Summary

gd.h |
Color Decomposition |
gdTrueColorGetAlpha | Gets the alpha channel value
gdTrueColorGetRed | Gets the red channel value
gdTrueColorGetGreen | Gets the green channel value
gdTrueColorGetBlue | Gets the blue channel value
Effects | The layering effect
Color Quantization |
gdPaletteQuantizationMethod |
Transform |
gdInterpolationMethod |
HEIF Coding Format | Values that select the HEIF coding format.
gdHeifCodec | GD_HEIF_CODEC_UNKNOWN GD_HEIF_CODEC_HEVC GD_HEIF_CODEC_AV1
HEIF Chroma Subsampling | Values that select the HEIF chroma subsampling.
gdHeifCompression | GD_HEIF_CHROMA_420 GD_HEIF_CHROMA_422 GD_HEIF_CHROMA_444
Types |
gdImage |
gdImagePtr | The data structure in which gd stores images.
Types |
gdPointF | Defines a point in a 2D coordinate system using floating point values.
gdPointFPtr | Pointer to a gdPointF
Types |
gdFont |
gdFontPtr | A font structure, containing the bitmaps of all characters in a font.
Colors | Colors are always of type int which is supposed to be at least 32 bit large.
Special Colors |
Types |
gdSource |
gdSourcePtr | Note: This interface is obsolete and kept only for *compatibility.
Types |
gdFTStringExtra |
gdFTStringExtraPtr | A structure and associated pointer type used to pass additional parameters to the gdImageStringFTEx function.
Types |
gdPoint |
gdPointPtr | Represents a point in the coordinate space of the image; used by gdImagePolygon, gdImageOpenPolygon and gdImageFilledPolygon for polygon drawing.
gdRect | A rectangle in the coordinate space of the image
gdRectPtr | A pointer to a gdRect
Color Composition |
gdTrueColorAlpha | Compose a truecolor value from its components
WebP |
gdWebpLossless | Lossless quality threshold.
GifAnim | Legal values for Disposal.
gdImageGifAnim |
Types |
gdSink |
gdSinkPtr | Note: This interface is obsolete and kept only for compatibility.
Accessor Macros |
gdImageTrueColor | Whether an image is a truecolor image.
gdImageSX | Gets the width (in pixels) of an image.
gdImageSY | Gets the height (in pixels) of an image.
gdImageColorsTotal | Gets the number of colors in the palette.
gdImageRed | Gets the red component value of a given color.
gdImageGreen | Gets the green component value of a given color.
gdImageBlue | Gets the blue component value of a given color.
gdImageAlpha | Gets the alpha component value of a given color.
gdImageGetTransparent | Gets the transparent color of the image.
gdImageGetInterlaced | Whether an image is interlaced.
gdImagePalettePixel | Gets the color of a pixel.
gdImageTrueColorPixel | Gets the color of a pixel.
gdImageResolutionX | Gets the horizontal resolution in DPI.
gdImageResolutionY | Gets the vertical resolution in DPI.
Crop |
gdCropMode |
Image Comparison |

### Color Decomposition

### gdTrueColorGetAlpha

Gets the alpha channel value

#### Parameters

c | The color

#### See also

- gdTrueColorAlpha

### gdTrueColorGetRed

Gets the red channel value

#### Parameters

c | The color

#### See also

- gdTrueColorAlpha

### gdTrueColorGetGreen

Gets the green channel value

#### Parameters

c | The color

#### See also

- gdTrueColorAlpha

### gdTrueColorGetBlue

Gets the blue channel value

#### Parameters

c | The color

#### See also

- gdTrueColorAlpha

### 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

gdEffectReplace | replace pixels
gdEffectAlphaBlend | blend pixels, see gdAlphaBlend
gdEffectNormal | default mode; same as gdEffectAlphaBlend
gdEffectOverlay | overlay pixels, see gdLayerOverlay
gdEffectMultiply | overlay pixels with multiply effect, see gdLayerMultiply

#### See also

- gdImageAlphaBlending

### Color Quantization

### gdPaletteQuantizationMethod

#### Constants

GD_QUANT_DEFAULT | GD_QUANT_LIQ if libimagequant is available, GD_QUANT_JQUANT otherwise.
GD_QUANT_JQUANT | libjpeg’s old median cut. Fast, but only uses 16-bit color.
GD_QUANT_NEUQUANT | NeuQuant - approximation using Kohonen neural network.
GD_QUANT_LIQ | A 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

- gdImageTrueColorToPaletteSetMethod

### Transform

### gdInterpolationMethod

GD_BELL | Bell
GD_BESSEL | Bessel
GD_BILINEAR_FIXED | fixed point bilinear
GD_BICUBIC | Bicubic
GD_BICUBIC_FIXED | fixed point bicubic integer
GD_BLACKMAN | Blackman
GD_BOX | Box
GD_BSPLINE | BSpline
GD_CATMULLROM | Catmullrom
GD_GAUSSIAN | Gaussian
GD_GENERALIZED_CUBIC | Generalized cubic
GD_HERMITE | Hermite
GD_HAMMING | Hamming
GD_HANNING | Hannig
GD_MITCHELL | Mitchell
GD_NEAREST_NEIGHBOUR | Nearest neighbour interpolation
GD_POWER | Power
GD_QUADRATIC | Quadratic
GD_SINC | Sinc
GD_TRIANGLE | Triangle
GD_WEIGHTED4 | 4 pixels weighted bilinear interpolation
GD_LINEAR | bilinear interpolation

#### See also

- gdImageSetInterpolationMethod
- gdImageGetInterpolationMethod

### HEIF Coding Format

Values that select the HEIF coding format.

### gdHeifCodec

GD_HEIF_CODEC_UNKNOWN GD_HEIF_CODEC_HEVC GD_HEIF_CODEC_AV1

#### See also

- gdImageHeif

### HEIF Chroma Subsampling

Values that select the HEIF chroma subsampling.

### gdHeifCompression

GD_HEIF_CHROMA_420 GD_HEIF_CHROMA_422 GD_HEIF_CHROMA_444

#### See also

- gdImageHeif

### 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

Pointer to a gdPointF

#### See also

gdImageCreate, gdImageCreateTrueColor,

### 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 colors | ARGB 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 indexes | The index of a color palette entry (0-255).
special colors | As listed in the following section.

### Special Colors

gdStyled | use the current style, see gdImageSetStyle
gdBrushed | use the current brush, see gdImageSetBrush
gdStyledBrushed | use the current style and brush
gdTiled | use the current tile, see gdImageSetTile
gdTransparent | indicate transparency, what is not the same as the transparent color index; used for lines only
gdAntiAliased | draw 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

x | The x-coordinate of the upper left corner.
y | The y-coordinate of the upper left corner.
width | The width.
height | The height.

### gdRectPtr

A pointer to a gdRect

### Color Composition

### gdTrueColorAlpha

Compose a truecolor value from its components

#### Parameters

r | The red channel (0-255)
g | The green channel (0-255)
b | The blue channel (0-255)
a | The alpha channel (0-127, where 127 is fully transparent, and 0 is completely opaque).

#### See also

- gdTrueColorGetAlpha
- gdTrueColorGetRed
- gdTrueColorGetGreen
- gdTrueColorGetBlue
- gdImageColorExactAlpha

### WebP

### gdWebpLossless

Lossless quality threshold. When image quality is greater than or equal to gdWebpLossless, the image will be written in the lossless WebP format.

#### See also

- gdImageWebpEx

### GifAnim

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

### gdImageGifAnim

gdDisposalUnknown | Not recommended
gdDisposalNone | Preserve previous frame
gdDisposalRestoreBackground | First allocated color of palette
gdDisposalRestorePrevious | Restore to before start of frame

#### See also

- gdImageGifAnimAdd

### 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

im | The 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

im | The image.

### gdImageSY

Gets the height (in pixels) of an image.

#### Parameters

im | The image.

### gdImageColorsTotal

Gets the number of colors in the palette.

This macro is only valid for palette images.

#### Parameters

im | The image

### gdImageRed

Gets the red component value of a given color.

#### Parameters

im | The image.
c | The color.

### gdImageGreen

Gets the green component value of a given color.

#### Parameters

im | The image.
c | The color.

### gdImageBlue

Gets the blue component value of a given color.

#### Parameters

im | The image.
c | The color.

### gdImageAlpha

Gets the alpha component value of a given color.

#### Parameters

im | The image.
c | The color.

### gdImageGetTransparent

Gets the transparent color of the image.

#### Parameters

im | The image.

#### See also

- gdImageColorTransparent

### gdImageGetInterlaced

Whether an image is interlaced.

#### Parameters

im | The image.

#### Returns

Non-zero for interlaced images, zero otherwise.

#### See also

- gdImageInterlace

### 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

im | The image.
x | The x-coordinate.
y | The y-coordinate.

#### See also

- gdImageTrueColorPixel
- gdImageGetPixel

### 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

im | The image.
x | The x-coordinate.
y | The y-coordinate.

#### See also

- gdImagePalettePixel
- gdImageGetTrueColorPixel

### gdImageResolutionX

Gets the horizontal resolution in DPI.

#### Parameters

im | The image.

#### See also

- gdImageResolutionY
- gdImageSetResolution

### gdImageResolutionY

Gets the vertical resolution in DPI.

#### Parameters

im | The image.

#### See also

- gdImageResolutionX
- gdImageSetResolution

### Crop

### gdCropMode

GD_CROP_DEFAULT | Same as GD_CROP_TRANSPARENT
GD_CROP_TRANSPARENT | Crop using the transparent color
GD_CROP_BLACK | Crop black borders
GD_CROP_WHITE | Crop white borders
GD_CROP_SIDES | Crop using colors of the 4 corners

#### See also

- gdImageCropAuto

### Image Comparison

#### Constants

GD_CMP_IMAGE | Actual image IS different
GD_CMP_NUM_COLORS | Number of colors in pallette differ
GD_CMP_COLOR | Image colors differ
GD_CMP_SIZE_X | Image width differs
GD_CMP_SIZE_Y | Image heights differ
GD_CMP_TRANSPARENT | Transparent color differs
GD_CMP_BACKGROUND | Background color differs
GD_CMP_INTERLACE | Interlaced setting differs
GD_CMP_TRUECOLOR | Truecolor vs palette differs

#### See also

- gdImageCompare

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

> void gdImageHeif( | gdImagePtr |  | im,
> | FILE | * | outFile | )

Variant of gdImageHeifEx which uses the default quality (-1), the default codec (GD_HEIF_Codec_HEVC) and the default chroma subsampling (GD_HEIF_CHROMA_444).

> 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
Lossless quality threshold.

> void gdImageWebpEx ( | gdImagePtr |  | im,
> | FILE | * | outFile,
> | int |  | quality | )

gdImageWebpEx outputs the specified image to the specified file in WebP format.

> 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