iOS Developer Library

Developer

SpriteKit Framework Reference SKEffectNode Class Reference

Options
Deployment Target:

On This Page
Language:

SKEffectNode

Inheritance


Conforms To


Import Statement


Swift

import SpriteKit

Objective-C

@import SpriteKit;

Availability


Available in iOS 7.0 and later.

An SKEffectNode object renders its children into a buffer and optionally applies a Core Image filter to this rendered output. Use effect nodes to incorporate sophisticated special effects into a scene or to cache the contents of a static subtree for faster rendering performance.

Each time a new frame is rendered using the effect node, the effect node follows these steps:

  1. The effect node draws its children into a private framebuffer.

  2. It applies a Core Image effect to the private framebuffer. This stage is optional; see the filter and shouldEnableEffects properties.

  3. It blends the contents of its private framebuffer into its parent’s framebuffer, using one of the standard sprite blend modes.

  4. It discards its private framebuffer. This step is optional; see the shouldRasterize property.

Example: Applying a Special Effect

One possible use for effect nodes is to apply special effects to a node’s children, as shown in Figure 1. In this example, the effect node’s children are two sprites that provide lighting information. The effect node accumulates the effects of these lights, applies a blur filter to soften the resulting image, and then uses a multiply blend mode to apply this lighting to a wall texture.

Figure 1Effect nodes applying special effects to a node’s children image: ../Art/ss5-effect_2x.png

Here’s how the scene generates this lighting effect:

  1. The scene has two children. The first is a textured sprite that represents the ground. The second is an effect node to apply lighting.

    • self.lightingNode = [[SKEffectNode alloc] init];
  2. The effect node’s children are sprite nodes rendered using an additive blend mode.

    • SKSpriteNode *light = [SKSpriteNode spriteNodeWithTexture:lightTexture];
    • light.blendMode = SKBlendModeAdd;
    • ...
    • [self.lightingNode addChild: light];
  3. The effect node includes a filter effect to soften the lighting.

    • - (CIFilter *)blurFilter { CIFilter *filter = [CIFilter filterWithName:@"CIBoxBlur"]; // 3 [filter setDefaults]; [filter setValue:[NSNumber numberWithFloat:20] forKey:@"inputRadius"]; return filter; }
    • self.lightingNode.filter = [self blurFilter];

    If you specify a Core Image filter, it must be a filter that takes a single input image and produces a single output image.

  4. The effect node uses a multiplication blend mode to apply its lighting effect to the scene’s framebuffer.

    • self.lightingNode.blendMode = SKBlendModeMultiply;

Scenes Are Effect Nodes

The SKScene class is a subclass of SKEffectNode. This means that any scene can apply a filter to its contents. Although applying filters can be very expensive—not all filters are well designed for interactive effects—experimentation can help you find some interesting ways to use them.

Caching May Improve Performance of Static Content

An effect node normally discards its private framebuffer after rendering is complete. Rendering the content is necessary because it typically changes every frame. However, if the content is static, this is unnecessary. It might make more sense to keep the rendered framebuffer instead of discarding it. If the content of the effect node is static, set the node’s shouldRasterize property to YEStrue. Setting this property causes the following changes in behavior:

  • The framebuffer is not discarded at the end of rasterization. This also means that more memory is being used by the effect node, and rendering may take slightly longer.

  • When a new frame is rendered, the framebuffer is rendered only if the contents of the effect node’s descendants have changed.

  • If the effect node has a Core Image filter, changes to its properties no longer automatically update the framebuffer. You can force it to be updated by setting the shouldRasterize property to NOfalse.

You can use effect nodes to cache static content even when you aren’t applying a filter to the rendered image. This technique can be useful when the contents of a subtree are static and expensive to render.

  • A Boolean value that determines whether the effect node applies the filter to its children as they are drawn.

    Declaration

    Swift

    var shouldEnableEffects: Bool

    Objective-C

    @property(nonatomic) BOOL shouldEnableEffects

    Discussion

    If the value of this property is YEStrue, the effect node applies the filter and blends the results. If the value is NOfalse, the effect node is ignored and its children are rendered normally. The default value is NOfalse.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • filter filter Property

    The Core Image filter to apply.

    Declaration

    Swift

    var filter: CIFilter?

    Objective-C

    @property(nonatomic, retain) CIFilter *filter

    Discussion

    The Core Image filter must have a single inputImage parameter and produce a single outputImage parameter. The default value is nil. If the value is nil and the effect node is enabled, no filtering takes place. However, its children are still rendered in a separate pass and blended to the parent’s framebuffer.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • A Boolean value that determines whether the effect node automatically sets the filter’s image center.

    Declaration

    Swift

    var shouldCenterFilter: Bool

    Objective-C

    @property(nonatomic) BOOL shouldCenterFilter

    Discussion

    If the value of this property is YEStrue and the filter has an inputCenter parameter, the effect node automatically sets the filter’s input center to the effect node’s origin. The default value is YEStrue.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • blendMode blendMode Property

    The blend mode used to draw the filtered image into the parent’s framebuffer.

    Declaration

    Swift

    var blendMode: SKBlendMode

    Objective-C

    @property(nonatomic) SKBlendMode blendMode

    Discussion

    The default value is SKBlendModeAlpha.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.

  • shader shader Property

    A custom shader that is called when the effect node is blended into the parent’s framebuffer.

    Declaration

    Swift

    var shader: SKShader?

    Objective-C

    @property(nonatomic, retain) SKShader *shader

    Discussion

    The default value is nil, meaning that default blending behavior executes. If a shader is specified, it is called when the rasterized image is blended into the parent’s framebuffer.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 8.0 and later.

  • A Boolean value that indicates whether the results of rendering the child nodes should be cached.

    Declaration

    Swift

    var shouldRasterize: Bool

    Objective-C

    @property(nonatomic) BOOL shouldRasterize

    Discussion

    If the value of this property is YEStrue, the effect node caches the filtered image for use in future frames. If the value is NOfalse, then Sprite Kit discards the rendered image and redraws it from scratch the next time the node is rendered. The default value is NOfalse. Caching the rendered image uses more memory and may take more time to render. However, if the effect node’s descendants rarely change, caching can improve performance.

    When caching is enabled, changes to the effect node’s children trigger updates to the cached image in the next frame of animation. However, changing the filter’s properties does not.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 7.0 and later.