graphics.library Reference¶
Comprehensive function reference for graphics.library, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/AG/graphics).
This page documents 166 functions of graphics.library. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.
Function index¶
AddAnimOb()AddBob()AddFont()AddVSprite()AllocBitMap()AllocDBufInfo()AllocRaster()AllocSpriteDataA()AndRectRegion()AndRegionRegion()Animate()AreaCircle()AreaDraw()AreaEllipse()AreaEnd()AreaMove()AskFont()AskSoftStyle()AttachPalExtra()AttemptLockLayerRom()BestModeIDA()BitMapScale()BltBitMap()BltBitMapRastPort()BltClear()BltMaskBitMapRastPort()BltPattern()BltTemplate()CalcIVG()CBump()CEND()ChangeExtSpriteA()ChangeSprite()ChangeVPBitMap()ClearEOL()ClearRectRegion()ClearRegion()ClearScreen()ClipBlit()CloseFont()CloseMonitor()CMOVE()CMove()CoerceMode()CopySBitMap()CWAIT()CWait()DisownBlitter()DisposeRegion()DoCollision()Draw()DrawEllipse()DrawGList()EraseRect()ExtendFont()FindColor()FindDisplayInfo()Flood()FontExtent()FreeBitMap()FreeColorMap()FreeDBufInfo()FreeGBuffers()FreeRaster()FreeSprite()FreeSpriteData()GetAPen()GetBitMapAttr()GetBPen()GetColorMap()GetDisplayInfoData()GetDrMd()GetExtSpriteA()GetGBuffers()GetOutlinePen()GetRGB32()GetRGB4()GetRPAttrA()GetSprite()GetVPModeID()GfxAssociate()GfxFree()GfxLookUP()GfxNew()InitArea()InitBitMap()InitGels()InitGMasks()InitMasks()InitRastPort()InitTmpRas()InitView()InitVPort()LoadRGB32()LoadRGB4()LoadView()LockLayerRom()MakeVPort()ModeNotAvailable()Move()MoveSprite()MrgCop()NewRegion()NextDisplayInfo()ObtainBestPenA()ObtainPen()OpenFont()OpenMonitor()OrRectRegion()OrRegionRegion()OwnBlitter()PolyDraw()QBlit()QBSBlit()ReadPixel()ReadPixelArray8()ReadPixelLine8()RectFill()ReleasePen()RemBob()RemFont()RemIBob()RemVSprite()ScalerDiv()ScrollRaster()ScrollRasterBF()ScrollVPort()SetABPenDrMd()SetAPen()SetBPen()SetChipRev()SetCollision()SetDrMd()SetFont()SetMaxPen()SetOPen()SetOutlinePen()SetRast()SetRGB32()SetRGB32CM()SetRGB4()SetRGB4CM()SetRPAttrA()SetSoftStyle()SetWriteMask()SortGList()StripFont()SyncSBitMap()Text()TextExtent()TextFit()TextLength()UCopperListInit()UnlockLayerRom()VBeamPos()VideoControl()VPOrigin()WaitBlit()WaitBOVP()WaitTOF()WriteChunkyPixels()WritePixel()WritePixelArray8()WritePixelLine8()XorRectRegion()XorRegionRegion()
AddAnimOb()¶
AddAnimOb -- Add an AnimOb to the linked list of AnimObs.
Synopsis
AddAnimOb(anOb, anKey, rp)
A0 A1 A2
void AddAnimOb(AnimOb*,AnimOb**,RastPort*);
Function
Links this AnimOb into the current list pointed to by animKey. Initializes all the Timers of the AnimOb's components. Calls AddBob with each component's Bob. rp->GelsInfo must point to an initialized GelsInfo structure.
Inputs
anOb = pointer to the AnimOb structure to be added to the list anKey = address of a pointer to the first AnimOb in the list (anKey = NULL if there are no AnimObs in the list so far) rp = pointer to a valid RastPort
See also
AddBob()¶
AddBob -- Adds a Bob to current gel list.
Synopsis
AddBob(Bob, rp)
A0 A1
void AddBob(struct Bob*,RastPort*);
Function
Sets up the system Bob flags, then links this gel into the list via AddVSprite.
Inputs
Bob = pointer to the Bob structure to be added to the gel list rp = pointer to a RastPort structure
See also
AddFont()¶
AddFont -- add a font to the system list
Synopsis
AddFont(textFont)
A1
void AddFont(TextFont*);
Function
This function adds the text font to the system, making it available for use by any application. The font added must be in public memory, and remain until successfully removed.
Inputs
textFont - a TextFont structure in public ram.
Notes
This function will set the tf_Accessors to 0.
See also
AddVSprite()¶
AddVSprite -- Add a VSprite to the current gel list.
Synopsis
AddVSprite(vs, rp)
A0 A1
void AddVSprite(VSprite*,RastPort*);
Function
Sets up the system VSprite flags Links this VSprite into the current gel list using its Y,X
Inputs
vs = pointer to the VSprite structure to be added to the gel list rp = pointer to a RastPort structure
See also
AllocBitMap()¶
AllocBitMap -- Allocate a bitmap and attach bitplanes to it. (V39)
Synopsis
bitmap=AllocBitMap(sizex,sizey,depth, flags, friend_bitmap)
d0 d1 d2 d3 a0
BitMap*AllocBitMap(ULONG,ULONG,ULONG,ULONG,BitMap*);
Function
Allocates and initializes a bitmap structure. Allocates and initializes bitplane data, and sets the bitmap's planes to point to it.
Inputs
sizex = The width (in pixels) desired for the bitmap data.
CAUTION: AllocBitMap() will return NULL if the BitMap
width exceeds 32760 pixels on ECS or AGA systems.
No such check is performed on Amigas using the
original Amiga custom chipset (OCS). You should
never request a BitMap wider than 1024 pixels
on an OCS Amiga and actively prevent it from
getting created by your code!
sizey = The height (in pixels) desired.
depth = The number of bitplanes deep for the allocation.
Pixels with AT LEAST this many bits will be allocated.
flags = A combination of the following:
BMF_CLEAR to specify that the allocated raster should be
filled with color 0.
BMF_DISPLAYABLE to specify that this bitmap data should be
allocated in such a manner that it can be displayed. Displayable
data has more severe alignment restrictions than non-displayable
data in some systems.
BMF_INTERLEAVED tells graphics that you would like your bitmap to
be allocated with one large chunk of display memory for all
bitplanes. This minimizes color flashing on deep displays.
CAUTION: The BMF_INTERLEAVED flag is ignored on Amigas which
use the Original Amiga custom chipset (OCS). You
need either the ECS or AGA custom chipsets to
create interleaved BitMaps with AllocBitMap().
CAUTION: If there is not enough contiguous RAM for an
interleaved bitmap, AllocBitMap() will return NULL.
BMF_MINPLANES causes graphics to only allocate enough space in
the bitmap structure for "depth" plane pointers. This is for
system use and should not be used by applications use as it is
inefficient, and may waste memory.
BMF_RTGTAGS, BMF_RTGCHECK and BMF_FRIENDISTAG - If these three
flags are set in combination, then friend_bitmap is, actually, a
pointer to a taglist, see <utility/tagitem.h>. This taglist
contains items that defines additional parameters that may be
useful to create the bitmap (see below).
friend_bitmap = Pointer to another bitmap, or a pointer to a
'struct TagItem *' if BMF_RTGTAGS|BMF_RTGCHECK|BMF_FRIENDISTAG
flags are all set or NULL.
If this pointer is a bitmap (regular case), then the bitmap
data will be allocated in the most efficient form for blitting
to friend_bitmap.
If this pointer is a pointer to a taglist, the tags defined in
<graphics/gfx.h> may be recognized to allocate a bitmap for most
efficient usage.
Results
Returns a pointer to a 'struct BitMap' or NULL in case of failure.
NULL will be returned if there is not enough contiguous RAM
available to allocate an interleaved BitMap. Even if there is still
nominally enough RAM available, the constraints of an interleaved
BitMap render it unusable.
NULL will be returned if the requested BitMap width exceeds
32760 pixels on an ECS or AGA system.
Notes
When allocating using a friend bitmap, it is not safe to assume anything about the structure of the bitmap data if that friend BitMap might not be a standard amiga bitmap.
For instance, if the workbench is running on a non-amiga display
device, its Screen->RastPort->BitMap won't be in standard Amiga
format. The only safe operations to perform on a non-standard BitMap
are:
- blitting it to another bitmap, which must be either a standard
Amiga bitmap, or a friend of this bitmap.
- blitting from this bitmap to a friend bitmap or to a standard
Amiga bitmap.
- attaching it to a rastport and making rendering calls.
Good arguments to pass for the friend_bitmap are your window's
RPort->BitMap, and your screen's RastPort->BitMap. Do NOT pass
&(screenptr->BitMap)!
BitMaps not allocated with BMF_DISPLAYABLE may not be used as
Intuition Custom BitMaps or as RasInfo->BitMaps. They may be blitted
to a BMF_DISPLAYABLE BitMap, using one of the BltBitMap() family of
functions.
The taglist which AllocBitMap() accepts with the flag combination of
BMF_RTGTAGS|BMF_RTGCHECK|BMF_FRIENDISTAG uses tag IDs that are
intentionally identical to those of OpenScreenTagList().
It is good practise, which is in fact followed by intuition V47, to
pass over the taglist used for creating a screen to this function to
receive a bitmap that is suitable for the specific mode ID and screen
dimensions.
Bugs
Interleaved BitMaps are a crucial building block of the Amiga graphics system and its hardware. You are bound to make use of them, but you should be aware of their limitations and the constraints which govern their proper use.
Exceeding these limitations will lead to software errors and data
corruption, whose causes are difficult to track down. The
graphics.library Blitter functions do not provide protection against
accidental misuse.
Make no mistake: These constraints are subtle because interleaved
BitMaps are not merely an extension of the BitMaps which
you are already familiar with. There are side-effects
which must be accounted for.
The AllocBitMap() function was introduced in Kickstart 3.0. Prior to
this the creation of a BitMap suitable for both display purposes and
Blitter operations went along the following steps:
struct BitMap bm;
int width = 320, height = 200, depth = 4;
int i;
/* This will yield bm.BytesPerRow == 2 * ((320 + 15)) / 16 == 40.
* You need to add 40 bytes to the address of a bit plane row
* to access the next row.
*/
InitBitMap(&bm, width, height, depth);
for (i = 0 ; i < depth ; i++)
bm.Planes[i] = AllocRaster(width, height);
The memory bandwidth requirements of the AGA chipset made it
necessary for bit planes not to be allocated separately, as
illustrated by this example.
Preferably, the memory contents representing each line of graphics
should be close by so that the display hardware could fetch all of it
in a single sweep. This is what the interleaved bitmap format enables
and why the AllocBitMap() function exists which creates this special
type of BitMap.
* For the BitMap "interleaving" means that all the planes of a single
BitMap row directly follow one another in memory. For an
interleaved BitMap the BitMap.BytesPerRow value will be affected by
the BitMap depth. For the example above which constructed a BitMap
using InitBitMap() and AllocRaster() you would find that invoking
AllocBitMap() with width=320, depth=4 and requesting the BitMap to
be interleaved, the BitMap.BytesPerRow value will be 4 * 40 = 160
bytes instead of 40.
CAUTION: The number of bytes per row are no longer both the row
modulus and an indication of the width of each row for an
interleaved BitMap.
* AllocBitMap() allocates the interleaved plane data, taking
alignment requirements into account (e.g. AGA requires that each
row of image data must be aligned to a 64 bit address, i.e. a
multiple of 8 bytes), in a single consecutive chunk.
CAUTION: Memory fragmentation constraints may cause the allocation
to fail entirely.
* The ECS and AGA Blitter cannot handle BitMaps with BytesPerRow
values exceeding 4095 bytes. Which means that interleaved BitMaps
on the ECS and AGA chipsets are constrained to
width * depth <= 4095 (approximately).
The maximum BitMap height which the Blitter can access is reduced,
too. For the ECS and AGA chipsets the height is limited
to 32768 / depth pixels (approximately).
CAUTION: AllocBitMap() permits you to allocate BitMaps which
exceed these dimensions. But you should be aware that you
may be unable to use them with the Blitter when running on
a system which exclusively uses the Amiga custom chipset.
For Amigas which use the original chipset (OCS) no
sanity check is performed when BitMaps wider than 1024
pixels are requested. The operating system will try to
satisfy your request even though the resulting BitMap will
be unsafe to use. You should catch such cases before the
call to AllocBitMap() is made!
If you still try, the results may lead to software errors
and data corruption.
See also
FreeBitMap(), LoadRGB32(), OpenScreenTagList()
AllocDBufInfo()¶
AllocDBufInfo -- Allocate structure for multi-buffered animation (V39)
Synopsis
AllocDBufInfo(vp)
a0
DBufInfo* AllocDBufInfo(ViewPort*)
Function
Allocates a structure which is used by the ChangeVPBitMap() routine.
Inputs
vp = A pointer to a ViewPort structure.
Notes
Returns 0 if there is no memory available or if the display mode of the viewport does not support double-buffering.
The only fields of the DBufInfo structure which can be used by application
programs are the dbi_SafeMessage, dbi_DispMessage, dbi_UserData1 and
dbi_UserData2 fields.
dbi_SafeMessage and dbi_DispMessage are standard exec message structures
which may be used for synchronizing your animation with the screen update.
dbi_SafeMessage is a message which is replied to when it is safe to write to
the old BitMap (the one which was installed when you called ChangeVPBitMap).
dbi_DispMessage is replied to when it is safe to call ChangeVPBitMap again
and be certain that the new frame has been seen at least once.
The dbi_UserData1 and dbi_UserData2 fields, which are stored after each
message, are for your application to stuff any data into that it may need
to examine when looking at the reply coming into the ReplyPort for either
of the embedded Message structures.
DBufInfo structures MUST be allocated with this function. The size of
the structure will grow in future releases.
The following fragment shows proper double buffering synchronization:
int SafeToChange=TRUE, SafeToWrite=TRUE, CurBuffer=1;
struct MsgPort *ports[2]; /* reply ports for DispMessage and SafeMessage
/ struct BitMap BmPtrs[2]; struct DBufInfo *myDBI;
... allocate bitmap pointers, DBufInfo, set up viewports, etc.
myDBI->dbi_SafeMessage.mn_ReplyPort=ports[0];
myDBI->dbi_DispMessage.mn_ReplyPort=ports[1];
while (! done)
{
if (! SafeToWrite)
while(! GetMsg(ports[0])) Wait(1l<<(ports[0]->mp_SigBit));
SafeToWrite=TRUE;
... render to bitmap # CurBuffer.
if (! SafeToChange)
while(! GetMsg(ports[1])) Wait(1l<<(ports[1]->mp_SigBit));
SafeToChange=TRUE;
WaitBlit(); /* be sure rendering has finished */
ChangeVPBitMap(vp,BmPtrs[CurBuffer],myDBI);
SafeToChange=FALSE;
SafeToWrite=FALSE;
CurBuffer ^=1; /* toggle current buffer */
}
if (! SafeToChange) /* cleanup pending messages */
while(! GetMsg(ports[1])) Wait(1l<<(ports[1]->mp_SigBit));
if (! SafeToWrite) /* cleanup */
while(! GetMsg(ports[0])) Wait(1l<<(ports[0]->mp_SigBit));
See also
FreeDBufInfo(), ChangeVPBitMap()
AllocRaster()¶
AllocRaster -- Allocate space for a native bitplane.
Synopsis
planeptr = AllocRaster( width, height )
d0 d0 d1
PLANEPTR AllocRaster(ULONG,ULONG);
Function
This function calls the memory allocation routines to allocate memory space for a native bitplane "width" bits wide and "height" bits high.
Inputs
width - number of columns in bitplane height - number of rows in bitplane
Results
planeptr - pointer to first word in bitplane, or NULL if it was not possible to allocate the desired amount of memory.
Notes
This function is only able to allocate memory for native, off-screen (non-displayable) bitmaps. It is not able to align memory correctly for all display modes, or RTG (retargetable graphics) modes. In almost all cases, AllocBitMap() should be preferred, as it ensures proper alignment, allocation and initialization of display memory that is to be attached to a ViewPort or Screen.
See also
AllocSpriteDataA()¶
AllocSpriteDataA -- allocate sprite data and convert from a bitmap. (V39) AllocSpriteData -- varargs stub for AllocSpriteData(). (V39)
Synopsis
SpritePtr | 0 = AllocSpriteDataA(bitmap,taglist)
d0 a2 a1
struct ExtSprite*AllocSpriteDataA(BitMap*,TagItem* );
extsprite=AllocSpriteData(bitmap,tags,...TAG_END)
Function
Allocate memory to hold a sprite image, and convert the passed-in bitmap data to the appropriate format. The tags allow specification of width, scaling, and other options.
Inputs
bitmap - ptr to a bitmap. This bitmap provides the source data for the sprite image.
tags -
SPRITEA_Width specifies how many pixels wide you desire
the sprite to be. Specifying a width wider than the hardware
can handle will cause the function to return failure. If the
bitmap passed in is narrower than the width asked for, then
it will be padded on the right with transparent pixels.
Defaults to 16.
SPRITEA_XReplication controls the horizontal pixel replication factor
used when converting the bitmap data. Valid values are:
0 - perform a 1 to 1 conversion
1 - each pixel from the source is replicated twice
in the output.
2 - each pixel is replicated 4 times.
-1 - skip every other pixel in the source bitmap
-2 - only include every fourth pixel from the source.
This tag is useful for converting data from one resolution
to another. For instance, hi-res bitmap data can be correctly
converted for a lo-res sprite by using an x replication factor
of -1. Defaults to 0.
SPRITEA_YReplication controls the vertical pixel replication factor
in the same manner as SPRITEA_XReplication controls the horizontal.
SPRITEA_OutputHeight specifies how tall the resulting sprite
should be. Defaults to the bitmap height. The bitmap MUST be at
least as tall as the output height.
SPRITEA_Attached tells the function that you wish to convert
the data for the second sprite in an attached sprite pair.
This will cause AllocSpriteData() to take its data from the
3rd and 4th bitplanes of the passed in bitmap.
Bitplane data is not required to be in chip ram for this function.
Results
SpritePtr = a pointer to a ExtSprite structure, or 0 if there is a failure. You should pass this pointer to FreeSpriteData() when finished with the sprite.
Bugs
Under V39, the appropriate attach bits would not be set in the sprite data. The work-around is to set the bits manually. Bit 7 of the second word should be set. On a 32 bit sprite, bit 7 of the 3rd word should also be set. For a 64 bit sprite, bit 7 of the 5th word should also be set. This should NOT be done under V40, as the bug is fixed.
See also
FreeSpriteData(), FreeSprite(), ChangeSprite(), MoveSprite(), GetExtSpriteA(), AllocBitMap()
AndRectRegion()¶
AndRectRegion -- Perform 2d AND operation of rectangle with region, leaving result in region.
Synopsis
AndRectRegion(region,rectangle)
a0 a1
BOOL AndRectRegion(Region*,Rectangle* );
Function
Clip away any portion of the region that exists outside of the rectangle. Leave the result in region.
Inputs
region - pointer to Region structure rectangle - pointer to Rectangle structure
Results
a boolean success indicator. In case the result is FALSE, the region remained untouched.
Notes
Unlike the other rect-region primitives, AndRectRegion() cannot fail.
Bugs
Releases up to V40 did not return a success indicator, but may have failed in out-of-memory situation nevertheless. V40 releases and before may have left the region in an inconsistent state in case of failure.
See also
AndRegionRegion(), OrRectRegion()
AndRegionRegion()¶
AndRegionRegion -- Perform 2d AND operation of one region with second region, leaving result in second region.
Synopsis
status = AndRegionRegion(region1,region2)
d0 a0 a1
BOOL AndRegionRegion(Region*,Region* );
Function
Remove any portion of region2 that is not in region1.
Inputs
region1 - pointer to Region structure region2 - pointer to Region structure to use and for result
Results
status - return TRUE if successful operation return FALSE if ran out of memory
Bugs
In case of failure, the target region may be partially updated.
See also
OrRegionRegion(), AndRectRegion()
Animate()¶
Animate -- Processes every AnimOb in the current animation list.
Synopsis
Animate(anKey, rp)
A0 A1
void Animate(AnimOb**,RastPort*);
Function
For every AnimOb in the list - update its location and velocities - call the AnimOb's special routine if one is supplied - for each component of the AnimOb - if this sequence times out, switch to the new one - call this component's special routine if one is supplied - set the sequence's VSprite's y,x coordinates based on whatever these routines cause
Inputs
ankey = address of the variable that points to the head AnimOb rp = pointer to the RastPort structure
See also
AreaCircle()¶
AreaCircle -- add a circle to areainfo list for areafill.
Synopsis
error = (int) AreaCircle( rp, cx, cy, radius)
D0 A1 D0 D1 D2
ULONG AreaCircle(RastPort*, WORD, WORD, UWORD);
Function
Add circle to the vector buffer. It will be drawn to the rastport when AreaEnd is executed.
Inputs
rp - pointer to a RastPort structure
cx, cy - the coordinates of the center of the desired circle.
radius - is the radius of the circle to draw around the centerpoint.
Results
0 if no error -1 if no space left in vector list
Notes
This function is actually a macro which calls AreaEllipse(rp,cx,cy,radius,radius).
See also
AreaMove(), AreaDraw(), InitArea(), AreaEnd()
AreaDraw()¶
AreaDraw -- Add a point to a list of end points for areafill.
Synopsis
error = AreaDraw( rp, x, y)
d0 A1 D0:16 D1:16
ULONG AreaDraw(RastPort*, SHORT, SHORT);
Function
Add point to the vector buffer.
Inputs
rp - points to a RastPort structure. x,y - are coordinates of a point in the raster.
Results
error - zero for success, else -1 if no there was no space left in the vector list.
See also
AreaMove(), InitArea(), AreaEnd()
AreaEllipse()¶
AreaEllipse -- add a ellipse to areainfo list for areafill.
Synopsis
error = AreaEllipse( rp, cx, cy, a, b )
d0 a1 d0:16 d1:16 d2:16 d3:16
LONG AreaEllipse(RastPort*, SHORT, SHORT, SHORT, SHORT)
Function
Add an ellipse to the vector buffer. It will be draw when AreaEnd() is called.
Inputs
rp - pointer to a RastPort structure cx - x coordinate of the centerpoint relative to the rastport. cy - y coordinate of the centerpoint relative to the rastport. a - the horizontal radius of the ellipse (note: a must be > 0) b - the vertical radius of the ellipse (note: b must be > 0)
Results
error - zero for success, or -1 if there is no space left in the vector list
See also
AreaMove(), AreaDraw(), AreaCircle(), InitArea(), AreaEnd()
AreaEnd()¶
AreaEnd -- Process table of vectors and ellipses and produce areafill.
Synopsis
error = AreaEnd(rp)
d0 A1
LONG AreaEnd(RastPort* );
Function
Trigger the filling operation. Process the vector buffer and generate required fill into the raster planes. After the fill is complete, reinitialize for the next AreaMove or AreaEllipse. Use the raster set up by InitTmpRas when generating an areafill mask.
Inputs
rp - pointer to a RastPort structure which specifies where the filled regions will be rendered to.
Results
error - zero for success, or -1 if an error occurred anywhere.
See also
InitArea(), AreaMove(), AreaDraw(), AreaEllipse(), InitTmpRas()
AreaMove()¶
AreaMove -- Define a new starting point for a new shape in the vector list.
Synopsis
error = AreaMove( rp, x, y)
d0 a1 d0:16 d1:16
LONG AreaMove(RastPort*, SHORT, SHORT );
Function
Close the last polygon and start another polygon at (x,y). Add the necessary points to vector buffer. Closing a polygon may result in the generation of another AreaDraw() to close previous polygon. Remember to have an initialized AreaInfo structure attached to the RastPort.
Inputs
rp - points to a RastPort structure x,y - positions in the raster
See also
InitArea(), AreaDraw(), AreaEllipse(), AreaEnd()
AskFont()¶
AskFont -- get the text attributes of the current font
Synopsis
AskFont(rp, textAttr)
A1 A0
void AskFont(RastPort*,TextAttr*);
Function
This function fills the text attributes structure with the attributes of the current font in the RastPort.
Inputs
rp - the RastPort from which the text attributes are extracted textAttr - the TextAttr structure to be filled. Note that there is no support for a TTextAttr.
Results
The textAttr structure is filled with the RastPort's text attributes.
AskSoftStyle()¶
AskSoftStyle -- Get the soft style bits of the current font.
Synopsis
enable = AskSoftStyle(rp)
D0 A1
ULONG AskSoftStyle(RastPort*);
Function
This function returns those style bits of the current font that are not intrinsic in the font itself, but algorithmically generated. These are the bits that are valid to set in the enable mask for SetSoftStyle().
Inputs
rp - the RastPort from which the font and style are extracted.
Results
enable - those bits in the style algorithmically generated. Style bits that are not defined are also set.
See also
AttachPalExtra()¶
AttachPalExtra -- Allocate and attach a palette sharing structure to a colormap. (V39)
Synopsis
status=AttachPalExtra( cm, vp)
a0 a1
LONG AttachPalExtra( Struct ColorMap *,ViewPort*);
Function
Allocates and attaches a PalExtra structure to a ColorMap. This is necessary for color palette sharing to work. The PalExtra structure will be freed by FreeColorMap(). The set of available colors will be determined by the mode and depth of the viewport.
Inputs
cm = A pointer to a color map created by GetColorMap().
vp = A pointer to the viewport structure associated with
the ColorMap.
Results
status - 0 if sucessful, else an error number. The only currently defined error number is out of memory (1).
Notes
This function is for use with custom ViewPorts and custom ColorMaps, as Intuition attaches a PalExtra to all of its Screens. If there is already a PalExtra associated with the ColorMap, then this function will do nothing.
See also
GetColorMap(), FreeColorMap(), ObtainPen(), ObtainBestPenA()
AttemptLockLayerRom()¶
AttemptLockLayerRom -- Attempt to Lock Layer structure by ROM(gfx lib) code
Synopsis
gotit = AttemptLockLayerRom( layer )
d0 a5
BOOL AttempLockLayerRom(Layer* );
Function
Query the current state of the lock on this Layer. If it is already locked then return FALSE, could not lock. If the Layer was not locked then lock it and return TRUE. This call does not destroy any registers. This call nests so that callers in this chain will not lock themselves out.
Inputs
layer - pointer to Layer structure
Results
gotit - TRUE or FALSE depending on whether the Layer was successfully locked by the caller.
See also
LockLayerRom(), UnlockLayerRom()
BestModeIDA()¶
BestModeIDA -- calculate the best ModeID with given parameters (V39) BestModeID -- varargs stub for BestModeIDA()
Synopsis
ID = BestModeIDA(TagItems)
d0 a0
ULONG BestModeIDA(TagItem*);
ID = BestModeID(Tag1, ...)
ULONG BestModeID(ULONG, ...);
Function
To determine the best ModeID to fit the parameters set in the TagList.
Inputs
TagItems - A pointer to an array of TagItems.
Results
ID - ID of the best mode to use, or INVALID_ID if a match could not be found.
Notes
This function takes into account the Compatability of the Monitor being matched to, and the source ViewPort or ModeID. Incompatibilitys will cause a result of INVALID_ID.
BIDTAG_NominalWidth, BIDTAG_NominalHeight,
BIDTAG_DesiredWidth, BIDTAG_DesiredHeight, must all be non-0.
The comparisons are made against the DimensionInfo->Nominal values.
ie, this will not return a best fit against overscan dimensions.
Example
IFF Display Program with a HAM image, to be displayed in the same monitor type as the Workbench ViewPort.
ID = BestModeID(BIDTAG_NominalWidth, IFFImage->Width,
BIDTAG_NominalHeight, IFFImage->Height,
BIDTAG_Depth, IFFImage->Depth,
BIDTAG_DIPFMustHave, DIPF_IS_HAM,
BIDTAG_MonitorID, (GetVPModeID(WbVP) & MONITOR_ID_MASK),
TAG_END);
To make an interlace version of a ViewPort:
ID = BestModeID(BIDTAG_ViewPort, ThisViewPort,
BIDTAG_MustHave, DIFP_IS_LACE,
TAG_END);
BitMapScale()¶
BitMapScale -- Perform raster scaling on a bit map. (V36)
Synopsis
BitMapScale(bitScaleArgs)
A0
void BitMapScale(BitScaleArgs*);
Function
Scale a source bit map to a non-overlapping destination bit map.
Inputs
bitScaleArgs - structure of parameters describing scale: bsa_SrcX, bsa_SrcY - origin of the source bits. bsa_SrcWidth, bsa_SrcHeight - number of bits to scale from in x and y. bsa_DestX, bsa_DestY - origin of the destination. bsa_DestWidth, bsa_DestHeight - resulting number of bits in x and y. NOTE: these values are set by this function. bsa_XSrcFactor:bsa_XDestFactor - equivalent to the ratio srcWidth:destWidth, but not necessarily the same numbers. Each must be in the range 1..16383. bsa_YSrcFactor:bsa_YDestFactor - equivalent to the ratio srcHeight:destHeight, but not necessarily the same numbers. Each must be in the range 1..16383. bsa_SrcBitMap - source of the bits to scale. bsa_DestBitMap - destination for the bits to scale. This had better be big enough! bsa_Flags - future scaling options. Set it to zero! bsa_XDDA, bsa_YDDA - for future use. Need not be set by user. bsa_Reserved1, bsa_Reserved2 - for future use. Need not be set.
Results
The destWidth, destHeight fields are set by this function as described above.
Notes
o This function may use the blitter. o Overlapping source and destination bit maps are not supported. o No check is made to ensure destBitMap is big enough: use ScalerDiv to calculate a destination dimension.
Bugs
o This function does not use the HighRes Agnus 'Big Blit' facility. You should not use XSrcFactor == XDestFactor, where SrcWidth or DestWidth > 1024.
o Also, the blitter is used when expanding in the Y direction.
You should not expand in the Y direction if
((DestX & 0xf) + DestWidth) >= 1024 pixels. (Up to 1008 pixels
is always safe).
See also
BltBitMap()¶
BltBitMap -- Copy or change a rectangular region of bits in a BitMap; these bits are typically pixels.
Synopsis
planecnt = BltBitMap(SrcBitMap, SrcX, SrcY, DstBitMap,
D0 A0 D0:16 D1:16 A1
DstX, DstY, SizeX, SizeY, Minterm, Mask, TempA)
D2:16 D3:16 D4:16 D5:16 D6:8 D7:8 A2
ULONG BltBitMap(BitMap*, WORD, WORD,BitMap*,
WORD, WORD, WORD, WORD, UBYTE, UBYTE, UWORD *);
Function
Perform a blit operation which copies a rectangle from one area in a BitMap to a different BitMap, or within the same BitMap. Depending upon the Minterm used, the operation may ignore the source BitMap and change the destination BitMap.
Inputs
SrcBitMap, DstBitMap - The BitMap(s) containing the rectangles to be copied or changed.
- The planes copied from the source to the destination are
only those whose plane numbers are identical and less
than the minimum Depth of either BitMap and whose Mask
bit for that plane is non-zero.
- As a special case, if a plane pointer in the SrcBitMap
is NULL, it acts as a pointer to a plane of all zeros, and
if the plane pointer is 0xffffffff, it acts as a pointer
to a plane of all ones. (Note: new for V36)
- SrcBitMap and DstBitMap can be identical if they point
to actual planes. This means that you may use plane
pointers of NULL or 0xffffffff only in the source, but
never in the destination BitMap.
- The blit operation combines the contents of the SrcBitMap
and the DstBitMap, storing the result in the DstBitMap.
Unless the area of effect for the blit operation is in
the same BitMap (SrcBitMap and DstBitMap being identical)
the source will never be modified.
SrcX, SrcY - The x and y coordinates of the upper left corner
of the source rectangle. Valid range is positive
signed integer such that the raster word's offset
0..(32767-Size)
DstX, DstY - The x and y coordinates of the upper left
corner of the destination for the rectangle. Valid
range is as for SrcX and SrcY, respectively.
SizeX, SizeY - The size of the rectangle to be copied or changed.
For the original Amiga chipset (OCS) the range is limited
to X: 1..992 and Y: 1..1024. For the ECS and AGA chipsets the
range is limited for X and Y both to 1..32768.
Minterm - The logic function to apply to the rectangle. See the
NOTES section for an explanation of what minterm values are
supported and which effects they will have.
Mask - The write mask to apply to this operation. Bits set
indicate the corresponding planes (if not greater than
the minimum plane count) are to participate in the
operation. Typically this is set to 0xff, which will
copy or change up 8 planes.
TempA - If the copy overlaps exactly to the left or right
(i.e. the scan line addresses overlap), and TempA is
not NULL, it points to enough chip accessible memory
to hold a line of A source for the blit (i.e. CHIP RAM).
BltBitMap will allocate (and free) the needed TempA if
none is provided (TempA == NULL) and one is needed.
Blit overlap is determined from the relation of the first
non-masked planes in the source and destination bit maps.
See the NOTES section for an explanation on why and how
you would allocate chip accessible memory.
Results
planecnt - the number of planes actually involved in the blit.
Notes
This function may use the blitter.
See also
AllocBitMap(), ClipBlit(), BltBitMapRastPort(), BltMaskBitMapRastPort(), WaitBlit()
BltBitMapRastPort()¶
BltBitMapRastPort -- Blit from source BitMap to destination RastPort.
Synopsis
success = BltBitMapRastPort
(srcbm, srcx, srcy, destrp, destX, destY, sizeX, sizeY, minterm)
D0 A0 D0 D1 A1 D2 D3 D4 D5 D6
BOOL BltBitMapRastPort
(BitMap*, WORD, WORD,RastPort*, WORD, WORD,
WORD, WORD, UBYTE);
Function
Blits from source BitMap to position specified in destination RastPort using minterm.
Inputs
srcbm - a pointer to the source bitmap srcx - x offset into source bitmap srcy - y offset into source bitmap destrp - a pointer to the destination rastport destX - x offset into dest rastport destY - y offset into dest rastport sizeX - width of blit in pixels sizeY - height of blit in rows minterm - minterm to use for this blit
Results
This function always returns TRUE, starting with Kickstart 1.2 (V33).
Prior releases could run out of memory when handling overlapping blit
operations and, if this occured, would return FALSE to indicate failure.
See also
BltBitMap(), BltMaskBitMapRastPort(), ClipBlit()
BltClear()¶
BltClear - Clear a block of memory words to zero.
Synopsis
BltClear( memBlock, bytecount, flags )
a1 d0 d1
void BltClear( void *, ULONG, ULONG );
Function
For memory that is local and blitter accessible, the most efficient way to clear a range of memory locations is to use the system's most efficient data mover, the blitter. This command accepts the starting location and count and clears that block to zeros.
Inputs
memBloc - pointer to local memory to be cleared memBlock is assumed to be even. flags - set bit 0 to force function to wait until the blit is done. set bit 1 to use row/bytesperrow.
bytecount - if (flags & 2) == 0 then
even number of bytes to clear.
else
low 16 bits is taken as number of bytes
per row and upper 16 bits taken as
number of rows.
This function is somewhat hardware dependent. In the rows/bytesperrow
mode (with the pre-ECS blitter) rows must be <- 1024. In bytecount mode
multiple runs of the blitter may be used to clear all the memory.
Set bit 2 to use the upper 16 bits of the Flags as the data to fill
memory with instead of 0 (V36).
Results
The block of memory is initialized.
BltMaskBitMapRastPort()¶
BltMaskBitMapRastPort -- blit from source BitMap to destination RastPort with masking of source image. The mask acts like a stencil or frisket. (V33)
Synopsis
BltMaskBitMapRastPort
(srcbm, srcx, srcy, destrp, destX, destY, sizeX, sizeY,
A0 D0 D1 A1 D2 D3 D4 D5
minterm, bltmask)
D6 A2
void BltMaskBitMapRastPort
(BitMap*, WORD, WORD,RastPort*, WORD, WORD,
WORD, WORD, UBYTE, APTR);
Function
Blits from source BitMap to position specified in destination RastPort using bltmask to determine where source overlays destination, and minterm to determine whether to copy the source image "as is" or to "invert" the sense of the source image when copying.
In either case, blit only occurs where a bit in the mask is non-zero.
The mask acts like a stencil or frisket, so that only the destination
area will be affected for which the mask has a pixel set to 1.
Inputs
srcbm - A pointer to the source BitMap srcx - X offset into source BitMap srcy - Y offset into source BitMap destrp - A pointer to the destination RastPort destX - X offset into destination RastPort destY - Y offset into destination RastPort sizeX - Width of blit in pixels sizeY - Height of blit in rows minterm - Either (ABC|ABNC|ANBC) if copy source and blit thru mask or (ANBC) if invert source and blit thru mask bltmask - Pointer to the single bit-plane mask, which must be the same size and dimensions as the planes of the source BitMap, i.e. as wide and high as the source.
CAUTION: The bltmask plane must reside in chip memory.
It can be created with AllocRaster().
Notes
WHY IMAGE CORRUPTION CAN OCCUR IN KICKSTART 3.0 AND 3.1
The BltMaskBitMapRastPort() function's chief purpose is to render images
such as Workbench icons, painting in only the shape covered by the bltmask
and leaving the rest unchanged.
The Amiga Blitter would be able to conveniently handle blitting an image
through a mask to the destination BitMap, but BltMaskBitMapRastPort() has
to make use of the BltBitMap() function which features only two source
bitmaps, with the second source also being the destination.
For this reason the "simple" blit operation has to be broken down into
a sequence of three individual blits, which is why it might flicker a
little when performed.
Because BltBitMap() is used, a temporary BitMap will be constructed using
the bltmask plane. This works well enough for standard format planar
image data such as used by intuition.library/DrawImage but there are
problems when using an interleaved source BitMap. A bug in the V39/V40
BltMaskBitMapRastPort() function caused the temporary BitMap constructed
using the bltmask plane to be both too wide and too tall for the mask
data available.
Interleaved BitMaps are typically featuring BitMap.BytesPerRow values much
greater than what the InitBitMap() function would fill in. Please see the
AllocBitMap() documentation for a detailed description of how interleaved
BitMaps work.
Because the bltmask plane is supposed to be created in the manner
documented for Kickstart 1.0-2.04 (see the RASSIZE() macro in
<graphics/gfx.h> and the AllocRaster() documentation) it will appear to
be both narrower and shorter than the interleaved srcbm BitMap. This
accounts for the apparent corruption of the image copied: the mask no
longer exactly matches the dimensions (width and height) of the interleaved
srcbm BitMap.
WORKAROUND FOR AVOIDING THE IMAGE CORRUPTION
A workaround which saw wider use in 1992 and beyond (Kickstart versions
3.0 and 3.1) has side-effects and will only work with a graphics.library
which features the image corruption bug. Put another way, it "works
correctly" only under the assumption that the BltMaskBitMapRastPort()
function *does not work correctly*.
Because the width of the bltmask plane does not match the interleaved
srcbm BitMap, it was discovered that you could make it fit by allocating
the plane in a specific manner:
struct BitMap * sourcebm;
PLANEPTR bltmask;
if ((GetBitMapAttr(sourcebm, BMA_FLAGS) & BMF_INTERLEAVED) != 0)
bltmask = AllocMem(sourcebm->BytesPerRow * sourcebm->Rows, MEMF_CHIP);
else
bltmask = AllocRaster(GetBitMapAttr(sourcebm, BMA_WIDTH),
GetBitMapAttr(sourcebm, BMA_HEIGHT));
This workaround is discouraged for three reasons. The first being that
assumptions are made about the contents of a BitMap created through the
AllocBitMap() function. These assumptions are bound not to hold because
of how retargetable graphics (RTG) may store the image data.
The second reason is that you cannot determine in advance and with
confidence if the BltMaskBitMapRastPort() bug fix is in effect. If it
is, then the workaround will produce a corrupted image which is what
the workaround was intended to avoid. The third reason is that RTG
systems may not make the same assumptions about the bltmask plane
as the graphics.library internals, which may lead to corruption.
WHY ONLY THE TWO PROVIDED MINTERM VALUES ARE USEFUL
As mentioned above, the blit operation performed by the
BltMaskBitMapRastPort() function has to be broken down into a sequence
of three individual BltBitMap() calls. These blits are designed to be
performed in such a manner that the same results will be achieved as
if a single blit operation using two sources and a separate destination
were performed.
In order to conserve ROM space, the minterms chosen are optimized for
two cases only. This being "copying the source image through a mask"
with (ABC|ABNC|ANBC) as the minterm and "copy the inverted source image
through a mask" with the mintern (ANBC). While the BltMaskBitMapRastPort()
function does not enforce the use of these two documented minterms, no
other minterms achieve such outcomes (note that because BltBitMap() does
not use source A, minterms which use logic terms that employ A or ~A
will produce identical results).
Bugs
BltMaskBitMapRastPort() is limited to a maximum of 8 bit planes in V33-V44. If the BitMaps involved use more than these, data corruption and undefined behaviour will follow.
This function did not work properly in V39 and V40 if the srcbm
BitMap was interleaved. In such a case, the mask was erroneously
expected to be as wide as 8 * srcbm->BytesPerRow pixels.
This was fixed in V45.
See also
AllocBitMap(), AllocRaster(), BltBitMap(), BltBitMapRastPort(), ClipBlit(), DrawImage(), GetBitMapAttr()
BltPattern()¶
BltPattern -- Using standard drawing rules for areafill, blit through a mask.
Synopsis
BltPattern(rp, mask, xl, yl, maxx, maxy, bytecnt)
a1, a0 d0 d1 d2 d3 d4
void BltPattern
(RastPort*, void *, SHORT, SHORT, SHORT, SHORT, SHORT);
Function
Blit using drawmode,areafill pattern, and mask at position rectangle (xl,yl) (maxx,maxy).
Inputs
rp - points to the destination RastPort for the blit. mask - points to 2 dimensional mask if needed if mask == NULL then use a rectangle. xl,yl - coordinates of upper left of rectangular region in RastPort maxx,maxy - points to lower right of rectangular region in RastPort bytecnt - BytesPerRow for mask
See also
BltTemplate()¶
BltTemplate -- Cookie cut a shape in a rectangle to the RastPort.
Synopsis
BltTemplate(SrcTemplate, SrcX, SrcMod, rp,
A0 D0:16 D1:16 A1
DstX, DstY, SizeX, SizeY)
D2:16 D3:16 D4:16 D5:16
void BltTemplate(UWORD *, WORD, WORD,RastPort*,
WORD, WORD, WORD, WORD);
Function
This function draws the image in the template into the RastPort in the current color and drawing mode at the specified position. The template is assumed not to overlap the destination. If the template falls outside the RastPort boundary, it is truncated to that boundary.
Note: the SrcTemplate pointer should point to the "nearest" word
(rounded down) of the template mask. Fine alignment of the mask
is achieved by setting the SrcX bit offseet within the range
of 0 to 15 decimal.
Inputs
SrcTemplate - pointer to the first (nearest) word of the template mask. SrcX - x bit offset into the template mask (range 0..15). SrcMod - number of bytes per row in template mask. rp - pointer to destination RastPort. DstX, DstY - x and y coordinates of the upper left corner of the destination for the blit. SizeX, SizeY - size of the rectangle to be used as the template.
Notes
o This function may use the blitter.
See also
CalcIVG()¶
CalcIVG -- Calculate the number of blank lines above a ViewPort (V39)
Synopsis
count = CalcIVG(View, ViewPort)
d0.w a0 a1
UWORD CalcIVG(View*,ViewPort*);
Function
To calculate the maximum number of blank lines above a viewport needed to load all the copper instructions, after accounting for the viewport bandwidth and size.
Inputs
View - pointer to the View ViewPort - pointer to the ViewPort you are interested in.
Results
count - the number of ViewPort resolution scan lines needed to execute all the copper instructions for ViewPort, or 0 if any error.
Notes
The number of copper instructions comes from the vp->vp_DspIns list. Although there may be other copper instructions in the final list (from UCopIns, SprIns and ClrIns) they are currently ignored for this function. This also means that if the ViewPort has never been made (for example, the ViewPort of an intuition screen was opened behind) then vp->vp_DspIns is NULL.
Although CalcIVG() returns the true number of lines needed by the
copper, intuition still maintains an inter-screen gap of 3 non-laced
lines (6 interlaced). Therefore, for intuition screens use:
MAX(CalcIVG(v, vp), (islaced ? 6 : 3))
See also
CBump()¶
CBump - increment user copper list pointer (bump to next position in list).
Synopsis
CBump( c )
a1
void CBump(struct UCopList* );
Function
Increment pointer to space for next instruction in user copper list.
Inputs
c - pointer to UCopList structure
Results
User copper list pointer is incremented to next position. Pointer is repositioned to next user copperlist instruction block if the current block is full.
Note: CBump is usually invoked for the programmer as part of the
macro definitions CWAIT or CMOVE.
Bugs
This function does not return a failure indicator in case the user copper list overruns and there is no free memory to allocate an extension. Instead, the next CMove() or CWait() will then indicate failure.
CEND()¶
CEND -- Terminate user copper list.
Synopsis
CEND( c )
struct UCopList*c;
Function
Add instruction to terminate user copper list.
Inputs
c - pointer to UCopList structure
Results
This is actually a macro that calls the macro CWAIT(c,10000,255) 10000 is a magical number that the graphics.library uses. I hope display technology doesn't catch up too fast!
ChangeExtSpriteA()¶
ChangeExtSpriteA -- Change the sprite image pointer. (V39) ChangeExtSprite -- varargs stub for ChangeExtSpriteA(). (V39)
Synopsis
ChangeExtSpriteA( vp, oldsprite, newsprite, tags)
a0 a1 a2 a3
success=ChangeExtSpriteA(ViewPort*,struct ExtSprite*,
struct ExtSprite*,struct TagList*);
success=ChangeExtSprite(vp,old_sp,new_sp,tag,....);
Function
Attempt to change which sprite is displayed for a given sprite engine.
Inputs
vp - pointer to ViewPort structure that this sprite is relative to, or 0 if relative only top of View oldsprite - pointer the old ExtSprite structure newsprite - pointer to the new ExtSprite structure.
Results
success - 0 if there was an error.
See also
FreeSprite(), ChangeSprite(), MoveSprite(), AllocSpriteDataA()
ChangeSprite()¶
ChangeSprite -- Change the sprite image pointer.
Synopsis
ChangeSprite( vp, s, newdata)
a0 a1 a2
void ChangeSprite(ViewPort*,struct SimpleSprite*, void * )
Function
The sprite image is changed to use the data starting at newdata
Inputs
vp - pointer to ViewPort structure that this sprite is relative to, or 0 if relative only top of View s - pointer to SimpleSprite structure newdata - pointer to data structure of the following form. struct spriteimage { UWORD posctl[2]; / used by simple sprite machine/ UWORD data[height][2]; / actual sprite image / UWORD reserved[2]; / initialized to / / 0x0,0x0 / }; The programmer must initialize reserved[2]. Spriteimage must be in CHIP memory. The height subfield of the SimpleSprite structure must be set to reflect the height of the new spriteimage BEFORE calling ChangeSprite(). The programmer may allocate two sprites to handle a single attached sprite. After GetSprite(), ChangeSprite(), the programmer can set the SPRITE_ATTACHED bit in posctl[1] of the odd numbered sprite. If you need more than 8 sprites, look up VSprites in the graphics documentation.
See also
FreeSprite(), MoveSprite(), AddVSprite()
ChangeVPBitMap()¶
ChangeVPBitMap -- change display memory address for multi-buffered animation (V39)
Synopsis
ChangeVPBitMap(vp,bm,db)
a0 a1 a2
void ChangeVPBitMap(ViewPort*,BitMap*,DBufInfo*);
Function
Changes the area of display memory which will be displayed in a viewport. This can be used to implement double (or triple) buffering, a method of achieving smooth animation.
Inputs
vp = a pointer to a viewport bm = a pointer to a BitMap structure. This BitMap structure must be of the same layout as the one attached to the viewport (same depth, alignment, and BytesPerRow). db = A pointer to a DBufInfo.
Notes
This will set the vp->RasInfo->BitMap field to the bm pointer which is passed.
When using the synchronization features, you MUST carefully insure that
all messages have been replied to before calling FreeDBufInfo or
calling ChangeVPBitMap with the same DBufInfo.
See also
AllocDBufInfo(), AllocBitMap()
ClearEOL()¶
ClearEOL -- Clear from current position to end of line.
Synopsis
ClearEOL(rp)
A1
void ClearEOL(RastPort*);
Function
Clear a rectangular swath from the current position to the right edge of the rastPort. The height of the swath is taken from that of the current text font, and the vertical positioning of the swath is adjusted by the text baseline, such that text output at this position would lie wholly on this newly cleared area. Clearing consists of setting the color of the swath to zero, or, if the DrawMode is JAM2, to the BgPen.
Inputs
rp - pointer to RastPort structure
Notes
o This function may use the blitter.
See also
Text(), ClearScreen(), SetRast()
ClearRectRegion()¶
ClearRectRegion -- Removes all parts from a region that are within a rectangle
Synopsis
status = ClearRectRegion(region,rectangle)
d0 a0 a1
BOOL ClearRectRegion(Region*,Rectangle* );
Function
Clip away any portion of the region that exists inside of the rectangle. Leave the result in region.
Inputs
region - pointer to Region structure rectangle - pointer to Rectangle structure
Results
status - return TRUE if successful operation return FALSE if ran out of memory The region is left unchanged in case of failure.
Bugs
V40 releases and before may have left the region in an inconsistent state in case of failure.
See also
ClearRegion()¶
ClearRegion -- Remove all rectangles from a region.
Synopsis
ClearRegion(region)
a0
void ClearRegion(Region* );
Function
Clip away all rectangles in the region leaving nothing.
Inputs
region - pointer to Region structure
See also
ClearScreen()¶
ClearScreen -- Clear from current position to end of RastPort.
Synopsis
ClearScreen(rp)
A1
void ClearScreen(RastPort*);
Function
Clear a rectangular swath from the current position to the right edge of the rastPort with ClearEOL, then clear the rest of the screen from just beneath the swath to the bottom of the rastPort. Clearing consists of setting the color of the swath to zero, or, if the DrawMode is JAM2, to the BgPen.
Inputs
rp - pointer to RastPort structure
Notes
o This function may use the blitter.
See also
ClipBlit()¶
ClipBlit -- Calls BltBitMap() through ClipRects of Layers.
Synopsis
ClipBlit(Src, SrcX, SrcY, Dest, DestX, DestY, XSize, YSize, Minterm)
A0 D0 D1 A1 D2 D3 D4 D5 D6
void ClipBlit
(RastPort*, WORD, WORD,RastPort*, WORD, WORD,
WORD, WORD, UBYTE);
Function
Performs the same function as BltBitMap(), except that it takes into account the Layers and ClipRects of the layer library, all of which are (and should be) transparent to you. So, whereas BltBitMap() requires pointers to BitMaps, ClipBlit requires pointers to the RastPorts that contain the BitMaps, Layers, etc.
If you are going to blit blocks of data around via the RastPort of your
Intuition Window, you must call this routine rather than BltBitMap().
Either the Src RastPort, the Dest RastPort, both, or neither, can have
Layers. This routine takes care of all cases.
See BltBitMap() for a thorough explanation.
Inputs
Src = pointer to the RastPort of the source for your blit SrcX, SrcY = the topleft offset into Src for your data Dest = pointer to the RastPort to receive the blitted data DestX, DestY = the topleft offset into the destination RastPort XSize = the width of the blit (must be ta least 1) YSize = the height of the blit (must be at least 1) Minterm = the boolean blitter function, where SRCB is associated with the Src RastPort and SRCC goes to the Dest RastPort
See also
BltBitMap(), BltBitMapRastPort(), BltMaskBitMapRastPort()
CloseFont()¶
CloseFont -- Release a pointer to a system font.
Synopsis
CloseFont(font)
A1
void CloseFont(TextFont*);
Function
This function indicates that the font specified is no longer in use by the caller, and may be removed from the system if there are no other users. A RemFont() will be delayed until the font has been closed by all its users.
Inputs
font - a font pointer as returned by OpenFont() or OpenDiskFont()
See also
CloseMonitor()¶
CloseMonitor -- close a MonitorSpec (V36)
Synopsis
error = CloseMonitor( monitor_spec )
d0 a0
LONG CloseMonitor(struct MonitorSpec* );
Function
Relinquish access to a MonitorSpec.
Inputs
monitor_spec - a pointer to a MonitorSpec opened via OpenMonitor(), or NULL.
Results
error - FALSE if MonitorSpec closed uneventfully. TRUE if MonitorSpec could not be closed.
See also
CMOVE()¶
CMOVE -- append copper move instruction to user copper list.
Synopsis
CMOVE( c , a , v )
Function
Add instruction to the user copper list to load value v into hardware register a.
Inputs
c - pointer to UCopList structure a - hardware register v - 16 bit value to be written
Results
This is actually a macro that calls CMove(c,&a,v) and then calls CBump(c) to bump the local pointer to the next instruction. Watch out for macro side affects.
Bugs
This macro does not provide a result code. Check the CMove() function if you need one.
See also
CMove()¶
CMove -- include a copper move instruction in the user copper list
Synopsis
CMove( c , a , v )
a1 d0 d1
LONG CMove(struct UCopList*, void *, WORD );
Function
Include a instruction to move value v to hardware register a in the user copper list. You should also call CBump(c) afterwards to increment the user copper list instruction pointer, or use the CMOVE macro in first place.
Inputs
c - pointer to UCopList structure a - hardware register v - 16 bit value to be written
Results
A boolean success indicator. Returns non-zero if there was still room in the user copper list to include the move, FALSE if the user copper list is full.
Bugs
Versions prior to V47 did not provide a return code, though may have failed.
See also
CoerceMode()¶
CoerceMode -- calculate ViewPort mode coercion (V39)
Synopsis
ID = CoerceMode(RealViewPort, MonitorID, Flags);
d0 a0 d0 d1
ULONG CoerceMode(ViewPort*, ULONG, ULONG);
Function
To determine the best mode in the MonitorID to coerce RealViewPort to, given the restrictions set in Flags.
Inputs
RealViewPort - ViewPort to coerce MonitorID - Montor number to coerce to (ie a mode masked with MONITOR_ID_MASK). Flags - PRESERVE_COLORS - keep the number of bitplanes in the ViewPort. AVOID_FLICKER - do not coerce to an interlace mode
Results
ID - ID of the best mode to coerce to, or INVALID_ID if could not coerce (see NOTES).
Notes
This function takes into account the compatibility of the Monitor being coerced to, and the ViewPort that is being coerced. Incompatibilities will cause a result of INVALID_ID.
Example
newmode = CoerceMode(vp, VGA_MONITOR_ID, PRESERVE_COLORS);
CopySBitMap()¶
CopySBitMap -- Syncronize Layer with contents of SuperBitMap
Synopsis
CopySBitMap( layer )
a0
void CopySBitMap(Layer*);
Function
This is the inverse of SyncSBitMap. Copy all bits from SuperBitMap to Layer bounds, making all changes in the SuperBitMap visible.
This is used for those functions that do not
want to deal with the ClipRect structures but do want
to be able to work with a SuperBitMap Layer.
Inputs
layer - pointer to a SuperBitMap Layer The Layer must already be locked by the caller.
See also
CWAIT()¶
CWAIT -- Append copper wait instruction to user copper list.
Synopsis
CWAIT( c , v , h )
Function
Add instruction to wait for vertical beam position v and horizontal position h to this intermediate copper list.
Inputs
c - pointer to UCopList structure v - vertical beam position (relative to top of viewport) h - horizontal beam position
Results
this is actually a macro that calls CWait(c,v,h) and then calls CBump(c) to bump the local pointer to the next instruction.
Bugs
This macro does not provide a result code. Check the CWait() function if you need one. User waiting for horizontal values of greater than 222 decimal is illegal.
See also
CWait()¶
CWait -- Include copper wait instruction in the user copper list.
Synopsis
CWait( c , v , h )
a1 d0 d1
LONG CWait(struct UCopList*, WORD, WORD)
Function
Include a instruction to wait for vertical beam position v and horizontal position h to this intermediate copper list. You should also call CBump(c) afterwards to increment the user copper list instruction pointer, or use the CWAIT() macro in first place.
Inputs
c - pointer to UCopList structure v - vertical beam position (relative to top of viewport) h - horizontal beam position
Results
A boolean success indicator. Returns non-zero if there was still room in the user copper list to include the move, FALSE if the user copper list is full.
Bugs
Versions prior to V47 did not provide a return code, though may have failed. User waiting for horizontal values of greater than 222 decimal is illegal.
See also
DisownBlitter()¶
DisownBlitter -- return blitter to free state.
Synopsis
DisownBlitter()
void DisownBlitter( void );
Function
Free blitter up for use by other blitter users.
See also
DisposeRegion()¶
DisposeRegion -- Return all space for this region to free memory pool.
Synopsis
DisposeRegion(region)
a0
void DisposeRegion(Region* );
Function
Free all RegionRectangles for this Region then free the Region itself.
Inputs
region - pointer to Region structure
See also
DoCollision()¶
DoCollision -- Test every gel in gel list for collisions.
Synopsis
DoCollision(rp)
A1
void DoCollision(RastPort*);
Function
Tests each gel in gel list for boundary and gel-to-gel collisions. On detecting one of these collisions, the appropriate collision- handling routine is called. See the documentation for a thorough description of which collision routine is called. This routine expects to find the gel list correctly sorted in Y,X order. The system routine SortGList performs this function for the user.
Inputs
rp = pointer to a RastPort
See also
Draw()¶
Draw -- Draw a line between the current pen position and the new x,y position.
Synopsis
Draw( rp, x, y)
a1 d0:16 d1:16
void Draw(RastPort*, SHORT, SHORT);
Function
Draw a line from the current pen position to (x,y).
Inputs
rp - pointer to the destination RastPort x,y - coordinates of where in the RastPort to end the line.
See also
DrawEllipse()¶
DrawEllipse -- Draw an ellipse centered at cx,cy with vertical and horizontal radii of a,b respectively.
Synopsis
DrawEllipse( rp, cx, cy, a, b )
a1 d0 d1 d2 d3
void DrawEllipse(RastPort*, SHORT, SHORT, SHORT, SHORT);
Function
Creates an elliptical outline within the rectangular region specified by the parameters, using the current foreground pen color.
Inputs
rp - pointer to the RastPort into which the ellipse will be drawn. cx - x coordinate of the centerpoint relative to the rastport. cy - y coordinate of the centerpoint relative to the rastport. a - the horizontal radius of the ellipse (note: a must be > 0) b - the vertical radius of the ellipse (note: b must be > 0)
Notes
this routine does not clip the ellipse to a non-layered rastport.
See also
DrawGList()¶
DrawGList -- Process the gel list, queueing VSprites, drawing Bobs.
Synopsis
DrawGList(rp, vp)
A1 A0
void DrawGList(RastPort*,ViewPort*);
Function
Performs one pass of the current gel list. - If nextLine and lastColor are defined, these are initialized for each gel. - If it's a VSprite, build it into the copper list. - If it's a Bob, draw it into the current raster. - Copy the save values into the "old" variables, double-buffering if required.
Inputs
rp = pointer to the RastPort where Bobs will be drawn vp = pointer to the ViewPort for which VSprites will be created
Bugs
MUSTDRAW isn't implemented yet.
See also
EraseRect()¶
EraseRect -- Fill a defined rectangular area using the current BackFill hook. (V36)
Synopsis
EraseRect( rp, xmin, ymin, xmax, ymax)
a1 d0:16 d1:16 d2:16 d3:16
void EraseRect(RastPort*, SHORT, SHORT, SHORT, SHORT);
Function
Fill the rectangular region specified by the parameters with the BackFill hook. If non-layered, the rectangular region specified by the parameters is cleared. If layered the Layer->BackFill Hook is used.
Inputs
rp - pointer to a RastPort structure xmin - x coordinate of the upper left corner of the region to fill. ymin - y coordinate of the upper left corner of the region to fill. xmax - x coordinate of the lower right corner of the region to fill. ymax - y coordinate of the lower right corner of the region to fill.
Notes
The following relation MUST be true: (xmax >= xmin) and (ymax >= ymin)
ExtendFont()¶
ExtendFont -- ensure tf_Extension has been built for a font (V36)
Synopsis
success = ExtendFont(font, fontTags)
D0 A0 A1
ULONG ExtendFont(TextFont*,TagItem*);
success = ExtendFontTags(font, Tag1, ...) (V39)
ULONG ExtendFontTags(TextFont*, ULONG, ...);
Function
To extend a TextFont structure.
Inputs
font - The font to extend. fontTags - An optional taglist. If NULL, then a default is used. Currently, the only tag defined is TA_DeviceDPI.
Results
success - 1 if the TextFont was properly extended, else 0.
Notes
The varargs stub was missing from amiga.lib until V39.
FindColor()¶
FindColor -- Find the closest matching color in a ColorMap. (V39)
Synopsis
color = FindColor(cm, R, G, B , maxpen)
a3 d1 d2 d3 d4
ULONG FindColor(ColorMap*, ULONG, ULONG, ULONG,LONG);
Inputs
cm = colormap R = red level (32 bit left justified fraction) G = green level (32 bit left justified fraction) B = blue level (32 bit left justified fraction) MaxPen = the maximum entry in the color table to search. A value of -1 will limit the search to only those pens which could be rendered in (for instance, it will not examine the sprite colors on a 4 color screen).
Results
The system will attempt to find the color in the passed ColorMap which most closely matches the RGB values passed. No new pens will be allocated, and you should not ReleasePen() the returned pen.
This function is not sensitive to palette sharing issues. Its
intended use is for:
(a) programs which pop up on public screens when those
screens are not using palette sharing. You might
use this function as a fallback when ObtainBestPenA()
says that there are no sharable pens.
(b) Internal color matching by an application which is
either running on a non-public screen, or which
wants to match colors to an internal color table
which may not be associated with any displayed screen.
Notes
In order to use the MaxPen=-1 feature, you must have initialized palette sharing via AttachPalExtra() (all intuition screens do this). Otherwise, MaxPen=-1 will search all colors in the colormap.
When searching for the color which most closely matches the RGB
values passed, the graphics.library default color match function
will be used. You cannot override this function and you cannot
influence how it will perform the matching operation.
Bugs
The default color match function in graphics.library V39-V47 pays no attention to how close two colors are in terms human perception because it lends greatest weight to the largest relative difference in any two random RGB components. This will impact fidelity and will randomly consider two colors to "match most closely" which may have little else in common.
This has been addressed in version 47.9 of graphics library
Both the color specified and the color information stored in the
ColorMap will be truncated during the search for the best
match. This means that if you specify a 96 bit RGB value, only the
4 most significant bits of each color component may be checked on
a system using the ECS or OCS graphics custom chips.
See also
ObtainBestPenA(), GetColorMap(), ObtainPen(), ReleasePen()
FindDisplayInfo()¶
FindDisplayInfo -- search for a record identified by a specific key (V36)
Synopsis
handle = FindDisplayInfo(ID)
D0 D0
DisplayInfoHandle FindDisplayInfo(ULONG);
Function
Given a 32-bit Mode Key, return a handle to a valid DisplayInfoRecord found in the graphics database. Using this handle, you can obtain information about this Mode, including its default dimensions, properties, and whether it is currently available for use.
Inputs
ID - unsigned long identifier
Results
handle - handle to a displayinfo Record with that key or NULL if no match.
Flood()¶
Flood -- Flood rastport like areafill.
Synopsis
error = Flood( rp, mode, x, y)
d0 a1 d2 d0 d1
BOOL Flood(RastPort*, ULONG, SHORT, SHORT);
Function
Search the BitMap starting at (x,y). Fill all adjacent pixels if they are: Mode 0: not the same color as AOLPen Mode 1: the same color as the pixel at (x,y)
When actually doing the fill use the modes that apply to
standard areafill routine such as drawmodes and patterns.
Inputs
rp - pointer to RastPort (x,y) - coordinate in BitMap to start the flood fill at. mode - 0 fill all adjacent pixels searching for border. 1 fill all adjacent pixels that have same pen number as the one at (x,y).
Notes
In order to use Flood, the destination RastPort must have a valid TmpRas raster whose size is as large as that of the RastPort.
Bugs
Could not fill rastports wider or taller than 1024 pixels prior to release V45. This was fixed in V45.
See also
FontExtent()¶
FontExtent -- get the font attributes of the current font (V36)
Synopsis
FontExtent(font, fontExtent)
A0 A1
void FontExtent(TextFont*,TextExtent*);
Function
This function fills the text extent structure with a bounding (i.e. maximum) extent for the characters in the specified font.
Inputs
font - the TextFont from which the font metrics are extracted. fontExtent - the TextExtent structure to be filled.
Results
fontExtent is filled.
Notes
The TextFont, not the RastPort, is specified -- unlike TextExtent(), effect of algorithmic enhancements is not included, nor does te_Width include any effect of rp_TxSpacing. The returned te_Width will be negative only when FPF_REVPATH is set in the tf_Flags of the font -- the effect of left-moving characters is ignored for the width of a normal font, and the effect of right-moving characters is ignored if a REVPATH font. These characters will, however, be reflected in the bounding extent.
See also
FreeBitMap()¶
FreeBitMap -- free a bitmap created by AllocBitMap (V39)
Synopsis
FreeBitMap(bm)
a0
VOID FreeBitMap(BitMap*)
Function
Frees bitmap and all associated bitplanes
Inputs
bm = A pointer to a BitMap structure. Passing a NULL-pointer (meaning "do nothing") is OK.
Notes
Be careful to insure that any rendering done to the bitmap has completed (by calling WaitBlit()) before you call this function.
See also
FreeColorMap()¶
FreeColorMap -- Free the ColorMap structure and return memory to free memory pool.
Synopsis
FreeColorMap( colormap )
a0
void FreeColorMap(ColorMap*);
Function
Return the memory to the free memory pool that was allocated with GetColorMap.
Inputs
colormap - pointer to ColorMap allocated with GetColorMap.
Passing a NULL pointer (meaning "do nothing") is
acceptable (V39).
Results
The space is made available for others to use.
See also
FreeDBufInfo()¶
FreeDBufInfo -- free information for multi-buffered animation (V39)
Synopsis
FreeDBufInfo(db)
a1
void FreeDBufInfo(DBufInfo*)
Function
Frees a structure obtained from AllocDBufInfo
Inputs
db = A pointer to a DBufInfo.
Notes
FreeDBufInfo(NULL) is a no-op.
See also
AllocDBufInfo(), ChangeVPBitMap()
FreeGBuffers()¶
FreeGBuffers -- Deallocate memory obtained by GetGBufers.
Synopsis
FreeGBuffers(anOb, rp, db)
A0 A1 D0
void FreeGBuffers(AnimOb*,RastPort*, BOOL);
Function
For each sequence of each component of the AnimOb, deallocate memory for: SaveBuffer BorderLine CollMask and ImageShadow (point to same buffer) if db is set (user had used double-buffering) deallocate: DBufPacket BufBuffer
Inputs
anOb = pointer to the AnimOb structure rp = pointer to the current RastPort db = double-buffer indicator (set TRUE for double-buffering)
See also
FreeRaster()¶
FreeRaster -- Release an allocated area to the system free memory pool.
Synopsis
FreeRaster( p, width, height)
a0 d0:16 d1:16
void FreeRaster( PLANEPTR, USHORT, USHORT);
Function
Return the memory associated with this PLANEPTR of size width and height to the MEMF_CHIP memory pool.
Inputs
p = a pointer to a memory space returned as a result of a call to AllocRaster.
width - the width in bits of the bitplane.
height - number of rows in bitplane.
Notes
Width and height should be the same values with which you called AllocRaster in the first place.
See also
FreeSprite()¶
FreeSprite -- Return sprite for use by others and virtual sprite machine.
Synopsis
FreeSprite( pick )
d0
void FreeSprite( WORD );
Function
Mark sprite as available for others to use. These sprite routines are provided to ease sharing of sprite hardware and to handle simple cases of sprite usage and movement. It is assumed the programs that use these routines do want to be good citizens in their hearts. ie: they will not FreeSprite unless they actually own the sprite. The Virtual Sprite machine may ignore the simple sprite machine.
Inputs
pick - number in range of 0-7
Results
sprite made available for subsequent callers of GetSprite as well as use by Virtual Sprite Machine.
See also
GetSprite(), ChangeSprite(), MoveSprite()
FreeSpriteData()¶
FreeSpriteData -- free sprite data allocated by AllocSpriteData() (V39)
Synopsis
FreeSpriteData(extsp)
a2
void FreeSpriteData(struct ExtSprite*);
Inputs
extsp - The extended sprite structure to be freed. Passing NULL is a NO-OP.
See also
FreeSprite(), ChangeSprite(), MoveSprite(), GetExtSprite(), AllocBitMap()
GetAPen()¶
GetAPen -- Get the A Pen value for a RastPort (V39).
Synopsis
pen = GetAPen ( rp )
d0 a0
ULONG GetAPen(RastPort*)
Function
Return the current value of the A pen for the rastport. This function should be used instead of peeking the structure directly, because future graphics devices may store it differently, for instance, using more bits.
Inputs
rp = a pointer to a valid RastPort structure.
See also
GetBitMapAttr()¶
GetBitMapAttr -- Returns information about a bitmap (V39)
Synopsis
value=GetBitMapAttr(bitmap,attribute_number);
d0 a0 d1
ULONG GetBitMapAttr(BitMap*,ULONG);
Function
Determines information about a bitmap. This function should be used instead of reading the bitmap structure fields directly. This will provide future compatibility.
Inputs
bm = A pointer to a BitMap structure.
attribute_number = A number telling graphics which attribute
of the bitmap should be returned:
BMA_HEIGHT returns the height in pixels
BMA_WIDTH returns the width in pixels.
BMA_DEPTH returns the depth. This is the number of
bits which are required to store the information
for one pixel in the bitmap.
BMA_FLAGS returns a longword bitfield describing
various attributes which the bitmap may have.
Currently defined flags are BMF_DISPLAYABLE,
BMF_INTERLEAVED (see AllocBitMap()). The flag
BMF_STANDARD returns will be set if the
bitmap is represented as planar data in Amiga
Chip RAM.
Notes
Unknown attributes are reserved for future use, and return zero.
BMF_DISPLAYABLE will only be set if the source bitmap meets all of the
required alignment restrictions. A bitmap which does not meet these
restrictions may still be displayable at some loss of efficiency.
Size values returned by this function may not exactly match the values
which were passed to AllocBitMap(), due to alignment restrictions.
See also
GetBPen()¶
GetBPen -- Get the B Pen value for a RastPort (V39).
Synopsis
pen = GetBPen ( rp )
d0 a0
ULONG GetBPen(RastPort*)
Function
Return the current value of the B pen for the rastport. This function should be used instead of peeking the structure directly, because future graphics devices may store it differently, using more bits.
Inputs
rp = a pointer to a valid RastPort structure.
See also
GetColorMap()¶
GetColorMap -- allocate and initialize Colormap
Synopsis
cm = GetColorMap( entries )
d0 d0
ColorMap*GetColorMap( ULONG);
Function
Allocates, initializes and returns a pointer to a ColorMap data structure, later enabling calls to SetRGB4 and LoadRGB4 to load colors for a view port. The ColorTable pointer in the ColorMap structure points to a hardware specific colormap data structure. You should not count on it being anything you can understand. Use GetRGB4() to query it or SetRGB4CM to set it directly.
Inputs
entries - number of entries for this colormap
Results
The pointer value returned by this routine, if nonzero, may be stored into the ViewPort.ColorMap pointer. If a value of 0 is returned, the system was unable to allocate enough memory space for the required data structures.
See also
GetDisplayInfoData()¶
GetDisplayInfoData -- query DisplayInfo Record parameters (V36)
Synopsis
result = GetDisplayInfoData(handle, buf, size, tagID, [ID])
D0 A0 A1 D0 D1 [D2]
ULONG GetDisplayInfoData(DisplayInfoHandle, UBYTE *, ULONG, ULONG, ULONG);
Function
GetDisplayInfoData() fills a buffer with data meaningful to the DisplayInfoRecord pointed at by your valid handle. The data type that you are interested in is indicated by a tagID for that chunk. The types of tagged information that may be available include:
DTAG_DISP: (DisplayInfo) - properties and availability information.
DTAG_DIMS: (DimensionInfo) - default dimensions and overscan info.
DTAG_MNTR: (MonitorInfo) - type, position, scanrate, and compatibility
DTAG_NAME: (NameInfo) - a user friendly way to refer to this mode.
Inputs
handle - displayinfo handle buf - pointer to destination buffer size - buffer size in bytes tagID - data chunk type ID - displayinfo identifier, optionally used if handle is NULL
Results
result - if positive, number of bytes actually transferred if zero, no information for ID was available
See also
FindDisplayInfo(), NextDisplayInfo()
GetDrMd()¶
GetDrMd -- Get the draw mode value for a RastPort (V39).
Synopsis
mode = GetDrMd ( rp )
d0 a0
ULONG GetDrMd(RastPort*)
Function
Return the current value of the draw mode for the rastport. This function should be used instead of peeking the structure directly, because future graphics devices may store it differently.
Inputs
rp = a pointer to a valid RastPort structure.
See also
GetExtSpriteA()¶
GetExtSpriteA -- Attempt to get a sprite for the extended sprite manager. (V39) GetExtSprite -- varargs stub for GetExtSpriteA. (V39)
Synopsis
Sprite_Number = GetExtSpriteA( sprite, tags )
d0 a2 a1
LONG GetExtSpriteA(struct ExtSprite*,TagItem* );
spritenum=GetExtSprite(sprite,tags,...);
Function
Attempt to allocate one of the eight sprites for private use with the extended sprite manager.
Inputs
sprite - ptr to programmer's ExtSprite (from AllocSpriteData()). tags - a standard tag list:
GSTAG_SPRITE_NUM specifies a specific sprite to get by number.
GSTAG_ATTACHED specifies that you wish to get a sprite pair.
the tag data field points to a ExtSprite structure
for the second sprite. You must free both sprites.
Results
Sprite_number = a sprite number or -1 for an error. This call will fail if no sprites could be allocated, or if you try to allocate a sprite which would require a mode change when there are other sprites of incompatible modes in use.
Bugs
GSTAG_ATTACHED does not work in version 39. When running under V39, you should attach the second sprite with a separate GetExtSprite call.
See also
FreeSprite(), ChangeSprite(), MoveSprite(), GetSprite()
GetGBuffers()¶
GetGBuffers -- Attempt to allocate ALL buffers of an entire AnimOb.
Synopsis
status = GetGBuffers(anOb, rp, db)
D0 A0 A1 D0
BOOL GetGBuffers(AnimOb*,RastPort*, BOOL);
Function
For each sequence of each component of the AnimOb, allocate memory for: SaveBuffer BorderLine CollMask and ImageShadow (point to same buffer) if db is set TRUE (user wants double-buffering) allocate: DBufPacket BufBuffer
Inputs
anOb = pointer to the AnimOb structure rp = pointer to the current RastPort db = double-buffer indicator (set TRUE for double-buffering)
Results
status = TRUE if the memory allocations were all successful, else FALSE
Bugs
If any of the memory allocations fail it does not free the partial allocations that did succeed.
See also
GetOutlinePen()¶
GetOutlinePen -- Get the Outline-Pen value for a RastPort (V39).
Synopsis
pen = GetOutlinePen ( rp )
d0 a0
ULONG GetOutlinePen(RastPort*)
Function
Return the current value of the O pen for the rastport. This function should be used instead of peeking the structure directly, because future graphics devices may store it differently, for instance, using more bits.
Inputs
rp = a pointer to a valid RastPort structure.
See also
GetRGB32()¶
GetRGB32 -- Set a series of color registers for this Viewport. (V39)
Synopsis
GetRGB32( cm, firstcolor, ncolors, table )
a0 d0 d1 a1
void GetRGB32(ColorMap*, ULONG, ULONG, ULONG *);
Inputs
cm = colormap firstcolor = the first color register to get ncolors = the number of color registers to set. table=a pointer to a series of 32-bit RGB triplets.
Results
The ULONG data pointed to by 'table' will be filled with the 32 bit fractional RGB values from the colormap.
Notes
'Table' should point to at least ncolors*3 longwords.
See also
LoadRGB4(), GetColorMap(), LoadRGB32(), SetRGB32CM()
GetRGB4()¶
GetRGB4 -- Inquire value of entry in ColorMap.
Synopsis
value = GetRGB4( colormap, entry )
d0 a0 d0
ULONG GetRGB4(ColorMap*, LONG);
Function
Read and format a value from the ColorMap.
Inputs
colormap - pointer to ColorMap structure entry - index into colormap
Results
returns -1 if no valid entry return UWORD RGB value 4 bits per gun right justified
Note
Intuition's DisplayBeep() changes color 0. Reading Color 0 during a DisplayBeep() will lead to incorrect results.
See also
SetRGB4(), LoadRGB4(), GetColorMap(), FreeColorMap()
GetRPAttrA()¶
GetRPAttrA -- examine rastport settings via a tag list GetRPAttrs -- varargs stub for GetRPAttrA
Synopsis
GetRPAttrA(rp,tags)
a0 a1
void GetRPAttrA(RastPort*,TagItem*);
GetRPAttrs(rp,attr1,&result1,...);
Function
Read the settings of a rastport into variables. The ti_Tag field of the TagItem specifies which attribute should be read, and the ti_Data field points at the location where the result hsould be stored. All current tags store the return data as LONGs (32 bits).
currently available tags are:
RPTAG_Font Font for Text()
RPTAG_SoftStyle style for text (see graphics/text.h)
RPTAG_APen Primary rendering pen
RPTAG_BPen Secondary rendering pen
RPTAG_DrMd Drawing mode (see graphics/rastport.h)
RPTAG_OutLinePen Area Outline pen
RPTAG_WriteMask Bit Mask for writing.
RPTAG_MaxPen Maximum pen to render (see SetMaxPen())
RPTAG_DrawBounds Determine the area that will be rendered
into by rendering commands. Can be used
to optimize window refresh. Pass a pointer
to a rectangle in the tag data. On return,
the rectangle's MinX will be greater than
its MaxX if there are no active cliprects.
Inputs
rp - pointer to the RastPort to examine. tags - a standard tag list specifying the attributes to be read, and where to store their values.
See also
GetAPen(), GetBPen(), GetDrMd(), GetOutLinePen(), GetWriteMask(), SetRPAttrA()
GetSprite()¶
GetSprite -- Attempt to get a sprite for the simple sprite manager.
Synopsis
Sprite_Number = GetSprite( sprite, pick )
d0 a0 d0
WORD GetSprite(struct SimpleSprite*, WORD );
Function
Attempt to allocate one of the eight sprites for private use with the simple sprite manager. This must be done before using further calls to the simple sprite machine. If the programmer wants to use 15 color sprites, they must allocate both sprites and set the 'SPRITE_ATTACHED' bit in the odd sprite's posctldata array.
Inputs
sprite - ptr to programmers SimpleSprite structure. pick - number in the range of 0-7 or -1 if programmer just wants the next one.
Results
If pick is 0-7 attempt to allocate the sprite. If the sprite is already allocated then return -1. If pick -1 allocate the next sprite starting search at 0. If no sprites are available return -1 and fill -1 in num entry of SimpleSprite structure. If the sprite is available for allocation, mark it allocated and fill in the 'num' entry of the SimpleSprite structure. If successful return the sprite number.
See also
FreeSprite(), ChangeSprite(), MoveSprite()
GetVPModeID()¶
GetVPModeID -- get the 32 bit DisplayID from a ViewPort. (V36)
Synopsis
modeID = GetVPModeID( vp )
d0 a0
ULONG GetVPModeID(ViewPort*);
Function
returns the normal display modeID, if one is currently associated with this ViewPort.
Inputs
vp -- pointer to a ViewPort structure.
Results
modeID -- a 32 bit DisplayInfoRecord identifier associated with this ViewPort, or INVALID_ID.
Notes
Test the return value of this function against INVALID_ID, not NULL. (INVALID_ID is defined in graphics/displayinfo.h).
See also
GfxAssociate()¶
GfxAssociate -- associate a graphics extended node with a given pointer (V36)
Synopsis
GfxAssociate(pointer, node);
A0 A1
void GfxAssociate(VOID *,ExtendedNode*);
Function
Associate a special graphics extended data structure (each of which begins with an ExtendedNode structure) with another structure via the other structure's pointer. Later, when you call GfxLookUp() with the other structure's pointer you may retrieve a pointer to this special graphics extended data structure, if it is available.
Inputs
pointer = a pointer to a data structure. node = an ExtendedNode structure to associate with the pointer
Results
an association is created between the pointer and the node such that given the pointer the node can be retrieved via GfxLookUp().
See also
GfxNew(), GfxFree(), GfxLookUp()
GfxFree()¶
GfxFree -- free a graphics extended data structure (V36)
Synopsis
GfxFree( node );
a0
void GfxFree(ExtendedNode*);
Function
Free a special graphics extended data structure (each of which begins with an ExtendedNode structure).
Inputs
node = pointer to a graphics extended data structure obtained via GfxNew().
Results
the node is deallocated from memory. graphics will disassociate this special graphics extended node from any associated data structures, if necessary, before freeing it (see GfxAssociate()).
Bugs
an Alert() will be called if you attempt to free any structure other than a graphics extended data structure obtained via GfxFree().
See also
GfxNew(), GfxAssociate(), GfxLookUp()
GfxLookUP()¶
GfxLookUp -- find a graphics extended node associated with a given pointer (V36)
Synopsis
result = GfxLookUp( pointer );
d0 a0
ExtendedNode*GfxLookUp( void *);
Function
Finds a special graphics extended data structure (if any) associated with the pointer to a data structure (eg: ViewExtra associated with a View structure).
Inputs
pointer = a pointer to a data structure which may have an ExtendedNode associated with it (typically a View ).
Results
result = a pointer to the ExtendedNode that has previously been associated with the pointer.
See also
GfxNew(), GfxFree(), GfxAssociate()
GfxNew()¶
GfxNew -- allocate a graphics extended data structure (V36)
Synopsis
result = GfxNew( node_type );
d0 d0
ExtendedNode*GfxNew( ULONG);
Function
Allocate a special graphics extended data structure (each of which begins with an ExtendedNode structure). The type of structure to be allocated is specified by the node_type identifier.
Inputs
node_type = which type of graphics extended data structure to allocate. (see gfxnodes.h for identifier definitions.)
Results
result = a pointer to the allocated graphics node or NULL if the allocation failed.
See also
GfxFree(), GfxAssociate(), GfxLookUp()
InitArea()¶
InitArea -- Initialize vector collection matrix
Synopsis
InitArea( areainfo, buffer, maxvectors )
a0 a1 d0
void InitArea(AreaInfo*, void *, SHORT);
Function
This function provides initialization for the vector collection matrix such that it has a size of (max vectors ). The size of the region pointed to by buffer (short pointer) should be five (5) times as large as maxvectors. This size is in bytes. Areafills done by using AreaMove, AreaDraw, and AreaEnd must have enough space allocated in this table to store all the points of the largest fill. AreaEllipse takes up two vectors for every call. If AreaMove/Draw/Ellipse detect too many vectors going into the buffer they will return -1.
Inputs
areainfo - pointer to AreaInfo structure buffer - pointer to chunk of memory to collect vertices maxvectors - max number of vectors this buffer can hold
Results
Pointers are set up to begin storage of vectors done by AreaMove, AreaDraw, and AreaEllipse.
See also
AreaEnd(), AreaMove(), AreaDraw(), AreaEllipse()
InitBitMap()¶
InitBitMap -- Initialize bit map structure with input values.
Synopsis
InitBitMap( bm, depth, width, height )
a0 d0 d1 d2
void InitBitMap(BitMap*, BYTE, UWORD, UWORD );
Function
Initialize various elements in the BitMap structure to correctly reflect depth, width, and height. Must be used before use of BitMap in other graphics calls. The Planes[8] are not initialized and need to be set up by the caller. The Planes table was put at the end of the structure so that it may be truncated to conserve space, as well as extended. All routines that use BitMap should only depend on existence of depth number of bitplanes. The Flags and pad fields are reserved for future use and should not be used by application programs.
Inputs
bm - pointer to a BitMap structure (gfx.h) depth - number of bitplanes that this bitmap will have width - number of bits (columns) wide for this BitMap height- number of bits (rows) tall for this BitMap
InitGels()¶
InitGels -- initialize a gel list; must be called before using gels.
Synopsis
InitGels(head, tail, GInfo)
A0 A1 A2
void InitGels(VSprite*,VSprite*,GelsInfo*);
Function
Assigns the VSprites as the head and tail of the gel list in GfxBase. Links these two gels together as the keystones of the list. If the collHandler vector points to some memory array, sets the BORDERHIT vector to NULL.
Inputs
head = pointer to the VSprite structure to be used as the gel list head tail = pointer to the VSprite structure to be used as the gel list tail GInfo = pointer to the GelsInfo structure to be initialized
InitGMasks()¶
InitGMasks -- Initialize all of the masks of an AnimOb.
Synopsis
InitGMasks(anOb)
A0
void InitGMasks(AnimOb*);
Function
For every sequence of every component call InitMasks.
Inputs
anOb = pointer to the AnimOb
See also
InitMasks()¶
InitMasks -- Initialize the BorderLine and CollMask masks of a VSprite.
Synopsis
InitMasks(vs)
A0
void InitMasks(VSprite*);
Function
Creates the appropriate BorderLine and CollMask masks of the VSprite. Correctly detects if the VSprite is actually a Bob definition, handles the image data accordingly.
Inputs
vs = pointer to the VSprite structure
See also
InitRastPort()¶
InitRastPort -- Initialize raster port structure
Synopsis
InitRastPort( rp )
a1
void InitRastPort(RastPort*rp);
Function
Initialize a RastPort structure to standard values.
Inputs
rp = pointer to a RastPort structure.
Results
all entries in RastPort get zeroed out, with the following exceptions:
Mask, FgPen, AOLPen, and LinePtrn are set to -1.
The DrawMode is set to JAM2
The font is set to the standard system font
Notes
The struct Rastport describes a control structure for a write-able raster. The RastPort structure describes how a complete single playfield display will be written into. A RastPort structure is referenced whenever any drawing or filling operations are to be performed on a section of memory.
The section of memory which is being used in this
way may or may not be presently a part of the
current actual onscreen display memory. The name
of the actual memory section which is linked to
the RastPort is referred to here as a "raster" or
as a bitmap.
NOTE: Calling the routine InitRastPort only
establishes various defaults. It does NOT
establish where, in memory, the rasters are
located. To do graphics with this RastPort the user
must set up the BitMap pointer in the RastPort.
InitTmpRas()¶
InitTmpRas -- Initialize area of local memory for usage by areafill, floodfill, text.
Synopsis
InitTmpRas(tmpras, buffer, size)
a0 a1 d0
void InitTmpRas(TmpRas*, void *, ULONG );
Function
The area of memory pointed to by buffer is set up to be used by RastPort routines that may need to get some memory for intermediate operations in preparation to putting the graphics into the final BitMap. Tmpras is used to control the usage of buffer.
Inputs
tmpras - pointer to a TmpRas structure to be linked into a RastPort buffer - pointer to a contiguous piece of chip memory. size - size in bytes of buffer
Results
makes buffer available for users of RastPort
Bugs
Would be nice if RastPorts could share one TmpRas.
See also
InitView()¶
InitView - Initialize View structure.
Synopsis
InitView( view )
a1
void InitView(View* );
Function
Initialize View structure to default values.
Inputs
view - pointer to a View structure
Results
View structure set to all 0's. (1.0,1.1.1.2) Then values are put in DxOffset,DyOffset to properly position default display about .5 inches from top and left on monitor. InitView pays no attention to previous contents of view.
See also
InitVPort()¶
InitVPort - Initialize ViewPort structure.
Synopsis
InitVPort( vp )
a0
void InitViewPort(ViewPort* );
Function
Initialize ViewPort structure to default values.
Inputs
vp - pointer to a ViewPort structure
Results
ViewPort structure set to all 0's. (1.0,1.1) New field added SpritePriorities, initialized to 0x24 (1.2)
See also
LoadRGB32()¶
LoadRGB32 -- Set a series of color registers for this Viewport. (V39)
Synopsis
LoadRGB32( vp, table )
a0 a1
void LoadRGB32(ViewPort*, ULONG *);
Inputs
vp = viewport table = a pointer to a series of records which describe which colors to modify.
Results
The selected color registers are changed to match your specs.
Notes
Passing a NULL "table" is ignored. The format of the table passed to this function is a series of records, each with the following format:
1 Word with the number of colors to load
1 Word with the first color to be loaded.
3 longwords representing a left justified 32 bit rgb triplet.
The list is terminated by a count value of 0.
examples:
ULONG table[]={1l<<16+0,0xffffffff,0,0,0} loads color register
0 with 100% red.
ULONG table[]={256l<<16+0,r1,g1,b1,r2,g2,b2,.....0} can be used
to load an entire 256 color palette.
Lower order bits of the palette specification will be discarded,
depending on the color palette resolution of the target graphics
device. Use 0xffffffff for the full value, 0x7fffffff for 50%,
etc. You can find out the palette range for your screen by
querying the graphics data base.
LoadRGB32 is faster than SetRGB32, even for one color.
See also
LoadRGB4(), GetColorMap(), GetRGB32(), SetRGB32CM()
LoadRGB4()¶
LoadRGB4 -- Load RGB color values from table.
Synopsis
LoadRGB4( vp, colors , count )
a0 a1 d0:16
void LoadRGB4(ViewPort*, UWORD *, WORD);
Function
load the count words of the colormap from table starting at entry 0.
Inputs
vp - pointer to ViewPort, whose colors you wish to change colors - pointer to table of RGB values set up as an array of USHORTS background-- 0x0RGB color1 -- 0x0RGB color2 -- 0x0RGB etc. UWORD per value. The colors are interpreted as 15 = maximum intensity. 0 = minimum intensity. count = number of UWORDs in the table to load into the colormap starting at color 0(background) and proceeding to the next higher color number
Results
The ViewPort should have a pointer to a valid ColorMap to store the colors in. Updates the hardware copperlist to reflect the new colors. Updates the intermediate copperlist with the new colors.
Bugs
NOTE: Under V36 and up, it is not safe to call this function from an interrupt, due to semaphore protection of graphics copper lists.
See also
SetRGB4(), GetRGB4(), GetColorMap()
LoadView()¶
LoadView -- Use a (possibly freshly created) coprocessor instruction list to create the current display.
Synopsis
LoadView( View )
A1
void LoadView(View* );
Function
Install a new view to be displayed during the next display refresh pass. Coprocessor instruction list has been created by InitVPort(), MakeVPort(), and MrgCop().
Inputs
View - a pointer to the View structure which contains the pointer to the constructed coprocessor instructions list, or NULL.
Results
If the View pointer is non-NULL, the new View is displayed, according to your instructions. The vertical blank routine will pick this pointer up and direct the copper to start displaying this View.
If the View pointer is NULL, no View is displayed.
Note
Even though a LoadView(NULL) is performed, display DMA will still be active. Sprites will continue to be displayed after a LoadView(NULL) unless an OFF_SPRITE is subsequently performed.
See also
InitVPort(), MakeVPort(), MrgCop(), RethinkDisplay()
LockLayerRom()¶
LockLayerRom -- Lock Layer structure by ROM(gfx lib) code.
Synopsis
LockLayerRom( layer )
a5
void LockLayerRom(Layer* );
Function
Return when the layer is locked and no other task may alter the ClipRect structure in the Layer structure. This call does not destroy any registers. This call nests so that callers in this chain will not lock themselves out. Do not have the Layer locked during a call to intuition. There is a potential deadlock problem here, if intuition needs to get other locks as well. Having the layer locked prevents other tasks from using the layer library functions, most notably intuition itself. So be brief. layers.library's LockLayer is identical to LockLayerRom.
Inputs
layer - pointer to Layer structure
Results
The layer is locked and the task can render assuming the ClipRects will not change out from underneath it until an UnlockLayerRom is called.
See also
MakeVPort()¶
MakeVPort -- generate display copper list for a viewport.
Synopsis
error = MakeVPort( view, viewport )
d0 a0 a1
ULONG MakeVPort(View*,ViewPort* );
Function
Uses information in the View, ViewPort, ViewPort->RasInfo to construct and intermediate copper list for this ViewPort.
Inputs
view - pointer to a View structure viewport - pointer to a ViewPort structure The viewport must have valid pointer to a RasInfo.
Results
constructs intermediate copper list and puts pointers in viewport.DspIns If the ColorMap ptr in ViewPort is NULL then it uses colors from the default color table. If DUALPF in Modes then there must be a second RasInfo pointed to by the first RasInfo
From V39, MakeVPort can return a ULONG error value (previous versions
returned void), to indicate that either not enough memory could be
allocated for MakeVPort's use, or that the ViewPort mode
and bitplane alignments are incorrect for the bitplane's depth.
You should check for these error values - they are defined in
<graphics/view.h>.
Bugs
In V37 and earlier, narrow Viewports (whose righthand edge is less than 3/4 of the way across the display) do not work properly.
See also
InitVPort(), MrgCop(), MakeScreen(), RemakeDisplay(), RethinkDisplay()
ModeNotAvailable()¶
ModeNotAvailable -- check to see if a DisplayID isn't available. (V36)
Synopsis
error = ModeNotAvailable( modeID )
d0 d0
ULONG ModeNotAvailable( ULONG);
Function
returns an error code, indicating why this modeID is not available, or NULL if there is no reason known why this mode should not be there.
Inputs
modeID -- a 32 bit DisplayInfoRecord identifier.
Results
error -- a general indication of why this modeID is not available, or NULL if there is no reason why it shouldn't be available.
Note
ULONG return values from this function are a proper superset of the DisplayInfo.NotAvailable field (defined in graphics/displayinfo.h).
See also
Move()¶
Move -- Move graphics pen position.
Synopsis
Move( rp, x, y)
a1 d0:16 d1:16
void Move(RastPort*, SHORT, SHORT );
Function
Move graphics pen position to (x,y) relative to upper left (0,0) of RastPort. This sets the starting point for subsequent Draw() and Text() calls.
Inputs
rp - pointer to a RastPort structure x,y - point in the RastPort
See also
MoveSprite()¶
MoveSprite -- Move sprite to a point relative to top of viewport.
Synopsis
MoveSprite(vp, sprite, x, y)
A0 A1 D0 D1
void MoveSprite(ViewPort*,struct SimpleSprite*, WORD, WORD);
Function
Move sprite image to new place on display.
Inputs
vp - pointer to ViewPort structure if vp = 0, sprite is positioned relative to View. sprite - pointer to SimpleSprite structure (x,y) - new position relative to top of viewport or view.
Results
Calculate the hardware information for the sprite and place it in the posctldata array. During next video display the sprite will appear in new position.
Bugs
Sprites really appear one pixel to the left of the position you specify. This bug affects the apparent display position of the sprite on the screen, but does not affect the numeric position relative to the viewport or view. This behaviour only applies to SimpleSprites, not to ExtSprites.
See also
FreeSprite(), ChangeSprite(), GetSprite()
MrgCop()¶
MrgCop -- Merge together coprocessor instructions.
Synopsis
error = MrgCop( View )
d0 A1
ULONG MrgCop(View* );
Function
Merge together the display, color, sprite and user coprocessor instructions into a single coprocessor instruction stream. This essentially creates a per-display-frame program for the coprocessor. This function MrgCop is used, for example, by the graphics animation routines which effectively add information into an essentially static background display. This changes some of the user or sprite instructions, but not those which have formed the basic display in the first place. When all forms of coprocessor instructions are merged together, you will have a complete per- frame instruction list for the coprocessor.
Restrictions: Each of the coprocessor instruction lists MUST be
internally sorted in min to max Y-X order. The merge routines
depend on this! Each list must be terminated using CEND(copperlist).
Inputs
View - a pointer to the view structure whose coprocessor instructions are to be merged.
Results
The view structure will now contain a complete, sorted/merged list of instructions for the coprocessor, ready to be used by the display processor. The display processor is told to use this new instruction stream through the instruction LoadView().
From V39, MrgCop() can return a ULONG error value (previous versions
returned void), to indicate that either there was insufficient memory
to build the system copper lists, or that MrgCop() had no work to do
if, for example, there were no ViewPorts in the list.
You should check for these error values - they are defined in
<graphics/view.h>.
See also
InitVPort(), MakeVPort(), LoadView(), RethinkDisplay()
NewRegion()¶
NewRegion -- Get an empty region.
Synopsis
region = NewRegion()
d0
Region*NewRegion();
Function
Create a Region structure, initialize it to empty, and return a pointer it.
Inputs
none
Results
region - pointer to initialized region. If it could not allocate required memory region = NULL.
NextDisplayInfo()¶
NextDisplayInfo -- iterate current displayinfo identifiers (V36)
Synopsis
next_ID = NextDisplayInfo(last_ID)
D0 D0
ULONG NextDisplayInfo(ULONG);
Function
The basic iteration function with which to find all records in the graphics database. Using each ID in succession, you can then call FindDisplayInfo() to obtain the handle associated with each ID. Each ID is a 32-bit Key which uniquely identifies one record. The INVALID_ID is special, and indicates the end-of-list.
Inputs
last_ID - previous displayinfo identifier or INVALID_ID if beginning iteration.
Results
next_ID - subsequent displayinfo identifier or INVALID_ID if no more records.
See also
FindDisplayInfo(), GetDisplayInfoData()
ObtainBestPenA()¶
ObtainBestPenA --- Search for the closest color match, or allocate a new one. (V39) ObtainBestPen --- varargs stub for ObtainBestPenA
Synopsis
color | -1 =ObtainBestPenA(cm, R, G, B, taglist)
a0 d1 d2 d3 a1
LONG ObtainBestPenA(ColorMap*cm, ULONG R, ULONG G,
BULONG,TagItem* taglist);
color = ObtainBestPen(cm, r, g, b, tags....);
Function
This function can be used by applications to figure out what pen to use to represent a given color.
The system will attempt to find the color in your ColorMap closest
to the specified color. If there is no color within your tolerance,
then a new one will be allocated, if possible. If no color map entry
is available for allocation, then the closest one found will be returned
unless you specified through the tag OBP_FailIfBad=TRUE that -1 should
be returned instead.
Inputs
cm = colormap R = red level (32 bit left justified fraction) G = green level (32 bit left justified fraction) B = blue level (32 bit left justified fraction) taglist = a pointer to a standard tag list specifying the color matching settings desired:
OBP_Precision - specifies the desired precision for the
match. Should be PRECISION_GUI, PRECISION_ICON, or
PRECISION_IMAGE or PRECISION_EXACT.
Defaults to PRECISION_IMAGE.
OBP_FailIfBad - specifies that you want ObtainBestPen to return
a failure value if there is not a color within the
given tolerance, instead of returning the closest color.
With OBP_FailIfBad==FALSE, ObtainBestPen will only fail
if the ColorMap contains no sharable colors.
Defaults to FALSE.
Results
The correct pen value, or -1. A value of -1 indicates that no sharable palette entry may be available, no palette entry is available for allocation or, if the tag OBP_FailIfBad=TRUE is used, that no palette entry is close enough to the color you asked for.
Notes
If this call succceeds, then you must call ReleasePen() when you are done with the color.
When searching for the color which most closely matches the RGB
values passed, the graphics.library default color match function
will be used. You cannot override this function and you cannot
influence how it will perform the matching operation.
ObtainBestPenA() applies three metrices to find the color in the
ColorMap closest to the specified color, and will attempt to allocate
a new color if no good match could be found.
The first metric is employed by the default color match function of
graphics.library, which tests each ColorMap entry to find the one
whose color comes closest to the specified color.
The second metric is based upon the number of sharable colors in the
ColorMap and the number of colors left which can be allocated if there
is no good match available. The more colors are still available for
allocation the greater the focus on finding a good match before finally
trying to allocate a free color. As the number of colors available for
allocation shrinks, the greater the focus on allocating a free color
will become. The desired precision for the colors to match contributes
as much to this metric as the total number of sharable colors.
The third metric is controlled by the desired precision for the
colors to match and will be applied when the best possible match
has been found. If it fails to satisfy the specified precision,
ObtainBestPenA() will attempt to allocate a new color instead.
Bugs
The default color match function in graphics.library V39-V47 pays no attention to how close two colors are in terms of hue and brightness because it lends greatest weight to the largest relative difference in any two random RGB components. This will impact fidelity and will randomly consider two colors to "match most closely" which may have little else in common.
Both the color specified and the color information stored in the
ColorMap will be truncated during the search for the best
match. This means that if you specify a 96 bit RGB value, only the
4 most significant bits of each color component may be checked on
a system using the ECS or OCS graphics custom chips.
If ObtainBestPenA() eventually allocates a shared pen and sets the
pen color, it will not use the original 96 bit RGB value specified,
but a truncated version. These will be the 4 most significant bits
of each color component on ECS or OCS graphics chips and the 8 most
significant bits, respectively, for AGA graphics chips.
See also
GetColorMap(), ObtainPen(), ReleasePen(), FindColor(), SetRGB32()
ObtainPen()¶
ObtainPen -- Obtain a free palette entry for use by your program. (V39)
Synopsis
n = ObtainPen( cm, n, r, g, b, flags)
d0 a0 d0 d1 d2 d3 d4
LONG ObtainPen(ColorMap*,ULONG,ULONG,ULONG,ULONG,ULONG);
Function
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.
Inputs
cm = A pointer to a color map created by GetColorMap(). n = The index of the desired entry, or -1 if any one is acceptable rgb = The RGB values (32 bit left justified fractions) to set the new palette entry to. flags= PEN_EXCLUSIVE - tells the system that you want exclusive (non-shared) use of this pen value. Default is shared access.
PEN_NO_SETCOLOR - tells the system to not change the rgb values
for the selected pen. Really only makes sense for exclusive pens.
Results
n = The allocated pen. -1 will be returned if there is no pen available for you.
Notes
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
GetColorMap(), ReleasePen(), AttachPalExtra(), ObtainBestPenA()
OpenFont()¶
OpenFont -- Get a pointer to a system font.
Synopsis
font = OpenFont(textAttr)
D0 A0
Function
This function searches the system font space for the graphics text font that best matches the attributes specified. The pointer to the font returned can be used in subsequent SetFont and CloseFont calls. It is important to match this call with a corresponding CloseFont call for effective management of ram fonts.
Inputs
textAttr - a TextAttr or TTextAttr structure that describes the text font attributes desired.
Results
font is zero if the desired font cannot be found. If the named font is found, but the size and style specified are not available, a font with the nearest attributes is returned.
Bugs
Prior to V39 this function would return a TextFont pointer for any font which matched exactly in Y size, regardless of differences in DPI, or DotSize.
As part of fixing this bug it is REQUIRED that you use pass the
same TextAttr (or TTextAttr) to this function that was used when
OpenDiskFont() was called.
OpenFont(), and OpenDiskFont() use WeighTAMatch() to measure
how well two fonts match. WeightTAMatch() was a public function
in graphics.library V36-V37; it is now a system PRIVATE function
as of V39.
See also
CloseFont(), SetFont(), OpenDiskFont()
OpenMonitor()¶
OpenMonitor -- open a named MonitorSpec (V36)
Synopsis
mspc = OpenMonitor( monitor_name , display_id)
d0 a1 d0
struct MonitorSpec*OpenMonitor( char *, ULONG );
Function
Locate and open a named MonitorSpec.
Inputs
monitor_name - a pointer to a null terminated string. display_id - an optional 32 bit monitor/mode identifier
Results
mspc - a pointer to an open MonitorSpec structure. NULL if MonitorSpec could not be opened.
Note
if monitor_name is non-NULL, the monitor will be opened by name. if monitor_name is NULL the monitor will be opened by optional ID. if both monitor_name and display_id are NULL returns default monitor.
See also
OrRectRegion()¶
OrRectRegion -- Perform 2d OR operation of rectangle with region, leaving result in region.
Synopsis
status = OrRectRegion(region,rectangle)
d0 a0 a1
BOOL OrRectRegion(Region*,Rectangle* );
Function
If any portion of rectangle is not in the region then add that portion to the region.
Inputs
region - pointer to Region structure rectangle - pointer to Rectangle structure
Results
status - return TRUE if successful operation return FALSE if ran out of memory The region is left unchanged in case of failure.
Bugs
V40 releases and before may have left the region in an inconsistent state in case of failure.
See also
AndRectRegion(), OrRegionRegion()
OrRegionRegion()¶
OrRegionRegion -- Perform 2d OR operation of one region with second region, leaving result in second region
Synopsis
status = OrRegionRegion(region1,region2)
d0 a0 a1
BOOL OrRegionRegion(Region*,Region* );
Function
If any portion of region1 is not in the region then add that portion to the region2
Inputs
region1 - pointer to Region structure region2 - pointer to Region structure
Results
status - return TRUE if successful operation return FALSE if ran out of memory
Bugs
In case of failure, the target region may be partially updated.
See also
OwnBlitter()¶
OwnBlitter -- get the blitter for private usage
Synopsis
OwnBlitter()
void OwnBlitter( void );
Function
If blitter is available return immediately with the blitter locked for your exclusive use. If the blitter is not available put task to sleep. It will be awakened as soon as the blitter is available. When the task first owns the blitter the blitter may still be finishing up a blit for the previous owner. You must do a WaitBlit before actually using the blitter registers.
Calls to OwnBlitter() do not nest. If a task that owns the
blitter calls OwnBlitter() again, a lockup will result.
(Same situation if the task calls a system function
that tries to own the blitter).
Inputs
NONE
See also
PolyDraw()¶
PolyDraw -- Draw lines from table of (x,y) values.
Synopsis
PolyDraw( rp, count , array )
a1 d0 a0
void PolyDraw(RastPort*, WORD, WORD * );
Function
draws connected line segments between the current graphics cursor position to the first point in the array, and between every successive pair of points in it. The function does not attempt to draw a closed figure, i.e. drawing ends at the last point in the array.
Inputs
rp - pointer to RastPort structure count - number of (x,y) pairs in the array array - pointer to first (x,y) pair
Bugs
This function did not change between the current and and former versions of the operating system, though its description might have been misleading. The first line always started at the graphics cursor position, and no provisions are made to close the figure.
See also
QBlit()¶
QBlit -- Queue up a request for blitter usage
Synopsis
QBlit( bp )
a1
void QBlit( struct bltnode * );
Function
Link a request for the use of the blitter to the end of the current blitter queue. The pointer bp points to a blit structure containing, among other things, the link information, and the address of your routine which is to be called when the blitter queue finally gets around to this specific request. When your routine is called, you are in control of the blitter ... it is not busy with anyone else's requests. This means that you can directly specify the register contents and start the blitter. See the description of the blit structure and the uses of QBlit in the section titled Graphics Support in the OS Kernel Manual. Your code must be written to run either in supervisor or user mode on the 68000.
Inputs
bp - pointer to a blit structure
Results
Your routine is called when the blitter is ready for you. In general requests for blitter usage through this channel are put in front of those who use the blitter via OwnBlitter and DisownBlitter. However for small blits there is more overhead using the queuer than Own/Disown Blitter.
Notes
Code which uses QBlit(), or QBSBlit() should make use of the pointer to a cleanup routine in the bltnode structure. The cleanup routine may be called on the context of an interrupt, therefore the routine may set a flag, and signal a task, but it may not call FreeMem() directly. Use of the cleanup routine is the only safe way to signal that your bltnode has completed.
Bugs
QBlit(), and QBSBlit() have been rewritten for V39 due to various long standing bugs in earlier versions of this code.
See also
QBSBlit()¶
QBSBlit -- Synchronize the blitter request with the video beam.
Synopsis
QBSBlit( bsp )
a1
void QBSBlit( struct bltnode * );
Function
Call a user routine for use of the blitter, enqueued separately from the QBlit queue. Calls the user routine contained in the blit structure when the video beam is located at a specified position onscreen. Useful when you are trying to blit into a visible part of the screen and wish to perform the data move while the beam is not trying to display that same area. (prevents showing part of an old display and part of a new display simultaneously). Blitter requests on the QBSBlit queue take precedence over those on the regular blitter queue. The beam position is specified the blitnode.
Inputs
bsp - pointer to a blit structure. See description in the Graphics Support section of the manual for more info.
Results
User routine is called when the QBSBlit queue reaches this request AND the video beam is in the specified position. If there are lots of blits going on and the video beam has wrapped around back to the top it will call all the remaining bltnodes as fast as it can to try and catch up.
Notes
QBlit(), and QBSBlit() have been rewritten for V39. Queued blits are now handled in FIFO order. Tasks trying to OwnBlitter() are now given a fair share of the total blitter time available. QBSBlit() are no longer queued separately from nodes added by QBlit(). This fixes the ordering dependencies listed under BUGS in prior autodoc notes.
See also
ReadPixel()¶
ReadPixel -- read the pen number value of the pixel at a specified x,y location within a certain RastPort.
Synopsis
penno = ReadPixel( rp, x, y )
d0 a1 d0:16 d1:16
LONG ReadPixel(RastPort*, SHORT, SHORT );
Function
Combine the bits from each of the bit-planes used to describe a particular RastPort into the pen number selector which that bit combination normally forms for the system hardware selection of pixel color.
Inputs
rp - pointer to a RastPort structure (x,y) a point in the RastPort
Results
penno - the pen number of the pixel at (x,y) is returned. -1 is returned if the pixel cannot be read for some reason.
See also
ReadPixelArray8()¶
ReadPixelArray8 -- Read the color values of all the pixels in a rectangular array whose top left and bottom right edges describe its position, width and height. (V36)
Synopsis
count = ReadPixelArray8(rp,xstart,ystart,xstop,ystop,array,temprp)
D0 A0 D0:16 D1:16 D2:16 D3:16 A2 A1
LONG ReadPixelArray8(RastPort*, UWORD, UWORD, UWORD, UWORD,
UBYTE *,RastPort*);
Function
Read pixel color data from the RastPort, beginning at position (xstart, ystart), stopping at position (xstop, ystart). This process will continue for each following row, reading from position xstart to xstop, until the ystop row has been read.
When finished, a total of (xstop - xstart + 1) * (ystop - ystart + 1)
pixels will have been read in sequence.
The color data is read in bulk, which is significantly faster
than calling ReadPixel() for each single pixel covered.
Inputs
rp - pointer to a RastPort structure (xstart,ystart) - starting point in the RastPort; xstart must be <= xstop (xstop,ystop) - stopping point in the RastPort; ystart must be <= ystop array - Pointer to an array of UBYTEs into which to store the pixel data; the array must be large enough to hold a total of RASSIZE(xstop - xstart + 1, ystop - ystart + 1) number of bytes See the NOTES section for setting up the array. temprp - Temporary RastPort See the NOTES section for setting up the temporary RastPort.
Results
For each pixel in the array: Pen - Pixel color (0..255) at that position count - The number of pixels read; this will be (xstop - xstart + 1) * (ystop - ystart + 1)
Notes
The correct use of ReadPixelArray8() requires the temporary RastPort and the array to store the pixel color data in to be set up in a very specific manner. Deviating from these requirements can lead to data corruption and undefined behavior.
How you would set up the temporary RastPort and allocate a memory
buffer of the proper size is detailed with ready to use example
code in the EXAMPLE section.
For ReadPixelArray8() you would use the example code as follows:
#include <proto/exec.h>
#include <proto/graphics.h>
struct RastPort temprp;
UBYTE * array;
if (setup_temp_rastport(&temprp, rp, xstop - xstart + 1))
{
array = allocate_pixel_array(xstop - xstart + 1, ystop - ystart + 1);
if (array != NULL)
{
/* Call ReadPixelArray8(rp,xstart,ystart,xstop,ystop,array,&temprp)
* as needed.
*/
FreeVec(array);
}
cleanup_temp_rastport(&temprp, xstop - xstart + 1);
}
Example
To initialize a temporary RastPort and allocate memory for its BitMap you could use the following functions. Both require a temporary RastPort which first has to be initialized by setup_temp_rastport(). This involves allocating memory for a BitMap. In order to release the allocated memory call cleanup_temp_rastport().
The temporary RastPort can be allocated separately but a declaring a
local 'struct RastPort temprp;' is fine, too.
The ReadPixelLine8(), ReadPixelArray8(), WritePixelLine8() and
WritePixelArray8() functions transfer pixel color data to/from a
memory buffer with very specific size requirements. The
allocate_pixel_array() function below will accomplish this.
/* Initialize the temporary RastPort, then create a BitMap
* which is suitable for use with ReadPixelLine8(), ReadPixelArray8(),
* WritePixelLine8() and WritePixelArray8().
*
* This function will return FALSE if the BitMap could not be
* created and TRUE otherwise.
*
* Call cleanup_temp_rastport() when the BitMap is no longer needed,
* so that the memory allocated for it will be released again.
*/
BOOL
setup_temp_rastport(
struct RastPort * temp_rp,
CONST struct RastPort * rp,
UWORD width)
{
struct BitMap * temp_rp_bm;
BOOL success = FALSE;
int i, j;
/* Use a default RastPort configuration to avoid side-effects
* resulting from copying the source RastPort data.
*/
InitRastPort(temp_rp);
/* For Kickstart 3.0 and beyond use the designated BitMap
* allocation function in graphics.library.
*/
if (GfxBase->LibNode.lib_Version >= 39)
{
temp_rp->BitMap = AllocBitMap(width, 1,
GetBitMapAttr(rp->BitMap, BMA_DEPTH),
GetBitMapAttr(rp->BitMap, BMA_FLAGS) & BMF_INTERLEAVED,
NULL);
}
/* For Kickstart 2.x set up a BitMap via InitBitMap() and
* AllocRaster() for each single bitplane.
*/
else
{
temp_rp_bm = AllocVec(sizeof(*temp_rp_bm), MEMF_PUBLIC);
if (temp_rp_bm != NULL)
{
InitBitMap(temp_rp_bm, width, 1, rp->BitMap->Depth);
temp_rp->BitMap = temp_rp_bm;
for (i = 0 ; i < temp_rp_bm->Depth ; i++)
{
temp_rp_bm->Planes[i] = AllocRaster(width, 1);
if (temp_rp_bm->Planes[i] == NULL)
{
/* Free all the bit planes allocated so far. */
for (j = 0 ; j < i ; j++)
{
FreeRaster(temp_rp_bm->Planes[j], width, 1);
temp_rp_bm->Planes[j] = NULL;
}
temp_rp->BitMap = NULL;
FreeVec(temp_rp_bm);
break;
}
}
}
}
success = (BOOL)(temp_rp->BitMap != NULL);
return success;
}
/* Release the BitMap allocated for the temporary RastPort
* when no longer needed.
*/
VOID
cleanup_temp_rastport(
struct RastPort * temp_rp,
UWORD width)
{
int i;
if (temp_rp->BitMap != NULL)
{
/* Wait for the Blitter to finish, in case it is still
* modifying the BitMap created.
*/
WaitBlit();
if (GfxBase->LibNode.lib_Version >= 39)
{
FreeBitMap(temp_rp->BitMap);
}
else
{
for (i = 0 ; i < temp_rp->BitMap->Depth ; i++)
{
if (temp_rp->BitMap->Planes[i] != NULL)
{
FreeRaster(temp_rp->BitMap->Planes[i],
width, 1);
}
}
}
temp_rp->BitMap = NULL;
}
}
/* Allocate a memory buffer suitable for use with the ReadPixelLine8(),
* ReadPixelArray8(), WritePixelLine8() and WritePixelArray8() functions.
*
* Returns the address of the buffer allocated or NULL for failure. The
* memory buffer allocated can be freed with the FreeVec() function.
*
* For ReadPixelLine8() and WritePixelLine8() you would use height = 1.
*/
UBYTE *
allocate_pixel_array(UWORD width, UWORD height)
{
UBYTE * array;
array = AllocVec(RASSIZE(width, height), MEMF_PUBLIC);
return array;
}
Bugs
Previous documentation suggested copying the contents of the rp parameter when setting up the temprp (temporary RastPort). This is not recommended because the rp.Mask settings could interfere with the ClipBlit() operation implied by ReadPixelLine8(). This could yield corrupted color data.
See also
ReadPixelLine8()¶
ReadPixelLine8 -- Read the color values of all the pixels on a horizontal line, starting at a specified x,y location and continuing right for a given number of pixels. (V36)
Synopsis
count = ReadPixelLine8(rp,xstart,ystart,pixel_count,array,temprp)
D0 A0 D0:16 D1:16 D2 A2 A1
LONG ReadPixelLine8(RastPort*, UWORD, UWORD, UWORD,
UBYTE *,RastPort* );
Function
Read pixel color data from the RastPort, beginning at position (xstart, ystart) and stopping at position (xstart + pixel_count - 1, ystart).
The color data is read in bulk, which is significantly faster
than calling ReadPixel() for each single pixel covered.
Inputs
rp - Pointer to a RastPort structure (x,y) - A point in the RastPort pixel_count - Count of horizontal pixels to read; this must be >= 0 array - Pointer to an array of UBYTEs into which to store the pixel data; the array must be large enough to hold RASSIZE(num_pixels, 1) number of bytes. See the NOTES section for setting up the array. temprp - Temporary RastPort See the NOTES section for setting up the temporary RastPort.
Results
For each pixel in the array: Pen - Pixel color (0..255) at that position count - The number of pixels read (identical to pixel_count)
Notes
The correct use of ReadPixelLine8() requires the temporary RastPort and the array to store the pixel color data in to be set up in a very specific manner. Deviating from these requirements can lead to data corruption and undefined behavior.
How you would set up the temporary RastPort and allocate a memory
buffer of the proper size is detailed with ready to use example
code in the ReadPixelArray8() documentation EXAMPLE section.
For ReadPixelLine8() you would use the example code as follows:
#include <proto/exec.h>
#include <proto/graphics.h>
struct RastPort temprp;
UBYTE * array;
if (setup_temp_rastport(&temprp, rp, pixel_count))
{
array = allocate_pixel_array(pixel_count, 1);
if (array != NULL)
{
/* Call ReadPixelLine8(rp,xstart,ystart,pixel_count,array,&temprp)
* as needed.
*/
FreeVec(array);
}
cleanup_temp_rastport(&temprp, pixel_count);
}
Bugs
Previous documentation suggested copying the contents of the rp parameter when setting up the temprp (temporary RastPort). This is not recommended because the rp.Mask settings could interfere with the ClipBlit() operation implied by ReadPixelLine8(). This could yield corrupted color data.
See also
ReadPixel(), ReadPixelArray8(), ClipBlit()
RectFill()¶
RectFill -- Fill a rectangular region in a RastPort.
Synopsis
RectFill( rp, xmin, ymin, xmax, ymax)
a1 d0:16 d1:16 d2:16 d3:16
void RectFill(RastPort*, SHORT, SHORT, SHORT, SHORT );
Function
Fills the rectangular region specified by the parameters with the chosen pen colors, areafill pattern, and drawing mode. If no areafill pattern is specified, fill the rectangular region with the FgPen color, taking into account the drawing mode.
Inputs
rp - pointer to a RastPort structure (xmin,ymin) (xmax,ymax) are the coordinates of the upper left corner and the lower right corner, respectively, of the rectangle.
Note
The following relation MUST be true: (xmax >= xmin) and (ymax >= ymin)
Bugs
Complement mode with FgPen complements all bitplanes.
See also
ReleasePen()¶
ReleasePen -- Release an allocated palette entry to the free pool. (V39)
Synopsis
ReleasePen( cm, n)
a0 d0
void ReleasePen( Struct ColorMap *, ULONG);
Function
Return the palette entry for use by other applications. If the reference count for this palette entry goes to zero, then it may be reset to another RGB value.
Inputs
cm = A pointer to a color map created by GetColorMap().
n = A palette index obtained via any of the palette allocation
functions. Passing a -1 will result in this call doing
nothing.
Notes
This function works for both shared and exclusive palette entries.
See also
GetColorMap(), ObtainPen(), ObtainBestPenA()
RemBob()¶
RemBob -- Macro to remove a Bob from the gel list.
Synopsis
RemBob(bob)
RemBob(struct Bob*);
Function
Marks a Bob as no-longer-required. The gels internal code then removes the Bob from the list of active gels the next time DrawGList is executed. This is implemented as a macro. If the user is double-buffering the Bob, it could take two calls to DrawGList before the Bob actually disappears from the RastPort.
Inputs
Bob = pointer to the Bob to be removed
See also
RemFont()¶
RemFont -- Remove a font from the system list.
Synopsis
RemFont(textFont)
A1
void RemFont(TextFont*);
Function
This function removes a font from the system, ensuring that access to it is restricted to those applications that currently have an active pointer to it: i.e. no new SetFont requests to this font are satisfied.
Inputs
textFont - the TextFont structure to remove.
See also
RemIBob()¶
RemIBob -- Immediately remove a Bob from the gel list and the RastPort.
Synopsis
RemIBob(bob, rp, vp)
A0 A1 A2
void RemIBob(struct Bob*,RastPort*,ViewPort*);
Function
Removes a Bob immediately by uncoupling it from the gel list and erases it from the RastPort.
Inputs
bob = pointer to the Bob to be removed rp = pointer to the RastPort if the Bob is to be erased vp = pointer to the ViewPort for beam-synchronizing
See also
RemVSprite()¶
RemVSprite -- Remove a VSprite from the current gel list.
Synopsis
RemVSprite(vs)
A0
void RemVSprite(VSprite*);
Function
Unlinks the VSprite from the current gel list.
Inputs
vs = pointer to the VSprite structure to be removed from the gel list
See also
ScalerDiv()¶
ScalerDiv -- Get the scaling result that BitMapScale would. (V36)
Synopsis
result = ScalerDiv(factor, numerator, denominator)
D0 D0 D1 D2
UWORD ScalerDiv(UWORD, UWORD, UWORD);
Function
Calculate the expression (factor*numerator/denominator) such that the result is the same as the width of the destination result of BitMapScale when the factor here is the width of the source, and the numerator and denominator are the XDestFactor and XSrcFactor for BitMapScale.
Inputs
factor - a number in the range 0..16383 numerator, denominator - numbers in the range 1..16383
Results
this returns factor*numerator/denominator
ScrollRaster()¶
ScrollRaster -- Push bits in rectangle in raster around by dx,dy towards 0,0 inside rectangle.
Synopsis
ScrollRaster(rp, dx, dy, xmin, ymin, xmax, ymax)
A1 D0 D1 D2 D3 D4 D5
void ScrollRaster(RastPort*,
WORD, WORD, WORD, WORD, WORD, WORD);
Function
Move the bits in the raster by (dx,dy) towards (0,0) The space vacated is RectFilled with BGPen. Limit the scroll operation to the rectangle defined by (xmin,ymin)(xmax,ymax). Bits outside will not be affected. If xmax,ymax is outside the rastport then use the lower right corner of the rastport. If you are dealing with a SimpleRefresh layered RastPort you should check rp->Layer->Flags & LAYERREFRESH to see if there is any damage in the damage list. If there is you should call the appropriate BeginRefresh(Intuition) or BeginUpdate(graphics) routine sequence.
Inputs
rp - pointer to a RastPort structure dx,dy are integers that may be positive, zero, or negative xmin,ymin - upper left of bounding rectangle xmax,ymax - lower right of bounding rectangle
Example
ScrollRaster(rp,0,1,minx,miny,maxx,maxy) shift raster up by one row * ScrollRaster(rp,-1,-1,minx,miny,maxx,maxy) shift raster down and to the right by 1 pixel
Bugs
In 1.2/V1.3 if you ScrollRaster a SUPERBITMAP exactly left or right, and there is no TmpRas attached to the RastPort, the system will allocate one for you, but will never free it or record its location. This bug has been fixed for V36. The workaround for 1.2/1.3 is to attach a valid TmpRas of size at least MAXBYTESPERROW to the RastPort before the call.
Beginning with V36 ScrollRaster adds the shifted areas into the
damage list for SIMPLE_REFRESH windows. Due to unacceptable
system overhead, the decision was made NOT to propagate this
shifted area damage for SMART_REFRESH windows.
See also
ScrollRasterBF()¶
ScrollRasterBF -- Push bits in rectangle in raster around by dx,dy towards 0,0 inside rectangle. Newly empty areas will be filled via EraseRect(). (V39)
Synopsis
ScrollRasterBF(rp, dx, dy, xmin, ymin, xmax, ymax)
A1 D0 D1 D2 D3 D4 D5
void ScrollRasterBF(RastPort*, WORD, WORD, WORD,
WORD, WORD, WORD);
Function
Move the bits in the raster by (dx,dy) towards (0,0) The space vacated is filled by calling EraseRect(). Limit the scroll operation to the rectangle defined by (xmin,ymin)(xmax,ymax). Bits outside will not be affected. If xmax,ymax is outside the rastport then use the lower right corner of the rastport. If you are dealing with a SimpleRefresh layered RastPort you should check rp->Layer->Flags & LAYERREFRESH to see if there is any damage in the damage list. If there is you should call the appropriate BeginRefresh(Intuition) or BeginUpdate(graphics) routine sequence.
Inputs
rp - pointer to a RastPort structure dx,dy are integers that may be positive, zero, or negative xmin,ymin - upper left of bounding rectangle xmax,ymax - lower right of bounding rectangle
Notes
This call is exactly the same as ScrollRaster, except that it calls EraseRect() instead of RectFill() when clearing the newly exposed area. This allows use of a custom layer backfill hook.
See also
ScrollRaster(), EraseRect(), ScrollWindowRaster()
ScrollVPort()¶
ScrollVPort -- Reinterpret RasInfo information in ViewPort to reflect the current Offset values.
Synopsis
ScrollVPort( vp )
a0
void ScrollVPort(ViewPort*vp);
Function
After the programmer has adjusted the Offset values in the RasInfo structures of ViewPort, change the the copper lists to reflect the the Scroll positions. Changing the BitMap ptr in RasInfo and not changing the the Offsets will effect a double buffering affect.
Inputs
vp - pointer to a ViewPort structure that is currently be displayed.
Results
modifies hardware and intermediate copperlists to reflect new RasInfo
Bugs
pokes not fast enough to avoid some visible hashing of display (V37) This function was re-written in V39 and is ~10 times faster than before.
See also
MakeVPort(), MrgCop(), LoadView()
SetABPenDrMd()¶
SetABPenDrMd -- Set pen colors and draw mode for a RastPort (V39).
Synopsis
SetABPenDrMd( rp, apen, bpen, mode )
a1 d0 d1 d2
void SetABPenDrMd(RastPort*, ULONG, ULONG, ULONG );
Function
Set the pen values and drawing mode for lines, fills and text. Get the bit definitions from rastport.h
Inputs
rp - pointer to RastPort structure. apen - primary pen value bpen - secondary pen value mode - 0-255, some combinations may not make much sense.
Results
The mode set is dependent on the bits selected. Changes minterms to reflect new drawing mode and colors. Sets line drawer to restart pattern.
Notes
This call is essentially the same as a sequence of SetAPen()/SetBPen()/SetDrMD() calls, except that it is significantly faster. The minterms will only be generated once, or not at all if nothing changed (warning to illegal RastPort pokers!).
See also
SetAPen(), SetBPen(), SetDrMd()
SetAPen()¶
SetAPen -- Set the primary pen for a RastPort.
Synopsis
SetAPen( rp, pen )
a1 d0
void SetAPen(RastPort*, UBYTE );
Function
Set the primary drawing pen for lines, fills, and text.
Inputs
rp - pointer to RastPort structure. pen - (0-255)
Results
Changes the minterms in the RastPort to reflect new primary pen. Sets line drawer to restart pattern.
See also
SetBPen()¶
SetBPen -- Set secondary pen for a RastPort
Synopsis
SetBPen( rp, pen )
a1 d0
void SetBPen(RastPort*, UBYTE );
Function
Set the secondary drawing pen for lines, fills, and text.
Inputs
rp - pointer to RastPort structure. pen - (0-255)
Results
Changes the minterms in the RastPort to reflect new secondary pen. Sets line drawer to restart pattern.
See also
SetChipRev()¶
SetChipRev -- turns on the features of a Chip Set (V39)
Synopsis
chiprevbits = SetChipRev(ChipRev)
d0
ULONG SetChipRev(ULONG);
Function
Enables the features of the requested Chip Set if available, and updates the graphics database accordingly.
Inputs
ChipRev - Chip Rev that you would like to be enabled.
Results
chiprevbits - Actual bits set in GfxBase->ChipRevBits0.
Notes
This routine should only be called once. It will be called by the system in the startup-sequence, but is included in the autodocs for authors of bootblock-games that wish to take advantage of post-ECS features.
SetCollision()¶
SetCollision -- Set a pointer to a user collision routine.
Synopsis
SetCollision(num, routine, GInfo)
D0 A0 A1
void SetCollision(ULONG, VOID (*)(),GelsInfo*);
Function
Sets a specified entry (num) in the user's collision vectors table equal to the address of the specified collision routine.
Inputs
num = collision vector number routine = pointer to the user's collision routine GInfo = pointer to a GelsInfo structure
See also
SetDrMd()¶
SetDrMd -- Set drawing mode for a RastPort
Synopsis
SetDrMd( rp, mode )
a1 d0:8
void SetDrMd(RastPort*, UBYTE );
Function
Set the drawing mode for lines, fills and text. Get the bit definitions from rastport.h
Inputs
rp - pointer to RastPort structure. mode - 0-255, some combinations may not make much sense.
Results
The mode set is dependent on the bits selected. Changes minterms to reflect new drawing mode. Sets line drawer to restart pattern.
See also
SetFont()¶
SetFont -- Set the text font and attributes in a RastPort.
Synopsis
SetFont(rp, font)
A1 A0
void SetFont(RastPort*,TextFont*);
Function
This function sets the font in the RastPort to that described by font, and updates the text attributes to reflect that change. This function clears the effect of any previous soft styles.
Inputs
rp - the RastPort in which the text attributes are to be changed font - pointer to a TextFont structure returned from OpenFont() or OpenDiskFont()
Notes
This function had previously been documented that it would accept a null font. This practice is discouraged. o Use of a RastPort with a null font with text routines has always been incorrect and risked the guru. o Keeping an obsolete font pointer in the RastPort is no more dangerous than keeping a zero one there. o SetFont(rp, 0) causes spurious low memory accesses under some system software releases.
As of V36, the following Amiga font variants are no longer
directly supported:
fonts with NULL tf_CharSpace and non-NULL tf_CharKern.
fonts with non-NULL tf_CharSpace and NULL tf_CharKern.
fonts with NULL tf_CharSpace and NULL tf_CharKern with
a tf_CharLoc size component greater than tf_XSize.
Attempts to SetFont these one of these font variants will
cause the system to modify your font to make it acceptable.
Bugs
Calling SetFont() on in-code TextFonts (ie fonts not OpenFont()ed) will result in a loss of 24 bytes from the system as of V36. This can be resolved by calling StripFont().
See also
OpenFont(), StripFont(), OpenDiskFont()
SetMaxPen()¶
SetMaxPen -- set maximum pen value for a rastport (V39).
Synopsis
SetMaxPen ( rp, maxpen)
a0 d0
void SetMaxPen(RastPort*,ULONG)
Function
This will instruct the graphics library that the owner of the rastport will not be rendering in any colors whose index is >maxpen. If there are any speed optimizations which the graphics device can make based on this fact (for instance, setting the pixel write mask), they will be done.
Basically this call sets the rastport mask, if this would improve
speed. On devices where masking would slow things down (like with
chunky pixels), it will be a no-op.
Inputs
rp = a pointer to a valid RastPort structure. maxpen = a longword pen value.
Notes
The maximum pen value passed must take into account not only which colors you intend to render in the future, but what colors you will be rendering on top of. SetMaxPen(rp,0) doesn't make much sense.
See also
SetOPen()¶
SetOPen -- Change the Area OutLine pen and turn on Outline mode for areafills.
Synopsis
SetOPen(rp, pen)
void SetOPen(RastPort*, UBYTE );
Function
This is implemented as a c-macro. Pen is the pen number that will be used to draw a border around an areafill during AreaEnd().
Inputs
rp = pointer to RastPort structure pen = number between 0-255
See also
SetOutlinePen()¶
SetOutlinePen -- Set the Outline Pen value for a RastPort (V39).
Synopsis
old_pen=SetOutlinePen ( rp, pen )
d0 a0 d0
ULONG SetOutlinePen(RastPort*,ULONG)
Function
Set the current value of the O pen for the rastport and turn on area outline mode. This function should be used instead of poking the structure directly, because future graphics devices may store it differently, for instance, using more bits.
Inputs
rp = a pointer to a valid RastPort structure. pen = a longword pen number
returns the previous outline pen
See also
SetRast()¶
SetRast - Set an entire drawing area to a specified color.
Synopsis
SetRast( rp, pen )
a1 d0
void SetRast(RastPort*, UBYTE );
Function
Set the entire contents of the specified RastPort to the specified pen.
Inputs
rp - pointer to RastPort structure pen - the pen number (0-255) to jam into bitmap
Results
All pixels within the drawing area are set to the selected pen number.
See also
SetRGB32()¶
SetRGB32 -- Set one color register for this Viewport. (V39)
Synopsis
SetRGB32( vp, n, r, g, b)
a0 d0 d1 d2 d3
void SetRGB32(ViewPort*, ULONG, ULONG, ULONG, ULONG );
Inputs
vp = viewport n = the number of the color register to set. r = red level (32 bit left justified fraction) g = green level (32 bit left justified fraction) b = blue level (32 bit left justified fraction)
Results
If there is a ColorMap for this viewport, then the value will be stored in the ColorMap. The selected color register is changed to match your specs. If the color value is unused then nothing will happen.
Notes
Lower order bits of the palette specification will be discarded, depending on the color palette resolution of the target graphics device. Use 0xffffffff for the full value, 0x7fffffff for 50%, etc. You can find out the palette range for your screen by querying the graphics data base.
See also
GetColorMap(), GetRGB32(), SetRGB32CM(), LoadRGB32()
SetRGB32CM()¶
SetRGB32CM -- Set one color register for this ColorMap. (V39)
Synopsis
SetRGB32CM( cm, n, r, g, b)
a0 d0 d1 d2 d3
void SetRGB4CM(ColorMap*, ULONG, ULONG, ULONG , ULONG);
Inputs
cm = colormap n = the number of the color register to set. Must not exceed the number of c olors allocated for the colormap. r = red level (32 bit unsigned left justified fraction) g = green level b = blue level
Results
Store the (r,g,b) triplet at index n of the ColorMap structure. This function can be used to set up a ColorMap before before linking it into a viewport.
See also
GetColorMap(), GetRGB32(), SetRGB32(), SetRGB4CM()
SetRGB4()¶
SetRGB4 -- Set one color register for this viewport.
Synopsis
SetRGB4( vp, n, r, g, b)
a0 d0 d1:4 d2:4 d3:4
void SetRGB4(ViewPort*, SHORT, UBYTE, UBYTE, UBYTE );
Function
Change the color look up table so that this viewport displays the color (r,g,b) for pen number n.
Inputs
vp - pointer to viewport structure n - the color number (range from 0 to 31) r - red level (0-15) g - green level (0-15) b - blue level (0-15)
Results
If there is a ColorMap for this viewport, then the value will be stored in the ColorMap. The selected color register is changed to match your specs. If the color value is unused then nothing will happen.
Bugs
NOTE: Under V36 and up, it is not safe to call this function from an interrupt, due to semaphore protection of graphics copper lists.
See also
SetRGB4CM()¶
SetRGB4CM -- Set one color register for this ColorMap.
Synopsis
SetRGB4CM( cm, n, r, g, b)
a0 d0 d1:4 d2:4 d3:4
void SetRGB4CM(ColorMap*, SHORT, UBYTE, UBYTE, UBYTE );
Inputs
cm = colormap n = the number of the color register to set. Ranges from 0 to 31 on current Amiga displays. r = red level (0-15) g = green level (0-15) b = blue level (0-15)
Results
Store the (r,g,b) triplet at index n of the ColorMap structure. This function can be used to set up a ColorMap before before linking it into a viewport.
See also
GetColorMap(), GetRGB4(), SetRGB4()
SetRPAttrA()¶
SetRPAttrA -- modify rastport settings via a tag list SetRPAttrs -- varargs stub for SetRPAttrA
Synopsis
SetRPAttrA(rp,tags)
a0 a1
void SetRPAttrA(RastPort*,TagItem*);
SetRPAttrs(rp,tag,...);
Function
Modify settings of a rastport, based on the taglist passed. currently available tags are:
RPTAG_Font Font for Text()
RPTAG_SoftStyle style for text (see graphics/text.h)
RPTAG_APen Primary rendering pen
RPTAG_BPen Secondary rendering pen
RPTAG_DrMd Drawing mode (see graphics/rastport.h)
RPTAG_OutLinePen Area Outline pen
RPTAG_WriteMask Bit Mask for writing.
RPTAG_MaxPen Maximum pen to render (see SetMaxPen())
Inputs
rp - pointer to the RastPort to modify. tags - a standard tag list
See also
SetFont(), SetSoftStyle(), SetAPen(), SetBPen(), SetDrMd(), SetOutLinePen(), SetWriteMask(), SetMaxPen(), GetRPAttrA()
SetSoftStyle()¶
SetSoftStyle -- Set the soft style of the current font.
Synopsis
newStyle = SetSoftStyle(rp, style, enable)
D0 A1 D0 D1
ULONG SetSoftStyle(RastPort*, ULONG, ULONG);
Function
This function alters the soft style of the current font. Only those bits that are also set in enable are affected. The resulting style is returned, since some style request changes will not be honored when the implicit style of the font precludes changing them.
Inputs
rp - the RastPort from which the font and style are extracted. style - the new font style to set, subject to enable. enable - those bits in style to be changed. Any set bits here that would not be set as a result of AskSoftStyle will be ignored, and the newStyle result will not be as expected.
Results
newStyle - the resulting style, both as a result of previous soft style selection, the effect of this function, and the style inherent in the set font.
See also
SetWriteMask()¶
SetWriteMask -- Set the pixel write mask value for a RastPort (V39).
Synopsis
success=SetWriteMask ( rp, msk )
d0 a0 d0
ULONG SetWriteMask(RastPort*,ULONG)
Function
Set the current value of the bit write mask for the rastport. bits of the pixel with zeros in their mask will not be modified by subsequent drawing operations.
Inputs
rp = a pointer to a valid RastPort structure. msk = a longword mask value.
Graphics devices which do not support per-bit masking will
return 0 (failure).
SortGList()¶
SortGList -- Sort the current gel list, ordering its y,x coordinates.
Synopsis
SortGList(rp)
A1
void SortGList(RastPort*);
Function
Sorts the current gel list according to the gels' y,x coordinates. This sorting is essential before calls to DrawGList or DoCollision.
Inputs
rp = pointer to the RastPort structure containing the GelsInfo
See also
InitGels(), DoCollision(), DrawGList()
StripFont()¶
StripFont -- remove the tf_Extension from a font (V36)
Synopsis
StripFont(font)
A0
VOID StripFont(TextFont*);
SyncSBitMap()¶
SyncSBitMap -- Syncronize SuperBitMap with whatever is in the standard Layer bounds.
Synopsis
SyncSBitMap( layer )
a0
void SyncSBitMap(Layer* );
Function
Copy all bits from ClipRects in Layer into the SuperBitMap BitMap. This is used for those functions that do not want to deal with the ClipRect structures but do want to be able to work with a SuperBitMap Layer.
Inputs
layer - pointer to a Layer that has a SuperBitMap The Layer should already be locked by the caller.
Results
After calling this function, the programmer can manipulate the bits in the superbitmap associated with the layer. Afterwards, the programmer should call CopySBitMap to copy the bits back into the onscreen layer.
See also
Text()¶
Text -- Write text characters (no formatting).
Synopsis
Text(rp, string, length)
A1 A0 D0-0:16
void Text(RastPort*, STRPTR, WORD);
Function
This graphics function writes printable text characters to the specified RastPort at the current position. No control meaning is applied to any of the characters, thus only text on the current line is output.
The current position in the RastPort is updated to the next
character position.
If the characters displayed run past the RastPort boundary,
the current position is truncated to the boundary, and
thus does not equal the old position plus the text length.
Inputs
rp - a pointer to the RastPort which describes where the text is to be output string - the address of string to output length - the number of characters in the string. If zero, there are no characters to be output.
Notes
o This function may use the blitter. o Changing the text direction with RastPort->TxSpacing is not supported.
Bugs
For V34 and earlier: o The maximum string length (in pixels) is limited to (1024 - 16 = 1008) pixels wide. o A text string whose last character(s) have a tf_CharLoc size component that extends to the right of the rightmost of the initial and final CP positions will be (inappropriately) clipped.
See also
TextExtent()¶
TextExtent -- Determine raster extent of text data. (V36)
Synopsis
TextExtent(rp, string, count, textExtent)
A1 A0 D0:16 A2
void textExtent(RastPort*, STRPTR, WORD,
TextExtent*);
Function
This function determines a more complete metric of the space that a text string would render into than the TextLength() function.
Inputs
rp - a pointer to the RastPort which describes where the text attributes reside. string - the address of the string to determine the length of. count - the number of characters in the string. If zero, there are no characters in the string. textExtent - a structure to hold the result.
Results
textExtent is filled in as follows: te_Width - same as TextLength() result: the rp_cp_x advance that rendering this text would cause. te_Height - same as tf_YSize. The height of the font. te_Extent.MinX - the offset to the left side of the rectangle this would render into. Often zero. te_Extent.MinY - same as -tf_Baseline. The offset from the baseline to the top of the rectangle this would render into. te_Extent.MaxX - the offset of the left side of the rectangle this would render into. Often the same as te_Width-1. te_Extent.MaxY - same as tf_YSize-tf_Baseline-1. The offset from the baseline to the bottom of the rectangle this would render into.
Bugs
Before V47, this function suffered from an off-by-one error in case the input font was not fixed width.
See also
TextLength(), Text(), TextFit()
TextFit()¶
TextFit - count characters that will fit in a given extent (V36)
Synopsis
chars = TextFit(rastport, string, strLen, textExtent,
D0 A1 A0 D0 A2
constrainingExtent, strDirection,
A3 D1
constrainingBitWidth, constrainingBitHeight)
D2 D3
ULONG TextFit(RastPort*, STRPTR, UWORD,
TextExtent*,TextExtent*, WORD, UWORD, UWORD);
Function
This function determines how many of the characters of the provided string will fit into the space described by the constraining parameters. It also returns the extent of that number of characters.
Inputs
rp - a pointer to the RastPort which describes where the text attributes reside. string - the address of string to determine the constraint of strLen - The number of characters in the string. If zero, there are no characters in the string. textExtent - a structure to hold the extent result. constrainingExtent - the extent that the text must fit in. This can be NULL, indicating only the constrainingBit dimensions will describe the constraint. strDirection - the offset to add to the string pointer to get to the next character in the string. Usually 1. Set to -1 and the string to the end of the string to perform a TextFit() anchored at the end. No other value is valid. constrainingBitWidth - an alternative way to specify the rendering box constraint width that is independent of the rendering origin. Range 0..32767. constrainingBitHeight - an alternative way to specify the rendering box constraint height that is independent of the rendering origin. Range 0..32767.
Results
chars - the number of characters from the origin of the given string that will fit in both the constraining extent (which specifies a CP bound and a rendering box relative to the origin) and in the rendering width and height specified.
Notes
The result is zero chars and an empty textExtent when the fit cannot be performed. This occurs not only when no text will fit in the provided constraints, but also when: - the RastPort rp's rp_TxSpacing sign and magnitude is so great it reverses the path of the text. - the constrainingExtent does not include x = 0.
Bugs
Under V37, TextFit() would return one too few characters if the font was proportional. This can be worked around by passing (constrainingBitWidth + 1) for proportional fonts. This is fixed for V39.
See also
TextExtent(), TextLength(), Text()
TextLength()¶
TextLength -- Determine raster length of text data.
Synopsis
length = TextLength(rp, string, count)
D0 A1 A0 D0:16
WORD TextLength(RastPort*, STRPTR, WORD);
Function
This graphics function determines the length that text data would occupy if output to the specified RastPort with the current attributes. The length is specified as the number of raster dots: to determine what the current position would be after a Write() using this string, add the length to cp_x (cp_y is unchanged by Write()). Use the newer TextExtent() to get more information.
Inputs
rp - a pointer to the RastPort which describes where the text attributes reside. string - the address of string to determine the length of count - the string length. If zero, there are no characters in the string.
Results
length - the number of pixels in x this text would occupy, not including any negative kerning that may take place at the beginning of the text string, nor taking into account the effects of any clipping that may take place.
Notes
Prior to V36, the result length occupied only the low word of d0 and was not sign extended into the high word.
Bugs
A length that would overflow single word arithmetic is not calculated correctly.
See also
TextExtent(), Text(), TextFit()
UCopperListInit()¶
UCopperListInit -- Initialize user copperlist to accept intermedidate user copper instructions.
Synopsis
cl = CINIT( ucl , n )
cl = UCopperListInit( ucl , n )
a0 d0
struct CopList*UCopperListInit(struct UCopList*, UWORD );
Function
Allocates and/or initialize copperlist structures/buffers internal to a UCopList structure.
This is a macro that calls UCopListInit. You must pass a
(non-initialized) UCopList to UCopperListInit. It will
then initialize the intermediate data buffers internal
to a UCopList.
The maximum number of intermediate copper list instructions
that these internal CopList data buffers contain is specified
as the parameter n.
The CINIT macro is identical to this function
Inputs
ucl - pointer to UCopList structure or NULL n - number of instructions buffer must be able to hold
Results
cl- a pointer to a buffer which will accept n intermediate copper instructions.
NOTE: this is NOT a UCopList pointer, rather a pointer to the
UCopList's->FirstCopList sub-structure.
Bugs
This function does not actually allocate a new UCopList if ucl==0, instead it fails if the argument is NULL. You have to allocate a block MEMF_PUBLIC|MEMF_CLEAR of sizeof(struct UCopList) bytes and pass it to this function.
The system's FreeVPortCopLists function will take care of
deallocating it if they are called.
Prior to release V36 the CINIT macro had { } braces surrounding
the definition, preventing the proper return of the result value.
These braces have been removed for the V36 include definitions.
UnlockLayerRom()¶
UnlockLayerRom -- Unlock Layer structure by ROM(gfx lib) code.
Synopsis
UnlockLayerRom( layer )
a5
void UnlockLayerRom(Layer* );
Function
Release the lock on this layer. If the same task has called LockLayerRom more than once than the same number of calls to UnlockLayerRom must happen before the layer is actually freed so that other tasks may use it. This call does destroy scratch registers. This call is identical to UnlockLayer (layers.library).
Inputs
layer - pointer to Layer structure
See also
VBeamPos()¶
VBeamPos -- Get vertical beam position at this instant.
Synopsis
pos = VBeamPos()
d0
LONG VBeamPos( void );
Function
Get the vertical beam position from the hardware.
Inputs
none
Results
interrogates hardware for beam position and returns value. valid results in are the range of 0-2047, depending on the display mode of the frontmost view. Because of multitasking, the actual value returned may have little use. If you are the highest priority task then the value returned should be close, within 1 line.
VideoControl()¶
VideoControl -- Modify the operation of a ViewPort's ColorMap (V36) VideoControlTags -- varargs stub for VideoControl (V36)
Synopsis
error = VideoControl( cm , tags )
d0 a0 a1
ULONG VideoControl(ColorMap*,TagItem* );
error= VideoControlTags(cm, tags,...);
Function
Process the commands in the VideoControl command TagItem buffer using cm as the target, with respect to its "attached" ViewPort.
viewport commands:
VTAG_ATTACH_CM [_SET | _GET] -- set/get attached viewport
VTAG_VIEWPORTEXTRA [_SET | _GET] -- set/get attached vp_extra
VTAG_NORMAL_DISP [_SET | _GET] -- set/get DisplayInfoHandle
(natural mode)
VTAG_COERCE_DISP [_SET | _GET] -- set/get DisplayInfoHandle
(coerced mode)
VTAG_PF1_BASE [_SET | _GET] -- set/get color base for
first playfield. (V39)
VTAG_PF2_BASE [_SET | _GET] -- set/get color base for
second playfield. (V39)
VTAG_SPODD_BASE [_SET | _GET] -- set/get color base for odd
sprites. (V39)
VTAG_SPEVEN_BASE [_SET | _GET] -- set/get color base for even
sprites. (V39)
VTAG_BORDERSPRITE [_SET | _GET] -- on/off/inquire sprites in
borders. (V39)
VTAG_SPRITERESN [_SET | _GET] -- set/get sprite resolution
(legal values are SPRITERESN_ECS/_140NS/_70NS/_35NS.
see graphics/view.h) (V39)
VTAG_PF1_TO_SPRITEPRI [_SET | _GET] -- set/get playfield1 priority
with respect to sprites (V39)
VTAG_PF2_TO_SPRITEPRI [_SET | _GET] -- set/get playfield2 priority
with respect to sprites (V39)
(These two require that the ColorMap is attached to a ViewPort to be
effective).
genlock commands:
VTAG_BORDERBLANK [_SET | _CLR | _GET] -- on/off/inquire blanking
VTAG_BORDERNOTRANS [_SET | _CLR | _GET] -- on/off/inquire notransparency
VTAG_CHROMAKEY [_SET | _CLR | _GET] -- on/off/inquire chroma mode
VTAG_BITPLANEKEY [_SET | _CLR | _GET] -- on/off/inquire bitplane mode
VTAG_CHROMA_PEN [_SET | _CLR | _GET] -- set/clr/get chromakey pen #
VTAG_CHROMA_PLANE [_SET | | _GET] -- set/get bitplanekey plane #
control commands:
VTAG_IMMEDIATE - normally, VideoControl changes do not occur until the
next MakeVPort. Using this tag, some changes can be made to
happen immediately. The tag data is a pointer to a longword
flag variable which will be cleared if all changes happened
immediately. See the example. (V39)
VTAG_FULLPALETTE [_SET | _CLR | _GET] -- enable/disable loading of all
colors in the copper list.
Normally, graphics will only load the color which are necessary
for the viewport, based upon the screen depth and mode. In order
to use the color palette banking features, you may need to use
this tag to tell graphics to load ALL colors, regardless of
screen depth. (V39)
VC_IntermediateCLUpdate
VC_IntermediateCLUpdate_Query
When set, graphics will update the intermediate copper
lists on colour changes. When FALSE, graphics won't update
the intermediate copperlists, so ScrollVPort(),
ChangeVPBitMap() and colour loading functions will be faster.
This value is TRUE by default. (V40)
VC_NoColorPaletteLoad
VC_NoColorPaletteLoad_Query
When set, only colour 0 will be loaded for this ViewPort,
hence the inter-ViewPort gap will be smaller. The colours for
this ViewPort are inherited from the next higher ViewPort. The
results are undefined if this is the first or only ViewPort in
the display, and undefined when used in conjunction with
VTAG_FULLPALETTE (!?!).
This value is FALSE by default. (V40)
VC_DUALPF_Disable
VC_DUALPF_Disable_Query
When set, disables the setting of the dual-playfield
bit in bplcon0. When used with a dual-playfield mode
screen, this allows using separate scroll and bitmaps
for the odd and even bitplanes, without going through
the normal dual-playfield priority and palette selection.
With appropriate palette setup, this can be used for
transparency effects, etc.
copper commands
VTAG_USERCLIP [_SET | _CLR | _GET] -- on/off/inquire clipping of
UserCopperList at bottom
edge of ColorMap->cm_vp
(defaults to off)
buffer commands:
VTAG_NEXTBUF_CM -- link to more VTAG commands
VTAG_END_CM -- terminate command buffer
batch mode commands:
(if you want your videocontrol taglist to be processed in "batch"
mode, that is, at the next MakeVPort() for the ColorMap->cm_vp;
you may install a static list of videocontrol TagItems into the
ColorMap with the BATCH_ITEMS_SET command; and then enable/disable
batch mode processing of those items via the BATCH_CM control
command)
VTAG_BATCH_CM [_SET | _CLR | _GET] -- on/off/inquire batch mode
VTAG_BATCH_ITEMS [_SET | _ADD | _GET] -- set/add/get batched TagLists
private commands (used internally by intuition -- do not call):
VTAG_VPMODEID [_SET | _CLR | _GET] -- force GetVPModeID() return
Inputs
cm = pointer to struct ColorMap obtained via GetColorMap(). tags = pointer to a table of videocontrol tagitems.
Results
error = NULL if no error occurred in the control operation. (non-NULL if bad colormap pointer, no tagitems or bad tag)
The operating characteristics of the ColorMap and its attached
ViewPort are modified. The result will be incorporated into the
ViewPort when its copper lists are reassembled via MakeVPort().
Note that you must NOT change colors in the viewport (via SetRGB4(),
LoadRGB4(), SetRGB4(), etc.) after changing any of the color palette
offsets (VTAG_PF1_BASE, etc), without first remaking the ViewPort.
Notes
Sprite resolutions is controlled by two sets of tags, SPRITERESN and DEFSPRITERESN. If you don't set the sprite resolution, it will follow the intuition-controlled "default" sprite resolution. Setting the sprite resolution to one of the SPRITERESN_ values will allow the application to override intuition's control of it.
This function will modify the contents of the TagList you pass to it by
changing _GET tags to the corresponding _SET or _CLR tag. The
exceptions to this rule are documented as such above (such as
VTAG_IMMEDIATE).
The new tags added for V40 have the prefix VC_ instead of VTAG_. These
tags work in the same manner as all other tags in the system, and will
not be modified by VideoControl().
Example
struct TagItem VCTags[] = { {VC_NoColorPaletteLoad_Query, NULL}, {TAG_DONE}, }; ULONG query;
VCTags[0].ti_Data = (ULONG)&query;
if (VideoControl(cm, VCTags) == NULL)
{
printf("Palette loading is %s\n", (query ? "off" : "on"));
}
Bugs
VTAG_SPRITERESN_GET and VTAG_DEFSPRITERESN_GET returned 0xff instead of -1 for the default sprite resolution under V45 and below.
See also
VPOrigin()¶
VPOrigin -- Find the first visible pixel in the ViewPort (V39)
Synopsis
VPOrigin(v, vp, origin1, origin2)
a0 a1 a2 a3
void VPOrigin(View*,ViewPort*, Point *, Point *);
Function
To find the top left visible pixel in a viewport after accounting for hardware limitations.
Inputs
v - View the ViewPort is in. vp - This ViewPort origin1 - The Point structure that is to be filled for the first playfield. origin2 - The Point structure that is to be filled for the second playfield, or NULL if not dualplayfield.
Results
originx - The Point structure will hold the coordinate in ViewPort resolution of the first visible pixel, relative to the View origin.
Notes
The ViewPort must have a properly initialised DisplayClip in a ViewPortExtra that has been Associated with the ViewPort.
See also
WaitBlit()¶
WaitBlit -- Wait for the blitter to be finished before proceeding with anything else.
Synopsis
WaitBlit()
void WaitBlit( void );
Function
WaitBlit returns when the blitter is idle. This function should normally only be used when dealing with the blitter in a synchronous manner, such as when using OwnBlitter and DisownBlitter. WaitBlit does not wait for all blits queued up using QBlit or QBSBlit. You should call WaitBlit if you are just about to modify or free some memory that the blitter may be using.
Inputs
none
Results
Your program waits until the blitter is finished. This routine does not use any the CPU registers. do/d1/a0/a1 are preserved by this routine. It may change the condition codes though.
Bugs
When examining bits with the CPU right after a blit, or when freeing temporary memory used by the blitter, a WaitBlit() may be required.
Note that many graphics calls fire up the blitter, and let it run.
The CPU does not need to wait for the blitter to finish before
returning.
Because of a bug in Agnus (prior to all revisions of fat Agnus)
this code may return too soon when the blitter has, in fact, not
started the blit yet, even though BltSize has been written.
This most often occurs in a heavily loaded system with extended memory,
HIRES, and 4 bitplanes.
WaitBlit currently tries to avoid this Agnus problem by testing
the BUSY bit multiple times to make sure the blitter has started.
If the blitter is BUSY at first check, this function busy waits.
This initial hardware bug was fixed as of the first "Fat Agnus" chip,
as used in all A500 and A2000 computers.
Because of a different bug in Agnus (currently all revisions thru ECS)
this code may return too soon when the blitter has, in fact, not
stopped the blit yet, even though blitter busy has been cleared.
This most often occurs in a heavily loaded system with extended memory,
in PRODUCTIVITY mode, and 2 bitplanes.
WaitBlit currently tries to avoid this Agnus problem by testing
the BUSY bit multiple times to make sure the blitter has really
written its final word of destination data.
See also
WaitBOVP()¶
WaitBOVP -- Wait till vertical beam reached bottom of this viewport.
Synopsis
WaitBOVP( vp )
a0
void WaitBOVP(ViewPort* );
Function
Returns when the vertical beam has reached the bottom of this viewport
Inputs
vp - pointer to ViewPort structure
Results
This function will return sometime after the beam gets beyond the bottom of the viewport. Depending on the multitasking load of the system, the actual beam position may be different than what would be expected in a lightly loaded system.
Bugs
Horrors! This function currently busy waits waiting for the beam to get to the right place. It should use the copper interrupt to trigger and send signals like WaitTOF does.
See also
WaitTOF()¶
WaitTOF -- Wait for the top of the next video frame.
Synopsis
WaitTOF()
void WaitTOF( void );
Function
Wait for vertical blank to occur and all vertical blank interrupt routines to complete before returning to caller.
Inputs
none
Results
Places this task on the TOF wait queue. When the vertical blank interrupt comes around, the interrupt service routine will fire off signals to all the tasks doing WaitTOF. The highest priority task ready will get to run then.
See also
WriteChunkyPixels()¶
WriteChunkyPixels -- Write the color values of all the pixels in a rectangular array whose top left and bottom right edges describe its position, width and height. (V40)
Synopsis
WriteChunkyPixels(rp,xstart,ystart,xstop,ystop,array,bytesperrow)
A0 D0 D1 D2 D3 A2 D4
VOID WriteChunkyPixels(RastPort*, LONG, LONG,
LONG, LONG, CONST UBYTE *, LONG);
Function
Write pixel color data to the RastPort, beginning at position (xstart, ystart), stopping at position (xstop, ystart). This process will continue for each following row, writing from position xstart to xstop, until the ystop row has been written.
The color data is written in bulk, which is significantly faster
than calling WritePixel() for each single pixel covered.
Inputs
rp - Pointer to a RastPort structure (xstart,ystart) - Starting point in the RastPort; xstart must be <= xstop (xstop,ystop) - Stopping point in the RastPort; ystart must be <= ystop array - Pointer to an array of UBYTEs from which to fetch the pixel data. This data will not be changed. bytesperrow - The number of bytes per row in the source array. This should be at least as large as the number of pixels being written per line.
Bugs
The emulated WriteChunkyPixels() function used in all Amiga Kickstart ROMs (V40-V44) save for the Amiga CD32 could fail silently if insufficient memory was available.
In V45 speed improved over previous versions, and support for
specialized chunky to planar conversion hardware was dropped.
See also
WritePixel(), WritePixelLine8(), WritePixelArray8(), ClipBlit()
WritePixel()¶
WritePixel -- Change the pen num of one specific pixel in a specified RastPort.
Synopsis
error = WritePixel( rp, x, y)
d0 a1 D0 D1
LONG WritePixel(RastPort*, SHORT, SHORT );
Function
Changes the pen number of the selected pixel in the specified RastPort to that currently specified by PenA, the primary drawing pen. Obeys minterms in RastPort.
Inputs
rp - a pointer to the RastPort structure (x,y) - point within the RastPort at which the selected pixel is located.
Results
error = 0 if pixel succesfully changed = -1 if (x,y) is outside the RastPort
See also
WritePixelArray8()¶
WritePixelArray8 -- Write the color values of all the pixels in a rectangular array whose top left and bottom right edges describe its position, width and height. (V36)
Synopsis
count = WritePixelArray8(rp,xstart,ystart,xstop,ystop,array,temprp)
D0 A0 D0:16 D1:16 D2:16 D3:16 A2 A1
LONG WritePixelArray8(RastPort*, UWORD, UWORD,
UWORD, UWORD, UBYTE *,RastPort*);
Function
Write pixel color data to the RastPort, beginning at position (xstart, ystart), stopping at position (xstop, ystart). This process will continue for each following row, writing from position xstart to xstop, until the ystop row has been written.
When finished, a total of (xstop - xstart + 1) * (ystop - ystart + 1)
pixels will have been written in sequence.
The color data is written in bulk, which is significantly faster
than calling WritePixel() for each single pixel covered.
Inputs
rp - pointer to a RastPort structure (xstart,ystart) - starting point in the RastPort; xstart must be <= xstop (xstop,ystop) - stopping point in the RastPort; ystart must be <= ystop array - Pointer to an array of UBYTEs from which to fetch the pixel data; the array must be large enough to hold a total of RASSIZE(xstop - xstart + 1, ystop - ystart + 1) number of bytes See the NOTES section for setting up the array.
CAUTION: The contents of the array will be
destroyed. See the WARNING section
for more information.
temprp - Temporary RastPort
See the NOTES section for setting up the temporary
RastPort.
Results
The number of pixels written, which will be (xstop - xstart + 1) * (ystop - ystart + 1)
Notes
The correct use of WritePixelArray8() requires the temporary RastPort and the array to read the pixel color data from to be set up in a very specific manner. Deviating from these requirements can lead to data corruption and undefined behavior.
How you would set up the temporary RastPort and allocate a memory
buffer of the proper size is detailed with ready to use example
code in the EXAMPLE section.
For WritePixelArray8() you would use the example code as follows:
#include <proto/exec.h>
#include <proto/graphics.h>
struct RastPort temprp;
UBYTE * array;
if (setup_temp_rastport(&temprp, rp, xstop - xstart + 1))
{
array = allocate_pixel_array(xstop - xstart + 1, ystop - ystart + 1);
if (array != NULL)
{
/* Call WritePixelArray8(rp,xstart,ystart,xstop,ystop,array,&temprp)
* as needed.
*/
FreeVec(array);
}
cleanup_temp_rastport(&temprp, xstop - xstart + 1);
}
Bugs
Previous versions of this function could read over the end of the supplied array, or even write into it. Even though the code attempted to restore the original data, it might have been too late in case program code (e.g. interrupt code) was contained in the memory region past the buffer end.
Previous documentation suggested copying the contents of the rp
parameter when setting up the temprp (temporary RastPort). This is
not recommended because the rp.Mask settings could interfere with
the ClipBlit() operation implied by WritePixelLine8(). This could
yield corrupted color data.
V45 and above no longer require the temporary RastPort address
in register A1. You no longer need to initialize a temporary RastPort
and may pass NULL in place of its address instead.
See also
WritePixel(), ReadPixelArray8(), WritePixelLine8(), WriteChunkyPixels(), ClipBlit()
WritePixelLine8()¶
WritePixelLine8 -- Write the color values of all the pixels on a horizontal line, starting at a specified x,y location and continuing right for a given number of pixels. (V36)
Synopsis
count = WritePixelLine8(rp,xstart,ystart,width,array,temprp)
D0 A0 D0:16 D1:16 D2 A2 A1
LONG WritePixelLine8(RastPort*, UWORD, UWORD,
UWORD, UBYTE *,RastPort*);
Function
Write pixel color data to the RastPort, beginning at position (xstart, ystart) and stopping at position (xstart + pixel_count - 1, ystart).
The color data is written in bulk, which is significantly faster
than calling WritePixel() for each single pixel to be changed.
Inputs
rp - Pointer to a RastPort structure (x,y) - A point in the RastPort pixel_count - Count of horizontal pixels to change; this must be >= 0 array - Pointer to an array of UBYTEs from which to fetch the pixel data; the array must be large enough to hold RASSIZE(num_pixels, 1) number of bytes. See the NOTES section for setting up the array.
CAUTION: The contents of the array will be
destroyed. See the WARNING section
for more information.
temprp - Temporary RastPort
See the NOTES section for setting up the temporary
RastPort.
Results
The number of pixels written (identical to pixel_count)
Notes
The correct use of WritePixelLine8() requires the temporary RastPort and the array to read the pixel color data from to be set up in a very specific manner. Deviating from these requirements can lead to data corruption and undefined behavior.
How you would set up the temporary RastPort and allocate a memory
buffer of the proper size is detailed with ready to use example
code in the ReadPixelArray8() documentation EXAMPLE section.
For WritePixelLine8() you would use the example code as follows:
#include <proto/exec.h>
#include <proto/graphics.h>
struct RastPort temprp;
UBYTE * array;
if (setup_temp_rastport(&temprp, rp, pixel_count))
{
array = allocate_pixel_array(pixel_count, 1);
if (array != NULL)
{
/* Call WritePixelLine8(rp,xstart,ystart,pixel_count,array,&temprp)
* as needed.
*/
FreeVec(array);
}
cleanup_temp_rastport(&temprp, pixel_count);
}
Bugs
Previous versions of this function could read over the end of the supplied array, or even write into it. Even though the code attempted to restore the original data, it might have been too late in case program code (e.g. interrupt code) was contained in the memory region past the buffer end.
Previous documentation suggested copying the contents of the rp
parameter when setting up the temprp (temporary RastPort). This is
not recommended because the rp.Mask settings could interfere with
the ClipBlit() operation implied by WritePixelLine8(). This could
yield corrupted color data.
V45 and above no longer require the temporary RastPort address
in register A1. You no longer need to initialize a temporary RastPort
and may pass NULL in place of its address instead.
See also
WritePixel(), ReadPixelArray8(), WritePixelArray8(), WriteChunkyPixels(), ClipBlit()
XorRectRegion()¶
XorRectRegion -- Perform 2d XOR operation of rectangle with region, leaving result in region
Synopsis
status = XorRectRegion(region,rectangle)
d0 a0 a1
BOOL XorRectRegion(Region*,Rectangle* );
Function
Add portions of rectangle to region if they are not in the region. Remove portions of rectangle from region if they are in the region.
Inputs
region - pointer to Region structure rectangle - pointer to Rectangle structure
Results
status - return TRUE if successful operation return FALSE if ran out of memory The region is left unchanged in case of failure.
Bugs
V40 releases and before may have left the region in an inconsistent state in case of failure.
See also
OrRegionRegion(), AndRegionRegion()
XorRegionRegion()¶
XorRegionRegion -- Perform 2d XOR operation of one region with second region, leaving result in second region
Synopsis
status = XorRegionRegion(region1,region2)
d0 a0 a1
BOOL XorRegionRegion(Region*,Region* );
Function
Join the regions together. If any part of region1 overlaps region2 then remove that from the new region.
Inputs
region1 = pointer to Region structure region2 = pointer to Region structure
Results
status - return TRUE if successful operation return FALSE if ran out of memory
Bugs
In case of failure, the target region may be partially updated.