gameplay::SpriteBatch Class Reference

#include <SpriteBatch.h>

List of all members.

Classes
struct	SpriteVertex
Public Member Functions
virtual	~SpriteBatch ()
void	start ()
bool	isStarted () const
void	draw (const Rectangle &dst, const Rectangle &src, const Vector4 &color=Vector4::one())
void	draw (const Vector3 &dst, const Rectangle &src, const Vector2 &scale, const Vector4 &color=Vector4::one())
void	draw (const Vector3 &dst, const Rectangle &src, const Vector2 &scale, const Vector4 &color, const Vector2 &rotationPoint, float rotationAngle)
void	draw (const Vector3 &dst, float width, float height, float u1, float v1, float u2, float v2, const Vector4 &color, const Vector2 &rotationPoint, float rotationAngle, bool positionIsCenter=false)
void	draw (float x, float y, float z, float width, float height, float u1, float v1, float u2, float v2, const Vector4 &color, const Vector2 &rotationPoint, float rotationAngle, bool positionIsCenter=false)
void	draw (const Vector3 &position, const Vector3 &right, const Vector3 &forward, float width, float height, float u1, float v1, float u2, float v2, const Vector4 &color, const Vector2 &rotationPoint, float rotationAngle)
void	draw (float x, float y, float width, float height, float u1, float v1, float u2, float v2, const Vector4 &color)
void	draw (float x, float y, float width, float height, float u1, float v1, float u2, float v2, const Vector4 &color, const Rectangle &clip)
void	draw (float x, float y, float z, float width, float height, float u1, float v1, float u2, float v2, const Vector4 &color, const Rectangle &clip)
void	draw (float x, float y, float z, float width, float height, float u1, float v1, float u2, float v2, const Vector4 &color, bool positionIsCenter=false)
void	draw (SpriteBatch::SpriteVertex *vertices, unsigned int vertexCount, unsigned short *indices, unsigned int indexCount)
void	finish ()
Texture::Sampler *	getSampler () const
RenderState::StateBlock *	getStateBlock () const
Material *	getMaterial () const
void	setProjectionMatrix (const Matrix &matrix)
const Matrix &	getProjectionMatrix () const
Static Public Member Functions
static SpriteBatch *	create (const char *texturePath, Effect *effect=NULL, unsigned int initialCapacity=0)
static SpriteBatch *	create (Texture *texture, Effect *effect=NULL, unsigned int initialCapacity=0)

---

Detailed Description

Defines a class for drawing groups of sprites.

This class provides efficient rendering and sorting of two-dimensional sprites. Only a single texture and effect can be used with a SpriteBatch. This limitation promotes efficient batching by using texture atlases and implicit sorting to minimize state changes. Therefore, it is highly recommended to combine multiple small textures into larger texture atlases where possible when drawing sprites.

---

Constructor & Destructor Documentation

virtual gameplay::SpriteBatch::~SpriteBatch

(

)

[virtual]

Destructor.

---

Member Function Documentation

static SpriteBatch* gameplay::SpriteBatch::create	(	const char *	texturePath,
		Effect *	effect = NULL,
		unsigned int	initialCapacity = 0
	)		[static]

Creates a new SpriteBatch for drawing sprites with the given texture.

If the effect parameter is NULL, a default effect is used which applies an orthographic projection for the currently bound viewport. A custom projection matrix can be used with the default effect by passing a new projection matrix into the SpriteBatch via the setProjectionMatrix method.

If a custom effect is specified, it must meet the following requirements:

1. The vertex shader inputs must include a vec3 position, a vec2 tex coord and a vec4 color.
2. The names of the the vertex shader inputs must match the names defined by the VERTEX_ATTRIBUTE_XXX constants.
3. The fragment shader must define at least a single sampler/texture uniform.

Parameters:

texturePath	The path of the texture for this sprite batch.
effect	An optional effect to use with the SpriteBatch.
initialCapacity	An optional initial capacity of the batch (number of sprites).

Returns:

A new SpriteBatch for drawing sprites using the given texture.

static SpriteBatch* gameplay::SpriteBatch::create	(	Texture *	texture,
		Effect *	effect = NULL,
		unsigned int	initialCapacity = 0
	)		[static]

Creates a new SpriteBatch for drawing sprites with the given texture.

If the effect parameter is NULL, a default effect is used which applies an orthographic projection for the currently bound viewport. A custom projection matrix can be used with the default effect by passing a new projection matrix into the SpriteBatch via the setProjectionMatrix method.

If a custom effect is specified, it must meet the following requirements:

