Module: Mesh opacity

Package path: packages/babylon-lite/src/mesh/opacity/

Purpose

Provide opt-in native per-mesh opacity for ordinary Standard and PBR meshes without changing or cloning their materials. The compat layer implements Mesh.visibility automatically through the same native API. Meshes sharing a material, including glTF primitive meshes, can have independent opacity.

Opacity is separate from mesh visibility, hierarchy, picking, bounds and visibility epochs. Thin instances share their owning mesh's opacity. Node/shader materials cannot fade below 1. MeshLoD instances are not ordinary Mesh objects and are not supported targets at any opacity. Per-instance opacity, submesh opacity and compat InstancedMesh.visibility are outside this module's contract.

Public API surface

Both functions are named exports from the sole package root:

function setMeshOpacity(mesh: Mesh, opacity: number): void;
function getMeshOpacity(mesh: Mesh): number;

The default is 1. The native setter clamps finite numbers to [0, 1]; the getter returns the stored clamped value, including after disposal.

The setter performs these operations in order:

1. Reject non-number, NaN and infinite input with RangeError: setMeshOpacity: opacity must be a finite number, got <value>.
2. Require an object with the existing _gpu Mesh discriminator. Otherwise throw: setMeshOpacity: "<name>" is not a Lite Mesh (for example a MeshLoD instance); per-mesh opacity is not supported on MeshLoD in this release. The getter performs the same target check with its own API-name prefix.
3. Reject _disposed: Mesh "<name>" cannot set opacity: it was disposed when it left its last scene. Create a new mesh instead.
4. Clamp the value.
5. If below 1, validate a non-null material's _buildGroup._materialFamily. Only "standard" and "pbr" are accepted; otherwise throw: setMeshOpacity: mesh "<name>" uses a "<family>" material; mesh opacity supports only "standard" and "pbr" materials.
6. Install the feature once. If the stored/default value already equals the new clamped value, return without storing, dirtying or writing.
7. Store the value and synchronously set mesh._skipColorDraw = value === 0, enqueue a rebuild on crossing 1, and update live binding uniforms with every changed value, including 1.

A null material is permitted. An ordinary, non-disposed Mesh can reset to 1 regardless of material family. Invalid calls must not install hooks/extensions, store state, allocate/write buffers, enqueue swaps or mutate scenes.

Internal architecture

Mesh value and binding records

The feature uses a local intersection, not a member on the core Mesh interface:

type OpacityMesh = Mesh & { _opacity?: number };
interface OpacityBinding {
    readonly _buffer: GPUBuffer;
    readonly _device: GPUDevice;
    readonly _engine: EngineContext;
    readonly _disposers: (() => void)[];
}

mesh-opacity.ts owns validation, the scalar, installation, transitions and GPU records. A lazily created WeakMap<Mesh, Set<OpacityBinding>> tracks live binding-owned buffers. Neither the map nor its sets are allocated at import time. A reusable one-element Float32Array supplies live writes; a separate two-element array supplies binding initialization.

Each mesh's binding lifetime and device pair owns one 16-byte uniform buffer. Its first two f32 values are [opacity, policy], at byte offsets 0 and 4. Standard ignores the second value (initialized to 0); PBR uses it as an immutable per-binding OPAQUE policy. Live setters write only four bytes at offset 0, never the policy. Repeated binds with the same disposer-array identity and device reuse the existing buffer and record without another allocation, initial upload or disposer, preserving its creation-time policy even if a later bind supplies a different policy. Different lifetime arrays or devices create separate records; no material owns this buffer. Native shallow mesh clones copy the scalar and its corresponding skip flag but never the records.

Lazy installation and chained installers

The first successful setter call runs this once-guarded sequence:

1. Register Standard extension "0-mesh-opacity".
2. Register PBR extension "z-mesh-opacity".
3. Install a mesh-feature encoder returning 1 << 22 iff opacity is below 1.
4. Install a PBR binding-context augmenter that copies the binding's disposer array into context._disposers.
5. Install material-transition validation using the mesh's live opacity.

Extension registration invalidates sorted-extension caches. No registration, map/set allocation or GPU work executes merely by importing the API.

The generic installers preserve earlier features in installation order:

