A VRAM accessor for drawing graphics in the BG1 mode. More...

#include <sifteo/video/bg1.h>

Public Member Functions
CubeID	cube () const
	Return the CubeID associated with this drawable.

void	erase (uint16_t index=0)
	Erase mode-specific VRAM, filling the BG1 buffer with the specified absolute tile index value, clearing the allocation mask, and resetting the panning registers.

void	erase (const PinnedAssetImage &image)
	Erase mode-specific VRAM, filling the BG1 buffer with the first tile from the specified PinnedAssetImage, clearing the allocation mask, and resetting the panning registers.

void	eraseMask ()
	Erase just the allocation mask. All tiles will now be unallocated, and BG1 will be fully transparent. More...

void	fill (uint16_t index=0)
	Fill all BG1 tiles with the specified absolute index, without modifying the allocation mask.

void	fill (const PinnedAssetImage &image)
	Fill all BG1 tiles with first tile from the specified PinnedAssetImage, without modifying the allocation mask.

void	fillMask (UInt2 topLeft, UInt2 size)
	This is a specialized alternative to setMask(), for cases where each row of BG1 has a single contiguous span of tiles in it. More...

Int2	getPanning () const
	Retrieve the last value set by setPanning(). .

void	image (UInt2 pos, const AssetImage &image, unsigned frame=0)
	Draw a full AssetImage frame, with its top-left corner at the specified location. More...

void	image (UInt2 destXY, UInt2 size, const AssetImage &image, UInt2 srcXY, unsigned frame=0)
	Draw part of an AssetImage frame, with its top-left corner at the specified location. More...

void	maskedImage (const AssetImage &image, const PinnedAssetImage &key, unsigned frame=0)
	Draw an AssetImage, automatically allocating tiles on the BG1 mask. More...

void	maskedImage (UInt2 size, const AssetImage &image, const PinnedAssetImage &key, UInt2 srcXY, unsigned frame=0)
	Draw part of an AssetImage, automatically allocating tiles on the BG1 mask. More...

void	plot (unsigned locationIndex, uint16_t tileIndex)
	Plot a single tile, by absolute tile index, at a specific location in the 144-tile array.

void	setMask (const BG1Mask &mask)
	Change the tile allocation bitmap. More...

void	setPanning (Int2 pixels)
	Change the hardware pixel-panning origin for this mode. More...

void	span (unsigned locationIndex, unsigned count, unsigned tileIndex)
	Plot a horizontal span of tiles in consecutively allocated locations in the BG1 tile array. More...

void	text (Int2 topLeft, const AssetImage &font, const char *str, char firstChar= ' ')
	Draw text, using an AssetImage as a fixed width font. More...

_SYSVideoBuffer &	videoBuffer ()
	Return the VideoBuffer associated with this drawable.

Static Public Member Functions
static unsigned	numTiles ()
	Returns the maximum number of allcoated tiles.

static unsigned	pixelHeight ()
	Return the height, in pixel, of this mode.

static UInt2	pixelSize ()
	Return the size of this mode as a vector, in pixels.

static unsigned	pixelWidth ()
	Return the width, in pixels, of this mode.

static unsigned	tileHeight ()
	Return the height, in tiles, of this mode.

static UInt2	tileSize ()
	Return the size of this mode as a vector, in tiles.

static unsigned	tileWidth ()
	Return the width, in tiles, of this mode.

Detailed Description

A VRAM accessor for drawing graphics in the BG1 mode.

BG1 is an overlay layer, existing above BG0 and all Sprites. It consists of a virtual 16x16-tile grid which does not wrap. Tiles beyond the edges of this grid are treated as transparent.

Because of video memory size limitations, the hardware cannot keep use every tile in this 16x16 grid simultaneously. Up to 144 tiles are available, which is only enough to cover 56% of the full screen.

This layer is represented by a packed array of 144 tile indices, plus a separate 16x16-bit bitmap which tracks which tiles in the virtual grid have been allocated. Allocated tiles are mapped to locations in the 144-tile array, by walking top-to-bottom left-to-right and allocating a tile any time there's a '1' bit in the allocation bitmap. Unallocated tiles are rendered as fully transparent.

Member Function Documentation

void Sifteo::BG1Drawable::eraseMask ( )

inline

Erase just the allocation mask. All tiles will now be unallocated, and BG1 will be fully transparent.

Changes to the bitmap will affect the way the tile array is interpreted, causing already-drawn tiles to appear to shift. Normally you should only change the allocation map when the BG1 mode isn't currently active, or when you've ensured that the cube isn't currently rendering asynchronously.

