An object that defines how the surface of an entity scatters the light
it reflects.
In physically based rendering, the `roughness` property represents how
much the surface of an entity scatters the light it reflects. A material
with a high roughness has a matte appearance, whereas one with a low
roughness has a shiny appearance.
For more information on using roughness values in a custom material, see
``CustomMaterial/roughness-swift.property``.
Creates an object to specify the amount of roughness, using a single
value that applies to the entire material.
The `roughness` property represents how much the surface of the
entity scatters light that it reflects. A material with a high
roughness has a matte appearance, and one with a low roughness has a
shiny appearance.
-1)
The following Swift code shows how to specify roughness using a
single value for the entire entity:
```swift
material.roughness = PhysicallyBasedMaterial.Roughness(floatLiteral: 0.0)
```
With custom materials, the roughness value is available in your
surface shader; however, RealityKit doesn’t use it automatically to
render the entity.
To render an entity with roughness, the material’s
``CustomMaterial/lightingModel-swift.property``
needs to be
``CustomMaterial/LightingModel-swift.enum/lit`` or
``CustomMaterial/LightingModel-swift.enum/clearcoat``,
and call `params.surface().set_roughness()`
from its surface shader function.
The following Metal code shows how to retrieve the roughness value
set using this initializer in your surface shader:
```other
// Retrieve the roughness scale from the CustomMaterial.
float roughnessScale = params.material_constants().roughness_scale();
// Set the roughness value using the roughness scale.
params.surface().set_roughness(roughnessScale);
```
For more information on creating custom materials and writing shader
functions, see
<doc:modifying-realitykit-rendering-using-custom-materials>.
- Parameters:
- value: The roughness value.
Creates a roughness object from a color or texture.
Use this initializer to create an object to specify the amount of
roughness using a single value or an image texture, or both.
The `roughness` property represents how much the surface of the
entity scatters light that it reflects. A material with a high
roughness has a matte appearance, and one with a low roughness has a
shiny appearance.
-1)
The following code demonstrates creating a roughness object using
this initializer:
```swift
if let roughnessResource = try? TextureResource.load(named:
"entity_roughness") {
let roughness = MaterialParameters.Texture(roughnessResource)
customMaterial.roughness = .init(scale: 0.5, texture: roughness)
}
```
With custom materials, the `texture` and `scale` properties you set
on the ``CustomMaterial/roughness-swift.property`` property are
available in your surface shader function, but RealityKit doesn’t
automatically use them to render your entity.
To render an entity with roughness, set
``CustomMaterial/lightingModel-swift.property`` to
``CustomMaterial/LightingModel-swift.enum/lit`` or
``CustomMaterial/LightingModel-swift.enum/clearcoat``,
and call `params.surface().set_roughness()`
from its surface shader.
To achieve the same metallic behavior as
``PhysicallyBasedMaterial``, the surface shader function multiplies
the roughness scale by the sampled value from the roughness texture,
as the following Metal code demonstrates:
```swift
// Retrieve the roughness scale from the CustomMaterial.
float roughnessScale = params.material_constants().roughness_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 roughness = tex.roughness().sample(textureSampler, uv).r;
// Multiply the scale and the sampled value from the texture, and assign
// the result to the shader's base color property.
roughness *= roughnessScale;
// Set the roughness value to be used by the custom material shader.
params.surface().set_roughness(roughness);
```
For more information on creating custom materials and writing shader
functions, see
<doc:modifying-realitykit-rendering-using-custom-materials>.
- Parameters:
- scale: The roughness value.
- texture: An optional image texture.
get · iOS 15.0+
scale
TypeScript
get scale(): number
Swift declaration
var scale: Float
The roughness value for the entire entity or a multiplier for its
texture.
set · iOS 15.0+
scale
TypeScript
set scale(value: number)
Swift declaration
var scale: Float
The roughness value for the entire entity or a multiplier for its
texture.
get · iOS 15.0+
texture
TypeScript
get texture(): (CustomMaterial_CustomMaterialTexture) | null
Swift declaration
var texture: CustomMaterial.Texture?
The roughness values as a UV-mapped image texture.
set · iOS 15.0+
texture
TypeScript
set texture(value: (CustomMaterial_CustomMaterialTexture) | null)
Swift declaration
var texture: CustomMaterial.Texture?
The roughness values as a UV-mapped image texture.
Creates a roughness object from a physically based material’s
roughness property.
This initializer creates a roughness object by copying the scale and
texture values from an existing
``PhysicallyBasedMaterial/Roughness-swift.struct`` object.
With custom materials, the `texture` and `scale` properties of the
``CustomMaterial/Roughness-swift.struct`` object are available in
your surface shader function, but RealityKit doesn’t automatically
use them when rendering your entity.
To render an entity with roughness, set
``CustomMaterial/lightingModel-swift.property`` to
``CustomMaterial/LightingModel-swift.enum/lit`` or
``CustomMaterial/LightingModel-swift.enum/clearcoat``,
and call `params.surface().set_roughness()`
from its surface shader.
To achieve the same roughness behavior as
``PhysicallyBasedMaterial``, the surface shader function multiplies
roughness scale by the sampled value from the texture, as the
following Metal code demonstrates:
```swift
// Retrieve the roughness scale from the CustomMaterial.
float roughnessScale = params.material_constants().roughness_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 roughness = tex.roughness().sample(textureSampler, uv).r;
// Multiply the scale and the sampled value from the texture, and assign
// the result to the shader's base color property.
roughness *= roughnessScale;
// Set the roughness value to be used by the custom material shader.
params.surface().set_roughness(roughness);
```
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 roughness property.
