Inherits from SPDisplayObject : SPEventDispatcher : NSObject
Declared in SPQuadBatch.h

Overview

Optimizes rendering of a number of quads with an identical state.

The majority of all rendered objects in Sparrow are quads. In fact, all the default leaf nodes of Sparrow are quads (the SPImage and SPQuad classes). The rendering of those quads can be accelerated by a big factor if all quads with an identical state are sent to the GPU in just one call. That’s what the SPQuadBatch class can do.

The flatten method of the SPSprite class uses this class internally to optimize its rendering performance. In most situations, it is recommended to stick with flattened sprites, because they are easier to use. Sometimes, however, it makes sense to use the SPQuadBatch class directly: e.g. you can add one quad multiple times to a quad batch, whereas you can only add it once to a sprite. Furthermore, this class does not dispatch ADDED or ADDED_TO_STAGE events when a quad is added, which makes it more lightweight.

One QuadBatch object is bound to a specific render state. The first object you add to a batch will decide on the QuadBatch’s state, that is: its texture, its settings for smoothing and repetition, and if it’s tinted (colored vertices and/or transparency). When you reset the batch, it will accept a new state on the next added quad.

Tasks

Initialization

  • – initWithCapacity:

    Initialize a QuadBatch with a certain capacity. The batch will grow dynamically if it exceeds this value. Designated Initializer.
  • – init

    Initialize a QuadBatch with a capacity of 16 quads.
  • + quadBatch

    Create a new, empty quad batch.

Methods

  • – reset

    Resets the batch. The vertex- and index-buffers keep their size, so that they can be reused.
  • – addQuad:

    Adds a quad or image. Make sure you only add quads with an equal state.
  • – addQuad:alpha:

    Adds a quad or image using a custom alpha value (ignoring the quad’s original alpha). Make sure you only add quads with an equal state.
  • – addQuad:alpha:blendMode:

    Adds a quad or image to the batch, using custom alpha and blend mode values (ignoring the quad’s original values). Make sure you only add quads with an equal state.
  • – addQuad:alpha:blendMode:matrix:

    Adds a quad or image to the batch, using custom alpha and blend mode values (ignoring the quad’s original values) and transforming each vertex by a certain transformation matrix. Make sure you only add quads with an equal state.
  • – addQuadBatch:

    Adds another quad batch to this batch.
  • – addQuadBatch:alpha:

    Adds another quad batch to this batch, using a custom alpha value (ignoring the batch’s original alpha).
  • – addQuadBatch:alpha:blendMode:

    Adds another quad batch to this batch, using custom alpha and blend mode values (ignoring the batch’s original values). Just like the addQuad: method, you have to make sure that you only add batches with an equal state.
  • – addQuadBatch:alpha:blendMode:matrix:

    Adds another quad batch to this batch, using custom alpha and blend mode values (ignoring the batch’s original values) and transforming each vertex by a certain transformation matrix. Just like the addQuad: method, you have to make sure that you only add batches with an equal state.
  • – isStateChangeWithTinted:texture:alpha:premultipliedAlpha:blendMode:numQuads:

    Indicates if specific quads can be added to the batch without causing a state change. A state change occurs if the quad uses a different base texture, has a different smoothing, repeat or ‘tinted’ setting, or if the batch is full (one batch can contain up to 8192 quads).
  • – renderWithMvpMatrix:alpha:blendMode:

    Renders the batch with custom alpha and blend mode values, as well as a custom mvp matrix.
  • – renderWithMvpMatrix:

    Renders the batch with a custom mvp matrix.
  • + compileObject:

    Analyses an object that is made up exclusively of quads (or other containers) and creates an array of SPQuadBatch objects representing it. This can be used to render the container very efficiently. The ‘flatten’-method of the SPSprite class uses this method internally. */
  • + compileObject:intoArray:

    Analyses an object that is made up exclusively of quads (or other containers) and saves the resulting quad batches into the specified an array; batches inside that array are reused.

