Rexx/gd

Version 2.1

A Rexx extension for fast image creation

What is Rexx/gd?

Rexx/gd is a Rexx extension allowing you to quickly draw images complete with lines, arcs, text, multiple colors, cut and paste from other images, and flood fills, and write out the result as a PNG, BMP, JPEG or GIF file. This is particularly useful in World Wide Web applications, where these image formats are the most common formats accepted for inline images by most browsers. Rexx/gd now also creates animated GIF files.

Rexx/gd is not a paint program. If you are looking for a paint program, you are looking in the wrong place. If you are not a Rexx programmer, you are looking in the wrong place.

Rexx/gd does not provide for every possible desirable graphics operation. Rexx/gd is based on the freely available gd library. Currently Rexx/gd supports the majority of the functionality of gd 2.0.33.

What else do I need to use Rexx/gd?

Well, you obviously need a Rexx interpreter! Rexx/gd will work with any Rexx interpreter that supports the SAA API.

Rexx/gd is dependent on the requirements of the underlying gd library. As such Rexx/gd requires the following:

If you want to use the TrueType font support, you will also need the Freetype Library.

If you want to see the images you have created, then you will need a PNG and/or JPEG viewer. Most browsers will be able to view these files.

While this all looks daunting, the installer for the Win32 port of Rexx/gd contains the gd library DLL (which contains all of the above packages), so you don't need anything else, other than Rexx/gd. The OS/2 port requires only the gd library package (which at the time of writing was available at: OS/2 gd library 2-0.15. Note that any GIF support in the OS/2 package is NOT supported in Rexx/gd.

On Unix platforms there are packages, deb and rpm available for most popular distributions. However if you want to build from source things are not as simple :-( You will need to install (possibly build) the above packages. Once you have done this, then the configure script that comes with Rexx/gd should find all of the required libraries. if not, you can always specify where you have installed the packages. Note that you will need development versions of the packages; ie. library files and header files!
The basic steps once you have extracted the source is:

% ./configure --with-rexx=xxxx  (where xxxx is regina, oorexx, ...)
% make
% sudo make install

Rexx/gd basics: using Rexx/gd in your program

To use Rexx/gd in your program, load the library with RxFuncAdd as you would for any other Rexx extensions and call GdLoadFuncs.

Here is a short example program. (For a more advanced example, see rexxgddemo.rexx, included in the distribution. rexxgddemo.rexx is NOT the same program; it demonstrates additional features!)

/* Load the Rexx/gd library functions */
Call RxFuncAdd 'GdLoadFuncs', 'rexxgd', 'GdLoadFuncs'
Call GdLoadFuncs

/* Allocate the image: 64 pixels across by 64 pixels tall */
im = gdImageCreate(64, 64)

/* Allocate the color black (red, green and blue all minimum).
   Since this is the first color in a new image, it will
   be the background color. */
black = gdImageColorAllocate(im, 0, 0, 0)

/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)

/* Draw a line from the upper left to the lower right,
   using white color index. */
Call gdImageLine im, 0, 0, 63, 63, white

/* Output the image to the disk file in PNG format. */
gdImagePng(im, 'test.png');

/* Output the same image in JPEG format, using the default
   JPEG quality setting. */
Call gdImageJpeg im, 'test.jpg', -1

/* Destroy the image in memory. */
Call gdImageDestroy im
When executed, this program creates an image, allocates two colors (the first color allocated becomes the background color), draws a diagonal line (note that 0, 0 is the upper left corner), writes the image to PNG and JPEG files, and destroys the image.

The above example program should give you an idea of how the package works. Rexx/gd provides many additional functions, which are listed in the following reference chapters, complete with code snippets demonstrating each. There is also an alphabetical index.

Rexx/gd Coordinates System

Rexx/gd uses a coordinates system which has an origin (0,0) in the top-left corner of the image, with the x axis increasing to the right, and the y axis increasing to the bottom. No negative coordinates are supported.

Rexx/gd Coordinate System

Function and type reference

Image creation, destruction, loading and saving

gdImageCreate(x, y)
gdImageCreate is called to create images. Invoke gdImageCreate with the x and y dimensions of the desired image. gdImageCreate returns an internal identifier to the new image, or "" if unable to allocate the image. Don't change the value of the returned value; bad things will happen! The image must eventually be destroyed using gdImageDestroy().
im = gdImageCreate(64, 64)
/* ... Use the image ... */
Call gdImageDestroy im
gdImageCreateTrueColor(x, y)
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 an internal identifier to the new image, or "" 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.

im = gdImageCreateTrueColor(64, 64)
/* ... Use the image ... */
Call gdImageDestroy im
gdImageCreateFromJpeg(filename)
gdImageCreateFromJpegPtr(data)
gdImageCreateFromJpeg is called to load truecolor images from JPEG format files. Invoke gdImageCreateFromJpeg with a file containing the desired image. gdImageCreateFromJpeg returns an internal identifier to the new truecolor image, or "" if unable to load the image (most often because the file is corrupt or does not contain a JPEG image). The image must eventually be destroyed using gdImageDestroy(). The returned image is always a truecolor image.

If you already have the image file in memory, pass the variable containing the file's data to gdImageCreateFromJpegPtr, which is otherwise identical to gdImageCreateFromJpeg.

im = gdImageCreateFromJpeg("myjpeg.jpg")
Say 'Image size:' gdImageGetWidth(im) 'x' gdImageGetHeight(im)
Call gdImageDestroy im
gdImageCreateFromPng(filename)
gdImageCreateFromPngPtr(data)
gdImageCreateFromPng is called to load images from PNG format files. Invoke gdImageCreateFromPng with a file containing the desired image. gdImageCreateFromPng returns an internal identifier to the new image, or "" if unable to load the image (most often because the file is corrupt or does not contain a PNG image). The image must eventually be destroyed using gdImageDestroy().

If you already have the image file in memory, pass the variable containing the file's data to gdImageCreateFromPngPtr, which is otherwise identical to gdImageCreateFromPng.

If the PNG image being loaded is a truecolor image, the resulting identifier will refer to a truecolor image. If the PNG image being loaded is a palette or grayscale image, the resulting identifier 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.

im = gdImageCreateFromPng("mypng.png")
Say 'Image size:' gdImageGetWidth(im) 'x' gdImageGetHeight(im)
Call gdImageDestroy im
gdImageCreateFromGif(filename)
gdImageCreateFromGifPtr(data)
gdImageCreateFromGif is called to load truecolor images from GIF format files. Invoke gdImageCreateFromGif with a file containing the desired image. gdImageCreateFromGif returns an internal identifier to the new image, or "" if unable to load the image (most often because the file is corrupt or does not contain a GIF image). The image must eventually be destroyed using gdImageDestroy().

If you already have the image file in memory, pass the variable containing the file's data to gdImageCreateFromGifPtr, which is otherwise identical to gdImageCreateFromGif.

im = gdImageCreateFromGif("mygif.gif")
Say 'Image size:' gdImageGetWidth(im) 'x' gdImageGetHeight(im)
Call gdImageDestroy im
gdImageCreateFromGd(filename)
gdImageCreateFromGdPtr(data)
gdImageCreateFromGd is called to load images from gd format files. Invoke gdImageCreateFromGd with 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.)

If you already have the image file in memory, pass the variable containing the file's data to gdImageCreateFromGdPtr, which is otherwise identical to gdImageCreateFromGd.

gdImageCreateFromGd returns an internal identifier to the new image, or "" if unable to load the image (most often because the file is corrupt or does not contain a gd format image). The image must eventually be destroyed using gdImageDestroy().

im = gdImageCreateFromGd("mygd.gd")
Say 'Image size:' gdImageGetWidth(im) 'x' gdImageGetHeight(im)
Call gdImageDestroy im
gdImageCreateFromGd2(filename)
gdImageCreateFromGd2Ptr(data)
gdImageCreateFromGd2 is called to load images from gd2 format files. Invoke gdImageCreateFromGd2 with 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.)

If you already have the image file in memory, pass the variable containing the file's data to gdImageCreateFromGd2Ptr, which is otherwise identical to gdImageCreateFromGd2.

gdImageCreateFromGd2 returns an internal idetifier to the new image, or "" if unable to load the image (most often because the file is corrupt or does not contain a gd format image). The image must eventually be destroyed using gdImageDestroy().

im = gdImageCreateFromGd2("mygd2.gd2")
Say 'Image size:' gdImageGetWidth(im) 'x' gdImageGetHeight(im)
Call gdImageDestroy im
gdImageCreateFromGd2Part(filename, srcX, srcY, width, height)
gdImageCreateFromGd2PartPtr(data, srcX, srcY, width, height)
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 (srcX, srcY) and dimensions( width, height) of the desired image. gdImageCreateFromGd2Part returns an internal identifier to the new image, or "" if unable to load the image. The image must eventually be destroyed using gdImageDestroy().

If you already have the image file in memory, you may use gdImageCreateFromGd2PartPtr. Pass the variable containing the image file data.

EXAMPLE ???
gdImageCreateFromWBMP(file)
gdImageCreateFromWBMPPtr(data)
gdImageCreateFromWBMP is called to load images from WBMP format files. Invoke gdImageCreateFromWBMP with a file containing the desired image. gdImageCreateFromWBMP returns an internal identifier to the new image, or "" if unable to load the image (most often because the file is corrupt or does not contain a WBMP image). The image must eventually be destroyed using gdImageDestroy().

If you already have the image file in memory, pass the variable containing the file's data to gdImageCreateFromWBMPPtr, which is otherwise identical to gdImageCreateFromWBMP.