This preserves mirrored-mesh encoding, rect-area binding context and indexed-indirect borrow validation in either install order. Features installing into a chained slot must guard their own one-time installation: opacity does so, and installRectAreaEmissionPbr does so before installing its lighting-id/disposer augmenter. Binding ids and disposer arrays remain per invocation, not captured from the first prepare.

Mesh-bit transport and Standard folding

material/mesh-features.ts reserves mesh bit 22 with a comment. The opacity encoder owns its meaning; it does not add a shared opacity constant or read opacity from core code. The installed encoder returns 0 at opacity 1 and sets bit 22 below 1. It does not encode material alpha policy.

PBR's opacity fragment declares the feature-local MESH_OPACITY_MESH_BIT = 1 << 22. OPAQUE alpha policy lives in the uniform, not a shader-variant bit.

Standard uses its existing extension hook:

_meshFeatures?(meshFeatures: number, material?: StandardMaterialProps): number;

The opacity Standard hook tests mesh bit 22 and the source material's cached NO_COLOR_OUTPUT | ESM_SHADOW_OUTPUT bits. For a fading colour mesh it returns the feature-local STD_MESH_OPACITY_BIT = 1 << 30 plus MATERIAL_ALPHA_BLEND; otherwise it returns 0. Bit 30 is reserved by a comment in standard-flags.ts. Both Standard forward and geometry fold this result into their effective material features.

Standard forward queue classification retains the live mat.alpha < 1 term and tests the final HAS_OPACITY_TEXTURE | MATERIAL_ALPHA_BLEND word. Queue and pipeline selection therefore use the opacity-folded blend bit without dropping the existing live material-alpha behavior.

PBR folding at three consumers

PBR has no per-mesh extension fold hook or scratch object. The existing generic transport is:

(meshFeatures >>> 16) & PBR_HAS_ALPHA_BLEND;

Mesh bit 22 maps to material alpha-blend bit 6. The feature bit remains in the mesh word for the opacity PBR fragment; the generic fold supplies routing, blend state and compose-key identity.

The three consumers are:

1. pbr-renderable.ts forward rebuild. OR the transport into renderFeatures.features only when features2 contains neither PBR2_NO_COLOR_OUTPUT nor PBR2_ESM_SHADOW_OUTPUT. This effective word drives composition, binding/pipeline keys and transparent classification.
2. pbr-geometry-renderable.ts geometry pipeline selection. Geometry's composition view strips the material blend branch, but its source blend decision ORs the transport into source._renderFeatures?.features ?? 0. This colour-output route therefore blends and disables depth writes for a fading mesh while the geometry shader still gates on effective alpha.
3. pbr-built-variant.ts composed-variant lookup. Before _pbrComposeKey, fold the same transport into the source features with the same no-colour/ESM mask as forward. The lookup must ask for the variant the forward rebuild actually composes.

Shadow/no-colour/ESM outputs do not gain the alpha-blend bit or opacity fragment. Mesh bit 22 may still distinguish otherwise identical shadow variant keys; it does not change caster alpha.

_pbrMeshRequest(scene, mesh, noShadows) retains its four-item return:

readonly[(context, meshFeatures, lightMode, singleLightType)];

Forward generation metadata remains:

[geometryContext, meshFeatures, lightMode, singleLightType, renderFeatures];

There is no additional folded-material field in either tuple and no change to Renderable or geometry-view generation metadata.

Binding context and retirement transport

_PbrBindCtx._mesh permits Mesh | null. The opacity extension requires an actual mesh and its binding-owned disposer array.

_installPbrBindingContext also enables _pbrBindingIdentity, an identity function for the optional numeric binding id, and _createPbrBindingDisposers, a factory returning a fresh array. createPbrMeshBindGroup builds its ordinary context, invokes the installed augmenters, then runs the fragment bind hooks. Only feature-owned augmenters populate _disposers and _lightingId.

PBR geometry uses exactly:

const bindingDisposers = _createPbrBindingDisposers?.();

There is no ?? [] fallback. Without an installer this remains undefined and does not allocate an auxiliary lifetime collection. With opacity installed, the factory exists before geometry binds. The same array reaches the PBR context and geometry teardown. Standard passes its existing main/geometry binding-owned array through StdExt._bind.

Transparent and geometry loop skip

