iOS Developer Library — Prerelease

Developer

SpriteKit Framework Reference SKShader Class Reference

Options
Deployment Target:

On This Page
Language:

SKShader

An SKShader object holds a custom OpenGL ES fragment shader. Shader objects are used to customize the drawing behavior of many different kinds of nodes in Sprite Kit.

To use a custom shader, create an SKShader object and provide the source for the custom fragment shader. If your shader needs to provide uniform state to the shader, create one or more SKUniform objects and associate them with the shader object. Then, assign the shader object to the shader property of any sprites that need the custom behavior.

Compiling a shader and the uniform data associated with it can be expensive. Because of this, you should:

  • Initialize shader objects when your game launches, not while the game is running.

  • Avoid changing the shader’s source or uniforms while your game is running. Either of these things recompiles the shader.

  • Share shader objects whenever possible. If multiple sprites need the same behavior, create one shader object and associate it with every sprite that needs that behavior. Do not create a separate shader for each sprite.

Creating a Custom Fragment Shader

Your fragment shader should be written in the OpenGL ES 2.0 shading language. Sprite Kit automatically does the necessary work to make sure this shader compiles correctly in both iOS and OS X. The shader object compiles your shader by appending the source code you provide to a preamble created by Sprite Kit. This preamble declares all of the standard Sprite Kit variables and functions, including declarations for any uniforms you have associated with the shader object. Table 1 describes the Sprite Kit symbols made available to your shader.

Table 1Predefined custom shader symbols

Symbol declaration

Type

Description

sampler2D u_texture;

Uniform

A sampler associated with the texture used to render the node.

float u_time;

Uniform

The elapsed time in the simulation.

vec2 u_sprite_size;

Uniform

The size of the sprite in pixels.

float u_path_length;

Uniform

This uniform is provided only when the shader is attached to an SKShapeNode object’s strokeShader property. The total length of the path in points.

vec2 v_tex_coord;

Varying

The coordinates used to access the texture. These are normalized so that the point (0.0,0.0) is in the bottom-left corner of the texture.

vec4 v_color_mix;

Varying

The premultiplied color value for the node being rendered.

float v_path_distance;

Varying

This varying is provided only when the shader is attached to an SKShapeNode object’s strokeShader property. The distance along the path in points.

vec4 SKDefaultShading()

Function

A function that provides the default behavior used by Sprite Kit.

Your shader should define a main() function. This function must set the gl_FragColor variable to a color value to use in the blend stage; typically the color value you return in this variable should already be premultiplied by the fragment’s alpha value.

Listing 1 shows a very simple fragment shader that provides the default shading behavior.

Listing 1Example shader
  1. void main()
  2. {
  3. gl_FragColor = SKDefaultShading();
  4. }
  • Creates a new shader object by loading the source for a fragment shader from a file stored in the app’s bundle.

    Declaration

    Swift

    convenience init(fileNamed name: String)

    Objective-C

    + (instancetype _Nonnull)shaderWithFileNamed:(NSString * _Nonnull)name

    Parameters

    name

    The name of the fragment shader to load. The file must be present in your app bundle with the same name and a .fsh file extension.

    Return Value

    A newly initialized shader object whose initial source is loaded from the shader file.

    Availability

    Available in iOS 8.0 and later.

  • Creates a new shader object using the specified source and uniform data.

    Declaration

    Objective-C

    + (instancetype _Nonnull)shaderWithSource:(NSString * _Nonnull)source uniforms:(NSArray<SKUniform *> * _Nonnull)uniforms

    Parameters

    source

    A string that holds the source for a fragment shader.

    uniforms

    A list of uniforms to add to the shader object.

    Return Value

    A newly initialized shader object.

    Availability

    Available in iOS 8.0 and later.

  • Creates a new shader object using the specified source code.

    Declaration

    Objective-C

    + (instancetype _Nonnull)shaderWithSource:(NSString * _Nonnull)source

    Parameters

    source

    A string that holds the source code for a fragment shader.

    Return Value

    A newly initialized shader object.

    Availability

    Available in iOS 8.0 and later.

  • Creates a new empty shader object.

    Declaration

    Objective-C

    + (instancetype _Nonnull)shader

    Return Value

    A newly initialized shader object.

    Discussion

    The shader is initialized without any source code or uniform data. You must assign source code to the shader before using it.

    Availability

    Available in iOS 8.0 and later.

    See Also

    source

  • Initializes a new shader object using the specified source and uniform data.

    Declaration

    Swift

    init(source source: String, uniforms uniforms: [SKUniform])

    Objective-C

    - (instancetype _Nonnull)initWithSource:(NSString * _Nonnull)source uniforms:(NSArray<SKUniform *> * _Nonnull)uniforms

    Parameters

    source

    A string that holds the initial source for the shader.

    uniforms

    A list of uniforms to add to the shader object.

    Return Value

    An initialized shader object.

    Availability

    Available in iOS 8.0 and later.

  • Initializes a new shader object using the specified source code.

    Declaration

    Swift

    init(source source: String)

    Objective-C

    - (instancetype _Nonnull)initWithSource:(NSString * _Nonnull)source

    Parameters

    source

    A string that holds the initial source for the shader.

    Return Value

    An initialized shader object.

    Availability

    Available in iOS 8.0 and later.

  • Adds a uniform to the shader object.

    Declaration

    Swift

    func addUniform(_ uniform: SKUniform)

    Objective-C

    - (void)addUniform:(SKUniform * _Nonnull)uniform

    Parameters

    uniform

    The new uniform object to add. The uniform object’s name must not already be in use by another uniform attached to the shader.

    Discussion

    The uniform variable is automatically accessible inside your shader; do not add a declaration for it in your shader’s source code. The uniform must be accessed in the fragment shader.

    Availability

    Available in iOS 8.0 and later.

  • Removes a uniform from the shader.

    Declaration

    Swift

    func removeUniformNamed(_ name: String)

    Objective-C

    - (void)removeUniformNamed:(NSString * _Nonnull)name

    Parameters

    name

    The name of the uniform to remove.

    Discussion

    If a uniform with that name does not exist in the shader, nothing happens.

    Availability

    Available in iOS 8.0 and later.

  • The list of uniforms associated with the shader.

    Declaration

    Swift

    var uniforms: [SKUniform]

    Objective-C

    @property(copy, nonnull) NSArray <SKUniform *> *uniforms

    Discussion

    This property is not read-only, so you can also use it to provide all of the uniforms in a single operation. Each of the uniforms should be uniquely named.

    Availability

    Available in iOS 8.0 and later.

  • Returns the uniform object corresponding to a particular uniform variable.

    Declaration

    Swift

    func uniformNamed(_ name: String) -> SKUniform?

    Objective-C

    - (SKUniform * _Nullable)uniformNamed:(NSString * _Nonnull)name

    Parameters

    name

    The name of the uniform to search for.

    Return Value

    The uniform object corresponding to the name, or nil if that uniform cannot be found.

    Availability

    Available in iOS 8.0 and later.

  • The source code for the shader.

    Declaration

    Swift

    var source: String?

    Objective-C

    @property(copy, nullable) NSString *source

    Discussion

    The source code for a shader object can be updated at runtime. However, recompiling the fragment shader can be an expensive operation.

    Availability

    Available in iOS 8.0 and later.