im = gdImageCreateFromWBMP("mywbmp.bmp")
Say 'Image size:' gdImageGetWidth(im) 'x' gdImageGetHeight(im)
Call gdImageDestroy im
gdImageCreateFromXbm(filename)
gdImageCreateFromXbm is called to load images from X bitmap format files. Invoke gdImageCreateFromXbm with a file containing the desired image. gdImageCreateFromXbm returns an internal identifier to the new image, or "" if unable to load the image (most often because the file is corrupt or does not contain an X bitmap format image). The image must eventually be destroyed using gdImageDestroy().
im = gdImageCreateFromXbm("myxbm.xbm")
Say 'Image size:' gdImageGetWidth(im) 'x' gdImageGetHeight(im)
Call gdImageDestroy im
gdImageCreateFromXpm(filename)
gdImageCreateFromXpm is called to load images from X bitmap format files. Invoke gdImageCreateFromXpm with a file containing the desired image. gdImageCreateFromXpm returns an internal identifier to the new image, or "" if unable to load the image (most often because the file is corrupt or does not contain an X pixmap format image). The image must eventually be destroyed using gdImageDestroy().
im = gdImageCreateFromXpm("myxpm.xpm")
Say 'Image size:' gdImageGetWidth(im) 'x' gdImageGetHeight(im)
Call gdImageDestroy im
gdImageDestroy(im)
gdImageDestroy is used to free the memory associated with an image. It is important to invoke gdImageDestroy after finishing with the image.
im = gdImageCreate(10, 10)
/* ... Use the image ... */
/* Now destroy it */
Call gdImageDestroy im
gdImageJpeg(im, filename, jpeg_quality)
gdImageJpeg outputs the specified image to the specified file in JPEG format.

If jpeg_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.

/* 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)
/* Write JPEG using default quality */
Call gdImageJpeg im, "rect.jpg", -1
/* Destroy image */
Call gdImageDestroy im
gdImageGif(im, filename)
gdImageGif outputs the specified image to the specified file in GIF format.

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.

/* 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 */
Call gdImageRectangle im, 0, 0, 99, 99, black
/* Write GIF */
out = "rect.gif"
Call gdImageGif im, out
/* Destroy image */
Call gdImageDestroy im
gdImageGifAnimBegin(im, filename, GlobalCM, Loops)
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 calling gdImageGifAnimEnd.

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.



gdImageGifAnimAdd(im, filename, LocalCM, LeftOfs, TopOfs, Delay, Disposal, previm)
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.

/* Create the image */
im = gdImageCreate(100, 100)
/* Allocate background */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Allocate drawing color */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate transparent color for animation compression */
trans = gdImageColorAllocate(im, 1, 1, 1)
/* Draw rectangle */
Call gdImageRectangle im, 0, 0, 10, 10, black
out = "anim.gif"
/* Write GIF header.  Use global color map.  Loop a few times */
Call gdImageGifAnimBegin im, out, 1, 3
/* Write the first frame.  No local color map.  Delay = 1s */
Call gdImageGifAnimAdd im, out, 0, 0, 0, 100, 1, ""
/* construct the second frame */
im2 = gdImageCreate(100, 100)
/* Allocate background to make it white */
Call gdImageColorAllocate im2, 255, 255, 255
/* Make sure the palette is identical */
Call gdImagePaletteCopy im2, im
/* Draw something */
Call gdImageRectangle im2, 0, 0, 15, 15, black
/* Allow animation compression with transparent pixels */
Call gdImageColorTransparent im2, trans
/* Add the second frame */
Call gdImageGifAnimAdd im2, out, 0, 0, 0, 100, 1, im
/* construct the second frame */
im3 = gdImageCreate(100, 100)
/* Allocate background to make it white */
Call gdImageColorAllocate im3, 255, 255, 255
/* Make sure the palette is identical */
Call gdImagePaletteCopy im3, im
/* Draw something */
Call gdImageRectangle im3, 0, 0, 15, 20, black
/* Allow animation compression with transparent pixels */
Call gdImageColorTransparent im3, trans
/* Add the third frame, compressing against the second one */
Call gdImageGifAnimAdd im3, out, 0, 0, 0, 100, 1, im2
/* Write the end marker */
Call gdImageGifAnimEnd out
/* Destroy images */
Call gdImageDestroy im
Call gdImageDestroy im2
Call gdImageDestroy im3
gdImageGifAnimEnd(filename)
Writes semicolon character (;) to the output file. This terminates the GIF file properly.


gdImagePng(im, filename)
gdImagePng outputs the specified image to the specified file in PNG format.
/* 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)
/* Write PNG file */
Call gdImagePng im, "rect.png"
/* Destroy image */
Call gdImageDestroy im
gdImagePngEx(im, filename, level)
Like gdImagePng, gdImagePngEx outputs the specified image to the specified file in PNG format. 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.

For more information, see gdImagePng.



gdImageWBMP(im, fg, filename)
gdImageWBMP outputs the specified image to the specified file in WBMP format.

WBMP file support is black and white only. The color index specified by the fg argument is the "foreground," and only pixels of this color will be set in the WBMP file. All other pixels will be considered "background."

/* 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)
/* Write PNG file */
Call gdImageWBMP im, "rect.wbmp", black
/* Destroy image */
Call gdImageDestroy im
gdImageGd(im, filename)
gdImageGd outputs the specified image to the specified file in the gd image format.

The gd image format is intended for fast reads and writes of images your program will need frequently to build other images. It is not a compressed format, and is not intended for general use.

/* 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)
/* Write PNG file */
Call gdImageGd im, "rect.gd", black
/* Destroy image */
Call gdImageDestroy im
gdImageGd2(im, filename, chunkSize, fmt)
gdImageGd2 outputs the specified image to the specified file in the gd2 image format.

The gd2 image format is intended for fast reads and writes of parts of images. It is a compressed format, and well suited to retrieving small sections of much larger images.

The file is stored as a series of compressed subimages, and the chunkSize determines the sub-image size - a value of zero causes the GD library to use the default.

It is also possible to store GD2 files in an uncompressed format, in which case the fmt should be GD2RAW. To store GD2 files in compressed format specify GD2COMPRESSED for fmt.

/* 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)
/* Write PNG file */
Call gdImageGd im, "rect.gd", 0, "GD2COMPRESSED"
/* Destroy image */
Call gdImageDestroy im
gdImageTrueColorToPalette(im, ditherFlag, colorsWanted)
gdImageCreatePaletteFromTrueColor(im, ditherFlag, colorsWanted)
gdImageCreatePaletteFromTrueColor returns a new image. gdImageTrueColorToPalette permanently converts the existing image. The two functions are otherwise identical.

The function converts a truecolor image to a palette-based image, using a high-quality two-pass quantization routine. If ditherFlag is set, the image will be dithered to approximate colors better, at the expense of some obvious "speckling." colorsWanted can be anything up to 256. If the original source image includes photographic information or anything that came out of a JPEG, 256 is strongly recommended. 100% transparency of a single transparent color in the original truecolor image will be preserved. There is no other support for preservation of alpha channel or transparency in the destination image.

For best results, don't use this function -- write real truecolor PNGs and JPEGs. The disk space gain of conversion to palette is not great (for small images it can be negative) and the quality loss is ugly. However, the version of this function included in version 2.0.12 and later does do a better job than the version included prior to 2.0.12.



Drawing Functions

gdImageSetPixel(im, x, y, color)
gdImageSetPixel sets the pixel at coordinates x/y to a particular color index.
im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Set a pixel near the center. */
Call gdImageSetPixel im, 50, 50, white
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageLine(im, x1, y1, x2, y2, color)
gdImageLine is used to draw a line between two endpoints (x1,y1 and x2,y2). The line is drawn using the color index specified. Note that the color index can be an actual color returned by gdImageColorAllocate or one of GDSTYLED, GDBRUSHED, or GDSTYLEDBRUSHED.
im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Draw a line from the upper left corner to the lower right corner. */
Call gdImageLine im, 0, 0, 99, 99, white
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImagePolygon(im, xpoints, ypoints, color)
gdImagePolygon is used to draw a polygon with the verticies (at least 3) specified, using the color index specified. The vertices are specified by the xpoints and ypoints parameters which must be stem variable names that contain the x and y coordinates respectively. The stems must be valid Rexx arrays; ie xpoints.0 and ypoints.0 are set to the number of entries in each array, and they must both be the same value. See also gdImageFilledPolygon.
im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Draw a triangle. */
x.0 = 3; x.1 = 50; x.2 = 99; x.3 = 0;
y.0 = 3; y.1 = 0;  y.2 = 99; y.3 = 99;
Call gdImagePolygon im, 'x.', 'y.', white
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageOpenPolygon(im, xpoints, ypoints, color)
gdImageOpenPolygon is used to draw a sequence of lines with the verticies (at least 3) specified, using the color index specified. Unlike gdImagePolygon, the enpoints of the line sequence are not connected to a closed polygon.


