com.cyphercove.gdx.flexbatch

Class FlexBatch<T extends Batchable>

java.lang.Object

com.cyphercove.gdx.flexbatch.FlexBatch<T>

Type Parameters:

T - The type of Batchable that is returned when acquiring one with draw(). This must match the class type that is passed to the constructor.

All Implemented Interfaces:

com.badlogic.gdx.utils.Disposable

Direct Known Subclasses:

CompliantBatch

public class FlexBatch<T extends Batchable>
extends java.lang.Object
implements com.badlogic.gdx.utils.Disposable

Draws batched Batchable objects, optimizing the drawing process by combining them into a single Mesh. FlexBatch can be customized to batch almost any kind of small object by defining how to draw the object in a Batchable implementation. Most of the available Batchable types in this library are designed for subclassing, to minimize the work needed to define a Batchable. A FlexBatch is instantiated using a Batchable class that defines the types of Batchables it can draw. A FlexBatch must be disposed of when no longer used to avoid leaking memory.

Batchables can only be drawn between calls to begin() and end(). The current queue of Batchables can be flushed to screen immediately with a call to flush(). Flushes also occur automatically when end() is called or if any relevant OpenGL state changes or drawing changes are made (such as drawing a Batchable with different Texture(s) than the last, changing blend function parameters, changing the shader used, or changing the projection matrix).

Batchable objects can be passed to the draw(Batchable) method to queue them for drawing. Alternatively, the draw() method can be called to acquire a Batchable matching the class passed to the constructor parameter. This Batchable can be immediately customized for drawing, and will be automatically queued for drawing on the next call to any FlexBatch method.

A single FlexBatch might be capable of drawing more than one type of Batchable. See draw(Batchable) for details.

Unlike SpriteBatch, no default shader is provided automatically. A call to setShader(ShaderProgram) must be made before any drawing can occur. The attribute names to be used in the vertex shader are defined by the Batchable. By default FlexBatch automatically passes its combined transform and projection matrices to the shader with the uniform name "u_projTrans". This can be customized by overriding applyMatrices(). By default, FlexBatch automatically passes texture uniforms to the shader, with a count defined by the template Batchable class. The texture uniforms are given the names "u_texture0", "u_texture1", etc., but this can be customized by overriding applyTextureUniforms().

Other uniforms can be manually applied to the shader in between calls to begin() and end(). Take care of when these changes are made in relation to batch flushes, as only the most recently set uniforms are used when a flush occurs.

This API is based on SpriteBatch and NewSpriteBatch from the LibGDX project.

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.Class<T>	batchableType
int	renderCalls Number of render calls since the last begin().
int	totalRenderCalls Number of rendering calls, ever.

Constructor Summary

Constructors

Constructor and Description
FlexBatch(java.lang.Class<T> batchableType, int maxVertices, int maxTriangles) Construct a FlexBatch capable of drawing the given Batchable type and other compatible Batchables (ones with the same + * VertexAttributes or subset of beginning VertexAttributes).

Method Summary

Modifier and Type	Method and Description
protected void	applyMatrices() Called only while drawing.
protected void	applyTextureUniforms() Sets shader uniform values for the textures.
void	begin()
void	disableBlending()
void	dispose()
T	draw()
protected void	draw(Batchable.FixedSizeBatchable batchable, float[] explicitVertices, int offset, int count, int vertexSize) Draws explicit vertex data, using only the render context and Texture parameter(s) of the passed in FixedSizeBatchable.
void	draw(Batchable batchable) Queues a Batchable for drawing.
protected void	draw(T batchable, float[] explicitVertices, int verticesOffset, int vertexDataCount, int vertexSize, short[] explicitTriangles, int trianglesOffset, int trianglesCount) Draws explicit vertex data, using only the render context and Texture parameter(s) of the passed-in Batchable.
void	enableBlending()
void	end()
void	flush()
int	getBatchableCapacity()
int	getBlendDstFunc()
int	getBlendDstFuncAlpha()
int	getBlendSrcFunc()
int	getBlendSrcFuncAlpha()
com.badlogic.gdx.math.Matrix4	getProjectionMatrix()
RenderContextAccumulator	getRenderContext() Returns the render context, which can be used to modify drawing parameters for the next batch flush.
com.badlogic.gdx.graphics.glutils.ShaderProgram	getShader()
com.badlogic.gdx.math.Matrix4	getTransformMatrix()
int	getVertexCapacity()
boolean	isBlendingEnabled()
boolean	isDrawing()
void	repeatPreviousFlush() Flushes the same triangles drawn the last time a flush occurred.
void	setBlendFunction(int srcFunc, int dstFunc)
void	setBlendFunctionSeparate(int srcColorFunc, int dstColorFunc, int srcAlphaFunc, int dstAlphaFunc)
void	setProjectionMatrix(com.badlogic.gdx.math.Matrix4 projection)
void	setShader(com.badlogic.gdx.graphics.glutils.ShaderProgram shader)
void	setTransformMatrix(com.badlogic.gdx.math.Matrix4 transform)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

