/*
 * $Id: hbgd.txt 13926 2010-02-20 03:00:17Z vszakats $
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://www.xharbour.org http://www.harbour-project.org
 *
 * Copyright 2004-2005 Francesco Saverio Giudice <info@fsgiudice.com>
 *    Documentation for GD Library wrapper functions and classes
 *
 * See COPYING for licensing terms.
 *
 */

/*  $DOC$
 *  $FUNCNAME$
 *      The GD Library
 *  $CATEGORY$
 *      Document
 *  $ONELINER$
 *      Read me file for GD Library
 *  $DESCRIPTION$
 *      HBGD is basically a wrapper of Thomas Boutell's GD Library version 2.0.33.
 *      GD Library is a powerfull graphic library very usefull expecially under CGI environment.
 *
 *      HBGD actually contains almost all GD functions, more a set of functions that extends original
 *      library and a set of classes that make easier to work with this library.
 *
 *      Thomas Boutell's GD library actually supports these graphic formats:
 *      PNG, JPEG, GIF, Animated GIF, GD, GD2, WBMP, XBM, XPM
 *      WBMP is Wireless Bitmap, not Windows Bitmap, and it is used for WAP. It is a B&W bitmap.
 *
 *      HBGD actually supports PNG, JPEG, GIF, GD, WBMP
 *      The other Animated GIF, GD2, XBM and XPM are not wrapped actually.
 *
 *      Using this library you can, as a little example:
 *      - create an image in memory, true color or with a 256 colors palette;
 *      - load and save an image of above formats and convert it to another supported format;
 *      - draw dots, lines, dashed lines, polygons, rectangles, arcs, circles and ellipses;
 *      - fill with colors;
 *      - draw with brushes;
 *      - check a point or part or full image with a lot of query functions;
 *      - draw characters and words with internal fonts or using truetype fonts;
 *      - write strings on a base line or on a circle line and with any angle degree;
 *      - copy, resize and rotate part or full image;
 *
 *      and, over this, some functions to clone, crop, zoom, rotate outside and inside.
 *
 *      The prefix for all functions is GD (i.e. gdImageCreate() )
 *
 *      You can use directly all API functions or TGD class.
 *
 *      NOTE: Not all functions are wrapped.
 *
 *  $SEEALSO$
 *      Alphabetical list of functions, Categorized list of functions, GDImage Class, GDChart Class.
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageCreate()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Create a palette-based image in memory with no more that 256 colors.
 *  $SYNTAX$
 *      gdImageCreate( <nPixelWidth>, <nPixelHeight> ) --> <pImage>
 *  $ARGUMENTS$
 *      <nPixelWidth>  - image width
 *      <nPixelHeight> - image height
 *  $RETURNS$
 *      <pImage>       - Image pointer
 *  $DESCRIPTION$
 *      gdImageCreate() creates an empty image in memory.
 *      This image has no more than 256 colors.
 *
 *      gdImageCreate() returns an image pointer or NIL if unable to create the image.
 *      The image pointer must be destroyed using gdImageDestroy()
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *
 *        pImage := gdImageCreate( 64, 64 )
 *        // Use here image
 *        .........
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreateTrueColor()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageCreateTrueColor()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Create a true color image in memory.
 *  $SYNTAX$
 *      gdImageCreateTrueColor( <nPixelWidth>, <nPixelHeight> ) --> <pImage>
 *  $ARGUMENTS$
 *      <nPixelWidth>  - image width
 *      <nPixelHeight> - image height
 *  $RETURNS$
 *      <pImage>       - Image pointer
 *  $DESCRIPTION$
 *      gdImageCreateTrueColor() creates an empty image in memory.
 *      This image has true colors.
 *
 *      gdImageCreateTrueColor() returns an image pointer or NIL if unable to create the image.
 *      The image pointer must be destroyed using gdImageDestroy()
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *
 *        pImage := gdImageCreateTrueColor( 64, 64 )
 *        // Use here image
 *        .........
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageDestroy()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Free memory used from an image.
 *  $SYNTAX$
 *      gdImageDestroy( <pImage> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageDestroy() frees memory used from an image.
 *      It's important to use this function before exiting from a program.
 *
 *      HBGD uses it's own memory to manage an image, so it is important to use this function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *
 *        pImage := gdImageCreateTrueColor( 64, 64 )
 *        // Use here image
 *        .........
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageCreate(), gdImageCreateTrueColor()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageFromJpeg()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Load a JPEG image file.
 *  $SYNTAX$
 *      gdImageFromJpeg( <cFile> | <nHandle> | <pPointer> [, <nSize> ] ) --> <pImage>
 *  $ARGUMENTS$
 *      <cFile>        - Image file name
 *      <nHandle>      - File handle
 *      <pPointer>     - Memory image pointer
 *      <nSize>        - Image size
 *  $RETURNS$
 *      <pImage>       - Image pointer
 *  $DESCRIPTION$
 *      gdImageFromJpeg() creates a JPEG image from a file or a handle or another image in memory.
 *
 *      You can use one of 3 syntax:
 *
 *      pImage := gdImageFromJpeg( "myimage.jpg" )
 *
 *      or
 *
 *      pImage := gdImageFromJpeg( nFileHandle, nSize )
 *
 *      or
 *
 *      pImage := gdImageFromJpeg( pMemoryImagePtr, nSize )
 *
 *      the pImage pointer returned will be not NIL if successfull and will contains a memory pointer
 *      to the jpeg image.
 *
 *      Remember to free memory with gdImageDestroy() before exit from application.
 *      HBGD uses it's own memory to manage an image, so it is important to use this function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *
 *        pImage := gdImageFromJpeg( "myimage.jpg" )
 *        // Use here image
 *        .........
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageCreate(), gdImageCreateTrueColor(), gdImageDestroy(), gdImageFromGif(), gdImageFromPng(), gdImageFromGD(), gdImageFromWBmp()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageFromGif()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Load a Gif image file.
 *  $SYNTAX$
 *      gdImageFromGif( <cFile> | <nHandle> | <pPointer> [, <nSize> ] ) --> <pImage>
 *  $ARGUMENTS$
 *      <cFile>        - Image file name
 *      <nHandle>      - File handle
 *      <pPointer>     - Memory image pointer
 *      <nSize>        - Image size
 *  $RETURNS$
 *      <pImage>       - Image pointer
 *  $DESCRIPTION$
 *      gdImageFromGif() creates a GIF image from a file or a handle or another image in memory.
 *
 *      You can use one of 3 syntax:
 *
 *      pImage := gdImageFromGif( "myimage.gif" )
 *
 *      or
 *
 *      pImage := gdImageFromGif( nFileHandle, nSize )
 *
 *      or
 *
 *      pImage := gdImageFromGif( pMemoryImagePtr, nSize )
 *
 *      the pImage pointer returned will be not NIL if successfull and will contains a memory pointer
 *      to the gif image.
 *
 *      Remember to free memory with gdImageDestroy() before exit from application.
 *      HBGD uses it's own memory to manage an image, so it is important to use this function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *
 *        pImage := gdImageFromGif( "myimage.gif" )
 *        // Use here image
 *        .........
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageCreate(), gdImageCreateTrueColor(), gdImageDestroy(), gdImageFromJpeg(), gdImageFromPng(), gdImageFromGD(), gdImageFromWBmp()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageFromPng()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Load a PNG image file.
 *  $SYNTAX$
 *      gdImageFromPng( <cFile> | <nHandle> | <pPointer> [, <nSize> ] ) --> <pImage>
 *  $ARGUMENTS$
 *      <cFile>        - Image file name
 *      <nHandle>      - File handle
 *      <pPointer>     - Memory image pointer
 *      <nSize>        - Image size
 *  $RETURNS$
 *      <pImage>       - Image pointer
 *  $DESCRIPTION$
 *      gdImageFromPng() creates a PNG image from a file or a handle or another image in memory.
 *
 *      You can use one of 3 syntax:
 *
 *      pImage := gdImageFromPng( "myimage.png" )
 *
 *      or
 *
 *      pImage := gdImageFromPng( nFileHandle, nSize )
 *
 *      or
 *
 *      pImage := gdImageFromPng( pMemoryImagePtr, nSize )
 *
 *      the pImage pointer returned will be not NIL if successfull and will contains a memory pointer
 *      to the png image.
 *
 *      Remember to free memory with gdImageDestroy() before exit from application.
 *      HBGD uses it's own memory to manage an image, so it is important to use this function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *
 *        pImage := gdImageFromPng( "myimage.png" )
 *        // Use here image
 *        .........
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageCreate(), gdImageCreateTrueColor(), gdImageDestroy(), gdImageFromJpeg(), gdImageFromGif(), gdImageFromGD(), gdImageFromWBmp()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageFromGD()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Load a GD image file.
 *  $SYNTAX$
 *      gdImageFromGD( <cFile> | <nHandle> | <pPointer> [, <nSize> ] ) --> <pImage>
 *  $ARGUMENTS$
 *      <cFile>        - Image file name
 *      <nHandle>      - File handle
 *      <pPointer>     - Memory image pointer
 *      <nSize>        - Image size
 *  $RETURNS$
 *      <pImage>       - Image pointer
 *  $DESCRIPTION$
 *      gdImageFromGD() creates a GD image from a file or a handle or another image in memory.
 *
 *      You can use one of 3 syntax:
 *
 *      pImage := gdImageFromGD( "myimage.gd" )
 *
 *      or
 *
 *      pImage := gdImageFromGD( nFileHandle, nSize )
 *
 *      or
 *
 *      pImage := gdImageFromGD( pMemoryImagePtr, nSize )
 *
 *      the pImage pointer returned will be not NIL if successfull and will contains a memory pointer
 *      to the GD image.
 *
 *      Remember to free memory with gdImageDestroy() before exit from application.
 *      HBGD uses it's own memory to manage an image, so it is important to use this function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *
 *        pImage := gdImageFromGD( "myimage.gd" )
 *        // Use here image
 *        .........
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageCreate(), gdImageCreateTrueColor(), gdImageDestroy(), gdImageFromJpeg(), gdImageFromGif(), gdImageFromPng(), gdImageFromWBmp()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageFromWBmp()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Load a WBmp image file.
 *  $SYNTAX$
 *      gdImageFromWBmp( <cFile> | <nHandle> | <pPointer> [, <nSize> ] ) --> <pImage>
 *  $ARGUMENTS$
 *      <cFile>        - Image file name
 *      <nHandle>      - File handle
 *      <pPointer>     - Memory image pointer
 *      <nSize>        - Image size
 *  $RETURNS$
 *      <pImage>       - Image pointer
 *  $DESCRIPTION$
 *      gdImageFromWBmp() creates a WBmp image from a file or a handle or another image in memory.
 *
 *      You can use one of 3 syntax:
 *
 *      pImage := gdImageFromWBmp( "myimage.wbmp" )
 *
 *      or
 *
 *      pImage := gdImageFromWBmp( nFileHandle, nSize )
 *
 *      or
 *
 *      pImage := gdImageFromWBmp( pMemoryImagePtr, nSize )
 *
 *      the pImage pointer returned will be not NIL if successfull and will contains a memory pointer
 *      to the WBmp image.
 *
 *      Remember to free memory with gdImageDestroy() before exit from application.
 *      HBGD uses it's own memory to manage an image, so it is important to use this function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *
 *        pImage := gdImageFromWBmp( "myimage.wbmp" )
 *        // Use here image
 *        .........
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageCreate(), gdImageCreateTrueColor(), gdImageDestroy(), gdImageFromJpeg(), gdImageFromGif(), gdImageFromPng(), gdImageFromGD()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageJpeg()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Save a JPEG image.
 *  $SYNTAX$
 *      gdImageJpeg( <pImage>, <cFile> | <nHandle> [, <nCompressionLevel> ] ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <cFile>        - Image file name
 *      <nHandle>      - File handle
 *      <nCompressionLevel> - a numeric value between 0=max compression and 95=min compression (best quality)
 *                            default is -1=auto
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageJpeg() saves a JPEG image to a file or a handle.
 *
 *      You can use one of 2 syntax:
 *
 *      gdImageJpeg( pImage, "myimage.jpg" )
 *
 *      or
 *
 *      gdImageJpeg( pImage, nFileHandle )
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *
 *        pImage := gdImageFromGif( "myimage.gif" )
 *
 *        // Image conversion
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageFromGif()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageGif()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Save a GIF image.
 *  $SYNTAX$
 *      gdImageGif( <pImage>, <cFile> | <nHandle> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <cFile>        - Image file name
 *      <nHandle>      - File handle
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageGif() saves a GIF image to a file or a handle.
 *
 *      You can use one of 2 syntax:
 *
 *      gdImageGif( pImage, "myimage.gif" )
 *
 *      or
 *
 *      gdImageGif( pImage, nFileHandle )
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *
 *        pImage := gdImageFromJpeg( "myimage.jpg" )
 *
 *        // Image conversion
 *        gdImageGif( pImage, "myimage.gif" )
 *
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageFromJpeg()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImagePng()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Save a PNG image.
 *  $SYNTAX$
 *      gdImagePng( <pImage>, <cFile> | <nHandle> [, <nCompressionLevel> ] ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <cFile>        - Image file name
 *      <nHandle>      - File handle
 *      <nCompressionLevel> - a numeric value between 0=no compression and 9=max compression
 *                            default is -1=auto
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImagePng() saves a PNG image to a file or a handle.
 *
 *      You can use one of 2 syntax:
 *
 *      gdImagePng( pImage, "myimage.png" )
 *
 *      or
 *
 *      gdImagePng( pImage, nFileHandle )
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *
 *        pImage := gdImageFromGif( "myimage.gif" )
 *
 *        // Image conversion
 *        gdImagePng( pImage, "myimage.png" )
 *
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageFromGif()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageGD()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Save a GD image.
 *  $SYNTAX$
 *      gdImageGd( <pImage>, <cFile> | <nHandle> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <cFile>        - Image file name
 *      <nHandle>      - File handle
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageGd() saves a GD image to a file or a handle.
 *
 *      You can use one of 2 syntax:
 *
 *      gdImageGd( pImage, "myimage.gd" )
 *
 *      or
 *
 *      gdImageGd( pImage, nFileHandle )
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *
 *        pImage := gdImageFromGif( "myimage.gif" )
 *
 *        // Image conversion
 *        gdImageGd( pImage, "myimage.gd" )
 *
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageFromGif()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageWBmp()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Save a WBMP image.
 *  $SYNTAX$
 *      gdImageWBmp( <pImage>, <cFile> | <nHandle> [, <nFGcolor> ] ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <cFile>        - Image file name
 *      <nHandle>      - File handle
 *      <nFGcolor>     - foreground color value to be used as foreground, the others are background
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageWBmp() saves a WBMP image to a file or a handle.
 *
 *      You can use one of 2 syntax:
 *
 *      gdImageWBmp( pImage, "myimage.wbmp", nColor )
 *
 *      or
 *
 *      gdImagePng( pImage, nFileHandle, nColor )
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL white, black
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate background
 *        white := gdImageColorAllocate(pImage, 255, 255, 255)
 *
 *        // Allocate drawing color
 *        black := gdImageColorAllocate(pImage, 0, 0, 0)
 *
 *        // Draw a rectangle
 *        gdImageRectangle(pImage, 0, 0, 99, 99, black)
 *
 *        // Save the image with black as foreground color
 *        gdImageWBmp( pImage, "myimage.wbmp", black )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageRectangle(), gdColorAllocate()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageSetPixel()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Set a pixel to a particular color index.
 *  $SYNTAX$
 *      gdImageSetPixel( <pImage>, <x>, <y>, <nColor> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <x>            - Horizontal position
 *      <y>            - Vertical position
 *      <nColor>       - Color index
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageSetPixel() sets a pixel to a particular color index.
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL white
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        white := gdImageColorAllocate(pImage, 255, 255, 255)
 *
 *        // Draw a pixel
 *        gdImageSetPixel(pImage, 50, 50, white)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageLine()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Draws a line between two end points (x1, y1 and x2, y2) with a particular color index.
 *  $SYNTAX$
 *      gdImageLine( <pImage>, <x1>, <y1>, <x2>, <y2>, <nColor> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <x1>           - 1st point horizontal position
 *      <y1>           - 1st point vertical position
 *      <x2>           - 2nd point horizontal position
 *      <y2>           - 2nd point vertical position
 *      <nColor>       - Color index
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageLine() Draws a line between two end points (x1, y1 and x2, y2)
 *      with a particular color index.
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL blue
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        blue := gdImageColorAllocate(pImage, 0, 0, 255)
 *
 *        // Draw a line
 *        gdImageLine(pImage, 10, 10, 90, 90, blue)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageDashedLine()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Draws a dashed line between two end points (x1, y1 and x2, y2) with a particular color index.
 *  $SYNTAX$
 *      gdImageDashedLine( <pImage>, <x1>, <y1>, <x2>, <y2>, <nColor> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <x1>           - 1st point horizontal position
 *      <y1>           - 1st point vertical position
 *      <x2>           - 2nd point horizontal position
 *      <y2>           - 2nd point vertical position
 *      <nColor>       - Color index
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageDashedLine() Draws a dashed line between two end points (x1, y1 and x2, y2)
 *      with a particular color index.
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL blue
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        blue := gdImageColorAllocate(pImage, 0, 0, 255)
 *
 *        // Draw a dashed line
 *        gdImageDashedLine(pImage, 10, 10, 90, 90, blue)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImagePolygon()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Draws a closed polygon with verticies (at least 3) with a particular color index.
 *  $SYNTAX$
 *      gdImagePolygon( <pImage>, <aVerticies>, <nColor> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <aVerticies>   - Array of point array { <x>, <y> } where
 *                       <x> is horizontal position
 *                       <y> is vertical position
 *      <nColor>       - Color index
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImagePolygon() Draws a closed polygon with verticies (at least 3) with a
 *      particular color index.
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL blue
 *        LOCAL aVerticies := { ;
 *                              { 50,  0 } ,;
 *                              { 99, 99 } ,;
 *                              {  0, 99 }  ;
 *                            }
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        blue := gdImageColorAllocate(pImage, 0, 0, 255)
 *
 *        // Draw a polygon
 *        gdImagePolygon(pImage, aVerticies, blue)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageOpenPolygon()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Draws an open polygon with verticies (at least 3) with a particular color index.
 *  $SYNTAX$
 *      gdImageOpenPolygon( <pImage>, <aVerticies>, <nColor> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <aVerticies>   - Array of point array { <x>, <y> } where
 *                       <x> is horizontal position
 *                       <y> is vertical position
 *      <nColor>       - Color index
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageOpenPolygon() Draws an open polygon with verticies (at least 3) with a
 *      particular color index. Unlike gdImagePolygon() the endpoints of the line sequence
 *      are not connected to close the polygon.
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL blue
 *        LOCAL aVerticies := { ;
 *                              { 50,  0 } ,;
 *                              { 99, 99 } ,;
 *                              {  0, 99 }  ;
 *                            }
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        blue := gdImageColorAllocate(pImage, 0, 0, 255)
 *
 *        // Draws an open polygon
 *        gdImageOpenPolygon(pImage, aVerticies, blue)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageRectangle()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Draws a rectangle with a particular color index.
 *  $SYNTAX$
 *      gdImageRectangle( <pImage>, <x1>, <y1>, <x2>, <y2>, <nColor> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <x1>           - upper left point horizontal position
 *      <y1>           - upper left point vertical position
 *      <x2>           - lower right point horizontal position
 *      <y2>           - lower right point vertical position
 *      <nColor>       - Color index
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageRectangle() draws a rectangle between 2 points with a
 *      particular color index.
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL blue
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        blue := gdImageColorAllocate(pImage, 0, 0, 255)
 *
 *        // Draw a rectangle
 *        gdImageRectangle(pImage, 10, 10, 50, 50, blue)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageFilledPolygon()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Draws a filled polygon with verticies (at least 3) with a particular color index.
 *  $SYNTAX$
 *      gdImageFilledPolygon( <pImage>, <aVerticies>, <nColor> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <aVerticies>   - Array of point array { <x>, <y> } where
 *                       <x> is horizontal position
 *                       <y> is vertical position
 *      <nColor>       - Color index
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageFilledPolygon() Draws a filled polygon with verticies (at least 3) with a
 *      particular color index.
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL blue
 *        LOCAL aVerticies := { ;
 *                              { 50,  0 } ,;
 *                              { 99, 99 } ,;
 *                              {  0, 99 }  ;
 *                            }
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        blue := gdImageColorAllocate(pImage, 0, 0, 255)
 *
 *        // Draw a filled polygon
 *        gdImageFilledPolygon(pImage, aVerticies, blue)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageFilledRectangle()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Draws a filled rectangle with a particular color index.
 *  $SYNTAX$
 *      gdImageFilledRectangle( <pImage>, <x1>, <y1>, <x2>, <y2>, <nColor> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <x1>           - upper left point horizontal position
 *      <y1>           - upper left point vertical position
 *      <x2>           - lower right point horizontal position
 *      <y2>           - lower right point vertical position
 *      <nColor>       - Color index
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageFilledRectangle() draws a filled rectangle between 2 points with a
 *      particular color index.
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL blue
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        blue := gdImageColorAllocate(pImage, 0, 0, 255)
 *
 *        // Draw a filled rectangle
 *        gdImageFilledRectangle(pImage, 10, 10, 50, 50, blue)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageArc()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Draws a partial ellipse centered at a given point.
 *  $SYNTAX$
 *      gdImageArc( <pImage>, <cx>, <cy>, <w>, <h>, <s>, <e>, <nColor> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <cx>           - center point horizontal position
 *      <cy>           - center point vertical position
 *      <w>            - width
 *      <h>            - height
 *      <s>            - start degree
 *      <e>            - end degree
 *      <nColor>       - Color index
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageArc() is used to draw a partial ellipse centered at the given point,
 *      with the specified width and height in pixels. The arc begins at the position
 *      in degrees specified by s and ends at the position specified by e.
 *      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.
 *      <e> must be greater than <s>. Values greater than 360 are interpreted modulo 360.
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL blue
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        blue := gdImageColorAllocate(pImage, 0, 0, 255)
 *
 *        // Draw an ellipse
 *        gdImageArc(pImage, 50, 25, 98, 48, 0, 360, blue)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageFilledArc()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Draws a partial filled ellipse centered at a given point.
 *  $SYNTAX$
 *      gdImageArc( <pImage>, <cx>, <cy>, <w>, <h>, <s>, <e>, <nColor>, <nStyle> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <cx>           - center point horizontal position
 *      <cy>           - center point vertical position
 *      <w>            - width
 *      <h>            - height
 *      <s>            - start degree
 *      <e>            - end degree
 *      <nColor>       - Color index
 *      <nStyle>       - fill style
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageFilledArc() is used to draw a partial ellipse centered at the given point,
 *      with the specified width and height in pixels. The arc begins at the position
 *      in degrees specified by s and ends at the position specified by e.
 *      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.
 *      <e> must be greater than <s>. Values greater than 360 are interpreted modulo 360.
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *      Last parameter <nStyle> is a bitwise OR of the following possibilities:
 *      gdArc
 *      gdChord
 *      gdPie (synonym for gdArc)
 *      gdNoFill
 *      gdEdged
 *
 *      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'
 *
 *      these constants are defined in gd.ch
 *
 *  $EXAMPLES$
 *
 *      #include "gd.ch"
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL blue
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        blue := gdImageColorAllocate(pImage, 0, 0, 255)
 *
 *        // Draw an ellipse
 *        gdImageFilledArc(pImage, 50, 25, 98, 48, 0, 360, blue, gdArc)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageFilledEllipse()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      Draws a filled ellipse centered at a given point.
 *  $SYNTAX$
 *      gdImageFilledEllipse( <pImage>, <cx>, <cy>, <w>, <h>, <nColor> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <cx>           - center point horizontal position
 *      <cy>           - center point vertical position
 *      <w>            - width
 *      <h>            - height
 *      <nColor>       - Color index
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageFilledEllipse() is used to draw a filled ellipse centered at the given point,
 *      with the specified width and height in pixels.
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL blue
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        blue := gdImageColorAllocate(pImage, 0, 0, 255)
 *
 *        // Draw an ellipse
 *        gdImageFilledEllipse(pImage, 50, 25, 98, 48, blue)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageFillToBorder()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      floods a portion of the image with the specified color.
 *  $SYNTAX$
 *      gdImageFillToBorder( <pImage>, <x>, <y>, <nBorder>, <nColor> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <x>            - start point horizontal position
 *      <y>            - start point vertical position
 *      <nBorder>      - Color index where fill stops
 *      <nColor>       - Color index of filling color
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      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().
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL blue, red
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        blue := gdImageColorAllocate(pImage, 0, 0, 255)
 *        red  := gdImageColorAllocate(pImage, 255, 0, 0)
 *
 *        // Draw an ellipse
 *        gdImageArc(pImage, 50, 25, 98, 48, 0, 360, blue)
 *
 *        // Fill the ellipse
 *        gdImageFillToBorder(pImage, 50, 50, blue, red)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg(), gdImageArc()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageFill()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      floods a portion of the image with the specified color.
 *  $SYNTAX$
 *      gdImageFill( <pImage>, <x>, <y>, <nColor> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <x>            - start point horizontal position
 *      <y>            - start point vertical position
 *      <nColor>       - Color index of filling color
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageFill() floods a portion of the image with the specified color, beginning at the
 *      specified point 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.
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL blue, red
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        blue := gdImageColorAllocate(pImage, 0, 0, 255)
 *        red  := gdImageColorAllocate(pImage, 255, 0, 0)
 *
 *        // Draw an ellipse
 *        gdImageArc(pImage, 50, 25, 98, 48, 0, 360, blue)
 *
 *        // Fill the ellipse
 *        gdImageFill(pImage, 50, 50, red)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg(), gdImageArc()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageSetAntiAliased()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      specify the actual foreground color to be used when drawing antialiased lines.
 *  $SYNTAX$
 *      gdImageSetAntiAliased( <pImage>, <nColor> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <nColor>       - Color index of filling color
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      "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 constant 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.
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *  $EXAMPLES$
 *
 *      #include "gd.ch"
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL blue, red
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        /* Background color (first allocated) */
 *        blue := gdImageColorAllocate(pImage, 0, 0, 255)
 *        red  := gdImageColorAllocate(pImage, 255, 0, 0)
 *
 *        gdImageSetAntiAliased(pImage, blue)
 *
 *        // Draw a smooth line
 *        gdImageLine(pImage, 0, 0, 99, 9, gdAntiAliased)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg(), gdImageLine(), gdAntiAliased, gdSetAntiAliasedDontBlend()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdSetAntiAliasedDontBlend()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      indicate the special color that the foreground should stand out more clearly against.
 *  $SYNTAX$
 *      gdSetAntiAliasedDontBlend( <pImage>, <nColor> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <nColor>       - Color index of filling color
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      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.
 *
 *      To set the color index you have to use gdImageColorAllocate() function.
 *
 *  $EXAMPLES$
 *
 *      #include "gd.ch"
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL black, white, blue
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color
 *        /* Background color (first allocated) */
 *        black := gdImageColorAllocate(pImage, 0, 0, 0)
 *        white := gdImageColorAllocate(pImage, 255, 255, 255)
 *        blue  := gdImageColorAllocate(pImage, 0, 0, 255)
 *
 *        gdImageSetAntiAliased(pImage, blue)
 *
 *        // The portion of the line that crosses this white rectangle will not be blended smoothly
 *        gdImageSetAntiAliasedDontBlend(pImage, white)
 *
 *        // Draw a smooth line
 *        gdImageLine(pImage, 0, 0, 99, 9, gdAntiAliased)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg(), gdImageLine(), gdAntiAliased, gdSetAntiAlias()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageSetBrush()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      A "brush" is an image used to draw wide, shaped strokes in another image.
 *  $SYNTAX$
 *      gdImageSetBrush( <pImage>, <pBrush> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <pBrush>       - Brush Image pointer
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      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, gdImageOpenPolygon and gdImagePolygon,
 *      will use the current brush if the special "color" gdBrushed 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.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage, pBrush
 *        LOCAL blue, red
 *
 *        // Create an image in memory
 *        pImage := 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.
 *        pBrush := gdImageCreateFromPng( "mybrush.png" )
 *
 *        // Allocate color  (background color is the first allocate)
 *        black := gdImageColorAllocate(pImage, 0, 0, 0)
 *
 *        // Set the brush
 *        gdImageSetBrush(pImage, pBrush)
 *
 *        // Draw a line from the upper left corner to the lower
 *        // right corner using the brush.
 *        gdImageLine(pImage, 0, 0, 99, 99, gdBrushed)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *        // Destroy the brush image
 *        gdImageDestroy( pBrush )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg(), gdImageLine()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageSetTile()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *      A "tile" is an image used to fill an area with a repeated pattern.
 *  $SYNTAX$
 *      gdImageSetTile( <pImage>, <pTile> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <pTile>        - Tile Image pointer
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      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.
 *
 *  $EXAMPLES$
 *
 *      PROCEDURE Main()
 *        LOCAL pImage, pTile
 *        LOCAL blue, red
 *
 *        // Create an image in memory
 *        pImage := 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.
 *        pTile := gdImageCreateFromPng( "mytile.png" )
 *
 *        // Allocate color  (background color is the first allocate)
 *        black := gdImageColorAllocate(pImage, 0, 0, 0)
 *
 *        // Set the tile
 *        gdImageSetTile(pImage, pTile)
 *
 *        // Fill an area using the tile
 *        gdImageFilledRectangle(pImage, 25, 25, 75, 75, gdTiled)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *        // Destroy the tile image
 *        gdImageDestroy( pTile )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg(), gdImageFilledRectangle()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageSetStyle()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *       set any desired series of colors to be repeated during the drawing of a line.
 *  $SYNTAX$
 *      gdImageSetStyle( <pImage>, <aStyle> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <aStyle>       - Array of colors and special colors used to "style" a line
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      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 integers and assign them the desired series
 *      of color values 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.
 *
 *      The style array is copied when you set the style, so you need not be concerned with
 *      keeping the array around indefinitely. This should not break existing code that assumes
 *      styles are not copied.
 *
 *      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.
 *
 *  $EXAMPLES$
 *
 *      #include "gd.ch"
 *
 *      PROCEDURE Main()
 *        LOCAL pImage, aStyleDotted := {}, aStyleDashed := {}
 *        LOCAL black, red
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color  (background color is the first allocate)
 *        black := gdImageColorAllocate(pImage, 0, 0, 0)
 *        red   := gdImageColorAllocate(pImage, 255, 0, 0)
 *
 *        // Set up dotted style. Leave every other pixel alone.
 *        aAdd( aStyleDotted, red )
 *        aAdd( aStyleDotted, gdTransparent )
 *
 *        // Set up dashed style. Three on, three off.
 *        aAdd( aStyleDashed, red )
 *        aAdd( aStyleDashed, red )
 *        aAdd( aStyleDashed, red )
 *        aAdd( aStyleDashed, gdTransparent )
 *        aAdd( aStyleDashed, gdTransparent )
 *        aAdd( aStyleDashed, gdTransparent )
 *
 *        // Set dotted style.
 *        gdImageSetStyle(pImage, aStyleDotted)
 *
 *        // Draw a line from the upper left corner to the lower right corner.
 *        gdImageLine(pImage, 0, 0, 99, 99, gdStyled)
 *
 *        // Now the dashed line.
 *        gdImageSetStyle(pImage, aStyleDashed)
 *        gdImageLine(pimage, 0, 99, 0, 99, gdStyled)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg(), gdImageLine()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      gdImageSetThickness()
 *  $CATEGORY$
 *      HBGD
 *  $ONELINER$
 *       determines the width of lines drawn in pixels.
 *  $SYNTAX$
 *      gdImageSetThickness( <pImage>, <nThickness> ) --> NIL
 *  $ARGUMENTS$
 *      <pImage>       - Image pointer
 *      <nThickness>   - width of line in pixel
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      gdImageSetThickness determines the width of lines drawn by the gdImageLine,
 *      gdImagePolygon, gdImageOpenPolygon and related functions, in pixels.
 *
 *  $EXAMPLES$
 *
 *      #include "gd.ch"
 *
 *      PROCEDURE Main()
 *        LOCAL pImage
 *        LOCAL black, white
 *
 *        // Create an image in memory
 *        pImage := gdImageCreate( 100, 100 )
 *
 *        // Allocate color  (background color is the first allocate)
 *        black := gdImageColorAllocate(pImage, 0, 0, 0)
 *        white := gdImageColorAllocate(pImage, 255, 255, 255)
 *
 *        // Set thickness.
 *        gdImageSetThickness(pImage, 4)
 *
 *        // Draw a fat line from the upper left corner to the lower right corner.
 *        gdImageLine(pImage, 0, 0, 99, 99, white)
 *
 *        // Save the image
 *        gdImageJpeg( pImage, "myimage.jpg" )
 *
 *        // Destroy the image
 *        gdImageDestroy( pImage )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      GD Library
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      gdwrp.c
 *  $SEEALSO$
 *      gdImageDestroy(), gdImageCreate(), gdImageColorAllocate(), gdImageJpeg(), gdImageLine()
 *  $END$
 */

