@adobe/data-gpu 0.9.69

package/src/graphics/rendering/skinning/skinning-attributes/layout.ts

@@ -0,0 +1,20 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+// Skinning attributes live in a separate vertex buffer from the StandardVertex
+// data so static meshes pay no per-vertex cost. Encoded as:
+//
+//   joints  (uint32 × 4) — joint indices into the skeleton (16 bytes)
+//   weights (float32 × 4) — skinning weights, sum to 1.0   (16 bytes)
+//
+// Total stride: 32 bytes / vertex.
+
+export const SKINNING_STRIDE = 32;
+
+export const layout: GPUVertexBufferLayout = {
+    arrayStride: SKINNING_STRIDE,
+    stepMode: "vertex",
+    attributes: [
+        { format: "uint32x4",  offset: 0,  shaderLocation: 4 },
+        { format: "float32x4", offset: 16, shaderLocation: 5 },
+    ],
+};

package/src/graphics/rendering/skinning/skinning-attributes/public.ts

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export { layout, SKINNING_STRIDE } from "./layout.js";

package/src/graphics/rendering/skinning/skinning-attributes/skinning-attributes.ts

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export * as SkinningAttributes from "./public.js";

package/src/graphics/rendering/skinning/skinning-plugin.ts

@@ -0,0 +1,213 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database, Entity } from "@adobe/data/ecs";
+import { Mat4x4 } from "@adobe/data/math";
+import { modelLoader } from "../../scene/model/model-loader-plugin.js";
+import { pbrCore } from "../pbr-core-plugin.js";
+import { transform } from "../../scene/node/transform-plugin.js";
+import { animation } from "../../animation/animation-plugin.js";
+import type { JointTemplate } from "../../scene/model/gltf/parse-skin.js";
+
+/**
+ * pbrSkinning
+ *   query: Model+geometry, _Skeleton
+ *   read:
+ *     geometry
+ *     _skinJointTemplate          (from Geometry)
+ *     _skinInverseBindMatrices    (from Geometry)
+ *     _animationClipRefs          (from Geometry)
+ *     _worldMatrix                (from Model + joint Nodes)
+ *   write:
+ *     _Skeleton                   // new ephemeral entity, one per skinned Model
+ *     Node                        // joint entities (TRS hierarchy)
+ *     Animation                   // optional, when geometry has clips
+ *     _skeletonInstanceBuffer
+ *     _skeletonJointMatrixBuffer
+ *     _skeletonJointMatrixBindGroup
+ */
+export const pbrSkinning = Database.Plugin.create({
+    extends: Database.Plugin.combine(modelLoader, pbrCore, transform, animation),
+    components: {
+        _skeletonJoints:                  { default: [] as number[] },
+        _skeletonGeometry:                Entity.schema,
+        /** 64 bytes — the Model's world matrix, refreshed each frame. */
+        _skeletonInstanceBuffer:          { default: null as GPUBuffer | null },
+        /** N × 64 bytes — joint skinning matrices, refreshed each frame. */
+        _skeletonJointMatrixBuffer:       { default: null as GPUBuffer | null },
+    },
+    archetypes: {
+        _Skeleton: [
+            "_skeletonJoints",
+            "_skeletonGeometry",
+            "_skeletonModelRef",
+            "_skeletonInstanceBuffer",
+            "_skeletonJointMatrixBuffer",
+            "_skeletonJointMatrixBindGroup",
+        ],
+    },
+    transactions: {
+        initSkeleton(t, args: {
+            modelRef: number;
+            geometryRef: number;
+            jointTemplate: readonly JointTemplate[];
+            instanceBuffer: GPUBuffer;
+            jointMatrixBuffer: GPUBuffer;
+            jointMatrixBindGroup: GPUBindGroup;
+            clipRef: number | null;
+        }) {
+            const jointIds: number[] = new Array(args.jointTemplate.length);
+            // jointTemplate is in glTF skin.joints[] order. Parents can come
+            // after children in glTF, so resolve parent entity ids in two passes:
+            // first insert with parent=0, then update each joint's parent.
+            for (let i = 0; i < args.jointTemplate.length; i++) {
+                const j = args.jointTemplate[i];
+                jointIds[i] = t.archetypes.Node.insert({
+                    position: j.position,
+                    rotation: j.rotation,
+                    scale: j.scale,
+                    visible: true,
+                    parent: 0,
+                });
+            }
+            for (let i = 0; i < args.jointTemplate.length; i++) {
+                const parentJoint = args.jointTemplate[i].parentJointIndex;
+                const parentId = parentJoint >= 0 ? jointIds[parentJoint] : args.modelRef;
+                t.update(jointIds[i], { parent: parentId });
+            }
+            t.archetypes._Skeleton.insert({
+                _skeletonJoints: jointIds,
+                _skeletonGeometry: args.geometryRef,
+                _skeletonModelRef: args.modelRef,
+                _skeletonInstanceBuffer: args.instanceBuffer,
+                _skeletonJointMatrixBuffer: args.jointMatrixBuffer,
+                _skeletonJointMatrixBindGroup: args.jointMatrixBindGroup,
+            });
+            if (args.clipRef !== null) {
+                t.archetypes.Animation.insert({
+                    animationClipRef: args.clipRef,
+                    animationTargets: jointIds,
+                    animationTime: 0,
+                    animationSpeed: 1,
+                    animationLoop: true,
+                    animationPlaying: true,
+                });
+            }
+        },
+    },
+    systems: {
+        skinningInitSystem: {
+            create: db => {
+                const initialized = new Set<number>();
+                let layoutCache: GPUBindGroupLayout | null = null;
+                return () => {
+                    const { device } = db.store.resources;
+                    if (!device) return;
+                    if (!layoutCache) {
+                        layoutCache = device.createBindGroupLayout({
+                            entries: [
+                                { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+                                { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+                            ],
+                        });
+                    }
+                    for (const arch of db.store.queryArchetypes(["geometry"])) {
+                        const ids = arch.columns.id;
+                        const geoRefs = arch.columns.geometry;
+                        for (let i = 0; i < arch.rowCount; i++) {
+                            const modelId = ids.get(i);
+                            if (initialized.has(modelId)) continue;
+                            const geoId = geoRefs.get(i);
+                            const geo = db.store.read(geoId);
+                            const template = geo?._skinJointTemplate;
+                            if (!template || template.length === 0) continue;
+                            initialized.add(modelId);
+
+                            const instanceBuffer = device.createBuffer({
+                                size: 64,
+                                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+                            });
+                            const matrixBuffer = device.createBuffer({
+                                size: template.length * 64,
+                                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+                            });
+                            const matrixBindGroup = device.createBindGroup({
+                                layout: layoutCache,
+                                entries: [
+                                    { binding: 0, resource: { buffer: instanceBuffer } },
+                                    { binding: 1, resource: { buffer: matrixBuffer } },
+                                ],
+                            });
+                            db.transactions.initSkeleton({
+                                modelRef: modelId,
+                                geometryRef: geoId,
+                                jointTemplate: template,
+                                instanceBuffer,
+                                jointMatrixBuffer: matrixBuffer,
+                                jointMatrixBindGroup: matrixBindGroup,
+                                clipRef: geo?._animationClipRefs?.[0] ?? null,
+                            });
+                        }
+                    }
+                };
+            },
+            schedule: { during: ["preUpdate"] },
+        },
+        skinningMatrixSystem: {
+            create: db => {
+                let scratch = new Float32Array(0);
+                return () => {
+                    const { device } = db.store.resources;
+                    if (!device) return;
+                    for (const arch of db.store.queryArchetypes([
+                        "_skeletonJoints",
+                        "_skeletonGeometry",
+                        "_skeletonModelRef",
+                        "_skeletonInstanceBuffer",
+                        "_skeletonJointMatrixBuffer",
+                    ])) {
+                        const jointsCol = arch.columns._skeletonJoints;
+                        const geoCol = arch.columns._skeletonGeometry;
+                        const modelCol = arch.columns._skeletonModelRef;
+                        const instBufCol = arch.columns._skeletonInstanceBuffer;
+                        const bufCol = arch.columns._skeletonJointMatrixBuffer;
+                        for (let i = 0; i < arch.rowCount; i++) {
+                            const joints = jointsCol.get(i);
+                            const geoId = geoCol.get(i);
+                            const modelId = modelCol.get(i);
+                            const instanceBuffer = instBufCol.get(i);
+                            const buffer = bufCol.get(i);
+                            if (!buffer || !instanceBuffer) continue;
+                            const ibm = db.store.get(geoId, "_skinInverseBindMatrices");
+                            if (!ibm) continue;
+                            const modelWorld = db.store.get(modelId, "_worldMatrix");
+                            if (!modelWorld) continue;
+
+                            // The vertex shader's `instances[0]` slot.
+                            device.queue.writeBuffer(instanceBuffer, 0, new Float32Array(modelWorld));
+
+                            const invModelWorld = Mat4x4.inverse(modelWorld);
+                            if (scratch.length < joints.length * 16) {
+                                scratch = new Float32Array(joints.length * 16);
+                            }
+                            for (let j = 0; j < joints.length; j++) {
+                                const jw = db.store.get(joints[j], "_worldMatrix") ?? Mat4x4.identity;
+                                // inverse(modelWorld) × jointWorld × IBM — leaves vertices in
+                                // model-local space; vertex shader applies modelWorld separately.
+                                const ibmJoint: Mat4x4 = [
+                                    ibm[j * 16 + 0],  ibm[j * 16 + 1],  ibm[j * 16 + 2],  ibm[j * 16 + 3],
+                                    ibm[j * 16 + 4],  ibm[j * 16 + 5],  ibm[j * 16 + 6],  ibm[j * 16 + 7],
+                                    ibm[j * 16 + 8],  ibm[j * 16 + 9],  ibm[j * 16 + 10], ibm[j * 16 + 11],
+                                    ibm[j * 16 + 12], ibm[j * 16 + 13], ibm[j * 16 + 14], ibm[j * 16 + 15],
+                                ];
+                                const m = Mat4x4.multiply(Mat4x4.multiply(invModelWorld, jw), ibmJoint);
+                                scratch.set(m, j * 16);
+                            }
+                            device.queue.writeBuffer(buffer, 0, scratch, 0, joints.length * 16);
+                        }
+                    }
+                };
+            },
+            schedule: { during: ["preRender"], after: ["transformSystem"] },
+        },
+    },
+});

package/src/graphics/rendering/standard-vertex/layout.ts

@@ -0,0 +1,19 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { getStructLayout } from "@adobe/data/typed-buffer";
+import { schema } from "./schema.js";
+
+const sl = getStructLayout(schema);
+
+export const layout: GPUVertexBufferLayout = {
+    arrayStride: sl.size,
+    stepMode: "vertex",
+    attributes: [
+        { format: "float32x3", offset: sl.fields["position"]!.offset, shaderLocation: 0 },
+        { format: "float32x3", offset: sl.fields["normal"]!.offset, shaderLocation: 1 },
+        { format: "float32x4", offset: sl.fields["tangent"]!.offset, shaderLocation: 2 },
+        { format: "float32x2", offset: sl.fields["uv"]!.offset, shaderLocation: 3 },
+    ],
+};
+
+export const stride = sl.size;

package/src/graphics/rendering/standard-vertex/public.ts

@@ -0,0 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export * from "./schema.js";
+export * from "./layout.js";

package/src/graphics/rendering/standard-vertex/schema.ts

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Vec2, Vec3, Vec4 } from "@adobe/data/math";
+import { Schema } from "@adobe/data/schema";
+
+export const schema = {
+    type: "object",
+    properties: {
+        position: Vec3.schema,
+        normal: Vec3.schema,
+        tangent: Vec4.schema,
+        uv: Vec2.schema,
+    },
+    required: ["position", "normal", "tangent", "uv"],
+    additionalProperties: false,
+    layout: "packed",
+} as const satisfies Schema;

package/src/graphics/rendering/standard-vertex/standard-vertex.ts

@@ -0,0 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Schema } from "@adobe/data/schema";
+import { schema } from "./schema.js";
+
+export type StandardVertex = Schema.ToType<typeof schema>;
+
+export * as StandardVertex from "./public.js";