Properties

  •   numQuads

    The number of quads that has been added to the batch.

         property
  •   tinted

    Indicates if any vertices have a non-white color or are not fully opaque.

         property
  •   texture

    The current texture of the batch, if there is one.

         property
  •   premultipliedAlpha

    Indicates if the rgb values are stored premultiplied with the alpha value.

         property

Properties

numQuads

The number of quads that has been added to the batch.

@property (nonatomic, readonly) int numQuads

Discussion

The number of quads that has been added to the batch.

Declared In

SPQuadBatch.h

premultipliedAlpha

Indicates if the rgb values are stored premultiplied with the alpha value.

@property (nonatomic, readonly) BOOL premultipliedAlpha

Discussion

Indicates if the rgb values are stored premultiplied with the alpha value.

Declared In

SPQuadBatch.h

texture

The current texture of the batch, if there is one.

@property (nonatomic, readonly) SPTexture *texture

Discussion

The current texture of the batch, if there is one.

Declared In

SPQuadBatch.h

tinted

Indicates if any vertices have a non-white color or are not fully opaque.

@property (nonatomic, readonly) BOOL tinted

Discussion

Indicates if any vertices have a non-white color or are not fully opaque.

Declared In

SPQuadBatch.h

Class Methods

compileObject:

Analyses an object that is made up exclusively of quads (or other containers) and creates an array of SPQuadBatch objects representing it. This can be used to render the container very efficiently. The ‘flatten’-method of the SPSprite class uses this method internally. */

+ (NSMutableArray *)compileObject:(SPDisplayObject *)object

Discussion

Analyses an object that is made up exclusively of quads (or other containers) and creates an array of SPQuadBatch objects representing it. This can be used to render the container very efficiently. The ‘flatten’-method of the SPSprite class uses this method internally. */

Declared In

SPQuadBatch.h

compileObject:intoArray:

Analyses an object that is made up exclusively of quads (or other containers) and saves the resulting quad batches into the specified an array; batches inside that array are reused.

+ (NSMutableArray *)compileObject:(SPDisplayObject *)object intoArray:(NSMutableArray *)quadBatches

Discussion

Analyses an object that is made up exclusively of quads (or other containers) and saves the resulting quad batches into the specified an array; batches inside that array are reused.

Declared In

SPQuadBatch.h

quadBatch

Create a new, empty quad batch.

+ (instancetype)quadBatch

Discussion

Create a new, empty quad batch.

Declared In

SPQuadBatch.h

Instance Methods

addQuad:

Adds a quad or image. Make sure you only add quads with an equal state.

- (void)addQuad:(SPQuad *)quad

Discussion

Adds a quad or image. Make sure you only add quads with an equal state.

Declared In

SPQuadBatch.h

addQuad:alpha:

Adds a quad or image using a custom alpha value (ignoring the quad’s original alpha). Make sure you only add quads with an equal state.

- (void)addQuad:(SPQuad *)quad alpha:(float)alpha

Discussion

Adds a quad or image using a custom alpha value (ignoring the quad’s original alpha). Make sure you only add quads with an equal state.

Declared In

SPQuadBatch.h

addQuad:alpha:blendMode:

Adds a quad or image to the batch, using custom alpha and blend mode values (ignoring the quad’s original values). Make sure you only add quads with an equal state.

- (void)addQuad:(SPQuad *)quad alpha:(float)alpha blendMode:(uint)blendMode

Discussion

Adds a quad or image to the batch, using custom alpha and blend mode values (ignoring the quad’s original values). Make sure you only add quads with an equal state.

Declared In

SPQuadBatch.h

addQuad:alpha:blendMode:matrix:

Adds a quad or image to the batch, using custom alpha and blend mode values (ignoring the quad’s original values) and transforming each vertex by a certain transformation matrix. Make sure you only add quads with an equal state.

- (void)addQuad:(SPQuad *)quad alpha:(float)alpha blendMode:(uint)blendMode matrix:(SPMatrix *)matrix

Discussion

Adds a quad or image to the batch, using custom alpha and blend mode values (ignoring the quad’s original values) and transforming each vertex by a certain transformation matrix. Make sure you only add quads with an equal state.

Declared In

SPQuadBatch.h

addQuadBatch:

Adds another quad batch to this batch.

