TABLE OF CONTENTS graphics.library/AddAnimOb graphics.library/AddBob graphics.library/AddFont graphics.library/AddVSprite graphics.library/AllocBitMap graphics.library/AllocBitMapTagList graphics.library/AllocDBufInfo graphics.library/AllocRaster graphics.library/AllocSpriteDataA graphics.library/AndRectRegion graphics.library/AndRegionRegion graphics.library/Animate graphics.library/AreaCircle graphics.library/AreaDraw graphics.library/AreaEllipse graphics.library/AreaEnd graphics.library/AreaMove graphics.library/AskFont graphics.library/AskSoftStyle graphics.library/AttachPalExtra graphics.library/AttemptLockLayerRom graphics.library/BestModeIDA graphics.library/BitMapScale graphics.library/BltBitMap graphics.library/BltBitMapRastPort graphics.library/BltBitMapTagList graphics.library/BltClear graphics.library/BltMaskBitMapRastPort graphics.library/BltPattern graphics.library/BltTemplate graphics.library/CalcIVG graphics.library/CBump graphics.library/CEND graphics.library/ChangeExtSpriteA graphics.library/ChangeSprite graphics.library/ChangeVPBitMap graphics.library/CINIT graphics.library/ClearEOL graphics.library/ClearRectRegion graphics.library/ClearRegion graphics.library/ClearScreen graphics.library/ClipBlit graphics.library/CloseFont graphics.library/CloseMonitor graphics.library/CMOVE graphics.library/CoerceMode graphics.library/CompositeTagList graphics.library/CopySBitMap graphics.library/CWAIT graphics.library/DisownBlitter graphics.library/DisposeRegion graphics.library/DoCollision graphics.library/Draw graphics.library/DrawEllipse graphics.library/DrawGList graphics.library/EraseRect graphics.library/ExtendFont graphics.library/FindColor graphics.library/FindDisplayInfo graphics.library/Flood graphics.library/FontExtent graphics.library/FreeBitMap graphics.library/FreeColorMap graphics.library/FreeCopList graphics.library/FreeCprList graphics.library/FreeDBufInfo graphics.library/FreeGBuffers graphics.library/FreeRaster graphics.library/FreeSprite graphics.library/FreeSpriteData graphics.library/FreeVPortCopLists graphics.library/GetAPen graphics.library/GetBitMapAttr graphics.library/GetBoardBytesPerRow graphics.library/GetBoardDataTagList graphics.library/GetBPen graphics.library/GetColorMap graphics.library/GetDisplayInfoData graphics.library/GetDrMd graphics.library/GetExtSpriteA graphics.library/GetGBuffers graphics.library/GetMonitorDataTagList graphics.library/GetOutlinePen graphics.library/GetRGB32 graphics.library/GetRGB4 graphics.library/GetRPAttrsA graphics.library/GetSprite graphics.library/GetVPModeID graphics.library/GfxAssociate graphics.library/GfxFree graphics.library/GfxLookUp graphics.library/GfxNew graphics.library/GraphicsControlTagList graphics.library/InitArea graphics.library/InitBitMap graphics.library/InitGels graphics.library/InitGMasks graphics.library/InitMasks graphics.library/InitRastPort graphics.library/InitTmpRas graphics.library/InitView graphics.library/InitVPort graphics.library/LoadRGB32 graphics.library/LoadRGB4 graphics.library/LoadView graphics.library/LockBitMapTagList graphics.library/LockBitMapToBoardTagList graphics.library/LockLayerRom graphics.library/MakeVPort graphics.library/ModeNotAvailable graphics.library/Move graphics.library/MoveSprite graphics.library/MrgCop graphics.library/NewRegion graphics.library/NextDisplayInfo graphics.library/ObtainBestPenA graphics.library/ObtainPen graphics.library/OpenFont graphics.library/OpenMonitor graphics.library/OrRectRegion graphics.library/OrRegionRegion graphics.library/OwnBlitter graphics.library/PolyDraw graphics.library/QBlit graphics.library/QBSBlit graphics.library/ReadPixel graphics.library/ReadPixelArray graphics.library/ReadPixelArray8 graphics.library/ReadPixelColor graphics.library/ReadPixelLine8 graphics.library/RectFill graphics.library/RectFillColor graphics.library/ReleasePen graphics.library/RemBob graphics.library/RemFont graphics.library/RemIBob graphics.library/RemVSprite graphics.library/ScalerDiv graphics.library/ScrollRaster graphics.library/ScrollRasterBF graphics.library/ScrollVPort graphics.library/SetABPenDrMd graphics.library/SetAPen graphics.library/SetBPen graphics.library/SetChipRev graphics.library/SetCollision graphics.library/SetDrMd graphics.library/SetFont graphics.library/SetMaxPen graphics.library/SetOPen graphics.library/SetOutlinePen graphics.library/SetRast graphics.library/SetRGB32 graphics.library/SetRGB32CM graphics.library/SetRGB4 graphics.library/SetRGB4CM graphics.library/SetRPAttrsA graphics.library/SetSoftStyle graphics.library/SetWriteMask graphics.library/SortGList graphics.library/StripFont graphics.library/SyncSBitMap graphics.library/Text graphics.library/TextExtent graphics.library/TextFit graphics.library/TextLength graphics.library/UnlockBitMap graphics.library/UnlockBitMapFromBoard graphics.library/UnlockLayerRom graphics.library/VBeamPos graphics.library/VideoControl graphics.library/WaitBlit graphics.library/WaitBOVP graphics.library/WaitTOF graphics.library/WriteChunkyPixels graphics.library/WritePixel graphics.library/WritePixelArray graphics.library/WritePixelArray8 graphics.library/WritePixelColor graphics.library/WritePixelLine8 graphics.library/XorRectRegion graphics.library/XorRegionRegion graphics.library/AddAnimOb graphics.library/AddAnimOb NAME AddAnimOb -- Add an AnimOb to the linked list of AnimObs. SYNOPSIS AddAnimOb(anOb, anKey, rp) VOID AddAnimOb(struct AnimOb *,struct AnimOb **, struct 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 RESULT BUGS SEE ALSO Animate() graphics/rastport.h graphics/gels.h graphics.library/AddBob graphics.library/AddBob NAME AddBob -- Adds a Bob to current gel list. SYNOPSIS AddBob(Bob, rp) VOID AddBob(struct Bob *, struct 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 RESULT BUGS SEE ALSO InitGels() AddVSprite() graphics/gels.h graphics/rastport.h graphics.library/AddFont graphics.library/AddFont NAME AddFont -- add a font to the system list SYNOPSIS AddFont(textFont) VOID AddFont(struct 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. RESULT NOTES This function will set the tf_Accessors to 0. BUGS SEE ALSO SetFont() RemFont() graphics/text.h graphics.library/AddVSprite graphics.library/AddVSprite NAME AddVSprite -- Add a VSprite to the current gel list. SYNOPSIS AddVSprite(vs, rp) VOID AddVSprite(struct VSprite *, struct 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 RESULT BUGS SEE ALSO InitGels() graphics/rastport.h graphics/gels.h graphics.library/AllocBitMap graphics.library/AllocBitMap NAME AllocBitMap -- Allocate a bitmap and attach bitplanes to it. (V39) SYNOPSIS struct BitMap *bm = AllocBitMap(uint32 sizex, uint32 sizey, uint32 depth, uint32 flags, struct BitMap *friendBitmap); FUNCTION Allocates and initializes a BitMap structure plus underlying storage in whatever format is required. INPUTS sizex - the width (in pixels) desired for the bitmap data. 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 - BMF_CLEAR to specify that the allocated raster should be filled with color 0. Planar YUV formats (YUV410P and YUV420P) are cleared by filling the Y plane with 0 and the U and V planes with 128. 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. If there is not enough contiguous RAM for an interleaved bitmap, graphics.library will fall back to a non-interleaved one. 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_HIJACKED BMF_RTGTAGS BMF_RTGCHECK BMF_FRIENDISTAG BMF_INVALID are used together (BMF_CHECKMASK) to indicate that the friendBitMap pointer is actually a struct TagList array. See the AllocBitMapTagList() autodoc for full descriptions of all the available tags. (V45) BMF_LOCKED locks the bitmap in video memory and it cannot be moved. This is for system use only. (V51) friendBitmap - pointer to another bitmap or NULL. If this pointer is passed, then the bitmap data will be allocated in the most efficient form for blitting to friendBitmap. If flags is set to BMF_CHECKMASK then this pointer is a struct TagItem array pointer. See the AllocBitMapTagList() autodoc for tag descriptions. RESULT bm - Pointer to newly allocated bitmap or NULL for failure. 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 like a graphics card then its Screen->RastPort->BitMap won't be in standard Amiga format. 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. SEE ALSO AllocBitMapTagList(), FreeBitMap() graphics.library/AllocBitMapTagList graphics.library/AllocBitMapTagList NAME AllocBitMapTagList -- Allocate a bitmap using a tag list (V53.7) SYNOPSIS struct BitMap *bm = AllocBitMapTagList(uint32 sizex, uint32 sizey, uint32 depth, CONST struct TagItem * tags); struct BitMap *bm = AllocBitMapTags(uint32 sizex, uint32 sizey, uint32 depth, ...); FUNCTION Allocates and initializes a BitMap structure plus underlying storage in whatever format is required. INPUTS sizex - the width (in pixels) desired for the bitmap data. 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. tags - Tag list with additional parameters; see below. TAGS BMATags_Friend (struct BitMap *) -- Specifies a friend bitmap. Defaults to no friend bitmap. BMATags_PixelFormat (uint32) -- Color format of the bitmap data. Choose one of the enum enPixelFormat values in . It is usually best to use a friend bitmap and let the system determine the optimal format to use. BMATags_Depth (uint32) -- Specifies the bitmap depth and overrides the depth parameter. Defaults to the depth parameter. BMATags_Clear (BOOL) -- Clear the bitmap by filling it will color zero. Equivalent to the BMF_CLEAR flag. Defaults to no clearing. Planar YUV formats (YUV410P and YUV420P) are cleared by filling the Y plane with 0 and the U and V planes with 128. BMATags_Displayable (BOOL) -- Specifies whether this bitmap will be displayed or not. Equivalent to the BMF_DISPLAYABLE flag. Defaults to FALSE. BMATags_NoMemory (BOOL) -- Just allocate the bitmap structure and do not allocate any storage. Defaults to FALSE. BMATags_NoSprite (BOOL) -- Do not allow generation of sprites. Default is FALSE. BMATags_ModeWidth (uint32) -- Width of the display mode (BMATags_DisplayID) in pixels. Default is the sizex parameter. BMATags_ModeHeight (uint32) -- Height of the display mode (BMATags_DisplayID) in pixels. Default is the sizey parameter. BMATags_Alignment (uint32) -- Specifies additional alignment restriction (power of two) for the bitmap rows. If this tag is set then bitplane rows are aligned to this boundary. Default to the native alignment restriction for the video memory in use. BMATags_ConstantBytesPerRow (BOOL) -- Set to TRUE along with the BMATags_Alignment tag to enforce alignment for displayable screens. Defaults to FALSE. BMATags_UserPrivate (BOOL) -- Set to TRUE if this is a user private bitmap which will never be in video memory. LockBitMapTagList() should not be used because this bitmap never moves in and out of video memory. Defaults to FALSE. BMATags_DisplayID (uint32) -- A valid display ID from the monitor database which will be used to extract the board, width, height and format for the bitmap. Defaults to using sizex, sizey and friend bitmap (if available). BMATags_BitmapInvisible (BOOL) -- If set to TRUE then the bitmap is not allocated on the graphics board directly. The bitmap may remain in an off-hardware location if the screen is invisible. This is intentially identical to the SA_Behind tag. Defaults to FALSE. BMATags_BitmapColors (struct ColorSpec *) -- Specifies an array of struct ColorSpec entries terminated by ColorIndex = -1. Specifies the initial screen palette colors. This is intentially identical to the SA_Colors tag. BMATags_BitmapColors32 (uint32 *) -- Specifies a set of initial palette colors. ti_Data is a pointer to a table to be passed to the LoadRGB32() function. Any color set here has precedence over the same register set by BMATags_BitmapColors. This is intentionally identical to the SA_Colors32 tag. RESULT bm - Pointer to newly allocated bitmap or NULL for failure. SEE ALSO AllocBitMap(), FreeBitMap(), graphics/gfx.h graphics.library/AllocDBufInfo graphics.library/AllocDBufInfo NAME AllocDBufInfo -- Allocate structure for multi-buffered animation (V39) SYNOPSIS AllocDBufInfo(vp) struct DBufInfo * AllocDBufInfo(struct ViewPort *) FUNCTION Allocates a structure which is used by the ChangeVPBitMap() routine. INPUTS vp = A pointer to a ViewPort structure. BUGS 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() graphics.library/AllocRaster graphics.library/AllocRaster NAME AllocRaster -- Allocate space for a bitplane. SYNOPSIS PLANEPTR planeptr = AllocRaster(uint16 width, uint16 height); FUNCTION This function calls the memory allocation routines to allocate memory space for a bitplane "width" bits wide and "height" bits high. INPUTS width - number of columns in bitplane height - number of rows in bitplane RESULT planeptr - pointer to first word in bitplane, or NULL if it was not possible to allocate the desired amount of memory. NOTES In order to assure proper alignment of display memory, the AllocBitMap() function should be used instead of AllocRaster when you wish to allocate display memory (rasters which are attached to a ViewPort or Screen). BUGS SEE ALSO FreeRaster() graphics/gfx.h graphics.library/AllocSpriteDataA graphics.library/AllocSpriteDataA NAME AllocSpriteDataA -- allocate sprite data and convert from a bitmap. (V39) AllocSpriteData -- varargs stub for AllocSpriteData(). (V39) SYNOPSIS SpritePtr | 0 = AllocSpriteDataA(bitmap, taglist) struct ExtSprite *AllocSpriteDataA( CONST struct BitMap *, CONST struct TagItem * ); extsprite = AllocSpriteData(bitmap, tag1, ...); 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() graphics/sprite.h graphics.library/AndRectRegion graphics.library/AndRectRegion NAME AndRectRegion -- Perform 2d AND operation of rectangle with region, leaving result in region. SYNOPSIS AndRectRegion(region, rectangle) VOID AndRectRegion( struct Region *, CONST struct 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 NOTES Unlike the other rect-region primitives, AndRectRegion() cannot fail. BUGS SEE ALSO AndRegionRegion() OrRectRegion() graphics/regions.h graphics.library/AndRegionRegion graphics.library/AndRegionRegion NAME AndRegionRegion -- Perform 2d AND operation of one region with second region, leaving result in second region. SYNOPSIS status = AndRegionRegion(region1, region2) BOOL AndregionRegion(CONST struct Region *, struct 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 SEE ALSO OrRegionRegion() AndRectRegion() graphics/regions.h graphics.library/Animate graphics.library/Animate NAME Animate -- Processes every AnimOb in the current animation list. SYNOPSIS Animate(anKey, rp) VOID Animate(struct AnimOb **, struct 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 RESULT BUGS SEE ALSO AddAnimOb() graphics/gels.h graphics/rastport.h graphics.library/AreaCircle graphics.library/AreaCircle NAME AreaCircle -- add a circle to areainfo list for areafill. SYNOPSIS error = AreaCircle( rp, cx, cy, radius) LONG AreaCircle(struct 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() AreaCircle() InitArea() AreaEnd() graphics/rastport.h graphics/gfxmacros.h graphics.library/AreaDraw graphics.library/AreaDraw NAME AreaDraw -- Add a point to a list of end points for areafill. SYNOPSIS error = AreaDraw( rp, x, y) LONG AreaDraw( struct RastPort *, WORD, WORD); FUNCTION Add point to the vector buffer. INPUTS rp - points to a RastPort structure. x,y - are coordinates of a point in the raster. RESULT error - zero for success, else -1 if no there was no space left in the vector list. BUGS SEE ALSO AreaMove() InitArea() AreaEnd() graphics/rastport.h graphics.library/AreaEllipse graphics.library/AreaEllipse NAME AreaEllipse -- add a ellipse to areainfo list for areafill. SYNOPSIS error = AreaEllipse( rp, cx, cy, a, b ) LONG AreaEllipse( struct RastPort *, WORD, WORD, WORD, WORD) 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) RESULT error - zero for success, or -1 if there is no space left in the vector list SEE ALSO AreaMove() AreaDraw() AreaCircle() InitArea() AreaEnd() graphics/rastport.h graphics.library/AreaEnd graphics.library/AreaEnd NAME AreaEnd -- Process table of vectors and ellipses and produce areafill. SYNOPSIS error = AreaEnd(rp) LONG AreaEnd( struct 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. RESULT error - zero for success, or -1 if an error occurred anywhere. INPUTS rp - pointer to a RastPort structure which specifies where the filled regions will be rendered to. BUGS SEE ALSO InitArea() AreaMove() AreaDraw() AreaEllipse() InitTmpRas() graphics/rastport.h graphics.library/AreaMove graphics.library/AreaMove NAME AreaMove -- Define a new starting point for a new shape in the vector list. SYNOPSIS error = AreaMove( rp, x, y) LONG AreaMove( struct RastPort *, WORD, WORD ); 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 RETURNS error - zero for success, or -1 if there is no space left in the vector list BUGS SEE ALSO InitArea() AreaDraw() AreaEllipse() AreaEnd() graphics/rastport.h graphics.library/AskFont graphics.library/AskFont NAME AskFont -- get the text attributes of the current font SYNOPSIS AskFont(rp, textAttr) VOID AskFont(struct RastPort *, struct 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 struct TTextAttr. RESULT The textAttr structure is filled with the RastPort's text attributes. BUGS SEE ALSO diskfont.library/ObtainTTextAttr(), graphics/text.h graphics.library/AskSoftStyle graphics.library/AskSoftStyle NAME AskSoftStyle -- Get the soft style bits of the current font. SYNOPSIS enable = AskSoftStyle(rp) ULONG AskSoftStyle(struct 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. BUGS SEE ALSO SetSoftStyle() graphics/text.h graphics.library/AttachPalExtra graphics.library/AttachPalExtra NAME AttachPalExtra -- Allocate and attach a palette sharing structure to a colormap. (V39) SYNOPSIS status=AttachPalExtra( cm, vp) LONG AttachPalExtra( Struct ColorMap *, struct 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). BUGS 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() graphics.library/AttemptLockLayerRom graphics.library/AttemptLockLayerRom NAME AttemptLockLayerRom -- Attempt to Lock Layer structure by ROM(gfx lib) code SYNOPSIS gotit = AttemptLockLayerRom( layer ) BOOL AttempLockLayerRom( struct 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 RESULT gotit - TRUE or FALSE depending on whether the Layer was successfully locked by the caller. SEE ALSO LockLayerRom() UnlockLayerRom() graphics.library/BestModeIDA graphics.library/BestModeIDA NAME BestModeIDA -- calculate the best ModeID with given parameters (V39) SYNOPSIS uint32 ID = BestModeIDA(CONST struct TagItem *TagItems); uint32 ID = BestModeID(Tag Tag1, ...); FUNCTION To determine the best ModeID to fit the parameters set in the TagList. INPUTS TagItems - A pointer to an array of TagItems. TAGS BIDTAG_DIPFMustHave (uint32) - Mask of DIPF_ flags (from DisplayInfo->PropertyFlags) that the returned ModeID must have. Default - NULL BIDTAG_DIPFMustNotHave (uint32) - Mask of DIPF_ flags that the returned ModeID must not have. Default - SPECIAL_FLAGS BIDTAG_ViewPort (struct ViewPort *) - ViewPort for which a best-fit ModeID is sought. Default - NULL BIDTAG_NominalWidth (uint16) BIDTAG_NominalHeight (uint16) - Together make the aspect ratio. These values override the vp->DWidth and vp->DHeight values in the given ViewPort. Default - SourceID NominalDimensionInfo if BIDTAG_SourceID is passed, or vp->DWidth and vp->DHeight if BIDTAG_ViewPort is passed, or 640 x 200. BIDTAG_DesiredWidth (uint16) BIDTAG_DesiredHeight (uint16) - Used to distinguish between two mode IDs with identical aspect ratios. Default - same values as NominalWidth and NominalHeight. BIDTAG_MinDepth (uint8) - Minimum depth the returned ModeID must support. Default is vp->RasInfo->BitMap->Depth if BIDTAG_ViewPort is passed else 1. BIDTAG_MaxDepth (uint8) - Maximum depth the ModeID must support. The maximum depth is 24. Default is 24. (V54) BIDTAG_MonitorID (uint32) - Returned ModeID must use this monitor. Default - will not restrict the search to any particular monitor. BIDTAG_SourceID (uint32) - Use this ModeID instead of a ViewPort. If specified, the DIPFMustHave mask is made up of the ((DisplayInfo->PropertyFlags of this ID & SPECIAL_FLAGS) | DIPFMustHave flags). Default - VPModeID(vp) if BIDTAG_ViewPort was passed, else the DIPFMustHave and DIPFMustNotHave masks are left unchanged. BIDTAG_RedBits (uint8) BIDTAG_BlueBits (uint8) BIDTAG_Greenits (uint8) - Minimum bits per gun the resultant ModeID must support. Default - 4 bits per gun. 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 and BIDTAG_DesiredHeight must all be non-0. The comparisons are made against the DimensionInfo->Nominal values (i.e. this will not return a best fit against overscan dimensions). The minimum and maximum depth values are not the same as the bits per pixel or bytes per pixel. See the GetBitMapAttr() autodoc for more information. EXAMPLE IFF display program with a HAM image, to be displayed in the same monitor type as the Workbench ViewPort. uint32 monitorid = IGraphics->GetVPModeID(WbVP) & MONITOR_ID_MASK; uint32 ID = IGraphics->BestModeID( BIDTAG_NominalWidth, IFFImage->Width, BIDTAG_NominalHeight, IFFImage->Height, BIDTAG_MinDepth, IFFImage->Depth, BIDTAG_DIPFMustHave, DIPF_IS_HAM, BIDTAG_MonitorID, monitorid, TAG_END); To make an interlace version of a ViewPort: uint32 ID = IGraphics->BestModeID( BIDTAG_ViewPort, ThisViewPort, BIDTAG_MustHave, DIFP_IS_LACE, TAG_END); SEE ALSO graphics.library/BitMapScale graphics.library/BitMapScale NAME BitMapScale -- Perform raster scaling on a bit map. (V36) SYNOPSIS void BitMapScale(struct BitScaleArgs *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. RESULT 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 ScalerDiv() graphics/scale.h graphics.library/BltBitMap graphics.library/BltBitMap NAME BltBitMap -- Move a rectangular region of bits in a BitMap. SYNOPSIS planecnt = BltBitMap(SrcBitMap, SrcX, SrcY, DstBitMap, DstX, DstY, SizeX, SizeY, Minterm, Mask [, TempA]) ULONG BltBitMap(CONST struct BitMap *, WORD, WORD, struct BitMap *, WORD, WORD, WORD, WORD, UBYTE, UBYTE, PLANEPTR); FUNCTION Perform non-destructive blits to move a rectangle from one area in a BitMap to another area, which can be on a different BitMap. This blit is assumed to be friendly: no error conditions (e.g. a rectangle outside the BitMap bounds) are tested or reported. INPUTS SrcBitMap, DstBitMap - the BitMap(s) containing the rectangles - 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 zero, 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. 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 Src. SizeX, SizeY - the size of the rectangle to be moved. Valid range is (X: 1..976; Y: 1..1023 such that final raster word's offset is 0..32767) Minterm - the logic function to apply to the rectangle when A is non-zero (i.e. within the rectangle). B is the source rectangle and C, D is the destination for the rectangle. - $0C0 is a vanilla copy - $030 inverts the source before the copy - $050 ignores the source and inverts the destination - see the hardware reference manual for other combinations 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. TempA - If the copy overlaps exactly to the left or right (i.e. the scan line addresses overlap), and TempA is non-zero, it points to enough chip accessible memory to hold a line of A source for the blit (ie CHIP RAM). BltBitMap will allocate (and free) the needed TempA if none is provided and one is needed. Blit overlap is determined from the relation of the first non-masked planes in the source and destination bit maps. RESULTS planecnt - the number of planes actually involved in the blit. NOTES o This function may use the blitter. SEE ALSO ClipBlit() graphics/gfx.h hardware/blit.h graphics.library/BltBitMapRastPort graphics.library/BltBitMapRastPort NAME BltBitMapRastPort -- Blit from source bitmap to destination rastport. SYNOPSIS error=BltBitMapRastPort (srcbm, srcx, srcy, destrp, destX, destY, sizeX, sizeY,minterm) BOOL BltBitMapRastPort(CONST struct BitMap *, WORD, WORD, struct 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 RESULT TRUE BUGS SEE ALSO BltMaskBitMapRastPort() graphics/gfx.h graphics/rastport.h graphics.library/BltBitMapTagList graphics.library/BltBitMapTagList NAME BltBitMapTagList -- Blit from any source to any destination (V51). SYNOPSIS int32 error = BltBitMapTagList(struct TagItem *taglist); int32 error = BltBitMapTags(Tag tag1, ...); FUNCTION Blits from a source bitmap/rastport or pixel buffer to another bitmap/rastport or pixel buffer using the given minterm, alpha value and mask. Both source and destination can be a layered rastport. INPUTS BLITA_SrcX, BLITA_SrcY (int16) - source origin of blit, defaults to 0. BLITA_DestX, BLITA_DestY (int16) - destination coordinates of blit, defaults to 0. BLITA_Width, BLITA_Height (int16) - size of blit, defaults to 0. BLITA_Source, BLITA_Dest (APTR) - source and destination objects, see below for more. Defaults to NULL. BLITA_SrcType, BLITA_DestType (int32) - specifies the type of the source (BLITA_Source) and destination (BLITA_Dest). The following types are supported: BLITT_BITMAP (default) - a simple bitmap (struct BitMap *). BLITT_RASTPORT - a rastport (struct RastPort *). BLITT_TEMPLATE - a monochrome template (PLANEPTR), see BltTemplate() for more information. Only supported by BLITA_SrcType. BLITT_ALPHATEMPLATE - an 8bit alpha template (APTR). BLITT_CHUNKY - an 8bit chunky buffer (APTR). BLITT_RGB24 - 24bit RGB buffer (APTR). BLITT_ARGB32 - 32bit ARGB buffer (APTR). BLITT_RGB16 - 16bit RGB buffer (APTR). Not available before rtg.library 53.33. BLITA_SrcBytesPerRow, BLITA_DestBytesPerRow (uint16) - bytes per row value of the source/destination data when source/dest is neither a bitmap nor a rastport. BLITA_Minterm (uint8) - minterm of the blit operation, defaults to 0xc0 (copy blit). See BltBitMap() for more. BLITA_Mask (uint8) - the write mask to apply to this operation. Defaults to 0xff unless BLITA_Dest is a rastport in which case the rp->Mask value of the destination rastport is used. See BltBitMap() for more. BLITA_MaskPlane (APTR) - please see BltMaskBitMapRastPort() for details. This tag cannot be used in combination with alpha blits. BLITA_AlphaMask (APTR) - the alpha mask to apply, defaults to NULL. Source bitmap and mask must have the same dimension. BLITA_UseSrcAlpha (BOOL) - use alpha data stored in the source object for transparent blits, default is FALSE. BLITA_UseSrcAlpha, BLITA_UseDstAlpha (see below) and BLITA_AlphaMask are mutually- exclusive. BLITA_UseDstAlpha (BOOL) - use alpha data stored in the destination object for transparent blits, default is FALSE. BLITA_UseSrcAlpha, BLITA_UseDstAlpha, BLITA_AlphaMask are mutually-exclusive. BLITA_Alpha (uint32) - alpha blend value applied to each pixel, 32bit left justified fraction. Multiply an 8bit alpha value by 0x01010101 to get the 32bit alpha value. A value of 0xfffffff (default) means non-opaque blit unless either BLIT_UseSrcAlpha/ BLITA_UseDstAlpha is TRUE or BLITA_AlphaMask is used. BLITA_Alpha can be used in combination with the two tags mentioned above. BLITA_CLUT (APTR) - color lookuptable (256 entries each 4bytes large, format 0xAARRGGBB) to use when blitting chunky bitmaps to directmapped bitmaps. Default is NULL (APTR), means palette of destination bitmap is used (if available). The alpha value is ignored unless BLITA_UseSrcAlpha is TRUE. RESULT -1 for success 0 for error (not enough data, invalid data) 1..n in case of an unknown tag, the position of the tag inside the taglist is returned. NOTES - Masked blits from smartrefreshed rastports won't work. - BLITA_Alpha is not supported by BLITT_(ALPHA)TEMPLATE. - BLITA_Minterm is currently ignored by alpha blits. - When blitting a template the destination must be a rastport. - This function does nothing before graphics.library v51.37 and rtg.library 41.4279. - GetBoardBytesPerRow() may be used to determine the underlying graphics hardware's required bytes per row for use with tags such as BLITA_AlphaMask. BUGS SEE ALSO BltMaskBitMapRastPort(), BltBitMap(), ClipBlit(), BltTemplate(), BltBitMapRastPort(), WritePixelArray(), ReadPixelArray(), ReadPixeLine8(), WritePixelLine8(), GetBoardBytesPerRow(), graphics/gfx.h, graphics/blitattr.h, graphics/minterm.h graphics.library/BltClear graphics.library/BltClear NAME BltClear - Clear a block of memory words to zero. SYNOPSIS BltClear( memBlock, bytecount, flags ) VOID BltClear( PLANEPTR, 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). RESULT The block of memory is initialized. BUGS SEE ALSO graphics.library/BltMaskBitMapRastPort graphics.library/BltMaskBitMapRastPort NAME BltMaskBitMapRastPort -- blit from source bitmap to destination rastport with masking of source image. SYNOPSIS BltMaskBitMapRastPort (srcbm, srcx, srcy, destrp, destX, destY, sizeX, sizeY, minterm, bltmask) VOID BltMaskBitMapRastPort (struct BitMap *, WORD, WORD, struct RastPort *, WORD, WORD, WORD, WORD, UBYTE, PLANEPTR); 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 the mask is non-zero. 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 - 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. RESULT BUGS SEE ALSO BltBitMapRastPort() graphics/gfx.h graphics/rastport.h graphics.library/BltPattern graphics.library/BltPattern NAME BltPattern -- Using standard drawing rules for areafill, blit through a mask. SYNOPSIS BltPattern(rp, mask, xl, yl, maxx, maxy, bytecnt) VOID BltPattern(struct RastPort *, CONST PLANEPTR, WORD, WORD, WORD, WORD, UWORD); 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 RESULT SEE ALSO AreaEnd() graphics.library/BltTemplate graphics.library/BltTemplate NAME BltTemplate -- Cookie cut a shape in a rectangle to the RastPort. SYNOPSIS BltTemplate(SrcTemplate, SrcX, SrcMod, rp, DstX, DstY, SizeX, SizeY) VOID BltTemplate(CONST PLANEPTR, WORD, WORD, struct 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 BltBitMap() graphics/rastport.h graphics.library/CalcIVG graphics.library/CalcIVG NAME CalcIVG -- Calculate the number of blank lines above a ViewPort (V39) SYNOPSIS uint16 count = CalcIVG(struct View *view, struct ViewPort* vp); 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 vp - pointer to the ViewPort you are interested in. RESULT 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 GfxNew() VideoControl() graphics/view.h graphics.library/CBump graphics.library/CBump NAME CBump -- increment user copper list pointer (bump to next position in list). SYNOPSIS CBump( c ) 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 SEE ALSO CINIT() CWAIT() CMOVE() CEND() graphics/copper.h graphics.library/CEND graphics.library/CEND NAME 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! BUGS SEE ALSO CINIT() CWAIT() CMOVE() graphics/copper.h graphics.library/ChangeExtSpriteA graphics.library/ChangeExtSpriteA NAME ChangeExtSpriteA -- Change the sprite image pointer. (V39) ChangeExtSprite -- varargs stub for ChangeExtSpriteA(). (V39) SYNOPSIS success = ChangeExtSpriteA( vp, oldsprite, newsprite, tags) LONG ChangeExtSpriteA(struct ViewPort *, struct ExtSprite *, struct ExtSprite *, CONST struct TagItem *); LONG ChangeExtSprite(vp, old_sp, new_sp, tag1, ....); 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. BUGS SEE ALSO FreeSprite() ChangeSprite() MoveSprite() AllocSpriteDataA() graphics/sprite.h graphics.library/ChangeSprite graphics.library/ChangeSprite NAME ChangeSprite -- Change the sprite image pointer. SYNOPSIS ChangeSprite( vp, s, newdata) VOID ChangeSprite(struct ViewPort *, struct SimpleSprite *, APTR ) 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. RESULTS BUGS SEE ALSO FreeSprite() ChangeSprite() MoveSprite() AddVSprite() graphics/sprite.h graphics.library/ChangeVPBitMap graphics.library/ChangeVPBitMap NAME ChangeVPBitMap -- change display memory address for multi-buffered animation (V39) SYNOPSIS VOID ChangeVPBitMap(struct ViewPort *vp, struct BitMap *bm, struct DBufInfo *db); 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. BUGS 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() graphics.library/CINIT graphics.library/CINIT NAME CINIT -- Initialize user copperlist to accept intermediate user copper instructions. SYNOPSIS cl = CINIT( ucl , n ) cl = UCopperListInit( ucl , n ) 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 CINIT (CINIT will NOT allocate a new UCopList if ucl==0 ). If (ucl != 0) it will 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. INPUTS ucl - pointer to UCopList structure 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 CINIT will not actually allocate a new UCopList if ucl==0. Instead you must allocate a block MEMF_PUBLIC|MEMF_CLEAR, the sizeof(struct UCopList) 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. SEE ALSO CINIT() CMOVE() CEND() graphics/copper.h graphics.library/ClearEOL graphics.library/ClearEOL NAME ClearEOL -- Clear from current position to end of line. SYNOPSIS ClearEOL(rp) VOID ClearEOL(struct 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 2, to the BgPen. INPUTS rp - pointer to RastPort structure RESULT NOTES o This function may use the blitter. SEE ALSO Text() ClearScreen() SetRast() graphics/text.h graphics/rastport.h graphics.library/ClearRectRegion graphics.library/ClearRectRegion NAME ClearRectRegion -- Perform 2d CLEAR operation of rectangle with region, leaving result in region. SYNOPSIS status = ClearRectRegion(region,rectangle) BOOL ClearRectRegion(struct Region *, CONST struct 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 BUGS SEE ALSO AndRectRegion() graphics/regions.h graphics.library/ClearRegion graphics.library/ClearRegion NAME ClearRegion -- Remove all rectangles from region. SYNOPSIS ClearRegion(region) VOID ClearRegion( struct Region * ); FUNCTION Clip away all rectangles in the region leaving nothing. INPUTS region - pointer to Region structure BUGS SEE ALSO NewRegion() graphics/regions.h graphics.library/ClearScreen graphics.library/ClearScreen NAME ClearScreen -- Clear from current position to end of RastPort. SYNOPSIS ClearScreen(rp) VOID ClearScreen(struct 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 2, to the BgPen. INPUTS rp - pointer to RastPort structure NOTES o This function may use the blitter. SEE ALSO ClearEOL() Text() SetRast() graphics/text.h graphics/rastport.h graphics.library/ClipBlit graphics.library/ClipBlit NAME ClipBlit -- Calls BltBitMap() after accounting for windows SYNOPSIS ClipBlit(Src, SrcX, SrcY, Dest, DestX, DestY, XSize, YSize, Minterm) VOID ClipBlit (struct RastPort *, WORD, WORD, struct 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, etcetera. 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 RESULT BUGS SEE ALSO BltBitMap() graphics.library/CloseFont graphics.library/CloseFont NAME CloseFont -- Release a pointer to a system font. SYNOPSIS CloseFont(font) VOID CloseFont(struct TextFont *); FUNCTION This function indicates that the font specified is no longer in use. It is used to close a font opened by OpenFont, so that fonts that are no longer in use do not consume system resources. INPUTS font - A font pointer as returned by OpenFont() or OpenDiskFont(). RESULT BUGS SEE ALSO OpenFont() diskfont.library/OpenDiskFont() graphics/text.h graphics.library/CloseMonitor graphics.library/CloseMonitor NAME CloseMonitor -- close a MonitorSpec (V36) SYNOPSIS error = CloseMonitor( monitor_spec ) 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. BUGS SEE ALSO OpenMonitor() graphics.library/CMOVE graphics.library/CMOVE NAME CMOVE -- append copper move instruction to user copper list. SYNOPSIS CMOVE( c , a , v ) CMove( c , da , v ) CBump( c ) VOID CMove( struct UCopList *, WORD, WORD ); FUNCTION Add instruction to move value v to hardware register a. INPUTS c - pointer to UCopList structure a - hardware register da - hardware register offset 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 SEE ALSO CINIT() CWAIT() CEND() graphics/copper.h graphics.library/CoerceMode graphics.library/CoerceMode NAME CoerceMode -- calculate ViewPort mode coercion (V39) SYNOPSIS uint32 ID = CoerceMode(struct ViewPort *RealViewPort, uint32 MonitorID, uint32 Flags); 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 uint32 newmode = CoerceMode(vp, VGA_MONITOR_ID, PRESERVE_COLORS); SEE ALSO graphics/coerce.h graphics/displayinfo.h graphics.library/CompositeTagList graphics.library/CompositeTagList NAME CompositeTagList - Compose one bitmap onto another (V53) SYNOPSIS uint32 CompositeTagList(uint32 operator, struct BitMap *Source, struct BitMap *Dest, struct TagItem *tags); uint32 CompositeTags(uint32 operator, struct BitMap *Source, struct BitMap *Dest, ...); FUNCTION This function implements Porter/Duff image compositing. If possible, the operation will be hardware accelerated. The function composes the bitmap pointed to by Source onto the bitmap pointed to by Dest, using the specified operator. Color values in the bitmaps are pre-multiplied with the alpha values (or left unmodified if no alpha is present) before composition. The most common operator is COMPOSITE_Src_Over_Dest, which, if the destination's alpha value is 1, performs a standard OpenGL-style linear blend between the Source and Destination bitmaps based on the source alpha values (i.e. a "transparent blit"). For the purpose of the operation, this is the order in which the modifiers are applied: - The source rectangle specifies a sub-portion of the source bitmap that becomes the source operand. Note that ONLY the source rectangle is used for this, i.e for all intent and purpose this is equivalent to specifying a bitmap that only contains the pixels in the source rectangle. - The destination operand is ALWAYS the complete destination bitmap. However, no pixel outside the destination rectangle is modified. Likewise, the OffsetX and OffsetY values specify coordinates relative to the top left pixel of the destination bitmap, NOT the destination rectangle. - The scale factors are applied after the source rectangle is "cut" from the source bitmap. This enlarges or shrinks the source operand to a new size, doubling or removing pixels as needed, and possibly filtering them. For all intent and purpose this is equivalent to providing a bitmap that contains a scaled (and possibly filtered) image of the original source rectangle. - After scaling, the resulting pixels are composed into the destination bitmap one by one using the specified operator. As mentioned previously, no pixel outside the destination bitmap's destination rectangle are modified; the result of the compose operation there is discarded (this process is commonly called "clipping", although the term "sciscoring" is more adequate). - Exactly the same method is used for any alpha mask specified. Please refer to the SDK documentation and example code for a more in-depth discussion of the function and Porter/Duff style image composition in general. INPUTS operator - the Porter/Duff image composition operator. Please refer to graphics/composite.h for a list of operators, and the SDK documentation for their meaning. Source - The source bitmap. The bitmap may or may not have an Alpha channel. If it hasn't got one, then an alpha of one is assumed. The tag items may influence the interpretation of the alpha channel as well. The bitmap must be BMF_DISPLAYABLE to be able to use hardware acceleration, and it must be a compatible format, otherwise software blending is used. Dest - The destination bitmap. The same restrictions apply as with the Source bitmap. tags - A tag list with additional parameters. Some of the tag items accept fix point real numbers. These are 32 bit integers with the upper 16 bit representing the decimal part of the number, and the lower 16 bits representing the fractional part. To convert from a float to a fixpoint number, simply multiply 0x00010000 by the floating point number and typecast the result to an int32. Currently, the following tag items are possible: COMPTAG_SrcX (uint32) The X coordinate of a subrectangle on the source bitmap. If a subrectangle is specified, only that part of the bitmap is used for the compositing operation. Default is 0. COMPTAG_SrcY (uint32) The Y coordinate of a subrectangle on the source bitmap. If a subrectangle is specified, only that part of the bitmap is used for the compositing operation. Default is 0. COMPTAG_SrcWidth (uint32) The width of a subrectangle on the source bitmap. If a subrectangle is specified, only that part of the bitmap is used for the compositing operation. Default is the width of the source bitmap. COMPTAG_SrcHeight (uint32) The height of a subrectangle on the source bitmap. If a subrectangle is specified, only that part of the bitmap is used for the compositing operation. Default is the height of the source bitmap. COMPTAG_DestX (uint32) The X coordinate of a subrectangle on the destination bitmap. This rectangle specifies the area of the bitmap that is affected by the operation. In no case are pixels outside of this area affected by the operation. Default is 0. COMPTAG_DestY (uint32) The Y coordinate of a subrectangle on the destination bitmap. This rectangle specifies the area of the bitmap that is affected by the operation. In no case are pixels outside of this area affected by the operation. Default is 0. COMPTAG_DestWidth (uint32) The width of a subrectangle on the destination bitmap. This rectangle specifies the area of the bitmap that is affected by the operation. In no case are pixels outside of this area affected by the operation. Default is the width of the destination bitmap. COMPTAG_DestHeight (uint32) The height of a subrectangle on the destination bitmap. This rectangle specifies the area of the bitmap that is affected by the operation. In no case are pixels outside of this area affected by the operation. Default is the height of the destination bitmap. COMPTAG_SrcAlpha (fixpoint) A constant alpha factor for the source bitmap. If the COMPFLAG_SrcAlphaOverride flag is given (see below) this value replaces any alpha channel or mask that may be present in the bitmap itself or specified via a tag item. If the COMPFLAG_SrcAlphaOverride flag is not given, then the alpha channel of the source bitmap is multiplied with this value. This tag can be used to implement the Porter/Duff fade and darken operators. The default value is 1.0. Setting any value outside the interval of zero to one inclusive yields undefined results. COMPTAG_DestAlpha (fixpoint) A constant alpha factor for the destination bitmap. If the COMPFLAG_DestAlphaOverride flag is given (see below) this value replaces any alpha channel or mask that may be present in the bitmap itself or specified via a tag item. If the COMPFLAG_DestAlphaOverride flag is not given, then the alpha channel of the source bitmap is multiplied with this value. This tag can be used to implement the Porter/Duff fade and darken operators. The default value is 1.0f. Setting any value outside the interval of zero to one inclusive yields undefined results. COMPTAG_ScaleX (fixpoint) A floating-point scale factor by which the source bitmap resp. the subrectangle of the source bitmap should be scaled horizontally before the operation is executed. A value of 1.0f means no scaling. Values greater than one enlarge the bitmap, while values between zero and one shrink it. Values less than or equal to zero are illegal and will result in the function to fail. See graphics/composite.h for some useful macros that allow fixpoint<->float conversions. Defaults to 1.0f (no scaling) COMPTAG_ScaleY (fixpoint) A floating-point scale factor by which the source bitmap resp. the subrectangle of the source bitmap should be scaled vertically before the operation is executed. A value of 1.0f means no scaling. Values greater than one enlarge the bitmap, while values between zero and one shrink it. Values less than or equal to zero are illegal and will result in the function to fail. See graphics/composite.h for some useful macros that allow fixpoint<->float conversions. Defaults to 1.0f (no scaling) COMPTAG_SrcAlphaMask (struct BitMap *) A pointer to an (alternative) alpha channel for the source bitmap. If specified, alpha information in the source bitmap is ignored. COMPTAG_DestAlphaMask (struct BitMap *) A pointer to an (alternative) alpha channel for the destination bitmap. If specified, alpha information in the destination is ignored. COMPTAG_SrcAlphaX (uint32) COMPTAG_SrcAlphaY (uint32) The X and Y coordinates of a subrectangle on the alpha channel bitmap for the source. The width and height of the rectangle are the same as the COMPTAG_SrcWidth and COMPTAG_SrcHeight. Defaults to zero. COMPTAG_DestAlphaX (uint32) COMPTAG_DestAlphaY (uint32) The X and Y coordinates of a subrectangle on the alpha channel bitmap for the destination. The width and height of the rectangle are the same as the COMPTAG_SrcWidth and COMPTAG_SrcHeight. Defaults to zero. COMPTAG_Flags (uint32) A bit mask specifying a number of flag bits that further modify the operation of this call. Currently, the following flags are defined: COMPFLAG_SrcAlphaOverride COMPFLAG_DestAlphaOverride If either is set, the source respectively destination alpha factor specified with COMPTAG_SrcAlpha resp. COMPTAG_DestAlpha overrides the alpha value in the bitmap or alpha mask, i.e. the alpha channel is assumed to be a constant value as specified. If the respective bit is not set, source resp. destination alpha channel values are multiplied with the value specified by the COMPTAG_SrcAlpha/COMPTAG_DestAlpha tag. COMPFLAG_SrcFilter If set, then bilinear filtering is applied to the source bitmap to smooth out any artifacts introduced by scaling. Filtering will have a slight but negligible performance impact on hardware acceleration (usually this will be so small it cannot be noticed), but might have a severe impact when using software. The software implementation may ignore this flag. COMPFLAG_HardwareOnly If this flag is set and the operation cannot be performed in hardware, instead of falling back to software the operation will fail entirely. COMPFLAG_IgnoreDestAlpha If this flag is set, the destination bitmap is assumed to be without alpha channel, i.e. Alpha is assumed to be one. On some hardware this greatly enhances the performance or reduces the overhead of the function (for example, it frees the R200 driver from allocating temporary texture storage). Use this flag whenever possible. Note the destination bitmap's alpha is always left unchanged when using this flag. COMPTAG_OffsetX (int32) COMPTAG_OffsetY (int32) Specifies the offset on the destination bitmap (NOT the destination rectangle) where the source operand should be applied. Negative coordinates are possible. By default, both tags are zero. COMPTAG_SrcYUVStandard Specifies the YUV to RGB conversion standard to use for YUV source bitmaps. The options are: COMPYUV_BT601 - SD video standard ITU-R BT.601 COMPYUV_BT709 - HD video standard ITU-R BT.709 NOTE: This is only relevant if the source bitmap has a YUV pixel format. COMPTAG_SrcYUVMatrix (float32 *) Provide a custom YUV to RGB conversion matrix. This is a 3x4 matrix in row-major order. The 4th column is the offset vector, while the other columns are multiplication coefficients. Please note that all YUV values are in the range [0..1], so your matrix will have to take this into account (some conversion formulae assume different ranges). COMPTAG_VertexArray (float32 *) Specifies a vertex array and enter vertex array mode. See VERTEX ARRAY MODE for a description of vertex array mode. COMPTAG_VertexFormat (uint32) Specify the vertex format for vertex array mode. See VERTEX ARRAY MODE for a description of vertex array mode. COMPTAG_NumTriangles (uint32) Specify the number of triangles to draw. See VERTEX ARRAY MODE for a description of vertex array mode. COMPTAG_IndexArray (uint16 *) Specify an array of indices to define triangles. See VERTEX ARRAY MODE for a description of vertex array mode. VERTEX ARRAY MODE Instead of using a rectangle, the Composite call can also use triangles defined by an array of vertices. When in vertex array mode, the tag items COMPTAG_SrcX, COMPTAG_SrcY, COMPTAG_SrcWidth, COMPTAG_SrcHeight, COMPTAG_ScaleX, COMPTAG_ScaleY, COMPTAG_OffsetX and COMPTAG_OffsetY are ignored. Instead of rendering a single quad, the compositing engine will render a set of (disjoint) triangles using the composition source as a "texture". A vertex array is a set of points on the 2D plane. Each vertex consists of at least two floating point values defining the x and y coordinates of the vertex on the destination operator, relative to the top left corner of the bitmap (not the destination rectangle!). Furthermore, each vertex can have three or six more floating point value attributes, both of which are sets of texture coordinates. The first set of extra coordinates, if present, address the source operator bitmap itself. The second set, if present, are used to address the alpha mask. Each set consists of three floating point values. The first two values, named s and t respectively, define the X and Y coordinates on the source operator bitmap that this vertex maps to. The third, called w, is a homogenous space coordinate of the texture. Usually, this will be 1.0f, but it is possible to use different homogenous coordinates per vertex to achieve a perspective corrected 3D texture map The tag COMPTAG_VertexFormat is used to describe the format of each individual vertex. If ommited, the default value is for a vertex to only have x and y coordinates. Otherwise, the tag's value must be a compination of the two values COMPVF_STW0_Present and COMPVF_STW1_Present. These two values are bit masks and can be combined in any form. Each bit adds three floating point values to the vertex' required size. When both are specified, each vertex has a size of 8 floating point values. Vertex arrays must be specified compact, i.e. to get from one vertex in the array to the next, the compositing engine adds the size of the vertex, in bytes. Typically, your application would define a vertex "structure" like this: typedef struct { float x,y; float s,t,w; } myVertex_t; #define MYVERTEX_Format COMPVF_STW0_Present A vertex array could then be defined as myVertex_t vertices[20]; The tag COMPTAG_VertexArray is used to enter triangle mode by providing a packed vertex array as described above. The size of the vertex array is undefined. A vertex array does not, however, define triangles. It only defines vertices. To start drawing triangles, these vertices must be grouped into triplets that define a triangle. There are two possible ways to do that, either implicitly, or explicitly. The normal mode of operation is to assume implicit grouping of vertices into triangles. Each three consequtive vertices, starting at vertex index zero, is assumed to be one triangle, i.e. the first triangle consists of indices 0, 1 and 2, the second one consists of indices 3, 4 and 5, and so on. The number of triangles to draw is specified via COMPTAG_NumTriangles, and the vertex array must have at least three times this number of vertices. The second mode of operation is explicit index mode. In index mode, the triangles are not defined by the order of vertices in the index array. Instead, the caller can pass an explicit array of indices for each triangle. As in the implicit mode, the tag COMPTAG_NumTriangles determines how many triangles are drawn, but the size of the vertex array is unaffected by this value, since each vertex may be used zero or more times through specifying its index. To pass in the indices of the desired triangles, the tag COMPTAG_IndexArray can be used. Indices are passed in as an array of 16 bit unsigned integers. If we denote the index array as I and the vertex array as V, then triangles are defined as V[I[0]], V[I[1]], V[I[2]] V[I[3]], V[I[4]], V[I[5]] and so on. The number of vertices in the array must be at least as many as the highest index used in the index array. No consistency check is done whatsoever for speed reasons, so an application has to take care the input to this function is valid. Failure to do so will have an undefined result, with "undefined" ranging from "nothing at all" to "total system lockup". IMPORTANT: As of AmigaOS 4.1 Update 3, triangle mode only works with hardware accelerated rendering. There is currently no software fallback. RESULT The function returns a status code. The following values are possible: COMPERR_Success No error. The operation performed successfully. COMPERR_Incompatible The input bitmaps were incompatible for the call. This usually happens when a bitmap color format is not supported. COMPERR_Value An input value was illegal. This error is raised if e.g. the specified operator is not known, or negative coordinates are given, etc. COMPERR_SoftwareFallback The COMPFLAG_HardwareOnly flag was set but the operation was incompatible with the current hardware. COMPERR_OutOfMemory Temporary storage was required to finish the operation but could not be allocated. COMPERR_Generic An unknown error has occurred. SEE ALSO SDK examples and documentation. graphics.library/CopySBitMap graphics.library/CopySBitMap NAME CopySBitMap -- Syncronize Layer window with contents of Super BitMap SYNOPSIS CopySBitMap( layer ) VOID CopySBitMap(struct Layer *); FUNCTION This is the inverse of SyncSBitMap. Copy all bits from SuperBitMap to Layer bounds. 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. BUGS SEE ALSO LockLayerRom() SyncSBitMap() graphics.library/CWAIT graphics.library/CWAIT NAME CWAIT -- Append copper wait instruction to user copper list. SYNOPSIS CWAIT( c , v , h ) CWait( c , v , h ) CBump( c ) VOID CWait( struct UCopList *, WORD, WORD) 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 User waiting for horizontal values of greater than 222 decimal is illegal. SEE ALSO CINIT() CMOVE() CEND() graphics/copper.h graphics.library/DisownBlitter graphics.library/DisownBlitter NAME DisownBlitter -- return blitter to free state. SYNOPSIS DisownBlitter() VOID DisownBlitter( VOID ); FUNCTION Free blitter up for use by other blitter users. INPUTS RETURNS SEE ALSO OwnBlitter() graphics.library/DisposeRegion graphics.library/DisposeRegion NAME DisposeRegion -- Return all space for this region to free memory pool. SYNOPSIS DisposeRegion(region) VOID DisposeRegion( struct Region * ); FUNCTION Free all RegionRectangles for this Region then free the Region itself. INPUTS region - pointer to Region structure BUGS SEE ALSO NewRegion() graphics/regions.h graphics.library/DoCollision graphics.library/DoCollision NAME DoCollision -- Test every gel in gel list for collisions. SYNOPSIS DoCollision(rp) VOID DoCollision(struct 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 RESULT BUGS SEE ALSO InitGels() SortGList() graphics/gels.h graphics/gels.h graphics.library/Draw graphics.library/Draw NAME Draw -- Draw a line between the current pen position and the new x,y position. SYNOPSIS Draw( rp, x, y) VOID Draw( struct RastPort *, WORD, WORD); 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. BUGS SEE ALSO Move() graphics/rastport.h graphics.library/DrawEllipse graphics.library/DrawEllipse NAME DrawEllipse -- Draw an ellipse centered at cx,cy with vertical and horizontal radii of a,b respectively. SYNOPSIS DrawEllipse( rp, cx, cy, a, b ) VOID DrawEllipse( struct RastPort *, WORD, WORD, WORD, WORD); 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) BUGS NOTES this routine does not clip the ellipse to a non-layered rastport. SEE ALSO DrawCircle macro graphics/gfxmacros.h graphics/rastport.h graphics.library/DrawGList graphics.library/DrawGList NAME DrawGList -- Process the gel list, queueing VSprites, drawing Bobs. SYNOPSIS DrawGList(rp, vp) VOID DrawGList(struct RastPort *, struct 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 RESULT BUGS MUSTDRAW isn't implemented yet. SEE ALSO InitGels() graphics/gels.h graphics/rastport.h graphics/view.h graphics.library/EraseRect graphics.library/EraseRect NAME EraseRect -- Fill a defined rectangular area using the current BackFill hook. (V36) SYNOPSIS EraseRect( rp, xmin, ymin, xmax, ymax) VOID EraseRect(struct RastPort *, WORD, WORD, WORD, WORD); 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. BUGS NOTES The following relation MUST be true: (xmax >= xmin) and (ymax >= ymin) SEE ALSO graphics/rastport.h graphics/clip.h graphics.library/ExtendFont graphics.library/ExtendFont NAME ExtendFont -- ensure tf_Extension has been built for a font (V36) SYNOPSIS success = ExtendFont(font, fontTags) ULONG ExtendFont(struct TextFont *, CONST struct TagItem *); success = ExtendFontTags(font, Tag1, ...) (V39) ULONG ExtendFontTags(struct 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. RESULT success - 1 if the TextFont was properly extended, else 0. NOTES The varargs stub was missing from amiga.lib until V39. To avoid problems when old software copies the tf_Style flags from a TextFont to the ta_Style flags of a TextAttr (not a TTextAttr) structure, ExtendFont() clears the FSF_TAGGED bit. This does not mean that the TextFont is not tagged, only a NULL tfe_Tags pointer can indicate that its untagged. SEE ALSO graphics/text.h graphics.library/FindColor graphics.library/FindColor NAME FindColor -- Find the closest matching color in a colormap. (V39) SYNOPSIS uint16 color = FindColor(struct ColorMap *cm, uint32 R, uint32 G, uint32 B, int32 maxpen); 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). RESULT 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. BUGS 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. SEE ALSO ObtainBestPenA() GetColorMap() ObtainPen() ReleasePen() graphics.library/FindDisplayInfo graphics.library/FindDisplayInfo NAME FindDisplayInfo -- search for a record identified by a specific key (V36) SYNOPSIS handle = FindDisplayInfo(ID) 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 RESULT handle - handle to a displayinfo Record with that key or NULL if no match. BUGS SEE ALSO graphics/displayinfo.h graphics.library/Flood graphics.library/Flood NAME Flood -- Flood rastport like areafill. SYNOPSIS BOOL error = Flood(struct RastPort *rp, uint32 mode, int16 x, int16 y); 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() on classic Amiga bitmaps the destination RastPort must have a valid TmpRas raster whose size is as large as that of the RastPort. When using Flood() with retargetable bitmaps the TmpRas (if present) is ignored and internal buffers are used instead. To test whether a bitmap is retargetable see GetBitMapAttr()'s BMA_ISRTG attribute. SEE ALSO AreaEnd(), InitTmpRas(), GetBitMapAttr(), graphics/rastport.h graphics.library/FontExtent graphics.library/FontExtent NAME FontExtent -- get the font attributes of the current font (V36) SYNOPSIS FontExtent(font, fontExtent) VOID FontExtent(CONST struct TextFont *, struct 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. RESULT 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 TextExtent() graphics/text.h graphics.library/FreeBitMap graphics.library/FreeBitMap NAME FreeBitMap -- free a bitmap created by AllocBitMap (V39) SYNOPSIS VOID FreeBitMap(struct BitMap *bm); FUNCTION Frees bitmap and all associated underlying data. INPUTS bm - A pointer to a BitMap structure. Passing a NULL-pointer (meaning "do nothing") is OK. NOTES When using standard Amiga bitmaps, be careful to ensure that any rendering done to the bitmap has completed (by calling WaitBlit()) before you call this function. SEE ALSO AllocBitMap(), AllocBitMapTagList() graphics.library/FreeColorMap graphics.library/FreeColorMap NAME FreeColorMap -- Free the ColorMap structure and return memory to free memory pool. SYNOPSIS void FreeColorMap(struct ColorMap *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). RESULT The space is made available for others to use. BUGS SEE ALSO SetRGB4() GetColorMap() graphics/view.h graphics.library/FreeCopList graphics.library/FreeCopList NAME FreeCopList -- deallocate intermediate copper list SYNOPSIS FreeCopList(coplist) VOID FreeCopList( struct CopList *); FUNCTION Deallocate all memory associated with this copper list. INPUTS coplist - pointer to structure CopList RESULTS memory returned to memory manager BUGS SEE ALSO graphics/copper.h graphics.library/FreeCprList graphics.library/FreeCprList NAME FreeCprList -- deallocate hardware copper list SYNOPSIS FreeCprList(cprlist) VOID FreeCprList(struct cprlist *); FUNCTION return cprlist to free memory pool INPUTS cprlist - pointer to cprlist structure RESULTS memory returned and made available to other tasks BUGS SEE ALSO graphics/copper.h graphics.library/FreeDBufInfo graphics.library/FreeDBufInfo NAME FreeDBufInfo -- free information for multi-buffered animation (V39) SYNOPSIS FreeDBufInfo(db) VOID FreeDBufInfo(struct DBufInfo *) FUNCTION Frees a structure obtained from AllocDBufInfo INPUTS db = A pointer to a DBufInfo. BUGS NOTES FreeDBufInfo(NULL) is a no-op. SEE ALSO AllocDBufInfo() ChangeVPBitMap() graphics.library/FreeGBuffers graphics.library/FreeGBuffers NAME FreeGBuffers -- Deallocate memory obtained by GetGBufers. SYNOPSIS FreeGBuffers(anOb, rp, db) VOID FreeGBuffers(struct AnimOb *, struct 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) RESULT BUGS SEE ALSO GetGBuffers() graphics/gels.h graphics/rastport.h graphics.library/FreeRaster graphics.library/FreeRaster NAME FreeRaster -- Release an allocated area to the system free memory pool. SYNOPSIS FreeRaster( p, width, height ) VOID FreeRaster( PLANEPTR, UWORD, UWORD); 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. BUGS NOTES Width and height should be the same values with which you called AllocRaster in the first place. SEE ALSO AllocRaster() graphics/gfx.h graphics.library/FreeSprite graphics.library/FreeSprite NAME FreeSprite -- Return sprite for use by others and virtual sprite machine. SYNOPSIS FreeSprite( pick ) 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. BUGS SEE ALSO GetSprite() ChangeSprite() MoveSprite() graphics/sprite.h graphics.library/FreeSpriteData graphics.library/FreeSpriteData NAME FreeSpriteData -- free sprite data allocated by AllocSpriteData() (V39) SYNOPSIS FreeSpriteData(extsp) VOID FreeSpriteData(struct ExtSprite *); FUNCTION INPUTS extsp - The extended sprite structure to be freed. Passing NULL is a NO-OP. SEE ALSO FreeSpriteData() FreeSprite() ChangeSprite() MoveSprite() GetExtSprite() AllocBitMap() graphics/sprite.h graphics.library/FreeVPortCopLists graphics.library/FreeVPortCopLists NAME FreeVPortCopLists -- deallocate all intermediate copper lists and their headers from a viewport SYNOPSIS FreeVPortCopLists(vp) VOID FreeVPortCopLists(struct ViewPort *); FUNCTION Search display, color, sprite, and user copper lists and call FreeMem() to deallocate them from memory INPUTS vp - pointer to ViewPort structure RESULTS The memory allocated to the various copper lists will be returned to the system's free memory pool, and the following fields in the viewport structure will be set to NULL: DspIns, Sprins, ClrIns, UCopIns BUGS none known SEE ALSO graphics/view.h graphics.library/GetAPen graphics.library/GetAPen NAME GetAPen -- Get the A Pen value for a RastPort (V39). SYNOPSIS pen = GetAPen ( rp ) ULONG GetAPen(struct 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. RESULT pen - the A Pen value of the RastPort. BUGS NOTES SEE ALSO SetAPen() graphics/gfx.h graphics.library/GetBitMapAttr graphics.library/GetBitMapAttr NAME GetBitMapAttr -- Returns information about a bitmap (V39) SYNOPSIS uint32 value = GetBitMapAttr(CONST struct BitMap *bm, uint32 attrnum); FUNCTION Determines information about a bitmap. This function must be used instead of reading the bitmap structure fields directly. This will provide future compatibility. Some attributes such as the base address of the bitmap data is only available when the bitmap is locked. See the LockBitMapTagList() autodoc for dynamic attributes. INPUTS bm - A pointer to a BitMap structure. attrnum - A number indicating which attribute of the bitmap is returned: BMA_HEIGHT returns the height in pixels. BMA_WIDTH returns the width in pixels. Note this value may not be the same as the original value passed in via AllocBitMapTagList() due to hardware alignment restrictions. BMA_DEPTH returns the depth. This is the number of bits which are required to store the information for one pixel in the bitmap. The bitmap depth is the absolute number of bits required and is not be the same as the actual number of bits per pixel used to store the bitmap in memory. See BMA_BITSPERPIXEL for bits per pixel. Note this value may not be the same as the original value passed in via AllocBitMapTagList() due to hardware alignment restrictions. BMA_FLAGS returns a bit field describing attributes which the bitmap may have. Currently defined flags are: BMF_DISPLAYABLE, BMF_INTERLEAVED and BMF_STANDARD. The BMF_STANDARD flag will be set if the bitmap is a standard Amiga bitmap in Chip RAM. It is possible to allocate bitmaps in Fast RAM in which case this flag will not be set. For RTG bitmaps, this field will always be zero. BMA_ISRTG returns TRUE is the bitmap is retargetable or FALSE if not. Retargetable bitmaps can be moved into and out of graphics board memory. (V54) BMA_BYTESPERPIXEL returns the number of bytes per pixel used to store the bitmap data. Returns zero if this is not an RTG bitmap. (V54) BMA_BITSPERPIXEL returns the number of bits per pixel used to store the bitmap data. This is not the same the same as the depth of the bitmap. Returns zero if this is not an RTG bitmap. (V54) For example, an PIXF_A8B8G8R8 bitmap has a depth of 24 bits but stores 32 bits per pixel due to the extra 8 bits for the alpha channel. BMA_PIXELFORMAT returns the pixel format of the bitmap which is one of the enPixelFormat values. Returns PIXF_NONE if this is not an RTG bitmap. (V54) BMA_ACTUALWIDTH returns the unaltered original bitmap width passed in via AllocVecTagList(). This width is never altered or aligned by the system. Returns zero if this is not an RTG bitmap. (V54) RESULT value - A uint32 value. The interpretation of the return value depends on which of the chosen attrnum above. 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. Always use BMA_ISRTG to tell the difference between an RTG bitmap and a non-RTG bitmap. Not only is the code more explicit, it is also the fastest and most reliable method. SEE ALSO AllocBitMap(), AllocBitMapTagList(), LockBitMapTagList() graphics.library/GetBoardBytesPerRow graphics.library/GetBoardBytesPerRow NAME GetBoardBytesPerRow -- Get board bytes per row (V54) SYNOPSIS uint32 bpr = GetBoardBytesPerRow(uint32 boardNum, PIX_FMT pixelFormat, uint32 width); FUNCTION This function gets the bytes per row required for the provided pixel format and width. The underlying graphics hardware often has strict alignment requirements. INPUTS boardNum - Ordinal number of the board to query starting from 0. pixelFormat - Pixel format being used width - Pixel width OUTPUTS bpr - Bytes per row required by the underlying hardware or 0 on error. SEE ALSO BltBitMapTagList() graphics.library/GetBoardDataTagList graphics.library/GetBoardDataTagList NAME GetBoardDataTagList -- Returns information about a board. (V54) SYNOPSIS int32 result = GetBoardDataTagList(uint32 boardNum, struct TagItem *tags); int32 result = GetBoardDataTags(uint32 boardNum, Tag tag1, ...); FUNCTION Query function to get information about an active graphics board. If a parameter is not available then the data storage location will be left unchanged. INPUTS boardNum - Ordinal number of the board to query starting from 0. tags - A pointer to a TagItem array; see below. TAGS GBD_BoardName (CONST_STRPTR *) -- Pointer to the board name string. GBD_TotalMemory (uint64 *) -- Pointer to the total number of bytes available for bitmaps. This memory is also CPU accessible. GBD_FreeMemory (uint64 *) -- Pointer to the total number of free bytes. This function does not lock to gather this information so it could change before you get the result; user only for tools that display free memory and the like. GBD_LargestFreeMemory (uint64 *) -- Pointer to the size of the largest chuck of free memory in bytes. GBD_InternalMemorySize (uint64 *) -- Pointer to the total amount of memory that is available to the GPU including any VRAM that is not CPU accessible in bytes. GBD_PCIVendorID (uint16 *) -- Pointer to the PCI vendor ID. GBD_PCIProductID (uint16 *) -- Pointer to the PCI product ID. GBD_BoardDriver (CONST_STRPTR *) -- Pointer to the board driver name string. GBD_ChipDriver (CONST_STRPTR *) -- Pointer to the chip driver name string. RESULT value - Number of successfully processed tags or -1 for an invalid board number. SEE ALSO GetMonitorDataTagList() graphics.library/GetBPen graphics.library/GetBPen NAME GetBPen -- Get the B Pen value for a RastPort (V39). SYNOPSIS pen = GetBPen ( rp ) ULONG GetBPen(struct 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. RESULT pen - the B Pen value of the RastPort. BUGS NOTES SEE ALSO SetBPen() graphics/gfx.h graphics.library/GetColorMap graphics.library/GetColorMap NAME GetColorMap -- allocate and initialize Colormap SYNOPSIS struct ColorMap *cm = GetColorMap(uint16 entries); FUNCTION Allocates, initializes and returns a pointer to a ColorMap data structure, later enabling calls to SetRGB4/SetRGB32 and LoadRGB4/LoadRGB32 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()/GetRGB32() to query it or SetRGB4CM/SetRGB32CM to set it directly. INPUTS entries - number of entries for this colormap RESULT 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. BUGS SEE ALSO SetRGB4() FreeColorMap() graphics.library/GetDisplayInfoData graphics.library/GetDisplayInfoData NAME GetDisplayInfoData -- Query DisplayInfo Record parameters (V36) SYNOPSIS uint32 result = GetDisplayInfoData(CONST DisplayInfoHandle handle, APTR buf, uint32 size, Tag tagID, uint32 displayID); 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 (may be NULL) buf - pointer to destination buffer size - buffer size in bytes tagID - data chunk type displayID - displayinfo identifier, optionally used if handle is NULL RESULT result - if positive, number of bytes actually transferred if zero, no information for ID was available SEE ALSO FindDisplayInfo(), NextDisplayInfo() graphics/displayinfo.h graphics.library/GetDrMd graphics.library/GetDrMd NAME GetDrMd -- Get the draw mode value for a RastPort (V39). SYNOPSIS mode = GetDrMd ( rp ) ULONG GetDrMd(struct 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. RESULT mode - the draw mode of the RastPort. BUGS NOTES SEE ALSO SetDrMd() graphics/gfx.h graphics.library/GetExtSpriteA graphics.library/GetExtSpriteA NAME GetExtSpriteA -- Attempt to get a sprite for the extended sprite manager. (V39) GetExtSprite -- varargs stub for GetExtSpriteA. (V39) SYNOPSIS Sprite_Number = GetExtSpriteA( sprite, tags ) LONG GetExtSpriteA( struct ExtSprite *, CONST struct TagItem * ); spritenum = GetExtSprite(sprite, tag1, ...); 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. NOTES 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() graphics/sprite.h graphics.library/GetGBuffers graphics.library/GetGBuffers NAME GetGBuffers -- Attempt to allocate ALL buffers of an entire AnimOb. SYNOPSIS status = GetGBuffers(anOb, rp, db) BOOL GetGBuffers(struct AnimOb *, struct 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) RESULT 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 FreeGBuffers() graphics/gels.h graphics.library/GetMonitorDataTagList graphics.library/GetMonitorDataTagList NAME GetMonitorDataTagList -- Returns information about a monitor. (V54) SYNOPSIS int32 result = GetMonitorDataTagList(uint32 boardNum, uint32 monitorNum, struct TagItem *tags); int32 result = GetMonitorDataTags(uint32 boardNum, uint32 monitorNum, Tag tag1, ...); FUNCTION Query function to get information about a monitor connected to an active graphics board. This information is obtained via the DDC protocol and may not be available for every monitor. If a parameter is not available then the data storage location will be left unchanged. INPUTS boardNum - Ordinal number of the board to query starting from 0. monitorNum - Ordinal number of the monitor to query (Currently only 1 monitor is supported; set to 0). tags - A pointer to a TagItem array; see below. TAGS GMD_VendorID (CONST_STRPTR *) -- Pointer to vendor ID string. The vendor ID is assigned by Microsoft and is always three characters long. GMD_Product (CONST_STRPTR *) -- Pointer to a product string. GMD_ProductID (uint16 *) -- Pointer to uint16 to store the product ID number. GMD_HSyncMin (uint32 *) -- Pointer to uint32 to store the horizontal synchronization minimum (Hz). GMD_HSyncMax (uint32 *) -- Pointer to uint32 to store the horizontal synchronization maximum (Hz). GMD_VSyncMin (uint32 *) -- Pointer to uint32 to store the vertical synchronization minimum (Hz). GMD_VSyncMax (uint32 *) -- Pointer to uint32 to store the vertical synchronization maximum (Hz). GMD_DotClockMin (uint32 *) -- Pointer to uint32 to store the dot clock minimum (Hz). GMD_DotClockMax (uint32 *) -- Pointer to uint32 to store the dot clock maximum (Hz). GMD_DisplayWidth (uint32 *) -- Pointer to uint32 to store the display width (cm). GMD_DisplayHeight (uint32 *) -- Pointer to uint32 to store the display height (cm). GMD_InputType (uint32 *) -- Pointer to uint32 to store the input type. Returns one of enum enMonitorInputType as defined in . GMD_EDIDVersion (uint32 *) -- Pointer to uint32 to store the EDID version number. GMD_EDIDRevision (uint32 *) -- Pointer to uint32 to store the EDID revision number. GMD_BasicAudio (BOOL *) -- Pointer to BOOL to store whether the monitor supports basic audio or not. RESULT value - Number of successfully processed tags or -1 for an invalid board or monitor number. SEE ALSO GetBoardDataTagList() graphics.library/GetOutlinePen graphics.library/GetOutlinePen NAME GetOutlinePen -- Get the Outline-Pen value for a RastPort (V39). SYNOPSIS pen = GetOutlinePen ( rp ) ULONG GetOutlinePen(struct 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. RESULT pen - the Outline-Pen value of the RastPort. BUGS NOTES SEE ALSO SetOutlinePen() graphics/gfx.h graphics.library/GetRGB32 graphics.library/GetRGB32 NAME GetRGB32 -- Get a series of color registers for this Viewport. (V39) SYNOPSIS GetRGB32( cm, firstcolor, ncolors, table ) VOID GetRGB32( CONST struct ColorMap *, UWORD, UWORD, 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. RESULT The ULONG data pointed to by 'table' will be filled with the 32 bit fractional RGB values from the colormap. BUGS Prior to V46 this function did ignore the LowColorBits on non-AGA machines. NOTES 'Table' should point to at least ncolors*3 longwords. SEE ALSO LoadRGB4() GetColorMap() LoadRGB32() SetRGB32CM() graphics/view.h graphics.library/GetRGB4 graphics.library/GetRGB4 NAME GetRGB4 -- Inquire value of entry in ColorMap. SYNOPSIS value = GetRGB4( colormap, entry ) LONG GetRGB4(struct ColorMap *, UWORD); FUNCTION Read and format a value from the ColorMap. INPUTS colormap - pointer to ColorMap structure entry - index into colormap RESULT 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. BUGS SEE ALSO SetRGB4() LoadRGB4() GetColorMap() FreeColorMap() graphics/view.h graphics.library/GetRPAttrsA graphics.library/GetRPAttrsA NAME GetRPAttrsA -- examine rastport settings via a tag list GetRPAttrs -- varargs stub for GetRPAttrsA SYNOPSIS GetRPAttrsA(rp, tags) uint32 GetRPAttrsA(struct RastPort *, CONST struct 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 should be stored. All current tags store the return data as LONGs (32 bits). currently available tags are: RPTAG_Font Font for Text() 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. Tags introduced in V51: RPTAG_APenColor Primary rendering color (0xaarrggbb) RPTAG_BPenColor Secondary rendering color (0xaarrggbb) RPTAG_OPenColor Area outline color (0xaarrggbb) RPTAG_RemapColorFonts Make use of ColorTextFont->ColorFontColors to render color fonts (boolean). Tags introduced in V51: RPTAG_XPos Get X Position in Rastport. RPTAG_YPos Get Y Position in Rastport. 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. RESULT Returned the number of handled Tags. BUGS Before 54.126 it always returned Zero, now it returns the number of handled tags. SEE ALSO GetAPen() GetBPen() GetDrMd() GetOutLinePen() GetWriteMask() SetRPAttrsA() graphics/rpattr.h graphics.library/GetSprite graphics.library/GetSprite NAME GetSprite -- Attempt to get a sprite for the simple sprite manager. SYNOPSIS Sprite_Number = GetSprite( sprite, pick ) 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. BUGS SEE ALSO FreeSprite() ChangeSprite() MoveSprite() GetSprite() graphics/sprite.h graphics.library/GetVPModeID graphics.library/GetVPModeID NAME GetVPModeID -- get the 32 bit DisplayID from a ViewPort. (V36) SYNOPSIS uint32 modeID = GetVPModeID(CONST struct ViewPort *vp); FUNCTION returns the normal display modeID, if one is currently associated with this ViewPort. INPUTS vp -- pointer to a ViewPort structure. RESULT 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/modeid.h). BUGS SEE ALSO graphics/displayinfo.h, ModeNotAvailable() graphics.library/GfxAssociate graphics.library/GfxAssociate NAME GfxAssociate -- associate a graphics extended node with a given pointer (V36) SYNOPSIS GfxAssociate(pointer, node); VOID GfxAssociate(CONST APTR, struct 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 RESULT an association is created between the pointer and the node such that given the pointer the node can be retrieved via GfxLookUp(). BUGS SEE ALSO graphics/gfxnodes.h GfxNew() GfxFree() GfxLookUp() graphics.library/GfxFree graphics.library/GfxFree NAME GfxFree -- free a graphics extended data structure (V36) SYNOPSIS GfxFree( node ); VOID GfxFree(struct 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(). RESULT 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 graphics/gfxnodes.h GfxNew() GfxAssociate() GfxLookUp() graphics.library/GfxLookUp graphics.library/GfxLookUp NAME GfxLookUp -- find a graphics extended node associated with a given pointer (V36) SYNOPSIS result = GfxLookUp( pointer ); APTR GfxLookUp( CONST APTR ); 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 ). RESULT result = a pointer to the ExtendedNode that has previously been associated with the pointer. BUGS SEE ALSO graphics/gfxnodes.h GfxNew() GfxFree() GfxAssociate() graphics.library/GfxNew graphics.library/GfxNew NAME GfxNew -- allocate a graphics extended data structure (V36) SYNOPSIS struct ExtendedNode *result = GfxNew(uint32 node_type); 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.) RESULT result - a pointer to the allocated graphics node or NULL if the allocation failed. BUGS SEE ALSO graphics/gfxnodes.h GfxFree() GfxAssociate() GfxLookUp() graphics.library/GraphicsControlTagList graphics.library/GraphicsControlTagList NAME GraphicsControlTagList -- Set or obtain global graphics prefs values. (V54) SYNOPSIS uint32 result = GraphicsControlTagList(const struct TagItem *tags); uint32 result = GraphicsControlTags(Tag tag1, ...); FUNCTION This function provides a single method for reading or setting various features available in the V54+ graphics.library. This is the primary interface for graphics preferences tools, which use this function to implement the users prefered default settings. It is therefore recommended that applications use this function only to read what the user has chosen and not to flippantly override them. If you must change any values, read the previous setting and restore it after you have finished. You should never permanently change the users prefered settings without expressly having permission to do so. INPUTS tags - Tag list with additional parameters; see below. TAGS GCTRL_SetForceSWComposite (BOOL) -- Sets whether software compositing should always be used or not. Useful for testing when there is doubt hardware compositing is functioning correctly. Does nothing on platforms that don't support hardware compositing. Defaults to FALSE. GCTRL_GetForceSWComposite (BOOL *) -- Gets whether software compositing is forced or not. GCTRL_SetUseDMA (BOOL) -- Sets whether DMA acceleration should be used for graphics operations or not. Fails on platforms that do not support DMA accelerated graphics operations. Defaults to TRUE. GCTRL_GetUseDMA (BOOL *) -- Gets whether DMA acceleration is enabled or not. GCTRL_SetUseAltiVec (BOOL) -- Sets whether AltiVec acceleration should be used for graphics operations or not. Fails on platforms which do not support AltiVec accelerated graphics operations. Defaults to TRUE. GCTRL_GetUseAltiVec (BOOL *) -- Gets whether AltiVec acceleration is enabled or not. GCTRL_SetDisableAmigaBlitter (BOOL) -- Sets whether the Amiga blitter should be used on classic platforms or not. If the Amiga blitter is disabled then all blitter operations are replaced with CPU routines. Fails on non-classic Amiga platforms. Defaults to FALSE on classic Amiga platforms and TRUE on all other platforms. GCTRL_GetDisableAmigaBlitter (BOOL *) -- Gets whether the Amiga blitter has been disabled or not. GCTRL_SetPlanesToFast (BOOL) -- Used to enable the use of fast memory for all planar bitmaps that are allocated dynamically and that do not request BMF_STANDARD or BMF_DISPLAYABLE. This can speed up graphics operations and cause less chip RAM to be used. Fails on non-classic Amiga platforms. Defaults to FALSE on classic Amiga platforms and TRUE on all other platforms. GCTRL_Get31KHzScanRate (BOOL *) -- Gets whether the Amiga video scan rate is set to 31 KHz or not. GCTRL_Set31KHzScanRate (BOOL) -- Sets the Amiga video scan rate to 31 KHz on classic Amiga platforms. If set to 31 KHz the Amiga chip set will be programmed to a display timing like with the Amiga MULTISYNC monitor. This enables the use of high quality audio sample rates but might be harmful for a monitor attached to the Amiga video signal connector that is not compatible with a line frequency of 31 KHz. Fails on non-classic Amiga platforms. Amiga video scan rate defaults to 15 KHz. RESULT result - Returns the number of tags successfully processed or zero on error. SEE ALSO graphics/control.h graphics.library/InitArea graphics.library/InitArea NAME InitArea -- Initialize vector collection matrix SYNOPSIS InitArea( areainfo, buffer, maxvectors ) VOID InitArea(struct AreaInfo *, APTR, WORD); 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 RESULT Pointers are set up to begin storage of vectors done by AreaMove, AreaDraw, and AreaEllipse. BUGS SEE ALSO AreaEnd() AreaMove() AreaDraw() AreaEllipse() graphics/rastport.h graphics.library/InitBitMap graphics.library/InitBitMap NAME InitBitMap -- Initialize bit map structure with input values. SYNOPSIS InitBitMap( bm, depth, width, height ) VOID InitBitMap( struct 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 BUGS SEE ALSO graphics/gfx.h graphics.library/InitGels graphics.library/InitGels NAME InitGels -- initialize a gel list; must be called before using gels. SYNOPSIS InitGels(head, tail, GInfo) VOID InitGels(struct VSprite *, struct VSprite *, struct 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 gel list head tail - pointer to the VSprite structure to be used as gel list tail GInfo - pointer to the GelsInfo structure to be initialized RESULT BUGS SEE ALSO graphics/gels.h graphics/rastport.h graphics.library/InitGMasks graphics.library/InitGMasks NAME InitGMasks -- Initialize all of the masks of an AnimOb. SYNOPSIS InitGMasks(anOb) VOID InitGMasks(struct AnimOb *); FUNCTION For every sequence of every component call InitMasks. INPUTS anOb = pointer to the AnimOb BUGS SEE ALSO InitMasks() graphics/gels.h graphics.library/InitMasks graphics.library/InitMasks NAME InitMasks -- Initialize the BorderLine and CollMask masks of a VSprite. SYNOPSIS InitMasks(vs) VOID InitMasks(struct 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 RESULT BUGS SEE ALSO InitGels() graphics/gels.h graphics.library/InitRastPort graphics.library/InitRastPort NAME InitRastPort -- Initialize raster port structure SYNOPSIS InitRastPort( rp ) VOID InitRastPort(struct RastPort *rp); FUNCTION Initialize a RastPort structure to standard values. INPUTS rp - pointer to a RastPort structure. RESULT 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. BUGS SEE ALSO graphics/rastport.h graphics.library/InitTmpRas graphics.library/InitTmpRas NAME InitTmpRas -- Initialize area of local memory for usage by areafill, floodfill, text. SYNOPSIS struct TmpRas *InitTmpRas(struct TmpRas *tmpras, PLANPTR buffer, int32 size); 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 RESULT Pointer to the same struct TmpRas passed in. BUGS Would be nice if RastPorts could share one TmpRas. SEE ALSO AreaEnd() Flood() Text() graphics/rastport.h graphics.library/InitView graphics.library/InitView NAME InitView - Initialize View structure. SYNOPSIS InitView( view ) VOID InitView( struct View * ); FUNCTION Initialize View structure to default values. INPUTS view - pointer to a View structure RESULT 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. BUGS SEE ALSO MakeVPort graphics/view.h graphics.library/InitVPort graphics.library/InitVPort NAME InitVPort - Initialize ViewPort structure. SYNOPSIS InitVPort( vp ) VOID InitViewPort( struct ViewPort * ); FUNCTION Initialize ViewPort structure to default values. INPUTS vp - pointer to a ViewPort structure RESULT ViewPort structure set to all 0's. (1.0,1.1) New field added SpritePriorities, initialized to 0x24 (1.2) BUGS SEE ALSO MakeVPort() graphics/view.h graphics.library/LoadRGB32 graphics.library/LoadRGB32 NAME LoadRGB32 -- Set a series of color registers for this Viewport. (V39) SYNOPSIS VOID LoadRGB32(struct ViewPort *vp, CONST uint32 *table); INPUTS vp - viewport table - a pointer to a series of records which describe which colors to modify. RESULT The selected color registers are changed to match your specs. BUGS 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: uint32 table[] = {1 << 16 + 0, 0xffffffff, 0, 0, 0} loads color register 0 with 100% red. uint32 table[] = {256 << 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() graphics/view.h graphics.library/LoadRGB4 graphics.library/LoadRGB4 NAME LoadRGB4 -- Load RGB color values from table. SYNOPSIS VOID LoadRGB4(struct ViewPort *vp, CONST uint16 *colors, uint16 count); 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 UWORDS: background -- 0x0RGB color1 -- 0x0RGB color2 -- 0x0RGB etc. uint16 per value. The colors are interpreted as 15 = maximum intensity. 0 = minimum intensity. count - number of uint16's 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. On classic Amigas, updates the hardware copperlist to reflect the new colors. Updates the intermediate copperlist with the new colors. BUGS NOTES 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() graphics/view.h graphics.library/LoadView graphics.library/LoadView NAME LoadView -- Use a (possibly freshly created) coprocessor instruction list to create the current display. SYNOPSIS LoadView( View ) VOID LoadView( struct 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. RESULT 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. BUGS SEE ALSO InitVPort() MakeVPort() MrgCop() intuition/RethinkDisplay() graphics/view.h graphics.library/LockBitMapTagList graphics.library/LockBitMapTagList NAME LockBitMapTagList -- Lock BitMap against relocation. (V54) SYNOPSIS APTR lock = LockBitMapTagList(struct BitMap *bitMap, struct TagItem *tags); APTR lock = LockBitMapTags(struct BitMap *bitMap, Tag tag1, ...); FUNCTION This function prevents the graphics system from moving the BitMap to another location. Use this function only to protect direct accesses to the BitMap memory. Call UnlockBitMap() as soon as you are done. Never hold the lock for longer than about one second as all screen switching is disabled while you hold this lock. During holding this lock, your Task or Process will get a higher priority to try and avoid deadlocks. When this function is called on a user private bitmap the information above does not apply. Instead, this function is used to obtain the rendering information required to directly access the user private bitmap. The base address and bytes per row attributes may be cached and reused because a user private bitmap never moves in memory. See the BMATags_UserPrivate tag in the AllocBitMapTagList() autodoc for more information. INPUTS bitMap - Pointer to a BitMap to lock. tags - A pointer to a TagItem array; see below. TAGS LBM_BaseAddress (APTR *) - Pointer to the bitmap base address. LBM_BytesPerRow (uint32 *) - Pointer to the bytes per row for one bitmap line. LBM_PixelFormat (uint32 *) - Pointer to uint32 to store the pixel format type. Returns one of the enPixelFormat values defined in . LBM_PlanarYUVInfo (struct PlanarYUVInfo *) - Pointer to a struct PlanarYUVInfo used to store planar YUV bitmap information. Planar YUV formats include YUV410P and YUV420P. Non-planar YUV formats return all zero values. LBM_IsOnBoard (BOOL *) - Pointer to a BOOL which will indicate whether the BitMap is on a graphics board in VRAM or not. RESULT lock - An abstract handle to the lock which must never be interpreted in any way. NULL if the BitMap is not lockable (e.g. in MEMF_CHIP). NOTE Every call to this function must be matched with a call to UnlockBitMap() or your system will be blocked indefinately. All information obtained by locking a bitmap is only valid until UnlockBitMap() is called. Using other functions of graphics.library while holding the lock is possible but should be avoided as these functions lock the associated bitmaps internally. SEE ALSO UnlockBitMap(), AllocBitMapTagList() graphics.library/LockBitMapToBoardTagList graphics.library/LockBitMapToBoardTagList NAME LockBitMapToBoardTagList -- Locks a BitMap to a specific board (V54) SYNOPSIS APTR lock = LockBitMapToBoardTagList(struct BitMap *bm, uint32 boardNum, struct TagItem *tags); APTR lock = LockBitMapToBoardTags(struct BitMap *bm, uint32 boardNum, Tag tag1, ...); FUNCTION This function is similar to LockBitMap() except that it will lock a bitmap to a specific board. If the bitmap is currently not on the specified board, then this will attempt to copy it across. This function is intended only for 3D drivers which need to temporarily lock a buffer in graphics memory. As such, it does NOT wait for blitter and does NOT lock the graphics card so that the CPU can access the bitmap. Call UnlockBitMapFromBoard() as soon as you are done. INPUTS bm - RTG BitMap to lock boardNum - The number of the board to lock the bitmap to tags - A pointer to a TagItem array; see below. TAGS LBM_BaseAddress (APTR *) - Pointer to the bitmap base address. LBM_BytesPerRow (uint32 *) - Pointer to the bytes per row for one bitmap line. LBM_PixelFormat (uint32 *) - Pointer to uint32 to store the pixel format type. Returns one of the enPixelFormat values defined in . RESULT lock - An abstract handle to the lock which must never be interpreted in any way. NULL if the BitMap is not lockable (e.g. could not move the bitmap to the specific board). SEE ALSO UnlockBitMapFromBoard() graphics.library/LockLayerRom graphics.library/LockLayerRom NAME LockLayerRom -- Lock Layer structure by ROM(gfx lib) code. SYNOPSIS LockLayerRom( layer ) VOID LockLayerRom( struct 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. NOTE Since V50, this is a C function, which destroys registers However, registers are preserved when called from 68k. SEE ALSO UnlockLayerRom() layers.library/LockLayer() graphics/clip.h graphics.library/MakeVPort graphics.library/MakeVPort NAME MakeVPort -- generate display copper list for a viewport. SYNOPSIS uint32 error = MakeVPort(struct View *view, struct ViewPort *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 uint32 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() graphics/view.h intuition.library/MakeScreen() intuition.library/RemakeDisplay() intuition.library/RethinkDisplay() graphics.library/ModeNotAvailable graphics.library/ModeNotAvailable NAME ModeNotAvailable -- check if a DisplayID is not available. (V36) SYNOPSIS uint32 error = ModeNotAvailable(uint32 modeID); 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 display mode ID. RESULT 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 Return values from this function are a proper superset of the DisplayInfo.NotAvailable field (defined in graphics/displayinfo.h). ModeNotAvailable() will return INVALID_ID when given a non-existant mode ID. BUGS SEE ALSO graphics/displayinfo.h, GetVPModeID() graphics.library/Move graphics.library/Move NAME Move -- Move graphics pen position. SYNOPSIS Move( rp, x, y) VOID Move( struct RastPort *, WORD, WORD ); 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 RESULTS BUGS SEE ALSO Draw() graphics/rastport.h graphics.library/MoveSprite graphics.library/MoveSprite NAME MoveSprite -- Move sprite to a point relative to top of viewport. SYNOPSIS MoveSprite(vp, sprite, x, y) VOID MoveSprite(struct 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() graphics/sprite.h graphics.library/MrgCop graphics.library/MrgCop NAME MrgCop -- Merge together coprocessor instructions. SYNOPSIS uint32 error = MrgCop(struct View *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. RESULT 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 uint32 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. BUGS SEE ALSO InitVPort() MakeVPort() LoadView() graphics/view.h intuition.library/RethinkDisplay() graphics.library/NewRegion graphics.library/NewRegion NAME NewRegion -- Get an empty region. SYNOPSIS region = NewRegion() struct Region *NewRegion(); FUNCTION Create a Region structure, initialize it to empty, and return a pointer it. RESULTS region - pointer to initialized region. If it could not allocate required memory region = NULL. INPUTS none BUGS SEE ALSO graphics/regions.h graphics.library/NextDisplayInfo graphics.library/NextDisplayInfo NAME NextDisplayInfo -- iterate current displayinfo identifiers (V36) SYNOPSIS uint32 next_ID = NextDisplayInfo(uint32 last_ID); 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. RESULT next_ID - subsequent displayinfo identifier or INVALID_ID if no more records. BUGS SEE ALSO FindDisplayInfo(), GetDisplayInfoData() graphics/displayinfo.h graphics.library/ObtainBestPenA graphics.library/ObtainBestPenA NAME 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) LONG ObtainBestPenA( struct ColorMap *, ULONG, ULONG, ULONG, CONST struct TagItem *); color = ObtainBestPen(cm, r, g, b, tag1, ...); 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 ViewPort contains no sharable colors. Defaults to FALSE. 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 viewport closest to the specified color. If there is no color within your tolerance, then a new one will be allocated, if available. If none is available, then the closest one found will be returned. RESULT The correct pen value, or -1 if no sharable palette entries are available. BUGS NOTES If this call succceeds, then you must call ReleasePen() when you are done with the color. The error metric used for ObtainBestPen() is based on the magnitude squared between the two RGB values, scaled by the percentage of free entries. SEE ALSO GetColorMap() ObtainPen() ReleasePen() graphics.library/ObtainPen graphics.library/ObtainPen NAME ObtainPen -- Obtain a free palette entry for use by your program. (V39) SYNOPSIS n = ObtainPen( cm, n, r, g, b, flags) LONG ObtainPen(struct ColorMap *, LONG, 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 - PENF_EXCLUSIVE - tells the system that you want exclusive (non-shared) use of this pen value. Default is shared access. PENF_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. BUGS 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() graphics.library/OpenFont graphics.library/OpenFont NAME OpenFont -- Get a pointer to a system font. SYNOPSIS font = OpenFont(textAttr) struct TextFont *OpenFont(CONST struct TextAttr *); 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. RESULT 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. NOTES Prior to V46 this function used case sensitive font names. It is not necessary to call ExtendFont() for the returned font, OpenFont() only returns successfully extended fonts. 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() diskfont.library/OpenDiskFont() graphics/text.h intuition/intuition.h graphics.library/OpenMonitor graphics.library/OpenMonitor NAME OpenMonitor -- open a named MonitorSpec (V36) SYNOPSIS mspc = OpenMonitor( monitor_name , display_id) struct MonitorSpec *OpenMonitor( CONST_STRPTR, 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. BUGS SEE ALSO CloseMonitor() graphics/monitor.h graphics.library/OrRectRegion graphics.library/OrRectRegion NAME OrRectRegion -- Perform 2d OR operation of rectangle with region, leaving result in region. SYNOPSIS status = OrRectRegion(region, rectangle) BOOL OrRectRegion( struct Region *, CONST struct 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 BUGS SEE ALSO AndRectRegion() OrRegionRegion() graphics/regions.h graphics.library/OrRegionRegion graphics.library/OrRegionRegion NAME OrRegionRegion -- Perform 2d OR operation of one region with second region, leaving result in second region SYNOPSIS status = OrRegionRegion(region1, region2) BOOL OrRegionRegion( CONST struct Region *, struct 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 SEE ALSO OrRectRegion() XorRegionRegion() graphics/regions.h graphics.library/OwnBlitter graphics.library/OwnBlitter NAME 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 RETURNS NONE SEE ALSO DisownBlitter() WaitBlit() graphics.library/PolyDraw graphics.library/PolyDraw NAME PolyDraw -- Draw lines from table of (x,y) values. SYNOPSIS PolyDraw( rp, count , array ) VOID PolyDraw( struct RastPort *, WORD, CONST WORD * ); FUNCTION starting with the first pair in the array, draw connected lines to it and every successive pair. INPUTS rp - pointer to RastPort structure count - number of (x,y) pairs in the array array - pointer to first (x,y) pair BUGS SEE ALSO Draw() Move() graphics/rastport.h graphics.library/QBlit graphics.library/QBlit NAME QBlit -- Queue up a request for blitter usage SYNOPSIS QBlit( bp ) 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 RESULT 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() hardware/blit.h graphics.library/QBSBlit graphics.library/QBSBlit NAME QBSBlit -- Synchronize the blitter request with the video beam. SYNOPSIS QBSBlit( bsp ) 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 in the blitnode. INPUTS bsp - pointer to a blit structure. See description in the Graphics Support section of the manual for more info. RESULT 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() is no longer queued separately from nodes added by QBlit(). This fixes the ordering dependencies listed under BUGS in prior autodoc notes. BUGS SEE ALSO QBlit() hardware/blit.h graphics.library/ReadPixel graphics.library/ReadPixel NAME ReadPixel -- Read the pen number value of the pixel at a specified x,y location within a certain RastPort. SYNOPSIS int32 penno = ReadPixel(struct RastPort *rp, int16 x, int16 y); 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 RESULT 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 WritePixel(), ReadPixelColor() graphics.library/ReadPixelArray graphics.library/ReadPixelArray NAME ReadPixelArray -- Read the color values of a rectangular area. (V54) SYNOPSIS void ReadPixelArray(struct RastPort *src, uint32 srcX, uint32 srcY, uint8 *dst, uint32 dstX, uint32 dstY, uint32 dstBytesPerRow, PIX_FMT dstPixelFormat, uint32 sizeX, uint32 sizeY); FUNCTION Reads the color values of all pixels in a rectangular area of the RastPort to a specified memory area. INPUTS src - pointer to a RastPort structure (srcX, srcY) - starting point in the RastPort dst - destination array to write the pixel data into (dstX, dstY) - starting point in destination array dstBytesPerRow - destination bytes per row dstPixelFormat - destination pixel format (sizeX, sizeY) - size of the rectangular area SEE ALSO WritePixelArray(), ReadPixelArray8() graphics.library/ReadPixelArray8 graphics.library/ReadPixelArray8 NAME ReadPixelArray8 -- Read the pen number value of a rectangular array of pixels starting at a specified x,y location and continuing through to another x,y location within a certain RastPort. (V36) SYNOPSIS int32 count = ReadPixelArray8(struct RastPort *rp, uint16 xstart, uint16 ystart, uint16 xstop, uint16 ystop, uint8 *array, struct RastPort *temprp); FUNCTION For each pixel in a rectangular region, 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 (xstart,ystart) - starting point in the RastPort (xstop,ystop) - stopping point in the RastPort array - Pointer to an array of UBYTEs from which to fetch the pixel data. Allocate at least ((((width + 15) >> 4) << 4) * (ystop - ystart + 1)) bytes. temprp - Temporary rastport (copy of rp with Layer set == NULL, temporary memory allocated for temprp->BitMap with Rows set == 1, temprp->BitMap->BytesPerRow == (((width+15)>>4)<<1) and temporary memory allocated for temprp->BitMap->Planes[]) RESULT For each pixel in the array: Pen - (0..255) number at that position is returned count - the number of pixels read. NOTE xstop must be >= xstart ystop must be >= ystart SEE ALSO ReadPixel(), ReadPixelLine8() graphics.library/ReadPixelColor graphics.library/ReadPixelColor NAME ReadPixelColor -- Read the color value of the pixel at a specified x,y location within a certain RastPort. (V54) SYNOPSIS uint32 color = ReadPixelColor(struct RastPort *rp, uint32 x, uint32 y); FUNCTION Reads the color of the selected pixel in the specified RastPort. INPUTS rp - a pointer to the RastPort structure (x,y) - point within the RastPort at which the selected pixel is located. RESULT color - ARGB value of the pixel in the RastPort at position (x,y) SEE ALSO WritePixelColor(), ReadPixel() graphics.library/ReadPixelLine8 graphics.library/ReadPixelLine8 NAME ReadPixelLine8 -- Read the pen number value of a horizontal line of pixels starting at a specified x,y location and continuing right for count pixels. (V36) SYNOPSIS int32 count = ReadPixelLine8(struct RastPort *rp, uint16 xstart, uint16 ystart, uint16 width, uint8 *array, struct RastPort *temprp); FUNCTION For each pixel in a rectangular region, 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. width - Count of horizontal pixels to read. array - Pointer to an array of UBYTEs from which to fetch the pixel data. Allocate at least (((width + 15) >> 4) << 4) bytes. temprp - temporary rastport (copy of rp with Layer set == NULL, temporary memory allocated for temprp->BitMap with Rows set == 1, temprp->BitMap->BytesPerRow == (((width + 15) >> 4) << 1), and temporary memory allocated for temprp->BitMap->Planes[]) RESULT For each pixel in the array: Pen - (0..255) number at that position is returned count - the number of pixels read. NOTE width must be non negative SEE ALSO ReadPixel() graphics.library/RectFill graphics.library/RectFill NAME RectFill -- Fill a rectangular region in a RastPort. SYNOPSIS void RectFill(struct RastPort *rp, int16 xmin, int16 ymin, int16 xmax, int16 ymax); FUNCTION Fills the rectangular region specified by the paramters 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 AreaEnd(), RectFillColor(), graphics/rastport.h graphics.library/RectFillColor graphics.library/RectFillColor NAME RectFillColor -- Fill a rectangular region in a RastPort with an ARGB color. (V54) SYNOPSIS void RectFillColor(struct RastPort *rp, uint32 xmin, uint32 ymin, uint32 xmax, uint32 ymax, uint32 color); FUNCTION This function is similar to RectFill() except that it uses the ARGB value supplied as the color to fill with. INPUTS rp - pointer to a RastPort structure xmin - minimum x coordinate ymin - minimum y coordinate xmax - maximum x coordinate ymax - maximum y coordinate color - ARGB value used for the fill operation NOTE The following relation must be true: (xmax >= xmin) and (ymax >= ymin) SEE ALSO RectFill() graphics.library/ReleasePen graphics.library/ReleasePen NAME ReleasePen -- Release an allocated palette entry to the free pool. (V39) SYNOPSIS ReleasePen( cm, n ) VOID ReleasePen( Struct ColorMap *, LONG); 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. BUGS NOTES This function works for both shared and exclusive palette entries. SEE ALSO GetColorMap() ObtainPen() ObtainBestPenA() graphics.library/RemBob graphics.library/RemBob NAME 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 RESULT BUGS SEE ALSO RemIBob() DrawGList() graphics/gels.h graphics/gfxmacros.h graphics.library/RemFont graphics.library/RemFont NAME RemFont -- Remove a font from the system list. SYNOPSIS RemFont(textFont) VOID RemFont(struct 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. RESULT BUGS SEE ALSO SetFont() AddFont() graphics/text.h graphics.library/RemIBob graphics.library/RemIBob NAME RemIBob -- Immediately remove a Bob from the gel list and the RastPort. SYNOPSIS RemIBob(bob, rp, vp) VOID RemIBob(struct Bob *, struct RastPort *, struct 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 RESULT BUGS SEE ALSO InitGels() RemVSprite() graphics/gels.h graphics.library/RemVSprite graphics.library/RemVSprite NAME RemVSprite -- Remove a VSprite from the current gel list. SYNOPSIS RemVSprite(vs) VOID RemVSprite(struct VSprite *); FUNCTION Unlinks the VSprite from the current gel list. INPUTS vs = pointer to the VSprite structure to be removed from the gel list RESULT BUGS SEE ALSO InitGels() RemIBob() graphics/gels.h graphics.library/ScalerDiv graphics.library/ScalerDiv NAME ScalerDiv -- Get the scaling result that BitMapScale would. (V36) SYNOPSIS result = ScalerDiv(factor, numerator, denominator) 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 RESULT this returns factor*numerator/denominator graphics.library/ScrollRaster graphics.library/ScrollRaster NAME 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) VOID ScrollRaster (struct 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(Layers) routine sequence. INPUTS rp - pointer to a RastPort structure dx, dy - integers that may be positive, zero, or negative xmin, ymin - upper left of bounding rectangle xmax, ymax - lower right of bounding rectangle EXAMPLE // shift raster up by one row ScrollRaster(rp, 0, 1, minx, miny, maxx, maxy); // shift raster down and to the right by 1 pixel ScrollRaster(rp, -1, -1, minx, miny, maxx, maxy); 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() RectFill() intuition.library/ScrollWindowRaster() graphics/rastport.h graphics.library/ScrollRasterBF graphics.library/ScrollRasterBF NAME 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) VOID ScrollRasterBF (struct 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(Layers) routine sequence. INPUTS rp - pointer to a RastPort structure dx, dy - 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. BUGS SEE ALSO ScrollRaster() EraseRect() intuition.library/ScrollWindowRaster() graphics/rastport.h graphics.library/ScrollVPort graphics.library/ScrollVPort NAME ScrollVPort -- Reinterpret RasInfo information in ViewPort to reflect the current Offset values. SYNOPSIS ScrollVPort( vp ) VOID ScrollVPort(struct ViewPort *vp); FUNCTION After the programmer has adjusted the Offset values in the RasInfo structures of ViewPort, change the copper lists to reflect the Scroll positions. Changing the BitMap ptr in RasInfo and not changing 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() graphics/view.h graphics.library/SetABPenDrMd graphics.library/SetABPenDrMd NAME SetABPenDrMd -- Set pen colors and draw mode for a RastPort. (V39) SYNOPSIS SetABPenDrMd( rp, apen, bpen, mode ) VOID SetABPenDrMd( struct 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. RESULT 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!). BUGS SEE ALSO SetAPen() SetBPen() SetDrMd() graphics/rastport.h graphics.library/SetAPen graphics.library/SetAPen NAME SetAPen -- Set the primary pen for a RastPort. SYNOPSIS SetAPen( rp, pen ) VOID SetAPen( struct RastPort *, UBYTE ); FUNCTION Set the primary drawing pen for lines, fills, and text. INPUTS rp - pointer to RastPort structure. pen - (0-255) RESULT Changes the minterms in the RastPort to reflect new primary pen. Sets line drawer to restart pattern. BUGS SEE ALSO SetBPen() graphics/rastport.h graphics.library/SetBPen graphics.library/SetBPen NAME SetBPen -- Set secondary pen for a RastPort SYNOPSIS SetBPen( rp, pen ) VOID SetBPen( struct RastPort *, UBYTE ); FUNCTION Set the secondary drawing pen for lines, fills, and text. INPUTS rp - pointer to RastPort structure. pen - (0-255) RESULT Changes the minterms in the RastPort to reflect new secondary pen. Sets line drawer to restart pattern. BUGS SEE ALSO SetAPen() graphics/rastport.h graphics.library/SetChipRev graphics.library/SetChipRev NAME SetChipRev -- turns on the features of a Chip Set (V39) SYNOPSIS uint32 chiprevbits = SetChipRev(uint32 ChipRev); 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. RESULT 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. SEE ALSO graphics/gfxbase.h graphics.library/SetCollision graphics.library/SetCollision NAME SetCollision -- Set a pointer to a user collision routine. SYNOPSIS SetCollision(num, routine, GInfo) VOID SetCollision(ULONG, VOID (*)(), struct 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. See graphics/gels.h for the prototype. GInfo = pointer to a GelsInfo structure RESULT BUGS SEE ALSO InitGels() graphics/gels.h graphics/rastport.h graphics.library/SetDrMd graphics.library/SetDrMd NAME SetDrMd -- Set drawing mode for a RastPort SYNOPSIS SetDrMd( rp, mode ) VOID SetDrMd( struct 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. RESULT The mode set is dependent on the bits selected. Changes minterms to reflect new drawing mode. Sets line drawer to restart pattern. BUGS SEE ALSO SetAPen() SetBPen() graphics/rastport.h graphics.library/SetFont graphics.library/SetFont NAME SetFont -- Set the text font and attributes in a RastPort. SYNOPSIS SetFont(rp, font) VOID SetFont(struct RastPort *, struct 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() RESULT 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 one of these font variants will cause the system to try to modify your font to make it acceptable. SetFont() returns no result but may fail. It can only fail for fonts not obtained from OpenFont() or OpenDiskFont(), e.g. in-code TextFonts. It will not set the font if ExtendFont() fails (out of memory or obsolete font). In this case it simply keeps the previous font. 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() diskfont.library/OpenDiskFont() graphics/text.h graphics.library/SetMaxPen graphics.library/SetMaxPen NAME SetMaxPen -- set maximum pen value for a rastport (V39). SYNOPSIS SetMaxPen ( rp, maxpen) VOID SetMaxPen(struct 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. RESULT 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. BUGS 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 SetWriteMask() graphics.library/SetOPen graphics.library/SetOPen NAME SetOPen -- Change the Area OutLine pen and turn on Outline mode for areafills. SYNOPSIS SetOPen(rp, pen) VOID SetOPen( struct 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 BUGS SEE ALSO AreaEnd() graphics/gfxmacros.h graphics/rastport.h graphics.library/SetOutlinePen graphics.library/SetOutlinePen NAME SetOutlinePen -- Set the Outline Pen value for a RastPort (V39). SYNOPSIS old_pen=SetOutlinePen ( rp, pen ) ULONG SetOutlinePen(struct 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 RESULT returns the previous outline pen BUGS NOTES SEE ALSO GetOutlinePen() graphics/gfxmacros.h graphics.library/SetRast graphics.library/SetRast NAME SetRast - Set an entire drawing area to a specified color. SYNOPSIS SetRast( rp, pen ) VOID SetRast( struct 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 RESULT All pixels within the drawing area are set to the selected pen number. BUGS SEE ALSO RectFill() graphics/rastport.h graphics.library/SetRGB32 graphics.library/SetRGB32 NAME SetRGB32 -- Set one color register for this Viewport. (V39) SYNOPSIS SetRGB32( vp, n, r, g, b ) VOID SetRGB32( struct 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) RESULT 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 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() graphics/view.h graphics.library/SetRGB32CM graphics.library/SetRGB32CM NAME SetRGB32CM -- Set one color register for this ColorMap. (V39) SYNOPSIS SetRGB32CM( cm, n, r, g, b ) VOID SetRGB32CM( struct ColorMap *, UWORD, ULONG, ULONG , ULONG); INPUTS cm - colormap n - the number of the color register to set. Must not exceed the number of colors allocated for the colormap. r - red level (32 bit unsigned left justified fraction) g - green level b - blue level RESULT 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. BUGS Prior to V46 the lower nibble of the blue color in the ColorMap was constructed from the wrong bits of the input ULONG value, e.g. 0x01234567 -> 0x03 instead of 0x01 (or 0x01010101 returned by GetRGB32()). SEE ALSO GetColorMap() GetRGB32() SetRGB32() SetRGB4CM() graphics/view.h graphics.library/SetRGB4 graphics.library/SetRGB4 NAME SetRGB4 -- Set one color register for this viewport. SYNOPSIS VOID SetRGB4(struct ViewPort *vp, uint16 n, uint8 r, uint8 g, uint8 b); 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) RESULT 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 Under V36 and up, it is not safe to call this function from an interrupt, due to semaphore protection of graphics copper lists. BUGS SEE ALSO LoadRGB4() GetRGB4() graphics/view.h graphics.library/SetRGB4CM graphics.library/SetRGB4CM NAME SetRGB4CM -- Set one color register for this ColorMap. SYNOPSIS SetRGB4CM( cm, n, r, g, b ) VOID SetRGB4CM( struct ColorMap *, UWORD, 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) RESULT 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. BUGS SEE ALSO GetColorMap() GetRGB4() SetRGB4() graphics/view.h graphics.library/SetRPAttrsA graphics.library/SetRPAttrsA NAME SetRPAttrsA -- modify rastport settings via a tag list SetRPAttrs -- varargs stub for SetRPAttrsA SYNOPSIS SetRPAttrsA(rp, tags) uint32 SetRPAttrsA(struct RastPort *, CONST struct TagItem *); SetRPAttrs(rp, tag1, ...); FUNCTION Modify settings of a rastport, based on the taglist passed. currently available tags are: RPTAG_Font Font for Text() RPTAG_APen Primary rendering pen RPTAG_BPen Secondary rendering pen RPTAG_DrMd Drawing mode (see graphics/rastport.h) RPTAG_OutlinePen Area Outline pen RPTAG_OPen Area Outline pen (short alias added in V51) RPTAG_WriteMask Bit Mask for writing. RPTAG_MaxPen Maximum pen to render (see SetMaxPen()) Tags introduced in V51: RPTAG_APenColor Primary rendering color (overrides APen) RPTAG_BPenColor Secondary rendering color (overrides BPen) RPTAG_OPenColor Area outline color (overrides OutlinePen) RPTAG_OutlinePenColor Alias for RPTAG_OPenColor The color format used by the three tags above is 0xAARRGGBB. Please note that these tags won't have any effect when rp->BitMap does not point to a directmapped bitmap. The alpha part is currently ignored and should be set to 0xFF. RPTAG_RemapColorFonts Tells graphics to use ColorTextFont-> ColorFontColors to render text. The destination bitmap must be directmapped to make this work. This tag is a boolean. Tags introduced in V54: INPUTS rp - pointer to the RastPort to modify. tags - a standard tag list RESULT Return the number of handled Tags. BUGS Before 54.136 this function did not return anything, now it returns the number of handled tags. SEE ALSO SetFont() SetSoftStyle() SetAPen() SetBPen() SetDrMd() SetOutLinePen() SetWriteMask() SetMaxPen() GetRPAttrsA() graphics/rpattr.h graphics.library/SetSoftStyle graphics.library/SetSoftStyle NAME SetSoftStyle -- Set the soft style of the current font. SYNOPSIS newStyle = SetSoftStyle(rp, style, enable) ULONG SetSoftStyle(struct 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. BUGS SEE ALSO AskSoftStyle() graphics/text.h graphics.library/SetWriteMask graphics.library/SetWriteMask NAME SetWriteMask -- Set the pixel write mask value for a RastPort (V39). SYNOPSIS success=SetWriteMask ( rp, msk ) ULONG SetWriteMask(struct 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. RESULT Graphics devices which do not support per-bit masking will return 0 (failure). BUGS NOTES SEE ALSO graphics/gfxmacros.h graphics.library/SortGList graphics.library/SortGList NAME SortGList -- Sort the current gel list, ordering its y,x coordinates. SYNOPSIS SortGList(rp) VOID SortGList(struct 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 RESULT BUGS SEE ALSO InitGels() DoCollision() DrawGList() graphics/rastport.h graphics.library/StripFont graphics.library/StripFont NAME StripFont -- remove the tf_Extension from a font (V36) SYNOPSIS StripFont(font) VOID StripFont(struct TextFont *); graphics.library/SyncSBitMap graphics.library/SyncSBitMap NAME SyncSBitMap -- Syncronize Super BitMap with whatever is in the standard Layer bounds. SYNOPSIS SyncSBitMap( layer ) VOID SyncSBitMap( struct Layer * ); FUNCTION Copy all bits from ClipRects in Layer into Super BitMap 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. RESULT 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. BUGS SEE ALSO CopySBitMap() graphics/clip.h graphics.library/Text graphics.library/Text NAME Text -- Write text characters (no formatting). SYNOPSIS Text(rp, string, length) VOID Text(struct RastPort *, CONST_STRPTR, UWORD); 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 Move() TextLength() graphics/text.h graphics/rastport.h graphics.library/TextExtent graphics.library/TextExtent NAME TextExtent -- Determine raster extent of text data. (V36) SYNOPSIS TextExtent(rp, string, count, textExtent) VOID TextExtent(struct RastPort *, CONST_STRPTR, UWORD, struct 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 See also BUGS section of TextLength() autodoc. SEE ALSO TextLength() Text() TextFit() graphics/text.h graphics/rastport.h graphics.library/TextFit graphics.library/TextFit NAME TextFit - count characters that will fit in a given extent (V36) SYNOPSIS chars = TextFit(rastport, string, strLen, textExtent, constrainingExtent, strDirection, constrainingBitWidth, constrainingBitHeight) UWORD TextFit(struct RastPort *, CONST_STRPTR, UWORD, struct TextExtent *, CONST struct 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() graphics/text.h graphics/rastport.h graphics.library/TextLength graphics.library/TextLength NAME TextLength -- Determine raster length of text data. SYNOPSIS length = TextLength(rp, string, count) WORD TextLength(struct RastPort *, CONST_STRPTR, UWORD); 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 Text() using this string, add the length to cp_x (cp_y is unchanged by Text()). 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. This has been fixed in v51.21, length will be zero in this case. If you need determine the length of long strings, the following code can be used: LONG TextLength32(struct RastPort *rp, STRPTR string, ULONG count) { struct TextExtent te; LONG result = 0; ULONG chars; while (count > 0) { chars = TextFit(rp, string, MIN(count,65535), &te, NULL, 1, 32767, 32767); if (!chars) break; // paranoia! string += chars; count -= chars; result += te.te_Width; } return result; } Please note that this code requires graphics 51.21 or better to work. SEE ALSO TextExtent() Text() TextFit() graphics/text.h graphics/rastport.h graphics.library/UnlockBitMap graphics.library/UnlockBitMap NAME UnlockBitMap -- Unlock a previously locked BitMap. (V54) SYNOPSIS void UnlockBitMap(APTR lock); FUNCTION This function releases the BitMap lock obtained by a prior call to LockBitMapTagList(). INPUTS lock - Lock obtained with LockBitMapTagList() (NULL is safe and does nothing) SEE ALSO LockBitMapTagList() graphics.library/UnlockBitMapFromBoard graphics.library/UnlockBitMapFromBoard NAME UnlockBitMapFromBoard -- Unlock a BitMap from a board (V54) SYNOPSIS void UnlockBitMapFromBoard(APTR lock, BOOL modified); FUNCTION This function releases the bitmap lock obtained by a prior call to LockBitMapToBoardTagList(). INPUTS lock - Pointer to a locked RTG bitmap (NULL is safe and does nothing) modified - Set to TRUE if the bitmap was modified SEE ALSO LockBitMapToBoardTagList() graphics.library/UnlockLayerRom graphics.library/UnlockLayerRom NAME UnlockLayerRom -- Unlock Layer structure by ROM(gfx lib) code. SYNOPSIS UnlockLayerRom( layer ) VOID UnlockLayerRom( struct 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 BUGS SEE ALSO LockLayerRom() layers.library/UnlockLayer() graphics/clip.h graphics.library/VBeamPos graphics.library/VBeamPos NAME VBeamPos -- Get vertical beam position at this instant. SYNOPSIS pos = VBeamPos() LONG VBeamPos( VOID ); FUNCTION Get the vertical beam position from the hardware. INPUTS none RESULT interrogates hardware for beam position and returns value. valid results in are the range of 0-511. Because of multitasking, the actual value returned may have no use. If you are the highest priority task then the value returned should be close, within 1 line. BUGS SEE ALSO graphics.library/VideoControl graphics.library/VideoControl NAME VideoControl -- Modify the operation of a ViewPort's ColorMap (V36) SYNOPSIS uint32 error = VideoControl(struct ColorMap *cm, struct TagItem *tags); uint32 error = VideoControlTags(struct ColorMap *cm, Tag tag1, ...); 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. VC_DPMSLevel Sets the VESA Display Power Management Signaling (DPMS) power saving level for the associated viewport. See enDPMSLevel in for values. Defaults to DPMSLEVEL_ON. (V54) Note DPMS works only with graphics boards and is implemented by each graphics driver. 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. RESULT 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 must_remake = -1; error = VideoControl(myvp->ColorMap, VTAG_BORDERBLANK_SET, -1, (GFXBase->lib_Version >= 39) ? VTAG_IMMEDIATE : TAG_IGNORE, &must_remake); if (must_remake) { MakeVPort(myview, myvp); MrgCop(myview); } EXAMPLE struct TagItem VCTags[] = { {VTAG_BORDERBLANK_GET, NULL}, {VTAG_SPRITERESN_SET, SPRITERESN_35NS}, {TAG_DONE, NULL}, }; BOOL bblank = FALSE; if (VideoControl(cm, VCTags) == NULL) { bblank = (VCTags[0].ti_Tag == VTAG_BORDERBLANK_SET); } EXAMPLE struct TagItem VCTags[] = { { VC_NoColorPaletteLoad_Query, NULL }, { TAG_DONE, 0 } }; ULONG query; VCTags[0].ti_Data = (ULONG)&query; if (VideoControl(cm, VCTags) == NULL) { printf("Palette loading is %s\n", (query ? "off" : "on")); } BUGS SEE ALSO graphics/videocontrol.h, GetColorMap(), FreeColorMap() graphics.library/WaitBlit graphics.library/WaitBlit NAME 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 RESULT Your program waits until the blitter is finished. 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 OwnBlitter() DisownBlitter() hardware/blit.h graphics.library/WaitBOVP graphics.library/WaitBOVP NAME WaitBOVP -- Wait till vertical beam reached bottom of this viewport. SYNOPSIS WaitBOVP( vp ) VOID WaitBOVP( struct ViewPort * ); FUNCTION Returns when the vertical beam has reached the bottom of this viewport. INPUTS vp - pointer to ViewPort structure RESULT 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() VBeamPos() graphics.library/WaitTOF graphics.library/WaitTOF NAME 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 RESULT 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. BUGS SEE ALSO exec.library/Wait() exec.library/Signal() graphics.library/WriteChunkyPixels graphics.library/WriteChunkyPixels NAME WriteChunkyPixels -- write the pen number value of a rectangular array of pixels starting at a specified x,y location and continuing through to another x,y location within a certain RastPort. (V40) SYNOPSIS WriteChunkyPixels(rp,xstart,ystart,xstop,ystop,array,bytesperrow) VOID WriteChunkyPixels(struct RastPort *, UWORD, UWORD, UWORD, UWORD, CONST UBYTE *, LONG); FUNCTION For each pixel in a rectangular region, decode the pen number selector from a linear array of pen numbers into the bit-planes used to describe a particular rastport. INPUTS rp - pointer to a RastPort structure (xstart,ystart) - starting point in the RastPort (xstop,ystop) - stopping point in the RastPort array - pointer to an array of UBYTEs from which to fetch the pixel data. 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. RESULT NOTES xstop must be >= xstart ystop must be >= ystart The source array can be in fast RAM. ===chunky-to-planar conversion HW: GfxBase->ChunkyToPlanarPtr is either NULL, or a pointer to a HW register used to aid in the process of converting 8-bit chunky pixel data into the bit-plane format used by the Amiga custom display chips. If NULL, then such hardware is not present. If an expansion device provides hardware which operates compatibly, than it can install the HW address into this pointer at boot time, and the system will use it. This pointer may be used for direct access to the chunky-to-planar conversion HW, if more is desired than the straight chunky-pixel copy that is performed by WriteChunkyPixels(). If using the hardware directly, it should only be accessed when the task using it has control of the blitter (via OwnBlitter()), since this is the locking used to arbitrate usage of this device. The hardware may be viewed as a device which accepts 32 8-bit chunky pixels and outputs 8 longwords of bitplane data. For proper operation, exactly 8 longwords (containing 32 pixels) of chunky data should be written to *(GfxBase->ChunkyToPlanarPtr). After the data is written, bitplane data (starting with plane 0) can be read back a longword at a time. There is no need to read back all 8 longwords if the high-order bitplanes are not needed. Since WriteChunkyPixels is not (currently) particularly fast on systems without the chunky-to-planar hardware, time critical applications (games, etc) may want to use their own custom conversion routine if GfxBase->ChunkyToPlanarPtr is NULL, and call WriteChunkyPixels() otherwise. This pointer is only present in GfxBase in versions of graphics.library >= 40, so this should be checked before the pointer is read. BUGS Not very fast on systems without chunky-to-planar conversion hardware. SEE ALSO WritePixel() graphics/rastport.h graphics.library/WritePixel graphics.library/WritePixel NAME WritePixel -- Change the pen num of one specific pixel in a specified RastPort. SYNOPSIS int32 error = WritePixel(struct RastPort *rp, int16 x, int16 y); FUNCTION Changes the pen number of the selected pixel in the specified RastPort to that currently specified by Pen A, 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. RESULT error = 0 if pixel succesfully changed = -1 if (x,y) is outside the RastPort SEE ALSO ReadPixel(), WritePixelColor() graphics.library/WritePixelArray graphics.library/WritePixelArray NAME WritePixelArray -- Write the color values from a rectangular area into a RastPort. (V54) SYNOPSIS void WritePixelArray(uint8 *src, uint32 srcX, uint32 srcY, uint32 srcBytesPerRow, PIX_FMT srcPixelFormat, struct RastPort *dst, uint32 dstX, uint32 dstY, uint32 sizeX, uint32 sizeY); FUNCTION Writes the color values of all pixels in a rectangular area of a specified memory area into the RastPort. INPUTS src - source array to read the pixel data from (srcX, srcY) - starting point in the RastPort srcBytesPerRow - source bytes per row srcPixelFormat - source pixel format dst - destination RastPort (dstX, dstY) - starting point in destination array (sizeX, sizeY) - size of the rectangular area SEE ALSO ReadPixelArray(), WritePixelArray8() graphics.library/WritePixelArray8 graphics.library/WritePixelArray8 NAME WritePixelArray8 -- write the pen number value of a rectangular array of pixels starting at a specified x,y location and continuing through to another x,y location within a certain RastPort. (V36) SYNOPSIS int32 count = WritePixelArray8(struct RastPort *rp, uint16 xstart, uint16 ystart, uint16 xstop, uint16 ystop, uint8 *array, struct RastPort *temprp); FUNCTION For each pixel in a rectangular region, decode the pen number selector from a linear array of pen numbers into the bit-planes used to describe a particular rastport. INPUTS rp - pointer to a RastPort structure (xstart,ystart) - starting point in the RastPort (xstop,ystop) - stopping point in the RastPort array - pointer to an array of UBYTEs from which to fetch the pixel data. Allocate at least ((((width + 15) >> 4) << 4) * (ystop - ystart + 1)) bytes. temprp - temporary rastport (copy of rp with Layer set to NULL, temporary memory allocated for temprp->BitMap with Rows set to 1, temprp->BitMap->BytesPerRow set to (((width + 15) >> 4) << 1), and temporary memory allocated for temprp->BitMap->Planes[]) RESULT count will be set to the number of pixels plotted. NOTE xstop must be >= xstart ystop must be >= ystart SEE ALSO WritePixel() graphics/rastport.h graphics.library/WritePixelColor graphics.library/WritePixelColor NAME WritePixelColor -- Change the color of one specific pixel in a specified RastPort. (V54) SYNOPSIS int32 error = WritePixelColor(struct RastPort *rp, uint32 x, uint32 y, uint32 color); FUNCTION Changes the color of the selected pixel in the specified RastPort. INPUTS rp - a pointer to the RastPort structure (x,y) - point within the RastPort at which the selected pixel is located. RESULT error - 0 for no error. All other values are reserved. SEE ALSO ReadPixelColor(), WritePixel() graphics.library/WritePixelLine8 graphics.library/WritePixelLine8 NAME WritePixelLine8 -- write the pen number value of a horizontal line of pixels starting at a specified x,y location and continuing right for count pixels. (V36) SYNOPSIS int32 count = WritePixelLine8(struct RastPort *rp, uint16 xstart, uint16 ystart, uint16 width, uint8 *array, struct RastPort *temprp); FUNCTION For each pixel in a horizontal region, decode the pen number selector from a linear array of pen numbers into the bit-planes used to describe a particular rastport. INPUTS rp - pointer to a RastPort structure (x,y) - a point in the RastPort width - count of horizontal pixels to write array - pointer to an array of UBYTEs from which to fetch the pixel data. Allocate at least (((width + 15) >> 4) << 4) bytes. temprp - temporary rastport (copy of rp with Layer set == NULL, temporary memory allocated for temprp->BitMap with Rows set == 1, temprp->BitMap->BytesPerRow == (((width + 15) >> 4) << 1), and temporary memory allocated for temprp->BitMap->Planes[]) RESULT Count will be set to the number of pixels plotted NOTE width must be non negative SEE ALSO WritePixel() graphics/rastport.h graphics.library/XorRectRegion graphics.library/XorRectRegion NAME XorRectRegion -- Perform 2d XOR operation of rectangle with region, leaving result in region SYNOPSIS status = XorRectRegion(region, rectangle) BOOL XorRectRegion( struct Region *, CONST struct 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 BUGS SEE ALSO OrRegionRegion() AndRegionRegion() graphics/regions.h graphics.library/XorRegionRegion graphics.library/XorRegionRegion NAME XorRegionRegion -- Perform 2d XOR operation of one region with second region, leaving result in second region SYNOPSIS status = XorRegionRegion(region1, region2) BOOL XorRegionRegion( CONST struct Region *, struct 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 SEE ALSO XorRectRegion() OrRegionRegion() graphics/regions.h