# clearcoatRoughness The degree to which an entity’s clear, shiny coating scatters light to create soft highlights. ``` var clearcoatRoughness: CustomMaterial.ClearcoatRoughness { get set } ``` ## Discussion An entity in RealityKit can display a clearcoat, which is a separate layer of transparent specular highlights used to simulate a clear coating, like on a car or the surface of lacquered objects. This property allows you to specify a clearcoat roughness value to indicate how much the clearcoat scatters light that bounces off of it, which softens and disperses the highlights. You can specify a single value that applies to the entire material, or you can supply a UV-mapped image texture containing different roughness values for different parts of the entity. This value is available in your surface shader. RealityKit won’t render a clearcoat with roughness unless your surface shader calls both `params.surface().set_clearcoat_roughness()` and `params.surface().set_clearcoat()` with a value greater than `0.0`. The following Swift code demonstrates setting the `clearcoatRoughness` using a single value: ```swift material.clearcoatRoughness = .init(floatLiteral: 0.5) ``` This example shows how to set the `clearcoatRoughness` using a UV-mapped image: ```swift if let clearcoatRoughnessResource = try? TextureResource.load(named: "entity_cc_roughness") { let ccRoughnessMap = MaterialParameters.Texture(clearcoatRoughnessResource) material.clearcoat = .init(texture: ccRoughnessMap) } ``` With custom materials, RealityKit only renders a clearcoat if [`lightingModel`](/documentation/RealityKit/CustomMaterial/lightingModel-swift.property) is [`CustomMaterial.LightingModel.clearcoat`](/documentation/RealityKit/CustomMaterial/LightingModel-swift.enum/clearcoat) and the material’s surface shader function calls `params.surface().set_clearcoat()`. To specify [`clearcoatRoughness`](/documentation/RealityKit/CustomMaterial/clearcoatRoughness-swift.property), your surface shader function needs to also call `params.surface().set_clearcoat_roughness()`. The following Metal code demonstrates using [`clearcoat`](/documentation/RealityKit/CustomMaterial/clearcoat-swift.property) and [`clearcoatRoughness`](/documentation/RealityKit/CustomMaterial/clearcoatRoughness-swift.property) in a surface shader, replicating the behavior of the [`PhysicallyBasedMaterial`](/documentation/RealityKit/PhysicallyBasedMaterial) shader: ```cpp // Retrieve the clearcoat scale and roughness from the CustomMaterial. float clearcoatScale = params.material_constants().clearcoat_scale(); float clearcoatRoughnessScale = params.material_constants().clearcoat_roughness_scale(); // Retrieve the entity's texture coordinates. float2 uv = params.geometry().uv0(); // Entities loaded from a USDZ or .reality file use texture coordinates with // a flipped y-axis. This compensates for that. uv.y = 1.0 - uv.y; // Sample a value from the clearcoat and clearcoat roughness textures. auto tex = params.textures(); half clearcoat = tex.clearcoat().sample(textureSampler, uv).r; half clearcoatRoughness = tex.clearcoat_roughness().sample(textureSampler, uv).r; // Multiply the scale and sampled texture value from the clearcoat and // assign the result. clearcoat *= clearcoatScale; params.surface().set_clearcoat(clearcoat); // Multiply the scale and sampled texture value from the clearcoat roughness // and assign the result. clearcoatRoughness *= clearcoatRoughnessScale; params.surface().set_clearcoat_roughness(clearcoatRoughness); ``` --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)