- (void)addQuadBatch:(SPQuadBatch *)quadBatch

Discussion

Adds another quad batch to this batch.

Declared In

SPQuadBatch.h

addQuadBatch:alpha:

Adds another quad batch to this batch, using a custom alpha value (ignoring the batch’s original alpha).

- (void)addQuadBatch:(SPQuadBatch *)quadBatch alpha:(float)alpha

Discussion

Adds another quad batch to this batch, using a custom alpha value (ignoring the batch’s original alpha).

Declared In

SPQuadBatch.h

addQuadBatch:alpha:blendMode:

Adds another quad batch to this batch, using custom alpha and blend mode values (ignoring the batch’s original values). Just like the addQuad: method, you have to make sure that you only add batches with an equal state.

- (void)addQuadBatch:(SPQuadBatch *)quadBatch alpha:(float)alpha blendMode:(uint)blendMode

Discussion

Adds another quad batch to this batch, using custom alpha and blend mode values (ignoring the batch’s original values). Just like the addQuad: method, you have to make sure that you only add batches with an equal state.

Declared In

SPQuadBatch.h

addQuadBatch:alpha:blendMode:matrix:

Adds another quad batch to this batch, using custom alpha and blend mode values (ignoring the batch’s original values) and transforming each vertex by a certain transformation matrix. Just like the addQuad: method, you have to make sure that you only add batches with an equal state.

- (void)addQuadBatch:(SPQuadBatch *)quadBatch alpha:(float)alpha blendMode:(uint)blendMode matrix:(SPMatrix *)matrix

Discussion

Adds another quad batch to this batch, using custom alpha and blend mode values (ignoring the batch’s original values) and transforming each vertex by a certain transformation matrix. Just like the addQuad: method, you have to make sure that you only add batches with an equal state.

Declared In

SPQuadBatch.h

init

Initialize a QuadBatch with a capacity of 16 quads.

- (instancetype)init

Discussion

Initialize a QuadBatch with a capacity of 16 quads.

Declared In

SPQuadBatch.h

initWithCapacity:

Initialize a QuadBatch with a certain capacity. The batch will grow dynamically if it exceeds this value. Designated Initializer.

- (instancetype)initWithCapacity:(int)capacity

Discussion

Initialize a QuadBatch with a certain capacity. The batch will grow dynamically if it exceeds this value. Designated Initializer.

Declared In

SPQuadBatch.h

isStateChangeWithTinted:texture:alpha:premultipliedAlpha:blendMode:numQuads:

Indicates if specific quads can be added to the batch without causing a state change. A state change occurs if the quad uses a different base texture, has a different smoothing, repeat or ‘tinted’ setting, or if the batch is full (one batch can contain up to 8192 quads).

- (BOOL)isStateChangeWithTinted:(BOOL)tinted texture:(SPTexture *)texture alpha:(float)alpha premultipliedAlpha:(BOOL)pma blendMode:(uint)blendMode numQuads:(int)numQuads

Discussion

Indicates if specific quads can be added to the batch without causing a state change. A state change occurs if the quad uses a different base texture, has a different smoothing, repeat or ‘tinted’ setting, or if the batch is full (one batch can contain up to 8192 quads).

Declared In

SPQuadBatch.h

renderWithMvpMatrix:

Renders the batch with a custom mvp matrix.

- (void)renderWithMvpMatrix:(SPMatrix *)matrix

Discussion

Renders the batch with a custom mvp matrix.

Declared In

SPQuadBatch.h

renderWithMvpMatrix:alpha:blendMode:

Renders the batch with custom alpha and blend mode values, as well as a custom mvp matrix.

- (void)renderWithMvpMatrix:(SPMatrix *)matrix alpha:(float)alpha blendMode:(uint)blendMode

Discussion

Renders the batch with custom alpha and blend mode values, as well as a custom mvp matrix.

Declared In

SPQuadBatch.h

reset

Resets the batch. The vertex- and index-buffers keep their size, so that they can be reused.

- (void)reset

Discussion

Resets the batch. The vertex- and index-buffers keep their size, so that they can be reused.

Declared In

SPQuadBatch.h