@zephyr3d/scene 0.9.26 → 0.10.0

package/dist/render/primitive_readback.js

@@ -0,0 +1,209 @@
+import { PBPrimitiveType } from '@zephyr3d/device';
+
+function scalarByteSize(type) {
+    switch(type){
+        case PBPrimitiveType.I16:
+        case PBPrimitiveType.I16_NORM:
+        case PBPrimitiveType.U16:
+        case PBPrimitiveType.U16_NORM:
+        case PBPrimitiveType.F16:
+            return 2;
+        case PBPrimitiveType.I32:
+        case PBPrimitiveType.I32_NORM:
+        case PBPrimitiveType.U32:
+        case PBPrimitiveType.U32_NORM:
+        case PBPrimitiveType.F32:
+            return 4;
+        default:
+            return 1;
+    }
+}
+function readScalar(view, byteOffset, scalarType, normalized) {
+    switch(scalarType){
+        case PBPrimitiveType.I8:
+        case PBPrimitiveType.I8_NORM:
+            {
+                const value = view.getInt8(byteOffset);
+                return normalized ? Math.max(-1, value / 127) : value;
+            }
+        case PBPrimitiveType.U8:
+        case PBPrimitiveType.U8_NORM:
+            {
+                const value = view.getUint8(byteOffset);
+                return normalized ? value / 255 : value;
+            }
+        case PBPrimitiveType.I16:
+        case PBPrimitiveType.I16_NORM:
+            {
+                const value = view.getInt16(byteOffset, true);
+                return normalized ? Math.max(-1, value / 32767) : value;
+            }
+        case PBPrimitiveType.U16:
+        case PBPrimitiveType.U16_NORM:
+            {
+                const value = view.getUint16(byteOffset, true);
+                return normalized ? value / 65535 : value;
+            }
+        case PBPrimitiveType.I32:
+        case PBPrimitiveType.I32_NORM:
+            {
+                const value = view.getInt32(byteOffset, true);
+                return normalized ? Math.max(-1, value / 2147483647) : value;
+            }
+        case PBPrimitiveType.U32:
+        case PBPrimitiveType.U32_NORM:
+            {
+                const value = view.getUint32(byteOffset, true);
+                return normalized ? value / 4294967295 : value;
+            }
+        case PBPrimitiveType.F32:
+            return view.getFloat32(byteOffset, true);
+        default:
+            return 0;
+    }
+}
+/**
+ * Reads a vertex attribute of a primitive back from the GPU, as tightly packed
+ * floats: `componentCount` per vertex, for every vertex in the vertex buffer.
+ *
+ * @remarks
+ * Handles interleaved buffers and integer formats, normalized or not. Half
+ * float attributes are not supported and throw.
+ *
+ * @returns The data, or null if the primitive has no such attribute or it has
+ *   fewer than `componentCount` components.
+ *
+ * @public
+ */ async function readPrimitiveAttribute(primitive, semantic, componentCount) {
+    const info = primitive.getVertexBufferInfo(semantic);
+    if (!info || !info.type.isPrimitiveType() || info.type.cols < componentCount) {
+        return null;
+    }
+    const vertexCount = primitive.getNumVertices();
+    if (vertexCount <= 0) {
+        return null;
+    }
+    const bytes = await info.buffer.getBufferSubData();
+    const result = new Float32Array(vertexCount * componentCount);
+    const scalarType = info.type.scalarType;
+    const normalized = info.type.normalized;
+    const componentByteSize = scalarByteSize(scalarType);
+    const baseByteOffset = info.drawOffset + info.offset;
+    if (scalarType === PBPrimitiveType.F32 && !normalized && baseByteOffset % 4 === 0 && info.stride % 4 === 0) {
+        const raw = new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 2);
+        const stride = info.stride >> 2;
+        const srcOffset = baseByteOffset >> 2;
+        for(let i = 0; i < vertexCount; i++){
+            const src = srcOffset + i * stride;
+            const dst = i * componentCount;
+            for(let c = 0; c < componentCount; c++){
+                result[dst + c] = raw[src + c];
+            }
+        }
+        return result;
+    }
+    if (scalarType === PBPrimitiveType.F16) {
+        throw new Error(`Unsupported ${semantic} attribute format: half float`);
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    for(let i = 0; i < vertexCount; i++){
+        const src = baseByteOffset + i * info.stride;
+        const dst = i * componentCount;
+        for(let c = 0; c < componentCount; c++){
+            result[dst + c] = readScalar(view, src + c * componentByteSize, scalarType, normalized);
+        }
+    }
+    return result;
+}
+/**
+ * Reads a range of a triangle-list primitive's indices back from the GPU, as
+ * indices into its whole vertex buffer.
+ *
+ * @remarks
+ * The range defaults to what the primitive draws at full detail: its
+ * `indexStart` and `indexCount`, which for a primitive with LODs is LOD 0 only
+ * (the other levels are further ranges of the same index buffer). For a
+ * primitive without an index buffer the range is of vertices.
+ *
+ * @public
+ */ async function readPrimitiveIndices(primitive, indexStart = primitive.indexStart, indexCount = primitive.indexCount) {
+    if (primitive.primitiveType !== 'triangle-list') {
+        throw new Error(`Only triangle-list primitives can be read as triangles, not ${primitive.primitiveType}`);
+    }
+    if (indexCount <= 0 || indexCount % 3 !== 0 || indexStart < 0) {
+        throw new Error(`Invalid triangle range: start ${indexStart}, count ${indexCount}`);
+    }
+    const indexBuffer = primitive.getIndexBuffer();
+    if (!indexBuffer) {
+        if (indexStart + indexCount > primitive.getNumVertices()) {
+            throw new Error(`Invalid triangle range: start ${indexStart}, count ${indexCount}`);
+        }
+        const indices = new Uint32Array(indexCount);
+        for(let i = 0; i < indexCount; i++){
+            indices[i] = indexStart + i;
+        }
+        return indices;
+    }
+    const bytes = await indexBuffer.getBufferSubData();
+    const is16 = indexBuffer.indexType.primitiveType === PBPrimitiveType.U16;
+    const all = is16 ? new Uint16Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 1) : new Uint32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 2);
+    if (indexStart + indexCount > all.length) {
+        throw new Error(`Invalid triangle range: start ${indexStart}, count ${indexCount}`);
+    }
+    return Uint32Array.from(all.subarray(indexStart, indexStart + indexCount));
+}
+/**
+ * Reads the triangles of one level of detail of a triangle-list primitive back
+ * from the GPU, keeping only the vertices they use.
+ *
+ * @param lod - Level of detail; 0 is full detail. Levels beyond the primitive's
+ *   lowest detail use the lowest.
+ *
+ * @public
+ */ async function readPrimitiveTriangles(primitive, lod = 0) {
+    const level = Math.min(Math.max(0, Math.floor(lod)), primitive.lods.length);
+    const [indexStart, indexCount] = level === 0 ? [
+        primitive.indexStart,
+        primitive.indexCount
+    ] : [
+        primitive.lods[level - 1].indexStart,
+        primitive.lods[level - 1].indexCount
+    ];
+    const [positions, indices] = await Promise.all([
+        readPrimitiveAttribute(primitive, 'position', 3),
+        readPrimitiveIndices(primitive, indexStart, indexCount)
+    ]);
+    if (!positions) {
+        throw new Error('Primitive has no vertex positions');
+    }
+    // Other levels share the vertex buffer; keep only the vertices this one uses.
+    const vertexCount = positions.length / 3;
+    const remap = new Int32Array(vertexCount).fill(-1);
+    let used = 0;
+    for(let i = 0; i < indices.length; i++){
+        const v = indices[i];
+        if (v >= vertexCount) {
+            throw new Error(`Index ${v} out of range of ${vertexCount} vertices`);
+        }
+        if (remap[v] < 0) {
+            remap[v] = used++;
+        }
+        indices[i] = remap[v];
+    }
+    const compact = new Float32Array(used * 3);
+    for(let v = 0; v < vertexCount; v++){
+        const dst = remap[v];
+        if (dst >= 0) {
+            compact[dst * 3] = positions[v * 3];
+            compact[dst * 3 + 1] = positions[v * 3 + 1];
+            compact[dst * 3 + 2] = positions[v * 3 + 2];
+        }
+    }
+    return {
+        positions: compact,
+        indices
+    };
+}
+
+export { readPrimitiveAttribute, readPrimitiveIndices, readPrimitiveTriangles };
+//# sourceMappingURL=primitive_readback.js.map

