Unit 'agraphics' Package
[Overview][Constants][Types][Procedures and functions][Variables][Index] [#os4units]

ObtainPen

Obtain a free palette entry for use by your program.

Declaration

Source position: agraphics.pas line 2457

function ObtainPen(

  Cm: PColorMap;

  N: LongWord;

  R: LongWord;

  G: LongWord;

  B: LongWord;

  F: LongInt

):LongInt;

Arguments

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)

Description

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.

See also

ObtainBestPenA

  

Search for the closest color match, or allocate a new one.

GetColorMap

  

Allocate and initialize Colormap

AttachPalExtra

  

Allocate and attach a palette sharing structure to a colormap

ReleasePen

  

Release an allocated palette entry to the free pool.


Documentation generated on: 2021-07-30