cugl::SpriteBatch Class Reference

#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 Color4 color)
const Color4	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	setSrcBlendFunc (GLenum func)
void	setSrcBlendFunc (GLenum rgb, GLenum alpha)
GLenum	getSrcBlendRGB () const
GLenum	getSrcBlendAlpha () const
void	setDstBlendFunc (GLenum func)
void	setDstBlendFunc (GLenum rgb, GLenum alpha)
GLenum	getDstBlendRGB () const
GLenum	getDstBlendAlpha () const
void	setBlendEquation (GLenum equation)
GLenum	getBlendEquation () const
void	setDepth (float depth)
float	getDepth () const
void	setBlur (GLfloat radius)
GLfloat	getBlur () const
void	setStencilEffect (StencilEffect effect)
StencilEffect	getStencilEffect () const
void	clearStencil ()
void	clearHalfStencil (bool lower)
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 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< SpriteVertex2 > &mesh, const Vec2 position, bool tint=true)
void	drawMesh (const Mesh< SpriteVertex2 > &mesh, const Affine2 &transform, bool tint=true)
void	drawMesh (const std::vector< SpriteVertex2 > &vertices, const Vec2 position, bool tint=true)
void	drawMesh (const std::vector< SpriteVertex2 > &vertices, const Affine2 &transform, bool tint=true)
void	drawMesh (const SpriteVertex2 *vertices, size_t size, const Vec2 position, bool tint=true)
void	drawMesh (const SpriteVertex2 *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< 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 SpriteVertex2 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 Shader and VertexBuffer.

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.

clearHalfStencil()

void cugl::SpriteBatch::clearHalfStencil

(

bool

lower

)

Clears half of the stencil buffer.

This method clears only one of the two halves of the stencil buffer. See StencilEffect for a discussion of how the two halves of the stencil buffer work.

Parameters

lower

Whether to clear the lower stencil buffer

clearStencil()

void cugl::SpriteBatch::clearStencil

(

)

Clears the stencil buffer.

This method clears both halves of the stencil buffer: both upper and lower. See StencilEffect for a discussion of how the two halves of the stencil buffer work.

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

If depth testing is on, all vertices will use the current sprite batch 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 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.

If depth testing is on, all vertices will use the current sprite batch 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 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.

If depth testing is on, all vertices will use the current sprite batch 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 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.

If depth testing is on, all vertices will use the current sprite batch 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 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).

If depth testing is on, all vertices will use the current sprite batch 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 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.

If depth testing is on, all vertices will use the current sprite batch 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 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).

If depth testing is on, all vertices will use the current sprite batch 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 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).

If depth testing is on, all vertices will use the current sprite batch 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 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.

If depth testing is on, all vertices will use the current sprite batch 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 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.

If depth testing is on, all vertices will use the current sprite batch 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 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.

If depth testing is on, all vertices will use the current sprite batch 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 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.

If depth testing is on, all vertices will use the current sprite batch 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 use the current sprite batch 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 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).

If depth testing is on, all vertices will use the current sprite batch 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 use the current sprite batch 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 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).

If depth testing is on, all vertices will use the current sprite batch 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 use the current sprite batch 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 use the current sprite batch depth.

Parameters

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

drawMesh() [1/6]

