Programming Web Graphics with Perl and GNU Softwar

Name

colorAllocate( ) — allocate a color in the color table

Synopsis

GD::Image::colorAllocate(red, green, blue)

The colorAllocate( ) function is an object method that takes three decimal integers in the range 0...255 for the three color channels and allocates a space in the image’s color table. The method returns the index of the color in the color table if successful, or -1 if it fails. The first color that is allocated with this method becomes the background color for the image.

colorAllocate( ) does not check to see if the color is already in the colormap; it is possible to have the same color allocated multiple times within a colormap. Another quirk is that GD will always keep the number of entries in the colormap to a multiple of two. Thus if eight colors are currently in a colormap and you allocate a ninth, the colormap will be expanded to include 16 colors, the ninth of which is the color you just allocated and the remainder of which are random colors. You cannot allocate more than 256 colors in an image. In this case you must first use colorDeallocate( ) to remove indices from the color table before adding new ones.

If you are going to be using the color later in your script, you should store the returned index value. For example:

$blue = $image->colorAllocate(0, 0, 255);