EntityDraw

The entity_t::drawtype field is of type EntityDraw. It determines the drawing function for that entity.

There are several EntityDraw types intended for different situations. Each drawtype expects a specific kind of asset to be attached to the entity_t::passet field.

The entity_t::passet field is initially NULL (0) in the dictionary but should be assigned manually after asset loading and before any entities get spawned. The asset pointer will then be duplicated from the dictionary into any new spawns. Asset assignment is done using calls to one of several EntityDefAsset functions for the required asset type.

EntityDraw_NONE

The object is invisible. It can still be ticked and interact, but won't be drawn. The viewport entity uses this mode. No asset is required.

EntityDraw_IMSPR

This configures the entity to draw using interleaved-planar, masked sprites (.IMS format). When generated for STE, these are stored as 5 bitplanes and using the Blitter in 2-pass planar mode. It is also used for STF/non-blitter sprites when cut without mask (storing only 4 planes).

This format is compact to store, very quick to cut (via agtcut) and has few size restrictions. It is however the slowest sprite method to draw, requiring 2x RMW memory passes per bitplane with Blitter and requires runtime shifting on STF.

Full viewport clipping is supported.

Background restore (sprite clearing) is automatic.

.IMS files are produced with agtcut using '--cutmode imspr'

Note: While IMSPR is the slowest sprite format, it is possible to cut & reconstruct large non-rectangular sprites from smaller rectangles by preparing the art in such a way that each 'piece' is stored in a separate animation frame, and multiple entities are used to reconstruct the shape using different animation indexes (but sharing the same AI and coordinates). The x,y offsets embedded in the sprite data by agtcut will take care of the rest. This allows IMSPR to be used more cheaply in some situations and also works with the other sprite formats if the pieces are small enough. A demo of this will be added soon.

EntityDraw_EMSPR

This configures the entity to draw using preshifted [E]nd[M]ask sprites (.EMS format) using Blitter in copy mode using a single pass per scanline. These are faster to draw than IMSPR mode, but consume more ram and are restricted to 32 pixels wide (maximum).

This is probably the best all-round sprite method.

Full viewport clipping is supported.

Background restore (sprite clearing) is automatic.

.EMS files are produced with agtcut using '--cutmode emspr'

EntityDraw_EMXSPR

A highly optimized version of EMSPR (.EMX format). It is very slow to cut (via agtcut) and requires a more ram to store, especially for animations. It produces custom 68k Blitter code for each individual sprite frame.

This is best used for non-animating sprites up to 32 pixels wide and for small things like bullets requiring a low constant overhead. It can still be used for smaller animating sprites but too memory-expensive for large animations.

Full viewport clipping is supported.

Background restore (sprite clearing) is automatic.

.EMX files are produced with agtcut using '--cutmode emxspr'

EntityDraw_SLAB

Like EMSPR/EMXSPR the SLAB mode draws masked shapes using single-pass copy mode with the Blitter (.SLS/.SLR format). There two main benefit over the other modes:

1. SLAB objects can be up to 256 pixels wide with EMSPR efficiency.
2. You don't pay drawing or storage cost for transparent pixels outside of the solid perimeter.

The only unusual restriction for SLABS is not allowing holes between the left/right edge of the filled area. It is not unlike a solid-filled polygon in this respect. It is effectively a solid shape with an irregular outline, functioning like a mask.

Slabs provide a relatively fast way to draw rectangle graphics on pixel boundaries - much faster than an equivalent sized sprite due to the lack of internal masking.

For Slabs, a simpler outline results in faster filling, since less state needs updated for similarly masked scanlines. A rectangle is the cheapest shape for this reason (see above). However Slabs can save even more time for very irregular shapes since the transparent parts outside the shape are not written at all.

Asset binding is slightly more complicated than for sprites. Typically two assets are required, bound together using the sls_pair struct (this wraps a pair of slab asset pointers into a single asset). Both assets define the shape of the slab, but one is a high resolution shape for drawing (.SLS) while the other is a simpler approximation for efficient background-restore operations (.SLR).

Both of these formats are emitted by agtcut using different cutmodes (They are technically the same file format but content is different). The .SLR asset is optional - drawing can proceed with just the .SLS file bound to the sls_pair, but will not be automatically cleared between frames (it will leave a trail as it moves).

Note: A slab can still be cleared manually via AGT_SlabDirtyRegion passing the .SLR asset, or with simple calls to AGT_MarkDirtyRectangle but these in most cases will be less efficient than binding an .SLR shape to the entity for automatic clearing, especially if the shape is very irregular.

Viewport clipping is supported on Y axis only! No X clipping provided. Beware.

Note: Later revisions of AGT will allow arbitrarily wide display margins so large unclipped sprites can still be hidden in the border. Currently the margin is minimal and other sprite methods are fully clipped.

Background restore (sprite clearing) is automatic only if matching .SLR is bound along with the .SLS asset.

.SLS files are produced with agtcut using '--cutmode slabs'

.SLR files are produced with agtcut using '--cutmode slabrestore'

EntityDraw_RFILL

Fills the entire entity hitbox (rx,ry -> rx+sx, ry+sy) with a fixed colour. Mainly useful for debugging collisions and related. Might have other uses.

EntityDraw_CUSTOM (todo)

This allows the plugging in of user-defined draw functions, for specific effects. e.g laser beams, pattern fills, circles or whatever else might be useful.

• this feature is partially implemented but not yet exposed for use - there are no working examples yet.