[ Main Menu ] [ Extension Tools Menu ] [ Professional Edition Menu ]

<iIMAGEGETCOLOR> Tag


<iIMAGEGETCOLOR
NAME=""
TYPE="<exact | closest>"
[RED=""] (0)
[GREEN=""] (0)
[BLUE=""] (0)
[CREATE="<true | false>"] (FALSE)
>

Usage This tag gets the index value in a palette for a specified RGB value. Using the CREATE directive allows the creation of new colours in the palette. The NAME directive refers to the particular image in memory that is being manipulated.
When the TYPE directive is set to EXACT it 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 of the request. If no allocated color matches the request precisely, it returns -1.
When the TYPE directive is set to CLOSEST it 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 of the request. (Closeness is determined by Euclidean 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, this will return -1. This function is most useful as a backup method for choosing a drawing color when an image already contains 256 colours and no more can be allocated.
The CREATE directive finds the first available color index in the image specified, sets its RGB values to those requested (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 colors (256) have already been allocated, this will return -1 to indicate failure. (This is not uncommon when working with existing GIF files that already use 256 colors.)
NoteThis CREATE directive does not check for existing colors that match your request; use the TYPE directive for ways to locate existing colors that approximate the color desired in situations where a new color is not available.


Top