SCNGeometry Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/SceneKit.framework
Availability
Available in OS X v10.8 and later.
Declared in
SCNGeometry.h

Overview

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. In Scene Kit, geometries attached to SCNNode objects form the visible elements of a scene, and SCNMaterial objects attached to a geometry determine its appearance.

Working with Geometry Objects

You control a geometry’s appearance in a scene with nodes and materials. A geometry object provides only the form of a visible object rendered by Scene Kit. You specify color and texture for a geometry’s surface, control how it responds to light, and add special effects by attaching materials (for details, see the methods in Managing a Geometry’s Materials). You position and orient a geometry in a scene by attaching it to an SCNNode object. Multiple nodes can reference the same geometry object, allowing it to appear at different positions in a scene.

You can easily copy geometries and change their materials. A geometry object manages the association between immutable vertex data and a mutable assignment of materials. To make a geometry appear more than once in the same scene with a different set of materials, use its inherited copy method. The copy shares the underlying vertex data of the original, but can be assigned materials independently. You can thus make many copies of a geometry without incurring a significant cost to rendering performance.

You can animate a geometry object. The vertex data associated with a geometry is immutable, but Scene Kit provides several ways to animate geometry. You can use a SCNMorpher or SCNSkinner object to deform a geometry’s surface, or run animations created in an external 3D authoring tool and loaded from a scene file. You can also use methods in the SCNShadable protocol to add custom GLSL shader programs that alter Scene Kit’s rendering of a geometry.

Obtaining a Geometry Object

Scene Kit provides several ways to introduce geometry objects to your app:

Action

For further information

Load from a scene file created using external 3D authoring tools

SCNScene, SCNSceneSource

Use and customize Scene Kit’s built-in primitive shapes

SCNPlane, SCNBox, SCNSphere, SCNPyramid, SCNCone, SCNCylinder, SCNCapsule, SCNTube, and SCNTorus

Create 3D geometry from 2D text or Bézier curves

SCNText, SCNShape

Create a custom geometry from vertex data

SCNGeometrySource, SCNGeometryElement, geometryWithSources:elements:, Managing Geometry Data

Tasks

Creating a Custom Geometry

Managing Geometry Attributes

Managing a Geometry’s Materials

Managing Geometry Data

Properties

firstMaterial

The first material attached to the geometry.

@property(nonatomic, retain) SCNMaterial *firstMaterial
Discussion

Calling this convenience method is equivalent to retrieving the first object from the geometry’s materials array. This property’s value is nil if the geometry has no attached materials.

Availability
  • Available in OS X v10.8 and later.
Declared In
SCNGeometry.h

geometryElementCount

The number of geometry elements in the geometry. (read-only)

@property(nonatomic, readonly) NSInteger geometryElementCount
Discussion

Each SCNGeometryElement object describes how vertices from the geometry’s sources are combined into polygons to create the geometry’s shape. Visible geometries contain at least one element.

For geometries with multiple elements, you can use the materials property to attach different materials to each element.

Availability
  • Available in OS X v10.8 and later.
Declared In
SCNGeometry.h

levelsOfDetail

An array of SCNLevelOfDetail objects for managing the geometry’s appearance when viewed from far away.

@property(nonatomic, copy) NSArray *levelsOfDetail
Discussion

Because rendering a complex geometry incurs a performance cost, you can use level-of-detail objects to substitute simpler geometries in its place as its distance from the point of view camera increases (or its apparent size decreases). For details, see SCNLevelOfDetail Class Reference.

Availability
  • Available in OS X v10.9 and later.
Declared In
SCNGeometry.h

materials

An array of SCNMaterial objects that determine the geometry’s appearance when rendered.

@property(nonatomic, copy) NSArray *materials
Discussion

Materials provide the information Scene Kit uses to add color, lighting, texture, and special effects when rendering a geometry. Each SCNMaterial object can be shared between several geometries.

If a geometry contains multiple elements (see geometryElementCount), you can associate a separate material with each geometry element. For example, the teapot below has four elements, each with a different material.

../Art/geometry_multi_material_2x.png

If a geometry has the same number of materials as it has geometry elements, the material index corresponds to the element index. For geometries with fewer materials than elements, Scene Kit determines the material index for each element by calculating the index of that element modulo the number of materials. For example, in a geometry with six elements and three materials, Scene Kit renders the element at index 5 using the material at index 5 % 3 = 2.

Availability
  • Available in OS X v10.8 and later.
Declared In
SCNGeometry.h

name

A name associated with the geometry object.

@property(nonatomic, copy) NSString *name
Discussion

You can provide a descriptive name for a geometry object to make managing your scene graph easier. Geometries loaded from a scene file may have names assigned by an artist using a 3D authoring tool. Use the SCNSceneSource class to examine geometries in a scene file without loading its scene graph.

Geometry names are saved when you export a scene to a file using its writeToURL:options:delegate:progressHandler: method. They also appear in the Xcode scene editor.

Availability
  • Available in OS X v10.8 and later.
Declared In
SCNGeometry.h

Class Methods

geometry

Creates a new geometry object with no content (or default content).

+ (instancetype)geometry
Return Value

A new geometry object.

Discussion

This method creates a geometry with no visible content. You can use an empty geometry with another geometry’s levelsOfDetail property to make the geometry disappear when it is too far away from the camera to usefully render.

