http://www.aros.org AROS-Exec AROS-Exec Archives Power2People
kitty mascottop logo menu

AROS Application Development Manual -- The Graphics Library

Index

Warning

This document is not finished! It is highly likely that many parts are out-of-date, contain incorrect information, or are simply missing altogether. If you want to help rectify this, please contact us.

Bitmaps

Bitmaps are the drawing sheets of AROS. Their coordinate systems have the zero point in the upper left corner. The x-axis goes from left to right, the y-axis from top to bottom. The number of possible colors depends on the depth of the bitmap:

Depth Colors
1 2
2 4
3 8
4 16
5 32
6 64
7 128
8 256
15 32,768
16 65,536
24 16,777,216

The depths from 1 to 8 are LUT (look-up-table) modes. This means the red, green, and blue (RGB) value for each color is stored in a table. The index will then be stored as pen number in the bitmap.

The depths 15 and 16 are called high color, 24 is called true color. Unlike LUT mode the RGB value is stored directly in the bitmap.

The graphics library has only a limited support for high/true color modes. Some of the drawing functions work only with LUT modes. For full access you need the functions from the cybergraphics library.

GetBitMapAttr() Query bitmap attributes. (Don't peek at bitmap.)
AllocBitMap() Allocate and initialize bitmap
InitBitMap() Initialize bitmap
FreeBitMap() Free resources allocated by a bitmap
AllocRaster() Allocate a single bitplane
FreeRaster() Free a single bitplane
CopySBitMap() Syncronize super-bitmap (see Intuition)
SyncSBitMap() Syncronize super-bitmap

RastPort

The connection between the bitmaps and most drawing functions is done by a rastport. The rastport contains information about drawing pens, line and area patterns, drawing mode and text font.

You can connect more than one rastport to a bitmap. This allows a fast switch between different drawing configurations. Just copying a rastport is not possible in AROS, however; you have to use the function CloneRastPort().

Some Intuition elements, like screens and windows, already have a RastPort element. You can immediately use that for your drawing operations.

Object Structure RastPort
screen struct Screen RastPort
window struct Window *RPort

If you create a bitmap and want to draw into it you have to create the rastport by yourself. Warning: this example is simplified and lacks checks of return values:

struct BitMap *bm = AllocBitMap(400, 300, 8, BMF_CLEAR, NULL);
struct RastPort *rp = CreateRastPort();
rp->BitMap = bm;
...
WritePixel(rp, 50, 30);
...
FreeRastPort(rp);
FreeBitMap(bm);

Pens

A rastport contains 3 pens. The A (foreground, primary) pen, B (background, secondary) pen and the O (area outline) pen. The latter is used by the area fill and flood fill functions.

Drawing modes

  • JAM1: draw only with A pen.

  • JAM2: draw bit 1 in a pattern with A pen, bit 0 with B pen

  • COMPLEMENT: for each set bit, the state in the target is reversed

  • INVERSVID: is used for text rendering
    • JAM1|INVERSVID: transparent letters outlined in foreground color
    • JAM2|INVERSVID: like previous, but letter in background color.

TODO: check whether the drawing modes are really available.

Pattern

The line pattern can be set with the macro SetDrPt(). The second parameter is a 16 bit pattern:

SetDrPt(&rastPort, 0xCCCC);

The pattern can be reset with:

SetDrPt(&rastPort, ~0);

For area patterns a macro SetAfPt() exists. The width is 16 bit, the height a power of two (2, 4, 8, 16, ...). The third parameter is the n in 2^n=height:

UWORD areaPattern[] =
{
    0x5555, 0xAAAA
};
SetAfPt(&rastPort, areaPattern, 1);

Colored patterns are possible with a negative value for the height. The number of bitplanes in the pattern must be the same as in the target bitmap.

Reset of area pattern:

SetAfPt(&rastPort, NULL, 0);
CloneRastPort() Copy rastport
CreateRastPort() Create rastport
InitRastPort() Initialize rastport
DeinitRastPort() Deinitialize rastport
FreeRastPort() Free rastport
SetAPen() Set primary pen
GetAPen() Get primary pen
SetBPen() Set secondary pen
GetBPen() Get secondary pen
SetOPen() Set area outline pen and switch outline mode on *
SetOutlinePen() Get area outline pen
GetOutlinePen() Get area outline pen
BNDRYOFF() Switch off area outline mode *
SetDrMd() Set drawing mode
GetDrMd() Get drawing mode
SetDrPt() Set line pattern *
SetAfPt() Set area pattern *
SetABPenDrMd() Set primary & secondary pen and drawing mode in one step
SetRPAttrsA() Set misc. drawing attributes
GetRPAttrsA() Get misc. drawing attributes
InitTmpRas() Initialize a TmpRas structure.
SetWriteMask() Set write mask

* Macro in graphics/gfxmacros.h

Drawing functions

A line is drawn by setting the pen position with Move() to the start position and with Draw() to the end position.

For the Flood() function you have to attach a TmpRas to the rastport as explained under Area operations.

Move() Change pen position
Draw() Draw line from pen position to given coordinates
DrawEllipse() Draw an ellipse
DrawCircle() Draw a circle (macro in graphics/gfxmacros.h)
PolyDraw() Draw connected lines from an array of points
WritePixel() Write a single pixel
ReadPixel() Read the pen value of a pixel
EraseRect() Fill rectangular area with current backfill hook (TODO: what's this?)
SetRast() Fill entire drawing area with given pen
RectFill() Fill rectangular area with current rastport settings
Flood() Flood fill an arbitrary shape

Data moving

BltBitMap() Copy rectangular area
BltBitMapRastPort() Copy rectangular area
BltRastPortBitMap() Copy rectangular area (AROS extension)
ClipBlit() Copy rectangular area with layers and clip rects. Use this if you want to blit into a window
BltClear() Set a memory block to zero. On classic Amigas this block has to be in chip ram.
BltMaskBitMapRastPort() Copy rectangular area with using a mask
BltPattern() Draw a rectangular pattern into a bitmap
BltTemplate() Draw a rectangular pattern into a bitmap
BitMapScale() Copy a rectangular area and change its size
ScalerDiv() Helper function for BitMapScale()
ScrollRaster() Move rectangular area within a bitmap
ScrollRasterBF() Move rectangular area, the vacated space is filled with EraseRect()
WriteChunkyPixels() Write rectangular area from array with pen values
WritePixelArray8() Write rectangular area from array with pen values
ReadPixelArray8() Read rectangular area into memory
WritePixelLine8() Write horiz. line from an array with pen values
ReadPixelLine8() Read horiz. line from an array into memory

Area operations

The area functions allow a fast drawing of filled polygons and ellipses.

In order to use this functions you need a struct AreaInfo which must be connected to the rastport. The area buffer must be WORD-aligned (it must have an even address). You need five bytes per vertex:

#define AREA_SIZE 200
WORD areaBuffer[AREA_SIZE];
struct AreaInfo areaInfo = {0};
memset(areabuffer, 0, sizeof(areabuffer));
InitArea(&areaInfo, areaBuffer, sizeof(areaBuffer)/5);
rastPort->AreaInfo = &areaInfo;

Additionally, you need a TmpRas structure. It should have the same width and height as the bitmap you want to draw into:

#define WIDTH 400
#define HEIGHT 300
PLANEPTR rasplane = AllocRaster(WIDTH, HEIGHT);
struct TmpRas tmpRas = {0};
InitTmpRas(&tmpRas, rasPlane, WIDTH * HEIGHT);
rastPort->TmpRas = &tmpRas;
InitArea() Initializes the AreaInfo
AreaMove() Closes open polygon and sets start point for a new one. You don't have to connect the end point to the start point.
AreaDraw() Add point to vector buffer
AreaEllipse() Add filled ellipse to vector buffer
AreaEnd() Start filling operation

Text

OpenFont() Open a font which is in the system font list. Better use OpenDiskFont() from the diskfont library.
CloseFont() Close font opened by OpenFont() or OpenDiskFont()
AddFont() Add font to the system list
RemFont() Remove font from the system list
SetFont() Set current font of rastport
AskFont() Get TextAttr for current rastport font
SetSoftStyle() Set soft style bits of current font
AskSoftStyle() Get soft style bits of current font
Text() Render text at current pen position
ClearEOL() Clear from current position to end of line
ClearScreen() Clear from current position to end of rastport
ExtendFont() Extend struct TextFont by a struct ExtendFont
StripFont() Remove tf_Extension from a font
TextLength() Calculate the width of a string in pixels. You can use TextExtent() if you need more detailed information
TextExtent() Fill TextExtend structure with information on current font
FontExtent() Fill TextExtend structure with information on given font
TextFit() Give number of characters that will fit into given bounds
WeighTAMatch() Checks how well two different fonts match

Clipping

Bitmaps you've created with AllocBitMap() don't have a clipping rectangle. This means that you trash memory when you draw outside the bitmap. You can either take care about your drawing operations or you can install a clipping rectangle. There are two possibilities:

  • Using the tag RPTAG_ClipRectangle in SetRPAttrsA():

    struct Rectangle rect = {0, 0, 399, 299};
    SetRPAttrs(&rastPort, RPTAG_ClipRectangle, &rect, TAG_DONE);
    
  • Installing a layer:

    li = NewLayerInfo())
    rastPort.Layer = CreateUpfrontLayer(li, rastPort->BitMap, 0, 0, width - 1, height - 1, 0, NULL))
    
    ...
    
    DeleteLayer(0,rastPort.Layer)
    DisposeLayerInfo(li)
    

