ObtainPen

Obtain a free palette entry for use by your program. (V39)

Attempt to allocate an entry in the colormap for use by the application. If successful, you should ReleasePen() this entry after you have finished with it.

Applications needing exclusive use of a color register (say for color cycling) will typically call this function with n=-1. Applications needing only the shared use of a color will typically use ObtainBestPenA() instead. Other uses of this function are rare.

cm

A pointer to a color map created by GetColorMap().

n

The index of the desired entry, or -1 if any one is acceptable

rgb

The RGB values (32 bit left justified fractions) to set the new palette entry to.

flags

PEN_EXCLUSIVE - tells the system that you want exclusive (non-shared) use of this pen value. Default is shared access.

PEN_NO_SETCOLOR

tells the system to not change the rgb values

for the selected pen. Really only makes sense for exclusive pens.

n

The allocated pen. -1 will be returned if there is no pen available for you.

When you allocate a palette entry in non-exclusive mode, you should not change it (via SetRGB32), because other programs on the same screen may be using it. With PEN_EXCLUSIVE mode, you can change the returned entry at will.

To avoid visual artifacts, you should not free up a palette entry until you are sure that your application is not displaying any pixels in that color at the time you free it. Otherwise, another task could allocate and set that color index, thus changing the colors of your pixels.

Generally, for shared access, you should use ObtainBestPenA() instead, since it will not allocate a new color if there is one "close enough" to the one you want already. If there is no Palextra attached to the colormap, then this routine will always fail.

GetColorMap() ReleasePen() AttachPalExtra() ObtainBestPenA()