package/src/graphics/rendering/visible-material/color-material-options.ts

@@ -0,0 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Vec3 } from "@adobe/data/math";
+
+export interface ColorMaterialOptions {
+    color: readonly [number, number, number, number];
+    emissive?: Vec3;
+    metallic?: number;
+    roughness?: number;
+}

package/src/graphics/rendering/visible-material/create-bind-group-layout.ts

@@ -0,0 +1,35 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/**
+ * Bind group layout for a visible (PBR-style) material: a uniform buffer
+ * with the material factors, five 2D textures (baseColor, metallicRoughness,
+ * normal, occlusion, emissive), and a filtering sampler. Stable across
+ * renderer pipeline creation and the bind-group builders in `_modelLoader`
+ * and `VisibleMaterial.createColorBindGroup`.
+ */
+export function createBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+    const textureEntry = (binding: number): GPUBindGroupLayoutEntry => ({
+        binding,
+        visibility: GPUShaderStage.FRAGMENT,
+        texture: { sampleType: "float", viewDimension: "2d" },
+    });
+    return device.createBindGroupLayout({
+        entries: [
+            {
+                binding: 0,
+                visibility: GPUShaderStage.FRAGMENT,
+                buffer: { type: "uniform" },
+            },
+            textureEntry(1),
+            textureEntry(2),
+            textureEntry(3),
+            textureEntry(4),
+            textureEntry(5),
+            {
+                binding: 6,
+                visibility: GPUShaderStage.FRAGMENT,
+                sampler: { type: "filtering" },
+            },
+        ],
+    });
+}

