Mac Developer Library

Developer

SceneKit Framework Reference

Introduction

Classes   Protocols   Other Reference  

SceneKit is an Objective-C framework for building apps and games that use 3D graphics, combining a high-performance rendering engine with a high-level, descriptive API. SceneKit supports the import, manipulation, and rendering of 3D assets. Unlike lower-level APIs such as OpenGL that require you to implement in precise detail the rendering algorithms that display a scene, SceneKit only requires descriptions of your scene’s contents and the actions or animations you want it to perform. To learn more about SceneKit, see Scene Kit Programming Guide.

Getting Started with SceneKit

SceneKit implements content as a hierarchical tree structure of nodes, also known as scene graph. A scene consists of a root node, which defines a coordinate space for the world of the scene, and other nodes that populate the world with visible content. SceneKit displays scenes in a view, processing the scene graph and performing animations before efficiently rendering each frame on the GPU.

Before working with SceneKit, you should be familiar with basic graphics concepts such as coordinate systems and the mathematics of three-dimensional geometry. SceneKit uses a right-handed coordinate system where (by default) the direction of view is along the negative z-axis, as illustrated in Figure I-1.

Figure I-1SceneKit coordinate system image: ../Art/3d_coordinate_system.pdf

Table I-1 lists a recommended reading order for the most important classes in SceneKit. Read about these classes before moving on to other classes in the framework and building your app or game.

Table I-1Important classes and protocols in SceneKit

Class / Protocol

Description

SCNView & SCNSceneRenderer

A view that displays (or renders) SceneKit content and a protocol that defines important methods for use with SceneKit views.

SCNScene

The container for all SceneKit content. You load a scene from a file created in a 3D authoring tool or create one programmatically, then display it in a view.

SCNNode

The basic building block of a scene. A hierarchy of nodes defines the logical structure of a scene, and you provide visible content by attaching geometries, lights, and cameras to nodes.

SCNGeometry

A three-dimensional object that can be attached to a node. A geometry (sometimes called a model or mesh) defines only the form or shape for a visible object. To define the surface appearance of the object you attach materials to it.

You can load geometries created in 3D authoring tools from a scene file or create them using SceneKit classes for primitive shapes, extruded 2D shapes and text, and custom vertex data.

SCNMaterial

A reusable definition of surface appearance properties for an object. Materials specify how a surface is colored or textured and how it responds to lights in the scene.

SCNLight

A light source that can be attached to a node, providing shading in the rendered scene.

SCNCamera

A virtual camera that can be attached to a node, providing a point of view for rendering a scene.

Animating SceneKit Content

SceneKit animation support is based on the Core Animation framework. (For background on Core Animation, read Core Animation Programming Guide.) Several SceneKit classes define animatable properties—you can create animations that transition smoothly between two values of the property. For example, animating a node’s opacity property fades the node’s visible content in or out. You can create animations implicitly or explicitly.

You create an animation implicitly by changing the value of an animatable property. SceneKit automatically combines all changes you make to a scene during one pass through the run loop into a single atomic operation called a transaction, represented by the SCNTransaction class. The default transaction’s duration is zero, so the changes you make to animatable properties occur immediately. However, if you increase the transaction’s animation duration, all changes to animatable properties automatically animate. Implicit animation is useful when you want to quickly animate a one-time change or animate several property changes together without writing a lot of animation code, as in Listing I-1 below. For more details on implicit animation, see SCNTransaction Class Reference.

Listing I-1Implicit animation that makes a block of text fall out of the scene while fading away

Swift

  • func fallAndFade(sender: AnyObject) {
  • SCNTransaction.setAnimationDuration(1.0)
  • textNode.position = SCNVector3(x: 0.0, y: -10.0, z: 0.0)
  • textNode.opacity = 0.0
  • }

Objective-C

  • - (IBAction)fallAndFade:(id)sender
  • {
  • [SCNTransaction setAnimationDuration:1.0];
  • _textNode.position = SCNVector3Make(0.0, -10.0, 0.0);
  • _textNode.opacity = 0.0;
  • }

For more complex animations, you can explicitly create an animation object and attach it to the scene element being animated. To explicitly create an animation, you choose a CAAnimation subclass for the type of animation you want to create, specify the property to be animated using key-value coding, then set animation parameters. You then set the animation in motion by attaching it to one or more elements of your scene, as shown in Listing I-2. Using different Core Animation classes you can combine or sequence several animations or create animations that interpolate a property’s value between several keyframe values. For details on creating animation objects, see Core Animation Programming Guide. For details on attaching animations to SceneKit objects, see SCNAnimatable Protocol Reference.