gdImageRectangle(im, x1, y1, x2, y2, color)
gdImageRectangle is used to draw a rectangle with the two corners (upper left first, then lower right) specified, using the color index specified.
im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Draw a rectangle occupying the central area. */
Call gdImageRectangle im, 25, 25, 74, 74, white
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageFilledPolygon(im, xpoints, ypoints, color)
gdImageFilledPolygon is used to fill a polygon with the verticies (at least 3) specified, using the color index specified. See gdImagePolygon for details on how to pass the vertices.
im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
red = gdImageColorAllocate(im, 255, 0, 0)
/* Draw a triangle. */
x.0 = 3; x.1 = 50; x.2 = 99; x.3 = 0;
y.0 = 3; y.1 = 0;  y.2 = 99; y.3 = 99;
/* Paint it in white */
Call gdImageFilledPolygon im, 'x.', 'y.', white
/* Outline it in red; must be done second */
Call gdImagePolygon im, 'x.', 'y.', red
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageFilledRectangle(im, x1, y1, x2, y2, color)
gdImageFilledRectangle is used to draw a solid rectangle with the two corners (upper left first, then lower right) specified, using the color index specified.
im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Draw a rectangle occupying the central area. */
Call gdImageRectangle im, 25, 25, 74, 74, white
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageArc(im, x, y, width, height, start, end, color)
gdImageArc is used to draw a partial ellipse centered at the given point, specified by x and y, with the specified width and height in pixels. The arc begins at the position in degrees specified by start and ends at the position specified by end. The arc is drawn in the color specified by the last argument. A circle can be drawn by beginning from 0 degrees and ending at 360 degrees, with width and height being equal. end must be greater than start. Values greater than 360 are interpreted modulo 360.
im = gdImageCreate(100, 50)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Inscribe an ellipse in the image. */
Call gdImageArc im, 50, 25, 98, 48, 0, 360, white
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageFilledArc(im, x, y, width, height, start, end, color, style)
gdImageFilledArc is used to draw a partial ellipse centered at the given point, specified by x and y, with the specified width and height in pixels. The arc begins at the position in degrees specified by start and ends at the position specified by end. The arc is filled in the color specified by the second to last argument. A circle can be drawn by beginning from 0 degrees and ending at 360 degrees, with width and height being equal. e must be greater than s. Values greater than 360 are interpreted modulo 360. The last argument is a bitwise OR of the following possibilities: GDARC and GDCHORD are mutually exclusive; GDCHORD just connects the starting and ending angles with a straight line, while GDARC produces a rounded edge. GDPIE is a synonym for GDARC. GDNOFILL indicates that the arc or chord should be outlined, not filled. GDEDGED, used together with GDNOFILL, indicates that the beginning and ending angles should be connected to the center; this is a good way to outline (rather than fill) a 'pie slice'.
im = gdImageCreate(100, 50)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Inscribe a filled pie slice in the image. */
Call gdImageFilledArc im, 50, 25, 98, 48, 0, 45, white, 'GDARC'
/* ... Do something with the image, such as
  saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageFilledEllipse(im, x, y, width, height, color)
gdImageFilledEllipse is used to draw an ellipse centered at the given point, specified by x and y, with the specified width and height in pixels. The ellipse is filled in the color specified by the last argument.
im = gdImageCreate(100, 50)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Inscribe a filled ellipse in the image. */
Call gdImageFilledEllipse im, 50, 25, 98, 48, white
/* ... Do something with the image, such as
  saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageFillToBorder(im, x, y, border, color)
gdImageFillToBorder floods a portion of the image with the specified color, beginning at the specified point and stopping at the specified border color. For a way of flooding an area defined by the color of the starting point, see gdImageFill.

The border color cannot be a special color such as GDTILED; it must be a proper solid color. The fill color can be, however.

Note that gdImageFillToBorder is recursive. It is not the most naive implementation possible, and the implementation is expected to improve, but there will always be degenerate cases in which the stack can become very deep. This can be a problem in MSDOS and MS Windows 3.1 environments. (Of course, in a Unix or Windows 95/98/NT environment with a proper stack, this is not a problem at all.)

im = gdImageCreate(100, 50)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 25, 255)
/* Allocate the color red. */
red = gdImageColorAllocate(im, 255, 0, 0)
/* Inscribe an ellipse in the image. */
Call gdImageArc im, 50, 25, 98, 48, 0, 360, white
/* Flood-fill the ellipse. Fill color is red, border color is
  white (ellipse). */
Call gdImageFillToBorder im, 50, 50, white, red
/* ... Do something with the image, such as
  saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageFill(im, x, y, color)
gdImageFill floods a portion of the image with the specified color, beginning at the specified point given by x and y and flooding the surrounding region of the same color as the starting point. For a way of flooding a region defined by a specific border color rather than by its interior color, see gdImageFillToBorder.

The fill color can be GDTILED, resulting in a tile fill using another image as the tile. However, the tile image cannot be transparent. If the image you wish to fill with has a transparent color index, call gdImageTransparent on the tile image and set the transparent color index to -1 to turn off its transparency.

Note that gdImageFill is recursive. It is not the most naive implementation possible, and the implementation is expected to improve, but there will always be degenerate cases in which the stack can become very deep. This can be a problem in MSDOS and MS Windows environments. (Of course, in a Unix or Windown 96/98/NT environment with a proper stack, this is not a problem at all.)

im = gdImageCreate(100, 50)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Allocate the color red. */
red = gdImageColorAllocate(im, 255, 0, 0)
/* Inscribe an ellipse in the image. */
Call gdImageArc im, 50, 25, 98, 48, 0, 360, white
/* Flood-fill the ellipse. Fill color is red, and will replace the
   black interior of the ellipse. */
Call gdImageFill im, 50, 50, red;
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageSetAntiAliased(im, color)
"Antialiasing" is a process by which jagged edges associated with line drawing can be reduced by blending the foreground color with an appropriate percentage of the background, depending on how much of the pixel in question is actually within the boundaries of the line being drawn. All line-drawing functions, such as gdImageLine, gdImageOpenPolygon and gdImagePolygon, will draw antialiased lines if the special "color" gdAntiAliased is used when calling them.

gdImageSetAntiAliased is used to specify the actual foreground color to be used when drawing antialiased lines. You may set any color to be the foreground, however as of version 2.0.12 an alpha channel component is not supported.

Antialiased lines can be drawn on both truecolor and palette-based images. However, attempts to draw antialiased lines on highly complex palette-based backgrounds may not give satisfactory results, due to the limited number of colors available in the palette. Antialiased line-drawing on simple backgrounds should work well with palette-based images; otherwise create or fetch a truecolor image instead.

You need not take any special action when you are finished with antialised line drawing.

im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
blue = gdImageColorAllocate(im, 0, 0, 255)
Call gdImageSetAntiAliased im, blue
/* Draw a smooth line from the upper left corner to the
  lower right corner. */
Call gdImageLine im, 0, 0, 99, 99, "GDANTIALIASED"
/* ... Do something with the image, such as
  saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
See also gdAntiAliased and gdSetAntiAliasedDontBlend.

gdImageSetAntiAliasedDontBlend(im, color)
Normally, when drawing lines with the special gdAntiAliased "color," blending with the background to reduce jagged edges is the desired behavior. However, when it is desired that lines not be blended with one particular color when it is encountered in the background, the gdImageSetAntiAliasedDontBlend function can be used to indicate the special color that the foreground should stand out more clearly against.
im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
blue = gdImageColorAllocate(im, 0, 0, 255)
white = gdImageColorAllocate(im, 255, 255, 255)

Call gdImageSetAntiAliased im, blue
/* The portion of the line that crosses this white rectangle will
  not be blended smoothly */
Call gdImageSetAntiAliasedDontBlend im, white
Call gdImageFilledRectangle im, 25, 25, 75, 75, white
/* Draw a smooth line from the upper left corner
  to the lower right corner. */
Call gdImageLine im, 0, 0, 99, 99, "GDANTIALIASED"
/* ... Do something with the image, such as
  saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
See also gdAntiAliased and gdSetAntiAliased.

gdImageSetBrush(im, brush)
A "brush" is an image used to draw wide, shaped strokes in another image. Just as a paintbrush is not a single point, a brush image need not be a single pixel. Any gd image can be used as a brush, and by setting the transparent color index of the brush image with gdImageColorTransparent, a brush of any shape can be created. All line-drawing functions, such as gdImageLine and gdImageOpenPolygon and gdImagePolygon, will use the current brush if the special color; GDSTYLED or GDSTYLEDBRUSHED is used when calling them.

gdImageSetBrush is used to specify the brush to be used in a particular image. You can set any image to be the brush. If the brush image does not have the same color map as the first image, any colors missing from the first image will be allocated. If not enough colors can be allocated, the closest colors already available will be used. This allows arbitrary PNGs to be used as brush images. It also means, however, that you should not set a brush unless you will actually use it; if you set a rapid succession of different brush images, you can quickly fill your color map, and the results will not be optimal.

You need not take any special action when you are finished with a brush. As for any other image, if you will not be using the brush image for any further purpose, you should call gdImageDestroy. You must not use the color GDBRUSHED if the current brush has been destroyed; you can of course set a new brush to replace it.

im = gdImageCreate(100, 100)
/* Open the brush PNG. For best results, portions of the
   brush that should be transparent (ie, not part of the
   brush shape) should have the transparent color index. */
brush = gdImageCreateFromPng("star.png")
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
Call gdImageSetBrush im, brush
/* Draw a line from the upper left corner to the lower right corner
   using the brush. */
Call gdImageLine im, 0, 0, 99, 99, "GDBRUSHED"
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
/* Destroy the brush image */
Call gdImageDestroy brush
gdImageSetTile(im, tile)
A "tile" is an image used to fill an area with a repeated pattern. Any gd image can be used as a tile, and by setting the transparent color index of the tile image with gdImageColorTransparent, a tile that allows certain parts of the underlying area to shine through can be created. All region-filling functions, such as gdImageFill and gdImageFilledPolygon, will use the current tile if the special color GDTILED is used when calling them.

gdImageSetTile is used to specify the tile to be used in a particular image. You can set any image to be the tile. If the tile image does not have the same color map as the first image, any colors missing from the first image will be allocated. If not enough colors can be allocated, the closest colors already available will be used. This allows arbitrary PNGs to be used as tile images. It also means, however, that you should not set a tile unless you will actually use it; if you set a rapid succession of different tile images, you can quickly fill your color map, and the results will not be optimal.

You need not take any special action when you are finished with a tile. As for any other image, if you will not be using the tile image for any further purpose, you should call gdImageDestroy. You must not use the color GDTILED if the current tile has been destroyed; you can of course set a new tile to replace it.

im = gdImageCreate(100, 100)
   /* Open the tile PNG. For best results, portions of the
   tile that should be transparent (ie, allowing the
   background to shine through) should have the transparent
   color index. */
tile = gdImageCreateFromPng("star.png")
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
Call gdImageSetTile im, tile
/* Fill an area using the tile. */
Call gdImageFilledRectangle im, 25, 25, 75, 75, "GDTILED"
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
/* Destroy the tile image */
Call gdImageDestroy tile
gdImageSetStyle(im, style)
It is often desirable to draw dashed lines, dotted lines, and other variations on a broken line. gdImageSetStyle can be used to set any desired series of colors, including a special color that leaves the background intact, to be repeated during the drawing of a line.

To use gdImageSetStyle, create an array of colors to be repeated. You can assign the special color value; GDTRANSPARENT to indicate that the existing color should be left unchanged for that particular pixel (allowing a dashed line to be attractively drawn over an existing image).

Then, to draw a line using the style, use the normal gdImageLine function with the special color value; GDSTYLED.

You can also combine styles and brushes to draw the brush image at intervals instead of in a continuous stroke. When creating a style for use with a brush, the style values are interpreted differently: zero (0) indicates pixels at which the brush should not be drawn, while one (1) indicates pixels at which the brush should be drawn. To draw a styled, brushed line, you must use the special color value; GDSTYLEDBRUSHED. For an example of this feature in use, see rexxgddemo.rexx (provided in the distribution).

im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
red = gdImageColorAllocate(im, 255, 0, 0)
/* Set up dotted style. Leave every other pixel alone. */
styledotted.1 = red
styledotted.2 = "GDTRANSPARENT"
styledotted.0 = 2
/* Set up dashed style. Three on, three off. */
styledashed.1 = red
styledashed.2 = red
styledashed.3 = red
styledashed.4 = "GDTRANSPARENT"
styledashed.5 = "GDTRANSPARENT"
styledashed.6 = "GDTRANSPARENT"
styledashed.0 = 6
/* Set dotted style. Note that we have to specify how many pixels are
   in the style! */