package/src/graphics/rendering/visible-material/create-color-bind-group.ts

@@ -0,0 +1,40 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { createBindGroupLayout } from "./create-bind-group-layout.js";
+import type { ColorMaterialOptions } from "./color-material-options.js";
+import { createColorMaterial } from "../../scene/model/gltf/create-color-material.js";
+import { createFallbackTextures } from "../../scene/model/gltf/decode-images.js";
+import type { FallbackViews } from "../../scene/model/gltf/build-material-bind-group.js";
+
+interface DeviceCache {
+    layout: GPUBindGroupLayout;
+    sampler: GPUSampler;
+    fallback: FallbackViews;
+}
+
+const cacheByDevice = new WeakMap<GPUDevice, DeviceCache>();
+
+/**
+ * Builds a PBR material bind group from a flat color spec. The layout,
+ * sampler, and fallback textures are cached per-device, so calling this
+ * once per sphere/cube is cheap.
+ *
+ * The returned bind group is layout-compatible with the standard PBR
+ * pipeline (same layout structure as glTF-loaded materials).
+ */
+export function createColorBindGroup(
+    device: GPUDevice,
+    options: ColorMaterialOptions,
+): GPUBindGroup {
+    let cache = cacheByDevice.get(device);
+    if (!cache) {
+        cache = {
+            layout:   createBindGroupLayout(device),
+            sampler:  device.createSampler({ magFilter: "linear", minFilter: "linear", mipmapFilter: "linear" }),
+            fallback: createFallbackTextures(device),
+        };
+        cacheByDevice.set(device, cache);
+    }
+    return createColorMaterial(device, cache.layout, cache.sampler, cache.fallback, options);
+}
+

