Mac Developer Library

Developer

SceneKit Framework Reference SCNGeometry Class Reference

Options
Deployment Target:

On This Page
Language:

SCNGeometry

Conforms To


Import Statement


Swift

import SceneKit

Objective-C

@import SceneKit;

Availability


Available in OS X v10.8 and later.

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 SceneKit, 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 SceneKit. 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 SceneKit 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 SceneKit’s rendering of a geometry.

Obtaining a Geometry Object

SceneKit 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 SceneKit’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

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

    Declaration

    Swift

    convenience init(sources sources: [AnyObject], elements elements: [AnyObject]?)

    Objective-C

    + (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, SceneKit 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.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Objective-C

    + (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.

    SceneKit’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.

    Import Statement

    Objective-C

    @import SceneKit;

    Availability

    Available in OS X v10.9 and later.

  • name name Property

    A name associated with the geometry object.

    Declaration

    Swift

    var name: String?

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    var levelsOfDetail: [AnyObject]?

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.9 and later.

  • materials materials Property

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

    Declaration

    Swift

    var materials: [AnyObject]?

    Objective-C

    @property(nonatomic, copy) NSArray *materials

    Discussion

    Materials provide the information SceneKit 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 in Figure 1 has four elements, each with a different material.

    Figure 1A geometry with multiple geometry elements image: ../Art/geometry_multi_material.pdf

    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, SceneKit 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, SceneKit renders the element at index 5 using the material at index 5 % 3 = 2.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

  • The first material attached to the geometry.

    Declaration

    Swift

    var firstMaterial: SCNMaterial?

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    func materialWithName(_ name: String) -> SCNMaterial?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

  • Attaches a material to the geometry at the specified index.

    Declaration

    Swift

    func insertMaterial(_ material: SCNMaterial, atIndex index: Int)

    Objective-C

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

    Parameters

    material

    The material to attach.

    index

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

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

  • Removes a material attached to the geometry.

    Declaration

    Swift

    func removeMaterialAtIndex(_ index: Int)

    Objective-C

    - (void)removeMaterialAtIndex:(NSUInteger)index

    Parameters

    index

    The index of the attached material to be removed.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

  • Replaces a material attached to the geometry with another.

    Declaration

    Swift

    func replaceMaterialAtIndex(_ index: Int, withMaterial material: SCNMaterial)

    Objective-C

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

    Parameters

    index

    The index of the attached material to be replaced.

    material

    The material with which to replace the attached material.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    var geometryElementCount: Int { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

  • Returns the geometry element at a specified index.

    Declaration

    Swift

    func geometryElementAtIndex(_ elementIndex: Int) -> SCNGeometryElement?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

  • Returns the geometry sources for a specified semantic.

    Declaration

    Swift

    func geometrySourcesForSemantic(_ semantic: String) -> [AnyObject]?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.8 and later.

  • The number of subdivisions SceneKit uses to smooth the geometry’s surface at render time.

    Declaration

    Swift

    var subdivisionLevel: Int

    Objective-C

    @property(nonatomic) NSUInteger subdivisionLevel

    Discussion

    Surface subdivision is a technique for using low-detail geometry to generate a smooth surface for rendering. When you increase the subdivisionLevel value of a geometry, SceneKit automatically splits each face in the rendered surface, creating a more detailed, smoother geometry, as shown in Figure 2. SceneKit performs this subdivision process at render time, preserving the original geometry data.

    Figure 2Rendering a subdivision surface image: ../Art/subdiv.pdf

    Subdividing a surface rounds away any sharp edges and corners in the geometry; however, such details may be important to a model’s design. To preserve edges, use the edgeCreasesElement property to identify edges and the edgeCreasesSource property to specify how smooth or sharp they should appear after subdivision. To preserve corners, include a geometry source whose semantic value is SCNGeometrySourceSemanticVertexCrease when creating the geometry.

    The default subdivision level is zero, specifying no subdivision—SceneKit renders the geometry exactly as its vertex data specifies.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.10 and later.

  • The geometry element identifying which edges of the geometry’s surface should remain sharp after subdivision.

    Declaration

    Swift

    var edgeCreasesElement: SCNGeometryElement?

    Objective-C

    @property(nonatomic, retain) SCNGeometryElement *edgeCreasesElement

    Discussion

    This geometry element’s primitiveType value must be SCNGeometryPrimitiveTypeLine. The geometry element’s data is an array of vertex indices, each pair of which defines a line segment identifying an edge to be treated as a crease during subdivision. Use the edgeCreasesSource property to specify the smoothness or sharpness of each crease.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.10 and later.

    See Also

    subdivisionLevel

  • The geometry source specifying the smoothness or sharpness of edges after surface subdivision.

    Declaration

    Swift

    var edgeCreasesSource: SCNGeometrySource?

    Objective-C

    @property(nonatomic, retain) SCNGeometrySource *edgeCreasesSource

    Discussion

    This geometry source’s semantic value must be SCNGeometrySourceSemanticEdgeCrease. Its data is an array of scalar values (that is, the source’s componentsPerVector value is 1). The value at an index in the geometry source determines the smoothness or sharpness of the edge identified by the primitive at the corresponding index in the edgeCreasesElement geometry element: a value of 0.0 specifies a completely smoothed edge, and a value of 10.0 or greater specifies an infinitely sharp edge.

    Import Statement

    Objective-C

    @import SceneKit;

    Swift

    import SceneKit

    Availability

    Available in OS X v10.10 and later.

    See Also

    subdivisionLevel