1. The vertex shader inputs must include a vec3 position, a vec2 tex coord and a vec4 color.
2. The names of the the vertex shader inputs must match the names defined by the VERTEX_ATTRIBUTE_XXX constants.
3. The fragment shader must define at least a single sampler/texture uniform.

Parameters:

texture	The texture for this sprite batch.
effect	An optional effect to use with the SpriteBatch.
initialCapacity	An optional initial capacity of the batch (number of sprites).

Returns:

A new SpriteBatch for drawing sprites using the given texture.

void gameplay::SpriteBatch::draw	(	const Rectangle &	dst,
		const Rectangle &	src,
		const Vector4 &	color = Vector4::one()
	)

Draws a single sprite.

Parameters:

dst	The destination rectangle.
src	The source rectangle.
color	The color to tint the sprite. Use white for no tint.

void gameplay::SpriteBatch::draw	(	const Vector3 &	dst,
		const Rectangle &	src,
		const Vector2 &	scale,
		const Vector4 &	color = Vector4::one()
	)

Draws a single sprite.

Parameters:

dst	The destination position.
src	The source rectangle.
scale	The X and Y scale.
color	The color to tint the sprite. Use white for no tint.

void gameplay::SpriteBatch::draw	(	const Vector3 &	dst,
		const Rectangle &	src,
		const Vector2 &	scale,
		const Vector4 &	color,
		const Vector2 &	rotationPoint,
		float	rotationAngle
	)

Draws a single sprite, rotated around rotationPoint by rotationAngle.

Parameters:

dst	The destination position.
src	The source rectangle.
scale	The X and Y scale.
color	The color to tint the sprite. Use white for no tint.
rotationPoint	The point to rotate around, relative to dst's x and y values. (e.g. Use Vector2(0.5f, 0.5f) to rotate around the quad's center.)
rotationAngle	The rotation angle in radians.

void gameplay::SpriteBatch::draw	(	const Vector3 &	dst,
		float	width,
		float	height,
		float	u1,
		float	v1,
		float	u2,
		float	v2,
		const Vector4 &	color,
		const Vector2 &	rotationPoint,
		float	rotationAngle,
		bool	positionIsCenter = false
	)

Draws a single sprite, rotated around rotationPoint by rotationAngle.

Parameters:

dst	The destination position.
width	The source width.
height	The source height.
u1	Texture coordinate.
v1	Texture coordinate.
u2	Texture coordinate.
v2	Texture coordinate.
color	The color to tint the sprite. Use white for no tint.
rotationPoint	The point to rotate around, relative to dst's x and y values. (e.g. Use Vector2(0.5f, 0.5f) to rotate around the quad's center.)
rotationAngle	The rotation angle in radians.
positionIsCenter	Specified whether the given destination is to be the center of the sprite or not (if not, it is treated as the bottom-left).

void gameplay::SpriteBatch::draw	(	float	x,
		float	y,
		float	z,
		float	width,
		float	height,
		float	u1,
		float	v1,
		float	u2,
		float	v2,
		const Vector4 &	color,
		const Vector2 &	rotationPoint,
		float	rotationAngle,
		bool	positionIsCenter = false
	)

Draws a single sprite, rotated around rotationPoint by rotationAngle.

Parameters:

x	The destination x position.
y	The destination y position.
z	The destination z position.
width	The source width.
height	The source height.
u1	Texture coordinate.
v1	Texture coordinate.
u2	Texture coordinate.
v2	Texture coordinate.
color	The color to tint the sprite. Use white for no tint.
rotationPoint	The point to rotate around, relative to dst's x and y values. (e.g. Use Vector2(0.5f, 0.5f) to rotate around the quad's center.)
rotationAngle	The rotation angle in radians.
positionIsCenter	Specified whether the given destination is to be the center of the sprite or not (if not, it is treated as the bottom-left).

void gameplay::SpriteBatch::draw	(	const Vector3 &	position,
		const Vector3 &	right,
		const Vector3 &	forward,
		float	width,
		float	height,
		float	u1,
		float	v1,
		float	u2,
		float	v2,
		const Vector4 &	color,
		const Vector2 &	rotationPoint,
		float	rotationAngle
	)

Draws a single sprite, rotated about the implied up vector.

Parameters:

position	The destination position.
right	The right vector of the sprite quad (should be normalized).
forward	The forward vector of the sprite quad (should be normalized).
width	The width of the sprite.
height	The height of the sprite.
u1	Texture coordinate.
v1	Texture coordinate.
u2	Texture coordinate.
v2	Texture coordinate.
color	The color to tint the sprite. Use white for no tint.
rotationPoint	The point to rotate around, relative to dst's x and y values. (e.g. Use Vector2(0.5f, 0.5f) to rotate around the quad's center.)
rotationAngle	The rotation angle in radians.