package/src/graphics/rendering/visible-material/public.ts

@@ -0,0 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export * from "./schema.js";
+export { createBindGroupLayout } from "./create-bind-group-layout.js";
+export { createColorBindGroup } from "./create-color-bind-group.js";
+export type { ColorMaterialOptions } from "./color-material-options.js";

package/src/graphics/rendering/visible-material/schema.ts

@@ -0,0 +1,25 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { F32, Vec3, Vec4 } from "@adobe/data/math";
+import { Schema } from "@adobe/data/schema";
+
+export const schema = {
+    type: "object",
+    properties: {
+        baseColorFactor: Vec4.schema,
+        emissiveFactor: Vec3.schema,
+        metallicFactor: F32.schema,
+        roughnessFactor: F32.schema,
+        normalScale: F32.schema,
+        occlusionStrength: F32.schema,
+    },
+    required: [
+        "baseColorFactor",
+        "emissiveFactor",
+        "metallicFactor",
+        "roughnessFactor",
+        "normalScale",
+        "occlusionStrength",
+    ],
+    additionalProperties: false,
+} as const satisfies Schema;

package/src/graphics/rendering/visible-material/visible-material.ts

@@ -0,0 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Schema } from "@adobe/data/schema";
+import { schema } from "./schema.js";
+
+export type VisibleMaterial = Schema.ToType<typeof schema>;
+
+export * as VisibleMaterial from "./public.js";

package/src/graphics/scene/light/light-plugin.ts

@@ -0,0 +1,37 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+import { Vec3 } from "@adobe/data/math";
+import type { Light } from "./light.js";
+
+/**
+ * Authored lighting state — a directional light plus optional image-based
+ * lighting from an HDR environment.
+ *
+ * The `sceneUniforms` system packs these into the GPU uniform buffer the
+ * renderers consume; the `iblInitSystem` fetches and bakes the IBL textures
+ * from `light.environmentUrl`.
+ */
+export const light = Database.Plugin.create({
+    resources: {
+        light: {
+            default: {
+                direction:       Vec3.normalize([-1, -3, -10]),
+                color:           [1.0, 1.0, 1.0],
+                ambientStrength: 0.5,
+                environmentUrl:  null,
+            } satisfies Light as Light,
+        },
+    },
+    transactions: {
+        setLight(t, args: Partial<Light>) {
+            const cur = t.resources.light;
+            t.resources.light = {
+                direction:       args.direction !== undefined ? Vec3.normalize(args.direction) : cur.direction,
+                color:           args.color           ?? cur.color,
+                ambientStrength: args.ambientStrength ?? cur.ambientStrength,
+                environmentUrl:  args.environmentUrl  !== undefined ? args.environmentUrl : cur.environmentUrl,
+            };
+        },
+    },
+});

