A memory buffer which holds graphics data. More...

#include <sifteo/video.h>

Public Member Functions
void	attach (_SYSCubeID id)
	Attach this VideoBuffer to a cube. More...

CubeID	cube () const
	Get the CubeID that this buffer is currently attached to.

void	erase ()
	Zero all mode-specific video memory. More...

void	initMode (VideoMode m, unsigned firstLine=0, unsigned numLines=LCD_height)
	Initialize the video buffer and change modes. More...

void	lock (uint16_t addr)
	Prepare to modify a particular address. More...

VideoMode	mode () const
	Retrieve the last video mode set by setMode()

	operator _SYSCubeID () const
	Implicit conversion to _SYSCubeID. More...

Side	orientation () const
	Map the LCD rotation mask to screen orientation. This is the side which maps to the physical "top" of the screen.

void	orientTo (const Neighborhood &thisN, const VideoBuffer &src, const Neighborhood &srcN)
	Set this VideoBuffer's cube orientation to be consistent with the orientation of another "source" VideoBuffer whose cube is neighbored to this one. More...

void	orientTo (const VideoBuffer &src)
	Variant of orientTo() without explicitly specified Neighborhoods. More...

uint16_t	peek (uint16_t addr) const
	Read one word of VRAM.

uint8_t	peekb (uint16_t addr) const
	Read one byte of VRAM.

Byte3	physicalAccel () const
	Return the physical accelerometer reading for this cube. More...

Neighborhood	physicalNeighbors () const
	Return the current physical neighbors for the cube attached to this VideoBuffer. More...

Side	physicalToVirtual (Side side) const
	Convert a physical side (relative to the hardware itself) to a virtual side (relative to the current screen orientation).

Neighborhood	physicalToVirtual (Neighborhood nb) const
	Convert a Neighborhood from physical to virtual orientation. More...

void	poke (uint16_t addr, uint16_t word)
	Modify a word of VRAM, automatically locking it and marking the change only if that word has actually been modified. More...

void	pokeb (uint16_t addr, uint8_t byte)
	Like poke(), but modifies a single byte. Less efficient, but sometimes you really do just want to modify one byte.

void	pokei (uint16_t addr, uint16_t index)
	Poke a 14-bit tile index into a particular VRAM word.

Rotation	rotation () const
	Look up the last display rotation set by setRotation().

void	setDefaultWindow ()
	Restore the default full-screen drawing window.

void	setMode (VideoMode m)
	Change the video mode. More...

void	setOrientation (Side topSide)
	Set the LCD rotation such that the top of the framebuffer is at the physical side 'topSide'. More...

void	setRotation (Rotation r)
	Set the display rotation to use in subsequent rendering.

void	setWindow (uint8_t firstLine, uint8_t numLines)
	Change the current drawing window. More...

void	setWindowFirstLine (uint8_t firstLine)
	Like setWindow(), but change only the first line.

void	setWindowNumLines (uint8_t numLines)
	Like setWindow(), but change only the number of lines.

void	touch ()
	Mark the VideoBuffer as having changed, without actually modifying any memory. More...

void	unlock ()
	End a sequence of modifications to VRAM. More...

Byte3	virtualAccel () const
	Return the virtual accelerometer reading for this cube. More...

Neighborhood	virtualNeighbors () const
	Return the current virtual neighbors for the cube attached to this VideoBuffer. More...

Side	virtualToPhysical (Side side) const
	Convert a virtual side (relative to the current screen orientation) to a physical side (relative to the hardware itself).

Neighborhood	virtualToPhysical (Neighborhood nb) const
	Convert a Neighborhood from virtual to physical orientation. More...

uint8_t	windowFirstLine () const
	Retrieve the most recent 'firstLine' value, set with setWindow() or setWindowFirstLine()

uint8_t	windowNumLines () const
	Retrieve the most recent 'numLines' value, set with setWindow() or setWindowNumLines()

void	xorb (uint16_t addr, uint8_t byte)
	Like pokeb(), but atomically XORs a value with the byte. This is a no-op if and only if byte==0.

Static Public Member Functions
static Side	physicalToVirtual (Side side, Side rot)
	Convert a physical side (relative to the hardware itself) to a virtual side (relative to the specified screen orientation).

static Neighborhood	physicalToVirtual (Neighborhood nb, Side rot)
	Convert a Neighborhood from physical to virtual orientation. More...

static Side	virtualToPhysical (Side side, Side rot)
	Convert a virtual side (relative to the specified screen orientation) to a physical side (relative to the hardware itself).

static Neighborhood	virtualToPhysical (Neighborhood nb, Side rot)
	Convert a Neighborhood from virtual to physical orientation. More...

