CAUTION: This is the least stable part of AGT currently - most likely to see changes. It could take time to settle down.

The AGT engine has been designed for quickly prototyping 2D games at 8MHz and some tradeoffs have been made between efficiency, ease of use and customization.

One important design choice was to avoid the need for direct drawing calls for the majority of displayed content. There are several reasons for this choice but perhaps most importantly, it is fundamental to maintaining good performance while still being able to quickly write game-level code in C/C++. Rapid results with good performance is the main rationale for AGT after all.

Having said that - there are always exceptions. Some support for direct drawing calls is therefore provided to help deal with the odd cases - anything that turns out to be a poor fit with the entity/proxy approach. Just be aware that calling functions incurs hidden costs and any logic/looping placed around those calls will quickly mount up if adopted as the primary way of doing things... its nearly always better to find clever ways of using the entity drawchain where possible.

The following functions are found in agtsys/spritelib.h

AGT_STF_ISSprDrawClipped

AGT_STF_ISSprDrawUnClipped

Draws a single frame from software sprite format type .IMS on STF platform at given framebuffer coordinates. Drawcontext provides clipping window, vscroll loopback offset and framebuffer address.

AGT_BLiT_IMSprInit

Prepare drawing for a sequence of sprites in format .IMS

AGT_BLiT_IMSprDrawClipped

AGT_BLiT_IMSprDrawUnClipped

Draws a single frame of sprite format type .IMS at given framebuffer coordinates. Drawcontext provides clipping window, vscroll loopback offset and framebuffer address.

AGT_BLiT_EMSprInit

Prepare drawing for a sequence of sprites in format .EMS

AGT_BLiT_EMSprDrawClipped

AGT_BLiT_EMSprDrawUnClipped

Draws a single frame of sprite format type .EMS at given framebuffer coordinates. Drawcontext provides clipping window, vscroll loopback offset and framebuffer address.

AGT_BLiT_EMXSprInit

Prepare drawing for a sequence of sprites in format .EMX

AGT_BLiT_EMXSprDrawClipped

AGT_BLiT_EMXSprDrawUnClipped

Draws a single frame of sprite format type .EMX at given framebuffer coordinates. Drawcontext provides clipping window, vscroll loopback offset and framebuffer address.

AGT_BLiT_SlabSetupOnce

Prepares slab drawing system on startup. Needs called once only, and before any slabs are drawn.

AGT_BLiT_SlabDraw

Draws a single frame of slab format type .SLS at given framebuffer coordinates.

AGT_SlabDirtyRegion

Restores/clears a region of background pixels with shape defined by a single frame from slab format .SLR, at given framebuffer coordinates. Intended for clearing slabs, but can be used to restore any irregular outline after direct manipulation of the framebuffer.

AGT_MarkDirtyRectangle

Emits a background-restore record for any rectangular region of background pixels at given framebuffer coordinates. Can be used on all platforms.

Framebuffer Access

For all direct drawing functions, framebuffer coordinates must be offset from game world coordinates in certain scrolling modes using 'snapping adjustments', to compensate for invisible 'loopback' buffer hops.

Loopback hops occur with any kind of vertical scrolling (including 4- or 8-way scroll). The required snapping adjustments are provided by the drawcontext object, which is obtained from the playfield-arena (world) workbuffer. See examples for details.

For custom-written drawing functions, the translation from world coordinates to framebuffer address will be properly documented soon. Generally speaking it involves use of the drawcontext object to obtain a scanline index for the current playfield workbuffer, after the necessary snapping adjustments have been made. The scanline index provides the line offset. The rest is a typical framebuffer address calculation.

To obtain the drawcontext before calling draw functions, obtain it from the active arena by calling: myworld.get_context(drawcontext, /*field=*/0, /*viswidth=*/320+16, /*visheight=*/240)

Note that +16 should be incorporated when STE horizontal hardware scrolling is actively used since the effective visible width is 336 when taking scroll into account. An incorrect value will lead to incorrect sprite clipping.