AROS Application Development Manual -- The Graphics Library
Index
Avis
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 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.
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);
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.
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.
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);
* Macro in graphics/gfxmacros.h
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.
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 |
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.
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.
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 |
|
|