|  | overview |  | wiki |  | api reference |  | download

- Main Page
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Functions Variables Typedefs Enumerations Enumerator
Classes | Public Member Functions | Static Public Member Functions
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().

All Classes Functions Variables Typedefs Enumerations Enumerator