The latter is compatible with AmigaOS.

Color

So far, only the SetXPen() functions have been used to select the drawing pens. Described here is changing the red, green blue values of the pens.

We have to distinguish between two cases:

  • The colormap belongs to you. You can change the colors as you like with the LoadRGB... and SetRGB... functions. You'll get a private colormap when we open a private screen.
  • You want to draw in a window on a public Screen. You have to query a shared pen with the ObtainBestPenA() function. Otherwise you might change the colors used by other applications.
GetColorMap() Allocate and initialize colormap
FreeColorMap() Free colormap
AttachPalExtra() Allocate and attach palette sharing structure to colormap
FindColor() Find closest matching color
ObtainBestPenA() Search for closest color match or allocate a new pen
ObtainPen() Obtain a free palette entry
ReleasePen() Frees pen created with ObtainPen()/ObtainBestPenA()
GetRGB32() Read a series of RGB values from a colormap
GetRGB4() Reads RGB value of a single color register (deprecated)
LoadRGB32() Set a series of RGB values for this viewport
LoadRGB4() Set RGB color values from an array (deprecated)
SetMaxPen() Set maximum pen value for a rastport
SetRGB32() Set one color register for a viewport
SetRGB32CM() Set one color register for a colormap
SetRGB4() Set one color register for a viewport (deprecated)
SetRGB4CM() Set one color register for a colormap (deprecated)