The Mesh interface declares an optional @internal _skipColorDraw?: boolean. It has no factory initializer and is absent from public declarations. Only setMeshOpacity writes it, immediately after storing the clamped scalar. It is true exactly at opacity 0 and false at every other assigned value. It lives with the mesh and owns no resources, so no additional disposal hook is needed.

The general render loops read this generic flag alongside their existing visible === false test. For this feature, a plain internal-field read is an explicitly approved exception to GUIDANCE's engine-installed-seam requirement: it costs about 16–25 B in scenes that never use opacity, less than the alternative opt-in per-renderable draw-wrapper hook, which measured up to 148 B in the same scenes. No renderer imports opacity or reads the opacity scalar.

Fading Standard/PBR colour bindings are forced into transparent lists by the existing feature folding. Shadow renderables are never transparent, so their opaque/direct lists ignore the skip flag and preserve full-strength casting. Opaque render-bundle recording and visibility epochs are unchanged.

The loops read the flag every frame. A 0.5 → 0 → 0.5 transition skips and resumes without rebuilding or caching a stale skip. Opaque twins replay the same bundle. Public visible, compat isVisible, picking and accessibility are independent and never changed by opacity.

This is CPU draw omission, not shader discard. Standard/PBR builders return their ordinary unwrapped draws; there is no mesh draw-hook module, wrapper or installer. Direct invocation of a raw binding bypasses task-level filtering. The diagnostic overdraw probe remains unchanged and may count opacity-0 transparent bindings.

Pipeline configuration

Fading a mesh in a geometry task makes it a blended participant. Every colour target must be blendable: default VIEW_DEPTH (r32float) requires the device feature float32-blendable, or an r16float format override. Integer tag targets are never blended. This is the same requirement as a material's own BLEND policy. PBR, Standard, and Node geometry pipeline creation enforces the format contract through _geometryColorTarget. A blended 32-bit float target without the feature throws the existing error: Transparent geometry output format "${format}" requires the float32-blendable WebGPU feature or a blendable format override. Validation also rejects blended integer formats; the mesh-blending tag target remains explicitly unblended.

Faded cutouts discard geometry fragments whose post-opacity alpha <= 0.4, before any data or mesh-blending tag write. They therefore preserve underlying tags rather than writing a cutout's raw tag through a suppressed data sample. The trade-off is that these samples also stop contributing to an extra emit-colour slot. Forward cutout coverage is unchanged.

PBR main transparent order is 150; Standard main and both geometry routes use 200. Existing material-level alpha-to-coverage and :a2c pipeline identity remain; A2C and blending both see final alpha. No material alpha, alpha-test cutoff, alphaBlend flag or visible flag is mutated. Mirroring, VAT, thin instances and transmission remain independent.

Uniform layout

Each active opacity fragment contributes one structured declaration:

{
    _name: "meshOpacity",
    _type: { _kind: "uniform-buffer" },
    _visibility: SS.FRAGMENT,
}

Standard's helper is struct meshOpacityUniforms{value:f32}; PBR's is struct meshOpacityUniforms{value:f32,policy:f32}. The composer assigns the group-1 binding index from declarations; never parse emitted WGSL for an index. The bind hook pushes { binding, resource: { buffer } } and returns binding + 1. It reuses a record with the same lifetime array and device when present; otherwise it initializes the uniform from current mesh state, records the buffer and appends its disposer. Missing mesh/scene or lifetime transport throws a route-specific internal invariant error rather than silently allocating a fallback collection.

_bindMeshOpacity accepts a final optional numeric policy = 0 argument. Only creation initializes both floats; a reused record never rewrites them. PBR chooses the classifier with the same post-fold ctx._features & PBR_HAS_ALPHA_BLEND discriminator as its fragment slots. Forward bindings use the rendered binding material's own _renderFeatures: a public material view's declared flags, not its source's flags. Otherwise, geometry bindings use (material.source ?? material)._renderFeatures, because the geometry view strips the blend branch. Set policy 1 iff the chosen features exist and their pre-fold features contain neither PBR_HAS_ALPHA_BLEND nor PBR_HAS_ALPHA_TEST; otherwise set 0, including when features are absent. This uses only a type-only material-view import and plain fields, adding no runtime module dependency to Standard-only opacity scenes.

Overrides therefore use the override's own policy, not mesh.material. Material swaps and renderable rebuilds follow the new material/view policy through new lifetime-owned bindings. Rebinding the same lifetime/device retains its creation-time policy, consistent with its already-prepared pipeline variant.

Standard's leading "0-mesh-opacity" extension/fragment id aligns registry and composer ordering before "0-std-uv-transform". PBR uses id: "z-mesh-opacity", phase: "fragment"; its bind order follows the composed fragment key. Main, refraction and geometry each use the layout they composed.

Shader logic

Standard

Use slot BC:

alpha = alpha * meshOpacity.value;
color = vec4<f32>(color.rgb, color.a * meshOpacity.value);

The original AT alpha-test discard has already run; fog BA has not. Geometry compositions (features & GEOMETRY_OUTPUT) append if (mat.aCut > 0.0 && alpha <= 0.4) { discard; } to this BC. mat is in scope, and alpha is the same running value used by the geometry data gate. Forward BC remains exactly the two statements above. Colour returns color.a, while geometry gates on alpha > 0.4, so both alpha representations must be multiplied. No-colour/ESM templates return without this fragment. OPAQUE and surviving MASK fragments can therefore fade without changing their original discard threshold.

PBR

Return no fragment unless mesh bit 22 is set and features2 is neither no-colour nor ESM. Forward composition includes both policy normalization and the final opacity multiply; geometry combines them in one slot:

OPAQUE alpha policy: policy 1 treats source alpha as 1 even if the base-colour texture, base-colour factor or vertex colours carry alpha. Forward BC runs after decoding/vertex-colour alpha and before var finalAlpha=. The usual luminance fold saturates normalized alpha to 1; FA multiplies after that fold. Thus final alpha equals mesh opacity, not opacity plus luminance. Geometry normalizes and multiplies together before alpha > 0.4. Gamma-albedo and unlit paths declare alpha and use the same policy.

Own alpha policies: BLEND and material alpha below 1 retain the existing forward FA multiply after the normal output-alpha calculation: saturate(alpha * materialAlpha + luminanceOverAlpha²) * opacity. Geometry strips the blend branch and uses the combined BC with policy 0. MASK also uses policy 0 and keeps its forward FA / geometry BC behavior. Both occur after the original AT cutoff, so that cutoff tests the material's own alpha, not mesh opacity. Forward mesh opacity does not change which MASK fragments survive. In geometry only, PBR variants with PBR_HAS_ALPHA_TEST append if (alpha <= 0.4) { discard; } after the combined opacity BC, before the first data/tag write. Thus faded cutouts also obey the geometry data gate, while opacity-1 variants keep their original raw MASK tag and Standard aCut select. Non-cutout geometry and forward paths do not gain this discard. The opacity extension intentionally does not import geometry attachment state; a rejected sample also omits any extra emit-colour output.

The shadow-only fragment owns and internally exports PBR2_HAS_SHADOW_ONLY = 1 << 30. The lazy opacity fragment imports it from fragments/shadow-only-fragment.ts, not shared flags or the public root. When that features2 bit is set, declare dependency ["shadow-only"]; otherwise omit the dependency. Shadow-only's own features force alpha blending, so its policy is 0. The policy BC runs after shadow-only's BC and leaves that mask intact; opacity FA runs after shadow-only's final-alpha write and scales the mask, without a missing-dependency error or luminance bleed.

Refraction opens its conditional in NI and closes it in BC. The "z-" id places the geometry alpha override or multiplier after that closing brace. Transmission/refraction write colour, not alpha. The selected opacity slot runs before output or the geometry gate.

Why not a variant bit? The blend fold makes faded OPAQUE and BLEND materials share a compose key when their other features match. A distinguishing key bit would require shared transport/key changes and add bytes to unrelated scenes. Policy derived from cached mesh/material features can also go stale or describe the wrong material for an override. The binding uniform follows the rendered material/view classifier and its lifetime instead; no shared shader-key or render-loop change is needed.

State machine and lifecycle

Dirtying uses markMeshRenderableDirty and existing per-scene swap-queue deduplication; it never bumps the visibility epoch. Boundary enqueueing and direct writes are independent.