Because of this, we automatically do a System::finish() so we can ensure nobody is still using the old mask.

void Sifteo::BG1Drawable::fillMask	(	UInt2	topLeft,
		UInt2	size
	)

inline

This is a specialized alternative to setMask(), for cases where each row of BG1 has a single contiguous span of tiles in it.

This effectively draws a rectangle on the BG1 mask, leaving rows above and below the rectangle untouched, but clearing all tiles to either side of the rectangle.

If this doesn't sound like your BG1 use-case, the more general BG1Mask utility can help you construct a mask either at compile-time or runtime.

Changes to the bitmap will affect the way the tile array is interpreted, causing already-drawn tiles to appear to shift. Normally you should only change the allocation map when the BG1 mode isn't currently active, or when you've ensured that the cube isn't currently rendering asynchronously.

Because of this, we automatically do a System::finish() so we can ensure nobody is still using the old mask.

void Sifteo::BG1Drawable::image	(	UInt2	pos,
		const AssetImage &	image,
		unsigned	frame = `0`
	)

inline

Draw a full AssetImage frame, with its top-left corner at the specified location.

Locations are specified in tile units, relative to the top-left of the 18x18 grid.

Tiles are located in the BG1 array based on the current mask. Any tiles not allocated by the mask are not drawn. (There will be a "hole" in your asset there.)

void Sifteo::BG1Drawable::image	(	UInt2	destXY,
		UInt2	size,
		const AssetImage &	image,
		UInt2	srcXY,
		unsigned	frame = `0`
	)

inline

Draw part of an AssetImage frame, with its top-left corner at the specified location.

Locations are specified in tile units, relative to the top-left of the 18x18 grid.

Tiles are located in the BG1 array based on the current mask. Any tiles not allocated by the mask are not drawn. (There will be a "hole" in your asset there.)

void Sifteo::BG1Drawable::maskedImage	(	const AssetImage &	image,
		const PinnedAssetImage &	key,
		unsigned	frame = `0`
	)

inline

Draw an AssetImage, automatically allocating tiles on the BG1 mask.

This replaces the entirety of the BG1 mask; other drawing on BG1 will be automatically replaced.

The image is always drawn to the top-left corner of BG1. You can place it anywhere on-screen by calling setPanning() afterwards.

Because of this, we automatically do a System::finish() so we can ensure nobody is still using the old mask.

void Sifteo::BG1Drawable::maskedImage	(	UInt2	size,
		const AssetImage &	image,
		const PinnedAssetImage &	key,
		UInt2	srcXY,
		unsigned	frame = `0`
	)

inline

Draw part of an AssetImage, automatically allocating tiles on the BG1 mask.

This replaces the entirety of the BG1 mask; other drawing on BG1 will be automatically replaced.

The image is always drawn to the top-left corner of BG1. You can place it anywhere on-screen by calling setPanning() afterwards.

Because of this, we automatically do a System::finish() so we can ensure nobody is still using the old mask.

void Sifteo::BG1Drawable::setMask ( const BG1Mask & mask )

inline

Change the tile allocation bitmap.

Changes to the bitmap will affect the way the tile array is interpreted, causing already-drawn tiles to appear to shift. Normally you should only change the allocation map when the BG1 mode isn't currently active, or when you've ensured that the cube isn't currently rendering asynchronously.

Because of this, we automatically do a System::finish() so we can ensure nobody is still using the old mask.

void Sifteo::BG1Drawable::setPanning ( Int2 pixels )

inline

Change the hardware pixel-panning origin for this mode.

The supplied vector is interpreted as the location on the tile buffer, in pixels, where the origin of the LCD will begin.

BG1 is an 16x16 buffer that does not wrap. The panning value can be negative, but only panning of up to +/- 128 is supported. Larger values will cause wraparound.

void Sifteo::BG1Drawable::span	(	unsigned	locationIndex,
		unsigned	count,
		unsigned	tileIndex
	)

inline

Plot a horizontal span of tiles in consecutively allocated locations in the BG1 tile array.

These tiles may not necessarily be consecutive on-screen.

void Sifteo::BG1Drawable::text	(	Int2	topLeft,
		const AssetImage &	font,
		const char *	str,
		char	firstChar = `' '`
	)

inline

Draw text, using an AssetImage as a fixed width font.

Each character is represented by a consecutive 'frame' in the image. Characters not present in the font will be skipped.

The documentation for this struct was generated from the following file:

bg1.h

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation