Creates an opacity object from a single value.
This initializer creates an object that defines the opacity of an
entity using a single value for the entire entity. This value is
available to the material’s surface shader function, but RealityKit
draws the entity fully opaque unless the surface shader function
calls `params.surface().set_opacity()`.
The following Metal code demonstrates how to set the entity’s
opacity in the material’s surface shader function based on `value:`
```swift
// Retrieve the opacity scale from the CustomMaterial.
float opacityScale = params.material_constants().opacity_scale();
// Use the opacity scale to set the current pixel's opacity.
params.surface().set_opacity(opacityScale);
```
- Parameters:
- value: The opacity value.
Creates an object that defines the opacity of an entity using a
single value, a UV-mapped image texture, or both.
Both `scale` and `texture` are available to the material’s surface
shader function, but RealityKit draws the entity fully opaque unless
the surface shader function calls `params.surface().set_opacity()`.
The following Metal code demonstrates how to emulate the blending
logic RealityKit uses to render entities with a
``PhysicallyBasedMaterial`` in your custom material’s surface shader
function:
```swift
// Retrieve the opacity scale and threshold from the CustomMaterial.
float opacityScale = params.material_constants().opacity_scale();
float opacityThreshold = params.material_constants().opacity_threshold();
// Retrieve the entity's texture coordinates.
float2 uv = params.geometry().uv0();
// Entities loaded from USDZ or .reality files use texture coordinates with
// a flipped y-axis. This compensates for that.
uv.y = 1.0 - uv.y;
// Retrieve the opacity texture from the material.
auto tex = params.textures();
// Sample the value from the opacity texture.
half opacity = tex.opacity().sample(textureSampler, uv).r;
if (opacityThreshold > 0.0) {
// If the opacity threshold is greater than 0, use masking behavior
// and set the opacity to either 1.0 or 0.0 depending on the value
// of the opacity threshold.
opacity = (opacity <= opacityThreshold) ? 0.0 : 1.0;
} else {
// If the opacity threshold is 0, then mutiply opacity by scale.
opacity *= opacityScale;
}
// Use the calculated value to set the opacity for rendering.
params.surface().set_opacity(opacity);
```
- Parameters:
- scale: The opacity value for the entire material.
- texture: The opacity values as a UV-mapped image.
get · iOS 15.0+
scale
TypeScript
get scale(): number
Swift declaration
var scale: Float
The amount of opacity specified as a single value.
If ``CustomMaterial/Opacity/texture`` is `nil`, RealityKit uses this
value for the opacity of the entire material. If
``CustomMaterial/Opacity/texture`` isn’t `nil`, RealityKit
multiplies the value sampled from ``CustomMaterial/Opacity/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 amount of opacity specified as a single value.
If ``CustomMaterial/Opacity/texture`` is `nil`, RealityKit uses this
value for the opacity of the entire material. If
``CustomMaterial/Opacity/texture`` isn’t `nil`, RealityKit
multiplies the value sampled from ``CustomMaterial/Opacity/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 amount of opacity specified using a UV-mapped image.
set · iOS 15.0+
texture
TypeScript
set texture(value: (CustomMaterial_CustomMaterialTexture) | null)
Swift declaration
var texture: CustomMaterial.Texture?
The amount of opacity specified using a UV-mapped image.
Creates an object from the opacity property of an existing
physically based material.
This initializer creates a new object by copying values from an
existing physically based material’s
``PhysicallyBasedMaterial/blending-swift.property`` property. All of
the copied values, including ``CustomMaterial/Opacity/scale``,
``CustomMaterial/Opacity/texture``, and
``CustomMaterial/opacityThreshold`` are available to the material’s
surface shader function, but RealityKit draws the entity fully
opaque unless the surface shader function calls
`params.surface().set_opacity()`.
The following Metal code demonstrates how to emulate the blending
logic RealityKit uses to render entities with a
``PhysicallyBasedMaterial`` in your custom material’s surface shader
function:
```swift
// Retrieve the opacity scale and threshold from the CustomMaterial.
float opacityScale = params.material_constants().opacity_scale();
float opacityThreshold = params.material_constants().opacity_threshold();
// Retrieve the entity's texture coordinates.
float2 uv = params.geometry().uv0();
// Entities loaded from USDZ or .reality files use texture coordinates with
// a flipped y-axis. This compensates for that.
uv.y = 1.0 - uv.y;
// Retrieve the opacity texture from the material.
auto tex = params.textures();
// Sample the value from the opacity texture.
half opacity = tex.opacity().sample(textureSampler, uv).r;
if (opacityThreshold > 0.0) {
// If the opacity threshold is greater than 0, use masking
// behavior and set the opacity to either 1.0 or 0.0 depending
// on the value of the opacity threshold.
opacity = (opacity <= opacityThreshold) ? 0.0 : 1.0;
} else {
// If the opacity threshold is 0, mutiply the opacity by scale.
opacity *= opacityScale;
}
// Use the calculated value to set the opacity for rendering.
params.surface().set_opacity(opacity);
```
- Parameters:
- value: The opacity property from the ``PhysicallyBasedMaterial``’s
``PhysicallyBasedMaterial/blending-swift.property`` property.
