Obtain a free palette entry for use by your program.
Source position: agraphics.pas line 2133
function ObtainPen( |
Cm: PColorMap; |
N: LongInt; |
R: LongWord; |
G: LongWord; |
B: LongWord; |
F: LongInt |
):LongWord; |
Cm |
|
A pointer to a color map created by GetColorMap(). |
N |
|
The index of the desired entry, or -1 if any one is acceptable |
R |
|
Red Value (32 bit left justified fractions) |
G |
|
Green Value (32 bit left justified fractions) |
B |
|
Blue Value (32 bit left justified fractions) |
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.
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.
|
Search for the closest color match, or allocate a new one. |
|
|
Allocate and initialize Colormap |
|
|
Allocate and attach a palette sharing structure to a colormap |
|
|
Release an allocated palette entry to the free pool. |