Graphics and Layers Library Reference¶

graphics.library handles all pixel-level rendering: bitmaps, rastports, blitter, color, fonts, animation, and display mode management. layers.library manages clipping layers that windows are built on.

Core data structures¶

RastPort — the drawing context¶

struct RastPort {
    struct Layer *Layer;    /* layer this rastport belongs to */
    struct BitMap *BitMap;  /* bitmap to draw into */
    UBYTE *AreaInfo;        /* area fill info */
    UBYTE *TmpRas;          /* temporary raster */
    struct TextFont *Font;  /* current font */
    UBYTE_APen, BPen;       /* foreground/background pen */
    UBYTE DrMd;             /* draw mode (JAM1, JAM2, COMPLEMENT) */
    UBYTE *LinePtrn;        /* line pattern */
    /* ... */
};

Obtain from Window->RPort or create via InitRastPort().

BitMap — pixel buffer¶

struct BitMap {
    UBYTE  BytesPerRow;
    UBYTE  Rows;
    UBYTE  Flags;
    UBYTE  Depth;
    UWORD *Planes[8];  /* pointer to each bitplane */
};

V39+: use AllocBitMap(width, height, depth, flags, friendBM) which handles allocation and plane setup. Key flags: BMF_DISPLAYABLE (chip mem, display-ready), BMF_CLEAR (zeroed), BMF_INTERLEAVED.

MEMF_CHIP is mandatory for any bitmap that will be displayed, blitted by hardware, or used for audio/sprite data — only chip memory is reachable by the custom chips' DMA.

Drawing operations¶

void Move(struct RastPort *rp, LONG x, LONG y);
void Draw(struct RastPort *rp, LONG x, LONG y);
void RectFill(struct RastPort *rp, LONG xmin, LONG ymin, LONG xmax, LONG ymax);
void DrawEllipse(struct RastPort *rp, LONG xCenter, LONG yCenter, LONG a, LONG b);
void EraseRect(struct RastPort *rp, LONG xMin, LONG yMin, LONG xMax, LONG yMax);
void Flood(struct RastPort *rp, ULONG mode, LONG x, LONG y);

Drawing modes (SetDrMd): - JAM1 — draw foreground only (transparent background) - JAM2 — draw foreground + background - COMPLEMENT — XOR the pixels (useful for rubber-band lines)

Blitter (BltBitMap)¶

The blitter is a hardware DMA coprocessor for fast rectangle copies with boolean operations:

LONG BltBitMap(struct BitMap *src, LONG sx, LONG sy,
               struct BitMap *dst, LONG dx, LONG dy,
               LONG width, LONG height,
               UBYTE minterm, ULONG mask,
               ULONG tempA);

minterm is the boolean function — the 8-bit truth table for source (S), destination (D), and mask (M). Common values: 0xC0 (copy S), 0x30 (copy D = no-op), 0xFF (white fill), 0x00 (clear).

The blitter is a shared resource. OwnBlitter() / DisownBlitter() for exclusive access; QBlit() for queued blits that run during vertical blank.

Color management (V39 AA)¶

ULONG ObtainBestPens(struct ColorMap *cm, ULONG r1, ULONG g1, ULONG b1, ...);
LONG  ObtainPen(struct ColorMap *cm, ULONG pen, ULONG r, ULONG g, ULONG b, ...);
void  ReleasePen(struct ColorMap *cm, ULONG pen);
void  SetRGB32(struct ViewPort *vp, ULONG n, ULONG r, ULONG g, ULONG b);

On AA (V39+), each color gun can be up to 8 bits (from 32-bit params, only top 8 used). Pens are shared — ObtainPen()/ObtainBestPen() reserves a color register; always ReleasePen() when done. Pen sharing means your colors can be changed by other applications if you don't lock them.

Display modes (V39)¶

ULONG BestModeIDA(struct TagItem *tags);  /* find best display mode */

Tags include BIDTAG_DesiredWidth, BIDTAG_DesiredHeight, BIDTAG_Depth, BIDTAG_MonitorID. The display database (DisplayInfo) lists all available modes. FindDisplayInfo() / GetDisplayInfoData() query mode properties.

Fonts¶

struct TextFont *OpenFont(struct TextAttr *textAttr);
void CloseFont(struct TextFont *font);
void Text(struct RastPort *rp, STRPTR string, ULONG count);

TextAttr specifies font name, size, and style flags. diskfont.library extends this with outline (bullet) font support. Always CloseFont() when done.

layers.library¶

Layers are the clip-region-based clipping system that windows sit on. Key operations:

void LockLayer(struct Layer *layer);      /* HOLD THIS BRIEFLY */
void UnlockLayer(struct Layer *layer);
void LockLayerInfo(struct Layer_Info *li);
void UnlockLayerInfo(struct Layer_Info *li);

Layer locking is the #1 source of Intuition deadlocks — see Intuition Layer Locking. Never call Intuition functions while holding a layer lock.

BeginUpdate(layer) / EndUpdate(layer) convert the layer's damage list into a clip region for efficient repainting. Used inside window refresh handlers.

InstallClipRegion(layer, region) sets a custom clip region for a layer. DoHookClipRects(hook, layer, rect) calls a hook for each visible cliprect — useful for custom rendering that respects clipping.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search