Call gdImageSetStyle im, "STYLEDOTTED."
/* Draw a line from the upper left corner to the lower right corner. */
Call gdImageLine im, 0, 0, 99, 99, "GDSTYLED"
/* Now the dashed line. */
Call gdImageSetStyle(im, "STYLEDASHED."
Call gdImageLine im, 0, 99, 0, 99, "GDSTYLED"

/* ... Do something with the image, such as saving it to a file ... */

/* Destroy it */
Call gdImageDestroy im
gdImageSetThickness(im, thickness)
gdImageSetThickness determines the width of lines drawn by the gdImageLine, gdImagePolygon, gdImageOpenPolygon and related functions, in pixels.
im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Set thickness. */
Call gdImageSetThickness im, 4
/* Draw a fat line from the upper left corner to the lower right corner. */
Call gdImageLine im, 0, 0, 99, 99, white
/* ... Do something with the image, such as
  saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageAlphaBlending(im, blending)
The gdImageAlphaBlending function allows for two different modes of drawing on truecolor images. In blending mode, which is on by default (gd 2.0.2 and above), the alpha channel component of the color supplied to all drawing functions, such as gdImageSetPixel, determines how much of the underlying color should be allowed to shine through. As a result, gd automatically blends the existing color at that point with the drawing color, and stores the result in the image. The resulting pixel is opaque. In non-blending mode, the drawing color is copied literally with its alpha channel information, replacing the destination pixel. Blending mode is not available when drawing on palette images.
im = gdImageCreateTrueColor(100, 100)
/* Background color */
red = gdTrueColor(255, 0, 0)
Call gdImageFilledRectangle im, 0, 0, 100, 100, red
/* Drawing color. Full transparency would be an alpha channel value
  of 127 (gd has a 7 bit alpha chnanel). 0 is opaque,
  127 is transparent. So cut gdAlphaTransparent in half to get
  50% blending. */
blue = gdTrueColorAlpha(0, 0, 255, gdAlphaTransparent / 2)
/* Draw with blending. Result will be 50% red, 50% blue: yellow
  (emitted light, remember, not reflected light. What you learned
  in Kindergarten is wrong here). */
Call gdImageAlphaBlending im, 1
Call gdImageFilledRectangle im, 0, 0, 25, 25, blue
/* Draw without blending. Result will be 50% blue, 50%
  the background color of the image viewer or web browser
  used; results in browsers that don't support
  semi-transparent pixels are unpredictable! */
Call gdImageAlphaBlending im, 0
Call gdImageFilledRectangle im, 75, 75, 25, 25, blue
/* Write the image to disk, etc. */
gdImageSaveAlpha(im, saveFlag)
By default, gd 2.0.2 and above do not attempt to save full alpha channel information (as opposed to single-color transparency) when saving PNG images. (PNG is currently the only output format supported by gd which can accommodate alpa channel information.) This saves space in the output file. If you wish to create an image with alpha channel information for use with tools that support it, call gdImageSaveAlpha(im, 1) to turn on saving of such information, and call gdImageAlphaBlending(im, 0) to turn off alpha blending within the library so that alpha channel information is actually stored in the image rather than being composited immediately at the time that drawing functions are invoked.


gdImageSetClip(im, x1, y1, x2, y2)
Establishes a clipping rectangle. Once gdImageSetClip has been called, all future drawing operations will remain within the specified clipping area, until a new gdImageSetClip call takes place. For instance, if a clipping rectangle of 25, 25, 75, 75 has been set within a 100x100 image, a diagonal line from 0,0 to 99,99 will appear only between 25,25 and 75,75.

If gdImageSetClip is never called, the clipping area will be the entire image.

The parameters passed to gdImageSetClip are checked against the dimensions of the image and limited to "safe" values.

im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Set the clipping rectangle. */
Call gdImageSetClip im, 25, 25, 75, 75
/* Draw a line from the upper left corner to the lower right corner.
  Only the part within the clipping rectangle will appear. */
Call gdImageLine im, 0, 0, 99, 99, white
/* ... Do something with the image, such as
  saving it to a file ... */
/* Destroy it */
Call gdImageDestroy im
See also gdImageGetClip.

gdImageGetClip(im)
Fetches the boundaries of the current clipping rectangle. Returns 4 space delimited words as: x1 y1 x2 y2 coordinates.
im = gdImageCreateTrueColor(100, 100)
Call gdImageSetClip im, 25, 25, 75, 75
Parse Value gdImageGetClip(im) With x1 y1 x2 y2
Say 'Boundaries:' x1  y1 x2  y2
The above code would print:
25 25 75 75
See also gdImageSetClip.

Query Functions

gdImageAlpha(im, color)
gdImageAlpha returns the alpha channel component of the specified color index. Alpha channel values vary between 0 (GDALPHAOPAQUE), which does not blend at all with the background, through 127 (GDALPHATRANSPARENT), which allows the background to shine through 100%.


gdImageBlue(im, color)
gdImageBlue returns the blue component of the specified color.


gdImageGetPixel(im, x, y)
gdImageGetPixel retrieves the color index of a particular pixel at x,y.
im = gdImageCreateFromPng("mypng.png")
c = gdImageGetPixel(im, gdImageGetWidth(im) % 2, gdImageGetHeight(im) % 2)
Say "The value of the center pixel is" c
Say "RGB values are" gdImageColorRed(im,c)","gdImageColorGreen(im,c)","gdImageColorBlue(im,c)
Call gdImageDestroy im
gdImageBoundsSafe(im, x, y)
gdImageBoundsSafe returns 1 if the specified point is within the current clipping rectangle, 0 if not. The clipping rectangle is set by gdImageSetClip and defaults to the entire image. This function is intended primarily for use by those who wish to add functions to gd. All of the gd drawing functions already clip safely using this function.
If gdImageBoundsSafe(im, 50, 50) Then
   Say "50, 50 is within the image bounds"
Else
   Say "50, 50 is outside the image bounds"
Call gdImageDestroy im
gdImageGetWidth(im)
gdImageGetWidth returns the width of the image in pixels. It is the equivalent of the gd macro gdImageSX.


gdImageGetHeight(im)
gdImageGetHeight returns the height of the image in pixels. It is the equivalent of the gd macro gdImageSY.


gdImageGreen(im, color)
gdImageGreen returns the green component of the specified color. See gdImageBlue for an equivalent example.


gdImageRed(im, color)
gdImageRed returns the red component of the specified color. See gdImageBlue for an equivalent example.


Font and text-handling functions

gdFontGetHeight(font)
gdFontGetHeight returns the height in pixels of the specified font. font is one of 5 built-in, non-proportional fonts: GDFONTTINY, GDFONTSMALL, GDFONTMEDIUMBOLD, GDFONTLARGE, AND GDFONTGIANT.
Say "Large font is" gdFontGetHeight("GDFONTLARGE") "pixels high."
gdFontGetWidth(font)
gdFontGetWidth returns the height in pixels of the specified font. font is one of 5 built-in, non-proportional fonts: GDFONTTINY, GDFONTSMALL, GDFONTMEDIUMBOLD, GDFONTLARGE, AND GDFONTGIANT.
Say "Large font is" gdFontGetWidth("GDFONTLARGE") "pixels wide."
gdImageChar(im, font, x, y, ch, color)
gdImageChar is used to draw single characters on the image. (To draw multiple characters, use gdImageString or gdImageString16. See also gdImageStringFT for a high quality solution.) font is one of 5 built-in, non-proportional fonts: GDFONTTINY, GDFONTSMALL, GDFONTMEDIUMBOLD, GDFONTLARGE, AND GDFONTGIANT. The character specified by ch is drawn from left to right in the specified color. (See gdImageCharUp for a way of drawing vertical text.) Pixels not set by a particular character retain their previous color.
im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Draw a character. */
Call gdImageChar im, "GDFONTLARGE", 0, 0, 'Q', white
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageCharUp(im, font, x, y, ch, color)
gdImageCharUp is used to draw single characters on the image, rotated 90 degrees. (To draw multiple characters, use gdImageStringUp or gdImageStringUp16.) font is one of 5 built-in, non-proportional fonts: GDFONTTINY, GDFONTSMALL, GDFONTMEDIUMBOLD, GDFONTLARGE, AND GDFONTGIANT. The character specified by ch is drawn from bottom to top, rotated at a 90-degree angle, in the specified color. (See gdImageChar for a way of drawing horizontal text.) Pixels not set by a particular character retain their previous color.
im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Draw a character upwards so it rests against the top of the image. */
Call gdImageCharUp(im, "GDFONTLARGE", 0, gdFontGetHeight("GDFONTLARGE"), 'Q', white
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageString(im, font, x, y, string, color)
gdImageString is used to draw multiple characters on the image. (To draw single characters, use gdImageChar.) font is one of 5 built-in, non-proportional fonts: GDFONTTINY, GDFONTSMALL, GDFONTMEDIUMBOLD, GDFONTLARGE, AND GDFONTGIANT. string is drawn from left to right in the specified color. (See gdImageStringUp for a way of drawing vertical text. See also gdImageStringTTF. Pixels not set by a particular character retain their previous color.
/* String to draw. */
string = "Hello."
/* Font to use */
font = "GDFONTLARGE"
im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Draw a centered string. */
Call gdImageString(im, font,
 gdImageGetWidth(im) % 2 - ( Length(string) * gdFontGetWidth(font) % 2 ),
 gdImageGetHeight(im) % 2 - gdFontGetHeight(font) % 2,
 string, white)
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageString16(im, font, x, y, string, color)
gdImageString16 is used to draw multiple 16-bit characters on the image. (To draw single characters, use gdImageChar.) font is one of 5 built-in, non-proportional fonts: GDFONTTINY, GDFONTSMALL, GDFONTMEDIUMBOLD, GDFONTLARGE, AND GDFONTGIANT. The contents of the string stem representing 16-bit numbers, is drawn from left to right in the specified color. (See gdImageStringUp16 for a way of drawing vertical text.) Pixels not set by a particular character retain their previous color.

This function provides a means of rendering fonts with more than 256 characters for those who have them. A more frequently used routine is gdImageString.



gdImageStringUp(im, font, x, y, string, color)
gdImageStringUp is used to draw multiple characters on the image, rotated 90 degrees. (To draw single characters, use gdImageCharUp.) font is one of 5 built-in, non-proportional fonts: GDFONTTINY, GDFONTSMALL, GDFONTMEDIUMBOLD, GDFONTLARGE, AND GDFONTGIANT. string is drawn from bottom to top (rotated 90 degrees) in the specified color. (See gdImageString for a way of drawing horizontal text.) Pixels not set by a particular character retain their previous color.
/* String to draw. */
string = "Hello."
/* Font to use */
font = "GDFONTLARGE"
im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color white (red, green and blue all maximum). */
white = gdImageColorAllocate(im, 255, 255, 255)
/* Draw a centered string. */
Call gdImageStringUp(im, font,
 gdImageGetWidth(im) % 2 - ( Length(string) * gdFontGetWidth(font) % 2 ),
 gdImageGetHeight(im) % 2 - gdFontGetHeight(font) % 2,
 string, white)
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageStringUp16(im, font, x, y, string, color)
gdImageString is used to draw multiple 16-bit characters vertically on the image. (To draw single characters, use gdImageChar.) font is one of 5 built-in, non-proportional fonts: GDFONTTINY, GDFONTSMALL, GDFONTMEDIUMBOLD, GDFONTLARGE, AND GDFONTGIANT. The contents of the string stem representing 16-bit numbers, is drawn from bottom up in the specified color. (See gdImageStringUp16 for a way of drawing horizontal text.) Pixels not set by a particular character retain their previous color.

This function provides a means of rendering fonts with more than 256 characters for those who have them. A more frequently used routine is gdImageStringUp.



gdImageStringFT(im, brect, color, fontname, ptsize, angle, x, y, string)
gdImageStringFT draws a string of anti-aliased characters on the image using the FreeType library to render user-supplied TrueType fonts. We do not provide TrueType fonts (.ttf and .ttc files). Obtaining them is entirely up to you. The string is anti-aliased, meaning that there should be fewer "jaggies" visible. The fontname is the full pathname to a TrueType font file, or a font face name if the GDFONTPATH environment variable has been set intelligently. In the absence of a full path, the font face name may be presented with or without extension (2.0.26).

The string argument is considered to be encoded via the UTF_8 standard; also, HTML entities are supported, including decimal, hexadecimal, and named entities (2.0.26). Those who are passing ordinary ASCII strings may have difficulty with the & character unless encoded correctly as & but should have no other difficulties.

The string may be arbitrarily scaled ptsize and rotated (angle in radians). The direction of rotation is counter-clockwise, with 0 radians (0 degrees) at 3 o'clock and PI/2 radians (90 degrees) at 12 o'clock.

On return, gdImageStringFT returns "" if successful, or an error string if unsuccessful. The brect array is filled on return from gdImageStringFT with the 8 elements representing the 4 corner coordinates of the bounding rectangle:

brect.1 lower left corner, X position
brect.2 lower left corner, Y position
brect.3 lower right corner, X position
brect.4 lower right corner, Y position
brect.5 upper right corner, X position
brect.6 upper right corner, Y position
brect.7 upper left corner, X position
brect.8 upper left corner, Y position

The points are relative to the text regardless of the angle, so "upper left" means in the top left-hand corner seeing the text horizontally.

Use an empty argument for im to get the bounding rectangle without rendering. This is a relatively cheap operation if followed by a rendering of the same string, because of the caching of the partial rendering during bounding rectangle calculation.

The string is rendered in the color indicated. Use the negative of the desired color index to disable anti-aliasing.

The string may contain UTF-8 sequences like: "À"

string = "Hello." /* String to draw. */
size = 40
fontname = "/usr/local/share/ttf/Times.ttf"  /* User supplied font */

/* obtain brect so that we can size the image */
err = gdImageStringFT( ,"brect.",0,fontname,size,0,0,0,string)
If err \= "" Then
   Do
      Say "Error with gdImageStringFT():" err
      return 1
   End
/* create an image big enough for the string plus a little whitespace */
x = brect.3-brect.7 + 6
y = brect.4-brect.8 + 6
im = gdImageCreate(x,y)

/* Background color (first allocated) */
white = gdImageColorResolve(im, 255, 255, 255)
black = gdImageColorResolve(im, 0, 0, 0)

/* render the string, offset origin to center string*/
/* note that we use top-left coordinate for adjustment
 * since gd origin is in top-left with y increasing downwards. */
x = 3 - brect.7
y = 3 - brect.8
err = gdImageStringFT(im,"brect.",black,fontname,size,0,x,y,string)
If err \= "" Then
   Do
      Say "Error with gdImageStringFT():" err
      return 1
   End

/* Save image */
Call gdImagePng im, "mypng.png"

/* Destroy it */
Call gdImageDestroy im
gdImageStringFTCircle( im, cx, cy, radius, textRadius, fillPortion, font, points, top, bottom, fgcolor)
Draws the text strings specified by top and bottom on im, curved along the edge of a circle of radius radius, with its center at cx and cy. top is written clockwise along the top; bottom is written counterclockwise along the bottom. textRadius determines the "height" of each character; if textRadius is 1/2 of radius, characters extend halfway from the edge to the center. fillPortion varies from 0 to 1.0, with useful values from about 0.4 to 0.9, and determines how much of the 180 degrees of arc assigned to each section of text is actually occupied by text; 0.9 looks better than 1.0 which is rather crowded. font is a freetype font; see gdImageStringFT. points is passed to the freetype engine and has an effect on hinting; although the size of the text is determined by radius, textRadius, and fillPortion, you should pass a point size that "hints" appropriately -- if you know the text will be large, pass a large point size such as 24.0 to get the best results. fgcolor can be any color, and may have an alpha component, do blending, etc.

Returns 0 on success, or an error string otherwise.

/* Create an image of text on a circle, with an
   alpha channel so that we can copy it onto a
   background */
in = "mypicture.jpg"
If Stream( in, 'C', 'QUERY EXISTS' ) = '' Then
   im = gdImageCreateTrueColor(300, 300)
Else
   im = gdImageCreateFromJpeg(in)
If gdImageGetWidth(im) < gdImageGetHeight(im) Then
   radius = gdImageGetWidth(im) / 2
Else
   radius = gdImageGetHeight(im) / 2
Call gdImageStringFTCircle im, gdImageGetWidth(im) / 2,  gdImageGetHeight(im) / 2, ,
     radius, radius / 2, 0.8, "arial", 24, "top text", "bottom text",  ,
     gdTrueColorAlpha(240, 240, 255, 32)
out = "gdfx.png"
Call gdImagePng im, out
Call gdImageDestroy im
return 0
For more information, see gdImageSquareToCircle.

gdImageStringTTF(im, brect, color, fontname, ptsize, angle, x, y, string)
DEPRECATED. This function simply invokes gdImageStringFT for backwards compatibility with old code that was written with FreeType 1.x.

Color-handling functions

gdImageColorAllocate(im, r, g, b)
gdImageColorAllocate finds the first available color index in the image specified, sets its RGB values to those requested by r,g and b; (255 is the maximum for each), and returns the index of the new color table entry, or an RGBA value in the case of a truecolor image; in either case you can then use the returned value as a parameter to drawing functions. When creating a new palette-based image, the first time you invoke this function, you are setting the background color for that image.

In the event that all gdMaxColors colors (256) have already been allocated, gdImageColorAllocate will return -1 to indicate failure. (This is not uncommon when working with existing PNG files that already use 256 colors.) Note that gdImageColorAllocate does not check for existing colors that match your request; see gdImageColorExact, gdImageColorClosest and gdImageColorClosestHWB for ways to locate existing colors that approximate the color desired in situations where a new color is not available. Also see gdImageColorResolve.

im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color red. */
red = gdImageColorAllocate(im, 255, 0, 0)
/* Draw a dashed line from the upper left corner to the lower right corner. */
Call gdImageLine im, 0, 0, 99, 99, red
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageColorAllocateAlpha(im, r, g, b, a)
gdImageColorAllocateAlpha finds the first available color index in the image specified, sets its RGBA values to those requested (255 is the maximum for red, green and blue, and 127 represents full transparency for alpha), and returns the index of the new color table entry, or an RGBA value in the case of a truecolor image; in either case you can then use the returned value as a parameter to drawing functions. When creating a new palette-based image, the first time you invoke this function, you are setting the background color for that image.

In the event that all gdMaxColors colors (256) have already been allocated, gdImageColorAllocate will return -1 to indicate failure. (This is not uncommon when working with existing palette-based PNG files that already use 256 colors.) Note that gdImageColorAllocateAlpha does not check for existing colors that match your request; see gdImageColorExactAlpha and gdImageColorClosestAlpha for ways to locate existing colors that approximate the color desired in situations where a new color is not available. Also see gdImageColorResolveAlpha.

im = gdImageCreate(100, 100)
/* Background color (first allocated) */
black = gdImageColorAllocate(im, 0, 0, 0)
/* Allocate the color red, 50% transparent. */
red = gdImageColorAllocateAlpha(im, 255, 0, 0, 64)
/* Draw a dashed line from the upper left corner to the lower right corner. */
Call gdImageDashedLine im, 0, 0, 99, 99, red
/* ... Do something with the image, such as
  saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageColorClosest(im, r, g, b)
gdImageColorClosest searches the colors which have been defined thus far in the image specified and returns the index of the color with RGB values closest to those specified by r,g and b. (Closeness is determined by Euclidian distance, which is used to determine the distance in three-dimensional color space between colors.)

If no colors have yet been allocated in the image, gdImageColorClosest returns -1.

When applied to a truecolor image, this function always succeeds in returning the desired color.

This function is most useful as a backup method for choosing a drawing color when an image already contains gdMaxColors (256) colors and no more can be allocated. (This is not uncommon when working with existing PNG files that already use many colors.) See gdImageColorExact for a method of locating exact matches only.

/* Let's suppose that photo.png is a scanned photograph with
   many colors. */
im = gdImageCreateFromPng("photo.png");
/* Try to allocate red directly */
red = gdImageColorAllocate(im, 255, 0, 0)
/* If we fail to allocate red... */
If  red = -1 Then
   Do
      /* Find the closest color instead. */
      red = gdImageColorClosest(im, 255, 0, 0)
   End
/* Draw a line from the upper left corner to the lower right corner */
Call gdImageLine im, 0, 0, 99, 99, red
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageColorClosestAlpha(im, r, g, b, a)
gdImageColorClosest searches the colors which have been defined thus far in the image specified and returns the index of the color with RGBA values closest to those of the request. (Closeness is determined by Euclidian distance, which is used to determine the distance in four-dimensional color/alpha space between colors.)

If no colors have yet been allocated in the image, gdImageColorClosestAlpha returns -1.

When applied to a truecolor image, this function always succeeds in returning the desired color.

This function is most useful as a backup method for choosing a drawing color when a palette-based image already contains gdMaxColors (256) colors and no more can be allocated. (This is not uncommon when working with existing palette-based PNG files that already use many colors.) See gdImageColorExactAlpha for a method of locating exact matches only.

/* Let's suppose that photo.png is a scanned photograph with
  many colors. */
in = "photo.png"
im = gdImageCreateFromPng(in)
/* Try to allocate red, 50% transparent, directly */
red = gdImageColorAllocateAlpha(im, 255, 0, 0, 64)
/* If we fail to allocate red... */
If red = -1 Then
  /* Find the closest color instead. */
  red = gdImageColorClosestAlpha(im, 255, 0, 0, 64)
}
/* Draw a dashed line from the upper left corner to the lower right corner */
Call gdImageDashedLine im, 0, 0, 99, 99, red
/* ... Do something with the image, such as
  saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageColorClosestHWB(im, r, g, b)
gdImageColorClosestHWB searches the colors which have been defined thus far in the image specified and returns the index of the color with hue, whiteness and blackness closest to the color specified by by r,g and b. This scheme is typically superior to the Euclidian distance scheme used by gdImageColorClosest.

If no colors have yet been allocated in the image, gdImageColorClosestHWB returns -1.

When applied to a truecolor image, this function always succeeds in returning the desired color.

This function is most useful as a backup method for choosing a drawing color when an image already contains gdMaxColors (256) colors and no more can be allocated. (This is not uncommon when working with existing PNG files that already use many colors.) See gdImageColorExact for a method of locating exact matches only.

/* Let's suppose that photo.png is a scanned photograph with
   many colors. */
im = gdImageCreateFromPng("photo.png")
/* Try to allocate red directly */
red = gdImageColorAllocate(im, 255, 0, 0)
/* If we fail to allocate red... */
If red = -1 Then
   Do
      /* Find the closest color instead. */
      red = gdImageColorClosestHWB(im, 255, 0, 0)
   End
/* Draw a line from the upper left corner to the lower right corner */
Call gdImageLine im, 0, 0, 99, 99, red
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageColorExact(im, r, g, b)
gdImageColorExact searches the colors which have been defined thus far in the image specified and returns the index of the first color with RGB values which exactly match those specified by r,g and b. If no allocated color matches the request precisely, gdImageColorExact returns -1. See gdImageColorClosest for a way to find the color closest to the color requested.

When applied to a truecolor image, this function always succeeds in returning the desired color.

im = gdImageCreateFromPng("photo.png")
/* The image may already contain red; if it does, we'll save a slot
   in the color table by using that color. */
/* See if red already exists */
red = gdImageColorExact(im, 255, 0, 0)
/* If red isn't already present... */
If red = -1 Then
   Do
      /* Second best: try to allocate it directly. */
      red = gdImageColorAllocate(im, 255, 0, 0)
      /* Out of colors, so find the closest color instead. */
      If red = -1 Then red = gdImageColorClosest(im, 255, 0, 0)
   End
/* Draw a line from the upper left corner to the lower right corner */
Call gdImageLine im, 0, 0, 99, 99, red
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageColorResolve(im, r, g, b)
gdImageColorResolve searches the colors which have been defined thus far in the image specified and returns the index of the first color with RGB values which exactly match those specified by r,g and b. If no allocated color matches the request precisely, then gdImageColorResolve tries to allocate the exact color. If there is no space left in the color table then gdImageColorResolve returns the closest color (as in gdImageColorClosest). This function always returns an index of a color.

When applied to a truecolor image, this function always succeeds in returning the desired color.

im = gdImageCreateFromPng("photo.png")
/* The image may already contain red; if it does, we'll save a slot
   in the color table by using that color. */
/* Get index of red, or color closest to red */
red = gdImageColorResolve(im, 255, 0, 0);
/* Draw a line from the upper left corner to the lower right corner */
Call gdImageLine im, 0, 0, 99, 99, red
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageColorResolveAlpha(im, r, g, b, a)
gdImageColorResolveAlpha searches the colors which have been defined thus far in the image specified and returns the index of the first color with RGBA values which exactly match those of the request. If no allocated color matches the request precisely, then gdImageColorResolveAlpha tries to allocate the exact color. If there is no space left in the color table then gdImageColorResolveAlpha returns the closest color (as in gdImageColorClosestAlpha). This function always returns an index of a color.

When applied to a truecolor image, this function always succeeds in returning the desired color.

in = "photo.png"
im = gdImageCreateFromPng(in)
/* The image may already contain red; if it does,
  we'll save a slot in the color table by using that color. */
/* Get index of red, 50% transparent, or the next best thing */
red = gdImageColorResolveAlpha(im, 255, 0, 0, 64)
/* Draw a dashed line from the upper left corner to the lower right corner */
Call gdImageDashedLine im, 0, 0, 99, 99, red
/* ... Do something with the image, such as saving
  it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageColorsTotal(im)
gdImageColorsTotal returns the number of colors currently allocated in a palette image. For truecolor images, the result of this call is undefined and should not be used.


gdImageGetInterlaced(im)
gdImageGetInterlaced returns 1 if the image is interlaced, 0 if not. See gdImageInterlace for a means of interlacing images.


gdImageGetTransparent(im)
gdImageGetTransparent returns the current transparent color index in the image. If there is no transparent color, gdImageGetTransparent returns -1.


gdImageColorDeallocate(im, color)
gdImageColorDeallocate marks the specified color as being available for reuse. It does not attempt to determine whether the color index is still in use in the image. After a call to this function, the next call to gdImageColorAllocate for the same image will set new RGB values for that color index, changing the color of any pixels which have that index as a result. If multiple calls to gdImageColorDeallocate are made consecutively, the lowest-numbered index among them will be reused by the next gdImageColorAllocate call.
im = gdImageCreateFromPng("photo.png")
/* Look for red in the color table. */
red = gdImageColorExact(im, 255, 0, 0)
/* If red is present... */
If red != -1 Then
   Do
      /* Deallocate it. */
      Call gdImageColorDeallocate im, red
      /* Allocate blue, reusing slot in table.
         Existing red pixels will change color. */
      blue = gdImageColorAllocate(im, 0, 0, 255)
   End
/* ... Do something with the image, such as saving it to a file... */
/* Destroy it */
Call gdImageDestroy im
gdImageColorTransparent(im, color)
gdImageColorTransparent sets the transparent color index for the specified image to the specified color index. To indicate that there should be no transparent color, invoke gdImageColorTransparent with a color index of -1. Note that JPEG images do not support transparency, so this setting has no effect when writing JPEG images.

The color index used should be an index allocated by gdImageColorAllocate, whether explicitly invoked by your code or implicitly invoked by loading an image. In order to ensure that your image has a reasonable appearance when viewed by users who do not have transparent background capabilities (or when you are writing a JPEG-format file, which does not support transparency), be sure to give reasonable RGB values to the color you allocate for use as a transparent color, even though it will be transparent on systems that support PNG transparency.

im = gdImageCreateFromPng("photo.png")
/* Look for black in the color table and make it transparent. */
black = gdImageColorExact(im, 0, 0, 0)
/* If black is present... */
If black != -1 Then
   Do
      /* Make it transparent */
      Call gdImageColorTransparent im, black
   End
/* Save the newly-transparent image back to the file */
Call gdImagePng im, "photo.png"
/* Destroy it */
Call gdImageDestroy im
gdImageTrueColor(im)
gdImageTrueColor returns the true color from a truecolor image. This should not be used with palette-based images. If you need to write code which is compatible with both palette-based and truecolor images, use gdImageColorResolve.

gdTrueColorAlpha(red, green, blue, alpha)
gdTrueColorAlpha returns an RGBA color value for use when drawing on a truecolor image with alpha channel transparency. Red, green, and blue are all in the range between 0 (off) and 255 (maximum). Alpha is in the range between 0 (opaque) and 127 (fully transparent). This should not be used with palette-based images. If you need to write code which is compatible with both palette-based and truecolor images, use gdImageColorResolveAlpha.

Copying and resizing functions

gdImageCopy(dst, src, dstX, dstY, srcX, srcY, width, height)
gdImageCopy is used to copy a rectangular portion of one image (src) to another image (dst). (For a way of stretching or shrinking the image in the process, see gdImageCopyResized.)

dstX and dstY arguments specify the point in the destination image to which the region will be copied. The srcX and srcY arguments specify the upper left corner of the region in the source image. The width and height arguments specify the width and height of the region.

When you copy a region from one location in an image to another location in the same image, gdImageCopy will perform as expected unless the regions overlap, in which case the result is unpredictable.

Important note on copying between images: since different images do not necessarily have the same color tables, pixels are not simply set to the same color index values to copy them. gdImageCopy will attempt to find an identical RGB value in the destination image for each pixel in the copied portion of the source image by invoking gdImageColorExact. If such a value is not found, gdImageCopy will attempt to allocate colors as needed using gdImageColorAllocate. If both of these methods fail, gdImageCopy will invoke gdImageColorClosest to find the color in the destination image which most closely approximates the color of the pixel being copied.

/* Load a small png to tile the larger one with */
im_in = gdImageCreateFromPng("small.png")
/* Get size of im_in for later use */
in_x = gdImageGetWidth(im_in)
in_y = gdImageGetHeight(im_in)
/* Make the output image four times as large on both axes */
im_out = gdImageCreate(in_x * 4, in_y * 4)
/* Now tile the larger image using the smaller one */
Do y = 0 To 3
   Do x = 0 To 3
      Call gdImageCopy im_out, im_in, x * in_x, y * in_y, 0, 0, in_x, in_y
   End
End
Call gdImagePng im_out, "tiled.png"
Call gdImageDestroy im_in
Call gdImageDestroy im_out
void gdImageCopyResized(dst, src, dstX, dstY, srcX, srcY, dstW, dstH, srcW, srcH)
gdImageCopyResized is used to copy a rectangular portion of one image (src) to another image (dst). The X and Y dimensions of the original region and the destination region can vary, resulting in stretching or shrinking of the region as appropriate. (For a simpler version of this function which does not deal with resizing, see gdImageCopy.)

The dstX and dstY arguments specify the point in the destination image to which the region will be copied. The srcX and srcY arguments specify the upper left corner of the region in the source image. The dstW and dstH arguments specify the width and height of the destination region. The srcW and srcH arguments specify the width and height of the source region and can differ from the destination size, allowing a region to be scaled during the copying process.

When you copy a region from one location in an image to another location in the same image, gdImageCopy will perform as expected unless the regions overlap, in which case the result is unpredictable. If this presents a problem, create a scratch image in which to keep intermediate results.

Important note on copying between images: since images do not necessarily have the same color tables, pixels are not simply set to the same color index values to copy them. gdImageCopy will attempt to find an identical RGB value in the destination image for each pixel in the copied portion of the source image by invoking gdImageColorExact. If such a value is not found, gdImageCopy will attempt to allocate colors as needed using gdImageColorAllocate. If both of these methods fail, gdImageCopy will invoke gdImageColorClosest to find the color in the destination image which most closely approximates the color of the pixel being copied.

/* Load a small png to expand in the larger one */
im_in = gdImageCreateFromPng("small.png")
in_x = gdImageGetWidth(im_in)
in_y = gdImageGetHeight(im_in)
/* Make the output image four times as large on both axes */
im_out = gdImageCreate(in_x * 4, in_y * 4)
out_x = gdImageGetWidth(im_out)
out_y = gdImageGetHeight(im_out)
/* Now copy the smaller image, but four times larger */
Call gdImageCopyResized im_out, im_in, 0, 0, 0, 0, out_x, out_y, in_x, in_y
Call gdImagePng im_out, "large.png"
Call gdImageDestroy im_in
Call gdImageDestroy im_out
gdImageCopyResampled(dst, src, dstX, dstY, srcX, srcY, destW, destH, srcW, srcH)
gdImageCopyResampled is used to copy a rectangular portion of one image (src) to another image (dst), smoothly interpolating pixel values so that, in particular, reducing the size of an image still retains a great deal of clarity. The X and Y dimensions of the original region and the destination region can vary, resulting in stretching or shrinking of the region as appropriate. (For a simpler version of this function which does not deal with resizing, see gdImageCopy. For a version which does not interpolate pixel values, see gdImageCopyResized.

Pixel values are only interpolated if the destination image is a truecolor image. Otherwise, gdImageCopyResized is automatically invoked.

The dstX and dstY arguments specify the point in the destination image to which the region will be copied. The srcX and srcY arguments specify the upper left corner of the region in the source image. The dstW and dstH arguments specify the width and height of the destination region. The srcW and srcH arguments specify the width and height of the source region and can differ from the destination size, allowing a region to be scaled during the copying process.

When you copy a region from one location in an image to another location in the same image, gdImageCopy will perform as expected unless the regions overlap, in which case the result is unpredictable. If this presents a problem, create a scratch image in which to keep intermediate results.

Important note on copying between images: since images do not necessarily have the same color tables, pixels are not simply set to the same color index values to copy them. If the destination image is a palette image, gd will use the gdImageColorResolve function to determine the best color available.

/* Load a large png to shrink in the smaller one */
in = "large.png"
im_in = gdImageCreateFromPng(in)
in_x = gdImageGetWidth(im_in)
in_y = gdImageGetHeight(im_in)
/* Make the output image four times as small on both axes. Use
  a true color image so that we can interpolate colors. */
im_out = gdImageCreateTrueColor(in_x / 4, in_y / 4)
out_x = gdImageGetWidth(im_out)
out_y = gdImageGetHeight(im_out)
/* Now copy the large image, but four times smaller */
Call gdImageCopyResampled im_out, im_in, 0, 0, 0, 0, out_x, out_y, in_x, in_y
out = "large.png"
Call gdImagePng im_out, out
Call gdImageDestroy im_in
Call gdImageDestroy im_out
gdImageCopyRotated(dst, src, dstX, dstY, srcX, srcY, srcW, srcH, angle)
gdImageCopyRotated is used to copy a rectangular portion of one image (src) to another image (dst), or to another region of the same image. The srcX and srcY coordinates specify the upper left corner of the source area; however, the dstX and dstY coordinates specify the CENTER of the destination area. This important distinction is made because the rotated rectangle may may or may not be parallel to the X and Y axes. The destination coordinates may be floating point, as the center of the desired destination area may lie at the center of a pixel (0.5 pixels) rather than its upper left corner. The angle specified is an integer number of degrees, between 0 and 360, with 0 degrees causing no change, and counterclockwise rotation as the angle increases.

When you copy a region from one location in an image to another location in the same image, gdImageCopyRotated will perform as expected unless the regions overlap, in which case the result is unpredictable. If this presents a problem, create a scratch image in which to keep intermediate results.

Important note on copying between images: since palette-based images do not necessarily have the same color tables, pixels are not simply set to the same color index values to copy them. If the destination image is not a truecolor image, gdImageColorResolveAlpha is used to choose the destination pixel.

/* Load a small png to rotate in the larger one */
/* you will need a trancendental math's package!! */
in = "small.png"
im_in = gdImageCreateFromPng(in)
in_x = gdImageGetWidth(im_in)
in_y = gdImageGetHeight(im_in)
/* Make the output image four times as large on both axes */
im_out = gdImageCreate(n_x * 4, in_y * 4)
out_x = gdImageGetWidth(im_out)
out_y = gdImageGetHeight(im_out)
/* Now rotate the smaller image */
Do a = 0 While a < 360 By 45
   x = cos(a * .0174532925) * out_x / 2;
   y = -sin(a * .0174532925) * out_y / 2;
   Call gdImageCopyRotated im_out, im_in, out_x / 2 + x, out_y / 2 + y, 0, 0, in_x, in_y, a
End
out = "large.png"
Call gdImagePng im_out, out
Call gdImageDestroy im_in
Call gdImageDestroy im_out
gdImageCopyMerge(dst, src, dstX, dstY, srcX, srcY, w, h, pct)
gdImageCopyMerge is almost identical to gdImageCopy, except that it merges the two images by an amount specified in the pct parameter. If pct is 100, then it will function identically to gdImageCopy - the source image replaces the pixels in the destination.

If, however, pct is less than 100, then the two images are merged. With pct = 0, no action is taken.

This feature is most useful to 'highlight' sections of an image by merging a solid color with pct = 50:

Call gdImageCopyMerge im_out, im_in, 100, 200, 0, 0, 30, 50, 50
gdImageCopyMergeGray(dst, src, dstX, dstY, srcX, srcY, w, h, pct)
gdImageCopyMergeGray is almost identical to gdImageCopyMerge, except that when merging images it preserves the hue of the source by converting the destination pixels to grey scale before the copy operation.
Call gdImageCopyMergeGray im_out, im_in, 100, 200, 0, 0, 30, 50, 50
gdImagePaletteCopy(dst, src)
Copies a palette from one image to another, attempting to match the colors in the target image to the colors in the source palette.


gdImageSquareToCircle(im, radius)
im MUST be square, but can have any size. Returns a new image of width and height radius * 2, in which the X axis of the original has been remapped to theta (angle) and the Y axis of the original has been remapped to rho (distance from center). This is known as a "polar coordinate transform." See also gdImageStringFTCircle, which uses this function internally.

gdImageSharpen(im, pct)
Sharpens the specified image. pct is a sharpening percentage, and can be greater than 100. Silently does nothing to non-truecolor images. Silently does nothing for pct<0. Transparency/alpha channel are not altered.

Miscellaneous Functions

gdImageCompare(im1, im2)
gdImageCompare returns a number which indicates how the two images differ. The return value is then used as an argument to one of the following functions, to determine how the images differ. The most important comparison is gdImageDifferent, which indicated that the images will actually appear different when displayed. Other, less important, differences relate to pallette entries. Any difference in the transparent colour is assumed to make images display differently, even if the transparent colour is not used.
cmpMask = gdImageCompare(im1, im2)
If gdImageDifferent(cmpMask) Then Say "Images will display differently"
If gdImageDifferentTransparent(cmpMask) Then Say "Images have different transparency indexes"
gdImageDifferent(mask)
gdImageDifferent returns 1 if the bitmask represented by mask (as a result of a call to gdImageCompare) indicates the compared images are actually different.


gdImageDifferentBackground(mask)
gdImageDifferentBackground returns 1 if the bitmask represented by mask (as a result of a call to gdImageCompare) indicates the background colors in the compared images are different.


gdImageDifferentColors(mask)
gdImageDifferentColors returns 1 if the bitmask represented by mask (as a result of a call to gdImageCompare) indicates the colors in the compared images are different.


gdImageDifferentHeight(mask)
gdImageDifferentHeight returns 1 if the bitmask represented by mask (as a result of a call to gdImageCompare) indicates the height of the compared images are different.


gdImageDifferentInterlace(mask)
gdImageDifferentInterlace returns 1 if the bitmask represented by mask (as a result of a call to gdImageCompare) indicates the interlace settings in the compared images are different.


gdImageDifferentNumberColors(mask)
gdImageDifferentNumberColors returns 1 if the bitmask represented by mask (as a result of a call to gdImageCompare) indicates the number of colors in the compared images are different.


gdImageDifferentTransparent(mask)
gdImageDifferentTransparent returns 1 if the bitmask represented by mask (as a result of a call to gdImageCompare) indicates the transparent color of the compared images are different.


gdImageDifferentWidth(mask)
gdImageDifferentWidth returns 1 if the bitmask represented by mask (as a result of a call to gdImageCompare) indicates the height of the compared images are different.


gdImageInterlace(im, interlace)
gdImageInterlace is used to determine whether an image should be stored in a linear fashion, in which lines will appear on the display from first to last, or in an interlaced fashion, in which the image will "fade in" over several passes. By default, images are not interlaced. (When writing JPEG images, interlacing implies generating progressive JPEG files, which are represented as a series of scans of increasing quality. Noninterlaced gd images result in regular [sequential] JPEG data streams.)

A nonzero value for the interlace argument turns on interlace; a zero value turns it off. Note that interlace has no effect on other functions, and has no meaning unless you save the image in PNG or JPEG format; the gd and xbm formats do not support interlace.

When a PNG is loaded with gdImageCreateFromPng or a JPEG is loaded with gdImageCreateFromJpeg, interlace will be set according to the setting in the PNG or JPEG file.

Note that many PNG and JPEG viewers and web browsers do not support interlace or the incremental display of progressive JPEGs. However, the interlaced PNG or progressive JPEG should still display; it will simply appear all at once, just as other images do.

/* Load the image */
im_in = gdImageCreateFromPng("test.png")
/* Now turn on interlace */
Call gdImageInterlace im, 1
/* And open an output file */
/* Save the image  -- could also use gdImageJpeg */
Call gdImagePng im, "test.png"
Call gdImageDestroy im
gdLoadFuncs()
gdLoadFuncs registers all of the other Rexx/gd functions. For dynamically loaded libraries, this function must be called before any other Rexx/gd functions can be used.


gdDropFuncs()
gdDropFuncs does nothing. It exists for consistency with other Rexx extensions. All Rexx/gd programs should call gdDropFuncs at the end of the program.


gdVariable(variable [,newvalue])
gdDropFuncs gets or sets an internal Rexx/gd variable. With one argument, the current value of variable will be returned. With newvalue specified as well, the variable will have its value changed (assuming the variable is able to be changed). The bariable argument can be one of:
      DEBUG (settable)
         0 - no debugging
         1 - all Rexx variables set by rexx/gd are displayed as they are set
         2 - all Rexx/gd functions are traced on entry with argument values and
             on exit with the return value
         4 - all internal Rexx/gd functions are traced with their arguments
             (really only useful for developers)
         The values can be added together for a combination of the above details.
      DEBUGFILE (settable)
         Where any debugging output is written. By default this goes to
         the system's error stream; usually 'stderr'.
      VERSION (readonly)
         The full version details of Rexx/gd in the format:
         package version version_date
         Where:
            package      - the string 'rexxgd'
            version      - package version in n.n format; eg 1.0
            version_date - date package was released in DATE('N') format
gdQueryFunction(function|stem. [,option])
gdQueryFunction allows the user to determine what Rexx/gd functions are implemented and available for execution. option can be the default of R(registered and able to be executed) orA(available in package). If a stem variable is passed as the first option, then this stem will be populated with all function names in Rexx/gd that are "available" or "registered". If a Rexx/gd function name is passed as the first option, gdQueryFunction returns 0 if the function is "available" or "registered" depending on option, or 1 if the function name is not present depending on option.
call rxfuncadd 'GdQueryFunction', 'rexxgd', 'GdQueryFunction'
call rxfuncadd 'GdVariable', 'rexxgd', 'GdVariable'

say gdqueryfunction( 'stem.', 'A' ) /* returns 0 */
do i = 1 to stem.0                  /* 112 items displayed */
   say 'stem/A' stem.i
end

drop stem.
say gdqueryfunction( 'stem.', 'R' ) /* returns 0 */
do i = 1 to stem.0                  /* 2 items displayed */
   say 'stem/R' stem.i
end

drop stem.
say gdqueryfunction( 'gdvariable', 'A' ) /* returns 0 */

drop stem.
say gdqueryfunction( 'gdvariable' )      /* returns 0 */

drop stem.
say gdqueryfunction( 'gddropfuncs', 'A' ) /* returns 0 */

drop stem.
say gdqueryfunction( 'gddropfuncs', 'R' ) /* returns 1 */

Constants

GDANTIALIASED
Used in place of a color when invoking a line-drawing function such as gdImageLine or gdImageRectangle. When GDANTIALIASED is used as the color, the foreground color set with gdImageSetAntiAliased is used, with antialiasing mechanisms to minimize any "jagged" appearance. For more information, see gdImageSetAntiAliased.
GDBRUSHED
A string used in place of a color when invoking a line-drawing function such as gdImageLine or gdImageRectangle. When GDBRUSHED is used as the color, the brush image set with gdImageSetBrush is drawn in place of each pixel of the line (the brush is usually larger than one pixel, creating the effect of a wide paintbrush). See also GDSTYLEDBRUSHED for a way to draw broken lines with a series of distinct copies of an image.
GD2COMPRESSED
A string to indicate that an image is to saved in compressed gd2 format. Used in the function gdImageGd2.
GD2RAW
A string to indicate that an image is to saved in raw, unompressed gd2 format. Used in the function gdImageGd2.
GDFONTGIANT
A string representing the giant built-in, non-proportional font. Used as the fontname parameter in gdImageChar, gdImageCharUp, gdImageString, gdImageStringUp, gdImageString16 and gdImageStringUp16 functions.
GDFONTLARGE
A string representing the large built-in, non-proportional font. Used as the fontname parameter in gdImageChar, gdImageCharUp, gdImageString, gdImageStringUp, gdImageString16 and gdImageStringUp16 functions.
GDFONTMEDIUMBOLD
A string representing the mediumbold built-in, non-proportional font. Used as the fontname parameter in gdImageChar, gdImageCharUp, gdImageString, gdImageStringUp, gdImageString16 and gdImageStringUp16 functions.
GDFONTSMALL
A string representing the small built-in, non-proportional font. Used as the fontname parameter in gdImageChar, gdImageCharUp, gdImageString, gdImageStringUp, gdImageString16 and gdImageStringUp16 functions.
GDFONTTINY
A string representing the tiny built-in, non-proportional font. Used as the fontname parameter in gdImageChar, gdImageCharUp, gdImageString, gdImageStringUp, gdImageString16 and gdImageStringUp16 functions.
GDSTYLED
A string used in place of a color when invoking a line-drawing function such as gdImageLine or gdImageRectangle. When GDSTYLED is used as the color, the colors of the pixels are drawn successively from the style that has been set with gdImageSetStyle. If the color of a pixel is equal to gdTransparent, that pixel is not altered. (This mechanism is completely unrelated to the "transparent color" of the image itself; see gdImageColorTransparent gdImageColorTransparent for that mechanism.) See also GDSTYLEDBRUSHED.
GDSTYLEDBRUSHED
A string used in place of a color when invoking a line-drawing function such as gdImageLine or gdImageRectangle. When GDSTYLEDBRUSH is used as the color, the brush image set with gdImageSetBrush is drawn at each pixel of the line, providing that the style set with gdImageSetStyle contains a nonzero value (OR gdTransparent, which does not equal zero but is supported for consistency) for the current pixel. (Pixels are drawn successively from the style as the line is drawn, returning to the beginning when the available pixels in the style are exhausted.) Note that this differs from the behavior of GDSTYLED, in which the values in the style are used as actual pixel colors, except for GDTRANSPARENT.
GDTILED
A string used in place of a normal color in gdImageFilledRectangle, gdImageFilledPolygon, gdImageFill, and gdImageFillToBorder. GDTILED selects a pixel from the tile image set with gdImageSetTile in such a way as to ensure that the filled area will be tiled with copies of the tile image. See the discussions of gdImageFill and gdImageFillToBorder for special restrictions regarding those functions.
GDTRANSPARENT
A string used in place of a normal color in a style to be set with gdImageSetStyle. GDTRANSPARENT is not the transparent color index of the image; for that functionality please see gdImageColorTransparent.

Alphabetical quick index

GD2COMPRESSED GD2RAW GDANTIALIASED GDBRUSHED gdDropFuncs | gdFontGetHeight | gdFontGetWidth | GDFONTGIANT | GDFONTLARGE | GDFONTMEDIUMBOLD | GDFONTSMALL | GDFONTTINY | gdImageAlpha | gdImageAlphaBlending | gdImageArc | gdImageBlue | gdImageBoundsSafe | gdImageChar | gdImageCharUp | gdImageColorAllocate | gdImageColorAllocateAlpha | gdImageColorClosest | gdImageColorClosestAlpha | gdImageColorClosestHWB | gdImageColorDeallocate | gdImageColorExact | gdImageColorResolve | gdImageColorResolveAlpha | gdImageColorTransparent | gdImageColorsTotal | gdImageCompare | gdImageCopy | gdImageCopyMerge | gdImageCopyMergeGray | gdImageCopyResampled | gdImageCopyResized | gdImageCopyRotated | gdImageCreate | gdImageCreateFromGd | gdImageCreateFromGd2 | gdImageCreateFromGd2Part | gdImageCreateFromGif | gdImageCreateFromJpeg | gdImageCreateFromPng | gdImageCreateFromWBMP | gdImageCreateFromXbm | gdImageCreateFromXpm | gdImageCreateTrueColor | gdImageDestroy | gdImageDifferent | gdImageDifferentBackground | gdImageDifferentColors | gdImageDifferentHeight | gdImageDifferentInterlace | gdImageDifferentNumberColors | gdImageDifferentTransparent | gdImageDifferentWidth | gdImageFill | gdImageFillToBorder | gdImageFilledArc | gdImageFilledEllipse | gdImageFilledPolygon | gdImageFilledRectangle | gdImageGd | gdImageGd2 | gdImageGetClip | gdImageGetHeight | gdImageGetInterlaced | gdImageGetPixel | gdImageGetTransparent | gdImageGetWidth | gdImageGif | gdImageGifAnimAdd | gdImageGifAnimBegin | gdImageGifAnimEnd | gdImageGreen | gdImageInterlace | gdImageJpeg | gdImageLine | gdImageOpenPolygon | gdImagePaletteCopy | gdImagePng | gdImagePngEx | gdImagePolygon | gdImageRectangle | gdImageRed | gdImageSaveAlpha | gdImageSetAntiAliased | gdImageSetAntiAliasedDontBlend | gdImageSetBrush | gdImageSetClip | gdImageSetPixel | gdImageSetStyle | gdImageSetThickness | gdImageSetTile | gdImageSharpen | gdImageSquareToCircle | gdImageString | gdImageString16 | gdImageStringFT | gdImageStringFTCircle | gdImageStringTTF | gdImageStringUp | gdImageStringUp16 | gdImageTrueColor | gdImageTrueColorToPalette | gdImageWBMP | gdLoadFuncs | gdQueryFunction | GDSTYLED | GDSTYLEDBRUSHED | GDTILED | GDTRANSPARENT | gdTrueColorAlpha gdVariable |