Class

SKCropNode

A node that masks pixels drawn by its children so that only some are rendered to the parent’s frame buffer.

Declaration

class SKCropNode : SKNode

Overview

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 1

A crop node performing a masking operation

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 SpriteKit. 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 1

Creating a crop node

SKCropNode *cropNode = [[SKCropNode alloc] init];
cropNode.maskNode = [[SKSpriteNode alloc] initWithImageNamed:@"cockpitMask"];
[cropNode addChild: sceneContentNode];
[self addChild:cropNode];
[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.

Topics

Setting the Mask Filter

var maskNode: SKNode?

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

See Also

Nodes That Draw Content

class SKSpriteNode

A node that draws a rectangular texture, image or color.

class SKShapeNode

A node that renders a shape defined by a Core Graphics path.

class SKLabelNode

A node that displays a text label.

class SKVideoNode

A node that displays video content.

class SKReferenceNode

A node that creates its children from an archived collection of other nodes.