package/src/graphics/scene/light/light.ts

@@ -0,0 +1,18 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Vec3 } from "@adobe/data/math";
+
+/**
+ * Lighting state — one directional light plus optional image-based lighting
+ * from an HDR environment map. Setting `environmentUrl` triggers the IBL
+ * bake; it's the only field consumed for setup rather than as direct shader
+ * input.
+ */
+export interface Light {
+    direction: Vec3;
+    color: Vec3;
+    ambientStrength: number;
+    environmentUrl: string | null;
+}
+
+export * as Light from "./public.js";

package/src/graphics/scene/light/public.ts

@@ -0,0 +1 @@
+export { light as plugin } from "./light-plugin.js";

package/src/graphics/scene/model/geometry/geometry.ts

@@ -0,0 +1,12 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/**
+ * One row of the `Geometry` archetype — an asset identified by URL. The
+ * model loader fetches the URL, then writes derived state (`_bounds`,
+ * primitive entities, animation clips) onto the same row.
+ */
+export interface Geometry {
+    modelUrl: string;
+}
+
+export * as Geometry from "./public.js";

package/src/graphics/scene/model/geometry/public.ts

@@ -0,0 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+// Reserved for future Geometry helpers (e.g. bounds queries).
+export {};

package/src/graphics/scene/model/gltf/accessor-view.ts

@@ -0,0 +1,53 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import {
+    ACCESSOR_TYPE_COMPONENTS,
+    COMPONENT_TYPE,
+    type GltfAccessor,
+    type GltfAsset,
+} from "./gltf-schema.js";
+
+/**
+ * Returns a typed-array view over the buffer slice referenced by an accessor.
+ * Assumes tightly packed data (no byteStride). For interleaved attributes a
+ * different reader would be needed — glTF primitives commonly use separate buffer
+ * views per attribute so this is sufficient for the standard case.
+ */
+export function readAccessor(
+    gltf: GltfAsset,
+    bin: ArrayBuffer,
+    accessorIndex: number,
+): Float32Array | Uint16Array | Uint32Array | Uint8Array {
+    const accessor = gltf.accessors?.[accessorIndex];
+    if (!accessor) throw new Error(`Accessor ${accessorIndex} not found`);
+    const bv = gltf.bufferViews?.[accessor.bufferView ?? -1];
+    if (!bv) throw new Error(`BufferView for accessor ${accessorIndex} not found`);
+
+    const componentCount = ACCESSOR_TYPE_COMPONENTS[accessor.type];
+    const totalElements = accessor.count * componentCount;
+    const offset = (bv.byteOffset ?? 0) + (accessor.byteOffset ?? 0);
+
+    switch (accessor.componentType) {
+        case COMPONENT_TYPE.FLOAT:
+            return new Float32Array(bin, offset, totalElements);
+        case COMPONENT_TYPE.UNSIGNED_SHORT:
+            return new Uint16Array(bin, offset, totalElements);
+        case COMPONENT_TYPE.UNSIGNED_INT:
+            return new Uint32Array(bin, offset, totalElements);
+        case COMPONENT_TYPE.UNSIGNED_BYTE:
+            return new Uint8Array(bin, offset, totalElements);
+        default:
+            throw new Error(`Unsupported componentType ${accessor.componentType}`);
+    }
+}
+
+export function readImageBytes(gltf: GltfAsset, bin: ArrayBuffer, imageIndex: number): Uint8Array {
+    const image = gltf.images?.[imageIndex];
+    if (!image) throw new Error(`Image ${imageIndex} not found`);
+    if (image.bufferView === undefined) {
+        throw new Error(`Image ${imageIndex} has no bufferView (external URIs not supported)`);
+    }
+    const bv = gltf.bufferViews?.[image.bufferView];
+    if (!bv) throw new Error(`BufferView for image ${imageIndex} not found`);
+    return new Uint8Array(bin, bv.byteOffset ?? 0, bv.byteLength);
+}