A node that masks pixels drawn by its children so that only some are rendered to the parent’s framebuffer.
- iOS 8.0+
- macOS 10.10+
- tvOS 9.0+
- watchOS 3.0+
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.
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.
When the crop node’s children are rendered, the mask node is first rendered and used to crop the node’s children.