Name
ReadPen -- read pen from palette object (V9.0)
Synopsis
pen = ReadPen(x, y[, t])
Function
This function reads the pen at the position specified by x and y from the currently active palette object. By default, the current display is the active palette object but of course only in case the current display is a palette mode display. See Palette mode displays for details. You can set the active palette object using the SelectPalette() command.

Alternatively, you can also use ReadPen() to read a pen from a different palette object. To do so, you need to pass the optional table argument t to ReadPen() and specify the Type and ID tags. See below for an example.

The following tags are supported by the optional table argument t:

Type:
Set this to the type identifier of the object from whose pixel data you want to read the pen. This can be one of the following object types:

 
#ANIM
#BGPIC
#BRUSH
#DISPLAY
#LAYER
#PALETTE
#SPRITE

Note that if you use types #ANIM or #SPRITE, you also need to set the Frame tag (see below) to indicate the frame whose pixel data should be used. If you use #LAYER and the specified layer is an anim layer, you also need to set the Frame tag.

Type defaults to the type of the currently active palette object selected using SelectPalette(). See SelectPalette for details.

ID:
Set this tag to the identifier of the object whose pixel data should be used. The default is the identifier of the currently active palette object set using SelectPalette(). See SelectPalette for details.

Frame:
If the target type is an animation, sprite, or anim layer, you need to set this tag to specify the frame whose pixel data should be used. Frames are counted from 1. Defaults to 1 when used with anims and sprites and to the current frame when used with anim layers.

Inputs
x
x position to read from
y
y position to read from
t
optional: table for specifying further options (see above)
Results
pen
pen at the specified position
Example
@DISPLAY {Palette = #PALETTE_MONOCHROME}
pen = ReadPen(0, 0)
The code above reads the pen in the top-left corner of the display. This will be 0 because by default, the display background will be filled using pen 0. 

pen = ReadPen(0, 0, {Type = #BRUSH, ID = 2})
The code reads the pen in the top-left corner in brush 2.
Show TOC