Model I/O

A MDLAreaLight object represents a source of light that illuminates a 3D scene not from a single point or direction, but from an area with a specific shape. The shape of an area light is a two-dimensional figure in the xy-plane of the light’s local coordinate space, and its illumination is directed in the negative z-axis direction (spreading out from that direction according to the inherited innerConeAngle and outerConeAngle properties).

A MDLAsset object represents an indexed container for 3D objects and associated information, such as transform hierarchies, meshes, cameras, and lights. You create a MDLAsset object by loading data from a URL, and can export an asset to any of several file formats. To access the objects contained in an asset, use Fast Enumeration, the object(at:) method, or subscripting. Each object in an asset can be the root of a hierarchy of objects—use an object’s children property to traverse that hierarchy.

A MDLCamera object describes a point of view for rendering a 3D scene, along with a set of camera parameters that determine the intended appearance of the rendered scene. Camera parameters include basic information—such as the projectionMatrix and fieldOfView properties—for use with any renderer, as well as attributes that model real-world cameras—such as the fStop and exposure properties—for use in a renderer based on realistic optical physics.

A MDLCheckerboardTexture object procedurally generates texel data by creating a checkerboard pattern with two specified colors. Like other procedural MDLTexture subclasses, the MDLCheckerboardTexture class generates texel data only when that data is first referenced, and caches it for future use.

A MDLColorSwatchTexture object procedurally generates texel data by creating a gradient between two colors. Like other procedural MDLTexture subclasses, the MDLColorSwatchTexture class generates texel data only when that data is first referenced, and caches it for future use.

The MDLLight class is the abstract superclass for objects that describe light sources in a scene. When you load lights from an asset file using the MDLAsset class, or create lights when building an asset for export, you use one or more of the concrete subclasses MDLPhysicallyPlausibleLight, MDLAreaLight, MDLPhotometricLight, or MDLLightProbe.

A MDLLightProbe object describes a light source in terms of the variations in color and intensity of its illumination in all directions. A light probe represents this variation either as a cube map texture, where each texel represents the color and intensity of light in a particular direction from the cube’s center, or as a set of spherical harmonic coefficients. In addition to describing such light sources, the MDLLightProbe provides methods for generating light probe textures based on the contents of a scene and for generating spherical harmonic coefficients from a texture.

A MDLMaterial instance manages a collection of material properties that together describe the intended surface appearance for rendering a 3D object. Each material property (a MDLMaterialProperty object) provides one specific aspect of appearance, such as opacity, shininess, or a bump map. Use the material property of a MDLSubmesh object to associate a material with a 3D object for rendering or to find the material assigned to an object loaded from an asset file.

A MDLMaterialProperty object defines a specific aspect of the rendering parameters for a material. In turn, the collection of material properties in a MDLMaterial instance defines the intended surface appearance for rendering a 3D object. A material property object’s semantic property identifies which aspect of material rendering it affects, and its value (which can be any of several types) determines how the material property contributes to that aspect of rendering.

A MDLMesh instance provides vertex buffer data to be used in rendering a 3D object. A mesh contains one or more MDLSubmesh objects, each of which provides both index buffer data that describes how the mesh’s vertices should be combined for drawing and material information that describes an intended appearance for rendering. Typically, you obtain meshes by traversing the object hierarchy of a MDLAsset object, but you can also create a mesh from your own vertex data. The MDLMesh class also supports processing meshes to generate vertex attributes or bake lighting information.

A MDLMeshBufferData object provides a memory buffer that stores vertex or index data for a MDLMesh object. This class is the simplest concrete implementation of the MDLMeshBuffer protocol—use this class when you need only a single data store for loading or processing mesh data. To share mesh data for other uses, use another concrete implementation of the MDLMeshBuffer protocol—for example, the MTKMeshBuffer class shares mesh data with Metal buffers, ensuring that data is copied a minimal number of times between loading, processing, and rendering.

A MDLMeshBufferDataAllocator object provides an implementation of the MDLMeshBufferAllocator protocol that allocates from main memory using NSData objects. Model I/O uses this allocator by default if you do not specify an allocator when loading, creating, or modifying objects that require mesh buffer storage (for example, when loading an asset with the init(url:vertexDescriptor:bufferAllocator:) initializer). Use this allocator only if sharing mesh buffer memory with GPU-based renderers is not a concern. To minimize data copying when rendering with Metal or OpenGL, use the MTKMeshBufferAllocator or GLKMeshBufferAllocator class instead.

