RealityFoundation · IOS API REFERENCE

CustomMaterial.Normal

struct · iOS 15.0+ · SDK 27.1

struct Normal

An object that stores fine surface details for an entity in an image texture. _Normal mapping_ is a real-time rendering technique that captures fine surface details for a model by using a texture instead of by increasing the number of polygons in the model. It works by storing _surface normals_, which are vectors perpendicular to the surface of the model, from a much higher-resolution version of the same 3D object. A normal map stores each vector in the image by storing the vectors’ `X`, `Y`, and `Z` values as the `R`, `G`, and `B` components of the corresponding pixel in the UV-mapped image. This object defines a normal map for a custom material. For more information on using normal map values in a custom material, see ``CustomMaterial/normal-swift.property``.

Members (4)

get · iOS 15.0+

texture

TypeScript

get texture(): (CustomMaterial_CustomMaterialTexture) | null

Swift declaration

var texture: CustomMaterial.Texture?

The material’s normal map.

set · iOS 15.0+

texture

TypeScript

set texture(value: (CustomMaterial_CustomMaterialTexture) | null)

Swift declaration

var texture: CustomMaterial.Texture?

The material’s normal map.

init · iOS 15.0+

init

TypeScript

static initTexture(texture?: (CustomMaterial_CustomMaterialTexture) | null): CustomMaterial_Normal

Swift declaration

init(texture: CustomMaterial.Texture? = nil)

Create an object from a specified texture. This initializer creates an object from a normal map texture. _Normal mapping_ is a real-time rendering technique that captures fine surface details for a model using a texture instead of increasing the number of polygons in the model. It works by storing _surface normals_, which are vectors perpendicular to the surface of the model, from a much higher-resolution version of the same 3D object. A normal map stores each vector in the image by storing the vectors’ `X`, `Y`, and `Z` values as the `R`, `G`, and `B` components of the corresponding pixel in the UV-mapped image. To render an entity using a normal map, set ``CustomMaterial/lightingModel-swift.property`` to ``CustomMaterial/LightingModel-swift.enum/lit`` or ``CustomMaterial/LightingModel-swift.enum/clearcoat``, and call `params.surface().set_normal()` from its surface shader. The following Metal code demonstrates how to sample and use a value from the normal map in your surface shader function: ```swift // Retrieve the entity's UV texture coordinates. float2 uv = params.geometry().uv0(); // Models loaded from USDZ or Reality Composer use UVs that are flipped // on the y-axis. This compensates for that. uv.y = 1.0 - uv.y; // Sample the normal map texture based on the resulting UV coordinates. auto tex = params.textures(); float3 normal = (float3)tex.normal().sample(textureSampler, uv).rgb; // Set the sampled value as this pixel's normal. params.surface().set_normal(normal); ``` - Parameters: - texture: The image’s texture.

init · iOS 15.0+

init

TypeScript

static init(value: PhysicallyBasedMaterial_Normal): CustomMaterial_Normal

Swift declaration

init(_ value: PhysicallyBasedMaterial.Normal)

Creates an object containing surface details for an entity from a custom material’s normal property. This initializer creates an object by copying the normal map from the ``PhysicallyBasedMaterial/normal-swift.property`` property of a ``PhysicallyBasedMaterial``. _Normal mapping_ is a real-time rendering technique that captures fine surface details for a model by using a texture instead of by increasing the number of polygons in the model. It works by storing _surface normals_, which are vectors perpendicular to the surface of the model, from a much higher-resolution version of the same 3D object. A normal map stores each vector in the image by storing the vectors’ `X`, `Y`, and `Z` values as the `R`, `G`, and `B` components of the corresponding pixel in the UV-mapped image. To render an entity using a normal map, set ``CustomMaterial/lightingModel-swift.property`` to ``CustomMaterial/LightingModel-swift.enum/lit`` or ``CustomMaterial/LightingModel-swift.enum/clearcoat``, and call `params.surface().set_normal()` from its surface shader. The following Metal code demonstrates how to sample and use a value from the normal map in your surface shader function: ```swift // Retrieve the entity's UV texture coordinates. float2 uv = params.geometry().uv0(); // Models loaded from USDZ or Reality Composer use UVs that are flipped // on the y-axis. This compensates for that. uv.y = 1.0 - uv.y; // Sample the normal map texture based on the resulting UV coordinates. auto tex = params.textures(); float3 normal = (float3)tex.normal().sample(textureSampler, uv).rgb; // Set the sampled value as this pixel's normal. params.surface().set_normal(normal); ``` - Parameters: - value: The normal object from a ``PhysicallyBasedMaterial``.

Skipped declarations

No declarations were skipped in this snapshot.

All RealityFoundation types →