iOS Developer Library — Prerelease

Developer

SpriteKit Framework Reference SKCropNode Class Reference

Options
Deployment Target:

On This Page
Language:

SKCropNode

An SKCropNode crops the pixels drawn by its children so that only some of the pixels are rendered to the parent’s framebuffer.

A crop node is useful for implementing cockpit views, controls, and other game indicators, as well as any effect where a set of nodes should be drawn only inside a specific part of a scene. Figure 1 shows how a crop node works. It uses the rocket ship art shown on the left as a mask for a sprite drawn as a child of the crop node shown on the right.

Figure 1A crop node performing a masking operation image: ../Art/ss4-crop_2x.png

The cropped area is specified using a mask. The mask is not a fixed image. The mask is rendered from a node, just like other content in Sprite Kit. This means a crop node can use simple masks derived from a piece of artwork, but it can also use more sophisticated masks. For example, here are some ways you might specify a mask:

  • An untextured sprite that limits content to a rectangular portion of the scene.

  • A textured sprite is a precise per-pixel mask. But consider also the benefits of a nonuniformly scaled texture. You could use a nonuniformly scaled texture to create a mask for a resizable user-interface element (such as a health bar) and then fill the masked area with dynamic content.

  • A collection of nodes can dynamically generate a complex mask that changes each time the frame is rendered.

To use a crop node, add child nodes as you would for any other node. Then set the crop node’s maskNode property to point to another node. When the scene is rendered, the crop mask renders its mask node and uses the resulting mask to determine which pixels of its children should be rendered to the parent’s framebuffer.

Listing 1 shows a simple use of a mask. This code loads a mask image from a texture in the app bundle. A portion of the scene’s content is then rendered as children of the crop node, using the mask to prevent it from overdrawing the portion of the screen that the game uses to show controls.

Listing 1Creating a crop node
  1. SKCropNode *cropNode = [[SKCropNode alloc] init];
  2. cropNode.maskNode = [[SKSpriteNode alloc] initWithImageNamed:@"cockpitMask"];
  3. [cropNode addChild: sceneContentNode];
  4. [self addChild:cropNode];
  5. [self addChild:gameControlNodes];

When the crop node’s children are rendered, the mask node is first rendered and used to crop the node’s children.

  • The node used to determine the crop node’s mask.

    Declaration

    Swift

    var maskNode: SKNode?

    Objective-C

    @property(nonatomic, retain, nullable) SKNode *maskNode

    Discussion

    The node supplied to the crop node must not be a child of another node; however, it may have children of its own.

    When the crop node’s contents are rendered, the crop node first draws its mask into a private buffer. Then, it renders its children. When rendering its children, each pixel is verified against the corresponding pixel in the mask. If the pixel in the mask has an alpha value of less than 0.05, the image pixel is masked out. Any pixel not rendered by the mask node is automatically masked out.

    The default value of this property is nil, which indicates that the child nodes should not be cropped.

    Availability

    Available in iOS 7.0 and later.