Explicit render tasks

An autoMirror: false render task normally retains the renderables resolved by addMeshToTask. A crossing of 1 changes the opaque/transparent pipeline variant only when the task opts into enableRenderTaskMeshRefresh before recording, and the entry is a scene-owned mesh added without a per-task material override. As with material swaps, the owning scene first drains its rebuild queue; the enabled task follows the resulting renderable version on execute. It rebuilds its own auxiliary renderable and retires the old lifetime disposers after submitted GPU work drains. See Frame Graph — explicit-task mesh refresh.

const task = createRenderTask({ name: "fading", rt, autoMirror: false }, engine, scene);
enableRenderTaskMeshRefresh(task);
addMeshToTask(task, mesh);

Once a transparent binding is current, updates below 1 and the 0 skip are live; they require no task rebuild. A plain explicit task retains its old renderable across crossings, so callers must deliberately synchronize/re-record it if they do not enable refresh. Opaque lists do not check the opacity-0 flag: those lists also serve shadow tasks, where opacity must not remove casters, and opaque render bundles cache draws. Skipping there would break the shadow gate and cached-bundle replay contract. The flag is read only on transparent/transmission colour lists and geometry paths.

Unregistered meshes and retained bindings

A mesh registered in no scene but drawn through an explicit geometry-task meshes list picks up opacity threshold crossings (1 ↔ <1, selecting a pipeline/blend variant) only at that task's next renderable sync. This is the same contract as material/topology changes on such meshes; the setter does not invalidate off-scene geometry tasks. Value updates below 1 and the opacity-0 skip apply immediately. Returning to 1 also writes 1 to retained binding buffers, so they do not retain the old opacity while waiting for that sync.

Rapid double crossing: for 0.3 → 1 → 0.6 before asynchronous replacement settles, the retained transparent binding must receive 0.6, even though a rebuild was enqueued. A replacement binding initializes from the latest stored value. The intermediate transition to 1 writes 1 to still-live buffers. Zero/fraction changes require no rebuild because the loops read the synchronously updated skip flag.

For each direct write, require record._engine._device === record._device. Skip stale-device records without destroying them in the setter. The binding disposer removes its record before destroying the buffer and is idempotent.

Refraction rebinds reuse the opacity record and buffer associated with the same renderable lifetime array and device, even when other bind-group entries change. Each new lifetime or device gets a separate buffer. There is no new signature cache. Teardown of one scene removes only that scene's records when a mesh belongs to several scenes. The existing last-scene removal disposes mesh GPU resources and marks it disposed; opacity adds no mesh-disposal or retirement observer.

Recovery's material-group rebuild computes mesh features even at opacity 1. The installed opacity feature encoder, when the binding map exists, retires records whose engine's current device differs from their captured device. The setter uses the same helper before writing live records. Retirement removes the record before destroying its lost-device buffer; a later old disposer sees that deletion already happened and does nothing. Recovery clears the scene's disposer map without invoking it, so encoder retirement is required even if opacity was reset to 1 and no replacement binding is created. Faded meshes rebuild bindings from the latest scalar; live updates reach only matched-device records. Opacity owns no device-scoped cache.

Material replacement and target exclusion

For a faded registered mesh, the chained validator rejects an unsupported material synchronously before mesh.material stores the value or queues work. Registration validates an unregistered mesh's pending raw assignment before enrollment. Previous validators retain their ordering and atomicity.

MeshLoD instances lack _gpu and cannot be passed to either opacity API. Their asset/instance enrollment paths do not accept an ordinary Mesh, so neither operation order puts an opacity-bearing Mesh into a MeshLoD batch. No MeshLoD hook, scan or metadata is added. Sharing a material with a fading ordinary Mesh does not mutate that material.

Babylon.js equivalence map

Compat Mesh.visibility statically imports the native API; there is no compat enabler. The wrapper stores the raw finite value but renders the clamped native value. Non-finite assignments throw. Family checks use the compat unsupported(...) helper.

Validate all owned primitives before writing any; publish the wrapper's raw value only after native writes succeed. A GPU wrapper owns itself. A transform-only glTF-node wrapper owns its immediate GPU primitive children, not descendants through child nodes. The synthetic root owns no geometry. _fromLite reads native opacity for an actual GPU wrapper; transform-only wrappers start at 1.