A MDLMeshBufferMap object manages access to a memory buffer used for the vertex or index data storage of a MDLMesh object. Typically, you do not create MDLMeshBufferMap objects directly. Instead, you use classes supporting the MDLMeshBuffer protocol to manage mesh buffer memory shared with a rendering technology—for example, the MTKMeshBuffer class for rendering with Metal. A mesh buffer object vends a MDLMeshBufferMap objects when you use the map() method to gain temporary access to the shared memory.

A MDLMeshBufferZoneDefault object provides a standard implementation of the MDLMeshBufferZone protocol for managing pools of related memory allocations using a MDLMeshBufferAllocator object. Model I/O uses zones to ensure that related allocations—such as the multiple vertex and index buffers associated with a MDLMesh object—use contiguous blocks of memory for optimal performance. When working with a mesh buffer allocator that does not implement its own zone management, Model I/O uses this zone class.

A MDLNoiseTexture object procedurally generates texel data by creating a field of random noise. Like other procedural MDLTexture subclasses, the MDLNoiseTexture class generates texel data only when that data is first referenced, and caches it for future use.

A MDLNormalMapTexture object procedurally generates texel data by computing a normal map from a supplied texture. Model I/O examines the shapes of contrasting areas in the supplied texture to generate a normal map that results in an embossed appearance when rendering. Like other procedural MDLTexture subclasses, the MDLNormalMapTexture class generates texel data only when that data is first referenced, and caches it for future use.

MDLObject is the base class for objects that are part of a 3D asset, including meshes, cameras, and lights. When you load content from an asset file using the MDLAsset class, Model I/O creates instances of the MDLObject subclasses MDLMesh, MDLCamera, and MDLLight. For asset formats that describe a collection of meshes, cameras, and lights organized in a hierarchy of spatial transforms, Model I/O also creates instances of the MDLObject class itself to describe the transform nodes that organize the asset’s visual content. Similarly, you use the MDLObject class and its subclasses when creating an object graph to be exported as an asset file using the MDLAsset class.

The MDLObjectContainer class provides a default implementation of the MDLObjectContainerComponent protocol, which Model I/O uses to create object hierarchy relationships for meshes, lights, cameras, and containers loaded from a MDLAsset instance. To create your own containers—for example, to reference in-memory representations, offline databases, or custom asset file formats—create MDLObjectContainer subclasses and add them to a MDLObject instance using its setComponent(_:for:) method.

A MDLPhotometricLight object represents a light source whose shape, direction, and intensity of illumination is determined by a photometric profile. You create a photometric light from a file in the IES format, containing physical measurements of a light source. Many manufacturers of real-world light fixtures publish such files describing the lighting characteristics of their products. This photometry data measures the light web surrounding a light source—measurements of the light’s intensity in all directions around the source.

A MDLPhysicallyPlausibleLight object describes a light source for use in a shading model based on real-world physics.

A MDLPhysicallyPlausibleScatteringFunction object models a set of material properties that together define the response to lighting for a MDLMaterial object. (This aspect of shading is also called the Bidirectional Reflectance Distribution Function, or BRDF, for a surface shaded using the material.) The properties defined by this class, along with some properties inherited from the superclass MDLScatteringFunction, describe a shading model that more closely simulates real-world lighting physics than traditional shading models, as used in recent game engines and feature films.

A MDLScatteringFunction object models a set of material properties that together define the response to lighting for a MDLMaterial object. (This aspect of shading is also called the Bidirectional Reflectance Distribution Function, or BRDF, for a surface shaded using the material.) The set of properties defined by the MDLScatteringFunction class itself describes a Lambertian shading model with Blinn-Phong specular response; subclasses can define a set of properties for other shading models.

A MDLSkyCubeTexture object procedurally generates texel data for a cube texture using a physically realistic simulation of the sunlit sky. Such textures can be useful as environment maps or light probes in rendering. Like other procedural MDLTexture subclasses, the MDLSkyCubeTexture class generates texel data only when that data is first referenced, and caches it for future use.

