Inherits from NSObject
Declared in SPFragmentFilter.h

Overview

The SPFragmentFilter class is the base class for all filter effects in Sparrow.

All other filters of this package extend this class. You can attach them to any display object through the ‘filter’ property.

A fragment filter works in the following way: * The object that is filtered is rendered into a texture (in stage coordinates). * That texture is passed to the first filter pass. * Each pass processes the texture using a fragment shader (and optionally a vertex shader) to achieve a certain effect. * The output of each pass is used as the input for the next pass; if it’s the final pass, it will be rendered directly to the back buffer.

All of this is set up by the abstract SPFragmentFilter class. Concrete subclasses just need to override the protected methods ‘createPrograms’, ‘activateWithPass’ and (optionally) ‘deactivateWithPass’ to create and execute its custom shader code. Each filter can be configured to either replace the original object, or be drawn below or above it. This can be done through the ‘mode’ property, which accepts one of the enums defined in the ‘SPFragmentFilterMode’ enum.

Beware that each filter should be used only on one object at a time. Otherwise, it will get slower and require more resources; and caching will lead to undefined results.

SPFragmentFilter subclass category.

Tasks

Initialization

  • – initWithNumPasses:resolution:

    Initializes a fragment filter with the specified number of passes and resolution. This initializer must only be called by the initializer of a subclass. Designated Initializer.
  • – initWithNumPasses:

    Initializes a fragment filter with the specified number of passes and a resolution of 1.0f. This initializer must only be called by the initializer of a subclass.
  • – init

    Initializes a fragment filter with 1 pass and a resolution of 1.0f. This initializer must only be called by the initializer of a subclass.

Methods

  • – cache

    Caches the filter output into a SPTexture. An uncached filter is rendered in every frame; a cached filter only once. However, if the filtered object or the filter settings change, it has to be updated manually; to do that, call “cache” again.
  • – clearCache

    Clears the cached output of the filter. After calling this method, the filter will be executed once per frame again.
  • – renderObject:support:

    Applies the filter on a certain display object, rendering the output into the current render target. This method is called automatically by Sparrow’s rendering system for the object the filter is attached to.

Properties

  •   isCached

    Indicates if the filter is cached (via the “cache” method).

         property
  •   resolution

    The resolution of the filter texture. “1” means stage resolution, “0.5” half the stage resolution. A lower resolution saves memory and execution time(depending on the GPU), but results in a lower output quality. Values greater than 1 are allowed; such values might make sense for a cached filter when it is scaled up. @default 1

         property
  •   mode

    The filter mode, which is one of the constants defined in the ‘SPFragmentFilterMode’ enum. (default: SPFragmentFilterModeReplace)

         property
  •   offsetX

    Use the x-offset to move the filter output to the right or left.

         property
  •   offsetY

    Use the y-offset to move the filter output to the top or bottom.

         property

Subclasses Methods

  • – createPrograms

    Subclasses must override this method and use it to create their fragment and vertex shaders.
  • – activateWithPass:texture:mvpMatrix:

    Subclasses must override this method and use it to activate their shader program. The ‘activate’ call directly precedes the call to ‘glDrawElements’.
  • – deactivateWithPass:texture:

    This method is called directly after ‘glDrawElements’. If you need to clean up any resources, you can do so in this method.
  • + standardVertexShader

    The standard vertex shader code. It will be used automatically if you don’t create a custom vertex shader yourself.
  • + standardFragmentShader

    The standard fragment shader code. It just forwards the texture color to the output.
  •   marginX

    The x-margin will extend the size of the filter texture along the x-axis. Useful when the filter will “grow” the rendered object.

         property
  •   marginY

    The y-margin will extend the size of the filter texture along the y-axis. Useful when the filter will “grow” the rendered object.

         property
  •   numPasses

    The number of passes the filter is applied. The “activate” and “deactivate” methods will be called that often.

         property
  •   vertexPosID

    The ID of the vertex buffer attribute that stores the vertex position.

         property
  •   texCoordsID

    The ID of the vertex buffer attribute that stores the SPTexture coordinates.

         property

Properties

isCached

Indicates if the filter is cached (via the “cache” method).

@property (nonatomic, readonly) BOOL isCached

Discussion

Indicates if the filter is cached (via the “cache” method).

Declared In

SPFragmentFilter.h

marginX

The x-margin will extend the size of the filter texture along the x-axis. Useful when the filter will “grow” the rendered object.

@property (nonatomic, assign) float marginX

Discussion

The x-margin will extend the size of the filter texture along the x-axis. Useful when the filter will “grow” the rendered object.

Declared In

SPFragmentFilter.h

marginY

The y-margin will extend the size of the filter texture along the y-axis. Useful when the filter will “grow” the rendered object.

@property (nonatomic, assign) float marginY

Discussion

The y-margin will extend the size of the filter texture along the y-axis. Useful when the filter will “grow” the rendered object.

Declared In

SPFragmentFilter.h

mode

The filter mode, which is one of the constants defined in the ‘SPFragmentFilterMode’ enum. (default: SPFragmentFilterModeReplace)

@property (nonatomic, assign) SPFragmentFilterMode mode

Discussion

The filter mode, which is one of the constants defined in the ‘SPFragmentFilterMode’ enum. (default: SPFragmentFilterModeReplace)

Declared In

SPFragmentFilter.h

numPasses

The number of passes the filter is applied. The “activate” and “deactivate” methods will be called that often.

@property (nonatomic, assign) int numPasses

Discussion

The number of passes the filter is applied. The “activate” and “deactivate” methods will be called that often.