void gameplay::SpriteBatch::draw	(	float	x,
		float	y,
		float	width,
		float	height,
		float	u1,
		float	v1,
		float	u2,
		float	v2,
		const Vector4 &	color
	)

Draws a single sprite.

Parameters:

x	The x coordinate.
y	The y coordinate.
width	The sprite width.
height	The sprite height
u1	Texture coordinate.
v1	Texture coordinate.
u2	Texture coordinate.
v2	Texture coordinate.
color	The color to tint the sprite. Use white for no tint.

void gameplay::SpriteBatch::draw	(	float	x,
		float	y,
		float	width,
		float	height,
		float	u1,
		float	v1,
		float	u2,
		float	v2,
		const Vector4 &	color,
		const Rectangle &	clip
	)

Draws a single sprite, clipped within a rectangle.

Parameters:

x	The x coordinate.
y	The y coordinate.
width	The sprite width.
height	The sprite height
u1	Texture coordinate.
v1	Texture coordinate.
u2	Texture coordinate.
v2	Texture coordinate.
color	The color to tint the sprite. Use white for no tint.
clip	The clip rectangle.

void gameplay::SpriteBatch::draw	(	float	x,
		float	y,
		float	z,
		float	width,
		float	height,
		float	u1,
		float	v1,
		float	u2,
		float	v2,
		const Vector4 &	color,
		const Rectangle &	clip
	)

Draws a single sprite, clipped within a rectangle.

Parameters:

x	The x coordinate.
y	The y coordinate.
z	The z coordinate.
width	The sprite width.
height	The sprite height
u1	Texture coordinate.
v1	Texture coordinate.
u2	Texture coordinate.
v2	Texture coordinate.
color	The color to tint the sprite. Use white for no tint.
clip	The clip rectangle.

void gameplay::SpriteBatch::draw	(	float	x,
		float	y,
		float	z,
		float	width,
		float	height,
		float	u1,
		float	v1,
		float	u2,
		float	v2,
		const Vector4 &	color,
		bool	positionIsCenter = false
	)

Draws a single sprite.

Parameters:

x	The x coordinate.
y	The y coordinate.
z	The z coordinate.
width	The sprite width.
height	The sprite height
u1	Texture coordinate.
v1	Texture coordinate.
u2	Texture coordinate.
v2	Texture coordinate.
color	The color to tint the sprite. Use white for no tint.
positionIsCenter	Specified whether the given destination is to be the center of the sprite or not (if not, it is treated as the bottom-left).

void gameplay::SpriteBatch::draw	(	SpriteBatch::SpriteVertex *	vertices,
		unsigned int	vertexCount,
		unsigned short *	indices,
		unsigned int	indexCount
	)

Draws an array of vertices.

This is for more advanced usage.

Parameters:

vertices	The vertices to draw.
vertexCount	The number of vertices within the vertex array.
indices	The vertex indices.
indexCount	The number of indices within the index array.

void gameplay::SpriteBatch::finish

(

)

Finishes sprite drawing.

This method flushes the batch and commits rendering of all sprites that were drawn since the last call to start().

Material* gameplay::SpriteBatch::getMaterial

(

)

const

Gets the material used by this batch.

Returns:

The material.

const Matrix& gameplay::SpriteBatch::getProjectionMatrix

(

)

const

Gets the projection matrix for the SpriteBatch.

Returns:

The projection matrix.

Texture::Sampler* gameplay::SpriteBatch::getSampler

(

)

const

Gets the texture sampler.

This return texture sampler is used when sampling the texture in the effect. This can be modified for controlling sampler setting such as filtering modes.

RenderState::StateBlock* gameplay::SpriteBatch::getStateBlock

(

)

const

Gets the StateBlock for the SpriteBatch.

The returned state block controls the renderer state used when drawing items with this sprite batch. Modification can be made to the returned state block to change how primitives are rendered.

Returns:

The StateBlock for this SpriteBatch.

bool gameplay::SpriteBatch::isStarted

(

)

const

Determines if the sprite batch has been started but not yet finished.

Returns:

True if the batch has been started and not finished.

void gameplay::SpriteBatch::setProjectionMatrix

(

const Matrix &

matrix

)

Sets a custom projection matrix to use with the sprite batch.

When the default effect is used with a SpriteBatch (i.e. when NULL is passed into the 'effect' parameter of SpriteBatch::create), this method sets a custom projection matrix to be used instead of the default orthographic projection.

Parameters:

matrix

The new projection matrix to be used with the default effect.

void gameplay::SpriteBatch::start

(

)

Starts drawing sprites.

This method must be called before drawing any sprites and it must eventually be followed by a call to finish().