Scene Kit’s SCNGeometry subclasses use this method to create geometry instances with default contents. For example, if you call this method on the SCNSphere class, it creates a sphere geometry whose radius property has the default value of 0.5.

You cannot add geometry sources or elements to a geometry object after creating it. To create a custom geometry from your own source and element data, use the geometryWithSources:elements: method.

Availability
  • Available in OS X v10.9 and later.
Declared In
SCNGeometry.h

geometryWithSources:elements:

Creates a new geometry built from the specified geometry sources and elements.

+ (instancetype)geometryWithSources:(NSArray *)sources elements:(NSArray *)elements
Parameters
sources

An array of SCNGeometrySource objects describing vertices in the geometry and their attributes.

elements

An array of SCNGeometryElement objects describing how to connect the geometry’s vertices.

Discussion

A geometry’s visible content comes from the combination of geometry sources, which contain data describing its vertices, with geometry elements, which contain data describing how the vertices connect to form a surface.

Each SCNGeometrySource object describes an attribute of all vertices in the geometry (vertex position, surface normal vector, color, or texture mapping coordinates) identified by the source’s semantic property. To create a custom geometry you must provide at least one source, for the SCNGeometrySourceSemanticVertex semantic. Typically, you also provide sources for normals and texture coordinates for use in lighting and shading.

Sources for the vertex, normal, and color semantics must be unique—if multiple objects in the sources array have the same semantic, Scene Kit uses only the first. A geometry may have multiple sources for the SCNGeometrySourceSemanticTexcoord semantic—the order of texture coordinate sources in the sources array determines the value to use for the mappingChannel property when attaching materials.

Each SCNGeometryElement object describes how vertices from the geometry sources are combined into polygons to create the geometry’s shape. Creating a custom geometry requires at least one element. If the elements array contains multiple objects, their order determines the arrangement of the geometry’s materials—for details, see the discussion of the materials property.

Availability
  • Available in OS X v10.8 and later.
Declared In
SCNGeometry.h

Instance Methods

geometryElementAtIndex:

Returns the geometry element at a specified index.

- (SCNGeometryElement *)geometryElementAtIndex:(NSInteger)elementIndex
Parameters
elementIndex

The index of the geometry element.

Return Value

A geometry element.

Discussion

Each SCNGeometryElement object describes how vertices from the geometry’s sources are combined into polygons to create the geometry’s shape. Visible geometries contain at least one element.

Availability
  • Available in OS X v10.8 and later.
Declared In
SCNGeometry.h

geometrySourcesForSemantic:

Returns the geometry sources for a specified semantic.

- (NSArray *)geometrySourcesForSemantic:(NSString *)semantic
Parameters
semantic

A constant identifying a semantic for which to return geometry sources. See Geometry Semantic Identifiers for possible values.

Return Value

An array of SCNGeometrySource objects, or nil if the geometry has no source for the specified semantic.

Discussion

Each SCNGeometrySource object describes an attribute of all vertices in the geometry (vertex position, surface normal vector, color, or texture mapping coordinates) identified by the source’s semantic property. A geometry always has at least one source, for the SCNGeometrySourceSemanticVertex semantic, and typically has additional sources for use in lighting and shading.

The vertex, normal, and color semantics each refer to at most one source. A geometry may have multiple sources for the SCNGeometrySourceSemanticTexcoord semantic—in this case, indices in the returned array array correspond to values for the mappingChannel property used when attaching textures to materials.

Availability
  • Available in OS X v10.8 and later.
Declared In
SCNGeometry.h

insertMaterial:atIndex:

Attaches a material to the geometry at the specified index.

- (void)insertMaterial:(SCNMaterial *)material atIndex:(NSUInteger)index
Parameters
material

The material to attach.

Important: Raises an exception (NSInvalidArgumentException) if material is nil.

index

The location in the geometry’s materials array at which to add the new material.

Important: Raises an exception (NSRangeException) if index is greater than the number of elements in the materials array.

Availability
  • Available in OS X v10.8 and later.
Declared In
SCNGeometry.h

materialWithName:

Returns the first material attached to the geometry with the specified name.

- (SCNMaterial *)materialWithName:(NSString *)name
Parameters
name

The name of the material to be retrieved.

Return Value

A material object with the specified name.

Discussion

You can use the name property of each SCNMaterial object to make managing your scene graph easier. Materials loaded from a scene file may have names assigned by an artist using a 3D authoring tool.

If a geometry has multiple materials attached with the same name, this method returns the first according to the order of the materials array.

Availability
  • Available in OS X v10.8 and later.
Declared In
SCNGeometry.h

removeMaterialAtIndex:

Removes a material attached to the geometry.

- (void)removeMaterialAtIndex:(NSUInteger)index
Parameters
index

The index of the attached material to be removed.

Important: Raises an exception (NSRangeException) if index is beyond the bounds of the materials array.

Availability
  • Available in OS X v10.8 and later.
Declared In
SCNGeometry.h

replaceMaterialAtIndex:withMaterial:

Replaces a material attached to the geometry with another.

- (void)replaceMaterialAtIndex:(NSUInteger)index withMaterial:(SCNMaterial *)material
Parameters
index

The index of the attached material to be replaced.

Important: Raises an exception (NSRangeException) if index is beyond the bounds of the materials array.

material

The material with which to replace the attached material.

Important: Raises an exception (NSInvalidArgumentException) if material is nil.

Availability
  • Available in OS X v10.8 and later.
Declared In
SCNGeometry.h