An object that defines the specular highlights of an entity.
In physically based rendering (PBR), specular highlights primarily come
from the object’s ``PhysicallyBasedMaterial/roughness-swift.property``
value. RealityKit renders materials that have a low roughness value with
specular highlights based on the environment, lighting, and shape of the
entity.
For more information on using specular values in a custom material, see
``CustomMaterial/specular-swift.property``.
Creates an object from a single value.
RealityKit automatically draws _specular highlights_ for physically
based materials using the values of various properties, primarily
``PhysicallyBasedMaterial/roughness-swift.property`` and
``PhysicallyBasedMaterial/metallic-swift.property``. Specular
highlights are bright spots of reflected light that appear on shiny
objects.
-1)
While many real-world objects can be accurately and realistically
simulated with just the core physically based rendering (PBR)
properties, you can create additional realistic effects by
augmenting the specular highlights.
This initializer creates a
``PhysicallyBasedMaterial/Specular-swift.struct`` object from a
single value that applies to the entire material. The specular
``CustomMaterial/Specular-swift.struct/scale`` value is available to
the material’s surface shader, but RealityKit doesn’t create
additional specular highlights unless the surface shader function
calls `params.surface().set_specular()`.
The following Metal code demonstrates using the specular `scale`
value in a surface shader function:
```other
// Retrieve the opacity scale from the CustomMaterial and assign it.
float specularScale = params.material_constants().specular_scale();
params.surface().set_specular(specular);
```
- Parameters:
- value: A value from `0.0` to `1.0` to use as the specular value
for the material.
Creates an object from a single value, a UV-mapped texture, or both.
RealityKit automatically draws _specular highlights_ for physically
based materials using the values of various properties, primarily
``PhysicallyBasedMaterial/roughness-swift.property`` and
``PhysicallyBasedMaterial/metallic-swift.property``. Specular
highlights are bright spots of reflected light that appear on shiny
objects.
-1)
While many real-world objects can be accurately and realistically
simulated with just the core physically based rendering (PBR)
properties, you can create additional realistic effects by
augmenting the specular highlights.
The specular ``CustomMaterial/Specular-swift.struct/scale`` and
``CustomMaterial/Specular-swift.struct/texture`` values are
available to the material’s surface shader, but RealityKit doesn’t
render additional specular highlights unless the surface shader
function calls `params.surface().set_specular()`.
The following Metal code demonstrates using the specular `scale` and
`texture` values in a surface shader function to calculate specular
highlights, emulating the specular behavior of
``PhysicallyBasedMaterial``:
```other
// Retrieve the opacity scale from the CustomMaterial.
float specularScale = params.material_constants().specular_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 the specular texture.
auto tex = params.textures();
half specular = tex.specular().sample(textureSampler, uv).r;
// Multiply the tint and the sampled value from the texture and assign
// the result.
specular *= specularScale;
params.surface().set_specular(specular);
```
- Parameters:
- scale: A value from `0.0` to `1.0` to use as the specular value
for the material.
- texture: An optional UV-mapped image texture.
get · iOS 15.0+
scale
TypeScript
get scale(): number
Swift declaration
var scale: Float
The specular value for the entire entity or a multiplier for values
sampled from the material’s texture.
If ``CustomMaterial/Specular-swift.struct/texture`` is `nil`,
RealityKit uses this value for the opacity of the entire material.
If ``CustomMaterial/Specular-swift.struct/texture`` isn’t `nil`,
RealityKit multiplies the value sampled from
``CustomMaterial/Specular-swift.struct/texture`` by this property to
calculate the final opacity values.
set · iOS 15.0+
scale
TypeScript
set scale(value: number)
Swift declaration
var scale: Float
The specular value for the entire entity or a multiplier for values
sampled from the material’s texture.
If ``CustomMaterial/Specular-swift.struct/texture`` is `nil`,
RealityKit uses this value for the opacity of the entire material.
If ``CustomMaterial/Specular-swift.struct/texture`` isn’t `nil`,
RealityKit multiplies the value sampled from
``CustomMaterial/Specular-swift.struct/texture`` by this property to
calculate the final opacity values.
get · iOS 15.0+
texture
TypeScript
get texture(): (CustomMaterial_CustomMaterialTexture) | null
Swift declaration
var texture: CustomMaterial.Texture?
The specular value as a UV-mapped image texture.
set · iOS 15.0+
texture
TypeScript
set texture(value: (CustomMaterial_CustomMaterialTexture) | null)
Creates an object from a physically based material’s specular
property.
This initializer creates an object by copying the values from an
existing ``PhysicallyBasedMaterial/Specular-swift.struct`` object.
RealityKit automatically draws _specular highlights_ for physically
based materials using the values of various properties, primarily
``PhysicallyBasedMaterial/roughness-swift.property`` and
``PhysicallyBasedMaterial/metallic-swift.property``. Specular
highlights are bright spots of reflected light that appear on shiny
objects.
-1)
While many real-world objects can be accurately and realistically
simulated with just the core physically based rendering (PBR)
properties, you can create additional realistic effects by
augmenting the specular highlights.
The specular ``CustomMaterial/Specular-swift.struct/scale`` and
``CustomMaterial/Specular-swift.struct/texture`` values are
available to the material’s surface shader, but RealityKit doesn’t
add specular highlights unless the surface shader function calls
`params.surface().set_specular()`.
The following Metal code demonstrates using the specular `scale` and
`texture` values in a surface shader function to calculate
additional specular highlights, emulating the behavior of
``PhysicallyBasedMaterial``:
```other
// Retrieve the opacity scale from the CustomMaterial.
float specularScale = params.material_constants().specular_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 the specular texture.
auto tex = params.textures();
half specular = tex.specular().sample(textureSampler, uv).r;
// Multiply the tint and the sampled value from the texture, and
// assign the result.
specular *= specularScale;
params.surface().set_specular(specular);
```
- Parameters:
- value: The ``PhysicallyBasedMaterial/specular-swift.property``
property from a ``PhysicallyBasedMaterial``.