batchableType

public final java.lang.Class<T extends Batchable> batchableType

renderCalls

public int renderCalls

Number of render calls since the last begin().

totalRenderCalls

public int totalRenderCalls

Number of rendering calls, ever. Will not be reset unless set manually.

Constructor Detail

FlexBatch

public FlexBatch(java.lang.Class<T> batchableType,
                 int maxVertices,
                 int maxTriangles)

Construct a FlexBatch capable of drawing the given Batchable type and other compatible Batchables (ones with the same + * VertexAttributes or subset of beginning VertexAttributes). The FlexBatch will not be limited to FixedSizeBatchables.

Parameters:

batchableType - The type of Batchable that defines the VertexAttributes supported by this FlexBatch, and the + * default Batchable type drawn by the draw() method.

maxVertices - The number of vertices this FlexBatch can batch at once. Maximum of 32767. If the Batchable is a FixedSizeBatchable and 0 is used for maxTriangles, this value will be rounded down to a multiple of the Batchable's size.

maxTriangles - The number of triangles this FlexBatch can batch at once, or 0 to optimize this FlexBatch to draw only FixedSizeBatchables.

Method Detail

begin

public void begin()

end

public void end()

getRenderContext

public RenderContextAccumulator getRenderContext()

Returns the render context, which can be used to modify drawing parameters for the next batch flush. Changes to the render parameters will override any that have been set by batchables that are queued and awaiting the next flush, with the exception of the last batchable drawn with draw(), if there is one. Subsequent batchables might reverse these changes in their Batchable.prepareContext(RenderContextAccumulator, int, int) methods, and therefore trigger a flush before they are queued. For example, Quad3D manages blending parameters per batchable, and therefore setting blend parameters on the RenderContextAccumulator will have no effect.

Returns:

the render context, whose parameters may be set to affect drawing.

draw

public T draw()

Returns:

A Batchable that will automatically be queued for drawing upon the next call to draw(), flush(), or end(). The Batchable will be of the same type as the batchableType of this FlexBatch.

Do not cache and reuse the returned Batchable.

draw

public void draw(Batchable batchable)

Queues a Batchable for drawing. Certain characteristics of the supplied Batchable class must match those of the batchableType of this FlexBatch:

• Vertex attributes must be the same or be a beginning subset of the FlexBatch's type.
• Batchable.prepareSharedContext(RenderContextAccumulator) must perform equivalent changes.
• This FlexBatch may have been set up to draw only FixedSizeBatchables in the constructor.

The above criteria are not checked. If the supplied Batchable class's VertexAttributes) do not match those of the batchableType, a different shader may be needed for this Batchable, and some vertex data will go unused. The docs for the built-in Batchables explain their compatibility.

Parameters:

batchable -

draw

protected void draw(Batchable.FixedSizeBatchable batchable,
                    float[] explicitVertices,
                    int offset,
                    int count,
                    int vertexSize)

Draws explicit vertex data, using only the render context and Texture parameter(s) of the passed in FixedSizeBatchable. The restrictions on the supplied Batchable class are the same as those in draw(Batchable).

Parameters:

batchable - A Batchable that defines the render context and textures to draw, but not the actual vertex data.

explicitVertices - Pre-computed vertex data that is large enough for the Batchable type.

offset - Starting index of the data in the array.

count - The number of array elements to pass. This must be a multiple of the size of the FixedSizeBatchable, and is not checked.