void cugl::SpriteBatch::drawMesh	(	const Mesh< SpriteVertex2 > &	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. If depth testing is on, all vertices will be the current depth.

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.

If depth testing is on, all vertices will use the current sprite batch depth.

Parameters

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

drawMesh() [2/6]

void cugl::SpriteBatch::drawMesh	(	const Mesh< SpriteVertex2 > &	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. If depth testing is on, all vertices will be the current depth.

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.

If depth testing is on, all vertices will use the current sprite batch depth.

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::SpriteBatch::drawMesh	(	const SpriteVertex2 *	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. If depth testing is on, all vertices will be the current depth.

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. If depth testing is on, all vertices will use the current sprite batch depth.

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

Returns

the number of vertices added to the drawing buffer.

drawMesh() [4/6]

void cugl::SpriteBatch::drawMesh	(	const SpriteVertex2 *	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. If depth testing is on, all vertices will be the current depth.

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. If depth testing is on, all vertices will use the current sprite batch depth.

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

Returns

the number of vertices added to the drawing buffer.

drawMesh() [5/6]

void cugl::SpriteBatch::drawMesh ( const std::vector< SpriteVertex2 > &  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. If depth testing is on, all vertices will be the current depth.

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. If depth testing is on, all vertices will use the current sprite batch depth.

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

Returns

the number of vertices added to the drawing buffer.

drawMesh() [6/6]

void cugl::SpriteBatch::drawMesh ( const std::vector< SpriteVertex2 > &  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. If depth testing is on, all vertices will be the current depth.

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. If depth testing is on, all vertices will use the current sprite batch depth.

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

Returns

the number of vertices added to the drawing buffer.

drawText() [1/4]

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

If depth testing is on, the font glyphs will use the current sprite batch depth.

Parameters

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

drawText() [2/4]

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

If depth testing is on, the font glyphs will use the current sprite batch depth.

Parameters

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

drawText() [3/4]

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

If depth testing is on, the font glyphs will use the current sprite batch depth.

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

If depth testing is on, the font glyphs will use the current sprite batch depth.

Parameters

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

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/8]

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

If depth testing is on, all vertices will use the current sprite batch depth.

Parameters

poly	The polygon to draw

fill() [2/8]

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

If depth testing is on, all vertices will use the current sprite batch depth.

Parameters

poly	The polygon to draw
offset	The polygon offset

fill() [3/8]

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

If depth testing is on, all vertices will use the current sprite batch depth.

Parameters

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

fill() [4/8]

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

If depth testing is on, all vertices will use the current sprite batch 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() [5/8]

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 use the current sprite batch depth.

Parameters

rect	The rectangle to draw
offset	The rectangle offset

fill() [6/8]

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

If depth testing is on, all vertices will use the current sprite batch depth.

Parameters

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

fill() [7/8]

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 use the current sprite batch 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() [8/8]

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 use the current sprite batch 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.

If you play to apply any OpenGL functionality not directly supported by this sprite batch (e.g stencils), you MUST call this method first before applying your effects. In addition, you should call this again before restoring the OpenGL state.

getBlendEquation()

GLenum cugl::SpriteBatch::getBlendEquation

(

)

const

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

getBlur()

GLfloat cugl::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()

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 Color4 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

Returns the current depth of this sprite batch.

The depth value is appended to all 2d shapes drawn by this sprite batch.If this value is non-zero then depth testing is turned on. However, the exact depth function is up to you and should be set outside of this sprite batch.

Returns

the current depth of this sprite batch.

getDstBlendAlpha()

GLenum cugl::SpriteBatch::getDstBlendAlpha

(

)

const

Returns the destination blending function for the alpha component

By default this value is GL_ONE_MINUS_SRC_ALPHA, as sprite batches do not use premultiplied alpha. For other options, see

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

Returns

the destination blending function for the alpha component

getDstBlendRGB()

GLenum cugl::SpriteBatch::getDstBlendRGB

(

)

const

Returns the destination blending function for the RGB components

By default this value is GL_ONE_MINUS_SRC_ALPHA, as sprite batches do not use premultiplied alpha. For other options, see

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

Returns

the destination blending function for the RGB components

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 like applied textures, and use the gradient coordinates in SpriteVertex2 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::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::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

getSrcBlendAlpha()

GLenum cugl::SpriteBatch::getSrcBlendAlpha

(

)

const

Returns the source blending function for the alpha component

By default this value is GL_SRC_ALPHA, as sprite batches do not use premultiplied alpha. For other options, see

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

Returns

the source blending function for the alpha component

getSrcBlendRGB()

GLenum cugl::SpriteBatch::getSrcBlendRGB

(

)

const

Returns the source blending function for the RGB components

By default this value is GL_SRC_ALPHA, as sprite batches do not use premultiplied alpha. For other options, see

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

Returns

the source blending function for the RGB components

getStencilEffect()

StencilEffect cugl::SpriteBatch::getStencilEffect

(

)

const

Returns the current stencil effect

Stencil effects can be used to restrict the drawing region and are generally used to speed up the processing of non-convex shapes. See StencilEffect for the list of supported effects, as well as a discussion of how the two halves of the stencil buffer work.

This value should be set to StencilEffect#NATIVE (the default) if you wish to directly manipulate the OpenGL stencil. This is sometimes necessary for more complex effects.

Returns

the current stencil effect

getTexture()

const std::shared_ptr<Texture>& cugl::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()

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/8]

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

If depth testing is on, all vertices will use the current sprite batch depth.

Parameters

path	The path to outline

outline() [2/8]

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

If depth testing is on, all vertices will use the current sprite batch depth.

Parameters

path	The path to outline
offset	The path offset

outline() [3/8]

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

If depth testing is on, all vertices will use the current sprite batch depth.

Parameters

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

outline() [4/8]

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

If depth testing is on, all vertices will use the current sprite batch depth.

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::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 use the current sprite batch depth.

Parameters

rect	The rectangle to outline

outline() [6/8]

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 use the current sprite batch depth.

Parameters

rect	The rectangle to outline
offset	The rectangle offset

outline() [7/8]

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

If depth testing is on, all vertices will use the current sprite batch depth.

Parameters

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

outline() [8/8]

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 use the current sprite batch 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

setBlur()

void cugl::SpriteBatch::setBlur

(

GLfloat

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

setColor()

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

setDepth()

void cugl::SpriteBatch::setDepth

(

float

depth

)

Sets the current depth of this sprite batch.

The depth value is appended to all 2d shapes drawn by this sprite batch.If this value is non-zero then depth testing is turned on. However, the exact depth function is up to you and should be set outside of this sprite batch.

Parameters

depth

The current depth of this sprite batch.

setDstBlendFunc() [1/2]

void cugl::SpriteBatch::setDstBlendFunc ( GLenum  func )

inline

Sets the blending function for the destination color

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 this value is GL_ONE_MINUS_SRC_ALPHA, as sprite batches do not use premultiplied alpha.

Parameters

func	Specifies how the source color is blended

setDstBlendFunc() [2/2]

void cugl::SpriteBatch::setDstBlendFunc	(	GLenum	rgb,
		GLenum	alpha
	)

Sets the blending functions for the destination color

The enums are the standard ones supported by OpenGL. See

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

This version of the function allows you to specify different blending fuctions for the RGB and alpha components of the destiniation color. This setter does not do any error checking to verify that the enums are valid.

By default both values are GL_ONE_MINUS_SRC_ALPHA, as sprite batches do not use premultiplied alpha.

Parameters

rgb	The blend function for the source RGB components
alpha	The blend function for the source alpha component

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 like applied textures, and use the gradient coordinates in SpriteVertex2 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::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

setSrcBlendFunc() [1/2]

void cugl::SpriteBatch::setSrcBlendFunc ( GLenum  func )

inline

Sets the blending function for the source color

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 this value is GL_SRC_ALPHA, as sprite batches do not use premultiplied alpha.

Parameters

func	Specifies how the source color is blended

setSrcBlendFunc() [2/2]

void cugl::SpriteBatch::setSrcBlendFunc	(	GLenum	rgb,
		GLenum	alpha
	)

Sets the blending functions for the source color

The enums are the standard ones supported by OpenGL. See

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

This version of the function allows you to specify different blending fuctions for the RGB and alpha components of the source color. This setter does not do any error checking to verify that the enums are valid.

By default both values are GL_SRC_ALPHA, as sprite batches do not use premultiplied alpha.

Parameters

rgb	The blend function for the source RGB components
alpha	The blend function for the source alpha component

setStencilEffect()

void cugl::SpriteBatch::setStencilEffect

(

StencilEffect

effect

)

Sets the current stencil effect

Stencil effects can be used to restrict the drawing region and are generally used to speed up the processing of non-convex shapes. See StencilEffect for the list of supported effects, as well as a discussion of how the two halves of the stencil buffer work.

This value should be set to StencilEffect#NATIVE (the default) if you wish to directly manipulate the OpenGL stencil. This is sometimes necessary for more complex effects.

Parameters

effect

The current stencil effect

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