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