Animation

AddAnimOb() Add AnimObject to linked list
AddBob() Add Bob to GEL list
AddVSprite() Add VSprite to GEL list
AllocSpriteDataA() Allocate sprite data and convert from a bitmap
FreeSpriteData() Free data allocated by AllocSpriteDataA()
Animate() Processes all AnimObs in the current animation list
ChangeExtSpriteA() Change extended sprite
ChangeSprite() Change simple sprite
DoCollision() Test all GEL for collisions
DrawGList() Draw all GEL
GetGBuffers() Allocate all buffers for an AnimOb
FreeGBuffers() Release memory which was allocated by GetGBuffers()
SortGList() Sort GEL list by y and x coordinates
GetSprite() Get a simple sprite
FreeSprite() Free sprite
GetExtSpriteA() Attempt to allocate one of the 8 sprites
InitGMasks() Initialize all masks of an AnimOb
InitGels() Initialize GEL list
InitMasks() Initialize BorderLine and CollMask of a VSprite
MoveSprite() Move sprite relative to viewport
RemBob() Remove a Bob from GEL list (macro)
RemIBob() Remove a Bob from GEL list and RastPort
RemVSprite() Remove VSprite from GEL list
SetCollision() Set which is called at collisions
AllocDBufInfo() Allocate structure for multi-buffered animation
FreeDBufInfo() Free multi-buffer information
ChangeVPBitMap() Change buffer

Display database

BestModeIDA() Find a mode for the given properties
OpenMonitor() Open named monitor specification
CloseMonitor() Close monitor specification
CoerceMode() Viewport mode coercion
FindDisplayInfo() Get display information from the database
NextDisplayInfo() Iterate displayinfo
ModeNotAvailable() Check availability of a display ID
GetVPModeID() Get display ID from viewport
GfxNew() Allocate a graphics extended data structure
GfxFree() Free structure allocated by GfxNew()_
GfxAssociate() Associate a graphics extended node with a pointer
GfxLookUp() Find a graphics extended node by pointer

Blitter

DisownBlitter() Release the bitter from private use
OwnBlitter() Try to own the blitter for private use
QBSBlit() Queue a beam-synchronized blit
QBlit() Queue a blit
WaitBlit() Wait for the blitter to finish

Copper

CBump() Increment user copper list pointer
CMove() Add a copper move instruction to user copper list
CWait() Add a copper wait instruction to user copper list
FreeCopList() Deallocate all memory associated with copper list
FreeCprList() Deallocate all memory associated of cprlist structure
FreeVPortCopLists() Deallocate copperlist from viewport
MrgCop() Merge together copper instructions
UCopperListInit() Allocate & initialize copperlist structures & buffers

Miscellaneous

SetRGBConversionFunctionA() Replace pixel conversion routine
ConvertPixelsA() Convert pixels from one pixfmt to another
InitVPort() Initialize ViewPort structure
InitView() Initialize View structure
LoadView() Create current display from coprocessor instruction list
LockLayerRom() Lock layer structure
UnlockLayerRom() Unlock layer structure
MakeVPort() Create copper list for viewport
ScrollVPort() Scroll viewport
SetChipRev() Switch on chip-set features
VBeamPos() Get vertical beam position
VideoControl() Modify viewport's colormap
WaitBOVP() Wait till vertical beam reaches bottom viewport
WaitTOF() Wait for vertical blank
CalcIVG() Calculate number of blank lines above viewport

Copyright © 1995-2024, The AROS Development Team. All rights reserved.
Amiga® is a trademark of Amiga Inc. All other trademarks belong to their respective owners.