Public Attributes
union {
BG0Drawable bg0
	Drawable for the BG0 layer, as used in BG0, BG0_BG1, and BG0_SPR_BG1 modes.

BG0ROMDrawable bg0rom
	Drawable for the BG0_ROM tiled mode.

BG1Drawable bg1
	Drawable for the BG1 layer, as used in BG0_BG1 and BG0_SPR_BG1 modes.

BG2Drawable bg2
	Drawable for the BG2 tiled mode.

Colormap colormap
	Colormap accessor, for framebuffer modes.

FB128Drawable fb128
	Drawable for the FB128 framebuffer mode.

FB32Drawable fb32
	Drawable for the FB32 framebuffer mode.

FB64Drawable fb64
	Drawable for the FB64 framebuffer mode.

SpriteLayer sprites
	Drawable for the sprite layer in BG0_SPR_BG1 mode.

StampDrawable stamp
	Drawable for the STAMP framebuffer mode.

};
	Anonymous union of various ways to interpret the VideoBuffer memory.

Detailed Description

A memory buffer which holds graphics data.

This is a mirror of the remote graphics memory in each cube's hardware. By writing to this buffer, changes are enqueued for later transmission to the physical video buffer.

Cubes have a few basic video features that are always available: rotation, windowing, and selecting a video mode. This class provides access to those features, as well as low-level primitives for accessing the underlying video buffer memory.

The layout and meaning of video memory changes depending on what mode you're in. This class provides a union of mode-specific accessors you can use.

VideoBuffers can be used with at most one CubeID at a time, though this association between cubes and video buffers can change at runtime. Most games will want to have one VideoBuffer per cube, but if you plan to support very large numbers of cubes, it may be necessary to have fewer VideoBuffers that are shared among a larger number of cubes.

VideoBuffers must be explicitly attached to a cube. See VideoBuffer::attach() and CubeID::detachVideoBuffer().

If you're accessing the low-level VideoBuffer memory directly, it is strongly recommended that you're aware of the synchronization protocol used in this buffer, to keep it consistent between the system software and your application. See abi.h for details on this protocol.

Member Function Documentation

void Sifteo::VideoBuffer::attach ( _SYSCubeID id )

inline

Attach this VideoBuffer to a cube.

When this cube is enabled and connected, the system will asynchronously stream video data from this VideoBuffer to that cube.

This call automatically reinitializes the change bitmap in this buffer, so that we'll resend its contents to the cube on next paint.

If this VideoBuffer was previously attached to a different cube, you must manually attach() a different video buffer to the old cube first, or call CubeID::detachVideoBuffer() on the old cube. A VideoBuffer must never be attached to multiple cubes at once.

In general, a VideoBuffer should be attach()'ed prior to performing any tile rendering. This is because the relocated tile addresses of your assets may be different for each cube, so we need to know the attached cube's ID at draw time.

Waits for all cubes to finish rendering before (re)attaching this buffer.

void Sifteo::VideoBuffer::erase ( )

inline

Zero all mode-specific video memory.

This is typically part of initMode(), but it may be necessary to do this at other times. For example, when doing a multi-mode scene, you may need to ensure that unused portions of VRAM are in a known blank state.

void Sifteo::VideoBuffer::initMode	(	VideoMode	m,
		unsigned	firstLine = `0`,
		unsigned	numLines = `LCD_height`
	)

inline

Initialize the video buffer and change modes.

This is a shorthand for calling System::finish() to finish existing rendering before changing the mode, actually changing the mode, restoring the default window and rotation, and finally zero'ing all mode-specific video memory.

Most programs should use initMode() to set up the initial mode for a VideoBuffer, prior to attaching it to a cube. This is because the process of attaching a video buffer causes the system to assume all video memory is 'dirty', and re-send it to the cube. It is important to have video memory in the state you want it to be in before this happens.

You can optionally specify a non-default window size. This is helpful, since often when doing multi-mode rendering you need to change modes and change windows at the same time.

void Sifteo::VideoBuffer::lock ( uint16_t addr )

inline

Prepare to modify a particular address.

Addresses must be locked prior to the buffer memory being modified. Multiple calls to lock may be made in a row, without an intervening unlock().

Typically this operation is performed automatically as part of any other write operation, like a poke().

Sifteo::VideoBuffer::operator _SYSCubeID ( ) const

inline

Implicit conversion to _SYSCubeID.

This lets you pass a VideoBuffer to the CubeID constructor, to easily get a CubeID instance for the current cube that this buffer is attached to.

void Sifteo::VideoBuffer::orientTo	(	const Neighborhood &	thisN,
		const VideoBuffer &	src,
		const Neighborhood &	srcN
	)

inline

Set this VideoBuffer's cube orientation to be consistent with the orientation of another "source" VideoBuffer whose cube is neighbored to this one.

This version requires the caller to supply Neighborhood instances corresponding to both our own cube and the 'src' cube. This does not require that the cubes are currently neighbored, just that they were when the Neighborhood objects were created.