Listing I-2Explicit animation to vary the 3D extrusion depth of a block of text

Swift

  • let animation = CABasicAnimation(keyPath: "geometry.extrusionDepth")
  • animation.fromValue = 0.0
  • animation.toValue = 100.0
  • animation.duration = 1.0
  • animation.autoreverses = true
  • animation.repeatCount = Float.infinity
  • textNode.addAnimation(animation, forKey: "extrude")

Objective-C

  • CABasicAnimation *animation = [CABasicAnimation animationWithKeyPath:@"geometry.extrusionDepth"];
  • animation.fromValue = @0.0;
  • animation.toValue = @100.0;
  • animation.duration = 1.0;
  • animation.autoreverses = YES;
  • animation.repeatCount = INFINITY;
  • [_textNode addAnimation:animation forKey:@"extrude"];

SceneKit also uses CAAnimation objects for animations created using external 3D authoring tools and saved in scene files. For example, an artist might create a game character with animations for walking, jumping, and other actions. You incorporate these animations into your game by loading animation objects from the scene file using the SCNSceneSource class and attaching them to the SCNNode object that represents the game character.

Classes

Class

Abstract

NSObject

NSObject is the root class of most Objective-C class hierarchies.

SCNAction

An SCNAction object is an action that is executed by a node (SCNNode).

SCNAnimationEvent

You attach an SCNAnimationEvent object to an animation to execute a block at a specific time when the animation plays.

SCNCamera

An SCNCamera object manages camera attributes attached to a node.

SCNConstraint

A constraint automatically adjusts the transformation (position, rotation, and scale) of a node based on rules you define.

SCNIKConstraint

An SCNIKConstraint object automatically adjusts the orientations of one or more nodes in a specified hierarchy, applying inverse kinematics to make the chain reach toward a target point.

SCNLookAtConstraint

An SCNLookAtConstraint object automatically adjusts a node’s orientation so that it always points toward another node.

SCNTransformConstraint

An SCNTransformConstraint object runs a block that you specify to compute a new transformation (position, rotation, and scale) for each node affected by the constraint.

SCNGeometry

An SCNGeometry object represents a three-dimensional shape—a collection of vertices, normals and texture coordinates that define a surface, also known as a model or mesh.

SCNBox

An SCNBox geometry models a six-sided polyhedron whose faces are all rectangles.

SCNCapsule

An SCNCapsule geometry models a right circular cylinder whose ends are capped with hemispheres.

SCNCone

An SCNCone geometry models a right circular cone or frustum.

SCNCylinder

An SCNCylinder geometry models a right circular cylinder.

SCNFloor

An SCNFloor geometry models an infinite plane.

SCNPlane

An SCNPlane geometry models a rectangular, one-sided plane of specified width and height.

SCNPyramid

An SCNPyramid geometry models a right rectangular pyramid.

SCNShape

An SCNShape object is geometry that creates its contents from a two-dimensional path, optionally extruded to create a three-dimensional object.

SCNSphere

An SCNSphere geometry models a sphere (also known as a ball or globe).

SCNText

An SCNText object is a geometry that creates its contents from a string of text, rendered in 2D and optionally extruded to create a three-dimensional object.

SCNTorus

An SCNTorus geometry models a ring-shaped object.

SCNTube

An SCNTube geometry models a tube or pipe—a right circular cylinder with a circular hole along its central axis.

SCNGeometryElement

An SCNGeometryElement object describes how vertices are connected to form the surface of a three-dimensional object, or geometry.

SCNGeometrySource

An SCNGeometrySource object specifies per-vertex data for the set of vertices forming the surface of a three-dimensional object, or geometry.

SCNHitTestResult

Hit-testing is the process of finding elements of a scene located at a specified point, or along a specified line segment (or ray).

SCNLevelOfDetail

Use SCNLevelOfDetail objects to enable automatic substitution of alternate levels of detail for a geometry.

SCNLight

An SCNLight object represents a light source.

SCNMaterial

An SCNMaterial object manages the lighting and shading attributes associated with the surface of a geometry that define its appearance when rendered.

SCNMaterialProperty

An SCNMaterialProperty object represents the contents—color, texture, or other visual elements—of one of a material’s visual properties.

SCNMorpher

An SCNMorpher object deforms the surface of a node’s geometry, smoothly transitioning between a base geometry and one or more target geometries.

SCNNode

An SCNNode object represents a portion of a scene graph.

SCNParticlePropertyController

An SCNParticlePropertyController object uses Core Animation semantics to animate a property of the particles rendered by an SCNParticleSystem object.

SCNParticleSystem