Declared In

SPFragmentFilter.h

offsetX

Use the x-offset to move the filter output to the right or left.

@property (nonatomic, assign) float offsetX

Discussion

Use the x-offset to move the filter output to the right or left.

Declared In

SPFragmentFilter.h

offsetY

Use the y-offset to move the filter output to the top or bottom.

@property (nonatomic, assign) float offsetY

Discussion

Use the y-offset to move the filter output to the top or bottom.

Declared In

SPFragmentFilter.h

resolution

The resolution of the filter texture. “1” means stage resolution, “0.5” half the stage resolution. A lower resolution saves memory and execution time(depending on the GPU), but results in a lower output quality. Values greater than 1 are allowed; such values might make sense for a cached filter when it is scaled up. @default 1

@property (nonatomic, assign) float resolution

Discussion

The resolution of the filter texture. “1” means stage resolution, “0.5” half the stage resolution. A lower resolution saves memory and execution time(depending on the GPU), but results in a lower output quality. Values greater than 1 are allowed; such values might make sense for a cached filter when it is scaled up. @default 1

Declared In

SPFragmentFilter.h

texCoordsID

The ID of the vertex buffer attribute that stores the SPTexture coordinates.

@property (nonatomic, assign) int texCoordsID

Discussion

The ID of the vertex buffer attribute that stores the SPTexture coordinates.

Declared In

SPFragmentFilter.h

vertexPosID

The ID of the vertex buffer attribute that stores the vertex position.

@property (nonatomic, assign) int vertexPosID

Discussion

The ID of the vertex buffer attribute that stores the vertex position.

Declared In

SPFragmentFilter.h

Class Methods

standardFragmentShader

The standard fragment shader code. It just forwards the texture color to the output.

+ (NSString *)standardFragmentShader

Discussion

The standard fragment shader code. It just forwards the texture color to the output.

Declared In

SPFragmentFilter.h

standardVertexShader

The standard vertex shader code. It will be used automatically if you don’t create a custom vertex shader yourself.

+ (NSString *)standardVertexShader

Discussion

The standard vertex shader code. It will be used automatically if you don’t create a custom vertex shader yourself.

Declared In

SPFragmentFilter.h

Instance Methods

activateWithPass:texture:mvpMatrix:

Subclasses must override this method and use it to activate their shader program. The ‘activate’ call directly precedes the call to ‘glDrawElements’.

- (void)activateWithPass:(int)pass texture:(SPTexture *)texture mvpMatrix:(SPMatrix *)matrix

Discussion

Subclasses must override this method and use it to activate their shader program. The ‘activate’ call directly precedes the call to ‘glDrawElements’.

Declared In

SPFragmentFilter.h

cache

Caches the filter output into a SPTexture. An uncached filter is rendered in every frame; a cached filter only once. However, if the filtered object or the filter settings change, it has to be updated manually; to do that, call “cache” again.

- (void)cache

Discussion

Caches the filter output into a SPTexture. An uncached filter is rendered in every frame; a cached filter only once. However, if the filtered object or the filter settings change, it has to be updated manually; to do that, call “cache” again.

Declared In

SPFragmentFilter.h

clearCache

Clears the cached output of the filter. After calling this method, the filter will be executed once per frame again.

- (void)clearCache

Discussion

Clears the cached output of the filter. After calling this method, the filter will be executed once per frame again.

Declared In

SPFragmentFilter.h

createPrograms

Subclasses must override this method and use it to create their fragment and vertex shaders.

- (void)createPrograms

Discussion

Subclasses must override this method and use it to create their fragment and vertex shaders.

Declared In

SPFragmentFilter.h

deactivateWithPass:texture:

This method is called directly after ‘glDrawElements’. If you need to clean up any resources, you can do so in this method.

- (void)deactivateWithPass:(int)pass texture:(SPTexture *)texture

Discussion

This method is called directly after ‘glDrawElements’. If you need to clean up any resources, you can do so in this method.

Declared In

SPFragmentFilter.h

init

Initializes a fragment filter with 1 pass and a resolution of 1.0f. This initializer must only be called by the initializer of a subclass.

- (instancetype)init

Discussion

Initializes a fragment filter with 1 pass and a resolution of 1.0f. This initializer must only be called by the initializer of a subclass.

Declared In

SPFragmentFilter.h

initWithNumPasses:

Initializes a fragment filter with the specified number of passes and a resolution of 1.0f. This initializer must only be called by the initializer of a subclass.

- (instancetype)initWithNumPasses:(int)numPasses

Discussion

Initializes a fragment filter with the specified number of passes and a resolution of 1.0f. This initializer must only be called by the initializer of a subclass.

Declared In

SPFragmentFilter.h

initWithNumPasses:resolution:

Initializes a fragment filter with the specified number of passes and resolution. This initializer must only be called by the initializer of a subclass. Designated Initializer.

- (instancetype)initWithNumPasses:(int)numPasses resolution:(float)resolution

Discussion

Initializes a fragment filter with the specified number of passes and resolution. This initializer must only be called by the initializer of a subclass. Designated Initializer.

Declared In

SPFragmentFilter.h

renderObject:support:

Applies the filter on a certain display object, rendering the output into the current render target. This method is called automatically by Sparrow’s rendering system for the object the filter is attached to.

- (void)renderObject:(SPDisplayObject *)object support:(SPRenderSupport *)support

Discussion

Applies the filter on a certain display object, rendering the output into the current render target. This method is called automatically by Sparrow’s rendering system for the object the filter is attached to.

Declared In

SPFragmentFilter.h