Home / Autodocs / graphics.library
NAME
- ObtainBestPenA
-
Search for the closest color match, or allocate a new one. (V39)
- ObtainBestPen
-
varargs stub for ObtainBestPenA
SYNOPSIS
color = ObtainBestPenA(cm, R, G, B, taglist)
LONG ObtainBestPenA(struct ColorMap *cm, ULONG R, ULONG G,
color = ObtainBestPen(cm, r, g, b, tags....);
a0 d1 d2 d3 a1
BULONG, struct TagItem * taglist);
INPUTS
- cm
-
colormap
- R
-
red level (32 bit left justified fraction)
- G
-
green level (32 bit left justified fraction)
- B
-
blue level (32 bit left justified fraction)
- taglist
-
a pointer to a standard tag list specifying the color matching settings desired:
- OBP_Precision
-
specifies the desired precision for the match. Should be PRECISION_GUI, PRECISION_ICON, or PRECISION_IMAGE or PRECISION_EXACT. Defaults to PRECISION_IMAGE.
- OBP_FailIfBad
-
specifies that you want ObtainBestPen to return a failure value if there is not a color within the given tolerance, instead of returning the closest color. With OBP_FailIfBad==FALSE, ObtainBestPen will only fail if the ColorMap contains no sharable colors. Defaults to FALSE.
FUNCTION
This function can be used by applications to figure out what pen to use to represent a given color.
The system will attempt to find the color in your ColorMap closest to the specified color. If there is no color within your tolerance, then a new one will be allocated, if possible. If no color map entry is available for allocation, then the closest one found will be returned unless you specified through the tag OBP_FailIfBad=TRUE that -1 should be returned instead.
The system will attempt to find the color in your ColorMap closest to the specified color. If there is no color within your tolerance, then a new one will be allocated, if possible. If no color map entry is available for allocation, then the closest one found will be returned unless you specified through the tag OBP_FailIfBad=TRUE that -1 should be returned instead.
RESULT
The correct pen value, or -1. A value of -1 indicates that no sharable palette entry may be available, no palette entry is available for allocation or, if the tag OBP_FailIfBad=TRUE is used, that no palette entry is close enough to the color you asked for.
NOTES
If this call succceeds, then you must call ReleasePen() when you are done with the color.
When searching for the color which most closely matches the RGB values passed, the graphics.library default color match function will be used. You cannot override this function and you cannot influence how it will perform the matching operation.
ObtainBestPenA() applies three metrices to find the color in the ColorMap closest to the specified color, and will attempt to allocate a new color if no good match could be found.
The first metric is employed by the default color match function of graphics.library, which tests each ColorMap entry to find the one whose color comes closest to the specified color.
The second metric is based upon the number of sharable colors in the ColorMap and the number of colors left which can be allocated if there is no good match available. The more colors are still available for allocation the greater the focus on finding a good match before finally trying to allocate a free color. As the number of colors available for allocation shrinks, the greater the focus on allocating a free color will become. The desired precision for the colors to match contributes as much to this metric as the total number of sharable colors.
The third metric is controlled by the desired precision for the colors to match and will be applied when the best possible match has been found. If it fails to satisfy the specified precision, ObtainBestPenA() will attempt to allocate a new color instead.
When searching for the color which most closely matches the RGB values passed, the graphics.library default color match function will be used. You cannot override this function and you cannot influence how it will perform the matching operation.
ObtainBestPenA() applies three metrices to find the color in the ColorMap closest to the specified color, and will attempt to allocate a new color if no good match could be found.
The first metric is employed by the default color match function of graphics.library, which tests each ColorMap entry to find the one whose color comes closest to the specified color.
The second metric is based upon the number of sharable colors in the ColorMap and the number of colors left which can be allocated if there is no good match available. The more colors are still available for allocation the greater the focus on finding a good match before finally trying to allocate a free color. As the number of colors available for allocation shrinks, the greater the focus on allocating a free color will become. The desired precision for the colors to match contributes as much to this metric as the total number of sharable colors.
The third metric is controlled by the desired precision for the colors to match and will be applied when the best possible match has been found. If it fails to satisfy the specified precision, ObtainBestPenA() will attempt to allocate a new color instead.
BUGS
The default color match function in graphics.library V39-V47 pays no attention to how close two colors are in terms of hue and brightness because it lends greatest weight to the largest relative difference in any two random RGB components. This will impact fidelity and will randomly consider two colors to "match most closely" which may have little else in common.
Both the color specified and the color information stored in the ColorMap will be truncated during the search for the best match. This means that if you specify a 96 bit RGB value, only the 4 most significant bits of each color component may be checked on a system using the ECS or OCS graphics custom chips.
If ObtainBestPenA() eventually allocates a shared pen and sets the pen color, it will not use the original 96 bit RGB value specified, but a truncated version. These will be the 4 most significant bits of each color component on ECS or OCS graphics chips and the 8 most significant bits, respectively, for AGA graphics chips.
Both the color specified and the color information stored in the ColorMap will be truncated during the search for the best match. This means that if you specify a 96 bit RGB value, only the 4 most significant bits of each color component may be checked on a system using the ECS or OCS graphics custom chips.
If ObtainBestPenA() eventually allocates a shared pen and sets the pen color, it will not use the original 96 bit RGB value specified, but a truncated version. These will be the 4 most significant bits of each color component on ECS or OCS graphics chips and the 8 most significant bits, respectively, for AGA graphics chips.