A container for the color or texture of one of a material’s visual properties.
SDKs
- iOS 8.0+
- macOS 10.8+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
Framework
- Scene
Kit
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.
Note
Typically, you associate texture images with materials when creating 3D assets with third-party authoring tools, and the scene files containing those assets reference external image files. For best results when shipping assets in your app bundle, place scene files in a folder with the .scnassets
extension, and place image files referenced as textures from those scenes in an Asset Catalog.
Xcode then optimizes the scene and texture resources for best performance on each target device, and prepares your texture resources for delivery features such as App Thinning and On-Demand Resources.
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 SCNMaterial
objects elsewhere:
To provide content to be rendered behind a scene, in the
background
property of anSCNScene
object,To affect the color and shape of illumination from a light source, in the
gobo
property of anSCNLight
object.To bind texture samplers to custom GLSL shader source code snippets, in classes conforming to the
SCNShadable
protocol.