# Rexx/gd

## 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 or JPEG file. This is particularly useful in World Wide Web applications, where PNG and JPEG are two of the formats accepted for inline images by most browsers. Rexx/gd does not create GIF files. Unisys holds a patent on the LZW compression algorithm, which is used in fully compressed GIF images.

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.

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

- the gd library

  #### By HTTP

  - Gzipped Tar File (Unix)
  - .ZIP File (Windows)

  #### By FTP

  - Gzipped Tar File (Unix)
  - .ZIP File (Windows)
- libpng is available for a variety of platforms from the PNG web site.
- zlib is available for a variety of platforms from the zlib web site.
- libjpeg 6b or greater

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 DOS, Win32 and OS/2 ports of Rexx/gd are statically linked with ports of all of the above packages, so you don't need anything else, other than Rexx/gd.

On Unix platforms, 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!

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

## Function and type reference

- Image creation, destruction, loading and saving
- Drawing, styling, brushing, tiling and filling functions
- Query functions (not color-related)
- Font and text-handling functions
- Color handling functions
- Copying and resizing functions
- Miscellaneous Functions
- Constants

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

gdImageCreateFromJpeg(filename)
  gdImageCreateFromJpeg is called to load images from JPEG format files. Invoke gdImageCreateFromJpeg with a file containing the desired image. gdImageCreateFromJpeg 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 JPEG image). The image must eventually be destroyed using gdImageDestroy().

      im = gdImageCreateFromJpeg("myjpeg.jpg")
      Say 'Image size:' gdImageGetWidth(im) 'x' gdImageGetHeight(im)
      Call gdImageDestroy im

gdImageCreateFromPng(filename)
  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().

      im = gdImageCreateFromPng("mypng.png")
      Say 'Image size:' gdImageGetWidth(im) 'x' gdImageGetHeight(im)
      Call gdImageDestroy im

gdImageCreateFromGd(filename)
  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.) 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)
  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 a LZW compression). 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 = gdImageCreateFromGd2("mygd2.gd2")
      Say 'Image size:' gdImageGetWidth(im) 'x' gdImageGetHeight(im)
      Call gdImageDestroy im

gdImageCreateFromGd2Part(filename, 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 (x, y) and dimensions (width, height) of the desired image. gdImageCreateFromGd2Part returns an internal pointer to the new image, or "" if unable to load the image. The image must eventually be destroyed using gdImageDestroy().

      EXAMPLE ???

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

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

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

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

### Drawing Functions

void 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

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

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

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

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 3.1 environments. (Of course, in a Unix or Win32 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

gdImageFillToBorder(im, x, y, border, color)
  gdImageFillToBorder floods a portion of the image with the specified color, beginning at the specified point x and y, 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 Win32 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, 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

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

### Query Functions

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 bounds of the image, 0 if not. This function is intended primarily for use by those who wish to add functions to gd, rather than Rexx/gd, but it is included for completeness.

      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.

gdImageGetHeight(im)
  gdImageGetHeight returns the height of the image in pixels.

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

gdImageStringTTF(im, brect, color, fontname, ptsize, angle, x, y, string)
  gdImageStringTTF draws a string of anti-aliased characters on the image using the FreeType library to print from user-supplied TrueType fonts. Obtaining True-Type fonts is entirely up to you. The string is anti-aliased, meaning that there should be less "jaggies." The fontname is the full pathname to a TrueType font file. The string may be arbitrarily scaled using ptsize and rotated angle in radians.

  On return, gdImageStringTTF returns "" if successful, or an error string if unsuccessful. The brect array is filled on return from gdImageStringTTF 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: "&#192;"

      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 = gdImageStringTTF( ,"brect.",0,fontname,size,0,0,0,string)
      If err \= "" Then
         Do
            Say "Error with gdImageStringTTF():" 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 = gdImageStringTTF(im,"brect.",black,fontname,size,0,x,y,string)
      If err \= "" Then
         Do
            Say "Error with gdImageStringTTF():" err
            return 1
         End

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

      /* Destroy it */
      Call gdImageDestroy im

### 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. When creating a new 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.

      ... inside a function ...
      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

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.

  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

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.

  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.

      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.

      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

gdImageColorsTotal(im)
  gdImageColorsTotal returns the number of colors currently allocated in the image.

gdImageColorRed(im, color)
  gdImageColorRed returns the red portion of the specified color in the image.

gdImageColorGreen(im, color)
  gdImageColorGreen returns the green portion of the specified color in the image.

gdImageColorBlue(im, color)
  gdImageColorBlue returns the green portion of the specified color in the image.

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

### 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")
      /* Get size of im_in and out_im for later use */
      in_x = gdImageGetWidth(im_in)
      in_y = gdImageGetHeight(im_in)
      out_x = gdImageGetWidth(im_out)
      out_y = gdImageGetHeight(im_out)
      /* Make the output image four times as large on both axes */
      im_out = gdImageCreate(im_in->sx * 4, im_in->sy * 4);
      /* 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

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.

### Miscellaneous Functions

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.

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.
  - gdImageDifferent
  - gdImageDifferentBackground
  - gdImageDifferentColor
  - gdImageDifferentHeight
  - gdImageDifferentInterlace
  - gdImageDifferentNumberColors
  - gdImageDifferentTransparent
  - gdImageDifferentWidth
  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.

### Constants

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 | GDBRUSHED | gdDropFuncs | GDFONTGIANT | GDFONTLARGE | GDFONTMEDIUMBOLD | GDFONTSMALL | GDFONTTINY | gdImageArc | gdImageBlue | gdImageBoundsSafe | gdImageChar | gdImageCharUp | gdImageColorAllocate | gdImageColorClosest | gdImageColorDeallocate | gdImageColorExact | gdImageColorResolve | gdImageColorTransparent | gdImageCopy | gdImageCopyResized | gdImageCreate | gdImageCreateFromGd | gdImageCreateFromGd2 | gdImageCreateFromGd2Part | gdImageCreateFromJpeg | gdImageCreateFromPng | gdImageCreateFromXbm | gdImageDestroy | gdImageDifferent | gdImageDifferentBackground | gdImageDifferentColor | gdImageDifferentHeight | gdImageDifferentInterlace | gdImageDifferentNumberColors | gdImageDifferentTransparent | gdImageDifferentWidth | gdImageFill | gdImageFillToBorder | gdImageFilledRectangle | gdImageGd | gdImageGd2 | gdImageGetInterlaced | gdImageGetPixel | gdImageGetTransparent | gdImageGreen | gdImageInterlace | gdImageJpeg | gdImageLine | gdImageFilledPolygon | gdImagePaletteCopy | gdImagePng | gdImagePolygon | gdImageWBMP | gdImageRectangle | gdImageRed | gdImageSetBrush | gdImageSetPixel | gdImageSetStyle | gdImageSetTile | gdImageString | gdImageString16 | gdImageStringTTF | gdImageStringUp | gdImageStringUp16 | gdImageWBMP | gdLoadFuncs | GDSTYLED | GDSTYLEDBRUSHED | GDTILED | GDTRANSPARENT