Raw getters belong to the wrapper assigned, not to an inherited parent factor. Owner fan-out changes primitive rendering factors without changing primitive wrappers' independent raw getters. Effective native opacity is also checked for material replacement. Pending NodeMaterial handles are rejected below 1 before their native material exists. Clone copies the raw value without a redundant setter. isVisible and _syncVisibility are unchanged.

Dependencies

Use the existing Standard/PBR registries, structured shader composer, material family tags, scene validator/dirty registry, binding-owned lifetime arrays and clone/recovery paths. Runtime family code imports only generic seams, never this feature. Internal hooks and WebGPU handles do not leak through root declarations. The package still exposes one root export.

Core transport and draw call sites can survive across production chunk boundaries even when feature bodies are absent. Absence of opacity implementation markers is not proof of zero runtime-byte cost. Runtime-size checks count actually fetched JS with the repository's existing exclusions and gzip accounting, not artifact inventories.

Test specification

• Native input/error atomicity, finite clamping, disposal, clone isolation, unchanged material/picking/visibility, MeshLoD rejection and null-material policy.
• All boundary/non-boundary transition counts, multi-scene records, idempotent disposal, recovery/device mismatch and rapid-double-crossing buffer freshness.
• Off-scene retained geometry bindings receive 1 on reset. Repeated binds on the same device and lifetime allocate one buffer/disposer/record and write once per update; different lifetime arrays or devices remain independent.
• Atomic unsupported material swaps and both installation orders with the real indexed-indirect borrow validator; previous-first feature/context chains.
• PBR per-binding OPAQUE policy with alpha-bearing texture/factor/vertex colours, gamma/unlit forward/geometry matrix, large luminance and coherent compose keys. Explicit overrides in both directions use the rendered binding's policy: forward public views use their own flags when adding or stripping blend, while geometry views use the source's flags. Plain OPAQUE forward bindings retain policy 1; OPAQUE/BLEND/OPAQUE/Standard swaps create new bindings. Live writes preserve the policy while changing only four bytes at offset 0; same-lifetime reuse preserves creation-time policy. Shadow-only initializes [opacity, 0] and retains its mask. BLEND/material-alpha multiplication and MASK forward FA / geometry BC remain after the original cutoff. Standard output alpha ignores diffuse-texture alpha. Verify shadow-only dependencies, refraction closing braces, geometry > 0.4 gates and composer/bind-index equality.
• Transparent and geometry task loops skip colour draws at zero and resume live when the flag clears. Opaque/direct lists ignore it, preserving no-colour/ESM casters. Transmission and renderOnTop checks preserve texture-update ordering. Raw bindings remain unwrapped. Twin-bundle tests replay the same opaque bundle and preserve the visibility epoch while only the faded transparent draw changes.
• Scene-owned non-override explicit entries follow opacity crossings only with mesh refresh. Drain the real scene rebuild queue and execute the real task: 1 → 0.5 selects transparent, 0.5 → 0 skips live, and 0.5 → 1 restores opaque and retires auxiliary lifetimes. Plain explicit tasks retain their renderables.
• Flag tests cover zero-to-fraction/one, invalid-call atomicity, clone isolation, unchanged public visibility/pickability and accessibility projection.
• Preserve Standard's live material-alpha classification, A2C plus blending, mirroring/VAT bindings, PBR generation identity and composed-key consistency.
• Repeated rect-area emission installer calls register one context augmenter; that augmenter forwards each bind's current identity and lifetime array.
• Compat raw/clamped values, independent isVisible, atomic glTF fan-out, no inheritance, clone/_fromLite and unsupported material assignments.
• Build probes: unused entries contain no feature body markers; opted-in entries retain them. Root declaration trimming and root-only exports hold; MeshLoDInstance is a compile-time-invalid opacity target.
• Scene354 supplies static Standard/PBR 1/0.5/0 and opaque twins, normalized OPAQUE/MASK cases, full-strength shadows and A2C. Its BJS golden is immutable; pixel/MAD coverage belongs to the existing scene parity infrastructure.

File manifest

src/ below means packages/babylon-lite/src/. Listed generic files contain transport or integration, not feature-owned opacity comparisons.