#include <CUSpriteBatch.h>

Public Member Functions
	SpriteBatch ()

	~SpriteBatch ()

void	dispose ()

bool	init ()

bool	init (const std::shared_ptr< GraphicsShader > &shader)

bool	init (unsigned int capacity)

bool	init (unsigned int capacity, const std::shared_ptr< GraphicsShader > &shader)

bool	isReady () const

bool	isDrawing () const

Uint32	getVerticesDrawn () const

Uint32	getCallsMade () const

void	setShader (const std::shared_ptr< GraphicsShader > &shader)

const std::shared_ptr< GraphicsShader > &	getShader () const

void	setColor (const Color4 color)

const Color4	getColor () const

void	setPerspective (const Mat4 &perspective)

const Mat4 &	getPerspective () const

void	setCamera (const std::shared_ptr< Camera > &camera)

void	setTexture (const std::shared_ptr< Texture > &texture)

const std::shared_ptr< Texture > &	getTexture () const

void	setGradient (const std::shared_ptr< Gradient > &gradient)

std::shared_ptr< Gradient >	getGradient () const

void	setScissor (const std::shared_ptr< Scissor > &scissor)

std::shared_ptr< Scissor >	getScissor () const

void	setBlur (float radius)

float	getBlur () const

void	setBlendMode (const BlendMode &mode)

void	setBlendState (const BlendState &blend)

const BlendState &	getBlendState () const

void	enableStencilTest (bool enable)

bool	usesStencilTest () const

void	setStencilMode (StencilMode mode)

void	setStencilState (const StencilState &stencil)

void	setFrontStencilState (const StencilState &stencil)

void	setBackStencilState (const StencilState &stencil)

const StencilState &	getFrontStencilState () const

const StencilState &	getBackStencilState () const

void	setColorMask (Uint8 mask)

Uint8	getColorMask () const

void	begin ()

void	begin (const std::shared_ptr< FrameBuffer > &framebuffer)

void	end ()

void	flush ()

void	fill (const Rect &rect)

void	fill (const Rect &rect, const Vec2 &offset)

void	fill (const Rect &rect, const Vec2 &origin, const Vec2 &scale, float angle, const Vec2 &offset)

void	fill (const Rect &rect, const Vec2 &origin, const Affine2 &transform)

void	fill (const Poly2 &poly)

void	fill (const Poly2 &poly, const Vec2 &offset)

void	fill (const Poly2 &poly, const Vec2 &origin, const Vec2 &scale, float angle, const Vec2 &offset)

void	fill (const Poly2 &poly, const Vec2 &origin, const Affine2 &transform)

void	outline (const Rect &rect)

void	outline (const Rect &rect, const Vec2 &offset)

void	outline (const Rect &rect, const Vec2 &origin, const Vec2 &scale, float angle, const Vec2 &offset)

void	outline (const Rect &rect, const Vec2 &origin, const Affine2 &transform)

void	outline (const Path2 &path)

void	outline (const Path2 &path, const Vec2 &offset)

void	outline (const Path2 &path, const Vec2 &origin, const Vec2 &scale, float angle, const Vec2 &offset)

void	outline (const Path2 &path, const Vec2 &origin, const Affine2 &transform)

void	draw (const std::shared_ptr< Texture > &texture, const Vec2 &position)

void	draw (const std::shared_ptr< Texture > &texture, const Color4 color, const Vec2 &position)

void	draw (const std::shared_ptr< Texture > &texture, const Rect &bounds)

void	draw (const std::shared_ptr< Texture > &texture, const Color4 color, const Rect &bounds)

void	draw (const std::shared_ptr< Texture > &texture, const Vec2 &origin, const Vec2 &scale, float angle, const Vec2 &offset)

void	draw (const std::shared_ptr< Texture > &texture, const Color4 color, const Vec2 &origin, const Vec2 &scale, float angle, const Vec2 &offset)

void	draw (const std::shared_ptr< Texture > &texture, const Rect &bounds, const Vec2 &origin, const Vec2 &scale, float angle, const Vec2 &offset)

void	draw (const std::shared_ptr< Texture > &texture, const Color4 color, const Rect &bounds, const Vec2 &origin, const Vec2 &scale, float angle, const Vec2 &offset)

void	draw (const std::shared_ptr< Texture > &texture, const Vec2 &origin, const Affine2 &transform)

void	draw (const std::shared_ptr< Texture > &texture, const Color4 color, const Vec2 &origin, const Affine2 &transform)

void	draw (const std::shared_ptr< Texture > &texture, const Rect &bounds, const Vec2 &origin, const Affine2 &transform)

void	draw (const std::shared_ptr< Texture > &texture, const Color4 color, const Rect &bounds, const Vec2 &origin, const Affine2 &transform)

void	draw (const std::shared_ptr< Texture > &texture, const Poly2 &poly, const Vec2 &offset)

void	draw (const std::shared_ptr< Texture > &texture, const Color4 color, const Poly2 &poly, const Vec2 &offset)

void	draw (const std::shared_ptr< Texture > &texture, const Poly2 &poly, const Vec2 &origin, const Vec2 &scale, float angle, const Vec2 &offset)

void	draw (const std::shared_ptr< Texture > &texture, const Color4 color, const Poly2 &poly, const Vec2 &origin, const Vec2 &scale, float angle, const Vec2 &offset)

void	draw (const std::shared_ptr< Texture > &texture, const Poly2 &poly, const Vec2 &origin, const Affine2 &transform)

void	draw (const std::shared_ptr< Texture > &texture, const Color4 color, const Poly2 &poly, const Vec2 &origin, const Affine2 &transform)

void	drawMesh (const Mesh< SpriteVertex > &mesh, const Vec2 &position, bool tint=true)

void	drawMesh (const Mesh< SpriteVertex > &mesh, const Affine2 &transform, bool tint=true)

void	drawMesh (const std::vector< SpriteVertex > &vertices, const Vec2 &position, bool tint=true)

void	drawMesh (const std::vector< SpriteVertex > &vertices, const Affine2 &transform, bool tint=true)

void	drawMesh (const SpriteVertex *vertices, size_t size, const Vec2 &position, bool tint=true)

void	drawMesh (const SpriteVertex *vertices, size_t size, const Affine2 &transform, bool tint=true)

void	drawText (const std::string text, const std::shared_ptr< Font > &font, const Vec2 &position)

void	drawText (const std::string text, const std::shared_ptr< Font > &font, const Vec2 &origin, const Affine2 &transform)

void	drawText (const std::shared_ptr< TextLayout > &text, const Vec2 &position)

void	drawText (const std::shared_ptr< TextLayout > &text, const Affine2 &transform)

Static Public Member Functions
static std::shared_ptr< SpriteBatch >	alloc ()

static std::shared_ptr< SpriteBatch >	alloc (const std::shared_ptr< GraphicsShader > &shader)

static std::shared_ptr< SpriteBatch >	alloc (unsigned int capacity)

static std::shared_ptr< SpriteBatch >	alloc (unsigned int capacity, const std::shared_ptr< GraphicsShader > &shader)

Static Public Attributes
static Uint32	DEFAULT_CAPACITY

Detailed Description

This class is a sprite batch for drawing 2d graphics.

A sprite batch gathers together sprites and draws them as a single mesh whenever possible. However this sprite batch is different from a classic sprite batch (from XNA or LibGDX) in that it provides a complete 2d graphics pipeline supporting both solid shapes and outlines, with texture, gradient, and scissor mask support.

This sprite batch is capable of drawing with an active texture. In that case, the shape will be drawn with a solid color. If no color has been specified, the default color is white. Outlines use the same texturing rules that solids do. There is also support for a simple, limited radius blur effect on textures.

Color gradient support is provided by the Gradient class. All gradients will be tinted by the current color (so the color should be reset to white before using a gradient).

Scissor masks are supported by the Scissor class. This is useful for constraining shapes to an internal window. A scissor mask must be a transformed rectangle; it cannot mask with arbitrary polygons.

All sprites are drawn with a z depth of 0. This class is not designed to be combined with an 3d graphics. That is because depth testing is incompatible with transparency, which is a major part of sprite graphics.

Drawing only occurs when the methods flush or end are called. Because loading vertices into a VertexBuffer is an expensive operation, this sprite batch attempts to minimize this as much as possible. Even texture switches are batched. However, it is still true that using a single texture atlas can significantly improve drawing speed.

A review of this class shows that there are a lot of redundant drawing methods. The scene graphs only use the Mesh methods. This goal has been to make this class more accessible to students familiar with classic sprite batches found in LibGDX or XNA.

