[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]

	ObtainBestPenA --- Search for the closest color match, or allocate a
	                   new one. (V39)
	ObtainBestPen  --- varargs stub for ObtainBestPenA

	color | -1 =ObtainBestPenA(  cm,  R,   G,    B,    taglist)
	                             a0   d1   d2    d3       a1

	LONG ObtainBestPenA( struct ColorMap *, ULONG, ULONG,
			ULONG, struct TagItem *);

	color = ObtainBestPen(cm,r,g,b,tags....);

	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
	                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 ViewPort contains no sharable colors.
	                Defaults to FALSE.

	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 viewport closest
	to the specified color. If there is no color within your tolerance,
	then a new one will be allocated, if available. If none is available,
	then the closest one found will be returned.

	The correct pen value, or -1 if no sharable palette entries are available.


	If this call succceeds, then you must call ReleasePen() when you are
	done with the color.

	The error metric used for ObtainBestPen() is based on the magnitude
	squared between the two RGB values, scaled by the percentage of free

	GetColorMap() ObtainPen() ReleasePen()