A MDLStereoscopicCamera object describes a point of view for rendering a stereoscopic display of a 3D scene. This class provides properties related to rendering the scene from two slightly different perspectives to simulate binocular vision. For general and optical properties of a camera, see the superclass MDLCamera.

A MDLSubmesh instance provides index buffer data and material information to be used in rendering a 3D object. Submeshes are contained by MDLMesh objects, which provide vertex buffer data to which a submesh’s index data refers. Together, the vertex and index data describe the geometric form of a portion of the mesh, and the submesh’s material property determines its intended surface appearance for rendering.

A MDLSubmeshTopology object describes the arrangement of vertices identified in a submesh’s index buffers and how that arrangement produces the submesh’s shape. Model I/O creates topology objects when importing assets containing non-uniform index buffers (that is, index buffers not composed of a single primitive type such as triangles or quads). You can also use topology objects (or load assets from file formats supporting topology information) to describe models for surface subdivision, identifying which edges or vertices remain sharp or become smooth when you use the newSubdividedMesh(_:submeshIndex:subdivisionLevels:) method.

A MDLTexture instance represents a source of texel data to be used in rendering material surface appearances. You use the MDLTexture class or one of its subclasses to identify, load, or create texture data, then associate textures with materials using the MDLTextureSampler and MDLMaterialProperty classes. When you load 3D objects from an asset file (in a format that supports texturing) with the MDLAsset class, Model I/O automatically creates texture objects and material objects and associates them with the MDLSubmesh objects in the asset.

A MDLTextureFilter object describes filtering modes for a renderer to use when sampling from a texture. A texture filter, together with a MDLTexture object and transform information, form a MDLTextureSampler object, which describes a texture and its rendering parameters for use in rendering one aspect of a MDLMaterial object’s surface appearance.

A MDLTextureSampler object describes a texture along with its sampling parameters for use in rendering one aspect of a surface appearance. You use texture samplers as material property values with the MDLMaterialProperty class.

A MDLTransform object manages the local coordinate space transformations for 3D objects. Transform information can be static, or in the case of resources that describe animations, time-based. You use transform objects to position, orient, shear, and scale the meshes, cameras, lights, and container objects in an asset using their transform property.

A MDLURLTexture object stores a lightweight reference to a URL from which to load texture data. Unlike the superclass MDLTexture, the MDLURLTexture class loads texel data from the file at that URL only when that data is first referenced, and caches it for future use.

A MDLVertexAttribute object describes the structure, format, and layout of per-vertex data for a single vertex attribute—such as vertex position, surface normal vector, or texture coordinates—in the vertex buffers of a MDLMesh object. A collection of vertex attribute objects and additional information forms a MDLVertexDescriptor object, which completely describes the layout of vertex buffers for a mesh.

A MDLVertexAttributeData instance provides convenience access to the vertex data for a specific vertex attribute of a MDLMesh object. You retrieve a vertex attribute data object by calling the vertexAttributeData(forAttributeNamed:) method of a mesh, which is shorthand for looking up the the MDLMeshBuffer object corresponding to the named attribute and using the map() method to gain read-only access to its contents.

A MDLVertexBufferLayout object describes layout information for a vertex buffer in a MDLMesh object. A collection of vertex layer objects, vertex attribute objects, and additional information forms a MDLVertexDescriptor object, which completely describes the layout of vertex buffers for a mesh.

A MDLVertexDescriptor describes the structure, format, and layout of the set of vertex data buffers associated with a MDLMesh object. A mesh contains arrays of data for separate attributes of each vertex, such as position, color, surface normal vector, or texture coordinates. The vertex data for variouas atttributes can be contained in one or more buffers and may be laid out in various contigouous or interleaved formats. You use a mesh’s vertexDescriptor property to determine the structure of vertex data for a mesh loaded from an asset file for use in rendering or processing a mesh. You also use vertex descriptors to describe the structure of existing vertex data when creating a new mesh.

A MDLVoxelArray instance models a 3D object as a collection of voxels, or cubic units. Unlike a mesh, which models only surface topology, a voxel array models the solid volume of a 3D object. Voxels are thus useful for modeling volumetric phenomena such as clouds and fire, performing solid geometry operations such as intersection and union, or preparing a 3D design for real-world physical production.