Note that these Neighborhoods must be in physical orientation, not transformed to virtual.

void Sifteo::VideoBuffer::orientTo ( const VideoBuffer & src )

inline

Variant of orientTo() without explicitly specified Neighborhoods.

Uses the current system neighbor state for each of the two cubes.

Note that the caller is responsible for ensuring that this cube and the source cube are actually neighbored. The set of neighbored cubes may change at any event dispatch point, such as System::paint().

Byte3 Sifteo::VideoBuffer::physicalAccel ( ) const

inline

Return the physical accelerometer reading for this cube.

The resulting vector is oriented with respect to the cube hardware.

This is equivalent to calling accel() on the cube() object.

Neighborhood Sifteo::VideoBuffer::physicalNeighbors ( ) const

inline

Return the current physical neighbors for the cube attached to this VideoBuffer.

This is equivalent to creating a new Neighborhood instance from cube(), but it's provided by analogy with virtualNeighbors().

static Neighborhood Sifteo::VideoBuffer::physicalToVirtual	(	Neighborhood	nb,
		Side	rot
	)

inlinestatic

Convert a Neighborhood from physical to virtual orientation.

These two expressions produce the same result:

vbuf.physicalToVirtual(N).neighborAt(S)
N.neighborAt(vbuf.physicalToVirtual(S))

This version uses the specified cube orientation.

Neighborhood Sifteo::VideoBuffer::physicalToVirtual ( Neighborhood nb ) const

inline

Convert a Neighborhood from physical to virtual orientation.

These two expressions produce the same result:

vbuf.physicalToVirtual(N).neighborAt(S)
N.neighborAt(vbuf.physicalToVirtual(S))

Uses the current orientation of this VideoBuffer.

void Sifteo::VideoBuffer::poke	(	uint16_t	addr,
		uint16_t	word
	)

inline

Modify a word of VRAM, automatically locking it and marking the change only if that word has actually been modified.

After a sequence of poke() calls, the caller is responsible for issuing one unlock(). This happens automatically at the next System::paint().

void Sifteo::VideoBuffer::setMode ( VideoMode m )

inline

Change the video mode.

8 This affects subsequent rendering only. Note that this may change the way hardware interprets the contents of video memory, so it's important to synchronize any mode changes such that you know the hardware has finished rendering with the old mode before you start rendering with the new mode.

void Sifteo::VideoBuffer::setOrientation ( Side topSide )

inline

Set the LCD rotation such that the top of the framebuffer is at the physical side 'topSide'.

This is the counterpart to the orientation() getter.

void Sifteo::VideoBuffer::setWindow	(	uint8_t	firstLine,
		uint8_t	numLines
	)

inline

Change the current drawing window.

The graphics processor generates one scanline at a time. Windowed drawing allows the graphics processor to emit fewer scanlines than a full screen, and to modify where on the LCD these scanlines begin. In this way, you can do partial-screen rendering in the Y axis.

This can be used for many kinds of animation effects as well as effects that involve mixing different video modes.

Windowing takes place prior to Rotation. So, if your screen is rotated 90 degrees left, for example, setWindow would be operating on screen columns rather than rows, and the "line" numbers would start at the left edge.

void Sifteo::VideoBuffer::touch ( )

inline

Mark the VideoBuffer as having changed, without actually modifying any memory.

This will force the next System::paint() to actually redraw this cube, even if it seems like nothing has changed.

void Sifteo::VideoBuffer::unlock ( )

inline

End a sequence of modifications to VRAM.

If the system is not already busy flushing updates to the cube, this allows it to begin. This operation is performed implicitly during a System::paint().

Byte3 Sifteo::VideoBuffer::virtualAccel ( ) const

inline

Return the virtual accelerometer reading for this cube.

The resulting vector is oriented with respect to the current LCD rotation.

Neighborhood Sifteo::VideoBuffer::virtualNeighbors ( ) const

inline

Return the current virtual neighbors for the cube attached to this VideoBuffer.

This is equivalent to creating a new Neighborhood instance from cube(), and transforming it with physicalToVirtual().

static Neighborhood Sifteo::VideoBuffer::virtualToPhysical	(	Neighborhood	nb,
		Side	rot
	)

inlinestatic

Convert a Neighborhood from virtual to physical orientation.

These two expressions produce the same result:

vbuf.virtualToPhysical(N).neighborAt(S)
N.neighborAt(vbuf.virtualToPhysical(S))

This version uses the specified cube orientation.

Neighborhood Sifteo::VideoBuffer::virtualToPhysical ( Neighborhood nb ) const

inline

Convert a Neighborhood from virtual to physical orientation.

These two expressions produce the same result:

vbuf.virtualToPhysical(N).neighborAt(S)
N.neighborAt(vbuf.virtualToPhysical(S))

Uses the current orientation of this VideoBuffer.

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

video.h

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation