#include <CUSpriteBatch.h>

Public Member Functions
	SpriteBatch ()

	~SpriteBatch ()

void	dispose ()

bool	init ()

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

bool	init (unsigned int capacity)

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

bool	isReady () const

bool	isDrawing () const

unsigned int	getVerticesDrawn () const

unsigned int	getCallsMade () const

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

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

void	setColor (const Color4f color)

const Color4f	getColor () const

void	setPerspective (const Mat4 &perspective)

const Mat4 &	getPerspective () const

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	setBlendFunc (GLenum srcFactor, GLenum dstFactor)

GLenum	getSourceBlendFactor () const

GLenum	getDestinationBlendFactor () const

void	setBlendEquation (GLenum equation)

GLenum	getBlendEquation () const

void	setDepthFunc (GLenum function)

GLenum	getDepthFunc () const

void	setDepth (float depth)

float	getDepth () const

void	setBlurStep (GLuint step)

GLuint	getBlurStep () const

void	begin ()

void	begin (const Mat4 &perspective)

void	end ()

void	flush ()

void	fill (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 Mat4 &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 Mat4 &transform)

void	fill (const Mesh< SpriteVertex2 > &mesh, const Mat4 &transform, bool tint=true)

void	fill (const Mesh< SpriteVertex3 > &mesh, const Mat4 &transform, bool tint=true)

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 Mat4 &transform)

void	outline (const Poly2 &poly)

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

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

void	outline (const Poly2 &poly, const Vec2 origin, const Mat4 &transform)

void	outline (const Mesh< SpriteVertex2 > &mesh, const Mat4 &transform, bool tint=true)

void	outline (const Mesh< SpriteVertex3 > &mesh, const Mat4 &transform, bool tint=true)

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

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

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

void	draw (const std::shared_ptr< Texture > &texture, const Color4f 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 Color4f 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 Color4f 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 Mat4 &transform)

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

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

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

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

void	draw (const std::shared_ptr< Texture > &texture, const Color4f 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 Color4f 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 Mat4 &transform)

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

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

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

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

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

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.

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 SpriteVertex3 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 then gradient. See SpriteShader.frag for more information.

Constructor & Destructor Documentation

◆ SpriteBatch()

cugl::SpriteBatch::SpriteBatch ( )

Creates a degenerate sprite batch with no buffers.

You must initialize the buffer before using it.

◆ ~SpriteBatch()

cugl::SpriteBatch::~SpriteBatch ( )

inline

Deletes the sprite batch, disposing all resources

Member Function Documentation

◆ alloc() [1/4]

static std::shared_ptr<SpriteBatch> cugl::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::SpriteBatch::alloc ( const std::shared_ptr< Shader > & 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::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::SpriteBatch::alloc	(	unsigned int	capacity,
		const std::shared_ptr< Shader > &	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::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 OpenGL call counters to 0.

◆ begin() [2/2]

void cugl::SpriteBatch::begin ( const Mat4 & perspective )

inline

Starts drawing with the given 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 OpenGL call counters to 0.

Parameters

perspective The perspective matrix to draw with.

◆ dispose()

void cugl::SpriteBatch::dispose ( )

Deletes the vertex buffers and resets all attributes.

You must reinitialize the sprite batch to use it.

◆ draw() [1/18]

void cugl::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4f	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 SimpleTriangulator or ComplexTriangulator, 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.

If depth testing is on, all vertices will be the current depth.

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::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4f	color,
		const Poly2 &	poly,
		const Vec2	origin,
		const Mat4 &	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 SimpleTriangulator or ComplexTriangulator, 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.

If depth testing is on, all vertices will be the current depth.

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::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4f	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 SimpleTriangulator or ComplexTriangulator, 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.

If depth testing is on, all vertices will be the current depth.

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::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4f	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.

If depth testing is on, all vertices will be the current depth.

Parameters

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

◆ draw() [5/18]

void cugl::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4f	color,
		const Rect	bounds,
		const Vec2	origin,
		const Mat4 &	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).

If depth testing is on, all vertices will be the current depth.

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::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4f	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.

If depth testing is on, all vertices will be the current depth.

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::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4f	color,
		const Vec2	origin,
		const Mat4 &	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).

If depth testing is on, all vertices will be the current depth.

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::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4f	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).

If depth testing is on, all vertices will be the current depth.

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::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Color4f	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.

If depth testing is on, all vertices will be the current depth.

Parameters

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

◆ draw() [10/18]

void cugl::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 SimpleTriangulator or ComplexTriangulator, 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.

If depth testing is on, all vertices will be the current depth.

Parameters

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

◆ draw() [11/18]

void cugl::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Poly2 &	poly,
		const Vec2	origin,
		const Mat4 &	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 SimpleTriangulator or ComplexTriangulator, 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.

If depth testing is on, all vertices will be the current depth.

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::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 SimpleTriangulator or ComplexTriangulator, 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.

If depth testing is on, all vertices will be the current depth.

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::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.

If depth testing is on, all vertices will be the current depth.

Parameters

texture	The new active texture
bounds	The rectangle to texture

◆ draw() [14/18]

void cugl::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Rect	bounds,
		const Vec2	origin,
		const Mat4 &	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).

If depth testing is on, all vertices will be the current depth.

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::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.

If depth testing is on, all vertices will be the current depth.

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::SpriteBatch::draw	(	const std::shared_ptr< Texture > &	texture,
		const Vec2	origin,
		const Mat4 &	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).

If depth testing is on, all vertices will be the current depth.

Parameters

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

◆ draw() [17/18]

void cugl::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).

If depth testing is on, all vertices will be the current depth.

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::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.

If depth testing is on, all vertices will be the current depth.

Parameters

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

◆ end()

void cugl::SpriteBatch::end ( )

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

This method enables depth writes and disables blending and texturing. It must always be called after a call to begin.

◆ fill() [1/10]

void cugl::SpriteBatch::fill	(	const Mesh< SpriteVertex2 > &	mesh,
		const Mat4 &	transform,
		bool	tint = `true`
	)

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

This method provides more fine tuned control over texture coordinates that the other fill 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. If depth testing is on, all vertices will be the current depth.

The triangulation will be determined by the mesh indices. If necessary, these can be generated via one of the triangulation factories SimpleTriangulator or ComplexTriangulator.

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

◆ fill() [2/10]

void cugl::SpriteBatch::fill	(	const Mesh< SpriteVertex3 > &	mesh,
		const Mat4 &	transform,
		bool	tint = `true`
	)

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

This method provides more fine tuned control over texture coordinates that the other fill 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. This method will use the depth of each vertex and ignore the sprite batch depth

The triangulation will be determined by the mesh indices. If necessary, these can be generated via one of the triangulation factories SimpleTriangulator or ComplexTriangulator.

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

◆ fill() [3/10]

void cugl::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 SimpleTriangulator or ComplexTriangulator, 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.

If depth testing is on, all vertices will be the current depth.

Parameters

poly	The polygon to draw

◆ fill() [4/10]

void cugl::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 SimpleTriangulator or ComplexTriangulator, 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.

If depth testing is on, all vertices will be the current depth.

Parameters

poly	The polygon to draw
offset	The polygon offset

◆ fill() [5/10]

void cugl::SpriteBatch::fill	(	const Poly2 &	poly,
		const Vec2	origin,
		const Mat4 &	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 SimpleTriangulator or ComplexTriangulator, 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.

If depth testing is on, all vertices will be the current depth.

Parameters

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

◆ fill() [6/10]

void cugl::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 SimpleTriangulator or ComplexTriangulator, 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.

If depth testing is on, all vertices will be the current depth.

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() [7/10]

void cugl::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.

If depth testing is on, all vertices will be the current depth.

Parameters

rect	The rectangle to draw
offset	The rectangle offset

◆ fill() [8/10]

void cugl::SpriteBatch::fill	(	const Rect	rect,
		const Vec2	origin,
		const Mat4 &	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.

If depth testing is on, all vertices will be the current depth.

Parameters

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

◆ fill() [9/10]

void cugl::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.

If depth testing is on, all vertices will be the current depth.

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

◆ fill() [10/10]

void cugl::SpriteBatch::fill ( 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.

If depth testing is on, all vertices will be the current depth.

Parameters

rect	The rectangle to draw

◆ flush()

void cugl::SpriteBatch::flush ( )

Flushes the current mesh without completing the drawing pass.

This method is called whenever you change any attribute other than color mid-pass. It prevents the attribute change from retoactively affecting previuosly drawn shapes.

◆ getBlendEquation()

GLenum cugl::SpriteBatch::getBlendEquation ( ) const

inline

Returns the blending equation for this sprite batch

By default this value is GL_FUNC_ADD. For other options, see

 https://www.opengl.org/sdk/docs/man/html/glBlendEquation.xhtml

Returns: the blending equation for this sprite batch

◆ getBlurStep()

GLuint cugl::SpriteBatch::getBlurStep ( ) const

inline

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

This sprite batch supports a simple 9-step blur. The blur samples from the center pixel and 8 other pixels around it in a box. The blur step is the number of pixels away to sample. So a 1-step blur samples from the immediate neighbor pixels. On most textures a 5-step blur has very noticeable affects.

This is not a full-featured Gaussian blur. In particular, large step values 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.

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

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

◆ getCallsMade()

unsigned int cugl::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 Color4f cugl::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

◆ getDepth()

float cugl::SpriteBatch::getDepth ( ) const

inline

Returns the current depth of this sprite batch.

The depth value is appended to all 2d shapes drawn by this sprite batch. If depth testing is enabled, this can allow the sprite batch to draw shapes out of order. This value is 0 by default.

Returns: the current depth of this sprite batch.

◆ getDepthFunc()

GLenum cugl::SpriteBatch::getDepthFunc ( ) const

inline

Returns the depth testing function for this sprite batch

By default this value is GL_ALWAYS, disabling all depth testing. For other options, see

 https://www.opengl.org/sdk/docs/man/html/glDepthFunc.xhtml

Returns: the depth testing function for this sprite batch

◆ getDestinationBlendFactor()

GLenum cugl::SpriteBatch::getDestinationBlendFactor ( ) const

inline

Returns the destination blending factor

By default this value is GL_ONE_MINUS_SRC_ALPHA. For other options, see

 https://www.opengl.org/sdk/docs/man/html/glBlendFunc.xhtml

Returns: the destination blending factor

◆ getGradient()

std::shared_ptr<Gradient> cugl::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 applied textures, and use the first two attrbutes of the color attribute in SpriteVertex2 as texture coordinates. The last two coordinates (z and w) can used for minor feather adjustments in linear gradients (for smooth stroke effects).

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::SpriteBatch::getPerspective ( ) const

inline

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::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<Shader>& cugl::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

◆ getSourceBlendFactor()

GLenum cugl::SpriteBatch::getSourceBlendFactor ( ) const

inline

Returns the source blending factor

By default this value is GL_SRC_ALPHA. For other options, see

 https://www.opengl.org/sdk/docs/man/html/glBlendFunc.xhtml

Returns: the source blending factor

◆ getTexture()

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

inline

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()

unsigned int cugl::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::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::SpriteBatch::init ( const std::shared_ptr< Shader > & 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::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::SpriteBatch::init	(	unsigned int	capacity,
		const std::shared_ptr< Shader > &	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::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::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/10]

void cugl::SpriteBatch::outline	(	const Mesh< SpriteVertex2 > &	mesh,
		const Mat4 &	transform,
		bool	tint = `true`
	)

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

This method provides more fine tuned control over texture coordinates that the other fill 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. If depth testing is on, all vertices will be the current depth.

The triangulation will be determined by the mesh indices. If necessary, these can be generated via one of the triangulation factories SimpleTriangulator or ComplexTriangulator.

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

◆ outline() [2/10]

void cugl::SpriteBatch::outline	(	const Mesh< SpriteVertex3 > &	mesh,
		const Mat4 &	transform,
		bool	tint = `true`
	)

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

This method provides more fine tuned control over texture coordinates that the other fill 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. This method will use the depth of each vertex and ignore the sprite batch depth

The triangulation will be determined by the mesh indices. If necessary, these can be generated via one of the triangulation factories SimpleTriangulator or ComplexTriangulator.

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

◆ outline() [3/10]

void cugl::SpriteBatch::outline ( const Poly2 & poly )

Outlines the given polygon with the current color and texture.

The polygon path will be determined by the indices in poly. The indices should be a multiple of two, preferably generated by the factories PolyFactory or PolySplineFactory.

The drawing will be a wireframe of a polygon, but the lines are textured. 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 outlines the rectangle.

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.

If depth testing is on, all vertices will be the current depth.

Parameters

poly	The polygon to outline

◆ outline() [4/10]

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

Outlines the given polygon with the current color and texture.

The polygon will be offset by the given position.

The polygon path will be determined by the indices in poly. The indices should be a multiple of two, preferably generated by the factories PolyFactory or PolySplineFactory.

The drawing will be a wireframe of a polygon, but the lines are textured. 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 outlines the rectangle.

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.

If depth testing is on, all vertices will be the current depth.

Parameters

poly	The polygon to outline
offset	The polygon offset

◆ outline() [5/10]

void cugl::SpriteBatch::outline	(	const Poly2 &	poly,
		const Vec2	origin,
		const Mat4 &	transform
	)

Outlines the given polygon 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 path will be determined by the indices in poly. The indices should be a multiple of two, preferably generated by the factories PolyFactory or PolySplineFactory.

The drawing will be a wireframe of a polygon, but the lines are textured. 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 outlines the rectangle.

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.

If depth testing is on, all vertices will be the current depth.

Parameters

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

◆ outline() [6/10]

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

Outlines the given polygon 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 path will be determined by the indices in poly. The indices should be a multiple of two, preferably generated by the factories PolyFactory or PolySplineFactory.

The drawing will be a wireframe of a polygon, but the lines are textured. 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 outlines the rectangle.

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.

If depth testing is on, all vertices will be the current depth.

Parameters

poly	The polygon to outline
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

◆ outline() [7/10]

void cugl::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.

If depth testing is on, all vertices will be the current depth.

Parameters

rect	The rectangle to outline

◆ outline() [8/10]

void cugl::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.

If depth testing is on, all vertices will be the current depth.

Parameters

rect	The rectangle to outline
offset	The rectangle offset

◆ outline() [9/10]

void cugl::SpriteBatch::outline	(	const Rect	rect,
		const Vec2	origin,
		const Mat4 &	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.

If depth testing is on, all vertices will be the current depth.

Parameters

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

◆ outline() [10/10]

void cugl::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.

If depth testing is on, all vertices will be the current depth.

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

◆ setBlendEquation()

void cugl::SpriteBatch::setBlendEquation ( GLenum equation )

Sets the blending equation for this sprite batch

The enum must be a standard ones supported by OpenGL. See

 https://www.opengl.org/sdk/docs/man/html/glBlendEquation.xhtml

However, this setter does not do any error checking to verify that the input is valid. By default, the equation is GL_FUNC_ADD.

Parameters

equation Specifies how source and destination colors are combined

◆ setBlendFunc()

void cugl::SpriteBatch::setBlendFunc	(	GLenum	srcFactor,
		GLenum	dstFactor
	)

Sets the blending function for this sprite batch

The enums are the standard ones supported by OpenGL. See

 https://www.opengl.org/sdk/docs/man/html/glBlendFunc.xhtml

However, this setter does not do any error checking to verify that the enums are valid. By default, srcFactor is GL_SRC_ALPHA while dstFactor is GL_ONE_MINUS_SRC_ALPHA. This corresponds to non-premultiplied alpha blending.

Parameters

srcFactor	Specifies how the source blending factors are computed
dstFactor	Specifies how the destination blending factors are computed.

◆ setBlurStep()

void cugl::SpriteBatch::setBlurStep ( GLuint step )

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

This sprite batch supports a simple 9-step blur. The blur samples from the center pixel and 8 other pixels around it in a box. The blur step is the number of pixels away to sample. So a 1-step blur samples from the immediate neighbor pixels. On most textures a 5-step blur has very noticeable affects.

This is not a full-featured Gaussian blur. In particular, large step values 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.

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

Parameters

step	The blur step in pixels

◆ setColor()

void cugl::SpriteBatch::setColor ( const Color4f 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

◆ setDepth()

void cugl::SpriteBatch::setDepth ( float depth )

inline

Sets the current depth of this sprite batch.

The depth value is appended to all 2d shapes drawn by this sprite batch. If depth testing is enabled, this can allow the sprite batch to draw shapes out of order. This value is 0 by default.

Parameters

depth The current depth of this sprite batch.

◆ setDepthFunc()

void cugl::SpriteBatch::setDepthFunc ( GLenum function )

Sets the depth testing function for this sprite batch

The enum must be a standard ones supported by OpenGL. See

 https://www.opengl.org/sdk/docs/man/html/glDepthFunc.xhtml

However, this setter does not do any error checking to verify that the input is valid.

To disable depth testing, set the function to GL_ALWAYS. GL_ALWAYS is the initial default value.

Parameters

function Specifies how to accept fragments by depth value

◆ setGradient()

void cugl::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 applied textures, and use the first two attrbutes of the color attribute in SpriteVertex2 as texture coordinates. The last two coordinates (z and w) can used for minor feather adjustments in linear gradients (for smooth stroke effects).

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::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::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::SpriteBatch::setShader ( const std::shared_ptr< Shader > & 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

◆ setTexture()

void cugl::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

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

include/cugl/render/CUSpriteBatch.h

Public Member Functions

Static Public Member Functions

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]

◆ end()

◆ fill() [1/10]

◆ fill() [2/10]

◆ fill() [3/10]

◆ fill() [4/10]

◆ fill() [5/10]

◆ fill() [6/10]

◆ fill() [7/10]

◆ fill() [8/10]

◆ fill() [9/10]

◆ fill() [10/10]

◆ flush()

◆ getBlendEquation()

◆ getBlurStep()

◆ getCallsMade()

◆ getColor()

◆ getDepth()

◆ getDepthFunc()

◆ getDestinationBlendFactor()

◆ getGradient()

◆ getPerspective()

◆ getScissor()

◆ getShader()

◆ getSourceBlendFactor()

◆ getTexture()

◆ getVerticesDrawn()

◆ init() [1/4]

◆ init() [2/4]

◆ init() [3/4]

◆ init() [4/4]

◆ isDrawing()

◆ isReady()

◆ outline() [1/10]

◆ outline() [2/10]

◆ outline() [3/10]

◆ outline() [4/10]

◆ outline() [5/10]

◆ outline() [6/10]

◆ outline() [7/10]

◆ outline() [8/10]

◆ outline() [9/10]

◆ outline() [10/10]

◆ setBlendEquation()

◆ setBlendFunc()

◆ setBlurStep()

◆ setColor()

◆ setDepth()

◆ setDepthFunc()