It is possible to swap out the shader for this class with another one. Any shader for this class should support SpriteVertex as its vertex data. If you need additional vertex information, such as normals, you should create a new class. It should also have a uniform for the perspective matrix, texture, and drawing type (type 0). Support for gradients and scissors occur via a uniform block that is provides the data in the order scissor, and then gradient. See SpriteShader.frag for more information.

This is an extremely heavy-weight class. There is rarely any need to have more than one of these at a time. If you want to implement your own shader effects, it is better to construct your own custom pipeline with GraphicsShader and VertexBuffer.

Constructor & Destructor Documentation

◆ SpriteBatch()

cugl::graphics::SpriteBatch::SpriteBatch ( )

Creates a degenerate sprite batch with no buffers.

You must initialize the buffer before using it.

◆ ~SpriteBatch()

cugl::graphics::SpriteBatch::~SpriteBatch ( )

inline

Deletes the sprite batch, disposing all resources

Member Function Documentation

◆ alloc() [1/4]

static std::shared_ptr< SpriteBatch > cugl::graphics::SpriteBatch::alloc ( )

inlinestatic

Returns a new sprite batch with the default vertex capacity.

The default vertex capacity is 8192 vertices and 8192*3 = 24576 indices. If the mesh exceeds these values, the sprite batch will flush before before continuing to draw. Similarly uniform buffer is initialized with 512 buffer positions. This means that the uniform buffer is comparable in memory size to the vertices, but only allows 512 gradient or scissor mask context switches before the sprite batch must flush. If you wish to increase (or decrease) the capacity, use the alternate allocator.

The sprite batch begins with no active texture, and the color white. The perspective matrix is the identity.

Returns: a new sprite batch with the default vertex capacity.

◆ alloc() [2/4]

static std::shared_ptr< SpriteBatch > cugl::graphics::SpriteBatch::alloc ( const std::shared_ptr< GraphicsShader > & shader )

inlinestatic

Returns a new sprite batch with the default vertex capacity and given shader

The default vertex capacity is 8192 vertices and 8192*3 = 24576 indices. If the mesh exceeds these values, the sprite batch will flush before before continuing to draw. Similarly uniform buffer is initialized with 512 buffer positions. This means that the uniform buffer is comparable in memory size to the vertices, but only allows 512 gradient or scissor mask context switches before the sprite batch must flush. If you wish to increase (or decrease) the capacity, use the alternate allocator.

The sprite batch begins with no active texture, and the color white. The perspective matrix is the identity.

See the class description for the properties of a valid shader.

Parameters

shader The shader to use for this spritebatch

Returns: a new sprite batch with the default vertex capacity and given shader

◆ alloc() [3/4]

static std::shared_ptr< SpriteBatch > cugl::graphics::SpriteBatch::alloc ( unsigned int capacity )

inlinestatic

Returns a new sprite batch with the given vertex capacity.

The index capacity will be 3 times the vertex capacity. The maximum number of possible indices is the maximum size_t, so the vertex size must be a third that. In addition, the sprite batch will allocate 1/16 of the vertex capacity for uniform blocks (for gradients and scissor masks). This means that the uniform buffer is comparable in memory size to the vertices while still allowing a reasonably high rate of change for quads and regularly shaped sprites.

If the mesh exceeds the capacity, the sprite batch will flush before before continuing to draw. You should tune your system to have the appropriate capacity. To small a capacity will cause the system to thrash. However, too large a capacity could stall on memory transfers.

The sprite batch begins with the default blank texture, and color white. The perspective matrix is the identity.

Parameters

capacity The vertex capacity of this spritebatch

Returns: a new sprite batch with the given vertex capacity.

◆ alloc() [4/4]

static std::shared_ptr< SpriteBatch > cugl::graphics::SpriteBatch::alloc	(	unsigned int	capacity,
		const std::shared_ptr< GraphicsShader > &	shader
	)

inlinestatic

Returns a new sprite batch with the given vertex capacity and shader

The index capacity will be 3 times the vertex capacity. The maximum number of possible indices is the maximum size_t, so the vertex size must be a third that. In addition, the sprite batch will allocate 1/16 of the vertex capacity for uniform blocks (for gradients and scissor masks). This means that the uniform buffer is comparable in memory size to the vertices while still allowing a reasonably high rate of change for quads and regularly shaped sprites.

If the mesh exceeds the capacity, the sprite batch will flush before before continuing to draw. You should tune your system to have the appropriate capacity. To small a capacity will cause the system to thrash. However, too large a capacity could stall on memory transfers.

The sprite batch begins with the default blank texture, and color white. The perspective matrix is the identity.

See the class description for the properties of a valid shader.

Parameters

capacity	The vertex capacity of this spritebatch
shader	The shader to use for this spritebatch

Returns: a new sprite batch with the given vertex capacity and shader

◆ begin() [1/2]

void cugl::graphics::SpriteBatch::begin ( )

Starts drawing with the current perspective matrix.

This call will disable depth buffer writing. It enables blending and texturing. You must call either flush or end to complete drawing.

Calling this method will reset the vertex and draw call counters to 0.

◆ begin() [2/2]

void cugl::graphics::SpriteBatch::begin ( const std::shared_ptr< FrameBuffer > & framebuffer )

Starts drawing with the given frame buffer.

This call will disable depth buffer writing. It enables blending and texturing. You must call either flush or end to complete drawing.

This allows the sprite batch to draw to an offscreen framebuffer. You must call end to resume drawing to the primary display.

Calling this method will reset the vertex and draw call counters to 0.

Parameters

framebuffer The offscreen framebuffer to draw to.

◆ dispose()

void cugl::graphics::SpriteBatch::dispose ( )

Deletes the vertex buffers and resets all attributes.

You must reinitialize the sprite batch to use it.

◆ draw() [1/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4	color,
		const Poly2 &	poly,
		const Vec2 &	offset
	)

Draws the tinted, textured polygon at the given position

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It then draws the polygon, offset by the given value.