vertexSize - The size of the vertices in the data (from the VertexAttributes. Must be the same or smaller than the size of the vertices for the Batchable type. If smaller, the data for the excess vertex attributes will be garbage, but this may be acceptable if the current shader doesn't use them. It is assumed that the VertexAttributes being drawn match the first of the VertexAttributes of the Batchable type.

draw

protected void draw(T batchable,
                    float[] explicitVertices,
                    int verticesOffset,
                    int vertexDataCount,
                    int vertexSize,
                    short[] explicitTriangles,
                    int trianglesOffset,
                    int trianglesCount)

Draws explicit vertex data, using only the render context and Texture parameter(s) of the passed-in Batchable. This must only be called if this FlexBatch is not limited to drawing FixedSizedBatchables. The restrictions on the supplied Batchable class are the same as those in draw(Batchable).

The batch must have enough total capacity for the entire set of vertices and triangles. This is not checked.

Parameters:

batchable - A Batchable that defines the render context and textures to draw, but not the actual vertex data.

explicitVertices - Pre-computed vertex data that is large enough for the Batchable type.

verticesOffset - Starting index of the data in the array.

vertexDataCount - The number of array elements to pass. This must be the correct size for the Batchable type, and is not checked.

vertexSize - The size of the vertices in the data (from the VertexAttributes. Must be the same or smaller than the size of the vertices for the Batchable type. If smaller, the data for the excess vertex attributes will be garbage, but this may be acceptable if the current shader doesn't use them. It is assumed that the VertexAttributes being drawn match the first of the VertexAttributes of the Batchable type.

explicitTriangles - Vertex index data for the drawn item, starting from index 0.

trianglesOffset - Starting index of the data in the array.

trianglesCount - The number of array elements to pass. Must be a multiple of 3.

flush

public void flush()

repeatPreviousFlush

public void repeatPreviousFlush()

Flushes the same triangles drawn the last time a flush occurred. This is an expert method with no error checks. It provides a way to avoid re-submitting the batchable data for drawing if none of them have changed since the last flush and nothing in the render context has changed either (textures, blend modes, etc.). Note that there are several reasons the previous flush may have occurred other than a manual call to flush(), so care must be taken to be aware of these and avoid them if necessary.

getShader

public com.badlogic.gdx.graphics.glutils.ShaderProgram getShader()

setShader

public void setShader(com.badlogic.gdx.graphics.glutils.ShaderProgram shader)

disableBlending

public void disableBlending()

enableBlending

public void enableBlending()

setBlendFunction

public void setBlendFunction(int srcFunc,
                             int dstFunc)

setBlendFunctionSeparate

public void setBlendFunctionSeparate(int srcColorFunc,
                                     int dstColorFunc,
                                     int srcAlphaFunc,
                                     int dstAlphaFunc)

getBlendSrcFunc

public int getBlendSrcFunc()

getBlendDstFunc

public int getBlendDstFunc()

getBlendSrcFuncAlpha

public int getBlendSrcFuncAlpha()

getBlendDstFuncAlpha

public int getBlendDstFuncAlpha()

isBlendingEnabled

public boolean isBlendingEnabled()

getProjectionMatrix

public com.badlogic.gdx.math.Matrix4 getProjectionMatrix()

getTransformMatrix

public com.badlogic.gdx.math.Matrix4 getTransformMatrix()

setProjectionMatrix

public void setProjectionMatrix(com.badlogic.gdx.math.Matrix4 projection)

setTransformMatrix

public void setTransformMatrix(com.badlogic.gdx.math.Matrix4 transform)

applyMatrices

protected void applyMatrices()

Called only while drawing. Recalculates the matrices and sets their values to shader uniforms. The default implementation combines the projection and transform matrices and sets them to a single uniform named "u_projTrans".

applyTextureUniforms

protected void applyTextureUniforms()

Sets shader uniform values for the textures. The default implementation uses the uniform name "u_texture" with the texture unit appended. For example, if the Batchable type supports two textures, uniforms will be set for "u_texture0" and "u_texture1".

isDrawing

public boolean isDrawing()

Returns:

Whether this batch is between begin() and end() calls.

getVertexCapacity

public int getVertexCapacity()

Returns:

The number of vertices that can be drawn between flushes.

getBatchableCapacity

public int getBatchableCapacity()

Returns:

The number of batchables that can be drawn between flushes, or 0 if the batchable is not a Batchable.FixedSizeBatchable.

dispose

public void dispose()

Specified by:

dispose in interface com.badlogic.gdx.utils.Disposable