Class

SCNMaterialProperty

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

Declaration

@interface SCNMaterialProperty : NSObject

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, such as an image object, a URL to an image file, a specially formatted image or set of images for use as a cube map, or even animated content provided by Core Animation, SpriteKit, or AVFoundation—for the full set of options, see the contents property.

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.

Topics

Creating a Material Property

materialPropertyWithContents:

Creates a new material property object with the specified contents.

Working with Material Property Contents

contents

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

intensity

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

Configuring Texture Mapping Attributes

contentsTransform

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

wrapS

The wrapping behavior for the S texture coordinate.

wrapT

The wrapping behavior for the T texture coordinate.

SCNWrapMode

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

minificationFilter

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

magnificationFilter

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

mipFilter

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

SCNFilterMode

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

maxAnisotropy

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

mappingChannel

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

borderColor

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

Deprecated

Instance Properties

Relationships

Inherits From

See Also

Lighting, Cameras, and Shading

SCNLight

A light source that can be attached to a node to illuminate the scene.

SCNCamera

A set of camera attributes that can be attached to a node to provide a point of view for displaying the scene.

SCNMaterial

A set of shading attributes that define the appearance of a geometry's surface when rendered.