SPRenderSupport Class Reference
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
-
– 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). -
– popState
Restores the previous render state.
-
– applyBlendModeForPremultipliedAlpha:
Activates the current blend mode.
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
propertynextFrame
.
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
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