The polygon tesselation will be determined by the indices in poly. If the polygon has not been triangulated (by one of the triangulation factories EarclipTriangulator or DelaunayTriangulator, it may not draw properly.

The vertex coordinates will be determined by polygon vertex position. A horizontal position x has texture coordinate x/texture.width. A vertical coordinate has texture coordinate 1-y/texture.height. As a result, a rectangular polygon that has the same dimensions as the texture is the same as simply drawing the texture.

One way to think of the polygon is as a "cookie cutter". Treat the polygon coordinates as pixel coordinates in the texture filed, and use that to determine how the texture fills the polygon. This may make the polygon larger than you like in order to get the appropriate texturing. You should use one of the transform methods to fix this.

Parameters

texture	The new active texture
color	The new active color
poly	The polygon to texture
offset	The polygon offset

◆ draw() [2/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4	color,
		const Poly2 &	poly,
		const Vec2 &	origin,
		const Affine2 &	transform
	)

Draws the tinted, textured polygon transformed by the given matrix

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It then draws the polygon, translated by the given matrix.

The polygon will transformed by the given matrix. The transform will be applied assuming the given origin, which is specified relative to the origin of the polygon (not world coordinates). Hence this origin is essentially the pixel coordinate of the texture (see below) to assign as the origin of this transform.

The polygon tesselation will be determined by the indices in poly. If the polygon has not been triangulated (by one of the triangulation factories EarclipTriangulator or DelaunayTriangulator, it may not draw properly.

The vertex coordinates will be determined by polygon vertex position. A horizontal position x has texture coordinate x/texture.width. A vertical coordinate has texture coordinate 1-y/texture.height. As a result, a rectangular polygon that has the same dimensions as the texture is the same as simply drawing the texture.

One way to think of the polygon is as a "cookie cutter". Treat the polygon coordinates as pixel coordinates in the texture filed, and use that to determine how the texture fills the polygon. This may make the polygon larger than you like in order to get the appropriate texturing. You should use one of the transform methods to fix this.

Parameters

texture	The new active texture
color	The new active color
poly	The polygon to texture
origin	The image origin in pixel space
transform	The coordinate transform

◆ draw() [3/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4	color,
		const Poly2 &	poly,
		const Vec2 &	origin,
		const Vec2 &	scale,
		float	angle,
		const Vec2 &	offset
	)

Draws the tinted, textured polygon transformed by the given parameters

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It then draws the polygon, translated by the given parameters.

The polygon will be scaled first, then rotated, and finally offset by the given position. Rotation is measured in radians and is counter clockwise from the x-axis. Rotation will be about the provided origin, which is specified relative to the origin of the polygon (not world coordinates). Hence this origin is essentially the pixel coordinate of the texture (see below) to assign as the rotational center.

The polygon tesselation will be determined by the indices in poly. If the polygon has not been triangulated (by one of the triangulation factories EarclipTriangulator or DelaunayTriangulator, it may not draw properly.

The vertex coordinates will be determined by polygon vertex position. A horizontal position x has texture coordinate x/texture.width. A vertical coordinate has texture coordinate 1-y/texture.height. As a result, a rectangular polygon that has the same dimensions as the texture is the same as simply drawing the texture.

One way to think of the polygon is as a "cookie cutter". Treat the polygon coordinates as pixel coordinates in the texture filed, and use that to determine how the texture fills the polygon. This may make the polygon larger than you like in order to get the appropriate texturing. You should use one of the transform methods to fix this.

Parameters

texture	The new active texture
color	The new active color
poly	The polygon to texture
origin	The image origin in pixel space
scale	The amount to scale the polygon
angle	The amount to rotate the polygon
offset	The polygon offset in world coordinates

◆ draw() [4/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4	color,
		const Rect &	bounds
	)

Draws the tinted texture at the given position

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It then draws the specified rectangle filled with the texture.

Parameters

texture	The new active texture
color	The new active color
bounds	The rectangle to texture

◆ draw() [5/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4	color,
		const Rect &	bounds,
		const Vec2 &	origin,
		const Affine2 &	transform
	)

Draws the tinted texture transformed by the matrix

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It fills the specified rectangle with the texture, transformed by the given matrix.

The transform will be applied assuming the given image origin, which is specified in texture pixel coordinates (e.g from the bottom left corner).

Parameters

texture	The new active texture
color	The new active color
bounds	The rectangle to texture
origin	The image origin in pixel space
transform	The coordinate transform

◆ draw() [6/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4	color,
		const Rect &	bounds,
		const Vec2 &	origin,
		const Vec2 &	scale,
		float	angle,
		const Vec2 &	offset
	)

Draws the tinted texture transformed by the given parameters

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It fills the specified rectangle with the texture.

The rectangle will be scaled first, then rotated, and finally offset by the given position. Rotation is measured in radians and is counter clockwise from the x-axis. Rotation will be about the provided origin, which is specified relative to the origin of the rectangle (not world coordinates). So to spin about the center, the origin should be width/2, height/2 of the rectangle.

The texture will fill the entire rectangle before being transformed. Texture coordinate (0,1) will at the bottom left corner identified by rect,origin. To draw only part of a texture, use a subtexture to fill the rectangle with the region [minS,maxS]x[min,maxT]. Alternatively, you can use a Poly2 for more fine-tuned control.

Parameters

texture	The new active texture
color	The new active color
bounds	The rectangle to texture
origin	The image origin in pixel space
scale	The amount to scale the texture
angle	The amount to rotate the texture
offset	The rectangle offset in world coordinates

◆ draw() [7/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4	color,
		const Vec2 &	origin,
		const Affine2 &	transform
	)

Draws the tinted texture transformed by the matrix

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It then draws a texture-sized rectangle centered at the given origin, and transformed by the given matrix.

The transform will be applied assuming the given image origin, which is specified in texture pixel coordinates (e.g from the bottom left corner).

Parameters

texture	The new active texture
color	The new active color
origin	The image origin in pixel space
transform	The coordinate transform

◆ draw() [8/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4	color,
		const Vec2 &	origin,
		const Vec2 &	scale,
		float	angle,
		const Vec2 &	offset
	)

Draws the tinted texture transformed by the given parameters

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It then draws a texture-sized rectangle centered at the given origin, and transformed by the given parameters.

The rectangle will be scaled first, then rotated, and finally offset by the given position. Rotation is measured in radians and is counter clockwise from the x-axis. Rotation will be about the provided origin, which is specified in texture pixel coordinates (e.g from the bottom left corner).

Parameters

texture	The new active texture
color	The new active color
origin	The image origin in pixel space
scale	The amount to scale the texture
angle	The amount to rotate the texture
offset	The texture offset in world coordinates

◆ draw() [9/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4	color,
		const Vec2 &	position
	)

Draws the tinted texture at the given position

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It then draws a rectangle of the size of the texture, with bottom left corner at the given position.

Parameters

texture	The new active texture
color	The new active color
position	The bottom left corner of the texture

◆ draw() [10/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Poly2 &	poly,
		const Vec2 &	offset
	)

Draws the textured polygon (without tint) at the given position

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It then draws the polygon, offset by the given value.

The polygon tesselation will be determined by the indices in poly. If the polygon has not been triangulated (by one of the triangulation factories EarclipTriangulator or DelaunayTriangulator, it may not draw properly.

The vertex coordinates will be determined by polygon vertex position. A horizontal position x has texture coordinate x/texture.width. A vertical coordinate has texture coordinate 1-y/texture.height. As a result, a rectangular polygon that has the same dimensions as the texture is the same as simply drawing the texture.

One way to think of the polygon is as a "cookie cutter". Treat the polygon coordinates as pixel coordinates in the texture filed, and use that to determine how the texture fills the polygon. This may make the polygon larger than you like in order to get the appropriate texturing. You should use one of the transform methods to fix this.

Parameters

texture	The new active texture
poly	The polygon to texture
offset	The polygon offset

◆ draw() [11/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Poly2 &	poly,
		const Vec2 &	origin,
		const Affine2 &	transform
	)

Draws the textured polygon (without tint) transformed by the given matrix

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It then draws the polygon, translated by the given matrix.

The polygon will transformed by the given matrix. The transform will be applied assuming the given origin, which is specified relative to the origin of the polygon (not world coordinates). Hence this origin is essentially the pixel coordinate of the texture (see below) to assign as the origin of this transform.

The polygon tesselation will be determined by the indices in poly. If the polygon has not been triangulated (by one of the triangulation factories EarclipTriangulator or DelaunayTriangulator, it may not draw properly.

The vertex coordinates will be determined by polygon vertex position. A horizontal position x has texture coordinate x/texture.width. A vertical coordinate has texture coordinate 1-y/texture.height. As a result, a rectangular polygon that has the same dimensions as the texture is the same as simply drawing the texture.

One way to think of the polygon is as a "cookie cutter". Treat the polygon coordinates as pixel coordinates in the texture filed, and use that to determine how the texture fills the polygon. This may make the polygon larger than you like in order to get the appropriate texturing. You should use one of the transform methods to fix this.

Parameters

texture	The new active texture
poly	The polygon to texture
origin	The image origin in pixel space
transform	The coordinate transform

◆ draw() [12/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Poly2 &	poly,
		const Vec2 &	origin,
		const Vec2 &	scale,
		float	angle,
		const Vec2 &	offset
	)

Draws the textured polygon (without tint) transformed by the given parameters

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It then draws the polygon, transformed by the given parameters.

The polygon will be scaled first, then rotated, and finally offset by the given position. Rotation is measured in radians and is counter clockwise from the x-axis. Rotation will be about the provided origin, which is specified relative to the origin of the polygon (not world coordinates). Hence this origin is essentially the pixel coordinate of the texture (see below) to assign as the rotational center.

The polygon tesselation will be determined by the indices in poly. If the polygon has not been triangulated (by one of the triangulation factories EarclipTriangulator or DelaunayTriangulator, it may not draw properly.

The vertex coordinates will be determined by polygon vertex position. A horizontal position x has texture coordinate x/texture.width. A vertical coordinate has texture coordinate 1-y/texture.height. As a result, a rectangular polygon that has the same dimensions as the texture is the same as simply drawing the texture.

One way to think of the polygon is as a "cookie cutter". Treat the polygon coordinates as pixel coordinates in the texture filed, and use that to determine how the texture fills the polygon. This may make the polygon larger than you like in order to get the appropriate texturing. You should use one of the transform methods to fix this.

Parameters

texture	The new active texture
poly	The polygon to texture
origin	The image origin in pixel space
scale	The amount to scale the polygon
angle	The amount to rotate the polygon
offset	The polygon offset in world coordinates

◆ draw() [13/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Rect &	bounds
	)

Draws the texture (without tint) inside the given bounds

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It then draws the specified rectangle filled with the texture.

Parameters

texture	The new active texture
bounds	The rectangle to texture

◆ draw() [14/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Rect &	bounds,
		const Vec2 &	origin,
		const Affine2 &	transform
	)

Draws the texture (without tint) transformed by the matrix

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It fills the specified rectangle with the texture, transformed by the given matrix.

The transform will be applied assuming the given image origin, which is specified in texture pixel coordinates (e.g from the bottom left corner).

Parameters

texture	The new active texture
bounds	The rectangle to texture
origin	The image origin in pixel space
transform	The coordinate transform

◆ draw() [15/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Rect &	bounds,
		const Vec2 &	origin,
		const Vec2 &	scale,
		float	angle,
		const Vec2 &	offset
	)

Draws the texture (without tint) transformed by the given parameters

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It fills the specified rectangle with the texture.

The rectangle will be scaled first, then rotated, and finally offset by the given position. Rotation is measured in radians and is counter clockwise from the x-axis. Rotation will be about the provided origin, which is specified relative to the origin of the rectangle (not world coordinates). So to spin about the center, the origin should be width/2, height/2 of the rectangle.

The texture will fill the entire rectangle before being transformed. Texture coordinate (0,1) will at the bottom left corner identified by rect,origin. To draw only part of a texture, use a subtexture to fill the rectangle with the region [minS,maxS]x[min,maxT]. Alternatively, you can use a Poly2 for more fine-tuned control.

Parameters

texture	The new active texture
bounds	The rectangle to texture
origin	The image origin in pixel space
scale	The amount to scale the texture
angle	The amount to rotate the texture
offset	The rectangle offset in world coordinates

◆ draw() [16/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Vec2 &	origin,
		const Affine2 &	transform
	)

Draws the texture (without tint) transformed by the matrix

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It then draws a texture-sized rectangle centered at the given origin, and transformed by the given matrix.

The transform will be applied assuming the given image origin, which is specified in texture pixel coordinates (e.g from the bottom left corner).

Parameters

texture	The new active texture
origin	The image origin in pixel space
transform	The coordinate transform

◆ draw() [17/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Vec2 &	origin,
		const Vec2 &	scale,
		float	angle,
		const Vec2 &	offset
	)

Draws the texture (without tint) transformed by the given parameters

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It then draws a texture-sized rectangle centered at the given origin, and transformed by the given parameters.

The rectangle will be scaled first, then rotated, and finally offset by the given position. Rotation is measured in radians and is counter clockwise from the x-axis. Rotation will be about the provided origin, which is specified in texture pixel coordinates (e.g from the bottom left corner).

Parameters

texture	The new active texture
origin	The image origin in pixel space
scale	The amount to scale the texture
angle	The amount to rotate the texture
offset	The texture offset in world coordinates

◆ draw() [18/18]

void cugl::graphics::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Vec2 &	position
	)

Draws the texture (without tint) at the given position

This is a convenience method that calls the appropriate fill method. It sets both the texture and color (removing the previous active values). It then draws a rectangle of the size of the texture, with bottom left corner at the given position.

Parameters

texture	The new active texture
position	The bottom left corner of the texture

◆ drawMesh() [1/6]

void cugl::graphics::SpriteBatch::drawMesh	(	const Mesh< SpriteVertex > &	mesh,
		const Affine2 &	transform,
		bool	tint = `true`
	)

Draws the given mesh with the current texture and/or gradient.

This method provides more fine tuned control over texture coordinates that the other fill/outline methods. The texture no longer needs to be drawn uniformly over the shape. The transform will be applied to the vertex positions directly in world space.

The drawing command will be determined by the mesh, and the triangulation or lines determined by the mesh indices. The mesh vertices use their own color values. However, if tint is true, these values will be tinted (i.e. multiplied) by the current active color.

Parameters

mesh	The sprite mesh
transform	The coordinate transform
tint	Whether to tint with the active color

◆ drawMesh() [2/6]

void cugl::graphics::SpriteBatch::drawMesh	(	const Mesh< SpriteVertex > &	mesh,
		const Vec2 &	position,
		bool	tint = `true`
	)

Draws the given mesh with the current texture and/or gradient.

This method provides more fine tuned control over texture coordinates that the other fill/outline methods. The texture no longer needs to be drawn uniformly over the shape. The offset will be applied to the vertex positions directly in world space.

The drawing command will be determined by the mesh, and the triangulation or lines determined by the mesh indices. The mesh vertices use their own color values. However, if tint is true, these values will be tinted (i.e. multiplied) by the current active color.

Parameters

mesh	The sprite mesh
position	The coordinate offset for the mesh
tint	Whether to tint with the active color

◆ drawMesh() [3/6]

void cugl::graphics::SpriteBatch::drawMesh	(	const SpriteVertex *	vertices,
		size_t	size,
		const Affine2 &	transform,
		bool	tint = `true`
	)

Draws the vertices in a triangle fan with the current texture and/or gradient.

This method provides more fine tuned control over texture coordinates that the other fill/outline methods. The texture no longer needs to be drawn uniformly over the shape. The transform will be applied to the vertex positions directly in world space.

The drawing command will be GL_TRIANGLES, and the triangulation will be a mesh anchored on the first element. This method is ideal for convex polygons.

The mesh vertices use their own color values. However, if tint is true, these values will be tinted (i.e. multiplied) by the current active color.

Parameters

vertices	The vertices to draw as a triangle fan
size	The number of vertices in the fan
transform	The transform to apply to the vertices
tint	Whether to tint with the active color

◆ drawMesh() [4/6]

void cugl::graphics::SpriteBatch::drawMesh	(	const SpriteVertex *	vertices,
		size_t	size,
		const Vec2 &	position,
		bool	tint = `true`
	)

Draws the vertices in a triangle fan with the current texture and/or gradient.

This method provides more fine tuned control over texture coordinates that the other fill/outline methods. The texture no longer needs to be drawn uniformly over the shape. The offset will be applied to the vertex positions directly in world space.

The drawing command will be GL_TRIANGLES, and the triangulation will be a mesh anchored on the first element. This method is ideal for convex polygons.

The mesh vertices use their own color values. However, if tint is true, these values will be tinted (i.e. multiplied) by the current active color.

Parameters

vertices	The vertices to draw as a triangle fan
size	The number of vertices in the fan
position	The coordinate offset for the mesh
tint	Whether to tint with the active color

◆ drawMesh() [5/6]

void cugl::graphics::SpriteBatch::drawMesh	(	const std::vector< SpriteVertex > &	vertices,
		const Affine2 &	transform,
		bool	tint = `true`
	)

inline

Draws the vertices in a triangle fan with the current texture and/or gradient.

This method provides more fine tuned control over texture coordinates that the other fill/outline methods. The texture no longer needs to be drawn uniformly over the shape. The transform will be applied to the vertex positions directly in world space.

The drawing command will be GL_TRIANGLES, and the triangulation will be a mesh anchored on the first element. This method is ideal for convex polygons.

The mesh vertices use their own color values. However, if tint is true, these values will be tinted (i.e. multiplied) by the current active color.

Parameters

vertices	The vertices to draw as a triangle fan
transform	The transform to apply to the vertices
tint	Whether to tint with the active color

◆ drawMesh() [6/6]

void cugl::graphics::SpriteBatch::drawMesh	(	const std::vector< SpriteVertex > &	vertices,
		const Vec2 &	position,
		bool	tint = `true`
	)

inline

Draws the vertices in a triangle fan with the current texture and/or gradient.

This method provides more fine tuned control over texture coordinates that the other fill/outline methods. The texture no longer needs to be drawn uniformly over the shape. The offset will be applied to the vertex positions directly in world space.

The drawing command will be GL_TRIANGLES, and the triangulation will be a mesh anchored on the first element. This method is ideal for convex polygons.

The mesh vertices use their own color values. However, if tint is true, these values will be tinted (i.e. multiplied) by the current active color.

Parameters

vertices	The vertices to draw as a triangle fan
position	The coordinate offset for the mesh
tint	Whether to tint with the active color

◆ drawText() [1/4]

void cugl::graphics::SpriteBatch::drawText	(	const std::shared_ptr< TextLayout > &	text,
		const Affine2 &	transform
	)

Draws the text layout with the given coordinate transform

The transform is applied to the coordinate space of the TextLayout.

By default, all text is rendered with white letters. However, this can be tinted by the current sprite batch color to produce any color letters required.

Parameters

text	The text layout for the text to display
transform	The coordinate transform

◆ drawText() [2/4]

void cugl::graphics::SpriteBatch::drawText	(	const std::shared_ptr< TextLayout > &	text,
		const Vec2 &	position
	)

Draws the text layout at the specified position

The position specifies the location of the text layout origin. See the specification of TextLayout for more information.

By default, all text is rendered with white letters. However, this can be tinted by the current sprite batch color to produce any color letters required.

Parameters

text	The text layout for the text to display
position	The left edge of the text baseline

◆ drawText() [3/4]

void cugl::graphics::SpriteBatch::drawText	(	const std::string	text,
		const std::shared_ptr< Font > &	font,
		const Vec2 &	origin,
		const Affine2 &	transform
	)

Draws the text with the specified font and transform

The offset is measured from the left edge of the font baseline to identify the origin of the rendered text. This origin is used when applying the transform to the rendered text.

By default, all text is rendered with white letters. However, this can be tinted by the current sprite batch color to produce any color letters required.

Parameters

text	The text to display
font	The font to render the text
origin	The rotational origin relative to the baseline
transform	The coordinate transform

◆ drawText() [4/4]

void cugl::graphics::SpriteBatch::drawText	(	const std::string	text,
		const std::shared_ptr< Font > &	font,
		const Vec2 &	position
	)

Draws the text with the specified font at the given position.

The position specifies the location of the left edge of the baseline of the rendered text. The text will be displayed on only one line. For more fine tuned control of text, you should use a TextLayout.

By default, all text is rendered with white letters. However, this can be tinted by the current sprite batch color to produce any color letters required.

Parameters

text	The text to display
font	The font to render the text
position	The left edge of the text baseline

◆ enableStencilTest()

void cugl::graphics::SpriteBatch::enableStencilTest ( bool enable )

Sets whether stencil testing is enabled.

None of the stencil methods will do anything unless this value is set to true.

Parameters

enable Whether to enable stencil testing

◆ end()

void cugl::graphics::SpriteBatch::end ( )

Completes the drawing pass for this sprite batch, flushing the buffer.

This method will unbind the associated shader. It must always be called after a call to begin.

◆ fill() [1/8]

void cugl::graphics::SpriteBatch::fill ( const Poly2 & poly )

Draws the given polygon filled with the current color and texture.

The polygon tesselation will be determined by the indices in poly. If the polygon has not been triangulated (by one of the triangulation factories EarclipTriangulator or DelaunayTriangulator, it may not draw properly.

The vertex coordinates will be determined by polygon vertex position. A horizontal position x has texture coordinate x/texture.width. A vertical coordinate has texture coordinate 1-y/texture.height. As a result, a rectangular polygon that has the same dimensions as the texture is the same as simply drawing the texture.

One way to think of the polygon is as a "cookie cutter". Treat the polygon coordinates as pixel coordinates in the texture file, and use that to determine how the texture fills the polygon. This may make the polygon larger than you like in order to get the appropriate texturing. You should use one of the transform methods to fix this.

Parameters

poly	The polygon to draw

◆ fill() [2/8]

void cugl::graphics::SpriteBatch::fill	(	const Poly2 &	poly,
		const Vec2 &	offset
	)

Draws the given polygon filled with the current color and texture.

The polygon will be offset by the given position.

The polygon tesselation will be determined by the indices in poly. If the polygon has not been triangulated (by one of the triangulation factories EarclipTriangulator or DelaunayTriangulator, it may not draw properly.

The vertex coordinates will be determined by polygon vertex position. A horizontal position x has texture coordinate x/texture.width. A vertical coordinate has texture coordinate 1-y/texture.height. As a result, a rectangular polygon that has the same dimensions as the texture is the same as simply drawing the texture.

One way to think of the polygon is as a "cookie cutter". Treat the polygon coordinates as pixel coordinates in the texture file, and use that to determine how the texture fills the polygon. This may make the polygon larger than you like in order to get the appropriate texturing. You should use one of the transform methods to fix this.

Parameters

poly	The polygon to draw
offset	The polygon offset

◆ fill() [3/8]

void cugl::graphics::SpriteBatch::fill	(	const Poly2 &	poly,
		const Vec2 &	origin,
		const Affine2 &	transform
	)

Draws the given polygon filled with the current color and texture.

The polygon will transformed by the given matrix. The transform will be applied assuming the given origin, which is specified relative to the origin of the polygon (not world coordinates). Hence this origin is essentially the pixel coordinate of the texture (see below) to assign as the origin of this transform.

The polygon tesselation will be determined by the indices in poly. If the polygon has not been triangulated (by one of the triangulation factories EarclipTriangulator or DelaunayTriangulator, it may not draw properly.

The vertex coordinates will be determined by polygon vertex position. A horizontal position x has texture coordinate x/texture.width. A vertical coordinate has texture coordinate 1-y/texture.height. As a result, a rectangular polygon that has the same dimensions as the texture is the same as simply drawing the texture.

One way to think of the polygon is as a "cookie cutter". Treat the polygon coordinates as pixel coordinates in the texture file, and use that to determine how the texture fills the polygon. This may make the polygon larger than you like in order to get the appropriate texturing. You should use one of the transform methods to fix this.

Parameters

poly	The polygon to draw
origin	The image origin in pixel space
transform	The coordinate transform

◆ fill() [4/8]

void cugl::graphics::SpriteBatch::fill	(	const Poly2 &	poly,
		const Vec2 &	origin,
		const Vec2 &	scale,
		float	angle,
		const Vec2 &	offset
	)

Draws the given polygon filled with the current color and texture.

The polygon will be scaled first, then rotated, and finally offset by the given position. Rotation is measured in radians and is counter clockwise from the x-axis. Rotation will be about the provided origin, which is specified relative to the origin of the polygon (not world coordinates). Hence this origin is essentially the pixel coordinate of the texture (see below) to assign as the rotational center.

The polygon tesselation will be determined by the indices in poly. If the polygon has not been triangulated (by one of the triangulation factories EarclipTriangulator or DelaunayTriangulator, it may not draw properly.

The vertex coordinates will be determined by polygon vertex position. A horizontal position x has texture coordinate x/texture.width. A vertical coordinate has texture coordinate 1-y/texture.height. As a result, a rectangular polygon that has the same dimensions as the texture is the same as simply drawing the texture.

One way to think of the polygon is as a "cookie cutter". Treat the polygon coordinates as pixel coordinates in the texture file, and use that to determine how the texture fills the polygon. This may make the polygon larger than you like in order to get the appropriate texturing. You should use one of the transform methods to fix this.

Parameters

poly	The polygon to draw
origin	The image origin in pixel space
scale	The amount to scale the polygon
angle	The amount to rotate the polygon
offset	The polygon offset in world coordinates

◆ fill() [5/8]

void cugl::graphics::SpriteBatch::fill ( const Rect & rect )

Draws the given rectangle filled with the current color and texture.

The texture will fill the entire rectangle with texture coordinate (0,1) at the bottom left corner identified by rect,origin. To draw only part of a texture, use a subtexture to fill the rectangle with the region [minS,maxS]x[min,maxT]. Alternatively, you can use a Poly2 for more fine-tuned control.

Parameters

rect	The rectangle to draw

◆ fill() [6/8]

void cugl::graphics::SpriteBatch::fill	(	const Rect &	rect,
		const Vec2 &	offset
	)

Draws the given rectangle filled with the current color and texture.

The texture will fill the entire rectangle with texture coordinate (0,1) at the bottom left corner identified by rect,origin. To draw only part of a texture, use a subtexture to fill the rectangle with the region [minS,maxS]x[min,maxT]. Alternatively, you can use a Poly2 for more fine-tuned control.

Parameters

rect	The rectangle to draw
offset	The rectangle offset

◆ fill() [7/8]

void cugl::graphics::SpriteBatch::fill	(	const Rect &	rect,
		const Vec2 &	origin,
		const Affine2 &	transform
	)

Draws the given rectangle filled with the current color and texture.

The rectangle will transformed by the given matrix. The transform will be applied assuming the given origin, which is specified relative to the origin of the rectangle (not world coordinates). So to apply the transform to the center of the rectangle, the origin should be width/2, height/2 of the rectangle.

The texture will fill the entire rectangle with texture coordinate (0,1) at the bottom left corner identified by rect,origin. To draw only part of a texture, use a subtexture to fill the rectangle with the region [minS,maxS]x[min,maxT]. Alternatively, you can use a Poly2 for more fine-tuned control.

Parameters

rect	The rectangle to draw
origin	The rotational offset in the rectangle
transform	The coordinate transform

◆ fill() [8/8]

void cugl::graphics::SpriteBatch::fill	(	const Rect &	rect,
		const Vec2 &	origin,
		const Vec2 &	scale,
		float	angle,
		const Vec2 &	offset
	)

Draws the given rectangle filled with the current color and texture.

The rectangle will be scaled first, then rotated, and finally offset by the given position. Rotation is measured in radians and is counter clockwise from the x-axis. Rotation will be about the provided origin, which is specified relative to the origin of the rectangle (not world coordinates). So to spin about the center, the origin should be width/2, height/2 of the rectangle.

The texture will fill the entire rectangle before being transformed. Texture coordinate (0,1) will at the bottom left corner identified by rect,origin. To draw only part of a texture, use a subtexture to fill the rectangle with the region [minS,maxS]x[min,maxT]. Alternatively, you can use a Poly2 for more fine-tuned control.

Parameters

rect	The rectangle to draw
origin	The rotational offset in the rectangle
scale	The amount to scale the rectangle
angle	The amount to rotate the rectangle
offset	The rectangle offset in world coordinates

◆ flush()

void cugl::graphics::SpriteBatch::flush ( )

Flushes the current mesh to the underlying shader.

This methods converts all of the batched drawing commands into low-level drawing operations in the associated graphics API. This method is useful in OpenGL in that it allows us to recycle internal data structures, reducing the memory footprint. However, it is rarely useful in Vulkan. It is provided simply to keep the interface uniform between graphics APIs.

◆ getBackStencilState()

const StencilState & cugl::graphics::SpriteBatch::getBackStencilState ( ) const

Returns the back-facing stencil state for this spritebatch

This setting will only apply to triangles that are back-facing. Use getFrontStencilState to see the setting for front-facing triangles.

Returns: the back-facing stencil state for this spritebatch

◆ getBlendState()

const BlendState & cugl::graphics::SpriteBatch::getBlendState ( ) const

Returns the color blend state for this spritebatch

Note that if color blending was set using setBlendMode, that blend mode was expanded into a blend state, and this value will be the result of this expansion. This value is BlendMode#PREMULT by default as image files are loaded with premultiplied alpha.

Returns: the color blend state for this spritebatch

◆ getBlur()

float cugl::graphics::SpriteBatch::getBlur ( ) const

Returns the blur radius in pixels (0 if there is no blurring).

This sprite batch supports a simple Gaussian blur. The blur samples at 5 points along each axis. The values are essentially at the radius, half-radius, and center. Because of the limited sampling, large radii will start to produce a pixellation effect. But it can produce acceptable blur effects with little cost to performance. It is especially ideal for font-blur effects on font atlases.

When applying a blur to a GlyphRun, make sure that the source Font has Font#setPadding set to at least the blur radius. Otherwise, the blur will bleed into other glyphs.

Setting this value to 0 will disable texture blurring. This value is 0 by default.

Returns: the blur radius in pixels (0 if there is no blurring).

◆ getCallsMade()

Uint32 cugl::graphics::SpriteBatch::getCallsMade ( ) const

inline

Returns the number of OpenGL calls in the latest pass (so far).

This value will be reset to 0 whenever begin() is called.

Returns: the number of OpenGL calls in the latest pass (so far).

◆ getColor()

const Color4 cugl::graphics::SpriteBatch::getColor ( ) const

inline

Returns the active color of this sprite batch

All subsequent shapes and outlines drawn by this sprite batch will be tinted by this color. This color is white by default.

Returns: the active color of this sprite batch

◆ getColorMask()

Uint8 cugl::graphics::SpriteBatch::getColorMask ( ) const

Returns the color mask for stencils in this spritebatch

The color mask is used to prevent certain colors from being drawn. This is useful for when you want to draw to a stencil buffer and nothing else.

Returns: the color mask for stencils in this spritebatch

◆ getFrontStencilState()

const StencilState & cugl::graphics::SpriteBatch::getFrontStencilState ( ) const

Returns the font-facing stencil state for this spritebatch

This setting will only apply to triangles that are front-facing. Use getBackStencilState to see the setting for back-facing triangles.

Returns: the font-facing stencil state for this spritebatch

◆ getGradient()

std::shared_ptr< Gradient > cugl::graphics::SpriteBatch::getGradient ( ) const

Returns the active gradient of this sprite batch

Gradients may be used in the place of (and together with) colors. Gradients are like applied textures, and use the gradient coordinates in SpriteVertex as their texture coordinates.

If this value is nullptr, then no gradient is active. In that case, the color vertex attribute will be interpretted as normal (e.g. a traditional color vector). This value is nullptr by default.

All gradients are tinted by the active color. Unless you explicitly want this tinting, you should set the active color to white before drawing with an active gradient.

This method returns a copy of the internal gradient. Changes to this object have no effect on the sprite batch.

Returns: The active gradient for this sprite batch

◆ getPerspective()

const Mat4 & cugl::graphics::SpriteBatch::getPerspective ( ) const

Returns the active perspective matrix of this sprite batch

The perspective matrix is the combined modelview-projection from the camera. By default, this is the identity matrix.

Returns: the active perspective matrix of this sprite batch

◆ getScissor()

std::shared_ptr< Scissor > cugl::graphics::SpriteBatch::getScissor ( ) const

Returns the active scissor mask of this sprite batch

Scissor masks may be combined with all types of drawing (colors, textures, and gradients). They are specified in the same coordinate system as getPerspective.

If this value is nullptr, then no scissor mask is active. This value is nullptr by default.

This method returns a copy of the internal scissor. Changes to this object have no effect on the sprite batch.

Returns: The active scissor mask for this sprite batch

◆ getShader()

const std::shared_ptr< GraphicsShader > & cugl::graphics::SpriteBatch::getShader ( ) const

inline

Returns the shader for this sprite batch

This value may NOT be changed during a drawing pass. See the class description for the properties of a valid shader.

Returns: the shader for this sprite batch

◆ getTexture()

const std::shared_ptr< Texture > & cugl::graphics::SpriteBatch::getTexture ( ) const

Returns the active texture of this sprite batch

All subsequent shapes and outlines drawn by this sprite batch will use this texture. If the value is nullptr, all shapes and outlines will be drawn with a solid color instead. This value is nullptr by default.

Returns: the active texture of this sprite batch

◆ getVerticesDrawn()

Uint32 cugl::graphics::SpriteBatch::getVerticesDrawn ( ) const

inline

Returns the number of vertices drawn in the latest pass (so far).

This value will be reset to 0 whenever begin() is called.

Returns: the number of vertices drawn in the latest pass (so far).

◆ init() [1/4]

bool cugl::graphics::SpriteBatch::init ( )

Initializes a sprite batch with the default vertex capacity.

The default vertex capacity is 8192 vertices and 8192*3 = 24576 indices. If the mesh exceeds these values, the sprite batch will flush before before continuing to draw. Similarly uniform buffer is initialized with 512 buffer positions. This means that the uniform buffer is comparable in memory size to the vertices, but only allows 512 gradient or scissor mask context switches before the sprite batch must flush. If you wish to increase (or decrease) the capacity, use the alternate initializer.

The sprite batch begins with no active texture, and the color white. The perspective matrix is the identity.

Returns: true if initialization was successful.

◆ init() [2/4]

bool cugl::graphics::SpriteBatch::init ( const std::shared_ptr< GraphicsShader > & shader )

inline

Initializes a sprite batch with the default vertex capacity and given shader

The default vertex capacity is 8192 vertices and 8192*3 = 24576 indices. If the mesh exceeds these values, the sprite batch will flush before before continuing to draw. Similarly uniform buffer is initialized with 512 buffer positions. This means that the uniform buffer is comparable in memory size to the vertices, but only allows 512 gradient or scissor mask context switches before the sprite batch must flush. If you wish to increase (or decrease) the capacity, use the alternate initializer.

The sprite batch begins with no active texture, and the color white. The perspective matrix is the identity.

See the class description for the properties of a valid shader.

Parameters

shader The shader to use for this spritebatch

Returns: true if initialization was successful.

◆ init() [3/4]

bool cugl::graphics::SpriteBatch::init ( unsigned int capacity )

Initializes a sprite batch with the given vertex capacity.

The index capacity will be 3 times the vertex capacity. The maximum number of possible indices is the maximum size_t, so the vertex size must be a third that. In addition, the sprite batch will allocate 1/16 of the vertex capacity for uniform blocks (for gradients and scissor masks). This means that the uniform buffer is comparable in memory size to the vertices while still allowing a reasonably high rate of change for quads and regularly shaped sprites.

If the mesh exceeds the capacity, the sprite batch will flush before before continuing to draw. You should tune your system to have the appropriate capacity. To small a capacity will cause the system to thrash. However, too large a capacity could stall on memory transfers.

The sprite batch begins with no active texture, and the color white. The perspective matrix is the identity.

Parameters

capacity The vertex capacity of this spritebatch

Returns: true if initialization was successful.

◆ init() [4/4]

bool cugl::graphics::SpriteBatch::init	(	unsigned int	capacity,
		const std::shared_ptr< GraphicsShader > &	shader
	)

Initializes a sprite batch with the given vertex capacity and shader

The index capacity will be 3 times the vertex capacity. The maximum number of possible indices is the maximum size_t, so the vertex size must be a third that. In addition, the sprite batch will allocate 1/16 of the vertex capacity for uniform blocks (for gradients and scissor masks). This means that the uniform buffer is comparable in memory size to the vertices while still allowing a reasonably high rate of change for quads and regularly shaped sprites.

If the mesh exceeds the capacity, the sprite batch will flush before before continuing to draw. You should tune your system to have the appropriate capacity. To small a capacity will cause the system to thrash. However, too large a capacity could stall on memory transfers.

The sprite batch begins with no active texture, and the color white. The perspective matrix is the identity.

See the class description for the properties of a valid shader.

Parameters

capacity	The vertex capacity of this spritebatch
shader	The shader to use for this spritebatch

Returns: true if initialization was successful.

◆ isDrawing()

bool cugl::graphics::SpriteBatch::isDrawing ( ) const

inline

Returns whether this sprite batch is actively drawing.

A sprite batch is in use if begin() has been called without the requisite end() to flush the pipeline.

Returns: whether this sprite batch is actively drawing.

◆ isReady()

bool cugl::graphics::SpriteBatch::isReady ( ) const

inline

Returns true if this sprite batch has been initialized and is ready for use.

Returns: true if this sprite batch has been initialized and is ready for use.

◆ outline() [1/8]

void cugl::graphics::SpriteBatch::outline ( const Path2 & path )

Outlines the given path with the current color and texture.

The drawing will be a wireframe of a path, but the lines are textured. The vertex coordinates will be determined by path vertex position. A horizontal position x has texture coordinate x/texture.width. A vertical coordinate has texture coordinate 1-y/texture.height. As a result, a rectangular polygon that has the same dimensions as the texture is the same as simply outlining the rectangle.

One way to think of the path is as a "cookie cutter". Treat the path coordinates as pixel coordinates in the texture file, and use that to determine how the texture fills the path. This may make the path larger than you like in order to get the appropriate texturing. You should use one of the transform methods to fix this.

Parameters

path	The path to outline

◆ outline() [2/8]

void cugl::graphics::SpriteBatch::outline	(	const Path2 &	path,
		const Vec2 &	offset
	)

Outlines the given path with the current color and texture.

The path will be offset by the given position.

The drawing will be a wireframe of a path, but the lines are textured. The vertex coordinates will be determined by path vertex position. A horizontal position x has texture coordinate x/texture.width. A vertical coordinate has texture coordinate 1-y/texture.height. As a result, a rectangular polygon that has the same dimensions as the texture is the same as simply outlining the rectangle.

One way to think of the path is as a "cookie cutter". Treat the path coordinates as pixel coordinates in the texture file, and use that to determine how the texture fills the path. This may make the path larger than you like in order to get the appropriate texturing. You should use one of the transform methods to fix this.

Parameters

path	The path to outline
offset	The path offset

◆ outline() [3/8]

void cugl::graphics::SpriteBatch::outline	(	const Path2 &	path,
		const Vec2 &	origin,
		const Affine2 &	transform
	)

Outlines the given path with the current color and texture.

The path will transformed by the given matrix. The transform will be applied assuming the given origin, which is specified relative to the origin of the path (not world coordinates). Hence this origin is essentially the pixel coordinate of the texture (see below) to assign as the origin of this transform.

The drawing will be a wireframe of a path, but the lines are textured. The vertex coordinates will be determined by path vertex position. A horizontal position x has texture coordinate x/texture.width. A vertical coordinate has texture coordinate 1-y/texture.height. As a result, a rectangular polygon that has the same dimensions as the texture is the same as simply outlining the rectangle.

One way to think of the path is as a "cookie cutter". Treat the path coordinates as pixel coordinates in the texture file, and use that to determine how the texture fills the path. This may make the path larger than you like in order to get the appropriate texturing. You should use one of the transform methods to fix this.

Parameters

path	The path to outline
origin	The image origin in pixel space
transform	The coordinate transform

◆ outline() [4/8]

void cugl::graphics::SpriteBatch::outline	(	const Path2 &	path,
		const Vec2 &	origin,
		const Vec2 &	scale,
		float	angle,
		const Vec2 &	offset
	)

Outlines the given path with the current color and texture.

The path will be scaled first, then rotated, and finally offset by the given position. Rotation is measured in radians and is counter clockwise from the x-axis. Rotation will be about the provided origin, which is specified relative to the origin of the path (not world coordinates). Hence this origin is essentially the pixel coordinate of the texture (see below) to assign as the rotational center.

The drawing will be a wireframe of a path, but the lines are textured. The vertex coordinates will be determined by path vertex position. A horizontal position x has texture coordinate x/texture.width. A vertical coordinate has texture coordinate 1-y/texture.height. As a result, a rectangular polygon that has the same dimensions as the texture is the same as simply outlining the rectangle.

One way to think of the path is as a "cookie cutter". Treat the path coordinates as pixel coordinates in the texture file, and use that to determine how the texture fills the path. This may make the path larger than you like in order to get the appropriate texturing. You should use one of the transform methods to fix this.

Parameters

path	The path to outline
origin	The image origin in pixel space
scale	The amount to scale the path
angle	The amount to rotate the path
offset	The path offset in world coordinates

◆ outline() [5/8]

void cugl::graphics::SpriteBatch::outline ( const Rect & rect )

Outlines the given rectangle with the current color and texture.

The drawing will be a wireframe of a rectangle. The wireframe will be textured with Texture coordinate (0,1) at the bottom left corner identified by rect,origin. The remaining edges will correspond to the edges of the texture. To draw only part of a texture, use a subtexture to outline the edges with [minS,maxS]x[min,maxT]. Alternatively, you can use a Poly2 for more fine-tuned control.

Parameters

rect	The rectangle to outline

◆ outline() [6/8]

void cugl::graphics::SpriteBatch::outline	(	const Rect &	rect,
		const Vec2 &	offset
	)

Outlines the given rectangle with the current color and texture.

The drawing will be a wireframe of a rectangle. The wireframe will be textured with Texture coordinate (0,1) at the bottom left corner identified by rect,origin. The remaining edges will correspond to the edges of the texture. To draw only part of a texture, use a subtexture to outline the edges with [minS,maxS]x[min,maxT]. Alternatively, you can use a Poly2 for more fine-tuned control.

Parameters

rect	The rectangle to outline
offset	The rectangle offset

◆ outline() [7/8]

void cugl::graphics::SpriteBatch::outline	(	const Rect &	rect,
		const Vec2 &	origin,
		const Affine2 &	transform
	)

Outlines the given rectangle with the current color and texture.

The rectangle will transformed by the given matrix. The transform will be applied assuming the given origin, which is specified relative to the origin of the rectangle (not world coordinates). So to apply the transform to the center of the rectangle, the origin should be width/2, height/2 of the rectangle.

The drawing will be a wireframe of a rectangle. The wireframe will be textured with Texture coordinate (0,1) at the bottom left corner identified by rect,origin. The remaining edges will correspond to the edges of the texture. To draw only part of a texture, use a subtexture to outline the edges with [minS,maxS]x[min,maxT]. Alternatively, you can use a Poly2 for more fine-tuned control.

Parameters

rect	The rectangle to outline
origin	The rotational offset in the rectangle
transform	The coordinate transform

◆ outline() [8/8]

void cugl::graphics::SpriteBatch::outline	(	const Rect &	rect,
		const Vec2 &	origin,
		const Vec2 &	scale,
		float	angle,
		const Vec2 &	offset
	)

Outlines the given rectangle with the current color and texture.

The rectangle will be scaled first, then rotated, and finally offset by the given position. Rotation is measured in radians and is counter clockwise from the x-axis. Rotation will be about the provided origin, which is specified relative to the origin of the rectangle (not world coordinates). So to spin about the center, the origin should be width/2, height/2 of the rectangle.

The drawing will be a wireframe of a rectangle. The wireframe will be textured with Texture coordinate (0,1) at the bottom left corner identified by rect,origin. The remaining edges will correspond to the edges of the texture. To draw only part of a texture, use a subtexture to outline the edges with [minS,maxS]x[min,maxT]. Alternatively, you can use a Poly2 for more fine-tuned control.

Parameters

rect	The rectangle to outline
origin	The rotational offset in the rectangle
scale	The amount to scale the rectangle
angle	The amount to rotate the rectangle
offset	The rectangle offset in world coordinates

◆ setBackStencilState()

void cugl::graphics::SpriteBatch::setBackStencilState ( const StencilState & stencil )

Sets the back-facing stencil state for this spritebatch

This setting will only apply to triangles that are back-facing. Use setFrontStencilState to affect front-facing triangles.

Parameters

stencil The back-facing stencil state

◆ setBlendMode()

void cugl::graphics::SpriteBatch::setBlendMode ( const BlendMode & mode )

inline

Sets the color blend mode for this spritebatch

By default this value is BlendMode#PREMULT, as image files are loaded with premultiplied alpha. You cannot determine the blend mode for a spritebatch after it is set. You can only get the blend state for that mode with the method getBlendState.

Parameters

mode	The color blend mode for this spritebatch

◆ setBlendState()

void cugl::graphics::SpriteBatch::setBlendState ( const BlendState & blend )

Sets the color blend state for this spritebatch

This provides much more fine-tuned control over color blending that setBlendMode. This value is BlendMode#PREMULT by default as image files are loaded with premultiplied alpha.

Parameters

blend The color blend state for this spritebatch

◆ setBlur()

void cugl::graphics::SpriteBatch::setBlur ( float radius )

Sets the blur radius in pixels (0 if there is no blurring).

This sprite batch supports a simple Gaussian blur. The blur samples at 5 points along each axis. The values are essentially at the radius, half-radius, and center. Because of the limited sampling, large radii will start to produce a pixellation effect. But it can produce acceptable blur effects with little cost to performance. It is especially ideal for font-blur effects on font atlases.

When applying a blur to a GlyphRun, make sure that the source Font has Font#setPadding set to at least the blur radius. Otherwise, the blur will bleed into other glyphs.

Setting this value to 0 will disable texture blurring. This value is 0 by default.

Parameters

radius The blur radius in pixels

◆ setCamera()

void cugl::graphics::SpriteBatch::setCamera ( const std::shared_ptr< Camera > & camera )

inline

Sets the camera for this sprite batch

This method is a convenience method that calls setPerspective on the combined perspective matrix of the camera.

Parameters

camera The camera providing the perspective matrix

◆ setColor()

void cugl::graphics::SpriteBatch::setColor ( const Color4 color )

Sets the active color of this sprite batch

All subsequent shapes and outlines drawn by this sprite batch will be tinted by this color. This color is white by default.

Parameters

color The active color for this sprite batch

◆ setColorMask()

void cugl::graphics::SpriteBatch::setColorMask ( Uint8 mask )

Sets the color mask for stencils in this spritebatch

The color mask is used to prevent certain colors from being drawn. This is useful for when you want to draw to a stencil buffer and nothing else.

Parameters

mask	The stencil color mask

◆ setFrontStencilState()

void cugl::graphics::SpriteBatch::setFrontStencilState ( const StencilState & stencil )

Sets the font-facing stencil state for this spritebatch

This setting will only apply to triangles that are front-facing. Use setBackStencilState to affect back-facing triangles.

Parameters

stencil The font-facing stencil state

◆ setGradient()

void cugl::graphics::SpriteBatch::setGradient ( const std::shared_ptr< Gradient > & gradient )

Sets the active gradient of this sprite batch

Gradients may be used in the place of (and together with) colors. Gradients are like applied textures, and use the gradient coordinates in SpriteVertex as their texture coordinates.

If this value is nullptr, then no gradient is active. In that case, the color vertex attribute will be interpretted as normal (e.g. a traditional color vector). This value is nullptr by default.

All gradients are tinted by the active color. Unless you explicitly want this tinting, you should set the active color to white before drawing with an active gradient.

This method acquires a copy of the gradient. Changes to the original gradient after calling this method have no effect.

Parameters

gradient The active gradient for this sprite batch

◆ setPerspective()

void cugl::graphics::SpriteBatch::setPerspective ( const Mat4 & perspective )

Sets the active perspective matrix of this sprite batch

The perspective matrix is the combined modelview-projection from the camera. By default, this is the identity matrix.

Parameters

perspective The active perspective matrix for this sprite batch

◆ setScissor()

void cugl::graphics::SpriteBatch::setScissor ( const std::shared_ptr< Scissor > & scissor )

Sets the active scissor mask of this sprite batch

Scissor masks may be combined with all types of drawing (colors, textures, and gradients). They are specified in the same coordinate system as getPerspective.

If this value is nullptr, then no scissor mask is active. This value is nullptr by default.

This method acquires a copy of the scissor. Changes to the original scissor mask after calling this method have no effect.

Parameters

scissor The active scissor mask for this sprite batch

◆ setShader()

void cugl::graphics::SpriteBatch::setShader ( const std::shared_ptr< GraphicsShader > & shader )

Sets the shader for this sprite batch

This value may NOT be changed during a drawing pass. See the class description for the properties of a valid shader.

Parameters

shader The active color for this sprite batch

◆ setStencilMode()

void cugl::graphics::SpriteBatch::setStencilMode ( StencilMode mode )

Sets the stencil mode for this spritebatch

A stencil mode is a predefined stencil setting that applies to both front-facing and back-facing triangles. You cannot determine the stencil mode for a spritebatch after it is set. You can only get the stencil state for that mode with the methods getFrontStencilState and getBackStencilState.

Note that this method may also alter the color mask, as some stencil modes require a specific color mask to achieve their affects.

Parameters

mode	The stencil mode for this spritebatch

◆ setStencilState()

void cugl::graphics::SpriteBatch::setStencilState ( const StencilState & stencil )

Sets the stencil state (both front and back) for this spritebatch

This method will change both the front and back stencil states to the given value. You can access the individual settings with the methods getFrontStencilState and getBackStencilState.

Parameters

stencil The (front and back) stencil state

◆ setTexture()

void cugl::graphics::SpriteBatch::setTexture ( const std::shared_ptr< Texture > & texture )

Sets the active texture of this sprite batch

All subsequent shapes and outlines drawn by this sprite batch will use this texture. If the value is nullptr, all shapes and outlines will be draw with a solid color instead. This value is nullptr by default.

Parameters

texture The active texture for this sprite batch

◆ usesStencilTest()

bool cugl::graphics::SpriteBatch::usesStencilTest ( ) const

Returns whether stencil testing is currently enabled in this shader.

None of the stencil methods will do anything unless this value is set to true.

Returns: whether stencil testing is currently enabled in this shader.

Member Data Documentation

◆ DEFAULT_CAPACITY

Uint32 cugl::graphics::SpriteBatch::DEFAULT_CAPACITY

static

The default capacity of a sprite batch

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

/Users/wmwhite/Developer/CUGL/include/cugl/graphics/CUSpriteBatch.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ SpriteBatch()

◆ ~SpriteBatch()

Member Function Documentation

◆ alloc() [1/4]

◆ alloc() [2/4]

◆ alloc() [3/4]

◆ alloc() [4/4]

◆ begin() [1/2]

◆ begin() [2/2]

◆ dispose()

◆ draw() [1/18]

◆ draw() [2/18]

◆ draw() [3/18]

◆ draw() [4/18]

◆ draw() [5/18]

◆ draw() [6/18]

◆ draw() [7/18]

◆ draw() [8/18]

◆ draw() [9/18]

◆ draw() [10/18]

◆ draw() [11/18]

◆ draw() [12/18]

◆ draw() [13/18]

◆ draw() [14/18]

◆ draw() [15/18]

◆ draw() [16/18]

◆ draw() [17/18]

◆ draw() [18/18]

◆ drawMesh() [1/6]

◆ drawMesh() [2/6]

◆ drawMesh() [3/6]

◆ drawMesh() [4/6]

◆ drawMesh() [5/6]

◆ drawMesh() [6/6]

◆ drawText() [1/4]

◆ drawText() [2/4]

◆ drawText() [3/4]

◆ drawText() [4/4]

◆ enableStencilTest()

◆ end()

◆ fill() [1/8]

◆ fill() [2/8]

◆ fill() [3/8]

◆ fill() [4/8]

◆ fill() [5/8]

◆ fill() [6/8]

◆ fill() [7/8]

◆ fill() [8/8]

◆ flush()

◆ getBackStencilState()

◆ getBlendState()

◆ getBlur()

◆ getCallsMade()

◆ getColor()

◆ getColorMask()

◆ getFrontStencilState()

◆ getGradient()

◆ getPerspective()

◆ getScissor()

◆ getShader()

◆ getTexture()

◆ getVerticesDrawn()

◆ init() [1/4]

◆ init() [2/4]

◆ init() [3/4]

◆ init() [4/4]

◆ isDrawing()

◆ isReady()

◆ outline() [1/8]

◆ outline() [2/8]

◆ outline() [3/8]

◆ outline() [4/8]

◆ outline() [5/8]

◆ outline() [6/8]

◆ outline() [7/8]