package/dist/render/primitive_readback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitive_readback.js","sources":["../../src/render/primitive_readback.ts"],"sourcesContent":["import { PBPrimitiveType } from '@zephyr3d/device';\r\nimport type { Primitive } from './primitive';\r\n\r\n/**\r\n * Triangles read back from a primitive, with only the vertices they use.\r\n *\r\n * @public\r\n */\r\nexport interface PrimitiveTriangles {\r\n  /** Vertex positions in the primitive's local space, xyz per vertex. */\r\n  positions: Float32Array<ArrayBuffer>;\r\n  /** Three indices into `positions` per triangle. */\r\n  indices: Uint32Array<ArrayBuffer>;\r\n}\r\n\r\nfunction scalarByteSize(type: PBPrimitiveType) {\r\n  switch (type) {\r\n    case PBPrimitiveType.I16:\r\n    case PBPrimitiveType.I16_NORM:\r\n    case PBPrimitiveType.U16:\r\n    case PBPrimitiveType.U16_NORM:\r\n    case PBPrimitiveType.F16:\r\n      return 2;\r\n    case PBPrimitiveType.I32:\r\n    case PBPrimitiveType.I32_NORM:\r\n    case PBPrimitiveType.U32:\r\n    case PBPrimitiveType.U32_NORM:\r\n    case PBPrimitiveType.F32:\r\n      return 4;\r\n    default:\r\n      return 1;\r\n  }\r\n}\r\n\r\nfunction readScalar(view: DataView, byteOffset: number, scalarType: PBPrimitiveType, normalized: boolean) {\r\n  switch (scalarType) {\r\n    case PBPrimitiveType.I8:\r\n    case PBPrimitiveType.I8_NORM: {\r\n      const value = view.getInt8(byteOffset);\r\n      return normalized ? Math.max(-1, value / 127) : value;\r\n    }\r\n    case PBPrimitiveType.U8:\r\n    case PBPrimitiveType.U8_NORM: {\r\n      const value = view.getUint8(byteOffset);\r\n      return normalized ? value / 255 : value;\r\n    }\r\n    case PBPrimitiveType.I16:\r\n    case PBPrimitiveType.I16_NORM: {\r\n      const value = view.getInt16(byteOffset, true);\r\n      return normalized ? Math.max(-1, value / 32767) : value;\r\n    }\r\n    case PBPrimitiveType.U16:\r\n    case PBPrimitiveType.U16_NORM: {\r\n      const value = view.getUint16(byteOffset, true);\r\n      return normalized ? value / 65535 : value;\r\n    }\r\n    case PBPrimitiveType.I32:\r\n    case PBPrimitiveType.I32_NORM: {\r\n      const value = view.getInt32(byteOffset, true);\r\n      return normalized ? Math.max(-1, value / 2147483647) : value;\r\n    }\r\n    case PBPrimitiveType.U32:\r\n    case PBPrimitiveType.U32_NORM: {\r\n      const value = view.getUint32(byteOffset, true);\r\n      return normalized ? value / 4294967295 : value;\r\n    }\r\n    case PBPrimitiveType.F32:\r\n      return view.getFloat32(byteOffset, true);\r\n    default:\r\n      return 0;\r\n  }\r\n}\r\n\r\n/**\r\n * Reads a vertex attribute of a primitive back from the GPU, as tightly packed\r\n * floats: `componentCount` per vertex, for every vertex in the vertex buffer.\r\n *\r\n * @remarks\r\n * Handles interleaved buffers and integer formats, normalized or not. Half\r\n * float attributes are not supported and throw.\r\n *\r\n * @returns The data, or null if the primitive has no such attribute or it has\r\n *   fewer than `componentCount` components.\r\n *\r\n * @public\r\n */\r\nexport async function readPrimitiveAttribute(\r\n  primitive: Primitive,\r\n  semantic: 'position' | 'normal' | 'blendIndices' | 'blendWeights',\r\n  componentCount: number\r\n): Promise<Float32Array<ArrayBuffer> | null> {\r\n  const info = primitive.getVertexBufferInfo(semantic);\r\n  if (!info || !info.type.isPrimitiveType() || info.type.cols < componentCount) {\r\n    return null;\r\n  }\r\n  const vertexCount = primitive.getNumVertices();\r\n  if (vertexCount <= 0) {\r\n    return null;\r\n  }\r\n  const bytes = await info.buffer.getBufferSubData();\r\n  const result = new Float32Array(vertexCount * componentCount);\r\n  const scalarType = info.type.scalarType;\r\n  const normalized = info.type.normalized;\r\n  const componentByteSize = scalarByteSize(scalarType);\r\n  const baseByteOffset = info.drawOffset + info.offset;\r\n  if (\r\n    scalarType === PBPrimitiveType.F32 &&\r\n    !normalized &&\r\n    baseByteOffset % 4 === 0 &&\r\n    info.stride % 4 === 0\r\n  ) {\r\n    const raw = new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 2);\r\n    const stride = info.stride >> 2;\r\n    const srcOffset = baseByteOffset >> 2;\r\n    for (let i = 0; i < vertexCount; i++) {\r\n      const src = srcOffset + i * stride;\r\n      const dst = i * componentCount;\r\n      for (let c = 0; c < componentCount; c++) {\r\n        result[dst + c] = raw[src + c];\r\n      }\r\n    }\r\n    return result;\r\n  }\r\n  if (scalarType === PBPrimitiveType.F16) {\r\n    throw new Error(`Unsupported ${semantic} attribute format: half float`);\r\n  }\r\n  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\r\n  for (let i = 0; i < vertexCount; i++) {\r\n    const src = baseByteOffset + i * info.stride;\r\n    const dst = i * componentCount;\r\n    for (let c = 0; c < componentCount; c++) {\r\n      result[dst + c] = readScalar(view, src + c * componentByteSize, scalarType, normalized);\r\n    }\r\n  }\r\n  return result;\r\n}\r\n\r\n/**\r\n * Reads a range of a triangle-list primitive's indices back from the GPU, as\r\n * indices into its whole vertex buffer.\r\n *\r\n * @remarks\r\n * The range defaults to what the primitive draws at full detail: its\r\n * `indexStart` and `indexCount`, which for a primitive with LODs is LOD 0 only\r\n * (the other levels are further ranges of the same index buffer). For a\r\n * primitive without an index buffer the range is of vertices.\r\n *\r\n * @public\r\n */\r\nexport async function readPrimitiveIndices(\r\n  primitive: Primitive,\r\n  indexStart = primitive.indexStart,\r\n  indexCount = primitive.indexCount\r\n): Promise<Uint32Array<ArrayBuffer>> {\r\n  if (primitive.primitiveType !== 'triangle-list') {\r\n    throw new Error(`Only triangle-list primitives can be read as triangles, not ${primitive.primitiveType}`);\r\n  }\r\n  if (indexCount <= 0 || indexCount % 3 !== 0 || indexStart < 0) {\r\n    throw new Error(`Invalid triangle range: start ${indexStart}, count ${indexCount}`);\r\n  }\r\n  const indexBuffer = primitive.getIndexBuffer();\r\n  if (!indexBuffer) {\r\n    if (indexStart + indexCount > primitive.getNumVertices()) {\r\n      throw new Error(`Invalid triangle range: start ${indexStart}, count ${indexCount}`);\r\n    }\r\n    const indices = new Uint32Array(indexCount);\r\n    for (let i = 0; i < indexCount; i++) {\r\n      indices[i] = indexStart + i;\r\n    }\r\n    return indices;\r\n  }\r\n  const bytes = await indexBuffer.getBufferSubData();\r\n  const is16 = indexBuffer.indexType.primitiveType === PBPrimitiveType.U16;\r\n  const all = is16\r\n    ? new Uint16Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 1)\r\n    : new Uint32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 2);\r\n  if (indexStart + indexCount > all.length) {\r\n    throw new Error(`Invalid triangle range: start ${indexStart}, count ${indexCount}`);\r\n  }\r\n  return Uint32Array.from(all.subarray(indexStart, indexStart + indexCount));\r\n}\r\n\r\n/**\r\n * Reads the triangles of one level of detail of a triangle-list primitive back\r\n * from the GPU, keeping only the vertices they use.\r\n *\r\n * @param lod - Level of detail; 0 is full detail. Levels beyond the primitive's\r\n *   lowest detail use the lowest.\r\n *\r\n * @public\r\n */\r\nexport async function readPrimitiveTriangles(primitive: Primitive, lod = 0): Promise<PrimitiveTriangles> {\r\n  const level = Math.min(Math.max(0, Math.floor(lod)), primitive.lods.length);\r\n  const [indexStart, indexCount] =\r\n    level === 0\r\n      ? [primitive.indexStart, primitive.indexCount]\r\n      : [primitive.lods[level - 1].indexStart, primitive.lods[level - 1].indexCount];\r\n  const [positions, indices] = await Promise.all([\r\n    readPrimitiveAttribute(primitive, 'position', 3),\r\n    readPrimitiveIndices(primitive, indexStart, indexCount)\r\n  ]);\r\n  if (!positions) {\r\n    throw new Error('Primitive has no vertex positions');\r\n  }\r\n  // Other levels share the vertex buffer; keep only the vertices this one uses.\r\n  const vertexCount = positions.length / 3;\r\n  const remap = new Int32Array(vertexCount).fill(-1);\r\n  let used = 0;\r\n  for (let i = 0; i < indices.length; i++) {\r\n    const v = indices[i];\r\n    if (v >= vertexCount) {\r\n      throw new Error(`Index ${v} out of range of ${vertexCount} vertices`);\r\n    }\r\n    if (remap[v] < 0) {\r\n      remap[v] = used++;\r\n    }\r\n    indices[i] = remap[v];\r\n  }\r\n  const compact = new Float32Array(used * 3);\r\n  for (let v = 0; v < vertexCount; v++) {\r\n    const dst = remap[v];\r\n    if (dst >= 0) {\r\n      compact[dst * 3] = positions[v * 3];\r\n      compact[dst * 3 + 1] = positions[v * 3 + 1];\r\n      compact[dst * 3 + 2] = positions[v * 3 + 2];\r\n    }\r\n  }\r\n  return { positions: compact, indices };\r\n}\r\n"],"names":["scalarByteSize","type","PBPrimitiveType","I16","I16_NORM","U16","U16_NORM","F16","I32","I32_NORM","U32","U32_NORM","F32","readScalar","view","byteOffset","scalarType","normalized","I8","I8_NORM","value","getInt8","Math","max","U8","U8_NORM","getUint8","getInt16","getUint16","getInt32","getUint32","getFloat32","readPrimitiveAttribute","primitive","semantic","componentCount","info","getVertexBufferInfo","isPrimitiveType","cols","vertexCount","getNumVertices","bytes","buffer","getBufferSubData","result","Float32Array","componentByteSize","baseByteOffset","drawOffset","offset","stride","raw","byteLength","srcOffset","i","src","dst","c","Error","DataView","readPrimitiveIndices","indexStart","indexCount","primitiveType","indexBuffer","getIndexBuffer","indices","Uint32Array","is16","indexType","all","Uint16Array","length","from","subarray","readPrimitiveTriangles","lod","level","min","floor","lods","positions","Promise","remap","Int32Array","fill","used","v","compact"],"mappings":"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"}

package/dist/render/render_queue.js

@@ -5,13 +5,14 @@ import { ShaderHelper } from '../material/shader/helper.js';
 import '../material/lambert.js';
 import '../material/blinn.js';
 import '../material/unlit.js';
+import '../material/meshmaterial.js';
 import '../material/particle.js';
 import '../material/subsurfaceprofile.js';
-import '../material/skin.js';
+import '../material/sssprofile.js';
+import '../material/sss.js';
 import '../material/eye.js';
 import { RenderBundleWrapper } from './renderbundle_wrapper.js';
 import { getDevice } from '../app/api.js';
-import '../material/meshmaterial.js';
 import '../material/hair.js';
 import '../material/hairstrand.js';
 import '../material/grassmaterial.js';
@@ -23,6 +24,7 @@ import '../material/pbrblueprint.js';
 import '../material/sprite.js';
 import '../material/sprite_std.js';
 import '../utility/blueprint/material/texture.js';
+import { InstanceCuller } from './instance_culling.js';
 
 const maxBufferSizeInFloats = 65536 / 4;
 /**
@@ -100,18 +102,34 @@ const tmpDrawablePos = new Vector3();
     /** @internal */ _sunLight;
     /** @internal */ _primaryDirectionalLight;
     /** @internal */ _primaryTransmissionLight;
+    /**
+   * Visible water surfaces, in visit order.
+   *
+   * Collected separately from the item lists so passes that run before the light
+   * pass - the caustics pass, which has to know where the water plane is before
+   * anything shades under it - can find them without walking every draw item.
+   * @internal
+   */ _waterList;
     /** @internal */ _bindGroupAllocator;
     /** @internal */ _ref;
     /** @internal */ _instanceInfo;
     /** @internal */ _needSceneColor;
     _needSceneDepth;
+    _needHiZNearest;
     _needSceneColorWithDepth;
     /** @internal */ _drawTransparent;
     /** @internal */ _objectColorMaps;
+    /** @internal */ _cullCamera;
+    /** @internal */ _lodCamera;
+    /** @internal Culls the instances of the batches on the GPU, see InstanceCuller */ _instanceCuller;
+    /** @internal Queues pushed into this one, which may cull their instances for its view */ _childQueues;
     /**
    * Creates an instance of a render queue
    * @param renderPass - The render pass to which the render queue belongs
-   */ constructor(renderPass, bindGroupAllocator){
+   * @param bindGroupAllocator - Allocator of instance data, default the shared one
+   * @param instanceCulling - Whether the instances of the batches are frustum culled on the GPU
+   *   for each view the queue is pushed to, where supported. For queues built once and replayed
+   */ constructor(renderPass, bindGroupAllocator, instanceCulling){
         super();
         this._bindGroupAllocator = bindGroupAllocator ?? defaultInstanceBindGroupAlloator;
         this._itemList = null;
@@ -121,6 +139,7 @@ const tmpDrawablePos = new Vector3();
         this._sunLight = null;
         this._primaryDirectionalLight = null;
         this._primaryTransmissionLight = null;
+        this._waterList = [];
         this._ref = {
             ref: this,
             valid: true
@@ -128,11 +147,56 @@ const tmpDrawablePos = new Vector3();
         this._instanceInfo = new Map();
         this._needSceneColor = false;
         this._needSceneDepth = false;
+        this._needHiZNearest = false;
         this._needSceneColorWithDepth = false;
         this._drawTransparent = false;
         this._objectColorMaps = [
             new Map()
         ];
+        this._cullCamera = null;
+        this._lodCamera = null;
+        this._instanceCuller = instanceCulling && InstanceCuller.isSupported() ? new InstanceCuller() : null;
+        this._childQueues = [];
+    }
+    /**
+   * Cull the instances of the queues pushed into this one for its view, before drawing it.
+   *
+   * @internal
+   */ cullInstances() {
+        for (const child of this._childQueues){
+            child._instanceCuller?.cull(this);
+        }
+    }
+    /**
+   * Have the bounds of a batched drawable updated for GPU instance culling.
+   *
+   * @internal
+   */ markInstanceBoundsDirty(drawable) {
+        this._instanceCuller?.markBoundsDirty(drawable);
+    }
+    /**
+   * The camera this queue was culled with, set by {@link RenderQueue.end}.
+   *
+   * Differs from the draw context camera in shadow passes, which cull from the light. Drawables
+   * that cull their own sub-parts (clipmap terrain tiles) need it to keep only what the pass
+   * can see.
+   * @internal
+   */ get cullCamera() {
+        return this._cullCamera;
+    }
+    /**
+   * The camera whose view selects the levels of detail, set by {@link RenderQueue.end}: the main
+   * camera in shadow passes, where it differs from the cull camera.
+   * @internal
+   */ get lodCamera() {
+        return this._lodCamera;
+    }
+    /**
+   * Whether the instances of the batches are culled on the GPU, which then also selects the
+   * levels of detail where the device allows
+   * @internal
+   */ get culledOnGpu() {
+        return !!this._instanceCuller;
     }
     /** The sun light */ get sunLight() {
         return this._sunLight;
@@ -168,6 +232,17 @@ const tmpDrawablePos = new Vector3();
     /** @internal */ needSceneDepth() {
         return this._needSceneDepth;
     }
+    /**
+   * Whether any drawable needs the Hi-Z pyramid's nearest-depth channel.
+   *
+   * Materials request it the way they request the scene colour and depth, which
+   * is what lets a surface that queries the scene's proximity - water foam
+   * against a shoreline or a piling - turn the second channel on without the
+   * application having to know it exists.
+   * @internal
+   */ needHiZNearest() {
+        return this._needHiZNearest;
+    }
     /** @internal */ needSceneColorWithDepth() {
         return this._needSceneColorWithDepth;
     }
@@ -187,6 +262,15 @@ const tmpDrawablePos = new Vector3();
    */ get shadowedLights() {
         return this._shadowedLightList;
     }
+    /** Visible water surfaces collected while culling. */ get waters() {
+        return this._waterList;
+    }
+    /**
+   * Record a visible water surface.
+   * @param water - The water node that passed culling.
+   */ pushWater(water) {
+        this._waterList.push(water);
+    }
     /**
    * Gets the unshadowed lights
    */ get unshadowedLights() {
@@ -236,6 +320,10 @@ const tmpDrawablePos = new Vector3();
    * Push items from another render queue
    * @param queue - The render queue to be pushed
    */ pushRenderQueue(queue) {
+        if (queue._instanceCuller) {
+            this._childQueues.push(queue);
+        }
+        this._waterList.push(...queue._waterList);
         const newItemLists = queue._itemList;
         if (!newItemLists) {
             return;
@@ -253,6 +341,7 @@ const tmpDrawablePos = new Vector3();
         this._itemList.transmission_trans.unlit.push(...newItemLists.transmission_trans.unlit);
         this._needSceneColor ||= queue._needSceneColor;
         this._needSceneDepth ||= queue._needSceneDepth;
+        this._needHiZNearest ||= queue._needHiZNearest;
         this._needSceneColorWithDepth ||= queue._needSceneColorWithDepth;
         this._drawTransparent ||= queue._drawTransparent;
         this._sunLight ||= queue._sunLight;
@@ -268,7 +357,8 @@ const tmpDrawablePos = new Vector3();
    * Push an item to the render queue
    * @param camera - The camera for drawing the item
    * @param drawable - The object to be drawn
-   */ push(camera, drawable) {
+   * @param lod - Level of detail to draw the drawable's primitive at, default 0
+   */ push(camera, drawable, lod = 0) {
         if (drawable) {
             drawable.pushRenderQueueRef(this._ref);
             if (!this._itemList) {
@@ -281,19 +371,30 @@ const tmpDrawablePos = new Vector3();
             const transmission = !!drawable.needSceneColor() || needDepth;
             this._needSceneColor ||= transmission;
             this._needSceneDepth ||= drawable.needSceneDepth();
+            this._needHiZNearest ||= !!drawable.needHiZNearest?.();
             this._needSceneColorWithDepth ||= transmission && needDepth;
             this._drawTransparent ||= trans;
             if (camera.getPickResultResolveFunc()) {
                 drawable.getMaterial().objectColor = drawable.getObjectColor();
                 this._objectColorMaps[0].set(drawable.getDrawableId(), drawable);
             }
-            if (drawable.isBatchable()) {
-                const instanceList = trans ? transmission ? unlit ? this._itemList.transmission_trans.unlit[0].instanceList : this._itemList.transmission_trans.lit[0].instanceList : unlit ? this._itemList.transparent.unlit[0].instanceList : this._itemList.transparent.lit[0].instanceList : transmission ? unlit ? this._itemList.transmission.unlit[0].instanceList : this._itemList.transmission.lit[0].instanceList : unlit ? this._itemList.opaque.unlit[0].instanceList : this._itemList.opaque.lit[0].instanceList;
-                const hash = drawable.getInstanceId(this._renderPass);
+            // Meshes colored by level of detail draw with another material than the one whose instance
+            // data a batch would hold
+            if (drawable.isBatchable() && !camera.lodColoration) {
+                const info = trans ? transmission ? unlit ? this._itemList.transmission_trans.unlit[0] : this._itemList.transmission_trans.lit[0] : unlit ? this._itemList.transparent.unlit[0] : this._itemList.transparent.lit[0] : transmission ? unlit ? this._itemList.transmission.unlit[0] : this._itemList.transmission.lit[0] : unlit ? this._itemList.opaque.unlit[0] : this._itemList.opaque.lit[0];
+                const instanceList = info.instanceList;
+                // Levels of detail of one primitive draw different index ranges, each its own batch,
+                // unless GPU culling selects the level of every instance of the batch
+                if (this._instanceCuller && InstanceCuller.selectsLod(drawable)) {
+                    lod = 0;
+                }
+                const id = drawable.getInstanceId(this._renderPass);
+                const hash = lod > 0 ? `${id}:lod${lod}` : id;
                 let drawableList = instanceList[hash];
                 if (!drawableList) {
                     drawableList = [];
                     instanceList[hash] = drawableList;
+                    info.instanceLods[hash] = lod;
                 }
                 drawableList.push(drawable);
             } else {
@@ -313,7 +414,8 @@ const tmpDrawablePos = new Vector3();
                 this.binaryInsert(queue, {
                     drawable,
                     sortDistance: drawable.getSortDistance(camera),
-                    instanceData: null
+                    instanceData: null,
+                    lod
                 });
                 if (material) {
                     list.materialList.add(material.coreMaterial);
@@ -322,6 +424,55 @@ const tmpDrawablePos = new Vector3();
             }
         }
     }
+    /**
+   * Give every drawable of the queue its object color and register it for GPU picking.
+   *
+   * @remarks
+   * {@link push} does this for queues culled in a frame that picks. A queue built once and kept
+   * across frames (BatchGroup) was usually built in a frame that did not, so it is done again
+   * whenever a frame picks.
+   *
+   * @internal
+   */ registerObjectColors() {
+        const map = this._objectColorMaps[0];
+        const register = (drawable)=>{
+            const material = drawable.getMaterial();
+            if (material) {
+                material.objectColor = drawable.getObjectColor();
+            }
+            map.set(drawable.getDrawableId(), drawable);
+        };
+        for (const drawable of this._instanceInfo.keys()){
+            register(drawable);
+        }
+        const itemList = this._itemList;
+        if (itemList) {
+            for (const bundle of [
+                itemList.opaque,
+                itemList.transmission,
+                itemList.transparent,
+                itemList.transmission_trans
+            ]){
+                for (const info of [
+                    ...bundle.lit,
+                    ...bundle.unlit
+                ]){
+                    if (info.renderQueue === this) {
+                        for (const list of [
+                            info.itemList,
+                            info.skinItemList,
+                            info.morphItemList,
+                            info.skinAndMorphItemList
+                        ]){
+                            for (const item of list){
+                                register(item.drawable);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
     /** @internal */ getDrawableByColor(c, map) {
         const id = (c[0] << 24) + (c[1] << 16) + (c[2] << 8) + c[3];
         map = map ?? this._objectColorMaps;
@@ -366,6 +517,9 @@ const tmpDrawablePos = new Vector3();
                             if (info.instanceRenderBundle) {
                                 info.instanceRenderBundle.dispose();
                             }
+                            if (info.skinInstanceRenderBundle) {
+                                info.skinInstanceRenderBundle.dispose();
+                            }
                         }
                     }
                 }
@@ -378,6 +532,7 @@ const tmpDrawablePos = new Vector3();
             valid: true
         };
         this._instanceInfo.clear();
+        this._childQueues.length = 0;
         this._objectColorMaps.length = 0;
         this._objectColorMaps.push(new Map());
         this._shadowedLightList = [];
@@ -385,12 +540,22 @@ const tmpDrawablePos = new Vector3();
         this._sunLight = null;
         this._primaryDirectionalLight = null;
         this._primaryTransmissionLight = null;
+        this._waterList = [];
         this._needSceneColor = false;
         this._needSceneDepth = false;
+        this._needHiZNearest = false;
         this._needSceneColorWithDepth = false;
         this._drawTransparent = false;
     }
-    /** @internal */ end(camera, createRenderBundles) {
+    /**
+   * Finish the queue after pushing its items.
+   * @param camera - The camera the queue was culled with
+   * @param createRenderBundles - Whether the batches are recorded into render bundles
+   * @param lodCamera - The camera whose view selected the levels of detail, the culling camera by default
+   * @internal
+   */ end(camera, createRenderBundles, lodCamera) {
+        this._cullCamera = camera;
+        this._lodCamera = lodCamera ?? camera;
         const frameCounter = getDevice().frameInfo.frameCounter;
         const itemList = this._itemList;
         if (!this.itemList) {
@@ -432,9 +597,10 @@ const tmpDrawablePos = new Vector3();
                                     offset: bindGroup.offset,
                                     numInstances: 0,
                                     stride
-                                }
+                                },
+                                lod: info.instanceLods[x] ?? 0
                             };
-                            this.binaryInsert(info.instanceItemList, item);
+                            this.binaryInsert(drawable.getBoneMatrices() ? info.skinInstanceItemList : info.instanceItemList, item);
                             drawable.applyInstanceOffsetAndStride(this, stride, bindGroup.offset);
                         }
                         const instanceInfo = {
@@ -453,6 +619,7 @@ const tmpDrawablePos = new Vector3();
                     }
                 }
                 info.instanceList = {};
+                info.instanceLods = {};
                 if (createRenderBundles) {
                     if (info.itemList.length > 0) {
                         info.renderBundle = new RenderBundleWrapper();
@@ -469,8 +636,22 @@ const tmpDrawablePos = new Vector3();
                     if (info.instanceItemList.length > 0) {
                         info.instanceRenderBundle = new RenderBundleWrapper();
                     }
+                    if (info.skinInstanceItemList.length > 0) {
+                        info.skinInstanceRenderBundle = new RenderBundleWrapper();
+                    }
+                }
+            }
+        }
+        if (this._instanceCuller) {
+            const items = [];
+            for (const list of lists){
+                for (const info of list){
+                    if (info.renderQueue === this) {
+                        items.push(...info.instanceItemList, ...info.skinInstanceItemList);
+                    }
                 }
             }
+            this._instanceCuller.rebuild(items, this._instanceInfo);
         }
         return this;
     }
@@ -510,6 +691,10 @@ const tmpDrawablePos = new Vector3();
         super.onDispose();
         this.reset();
         this._ref.valid = false;
+        this._cullCamera = null;
+        this._lodCamera = null;
+        this._instanceCuller?.dispose();
+        this._instanceCuller = null;
     }
     drawableDistanceToCamera(drawable, cameraPos) {
         const drawablePos = drawable.getNode().getWorldPosition(tmpDrawablePos);
@@ -522,8 +707,10 @@ const tmpDrawablePos = new Vector3();
             morphItemList: [],
             skinAndMorphItemList: [],
             instanceItemList: [],
+            skinInstanceItemList: [],
             materialList: new Set(),
             instanceList: {},
+            instanceLods: {},
             renderQueue: this
         };
     }