Amiga ISO Collection

home *** CD-ROM | disk | FTP | other *** search

/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Inc&AD2.1 / Text_Autodocs / graphics.doc < prev next >

Wrap

Text File | 1992-09-11 | 150.0 KB | 5,351 lines

TABLE OF CONTENTS graphics.library/AddAnimOb graphics.library/AddBob graphics.library/AddFont graphics.library/AddVSprite graphics.library/AllocBitMap graphics.library/AllocBitMapData graphics.library/AllocPalette graphics.library/AllocRaster 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/BitMapScale graphics.library/BltBitMap graphics.library/BltBitMapRastPort graphics.library/BltClear graphics.library/BltMaskBitMapRastPort graphics.library/BltPattern graphics.library/BltTemplate graphics.library/CalcIVG graphics.library/CBump graphics.library/CEND graphics.library/ChangeSprite 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/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/FindDisplayInfo graphics.library/Flood graphics.library/FontExtent graphics.library/FreeBitMap graphics.library/FreeBitMapData graphics.library/FreeColorMap graphics.library/FreeCopList graphics.library/FreeCprList graphics.library/FreeGBuffers graphics.library/FreePalette graphics.library/FreeRaster graphics.library/FreeSprite graphics.library/FreeVPortCopLists graphics.library/GetAPen graphics.library/GetBPen graphics.library/GetColorMap graphics.library/GetDisplayInfoData graphics.library/GetDrMd graphics.library/GetGBuffers graphics.library/GetOPen graphics.library/GetRGB32 graphics.library/GetRGB4 graphics.library/GetSprite graphics.library/GetVPModeID graphics.library/GfxAssociate graphics.library/GfxFree graphics.library/GfxLookUP graphics.library/GfxNew 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/LockLayerRom graphics.library/MakeVPort graphics.library/ModeNotAvailable graphics.library/Move graphics.library/MoveSprite graphics.library/MrgCop graphics.library/NewRegion graphics.library/NextDisplayInfo graphics.library/OpenFont graphics.library/OpenMonitor graphics.library/OrRectRegion graphics.library/OrRegionRegion graphics.library/OwnBlitter graphics.library/PickBestColor graphics.library/PolyDraw graphics.library/QBlit graphics.library/QBSBlit graphics.library/ReadPixel graphics.library/ReadPixelArray8 graphics.library/ReadPixelLine8 graphics.library/RectFill graphics.library/RemBob graphics.library/RemFont graphics.library/RemIBob graphics.library/RemVSprite graphics.library/ScalerDiv graphics.library/ScrollRaster graphics.library/ScrollVPort graphics.library/SearchColorMap graphics.library/SetABPenDrMd graphics.library/SetAPen graphics.library/SetBPen graphics.library/SetCollision graphics.library/SetDrMd graphics.library/SetFont graphics.library/SetOPen graphics.library/SetRast graphics.library/SetRGB32 graphics.library/SetRGB4 graphics.library/SetRGB4CM graphics.library/SetSoftStyle graphics.library/SortGList graphics.library/StripFont graphics.library/SyncSBitMap graphics.library/Text graphics.library/TextExtent graphics.library/TextFit graphics.library/TextLength graphics.library/UnlockLayerRom graphics.library/VBeamPos graphics.library/VideoControl graphics.library/WaitBlit graphics.library/WaitBOVP graphics.library/WaitTOF graphics.library/WeighTAMatch graphics.library/WritePixel graphics.library/WritePixelArray8 graphics.library/WritePixelLine8 graphics.library/XorRectRegion graphics.library/XorRegionRegion graphics.library/WritePixel graphics.library/LoadRGB32 graphics.library/AddAnimOb graphics.library/AddAnimOb NAME AddAnimOb -- Add an AnimOb to the linked list of AnimObs. SYNOPSIS AddAnimOb(anOb, anKey, rp) A0 A1 A2 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) A0 A1 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) A1 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 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) A0 A1 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. SYNOPSIS bitmap=AllocBitMap(sizex,sizey,depth, flags, friend_bitmap) d0 d1 d2 d3 a0 struct BitMap *AllocBitMap(ULONG,ULONG,ULONG,ULONG, struct BitMap *); FUNCTION Allocates and initializes a bitmap structure. Allocates and initializes bitplane data, and sets the bitmap's planes to point to it. INPUTS sizex = the width (in pixels) desired for the bitmap data. 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. 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. friend_bitmap = 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 friend_bitmap. BUGS NOTES When allocating using a friend bitmap, it is not safe to assume anything about the structure of the bitmap data. The only safe operations to perform on it are: - blitting it to another bitmap, which must be either a standard amiga bitmap, or a friend of this bitmap. - blitting from this bitmap to a friend bitmap or to a standard amiga bitmap. - attaching it to a rastport and making rendering calls. It is also safe to examine the Depth field of the bitmap to determine how deep of a bitmap must be allocated to hold a copy of this one. 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)! Under RTG, this structure may not be valid on all devices. When finished with the bitmap, you should call FreeBitMap() to dispose of it. SEE ALSO FreeBitMap() AllocBitMapData() FreeBitMapData() graphics.library/AllocBitMapData graphics.library/AllocBitMapData NAME AllocBitMapData -- Initialize a bitmap and attach bitplanes to it. SYNOPSIS error=AllocBitMapData(bm,sizex,sizey,depth,flags) a0 d0 d1 d2 d3 ULONG AllocBitMapData(struct BitMap *,ULONG,ULONG,ULONG,ULONG); FUNCTION Initializes a bitmap structure. Allocates and initializes bitplane data, and sets the bitmap's planes to point to it. This function is similar to a call to InitBitMap() followed by multiple calls to AllocRaster(). INPUTS bm = A pointer to a BitMap structure, which will be filled in. 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. error=0 if success, or an error #. The only currently defined error is out of memory. flags = BMF_CLEAR to specify that the allocated raster should be filled with color 0. BMF_DISPLAYABLE to specify that this bitmap data should be allocated in such a manner that it can be displayed. Displayable data has more severe alignment restrictions than non-displyable data. BUGS NOTES This call is not recommended. For maximum upwards compatibility, you should use the AllocBitMap() call. When finished with the bitmap data, you should call FreeBitMapData() to dispose of it. SEE ALSO FreeBitMapData() AllocBitMap() FreeBitMap() graphics.library/AllocPalette graphics.library/AllocPalette NAME AllocPalette -- Obtain a free palette entry for use by your program. ( V38) SYNOPSIS n | -1= AllocPalette( cm, n, r, g, b, flags) d0 a0 d0 d1 d2 d3 d4 ULONG AllocPalette(struct ColorMap *,ULONG,ULONG,ULONG,ULONG,ULONG); FUNCTION Attempt to allocate an entry in the colormap for use by the application. If successful, you should free this entry after you have finished with it. 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= the only flag currently in use is PALETTE_EXCLUSIVE 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 PALETTE_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 PickColorMap() 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. This routine does not work if called on 1.3 format ColorMap structures. SEE ALSO GetColorMap() FreePalette() AttachPalExtra() graphics.library/AllocRaster graphics.library/AllocRaster NAME AllocRaster -- Allocate space for a bitplane. SYNOPSIS planeptr = AllocRaster( width, height ) d0 d0:16 d1:16 PLANEPTR AllocRaster(UWORD,UWORD); 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 bits wide for 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. BUGS SEE ALSO FreeRaster() graphics/gfx.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) a0 a1 void AndRectRegion( struct Region *, 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) d0 a0 a1 BOOL AndregionRegion(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) A0 A1 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 = (int) AreaCircle( rp, cx, cy, radius) D0 A1 D0 D1 D2 ULONG 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) d0 A1 D0:16 D1:16 ULONG AreaDraw( struct RastPort *, SHORT, SHORT); FUNCTION Add point to the vector buffer. INPUTS rp - points to a RastPort structure. x,y - are coordinates of a point in the raster. 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 ) d0 a1 d0:16 d1:16 d2:16 d3:16 LONG AreaEllipse( struct RastPort *, SHORT, SHORT, SHORT, SHORT) FUNCTION Add an ellipse to the vector buffer. It will be draw when AreaEnd() is called. INPUTS rp - pointer to a RastPort structure cx - x coordinate of the centerpoint relative to the rastport. cy - y coordinate of the centerpoint relative to the rastport. a - the horizontal radius of the ellipse (note: a must be > 0) b - the vertical radius of the ellipse (note: b must be > 0) 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) d0 A1 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 occured 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) d0 a1 d0:16 d1:16 LONG AreaMove( struct RastPort *, SHORT, SHORT ); FUNCTION Close the last polygon and start another polygon at (x,y). Add the necessary points to vector buffer. Closing a polygon may result in the generation of another AreaDraw() to close previous polygon. Remember to have an initialized AreaInfo structure attached to the RastPort. INPUTS rp - points to a RastPort structure x,y - positions in the raster 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) A1 A0 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 TTextAttr. RESULT The textAttr structure is filled with the RastPort's text attributes. BUGS SEE ALSO graphics/text.h graphics.library/AskSoftStyle graphics.library/AskSoftStyle NAME AskSoftStyle -- Get the soft style bits of the current font. SYNOPSIS enable = AskSoftStyle(rp) D0 A1 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. (V38) SYNOPSIS AttachPalExtra( cm, vp) a0 a1 void 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. BUGS NOTES If there is already a PalExtra associated with the ColorMap, then this function will do nothing. This function is incompatible with 1.3 format ColorMaps. SEE ALSO GetColorMap() FreeColorMap() AllocPalette() graphics.library/AttemptLockLayerRom graphics.library/AttemptLockLayerRom * NAME AttemptLockLayerRom -- Attempt to Lock Layer structure by rom(gfx lib) code SYNOPSIS gotit = AttemptLockLayerRom( layer ) d0 a5 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/BitMapScale graphics.library/BitMapScale NAME BitMapScale -- Perform raster scaling on a bit map. (V36) SYNOPSIS BitMapScale(bitScaleArgs) A0 void BitMapScale(struct 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 - equivalant to the ratio srcWidth:destWidth, but not necessarily the same numbers. Each must be in the range 1..16383. bsa_YSrcFactor:bsa_YDestFactor - equivalant 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, D0 A0 D0:16 D1:16 A1 DstX, DstY, SizeX, SizeY, Minterm, Mask [, TempA]) D2:16 D3:16 D4:16 D5:16 D6:8 D7:8 [A2] ULONG BltBitMap(struct BitMap *, WORD, WORD, struct BitMap *, WORD, WORD, WORD, WORD, UBYTE, UBYTE, UWORD *); 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 accessable memory to hold a line of A source for the blit (ie CHIP RAM). BitBitMap 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) D0 A0 D0 D1 A1 D2 D3 D4 D5 D6 BOOL BltBitMapRastPort (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/BltClear graphics.library/BltClear NAME BltClear - Clear a block of memory words to zero. SYNOPSIS BltClear( memBlock, bytecount, flags ) a1 d0 d1 void BltClear( void *, ULONG, ULONG ); FUNCTION For memory that is local and blitter accessable, 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 dependant. 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, A0 D0 D1 A1 D2 D3 D4 D5 minterm, bltmask) D6 A2 void BltMaskBitMapRastPort (struct BitMap *, WORD, WORD, struct RastPort *, WORD, WORD, WORD, WORD, UBYTE, APTR); FUNCTION Blits from source bitmap to position specified in destination rastport using bltmask to determine where source overlays destination, and minterm to determine whether to copy the source image "as is" or to "invert" the sense of the source image when copying. In either case, blit only occurs where 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) a1, a0 d0 d1 d2 d3 d4 void BltPattern (struct RastPort *, void *, SHORT, SHORT, SHORT, SHORT, SHORT); FUNCTION Blit using drawmode,areafill pattern, and mask at position rectangle (xl,yl) (maxx,maxy). INPUTS rp - points to the destination RastPort for the blit. mask - points to 2 dimensional mask if needed if mask == NULL then use a rectangle. xl,yl - coordinates of upper left of rectangular region in RastPort maxx,maxy - points to lower right of rectangular region in RastPort bytecnt - BytesPerRow for mask 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, A0 D0:16 D1:16 A1 DstX, DstY, SizeX, SizeY) D2:16 D3:16 D4:16 D5:16 void BltTemplate(UWORD *, 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 acheived 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 (V38) SYNOPSIS count = CalcIVG(View, ViewPort) d0.w a0 a1 UWORD CalcIVG(struct View *, struct ViewPort *); FUNCTION To calculate the maximum number of blank lines above a viewport needed to load all the copper instructions, after accounting for the viewport bandwidth, dimension, position, number of BitPlanes required in the gap area. This may not be the actual number used, as some copper instructions could be loaded before the highest viewport. INPUTS View - pointer to the View ViewPort - pointer to the ViewPort you are interested in. RESULT count - the number of non-interlaced scan lines needed to execute all the copper instructions for ViewPort, or 0 if any error. NOTES For best results, attach a ViewPortExtra structure to ViewPort, and initialise the ViewPortExtra->bpu, ViewPortExtra->FMode and ViewPortExtra->Blank fields if you want anything other than 0, Max-Bandwidth and -1 respectively (a -1 in vpe->Blank means all the lines in the gap are to be blank). If you are sure of setting the FMode correctly, then you must set the FPXF_HAVE_FMODE flags in the ViewPortExtra->Flags field, else the system will calculate it for you. It is recommended that you leave the calculation to the system. This function can also be used to calculate the number of scan lines needed to execute a batch of copper instructions in the middle of a display window by setting VPXF_IN_DIWINDOW in ViewPortExtra->Flags. Setting this bit means vpe->Blank is ignored. 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 ) a1 void CBump( struct UCopList * ); FUNCTION Increment pointer to space for next instruction in user copper list. INPUTS c - pointer to UCopList structure RESULTS User copper list pointer is incremented to next position. Pointer is repositioned to next user copperlist instruction block if the current block is full. Note: CBump is usually invoked for the programmer as part of the macro definitions CWAIT or CMOVE. BUGS 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/ChangeSprite graphics.library/ChangeSprite NAME ChangeSprite -- Change the sprite image pointer. SYNOPSIS ChangeSprite( vp, s, newdata) a0 a1 a2 void ChangeSprite(struct ViewPort *, struct SimpleSprite *, void * ) FUNCTION The sprite image is changed to use the data starting at newdata INPUTS vp - pointer to ViewPort structure that this sprite is relative to, or 0 if relative only top of View s - pointer to SimpleSprite structure newdata - pointer to data structure of the following form. struct spriteimage { UWORD posctl[2]; /* used by simple sprite machine*/ UWORD data[height][2]; /* actual sprite image */ UWORD reserved[2]; /* initialized to */ /* 0x0,0x0 */ }; The programmer must initialize reserved[2]. Spriteimage must be in CHIP memory. The height subfield of the SimpleSprite structure must be set to reflect the height of the new spriteimage BEFORE calling ChangeSprite(). The programmer may allocate two sprites to handle a single attached sprite. After GetSprite(), ChangeSprite(), the programmer can set the SPRITE_ATTACHED bit in posctl[1] of the odd numbered sprite. If you need more than 8 sprites, look up VSprites in the graphics documentation. RESULTS BUGS SEE ALSO FreeSprite() ChangeSprite() MoveSprite() AddVSprite() graphics/sprite.h 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 ) a0 d0 struct CopList *UCopperListInit( struct UCopList *, UWORD ); FUNCTION Allocates and/or initialize copperlist structures/buffers internal to a UCopList structure. This is a macro that calls UCopListInit. You must pass a (non-initialized) UCopList to 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) A1 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) d0 a0 a1 BOOL ClearRectRegion(struct Region *, 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) a0 viod 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) A1 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) A0 D0 D1 A1 D2 D3 D4 D5 D6 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) A1 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 ) d0 a0 LONG CloseMonitor( struct MonitorSpec * ); FUNCTION Relinquish access to a MonitorSpec. INPUTS monitor_spec - a pointer to a MonitorSpec opened via OpenMonitor(), or NULL. RESULTS error - FALSE if MonitorSpec closed uneventfully. TRUE if MonitorSpec could not be closed. 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 , a , v ) a1 d0 d1 CBump( c ) a1 void CMove( struct UCopList *, void *, WORD ); FUNCTION Add instruction to move value v to hardware register a. INPUTS c - pointer to UCopList structure a - hardware register v - 16 bit value to be written RESULTS This is actually a macro that calls CMove(c,&a,v) and then calls CBump(c) to bump the local pointer to the next instruction. Watch out for macro side affects. BUGS SEE ALSO CINIT CWAIT CEND graphics/copper.h graphics.library/CopySBitMap graphics.library/CopySBitMap NAME CopySBitMap -- Syncronize Layer window with contents of Super BitMap SYNOPSIS CopySBitMap( layer ) a0 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 ) a1 d0 d1 CBump( c ) a1 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) a0 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) A1 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) a1 d0:16 d1:16 void Draw( struct RastPort *, SHORT, SHORT); FUNCTION Draw a line from the current pen position to (x,y). INPUTS rp - pointer to the destination RastPort x,y - coordinates of where in the RastPort to end the line. 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 ) a1 d0 d1 d2 d3 void DrawEllipse( struct RastPort *, SHORT, SHORT, SHORT, SHORT); FUNCTION Creates an elliptical outline within the rectangular region specified by the parameters, using the current foreground pen color. INPUTS rp - pointer to the RastPort into which the ellipse will be drawn. cx - x coordinate of the centerpoint relative to the rastport. cy - y coordinate of the centerpoint relative to the rastport. a - the horizontal radius of the ellipse (note: a must be > 0) b - the vertical radius of the ellipse (note: b must be > 0) BUGS NOTES this routine does not clip the ellipse to a non-layered rastport. SEE ALSO DrawCircle(), graphics/rastport.h graphics.library/DrawGList graphics.library/DrawGList NAME DrawGList -- Process the gel list, queueing VSprites, drawing Bobs. SYNOPSIS DrawGList(rp, vp) A1 A0 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) a1 d0:16 d1:16 d2:16 d3:16 void EraseRect(struct RastPort *, SHORT, SHORT, SHORT, SHORT); FUNCTION Fill the rectangular region specified by the parameters with the BackFill hook. If non-layered, the rectangular region specified by the parameters is cleared. If layered the Layer->BackFill Hook is used. INPUTS rp - pointer to a RastPort structure xmin - x coordinate of the upper left corner of the region to fill. ymin - y coordinate of the upper left corner of the region to fill. xmax - x coordinate of the lower right corner of the region to fill. ymax - y coordinate of the lower right corner of the region to fill. 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) D0 A0 A1 ULONG ExtendFont(struct TextFont *, struct TagItem *); SEE ALSO graphics/text.h graphics.library/FindDisplayInfo graphics.library/FindDisplayInfo NAME FindDisplayInfo -- search for a record identified by a specific key (V36) SYNOPSIS handle = FindDisplayInfo(ID) D0 D0 DisplayInfoHandle FindDisplayInfo(ULONG); FUNCTION Given a 32-bit Mode Key, return a handle to a valid DisplayInfoRecord found in the graphics database. Using this handle, you can obtain information about this Mode, including its default dimensions, properties, and whether it is currently available for use. INPUTS ID - unsigned long identifier 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 error = Flood( rp, mode, x, y) d0 a1 d2 d0 d1 BOOL Flood(struct RastPort *, ULONG, SHORT, SHORT); FUNCTION Search the BitMap starting at (x,y). Fill all adjacent pixels if they are: Mode 0: not the same color as AOLPen Mode 1: the same color as the pixel at (x,y) When actually doing the fill use the modes that apply to standard areafill routine such as drawmodes and patterns. INPUTS rp - pointer to RastPort (x,y) - coordinate in BitMap to start the flood fill at. mode - 0 fill all adjacent pixels searching for border. 1 fill all adjacent pixels that have same pen number as the one at (x,y). NOTES In order to use Flood, the destination RastPort must have a valid TmpRas raster whose size is as large as that of the RastPort. SEE ALSO AreaEnd() InitTmpRas() graphics/rastport.h graphics.library/FontExtent graphics.library/FontExtent NAME FontExtent -- get the font attributes of the current font (V36) SYNOPSIS FontExtent(font, fontExtent) A0 A1 void FontExtent(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 SYNOPSIS FreeBitMap(bm) a0 VOID FreeBitMap(struct BitMap *) FUNCTION Frees bitmap and all associated bitplanes INPUTS bm = A pointer to a BitMap structure. BUGS NOTES SEE ALSO FreeBitMapData() AllocBitMap() FreeBitMap() graphics.library/FreeBitMapData graphics.library/FreeBitMapData NAME FreeBitMapData -- free the graphics memory associated with a bitmap. SYNOPSIS FreeBitMapData(bm) a0 VOID FreeBitMapData(struct BitMap *) FUNCTION Frees all the bitplanes associated with a bitmap. INPUTS bm = A pointer to a BitMap structure. BUGS NOTES SEE ALSO AllocBitMapData() AllocBitMap() FreeBitMap() graphics.library/FreeColorMap graphics.library/FreeColorMap NAME FreeColorMap -- Free the ColorMap structure and return memory to free memory pool. SYNOPSIS FreeColorMap( colormap ) a0 void FreeColorMap(struct ColorMap *); FUNCTION Return the memory to the free memory pool that was allocated with GetColorMap. INPUTS colormap - pointer to ColorMap allocated with GetColorMap 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) a0 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) a0 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/FreeGBuffers graphics.library/FreeGBuffers NAME FreeGBuffers -- Deallocate memory obtained by GetGBufers. SYNOPSIS FreeGBuffers(anOb, rp, db) A0 A1 D0 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/FreePalette graphics.library/FreePalette NAME FreePalette -- Release an allocated palette entry to the free pool. (V 38) SYNOPSIS FreePalette( cm, n) a0 d0 void FreePalette( Struct ColorMap *, ULONG); FUNCTION Return the palette entry for use by other applications. If the reference count for this palette entry goes to zero, then it may be reset to another RGB value. INPUTS cm = A pointer to a color map created by GetColorMap(). n = A palette index obtained via any of the palette allocation functions. BUGS NOTES This function works for both shared and exclusive palette entries. SEE ALSO GetColorMap() AllocPalette() graphics.library/FreeRaster graphics.library/FreeRaster NAME FreeRaster -- Release an allocated area to the system free memory pool . SYNOPSIS FreeRaster( p, width, height) a0 d0:16 d1:16 void FreeRaster( PLANEPTR, USHORT, USHORT); FUNCTION Return the memory associated with this PLANEPTR of size width and height to the MEMF_CHIP memory pool. INPUTS p = a pointer to a memory space returned as a result of a call to AllocRaster. width - the width in bits of the bitplane. height - number of rows in bitplane. 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 ) d0 void FreeSprite( WORD ); FUNCTION Mark sprite as available for others to use. These sprite routines are provided to ease sharing of sprite hardware and to handle simple cases of sprite usage and movement. It is assumed the programs that use these routines do want to be good citizens in their hearts. ie: they will not FreeSprite unless they actually own the sprite. The Virtual Sprite machine may ignore the simple sprite machine. INPUTS pick - number in range of 0-7 RESULTS sprite made available for subsequent callers of GetSprite as well as use by Virtual Sprite Machine. BUGS SEE ALSO GetSprite() ChangeSprite() MoveSprite() 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) a0 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 (V38). SYNOPSIS GetAPen ( rp ) a0 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. BUGS NOTES SEE ALSO SetAPen() graphics/gfx.h graphics.library/GetBPen graphics.library/GetBPen NAME GetBPen -- Get the B Pen value for a RastPort (V38). SYNOPSIS GetBPen ( rp ) a0 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. BUGS NOTES SEE ALSO SetBPen() graphics/gfx.h graphics.library/GetColorMap graphics.library/GetColorMap NAME GetColorMap -- allocate and initialize Colormap SYNOPSIS cm = GetColorMap( entries ) d0 d0 struct ColorMap *GetColorMap( ULONG); FUNCTION Allocates, initializes and returns a pointer to a ColorMap data structure, later enabling calls to SetRGB4 and LoadRGB4 to load colors for a view port. The ColorTable pointer in the ColorMap structure points to a hardware specific colormap data structure. You should not count on it being anything you can understand. Use GetRGB4() to query it or SetRGB4CM to set it directly. INPUTS entries - number of entries for this colormap 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 result = GetDisplayInfoData(handle, buf, size, tagID, [ID]) D0 A0 A1 D0 D1 [D2] ULONG GetDisplayInfoData(DisplayInfoHandle, UBYTE *, ULONG, ULONG, ULONG); FUNCTION GetDisplayInfoData() fills a buffer with data meaningful to the DisplayInfoRecord pointed at by your valid handle. The data type that you are interested in is indicated by a tagID for that chunk. The types of tagged information that may be available include: DTAG_DISP: (DisplayInfo) - properties and availability information. DTAG_DIMS: (DimensionInfo) - default dimensions and overscan info. DTAG_MNTR: (MonitorInfo) - type, position, scanrate, and compatibility DTAG_NAME: (NameInfo) - a user friendly way to refer to this mode. INPUTS handle - displayinfo handle buf - pointer to destination buffer size - buffer size in bytes tagID - data chunk type ID - displayinfo identifier, optionally used if handle is NULL RESULT result - if positive, number of bytes actually transferred if zero, no information for ID was available BUGS SEE ALSO FindDisplayInfo(), NextDisplayInfo() graphics/displayinfo.h graphics.library/GetDrMd graphics.library/GetDrMd NAME GetDrMd -- Get the draw mode value for a RastPort (V38). SYNOPSIS GetDrMd ( rp ) a0 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. BUGS NOTES SEE ALSO SetDrMd() graphics/gfx.h graphics.library/GetGBuffers graphics.library/GetGBuffers NAME GetGBuffers -- Attempt to allocate ALL buffers of an entire AnimOb. SYNOPSIS status = GetGBuffers(anOb, rp, db) D0 A0 A1 D0 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/GetOPen graphics.library/GetOPen NAME GetOPen -- Get the O Pen value for a RastPort (V38). SYNOPSIS GetOPen ( rp ) a0 ULONG GetOPen(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. BUGS NOTES SEE ALSO SetOPen() graphics/gfx.h graphics.library/GetRGB32 graphics.library/GetRGB32 NAME GetRGB32 -- Set a series of color registers for this Viewport. (V38) SYNOPSIS GetRGB32( cm, firstcolor, ncolors, table ) a0 d0 d1 a1 void GetRGB32( struct ColorMap *, ULONG, ULONG, ULONG *); INPUTS cm = colormap firstcolor = the first color register to get ncolors = the number of color registers to set. table=a pointer to a series of 32-bit RGB triplets. RESULT The ULONG data pointed to by 'table' will be filled with the 32 bit fractional RGB values from the colormap. BUGS 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 ) d0 a0 d0 ULONG GetRGB4(struct ColorMap *, LONG); 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/GetSprite graphics.library/GetSprite NAME GetSprite -- Attempt to get a sprite for the simple sprite manager. SYNOPSIS Sprite_Number = GetSprite( sprite, pick ) d0 a0 d0 SHORT GetSprite( struct SimpleSprite *, SHORT ); 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 modeID = GetVPModeID( vp ) d0 a0 ULONG GetVPModeID( struct ViewPort *); 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/displayinfo.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); A0 A1 void GfxAssociate(VOID *, 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 ); a0 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 dissassociate 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 strucure 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 ); d0 a0 struct ExtendedNode *GfxLookUp( void *); FUNCTION Finds a special graphics extended data structure (if any) associated with the pointer to a data structure (eg: ViewExtra associated with a View structure). INPUTS pointer = a pointer to a data structure which may have an ExtendedNode associated with it (typically a View ). 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 result = GfxNew( node_type ); d0 d0 struct ExtendedNode *GfxNew( ULONG); FUNCTION Allocate a special graphics extended data structure (each of which begins with an ExtendedNode structure). The type of structure to be allocated is specified by the node_type identifier. INPUTS node_type = which type of graphics extended data structure to allocate. (see gfxnodes.h for identifier definitions.) 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/InitArea graphics.library/InitArea NAME InitArea -- Initialize vector collection matrix SYNOPSIS InitArea( areainfo, buffer, maxvectors ) a0 a1 d0 void InitArea(struct AreaInfo *, void *, SHORT); FUNCTION This function provides initialization for the vector collection matrix such that it has a size of (max vectors ). The size of the region pointed to by buffer (short pointer) should be five (5) times as large as maxvectors. This size is in bytes. Areafills done by using AreaMove, AreaDraw, and AreaEnd must have enough space allocated in this table to store all the points of the largest fill. AreaEllipse takes up two vectors for every call. If AreaMove/Draw/Ellipse detect too many vectors going into the buffer they will return -1. INPUTS areainfo - pointer to AreaInfo structure buffer - pointer to chunk of memory to collect vertices maxvectors - max number of vectors this buffer can hold 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 ) a0 d0 d1 d2 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 Flagsh 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) A0 A1 A2 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 the gel list head tail = pointer to the VSprite structure to be used as the gel list tail GInfo = pointer to the GelsInfo structure to be initialized 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) A0 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) A0 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 ) a1 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 InitTmpRas(tmpras, buffer, size) a0 a1 d0 void InitTmpRas( struct TmpRas *, void *, ULONG ); FUNCTION The area of memory pointed to by buffer is set up to be used by RastPort routines that may need to get some memory for intermediate operations in preparation to putting the graphics into the final BitMap. Tmpras is used to control the usage of buffer. INPUTS tmpras - pointer to a TmpRas structure to be linked into a RastPort buffer - pointer to a contguous piece of chip memory. size - size in bytes of buffer RESULT makes buffer available for users of RastPort 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 ) a1 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 ) a0 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. (V38) SYNOPSIS LoadRGB32( vp, c1, n, table ) a0 d0 d1 a1 void LoadRGB32( struct ViewPort *, ULONG, ULONG, ULONG *); INPUTS vp = viewport c1 = the first color register to set n = the number of color registers to set. table=a pointer to a series of 32-bit RGB triplets. RESULT The selected color registers are changed to match your specs. Channels other than RGB will not be modified. 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. Do not set more colors then are present in the colormap! SEE ALSO LoadRGB4() GetColorMap() GetRGB32() SetRGB32CM() graphics/view.h graphics.library/LoadRGB4 graphics.library/LoadRGB4 NAME LoadRGB4 -- Load RGB color values from table. SYNOPSIS LoadRGB4( vp, colors , count ) a0 a1 d0:16 void LoadRGB4( struct ViewPort *, UWORD *, WORD); FUNCTION load the count words of the colormap from table starting at entry 0. INPUTS vp - pointer to ViewPort, whose colors you wish to change colors - pointer to table of RGB values set up as an array of USHORTS background-- 0x0RGB color1 -- 0x0RGB color2 -- 0x0RGB etc. UWORD per value. The colors are interpreted as 15 = maximum intensity. 0 = minimum intensity. count = number of UWORDs in the table to load into the colormap starting at color 0(background) and proceeding to the next higher color number RESULTS The ViewPort should have a pointer to a valid ColorMap to store the colors in. Updates the hardware copperlist to reflect the new colors. Updates the intermediate copperlist with the new colors. BUGS 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 ) A1 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/LockLayerRom graphics.library/LockLayerRom NAME LockLayerRom -- Lock Layer structure by rom(gfx lib) code. SYNOPSIS LockLayerRom( layer ) a5 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. 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 MakeVPort( view, viewport ) a0 a1 void MakeVPort( struct View *, struct 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 BUGS 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 to see if a DisplayID isn't available. (V36) SYNOPSIS error = ModeNotAvailable( modeID ) d0 d0 ULONG ModeNotAvailable( ULONG); FUNCTION returns an error code, indicating why this modeID is not available, or NULL if there is no reason known why this mode should not be there. INPUTS modeID -- a 32 bit DisplayInfoRecord identifier. 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 ULONG return values from this function are a proper superset of the DisplayInfo.NotAvailable field (defined in graphics/displayinfo.h). BUGS SEE ALSO graphics/displayinfo.h, GetVPModeID() graphics.library/Move graphics.library/Move NAME Move -- Move graphics pen position. SYNOPSIS Move( rp, x, y) a1 d0:16 d1:16 void Move( struct RastPort *, SHORT, SHORT ); FUNCTION Move graphics pen position to (x,y) relative to upper left (0,0) of RastPort. This sets the starting point for subsequent Draw() and Text() calls. INPUTS rp - pointer to a RastPort structure x,y - point in the RastPort 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) A0 A1 D0 D1 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. SEE ALSO FreeSprite() ChangeSprite() GetSprite() graphics/sprite.h graphics.library/MrgCop graphics.library/MrgCop NAME MrgCop -- Merge together coprocessor instructions. SYNOPSIS MrgCop( View ) A1 void MrgCop( struct 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(). 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() d0 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 next_ID = NextDisplayInfo(last_ID) D0 D0 ULONG NextDisplayInfo(ULONG); FUNCTION The basic iteration function with which to find all records in the graphics database. Using each ID in succession, you can then call FindDisplayInfo() to obtain the handle associated with each ID. Each ID is a 32-bit Key which uniquely identifies one record. The INVALID_ID is special, and indicates the end-of-list. INPUTS last_ID - previous displayinfo identifier or INVALID_ID if beginning iteration. RESULT next_ID - subsequent displayinfo identifier or INVALID_ID if no more records. BUGS SEE ALSO FindDisplayInfo(), GetDisplayInfoData() graphics/displayinfo.h graphics.library/OpenFont graphics.library/OpenFont NAME OpenFont -- Get a pointer to a system font. SYNOPSIS font = OpenFont(textAttr) D0 A0 struct TextFont *OpenFont(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. SEE ALSO CloseFont() SetFont() diskfont.library/OpenDiskFont graphics/text.h graphics.library/OpenMonitor graphics.library/OpenMonitor NAME OpenMonitor -- open a named MonitorSpec (V36) SYNOPSIS mspc = OpenMonitor( monitor_name , display_id) d0 a1 d0 struct MonitorSpec *OpenMonitor( char *, ULONG ); FUNCTION Locate and open a named MonitorSpec. INPUTS monitor_name - a pointer to a null terminated string. display_id - an optional 32 bit monitor/mode identifier RESULTS mspc - a pointer to an open MonitorSpec structure. NULL if MonitorSpec could not be opened. NOTE if monitor_name is non-NULL, the monitor will be opened by name. if monitor_name is NULL the monitor will be opened by optional ID. if both monitor_name and display_id are NULL returns default monitor. 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) d0 a0 a1 BOOL OrRectRegion( struct Region *, 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) d0 a0 a1 BOOL OrRegionRegion( 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() 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/PickBestColor graphics.library/PickBestColor NAME Search for the closest color match, or allocate a new one. (V38) SYNOPSIS color | -1 =PickBestColor( cm, R, G, B, Precision, MaxColor) a0 d1 d2 d3 d4 d5 ULONG PickBestColor( struct ColorMap *, ULONG, ULONG, ULONG, ULONG, ULONG ); 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) Precision = the relative amount of color resolution desired. MaxColor = the largest color value to examine. -1 means any valid one. RESULT 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. A -1 will be returned if no sharable palette entries are available. BUGS NOTES If this call succceeds, then you must call FreePalette() when you are done with the color. The precision value should be either PRECISION_IMAGE (for colorful images), PRECISION_ICON (for somewhat less precise images), and ..(I DON'T KNOW)!!! The error metric used for PickBestColor() is based on the magnitude squared between the two RGB values, scaled by the percentage of free entries. SEE ALSO GetColorMap() AllocPalette() FreePalette() SearchColorMap() graphics.library/PolyDraw graphics.library/PolyDraw NAME PolyDraw -- Draw lines from table of (x,y) values. SYNOPSIS PolyDraw( rp, count , array ) a1 d0 a0 void PolyDraw( struct RastPort *, WORD, 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 ) a1 void QBlit( struct bltnode * ); FUNCTION Link a request for the use of the blitter to the end of the current blitter queue. The pointer bp points to a blit structure containing, among other things, the link information, and the address of your routine which is to be called when the blitter queue finally gets around to this specific request. When your routine is called, you are in control of the blitter ... it is not busy with anyone else's requests. This means that you can directly specify the register contents and start the blitter. See the description of the blit structure and the uses of QBlit in the section titled Graphics Support in the OS Kernel Manual. Your code must be written to run either in supervisor or user mode on the 68000. INPUTS bp - pointer to a blit structure 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. BUGS 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 ) a1 void QBSBlit( struct bltnode * ); FUNCTION Call a user routine for use of the blitter, enqueued separately from the QBlit queue. Calls the user routine contained in the blit structure when the video beam is located at a specified position onscreen. Useful when you are trying to blit into a visible part of the screen and wish to perform the data move while the beam is not trying to display that same area. (prevents showing part of an old display and part of a new display simultaneously). Blitter requests on the QBSBlit queue take precedence over those on the regular blitter queue. The beam position is specified the blitnode. INPUTS bsp - pointer to a blit structure. See description in the Graphics Support section of the manual for more info. 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. BUGS Not very smart when getting blits from different tasks. They all get put in same queue so there are unfortunately some interdependencies with the beam syncing. 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 penno = ReadPixel( rp, x, y ) d0 a1 d0:16 d1:16 LONG ReadPixel( struct RastPort *, SHORT, SHORT ); FUNCTION Combine the bits from each of the bit-planes used to describe a particular RastPort into the pen number selector which that bit combination normally forms for the system hardware selection of pixel color. INPUTS rp - pointer to a RastPort structure (x,y) a point in the RastPort 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. BUGS SEE ALSO WritePixel() graphics/rastport.h 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 count = ReadPixelArray8(rp,xstart,ystart,xstop,ystop,array,temprp) D0 A0 D0:16 D1:16 D2:16 D3:16 A2 A1 LONG ReadPixelArray8(struct RastPort *, UWORD, UWORD, UWORD, UWORD, UBYTE *, struct RastPort *); 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->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 BUGS SEE ALSO ReadPixel() ReadPixelLine8() graphics/rastport.h 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 count = ReadPixelLine8(rp,xstart,ystart,width,array,temprp) D0 A0 D0:16 D1:16 D2 A2 A1 LONG ReadPixelLine8(struct RastPort *, UWORD, UWORD, UWORD, UBYTE *, struct RastPort * ); 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->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 BUGS SEE ALSO ReadPixel() graphics/rastport.h graphics.library/RectFill graphics.library/RectFill NAME RectFill -- Fill a rectangular region in a RastPort. SYNOPSIS RectFill( rp, xmin, ymin, xmax, ymax) a1 d0:16 d1:16 d2:16 d3:16 void RectFill( struct RastPort *, SHORT, SHORT, SHORT, SHORT ); FUNCTION Fills the rectangular region specified by the parameters with the chosen pen colors, areafill pattern, and drawing mode. If no areafill pattern is specified, fill the rectangular region with the FgPen color, taking into account the drawing mode. INPUTS rp - pointer to a RastPort structure (xmin,ymin) (xmax,ymax) are the coordinates of the upper left corner and the lower right corner, respectively, of the rectangle. NOTE The following relation MUST be true: (xmax >= xmin) and (ymax >= ymin) BUGS Complement mode with FgPen complements all bitplanes. SEE ALSO AreaEnd() graphics/rastport.h 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) A1 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) A0 A1 A2 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) A0 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) D0 D0 D1 D2 UWORD ScalerDiv(UWORD, UWORD, UWORD); FUNCTION Calculate the expression (factor*numerator/denominator) such that the result is the same as the width of the destination result of BitMapScale when the factor here is the width of the source, and the numerator and denominator are the XDestFactor and XSrcFactor for BitMapScale. INPUTS factor - a number in the range 0..16383 numerator, denominator - numbers in the range 1..16383 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) A1 D0 D1 D2 D3 D4 D5 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 & LAYER_REFRESH to see if there is any damage in the damage list. If there is you should call the appropriate BeginRefresh(Intuition) or BeginUpdate(graphics) routine sequence. INPUTS rp - pointer to a RastPort structure dx,dy are integers that may be postive, zero, or negative xmin,ymin - upper left of bounding rectangle xmax,ymax - lower right of bounding rectangle EXAMPLE ScrollRaster(rp,0,1) /* shift raster up by one row */ ScrollRaster(rp,-1,-1) /* shift raster down and to the right by 1 pixel BUGS In 1.2/V1.3 if you ScrollRaster a SUPERBITMAP exactly left or right, and there is no TmpRas attached to the RastPort, the system will allocate one for you, but will never free it or record its location. This bug has been fixed for V1.4. The workaround for 1.2/1.3 is to attach a valid TmpRas of size at least MAXBYTESPERROW to the RastPort before the call. Begining with V1.4 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 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 ) a0 struct ViewPort *vp; FUNCTION After the programmer has adjusted the Offset values in the RasInfo structures of ViewPort, change the the copper lists to reflect the the Scroll positions. Changing the BitMap ptr in RasInfo and not changing the the Offsets will effect a double buffering affect. INPUTS vp - pointer to a ViewPort structure that is currently be displayed. RESULTS modifies hardware and intermediate copperlists to reflect new RasInfo BUGS pokes not fast enough to avoid some visible hashing of display SEE ALSO MakeVPort() MrgCop() LoadView() graphics/view.h graphics.library/SearchColorMap graphics.library/SearchColorMap NAME Search for a close color match, using a user-supplied procedure. (V38) SYNOPSIS color | -1 =SearchColorMap( cm, proc, R, G, B, MaxError, MaxColor) a0 a1 d1 d2 d3 d4 d5 ULONG SearchColorMap( struct ColorMap *, (*int)(), ULONG, ULONG, ULONG , ULONG, ULONG ); INPUTS cm = colormap proc = the procedure to call for each color candidate. R = red level (32 bit left justified fraction) G = green level (32 bit left justified fraction) B = blue level (32 bit left justified fraction) MaxError = the maximum permissible error value for a match. MaxColor = the maximum color index that you want. -1 for any valid one. RESULT Your procedure will be called for each shared entry in the colormap. Your procedure will be passed the RGB values supplied to the call in d1/d2/d3, and the RGB values from the color map in d5/d6/d7. Your function should return the error value in d0. Your function will be called until it returns a zero, or until there are no more colors to examine. If no match was found with a return of less then the value passed in the MaxError parameter, then a new one will be allocated if available, and its RGB values set to the ones passed. This color will be returned. If no palette entry was found within the error tolerance, and there are none available for allocation, then the closest one found will be returned. If one was found within the tolerance passed by the application, then it will be returned, and its reference count will be bumped. If there are no sharable palette entries available, then -1 will be returned . BUGS NOTES If this call succceeds, then you must call FreePalette() when you are done with the color. 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. For most applications, you should call PickBestColor(), and not this function. This is provided for an application which might want to optimize its palette error metrics differently. PickBestColor() also works better in shared screens, because it changes its tolerances based on the amount of space free in the palette. SEE ALSO GetColorMap() PickBestColor() FreePalette() AllocPalette() graphics.library/SetABPenDrMd graphics.library/SetABPenDrMd NAME SetABPenDrMd -- Set pen colors and draw mode for a RastPort. SYNOPSIS SetABPenDrMd( rp, apen, bpen, mode ) a1 d0 d1 d2 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 ) a1 d0 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 ) a1 d0 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/SetCollision graphics.library/SetCollision NAME SetCollision -- Set a pointer to a user collision routine. SYNOPSIS SetCollision(num, routine, GInfo) D0 A0 A1 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 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 ) a1 d0:8 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 dependant 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) A1 A0 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 these one of these font variants will cause the system to modify your font to make it acceptable. BUGS Calling SetFont() on in-code TextFonts (ie fonts not OpenFont()ed) will result in a loss of 24 bytes from the system as of V36. This can be resolved by calling StripFont(). SEE ALSO OpenFont() StripFont() diskfont.library/OpenDiskFont() graphics/text.h 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/SetRast graphics.library/SetRast NAME SetRast - Set an entire drawing area to a specified color. SYNOPSIS SetRast( rp, pen ) a1 d0 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. (V38) SYNOPSIS SetRGB32( vp, n, r, g, b) a0 d0 d1 d2 d3 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() graphics/view.h graphics.library/SetRGB4 graphics.library/SetRGB4 NAME SetRGB4 -- Set one color register for this viewport. SYNOPSIS SetRGB4( vp, n, r, g, b) a0 d0 d1:4 d2:4 d3:4 void SetRGB4( struct ViewPort *, SHORT, UBYTE, UBYTE, UBYTE ); FUNCTION Change the color look up table so that this viewport displays the color (r,g,b) for pen number n. INPUTS vp - pointer to viewport structure n - the color number (range from 0 to 31) r - red level (0-15) g - green level (0-15) b - blue level (0-15) 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 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) a0 d0 d1:4 d2:4 d3:4 void SetRGB4CM( struct ColorMap *, SHORT, UBYTE, UBYTE, UBYTE ); INPUTS cm = colormap n = the number of the color register to set. Ranges from 0 to 31 on current amiga displays. r = red level (0-15) g = green level (0-15) b = blue level (0-15) 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/SetSoftStyle graphics.library/SetSoftStyle NAME SetSoftStyle -- Set the soft style of the current font. SYNOPSIS newStyle = SetSoftStyle(rp, style, enable) D0 A1 D0 D1 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/SortGList graphics.library/SortGList NAME SortGList -- Sort the current gel list, ordering its y,x coordinates. SYNOPSIS SortGList(rp) A1 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) A0 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 ) a0 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) A1 A0 D0-0:16 void Text(struct RastPort *, STRPTR, WORD); FUNCTION This graphics function writes printable text characters to the specified RastPort at the current position. No control meaning is applied to any of the characters, thus only text on the current line is output. The current position in the RastPort is updated to the next character position. If the characters displayed run past the RastPort boundary, the current position is truncated to the boundary, and thus does not equal the old position plus the text length. INPUTS rp - a pointer to the RastPort which describes where the text is to be output string - the address of string to output length - the number of characters in the string. If zero, there are no characters to be output. NOTES o This function may use the blitter. o Changing the text direction with RastPort->TxSpacing is not supported. BUGS For V34 and earlier: o The maximum string length (in pixels) is limited to (1024 - 16 = 1008) pixels wide. o A text string whose last character(s) have a tf_CharLoc size component that extends to the right of the rightmost of the initial and final CP positions will be (inappropriately) clipped. SEE ALSO 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) A1 A0 D0:16 A2 void textExtent(struct RastPort *, STRPTR, WORD, 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 rectanangle this would render into. 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, D0 A1 A0 D0 A2 constrainingExtent, strDirection, A3 D1 constrainingBitWidth, constrainingBitHeight) D2 D3 ULONG TextFit(struct RastPort *, STRPTR, UWORD, struct TextExtent *, 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. 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) D0 A1 A0 D0:16 WORD TextLength(struct RastPort *, STRPTR, WORD); FUNCTION This graphics function determines the length that text data would occupy if output to the specified RastPort with the current attributes. The length is specified as the number of raster dots: to determine what the current position would be after a Write() using this string, add the length to cp_x (cp_y is unchanged by Write()). Use the newer TextExtent() to get more information. INPUTS rp - a pointer to the RastPort which describes where the text attributes reside. string - the address of string to determine the length of count - the string length. If zero, there are no characters in the string. RESULTS length - the number of pixels in x this text would occupy, not including any negative kerning that may take place at the beginning of the text string, nor taking into account the effects of any clipping that may take place. NOTES Prior to V36, the result length occupied only the low word of d0 and was not sign extended into the high word. BUGS A length that would overflow single word arithmatic is not calculated correctly. SEE ALSO TextExtent() Text() TextFit() graphics/text.h graphics/rastport.h graphics.library/UnlockLayerRom graphics.library/UnlockLayerRom NAME UnlockLayerRom -- Unlock Layer structure by rom(gfx lib) code. SYNOPSIS UnlockLayerRom( layer ) a5 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() d0 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 error = VideoControl( cm , tags ) d0 a0 a1 ULONG VideoControl( struct ColorMap *, struct TagItem * ); 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. VTAG_PF2_BASE [_SET | _GET] -- set/get color base for second playfield. VTAG_SPODD_BASE [_SET | _GET] -- set/get color base for odd sprites. VTAG_SPEVEN_BASE [_SET | _GET] -- set/get color base for even sprites. VTAG_BORDERSPRITE [_SET | _GET] -- on/off/inquire sprites in borders 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 # 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 videocontol taglist to be processed in "batch" mode, that is, at the next MakeVPort() for the ColorMap->cm_vp; you may intall 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 occured 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. 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. This routine does not use any the CPU registers. do/d1/a0/a1 are preserved by this routine. It may change the condition codes though. BUGS When examining bits with the CPU right after a blit, or when freeeing temorary 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 systen 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 systen 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 desination 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 ) a0 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 interupt 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/WeighTAMatch graphics.library/WeighTAMatch NAME WeighTAMatch -- Get a measure of how well two fonts match. (V36) SYNOPSIS weight = WeighTAMatch(reqTextAttr, targetTextAttr, targetTags) D0 A0 A1 A2 WORD WeighTAMatch(struct TTextAttr *, struct TextAttr *, struct TagItem *); FUNCTION This function provides a metric to describe how well two fonts match. This metric ranges from MAXFONTMATCHWEIGHT (perfect match) through lower positive numbers to zero (unsuitable match). INPUTS reqTextAttr - the text attributes requested. targetTextAttr - the text attributes of a potential match. targetTags - tags describing the extended target attributes, or zero if not available. The [t]ta_Name fields of the [T]TextAttr structures are not used. The tags affect the weight only when both a) the reqTextAttr has the FSF_TAGGED bit set in ta_Style, and b) targetTags is not zero. To fairly compare two different weights, the inclusion or exclusion of tags in the weighing must be the same for both. RESULTS weight -- a positive weight describes suitable matches, in increasing desirability. MAXFONTMATCHWEIGHT is a perfect match. A zero weight is an unsuitable match. SEE ALSO OpenFont() graphics.library/WritePixel graphics.library/WritePixel NAME WritePixel -- Change the pen num of one specific pixel in a specified RastPort. SYNOPSIS error = WritePixel( rp, x, y) d0 a1 D0 D1 LONG WritePixel( struct RastPort *, SHORT, SHORT ); FUNCTION Changes the pen number of the selected pixel in the specified RastPort to that currently specified by PenA, the primary drawing pen. Obeys minterms in RastPort. INPUTS rp - a pointer to the RastPort structure (x,y) - point within the RastPort at which the selected pixel is located. RESULT error = 0 if pixel succesfully changed = -1 if (x,y) is outside the RastPort BUGS SEE ALSO ReadPixel() graphics/rastport.h 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 count = WritePixelArray8(rp,xstart,ystart,xstop,ystop,array,temprp) D0 A0 D0:16 D1:16 D2:16 D3:16 A2 A1 LONG WritePixelArray8(struct RastPort *, UWORD, UWORD, UWORD, UWORD, UBYTE *, struct RastPort *); 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 == NULL, temporary memory allocated for temprp->BitMap with Rows set == 1, temprp->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 NOTE xstop must be >= xstart ystop must be >= ystart BUGS SEE ALSO WritePixel() graphics/rastport.h 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 count = WritePixelLine8(rp,xstart,ystart,width,array,temprp) D0 A0 D0:16 D1:16 D2 A2 A1 LONG WritePixelLine8(struct RastPort *, UWORD, UWORD, UWORD, UBYTE *, struct RastPort *); 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->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 NOTE width must be non negative BUGS 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) d0 a0 a1 BOOL XorrectRegion( struct Region *, 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) d0 a0 a1 BOOL XorRegionRegion( 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 graphics.library/WritePixel graphics.library/WritePixel NAME WritePixel -- Change the pen num of one specific pixel in a specified RastPort. SYNOPSIS error = WritePixel( rp, x, y) d0 a1 D0 D1 LONG WritePixel( struct RastPort *, SHORT, SHORT ); FUNCTION Changes the pen number of the selected pixel in the specified RastPort to that currently specified by PenA, the primary drawing pen. Obeys minterms in RastPort. INPUTS rp - a pointer to the RastPort structure (x,y) - point within the RastPort at which the selected pixel is located. RESULT error = 0 if pixel succesfully changed = -1 if (x,y) is outside the RastPort BUGS SEE ALSO ReadPixel() graphics/rastport.h graphics.library/LoadRGB32 graphics.library/LoadRGB32 NAME LoadRGB32 -- Load RGB color values from table. SYNOPSIS LoadRGB32( vp, colors , count, firstcolor ) a0 a1 d0:16 d1 void LoadRGB32( struct ViewPort *, UWORD *, WORD, WORD); FUNCTION load the count words of the colormap from table starting at entry "firscolor". INPUTS vp - pointer to ViewPort, whose colors you wish to change colors - pointer to table of RGB values set up as an array of ULONG color triplets. firstcolor-- 0xRRRRRRRR, 0xGGGGGGGG, 0xBBBBBBBB firstcolor+1-- 0xRRRRRRRR, 0xGGGGGGGG, 0xBBBBBBBB firstcolor+2-- 0xRRRRRRRR, 0xGGGGGGGG, 0xBBBBBBBB etc. 3 ULONGs per value. count = number of ULONG triplets in the table to load into the colormap starting at firstcolor and proceeding to higher color numbers. RESULTS The ViewPort should have a pointer to a valid ColorMap to store the colors in. Updates the hardware copperlist to reflect the new colors. Updates the intermediate copperlist with the new colors. BUGS SEE ALSO SetRGB32() GetRGB32() GetColorMap() graphics/view.h