Inherits from NSObject
Declared in SPRenderSupport.h

Overview

A class that contains helper methods simplifying OpenGL rendering.

An SPRenderSupport instance is passed to any render: method. It saves information about the current render state, like the alpha value, modelview matrix, and blend mode.

It also keeps a list of quad batches, which can be used to render a high number of quads very efficiently; only changes in the state of added quads trigger OpenGL draw calls.

Furthermore, several static helper methods can be used for different needs whenever some OpenGL processing is required.

Tasks

Methods

  • – nextFrame

    Resets the render state stack to the default.
  • – batchQuad:

    Adds a quad or image to the current batch of unrendered quads. If there is a state change, all previous quads are rendered at once, and the batch is reset. Note that the values for alpha and blend mode are taken from the current render state, not the quad.
  • – finishQuadBatch

    Renders the current quad batch and resets it.
  • – purgeBuffers

    Clears all vertex and index buffers, releasing the associated memory. Useful in low-memory situations. Don’t call from within a render method!
  • – clear

    Clears OpenGL’s color buffer.
  • – clearWithColor:

    Clears OpenGL’s color buffer with a specified color.
  • – clearWithColor:alpha:

    Clears OpenGL’s color buffer with a specified color and alpha.
  • + clearWithColor:alpha:

    Clears OpenGL’s color buffer with a specified color and alpha.
  • + checkForOpenGLError

    Checks for an OpenGL error. If there is one, it is logged an the error code is returned.
  • – addDrawCalls:

    Raises the number of draw calls by a specific value. Call this method in custom render methods to keep the statistics display in sync.
  • – setupOrthographicProjectionWithLeft:right:top:bottom:

    Sets up the projection matrix for ortographic 2D rendering.

State Manipulation

Clipping

  • – pushClipRect:

    The clipping rectangle can be used to limit rendering in the current render target to a certain area. This method expects the rectangle in stage coordinates. Internally, it uses the ‘glScissor’ command of OpenGL, which works with pixel coordinates. Any pushed rectangle is intersected with the previous rectangle; the method returns that intersection.
  • – popClipRect

    Restores the clipping rectangle that was last pushed to the stack.
  • – applyClipRect

    Updates the scissor rectangle using the current clipping rectangle. This method is called automatically when either the projection matrix or the clipping rectangle changes.

Properties

  •   projectionMatrix

    Returns the current projection matrix. CAUTION: Use with care! Each call returns the same instance.

         property
  •   mvpMatrix

    Calculates the product of modelview and projection matrix. CAUTION: Use with care! Each call returns the same instance.

         property
  •   modelviewMatrix

    Returns the current modelview matrix. CAUTION: Use with care! Returns not a copy, but the internally used instance.

         property
  •   alpha

    The current (accumulated) alpha value.

         property
  •   blendMode

    The current blend mode.

         property
  •   renderTarget

    The texture that is currently being rendered into, or ‘nil’ to render into the back buffer. If you set a new target, it is immediately activated.

         property
  •   numDrawCalls

    Indicates the number of OpenGL ES draw calls since the last call to nextFrame.

         property

Properties

alpha

The current (accumulated) alpha value.

@property (nonatomic, assign) float alpha

Discussion

The current (accumulated) alpha value.

Declared In

SPRenderSupport.h

blendMode

The current blend mode.

@property (nonatomic, assign) uint blendMode

Discussion

The current blend mode.

Declared In

SPRenderSupport.h

modelviewMatrix

Returns the current modelview matrix. CAUTION: Use with care! Returns not a copy, but the internally used instance.

@property (nonatomic, readonly) SPMatrix *modelviewMatrix

Discussion

Returns the current modelview matrix. CAUTION: Use with care! Returns not a copy, but the internally used instance.

Declared In

SPRenderSupport.h

mvpMatrix

Calculates the product of modelview and projection matrix. CAUTION: Use with care! Each call returns the same instance.

@property (nonatomic, readonly) SPMatrix *mvpMatrix

Discussion

Calculates the product of modelview and projection matrix. CAUTION: Use with care! Each call returns the same instance.

Declared In

SPRenderSupport.h

numDrawCalls

Indicates the number of OpenGL ES draw calls since the last call to nextFrame.

@property (nonatomic, readonly) int numDrawCalls

Discussion

Indicates the number of OpenGL ES draw calls since the last call to nextFrame.

Declared In

SPRenderSupport.h

projectionMatrix

Returns the current projection matrix. CAUTION: Use with care! Each call returns the same instance.

@property (nonatomic, copy) SPMatrix *projectionMatrix

Discussion

Returns the current projection matrix. CAUTION: Use with care! Each call returns the same instance.

Declared In

SPRenderSupport.h

renderTarget

The texture that is currently being rendered into, or ‘nil’ to render into the back buffer. If you set a new target, it is immediately activated.

@property (nonatomic, strong) SPTexture *renderTarget

Discussion

The texture that is currently being rendered into, or ‘nil’ to render into the back buffer. If you set a new target, it is immediately activated.

Declared In

SPRenderSupport.h

Class Methods

checkForOpenGLError

Checks for an OpenGL error. If there is one, it is logged an the error code is returned.

