Class

SCNMaterialProperty

A container for the color or texture of one of a material’s visual properties.

Overview

A material has several visual properties that together determine its appearance under lighting and shading. SceneKit renders each pixel in the scene by combining the information from material properties with the locations, intensities, and colors of lights.

A material property’s contents can be either a color, which provides a uniform effect across the surface of a material, or a texture, which SceneKit maps across the surface of a material using texture coordinates provided by the geometry object the material is attached to. A texture, in turn, can come from any of several sources:

An image object, or a path or URL to an image file
A specially formatted image or array of six images to be used as a cube map
A Core Animation layer or layer hierarchy, which itself may contain animated content
A SpriteKit texture providing a static image, or an entire SpriteKit scene rendering animated 2D content.

SceneKit uses the material property’s contents object in different ways for each visual property of a material. For example:

When you provide a color for the diffuse property, it determines the material’s base color—geometries using the material appear shaded in gradations of this color when illuminated by white light. If you instead provide an image, SceneKit maps the image across the geometry’s surface instead of shading with a uniform base color.
When you provide a color for the specular property, it affects the color of light reflected directly toward the viewer from the surface of a geometry using the material. If you instead provide a grayscale image, it determines the tendency of the material to reflect light directly toward the viewer—lighter pixels in the image make those areas of the material appear more shiny, and darker pixels make the material appear more matte.
The normal property specifies the orientation of a surface at each point. Materials are uniformly smooth by default, so specifying a color for this property has no useful effect. Instead, you can specify an image for this property that describes the contours of the surface. SceneKit uses this image (called a normal map) in lighting, creating the illusion of a complex, bumpy surface without increasing the complexity of the geometry.

For more details on each visual property and the ways their contents affect a material’s appearance, see SCNMaterial.

SceneKit also uses SCNMaterialProperty objects elsewhere:

To provide content to be rendered behind a scene, in the background property of an SCNScene object,
To affect the color and shape of illumination from a light source, in the gobo property of an SCNLight object.
To bind texture samplers to custom GLSL shader source code snippets, in classes conforming to the SCNShadable protocol.

Symbols

Creating a Material Property

init(contents: Any)

Creates a new material property object with the specified contents.

Working with Material Property Contents

var contents: Any?

The visual contents of the material property—a color, image, or source of animated content. Animatable.

var intensity: CGFloat

A number between 0.0 and 1.0 that modulates the effect of the material property. Animatable.

Configuring Texture Mapping Attributes

var contentsTransform: SCNMatrix4

The transformation applied to the material property’s visual contents. Animatable.

var wrapS: SCNWrapMode

The wrapping behavior for the S texture coordinate.

var wrapT: SCNWrapMode

The wrapping behavior for the T texture coordinate.

var minificationFilter: SCNFilterMode

Texture filtering for rendering the material property’s image contents at a size smaller than that of the original image.

var magnificationFilter: SCNFilterMode

Texture filtering for rendering the material property’s image contents at a size larger than that of the original image.

var mipFilter: SCNFilterMode

Texture filtering for using mipmaps to render the material property’s image contents at a size smaller than that of the original image.

var maxAnisotropy: CGFloat

The amount of anisotropic texture filtering to be used when rendering the material property’s image contents.

var mappingChannel: Int

The source of texture coordinates for mapping the material property’s image contents.

var borderColor: Any?

A color used to fill in areas of a material’s surface not covered by the material property’s image contents.

Deprecated

Constants

SCNFilterMode

Texture filtering modes, used by the the minificationFilter, magnificationFilter, and mipFilter properties.

SCNWrapMode

Modes to apply to texture wrapping, used by the wrapT and wrapS properties.

Relationships

Inherits From

NSObject