An SCNParticleSystem object automatically creates, animates, and renders a system of particles—small image sprites—according to a high-level simulation whose general behavior you specify.

SCNPhysicsBehavior

An SCNPhysicsBehavior object defines a high-level behavior for one or more physics bodies, modifying the results of the physics simulation.

SCNPhysicsBallSocketJoint

An SCNPhysicsBallSocketJoint is a behavior that connects two physics bodies and allows them to pivot around each other in any direction.

SCNPhysicsHingeJoint

An SCNPhysicsHingeJoint is a behavior that connects two physics bodies and allows them to pivot around each other on a single axis.

SCNPhysicsSliderJoint

An SCNPhysicsSliderJoint is a behavior that connects two physics bodies and allows them to slide against each other and rotate around their connecting points.

SCNPhysicsVehicle

An SCNPhysicsVehicle object modifies SceneKit’s simulation of a physics body so that it behaves like a car, motorcycle, or other wheeled vehicle.

SCNPhysicsBody

An SCNPhysicsBody object is used to add physics simulation to a node.

SCNPhysicsContact

An SCNPhysicsContact object describes a contact between two physics bodies in your scene’s physics simulation.

SCNPhysicsField

An SCNPhysicsField object applies forces to objects in an area of effect within a scene.

SCNPhysicsShape

An SCNPhysicsShape object simulates the solid volume associated with an SCNPhysicsBody object for use in collision detection.

SCNPhysicsVehicleWheel

An SCNPhysicsVehicleWheel object defines the appearance and physical characteristics of an individual wheel associated with an SCNPhysicsVehicle behavior.

SCNPhysicsWorld

An SCNPhysicsWorld object simulates collisions and other physical properties in a scene.

SCNProgram

You use an SCNProgram object to perform custom rendering using shader programs written in the OpenGL Shading Language (GLSL).

SCNRenderer

An SCNRenderer object renders a SceneKit scene into an arbitrary OpenGL context.

SCNScene

An SCNScene object represents a three-dimensional scene.

SCNSceneSource

An SCNSceneSource object manages the data-reading tasks associated with loading scene contents from a file (or NSData object).

SCNSkinner

An SCNSkinner object provides access to portions of a node hierarchy used for skeletal animation.

SCNTechnique

An SCNTechnique object describes a rendering technique that uses one or more additional drawing passes, each of which uses a custom OpenGL shader program to augment or postprocess SceneKit’s rendering of the scene.

SCNTransaction

The SCNTransaction class defines SceneKit’s mechanism for batching scene graph modifications into atomic updates.

NSView

The NSView class defines the basic drawing, event-handling, and printing architecture of an app.

SCNView

You use an SCNView object to render SceneKit content for display in your app.

CAOpenGLLayer

CAOpenGLLayer provides a layer suitable for rendering OpenGL content.

SCNLayer

An SCNLayer object is a Core Animation layer that renders a SceneKit scene as its content.

Protocols

Protocol

Abstract

SCNActionable

The SCNActionable protocol defines methods for running actions on nodes.

SCNAnimatable

The SCNAnimatable protocol defines an interface for attaching animations to nodes, geometries, materials, and other SceneKit objects.

SCNBoundingVolume

The SCNBoundingVolume protocol defines an interface for describing objects that occupy a volume in space, adopted by the SCNNode and SCNGeometry classes.

SCNNodeRendererDelegate

The SCNNodeRendererDelegate protocol defines an interface for using your own custom OpenGL drawing code to render content for a node.

SCNPhysicsContactDelegate

The SCNPhysicsContactDelegate protocol defines methods you can implement to respond when two physics bodies contact each other in your scene’s physics simulation.

SCNProgramDelegate

The SCNProgramDelegate protocol methods you can implement to receive messages about custom GLSL shader programs.

SCNSceneExportDelegate

The SCNSceneExportDelegate protocol defines methods called when you export an SCNScene object to a file.

SCNSceneRenderer

The SCNSceneRenderer protocol defines methods and properties common to the SCNView, SCNLayer and SCNRenderer classes.

SCNSceneRendererDelegate

The SCNSceneRendererDelegate protocol defines methods that allow your app to participate in SceneKit’s animation and rendering process.

SCNShadable

The SCNShadable protocol defines an interface for SceneKit geometry and material objects whose rendering you can modify with OpenGL shader programs.

SCNTechniqueSupport

The SCNTechniqueSupport protocol defines an interface common to SceneKit objects that support multipass rendering using SCNTechnique objects.

Other Reference

Reference

SceneKit Constants Reference

SceneKit Data Types Reference

SceneKit Functions Reference