An object that defines an entity’s reflectiveness.
In physically based rendering, the `metallic` property represents the
reflectiveness of an entity. Use this object to specify whether an
entity displays metallic qualities and reflects the surrounding
environment.
For more information on using metallic values in a custom material, see
``CustomMaterial/metallic-swift.property``.
Creates an object from a single value.
In physically based rendering, the `metallic` property represents
the reflectiveness of an entity. This initializer creates a new
object that passes a single metallic value to your custom shader
functions but doesn’t pass a texture.
The following Swift code shows how to specify reflectiveness using a
single value for the entire entity:
```swift
material.roughness = PhysicallyBasedMaterial.Roughness(floatLiteral: 0.0)
```
To render an entity with reflectiveness, set
``CustomMaterial/lightingModel-swift.property`` to
``CustomMaterial/LightingModel-swift.enum/lit`` or
``CustomMaterial/LightingModel-swift.enum/clearcoat``,
and call `params.surface().set_metallic()`
from its surface shader.
The following Metal code shows how to retrieve the value set in this
initializer in your surface shader and use it:
```other
// Retrieve the metallic scale from the CustomMaterial.
float metallic = params.material_constants().metallic_scale();
// Set the roughness value using the metallic scale value.
params.surface().set_metallic(metallic);
```
For more information on creating custom materials and writing shader
functions, see
<doc:modifying-realitykit-rendering-using-custom-materials>.
- Parameters:
- value: The reflectiveness value for the material.
Creates an object from a color or texture.
In physically based rendering, the `metallic` property represents
the reflectiveness of an entity. This initializer creates a new
object that passes a single scale value, a texture, or both to the
material’s shader functions.
The following code demonstrates creating a roughness object using
this initializer:
```swift
if let metallicResource = try? TextureResource.load(named:
"metallic_roughness") {
let metallic = MaterialParameters.Texture(metallicResource)
customMaterial.roughness = .init(scale: 0.5, texture: metallic)
}
```
With custom materials, the `texture` and `scale` properties you set
on this property are available in your surface shader function, but
RealityKit doesn’t automatically use them to render your entity.
To render an entity with reflectiveness, set
``CustomMaterial/lightingModel-swift.property`` to
``CustomMaterial/LightingModel-swift.enum/lit`` or
``CustomMaterial/LightingModel-swift.enum/clearcoat``,
and call `params.surface().set_metallic()`
from its surface shader.
To achieve the same metallic behavior as
``PhysicallyBasedMaterial``, the surface shader function multiplies
the metallic scale by the sampled value from the roughness texture,
as the following Metal code demonstrates:
```other
// Retrieve the metallic scale from the CustomMaterial.
float metallicScale = params.material_constants().metallic_scale();
// 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 texture based on the resulting UVs.
auto tex = params.textures();
half metallic = tex.metallic().sample(textureSampler, uv).r;
// Multiply the scale and the sampled value from the texture, and assign
// the result to the shader's metallic property.
metallic *= metallicScale;
params.surface().set_metallic(metallic);
```
For more information on creating custom materials and writing shader
functions, see
<doc:modifying-realitykit-rendering-using-custom-materials>.
- Parameters:
- scale: The reflectiveness value.
- texture: An optional image texture.
get · iOS 15.0+
scale
TypeScript
get scale(): number
Swift declaration
var scale: Float
The reflectiveness value for the entire entity or a multiplier for
the metallic texture.
This property is an input to your material’s surface shader.
Although you can choose how to use the `scale` value in your shader,
RealityKit provides this property to control the reflectiveness of
the entire entity when there’s no texture, or to function as a
multiplier to the values you sample from the texture.
set · iOS 15.0+
scale
TypeScript
set scale(value: number)
Swift declaration
var scale: Float
The reflectiveness value for the entire entity or a multiplier for
the metallic texture.
This property is an input to your material’s surface shader.
Although you can choose how to use the `scale` value in your shader,
RealityKit provides this property to control the reflectiveness of
the entire entity when there’s no texture, or to function as a
multiplier to the values you sample from the texture.
get · iOS 15.0+
texture
TypeScript
get texture(): (CustomMaterial_CustomMaterialTexture) | null
Swift declaration
var texture: CustomMaterial.Texture?
The reflectiveness as a UV-mapped image texture.
set · iOS 15.0+
texture
TypeScript
set texture(value: (CustomMaterial_CustomMaterialTexture) | null)
Creates a metallic object from a physically based material’s
metallic property.
This initializer creates a new object by copying the values from an
existing ``PhysicallyBasedMaterial/Metallic-swift.struct`` object.
To render an entity with reflectiveness, set
``CustomMaterial/lightingModel-swift.property`` to
``CustomMaterial/LightingModel-swift.enum/lit`` or
``CustomMaterial/LightingModel-swift.enum/clearcoat``,
and call `params.surface().set_metallic()`
from its surface shader function.
To achieve the same metallic
behavior as ``PhysicallyBasedMaterial``, the surface shader function
multiplies metallic scale by the sampled value from the texture, as
the following Metal code demonstrates:
```other
// Retrieve the metallic scale from the CustomMaterial.
float metallicScale = params.material_constants().metallic_scale();
// 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 texture based on the resulting UVs.
auto tex = params.textures();
half metallic = tex.metallic().sample(textureSampler, uv).r;
// Multiply the scale and the sampled value from the texture,
// and assign the result to the shader's metallic property.
metallic *= metallicScale;
params.surface().set_metallic(metallic);
```
For more information on creating custom materials and writing shader
functions, see
<doc:modifying-realitykit-rendering-using-custom-materials>.
- Parameters:
- value: The physically based material’s metallic property.
