Contents

metallic

The reflectiveness of an entity.

Declaration

var metallic: CustomMaterial.Metallic { get set }

Discussion

In physically based rendering, the metallic property represents the reflectiveness of an entity. Use this property to specify whether the entity displays metallic qualities and reflects the surrounding environment, or displays dielectric qualities and doesn’t reflect the environment. With custom materials, RealityKit doesn’t automatically use the values set on this property. To render a custom material using the metallic property, set lightingModel to CustomMaterial.LightingModel.lit or CustomMaterial.LightingModel.clearcoat and call params.surface().set_roughness() from its surface shader.

[Image]

The following Swift code shows how to use an image and a scale to specify roughness:

if let metallicResource = try? TextureResource.load(named:"entity_metallic") {
    let metallic = MaterialParameters.Texture(metallicResource)
    material.metallic = PhysicallyBasedMaterial.Metallic(scale: 1.0, texture:metallic)
}

The following surface shader takes the scale and texture values from the metallic property, multiplies them together, and uses the result to specify the metallic value for rendering, which emulates the behavior of PhysicallyBasedMaterial.

#include <metal_stdlib>
#include <RealityKit/RealityKit.h>
using namespace metal;

// Use samplers to retrieve a color value from a texture based on // the
entity's UV coordinates. Samplers can be reused with different textures.
// Surface shader functions should define no more than eight samplers.
constexpr sampler textureSampler(address::clamp_to_edge,
filter::bicubic);

[[visible]] void mySurfaceShader(realitykit::surface_parameters params)
{
    // Retrieve the metallic scale from the CustomMaterial.
    float metallicScale = params.material_constants().metallic_scale();

    // Retrieve the entity's texture coordinates.
    float2 uv = params.geometry().uv0();

    // Entities loaded from USDZ or .reality files have texture coordinates
    // with a flipped y-axis. This adjusts for that.
    uv.y = 1.0 - uv.y;

    // Sample the metallic texture based on the UV coordinates.
    auto tex = params.textures();
    half metallic = tex.metallic().sample(textureSampler, uv).r;

    // Multiply the tint 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 Modifying RealityKit rendering using custom materials.

See Also

Setting the core properties