+ (uint)checkForOpenGLError

Discussion

Checks for an OpenGL error. If there is one, it is logged an the error code is returned.

Declared In

SPRenderSupport.h

clearWithColor:alpha:

Clears OpenGL’s color buffer with a specified color and alpha.

+ (void)clearWithColor:(uint)color alpha:(float)alpha

Discussion

Clears OpenGL’s color buffer with a specified color and alpha.

Declared In

SPRenderSupport.h

Instance Methods

addDrawCalls:

Raises the number of draw calls by a specific value. Call this method in custom render methods to keep the statistics display in sync.

- (void)addDrawCalls:(int)count

Discussion

Raises the number of draw calls by a specific value. Call this method in custom render methods to keep the statistics display in sync.

Declared In

SPRenderSupport.h

applyBlendModeForPremultipliedAlpha:

Activates the current blend mode.

- (void)applyBlendModeForPremultipliedAlpha:(BOOL)pma

Discussion

Activates the current blend mode.

Declared In

SPRenderSupport.h

applyClipRect

Updates the scissor rectangle using the current clipping rectangle. This method is called automatically when either the projection matrix or the clipping rectangle changes.

- (void)applyClipRect

Discussion

Updates the scissor rectangle using the current clipping rectangle. This method is called automatically when either the projection matrix or the clipping rectangle changes.

Declared In

SPRenderSupport.h

batchQuad:

Adds a quad or image to the current batch of unrendered quads. If there is a state change, all previous quads are rendered at once, and the batch is reset. Note that the values for alpha and blend mode are taken from the current render state, not the quad.

- (void)batchQuad:(SPQuad *)quad

Discussion

Adds a quad or image to the current batch of unrendered quads. If there is a state change, all previous quads are rendered at once, and the batch is reset. Note that the values for alpha and blend mode are taken from the current render state, not the quad.

Declared In

SPRenderSupport.h

clear

Clears OpenGL’s color buffer.

- (void)clear

Discussion

Clears OpenGL’s color buffer.

Declared In

SPRenderSupport.h

clearWithColor:

Clears OpenGL’s color buffer with a specified color.

- (void)clearWithColor:(uint)color

Discussion

Clears OpenGL’s color buffer with a specified color.

Declared In

SPRenderSupport.h

clearWithColor:alpha:

Clears OpenGL’s color buffer with a specified color and alpha.

- (void)clearWithColor:(uint)color alpha:(float)alpha

Discussion

Clears OpenGL’s color buffer with a specified color and alpha.

Declared In

SPRenderSupport.h

finishQuadBatch

Renders the current quad batch and resets it.

- (void)finishQuadBatch

Discussion

Renders the current quad batch and resets it.

Declared In

SPRenderSupport.h

nextFrame

Resets the render state stack to the default.

- (void)nextFrame

Discussion

Resets the render state stack to the default.

Declared In

SPRenderSupport.h

popClipRect

Restores the clipping rectangle that was last pushed to the stack.

- (void)popClipRect

Discussion

Restores the clipping rectangle that was last pushed to the stack.

Declared In

SPRenderSupport.h

popState

Restores the previous render state.

- (void)popState

Discussion

Restores the previous render state.

Declared In

SPRenderSupport.h

purgeBuffers

Clears all vertex and index buffers, releasing the associated memory. Useful in low-memory situations. Don’t call from within a render method!

- (void)purgeBuffers

Discussion

Clears all vertex and index buffers, releasing the associated memory. Useful in low-memory situations. Don’t call from within a render method!

Declared In

SPRenderSupport.h

pushClipRect:

The clipping rectangle can be used to limit rendering in the current render target to a certain area. This method expects the rectangle in stage coordinates. Internally, it uses the ‘glScissor’ command of OpenGL, which works with pixel coordinates. Any pushed rectangle is intersected with the previous rectangle; the method returns that intersection.

- (SPRectangle *)pushClipRect:(SPRectangle *)clipRect

Discussion

The clipping rectangle can be used to limit rendering in the current render target to a certain area. This method expects the rectangle in stage coordinates. Internally, it uses the ‘glScissor’ command of OpenGL, which works with pixel coordinates. Any pushed rectangle is intersected with the previous rectangle; the method returns that intersection.

Declared In

SPRenderSupport.h

pushStateWithMatrix:alpha:blendMode:

Adds a new render state to the stack. The passed matrix is prepended to the modelview matrix; the alpha value is multiplied with the current alpha; the blend mode replaces the existing mode (except SPBlendModeAuto, which will cause the current mode to prevail).

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

Discussion

Adds a new render state to the stack. The passed matrix is prepended to the modelview matrix; the alpha value is multiplied with the current alpha; the blend mode replaces the existing mode (except SPBlendModeAuto, which will cause the current mode to prevail).

Declared In

SPRenderSupport.h

setupOrthographicProjectionWithLeft:right:top:bottom:

Sets up the projection matrix for ortographic 2D rendering.

- (void)setupOrthographicProjectionWithLeft:(float)left right:(float)right top:(float)top bottom:(float)bottom

Discussion

Sets up the projection matrix for ortographic 2D rendering.

Declared In

SPRenderSupport.h