bplinejs 0.0.101-beta.10

package/lib/Render/BufferManager.js

@@ -0,0 +1,281 @@
+import "../Style/WriteStyleData.js";
+import DepthManager from "./DepthManager.js";
+import DevelopmentValidator from "./DevelopmentValidator.js";
+//#region src/scripts/Render/BufferManager.ts
+/**
+* 管理当前 Render 对应的 Camera、Material、Mesh 和 Geometry GPUBuffer。
+* @class
+*/
+var BufferManager = class {
+	pipeline;
+	depthManager;
+	developmentValidator;
+	_cameraSnapshot;
+	_validatedMaterials = /* @__PURE__ */ new WeakMap();
+	/**
+	* 创建缓冲管理器。
+	* @param pipeline 当前 Render 的共享管线资源
+	*/
+	constructor(pipeline) {
+		this.pipeline = pipeline;
+		this.depthManager = new DepthManager(pipeline);
+		this.developmentValidator = new DevelopmentValidator();
+	}
+	/**
+	* 创建或更新当前场景需要的 GPUBuffer。
+	* @param scene 场景对象
+	* @param camera 相机对象
+	* @param dpr 当前设备像素比
+	* @param renderMode 当前 Render 运行模式
+	* @returns 无返回值
+	*/
+	draw(scene, camera, dpr, renderMode) {
+		const device = this.pipeline.device;
+		if (device === void 0) return;
+		if (renderMode === "development") this.developmentValidator.validateCamera(camera);
+		this.drawCameraBuffers(device, camera, dpr);
+		this.drawGeometryBuffers(device, scene, renderMode);
+		this.prepareMaterials(scene, renderMode);
+		this.drawMeshBuffers(device, scene, renderMode);
+		this.depthManager.prepare(scene);
+	}
+	/**
+	* 按 materialList 检查材质，共享材质每个版本只检查一次。
+	* 材质显示数值的 GPU 存储属于 Mesh 实例数组，不在这里重复创建一份缓冲。
+	* @param scene 场景对象
+	* @param renderMode production 跳过开发检查
+	*/
+	prepareMaterials(scene, renderMode) {
+		if (renderMode !== "development") return;
+		for (const material of scene.materialList) {
+			if (this._validatedMaterials.get(material) === material.version) continue;
+			this.developmentValidator.validateMaterial(material);
+			this._validatedMaterials.set(material, material.version);
+		}
+	}
+	/**
+	* 创建并写入基础 GPUBuffer。
+	* @param device 当前 Render 对应的 WebGPU 设备
+	* @param label GPU 调试标签
+	* @param data 首次写入的缓冲数据
+	* @param usage 缓冲用途标记
+	* @returns 已写入数据的 GPUBuffer
+	*/
+	createBuffer(device, label, data, usage) {
+		const buffer = device.createBuffer({
+			label,
+			size: data.byteLength,
+			usage
+		});
+		device.queue.writeBuffer(buffer, 0, data);
+		return buffer;
+	}
+	/**
+	* 按当前 Render 自己的矩阵身份和版本快照上传相机数据。
+	* @param device WebGPU 设备
+	* @param camera 相机对象
+	* @param dpr 设备像素比
+	*/
+	drawCameraBuffers(device, camera, dpr) {
+		camera.ensureCameraMatrix();
+		const buffers = this.pipeline.buffers.cameraUniform;
+		const previous = this._cameraSnapshot;
+		const cameraChanged = previous?.camera !== camera;
+		const viewChanged = cameraChanged || previous?.view !== camera.viewMatrix || previous.viewVersion !== camera.viewMatrix.version;
+		const projectionChanged = cameraChanged || previous?.projection !== camera.orthogonalMatrix || previous.projectionVersion !== camera.orthogonalMatrix.version;
+		const parametersChanged = cameraChanged || previous?.zoom !== camera.zoom || previous.dpr !== dpr;
+		const created = buffers.length === 0;
+		if (created) buffers.push(this.createBuffer(device, "Camera View Matrix Buffer", camera.viewMatrix.GPUData, GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST), this.createBuffer(device, "Camera Orthogonal Matrix Buffer", camera.orthogonalMatrix.GPUData, GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST), this.createBuffer(device, "Render Camera Parameters Buffer", new Float32Array([
+			camera.zoom,
+			dpr,
+			0,
+			0
+		]), GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST));
+		else {
+			if (viewChanged) device.queue.writeBuffer(buffers[0], 0, camera.viewMatrix.GPUData);
+			if (projectionChanged) device.queue.writeBuffer(buffers[1], 0, camera.orthogonalMatrix.GPUData);
+			if (parametersChanged) device.queue.writeBuffer(buffers[2], 0, new Float32Array([
+				camera.zoom,
+				dpr,
+				0,
+				0
+			]));
+		}
+		if (created || viewChanged || projectionChanged || parametersChanged) this._cameraSnapshot = {
+			camera,
+			view: camera.viewMatrix,
+			viewVersion: camera.viewMatrix.version,
+			projection: camera.orthogonalMatrix,
+			projectionVersion: camera.orthogonalMatrix.version,
+			zoom: camera.zoom,
+			dpr
+		};
+	}
+	/**
+	* 创建或更新每个 Mesh 的连续矩阵与样式 Storage 数组，分别对比版本。
+	* @param device 当前 WebGPU 设备
+	* @param scene 场景对象
+	* @param renderMode 当前 Render 运行模式
+	* @returns 无返回值
+	*/
+	drawMeshBuffers(device, scene, renderMode) {
+		for (const mesh of scene.drawList) {
+			if (renderMode === "development" && (mesh.geometryPending || mesh.materialPending || !this.pipeline.buffers.meshStyle.has(mesh.id))) this.developmentValidator.validateMesh(mesh);
+			const material = mesh.material;
+			if (material === void 0) continue;
+			mesh.updateInstanceData();
+			if (mesh.count === 0) continue;
+			const limit = Math.min(device.limits.maxBufferSize, device.limits.maxStorageBufferBindingSize);
+			if (mesh.matrixData.byteLength > limit || mesh.styleData.byteLength > limit) throw new RangeError("Mesh " + String(mesh.id) + " capacity exceeds this GPUDevice storage buffer limit: " + String(limit) + " bytes.");
+			const matrixBuffers = this.pipeline.buffers.meshMatrix;
+			let matrixBuffer = matrixBuffers.get(mesh.id);
+			if (matrixBuffer !== void 0 && matrixBuffer.capacity !== mesh.capacity) {
+				matrixBuffer.buffer.destroy();
+				matrixBuffers.delete(mesh.id);
+				matrixBuffer = void 0;
+			}
+			if (matrixBuffer === void 0) {
+				matrixBuffer = {
+					meshId: mesh.id,
+					capacity: mesh.capacity,
+					version: mesh.matrixVersion,
+					buffer: this.createBuffer(device, "Mesh " + String(mesh.id) + " Instance Matrices", mesh.matrixData, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST)
+				};
+				matrixBuffers.set(mesh.id, matrixBuffer);
+			} else if (matrixBuffer.version !== mesh.matrixVersion) {
+				device.queue.writeBuffer(matrixBuffer.buffer, 0, mesh.matrixData, 0, mesh.count * 12);
+				matrixBuffer.version = mesh.matrixVersion;
+			}
+			let styleBuffer = this.pipeline.buffers.meshStyle.get(mesh.id);
+			if (styleBuffer !== void 0 && styleBuffer.capacity !== mesh.capacity) {
+				styleBuffer.buffer.destroy();
+				this.pipeline.buffers.meshStyle.delete(mesh.id);
+				styleBuffer = void 0;
+			}
+			if (styleBuffer === void 0) this.pipeline.buffers.meshStyle.set(mesh.id, {
+				meshId: mesh.id,
+				materialId: material.id,
+				capacity: mesh.capacity,
+				version: mesh.styleVersion,
+				buffer: this.createBuffer(device, "Mesh " + String(mesh.id) + " Instance Styles", mesh.styleData, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST)
+			});
+			else {
+				styleBuffer.materialId = material.id;
+				if (styleBuffer.version !== mesh.styleVersion) {
+					device.queue.writeBuffer(styleBuffer.buffer, 0, mesh.styleData, 0, mesh.count * 44);
+					styleBuffer.version = mesh.styleVersion;
+				}
+			}
+		}
+	}
+	/**
+	* 为去重后的 Geometry 创建顶点、二维轮廓法线、UV、索引和参数缓冲。
+	* @param device 当前 WebGPU 设备
+	* @param scene 场景对象
+	* @param renderMode 当前 Render 运行模式
+	* @returns 无返回值
+	*/
+	drawGeometryBuffers(device, scene, renderMode) {
+		for (const geometry of scene.geometryList) {
+			geometry.ensureGeometry();
+			const cachedGeometry = this.pipeline.buffers.geometry.get(geometry.id);
+			if (cachedGeometry?.version === geometry.version) continue;
+			if (renderMode === "development") this.developmentValidator.validateGeometry(geometry);
+			if (cachedGeometry !== void 0) {
+				this.destroyGeometryBuffer(cachedGeometry);
+				this.pipeline.buffers.geometry.delete(geometry.id);
+			}
+			const geometryData = geometry.geometry;
+			const normalData = geometry.normal;
+			const uvData = geometry.uv;
+			const indexData = geometry.index;
+			const vertexType = geometry.vertexType;
+			const position = geometry.position;
+			const miterScale = geometry.miterScale;
+			const triangleBuffer = geometryData !== void 0 && normalData !== void 0 && uvData !== void 0 && indexData !== void 0 && vertexType !== void 0 && position !== void 0 && miterScale !== void 0 && indexData.length > 0 ? this.createGeometryBufferPart(device, "Geometry " + String(geometry.id) + " Merged", {
+				geometry: geometryData,
+				normal: normalData,
+				uv: uvData,
+				index: indexData,
+				vertexType,
+				position,
+				miterScale
+			}) : void 0;
+			const linePointsBuffer = geometry.linePoints !== void 0 && geometry.linePoints.index.length > 0 ? this.createGeometryBufferPart(device, "Geometry " + String(geometry.id) + " Line Points", geometry.linePoints) : void 0;
+			if (triangleBuffer === void 0 && linePointsBuffer === void 0) continue;
+			const uniformBuffer = this.createBuffer(device, "Geometry " + String(geometry.id) + " Parameters Buffer", geometry.uniformData, GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST);
+			this.pipeline.buffers.geometry.set(geometry.id, {
+				geometryId: geometry.id,
+				version: geometry.version,
+				uniform: uniformBuffer,
+				geometry: triangleBuffer,
+				linePoints: linePointsBuffer
+			});
+		}
+	}
+	/**
+	* 创建单种几何绘制模式的顶点、二维轮廓法线、UV 和索引缓冲。
+	* @param device 当前 WebGPU 设备
+	* @param label GPU 调试标签前缀
+	* @param data CPU 几何数据
+	* @returns 已创建的几何缓冲分区
+	*/
+	createGeometryBufferPart(device, label, data) {
+		const vertexData = new Float32Array(data.geometry);
+		const normalData = new Float32Array(data.normal);
+		const textureCoordinateData = new Float32Array(data.uv);
+		const elementData = data.index instanceof Uint32Array ? new Uint32Array(data.index) : new Uint16Array(data.index);
+		const positionData = data.position === void 0 ? void 0 : new Float32Array(data.position);
+		const miterScaleData = data.miterScale === void 0 ? void 0 : new Float32Array(data.miterScale);
+		const alignedIndexByteLength = Math.ceil(elementData.byteLength / 4) * 4;
+		const alignedIndexData = new Uint8Array(alignedIndexByteLength);
+		alignedIndexData.set(new Uint8Array(elementData.buffer));
+		return {
+			vertex: this.createBuffer(device, label + " Vertex Buffer", vertexData, GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST),
+			normal: this.createBuffer(device, label + " Normal Buffer", normalData, GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST),
+			uv: this.createBuffer(device, label + " UV Buffer", textureCoordinateData, GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST),
+			index: this.createBuffer(device, label + " Index Buffer", alignedIndexData, GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST),
+			vertexType: data.vertexType === void 0 ? void 0 : this.createBuffer(device, label + " Vertex Type Buffer", new Float32Array(data.vertexType), GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST),
+			pointsFirstIndex: this.getPointsFirstIndex(data),
+			indexFormat: data.index instanceof Uint32Array ? "uint32" : "uint16",
+			position: positionData === void 0 ? void 0 : this.createBuffer(device, label + " Point Centers Buffer", positionData, GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST),
+			miterScale: miterScaleData === void 0 ? void 0 : this.createBuffer(device, label + " Miter Scale Buffer", miterScaleData, GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST)
+		};
+	}
+	/**
+	* 获取关键点索引段起点，缓存后绘制时无需重复遍历。
+	* 原生 line-list 需要插在实体面与关键点之间时，复用同一个合并缓冲分段绘制。
+	* @param data 已按面、边框、关键点顺序合并的数据
+	* @returns 关键点索引段起点；没有关键点时等于总索引数
+	*/
+	getPointsFirstIndex(data) {
+		if (data.vertexType !== void 0) {
+			for (let index = 0; index < data.index.length; index += 1) if (data.vertexType[data.index[index]] === 1) return index;
+		}
+		return data.index.length;
+	}
+	/**
+	* 销毁一个 Geometry 缓存集合中的全部已创建缓冲。
+	* @param geometryBuffer Geometry GPU 缓存集合
+	* @returns 无返回值
+	*/
+	destroyGeometryBuffer(geometryBuffer) {
+		for (const entry of this.pipeline.buffers.meshMatrix.values()) if (entry.bindGroup?.geometry === geometryBuffer.uniform) entry.bindGroup = void 0;
+		const DestroyPart = (part) => {
+			part?.vertex.destroy();
+			part?.normal.destroy();
+			part?.uv.destroy();
+			part?.index.destroy();
+			part?.miterScale?.destroy();
+			part?.position?.destroy();
+			part?.vertexType?.destroy();
+		};
+		DestroyPart(geometryBuffer.geometry);
+		DestroyPart(geometryBuffer.linePoints);
+		geometryBuffer.uniform.destroy();
+	}
+};
+//#endregion
+export { BufferManager as default };
+
+//# sourceMappingURL=BufferManager.js.map

package/lib/Render/BufferManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BufferManager.js","names":[],"sources":["../../src/scripts/Render/BufferManager.ts"],"sourcesContent":["import { STYLE_STRIDE } from \"../Style\";\nimport type Camera from \"../Camera\";\nimport type { Mat3 } from \"bpmatrixjs/Math\";\nimport type { GeoPartDataLike } from \"../Geometry/Geo\";\nimport type Scene from \"../Scene\";\nimport type { Material2d } from \"../global-types\";\nimport DepthManager from \"./DepthManager\";\nimport DevelopmentValidator from \"./DevelopmentValidator\";\nimport type { GeometryBufferLike, GeometryBufferPartLike, PipelineLike, RenderMode } from \"./types\";\n\ninterface BufferManagerLike {\n    draw(scene: Scene, camera: Camera, dpr: number, renderMode: RenderMode): void;\n}\n\n/**\n * 管理当前 Render 对应的 Camera、Material、Mesh 和 Geometry GPUBuffer。\n * @class\n */\nclass BufferManager implements BufferManagerLike {\n    private readonly pipeline: PipelineLike;\n    private readonly depthManager: DepthManager;\n    private readonly developmentValidator: DevelopmentValidator;\n    private _cameraSnapshot: {\n        camera: Camera;\n        view: Mat3;\n        viewVersion: number;\n        projection: Mat3;\n        projectionVersion: number;\n        zoom: number;\n        dpr: number;\n    } | undefined;\n    private readonly _validatedMaterials = new WeakMap<Material2d, number>();\n\n    /**\n     * 创建缓冲管理器。\n     * @param pipeline 当前 Render 的共享管线资源\n     */\n    public constructor(pipeline: PipelineLike) {\n        this.pipeline = pipeline;\n        this.depthManager = new DepthManager(pipeline);\n        this.developmentValidator = new DevelopmentValidator();\n    }\n\n    /**\n     * 创建或更新当前场景需要的 GPUBuffer。\n     * @param scene 场景对象\n     * @param camera 相机对象\n     * @param dpr 当前设备像素比\n     * @param renderMode 当前 Render 运行模式\n     * @returns 无返回值\n     */\n    public draw(\n        scene: Scene,\n        camera: Camera,\n        dpr: number,\n        renderMode: RenderMode,\n    ): void {\n        const device: GPUDevice | undefined = this.pipeline.device;\n\n        if (device === undefined) {\n            return;\n        }\n\n        if (renderMode === \"development\") {\n            this.developmentValidator.validateCamera(camera);\n        }\n\n        this.drawCameraBuffers(device, camera, dpr);\n        this.drawGeometryBuffers(device, scene, renderMode);\n        this.prepareMaterials(scene, renderMode);\n        this.drawMeshBuffers(device, scene, renderMode);\n        this.depthManager.prepare(scene);\n    }\n\n    /**\n     * 按 materialList 检查材质，共享材质每个版本只检查一次。\n     * 材质显示数值的 GPU 存储属于 Mesh 实例数组，不在这里重复创建一份缓冲。\n     * @param scene 场景对象\n     * @param renderMode production 跳过开发检查\n     */\n    private prepareMaterials(scene: Scene, renderMode: RenderMode): void {\n        if (renderMode !== \"development\") return;\n        for (const material of scene.materialList) {\n            if (this._validatedMaterials.get(material) === material.version) continue;\n            this.developmentValidator.validateMaterial(material);\n            this._validatedMaterials.set(material, material.version);\n        }\n    }\n\n    /**\n     * 创建并写入基础 GPUBuffer。\n     * @param device 当前 Render 对应的 WebGPU 设备\n     * @param label GPU 调试标签\n     * @param data 首次写入的缓冲数据\n     * @param usage 缓冲用途标记\n     * @returns 已写入数据的 GPUBuffer\n     */\n    private createBuffer(device: GPUDevice, label: string, data: GPUAllowSharedBufferSource, usage: GPUBufferUsageFlags): GPUBuffer {\n        const buffer: GPUBuffer = device.createBuffer({\n            label,\n            size: data.byteLength,\n            usage,\n        });\n\n        device.queue.writeBuffer(buffer, 0, data);\n        return buffer;\n    }\n\n    /**\n     * 按当前 Render 自己的矩阵身份和版本快照上传相机数据。\n     * @param device WebGPU 设备\n     * @param camera 相机对象\n     * @param dpr 设备像素比\n     */\n    private drawCameraBuffers(device: GPUDevice, camera: Camera, dpr: number): void {\n        camera.ensureCameraMatrix();\n        const buffers: GPUBuffer[] = this.pipeline.buffers.cameraUniform;\n        const previous = this._cameraSnapshot;\n        const cameraChanged: boolean = previous?.camera !== camera;\n        const viewChanged: boolean = cameraChanged || previous?.view !== camera.viewMatrix\n            || previous.viewVersion !== camera.viewMatrix.version;\n        const projectionChanged: boolean = cameraChanged || previous?.projection !== camera.orthogonalMatrix\n            || previous.projectionVersion !== camera.orthogonalMatrix.version;\n        const parametersChanged: boolean = cameraChanged || previous?.zoom !== camera.zoom || previous.dpr !== dpr;\n        const created: boolean = buffers.length === 0;\n        if (created) {\n            buffers.push(\n                this.createBuffer(device, \"Camera View Matrix Buffer\", camera.viewMatrix.GPUData, GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST),\n                this.createBuffer(device, \"Camera Orthogonal Matrix Buffer\", camera.orthogonalMatrix.GPUData, GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST),\n                this.createBuffer(device, \"Render Camera Parameters Buffer\", new Float32Array([camera.zoom, dpr, 0, 0]), GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST),\n            );\n        } else {\n            if (viewChanged) device.queue.writeBuffer(buffers[0], 0, camera.viewMatrix.GPUData);\n            if (projectionChanged) device.queue.writeBuffer(buffers[1], 0, camera.orthogonalMatrix.GPUData);\n            if (parametersChanged) device.queue.writeBuffer(buffers[2], 0, new Float32Array([camera.zoom, dpr, 0, 0]));\n        }\n        if (created || viewChanged || projectionChanged || parametersChanged) {\n            this._cameraSnapshot = {\n                camera, view: camera.viewMatrix, viewVersion: camera.viewMatrix.version,\n                projection: camera.orthogonalMatrix, projectionVersion: camera.orthogonalMatrix.version,\n                zoom: camera.zoom, dpr,\n            };\n        }\n    }\n\n    /**\n     * 创建或更新每个 Mesh 的连续矩阵与样式 Storage 数组，分别对比版本。\n     * @param device 当前 WebGPU 设备\n     * @param scene 场景对象\n     * @param renderMode 当前 Render 运行模式\n     * @returns 无返回值\n     */\n    private drawMeshBuffers(device: GPUDevice, scene: Scene, renderMode: RenderMode): void {\n        for (const mesh of scene.drawList) {\n            if (renderMode === \"development\" && (mesh.geometryPending || mesh.materialPending\n                || !this.pipeline.buffers.meshStyle.has(mesh.id))) {\n                this.developmentValidator.validateMesh(mesh);\n            }\n\n            const material = mesh.material;\n            if (material === undefined) continue;\n            mesh.updateInstanceData();\n            if (mesh.count === 0) continue;\n            const limit: number = Math.min(device.limits.maxBufferSize, device.limits.maxStorageBufferBindingSize);\n            if (mesh.matrixData.byteLength > limit || mesh.styleData.byteLength > limit) {\n                throw new RangeError(\"Mesh \" + String(mesh.id) + \" capacity exceeds this GPUDevice storage buffer limit: \" + String(limit) + \" bytes.\");\n            }\n            const matrixBuffers = this.pipeline.buffers.meshMatrix;\n            let matrixBuffer = matrixBuffers.get(mesh.id);\n            if (matrixBuffer !== undefined && matrixBuffer.capacity !== mesh.capacity) {\n                matrixBuffer.buffer.destroy();\n                matrixBuffers.delete(mesh.id);\n                matrixBuffer = undefined;\n            }\n            if (matrixBuffer === undefined) {\n                matrixBuffer = {\n                    meshId: mesh.id, capacity: mesh.capacity, version: mesh.matrixVersion,\n                    buffer: this.createBuffer(device, \"Mesh \" + String(mesh.id) + \" Instance Matrices\",\n                        mesh.matrixData, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST),\n                };\n                matrixBuffers.set(mesh.id, matrixBuffer);\n            } else if (matrixBuffer.version !== mesh.matrixVersion) {\n                device.queue.writeBuffer(matrixBuffer.buffer, 0, mesh.matrixData, 0, mesh.count * 12);\n                matrixBuffer.version = mesh.matrixVersion;\n            }\n\n            let styleBuffer = this.pipeline.buffers.meshStyle.get(mesh.id);\n            if (styleBuffer !== undefined && styleBuffer.capacity !== mesh.capacity) {\n                styleBuffer.buffer.destroy();\n                this.pipeline.buffers.meshStyle.delete(mesh.id);\n                styleBuffer = undefined;\n            }\n            if (styleBuffer === undefined) {\n                this.pipeline.buffers.meshStyle.set(mesh.id, {\n                    meshId: mesh.id, materialId: material.id,\n                    capacity: mesh.capacity, version: mesh.styleVersion,\n                    buffer: this.createBuffer(device, \"Mesh \" + String(mesh.id) + \" Instance Styles\",\n                        mesh.styleData, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST),\n                });\n            } else {\n                // 即使样式内容相同，更换材质后也要维护销毁时使用的关联 ID。\n                styleBuffer.materialId = material.id;\n                if (styleBuffer.version !== mesh.styleVersion) {\n                    device.queue.writeBuffer(styleBuffer.buffer, 0, mesh.styleData, 0, mesh.count * STYLE_STRIDE);\n                    styleBuffer.version = mesh.styleVersion;\n                }\n            }\n        }\n    }\n\n    /**\n     * 为去重后的 Geometry 创建顶点、二维轮廓法线、UV、索引和参数缓冲。\n     * @param device 当前 WebGPU 设备\n     * @param scene 场景对象\n     * @param renderMode 当前 Render 运行模式\n     * @returns 无返回值\n     */\n    private drawGeometryBuffers(device: GPUDevice, scene: Scene, renderMode: RenderMode): void {\n        for (const geometry of scene.geometryList) {\n            geometry.ensureGeometry();\n\n            const cachedGeometry: GeometryBufferLike | undefined = this.pipeline.buffers.geometry.get(geometry.id);\n\n            if (cachedGeometry?.version === geometry.version) {\n                continue;\n            }\n\n            if (renderMode === \"development\") {\n                this.developmentValidator.validateGeometry(geometry);\n            }\n\n            if (cachedGeometry !== undefined) {\n                this.destroyGeometryBuffer(cachedGeometry);\n                this.pipeline.buffers.geometry.delete(geometry.id);\n            }\n\n            const geometryData = geometry.geometry;\n            const normalData = geometry.normal;\n            const uvData = geometry.uv;\n            const indexData = geometry.index;\n            const vertexType = geometry.vertexType;\n            const position = geometry.position;\n            const miterScale = geometry.miterScale;\n            const triangleBuffer = geometryData !== undefined\n                && normalData !== undefined && uvData !== undefined && indexData !== undefined\n                && vertexType !== undefined && position !== undefined && miterScale !== undefined\n                && indexData.length > 0\n                ? this.createGeometryBufferPart(\n                    device, \"Geometry \" + String(geometry.id) + \" Merged\",\n                    { geometry: geometryData, normal: normalData, uv: uvData, index: indexData, vertexType, position, miterScale },\n                )\n                : undefined;\n            const linePointsBuffer = geometry.linePoints !== undefined && geometry.linePoints.index.length > 0\n                ? this.createGeometryBufferPart(device, \"Geometry \" + String(geometry.id) + \" Line Points\", geometry.linePoints)\n                : undefined;\n            if (triangleBuffer === undefined && linePointsBuffer === undefined) {\n                continue;\n            }\n            const uniformBuffer: GPUBuffer = this.createBuffer(device, \"Geometry \" + String(geometry.id) + \" Parameters Buffer\", geometry.uniformData, GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST);\n\n            this.pipeline.buffers.geometry.set(geometry.id, {\n                geometryId: geometry.id,\n                version: geometry.version,\n                uniform: uniformBuffer,\n                geometry: triangleBuffer,\n                linePoints: linePointsBuffer,\n            });\n        }\n    }\n\n    /**\n     * 创建单种几何绘制模式的顶点、二维轮廓法线、UV 和索引缓冲。\n     * @param device 当前 WebGPU 设备\n     * @param label GPU 调试标签前缀\n     * @param data CPU 几何数据\n     * @returns 已创建的几何缓冲分区\n     */\n    private createGeometryBufferPart(device: GPUDevice, label: string, data: GeoPartDataLike): GeometryBufferPartLike {\n        const vertexData: Float32Array<ArrayBuffer> = new Float32Array(data.geometry);\n        const normalData: Float32Array<ArrayBuffer> = new Float32Array(data.normal);\n        const textureCoordinateData: Float32Array<ArrayBuffer> = new Float32Array(data.uv);\n        const elementData: Uint16Array<ArrayBuffer> | Uint32Array<ArrayBuffer> = data.index instanceof Uint32Array\n            ? new Uint32Array(data.index)\n            : new Uint16Array(data.index);\n        const positionData: Float32Array<ArrayBuffer> | undefined = data.position === undefined\n            ? undefined\n            : new Float32Array(data.position);\n        const miterScaleData: Float32Array<ArrayBuffer> | undefined = data.miterScale === undefined\n            ? undefined\n            : new Float32Array(data.miterScale);\n        const alignedIndexByteLength: number = Math.ceil(elementData.byteLength / 4) * 4;\n        const alignedIndexData: Uint8Array<ArrayBuffer> = new Uint8Array(alignedIndexByteLength);\n\n        // WebGPU 写入长度必须是 4 的倍数，末尾补位不参与 drawIndexed。\n        alignedIndexData.set(new Uint8Array(elementData.buffer));\n\n        return {\n            vertex: this.createBuffer(device, label + \" Vertex Buffer\", vertexData, GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST),\n            normal: this.createBuffer(device, label + \" Normal Buffer\", normalData, GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST),\n            uv: this.createBuffer(device, label + \" UV Buffer\", textureCoordinateData, GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST),\n            index: this.createBuffer(device, label + \" Index Buffer\", alignedIndexData, GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST),\n            vertexType: data.vertexType === undefined\n                ? undefined\n                : this.createBuffer(device, label + \" Vertex Type Buffer\", new Float32Array(data.vertexType), GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST),\n            pointsFirstIndex: this.getPointsFirstIndex(data),\n            indexFormat: data.index instanceof Uint32Array ? \"uint32\" : \"uint16\",\n            position: positionData === undefined\n                ? undefined\n                : this.createBuffer(device, label + \" Point Centers Buffer\", positionData, GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST),\n            miterScale: miterScaleData === undefined\n                ? undefined\n                : this.createBuffer(device, label + \" Miter Scale Buffer\", miterScaleData, GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST),\n        };\n    }\n\n    /**\n     * 获取关键点索引段起点，缓存后绘制时无需重复遍历。\n     * 原生 line-list 需要插在实体面与关键点之间时，复用同一个合并缓冲分段绘制。\n     * @param data 已按面、边框、关键点顺序合并的数据\n     * @returns 关键点索引段起点；没有关键点时等于总索引数\n     */\n    private getPointsFirstIndex(data: GeoPartDataLike): number {\n        if (data.vertexType !== undefined) {\n            for (let index: number = 0; index < data.index.length; index += 1) {\n                if (data.vertexType[data.index[index]] === 1) {\n                    return index;\n                }\n            }\n        }\n        return data.index.length;\n    }\n\n    /**\n     * 销毁一个 Geometry 缓存集合中的全部已创建缓冲。\n     * @param geometryBuffer Geometry GPU 缓存集合\n     * @returns 无返回值\n     */\n    private destroyGeometryBuffer(geometryBuffer: GeometryBufferLike): void {\n        for (const entry of this.pipeline.buffers.meshMatrix.values()) {\n            if (entry.bindGroup?.geometry === geometryBuffer.uniform) entry.bindGroup = undefined;\n        }\n        const DestroyPart = (part: GeometryBufferPartLike | undefined): void => {\n            part?.vertex.destroy();\n            part?.normal.destroy();\n            part?.uv.destroy();\n            part?.index.destroy();\n            part?.miterScale?.destroy();\n            part?.position?.destroy();\n            part?.vertexType?.destroy();\n        };\n\n        DestroyPart(geometryBuffer.geometry);\n        DestroyPart(geometryBuffer.linePoints);\n        geometryBuffer.uniform.destroy();\n    }\n}\n\nexport default BufferManager;\nexport type { BufferManagerLike };\n"],"mappings":"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"}

package/lib/Render/DepthManager.d.ts

@@ -0,0 +1,22 @@
+import type Scene from "../Scene";
+import type { DepthTextureLike, PipelineLike } from "./types";
+/** 深度纹理和每个 Mesh 的绘制参数均属于当前 Render，不写入共享 CPU 样式。 */
+declare class DepthManager {
+    private readonly pipeline;
+    /** @param pipeline 当前 Render 的 GPU 资源 */
+    constructor(pipeline: PipelineLike);
+    /**
+     * 按原始排序分配层级，反向提交只改变访问方向，不重新定义谁在上面。
+     * 每个 Mesh 仅上传四个 u32：全局起点、条数、是否反读、补位。
+     * @param scene 已准备 drawList 的场景
+     */
+    prepare(scene: Scene): void;
+    /**
+     * 复用与颜色附件同尺寸的深度纹理，实际像素尺寸变化才重建。
+     * @param width 画布物理像素宽度，不是 CSS 宽度
+     * @param height 画布物理像素高度
+     * @returns 深度附件，设备尚未初始化时为 undefined
+     */
+    ensureTexture(width: number, height: number): DepthTextureLike | undefined;
+}
+export default DepthManager;

package/lib/Render/DepthManager.js

@@ -0,0 +1,95 @@
+//#region src/scripts/Render/DepthManager.ts
+/** 以 24 位整数层级生成精确可表示的 f32 深度，避免相邻对象因舍入获得相同深度。 */
+var DEPTH_LEVELS = 16777216;
+/** 深度纹理和每个 Mesh 的绘制参数均属于当前 Render，不写入共享 CPU 样式。 */
+var DepthManager = class {
+	pipeline;
+	/** @param pipeline 当前 Render 的 GPU 资源 */
+	constructor(pipeline) {
+		this.pipeline = pipeline;
+	}
+	/**
+	* 按原始排序分配层级，反向提交只改变访问方向，不重新定义谁在上面。
+	* 每个 Mesh 仅上传四个 u32：全局起点、条数、是否反读、补位。
+	* @param scene 已准备 drawList 的场景
+	*/
+	prepare(scene) {
+		const device = this.pipeline.device;
+		if (device === void 0) return;
+		let total = 0;
+		for (const mesh of scene.drawList) total += mesh.count;
+		if (!Number.isSafeInteger(total) || total >= DEPTH_LEVELS) throw new RangeError("Scene exceeds 16777215 distinct depth levels.");
+		let base = 0;
+		for (const mesh of scene.drawList) {
+			const material = mesh.material;
+			const count = mesh.count;
+			if (count > 0 && material !== void 0) {
+				const reverse = Number(material.depthTest && material.depthWrite && !material.transparent);
+				let cached = this.pipeline.buffers.meshDepth.get(mesh.id);
+				if (cached === void 0) {
+					const data = new Uint32Array([
+						base,
+						count,
+						reverse,
+						0
+					]);
+					const buffer = device.createBuffer({
+						label: "Mesh " + String(mesh.id) + " Depth Parameters",
+						size: 16,
+						usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+					});
+					device.queue.writeBuffer(buffer, 0, data);
+					cached = {
+						meshId: mesh.id,
+						buffer,
+						data
+					};
+					this.pipeline.buffers.meshDepth.set(mesh.id, cached);
+				} else if (cached.data[0] !== base || cached.data[1] !== count || cached.data[2] !== reverse) {
+					cached.data.set([
+						base,
+						count,
+						reverse,
+						0
+					]);
+					device.queue.writeBuffer(cached.buffer, 0, cached.data);
+				}
+			}
+			base += count;
+		}
+	}
+	/**
+	* 复用与颜色附件同尺寸的深度纹理，实际像素尺寸变化才重建。
+	* @param width 画布物理像素宽度，不是 CSS 宽度
+	* @param height 画布物理像素高度
+	* @returns 深度附件，设备尚未初始化时为 undefined
+	*/
+	ensureTexture(width, height) {
+		const device = this.pipeline.device;
+		if (device === void 0) return void 0;
+		const cached = this.pipeline.depthTexture;
+		if (cached?.width === width && cached.height === height) return cached;
+		const texture = device.createTexture({
+			label: "Render Depth Texture",
+			size: {
+				width,
+				height
+			},
+			format: "depth32float",
+			usage: GPUTextureUsage.RENDER_ATTACHMENT
+		});
+		const resource = {
+			texture,
+			view: texture.createView(),
+			width,
+			height
+		};
+		cached?.texture.destroy();
+		this.pipeline.depthTexture = resource;
+		return resource;
+	}
+};
+//#endregion
+export { DepthManager as default };
+
+//# sourceMappingURL=DepthManager.js.map

package/lib/Render/DepthManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DepthManager.js","names":[],"sources":["../../src/scripts/Render/DepthManager.ts"],"sourcesContent":["import type Scene from \"../Scene\";\nimport type { DepthTextureLike, PipelineLike } from \"./types\";\n\n/** 以 24 位整数层级生成精确可表示的 f32 深度，避免相邻对象因舍入获得相同深度。 */\nconst DEPTH_LEVELS: number = 16777216;\n\n/** 深度纹理和每个 Mesh 的绘制参数均属于当前 Render，不写入共享 CPU 样式。 */\nclass DepthManager {\n    private readonly pipeline: PipelineLike;\n\n    /** @param pipeline 当前 Render 的 GPU 资源 */\n    public constructor(pipeline: PipelineLike) { this.pipeline = pipeline; }\n\n    /**\n     * 按原始排序分配层级，反向提交只改变访问方向，不重新定义谁在上面。\n     * 每个 Mesh 仅上传四个 u32：全局起点、条数、是否反读、补位。\n     * @param scene 已准备 drawList 的场景\n     */\n    public prepare(scene: Scene): void {\n        const device = this.pipeline.device;\n        if (device === undefined) return;\n        let total: number = 0;\n        for (const mesh of scene.drawList) total += mesh.count;\n        if (!Number.isSafeInteger(total) || total >= DEPTH_LEVELS) {\n            throw new RangeError(\"Scene exceeds 16777215 distinct depth levels.\");\n        }\n        let base: number = 0;\n        for (const mesh of scene.drawList) {\n            const material = mesh.material;\n            const count: number = mesh.count;\n            if (count > 0 && material !== undefined) {\n                const reverse: number = Number(material.depthTest && material.depthWrite && !material.transparent);\n                let cached = this.pipeline.buffers.meshDepth.get(mesh.id);\n                if (cached === undefined) {\n                    const data: Uint32Array<ArrayBuffer> = new Uint32Array([base, count, reverse, 0]);\n                    const buffer = device.createBuffer({\n                        label: \"Mesh \" + String(mesh.id) + \" Depth Parameters\", size: 16,\n                        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,\n                    });\n                    device.queue.writeBuffer(buffer, 0, data);\n                    cached = { meshId: mesh.id, buffer, data };\n                    this.pipeline.buffers.meshDepth.set(mesh.id, cached);\n                } else if (cached.data[0] !== base || cached.data[1] !== count || cached.data[2] !== reverse) {\n                    cached.data.set([base, count, reverse, 0]);\n                    device.queue.writeBuffer(cached.buffer, 0, cached.data);\n                }\n            }\n            base += count;\n        }\n    }\n\n    /**\n     * 复用与颜色附件同尺寸的深度纹理，实际像素尺寸变化才重建。\n     * @param width 画布物理像素宽度，不是 CSS 宽度\n     * @param height 画布物理像素高度\n     * @returns 深度附件，设备尚未初始化时为 undefined\n     */\n    public ensureTexture(width: number, height: number): DepthTextureLike | undefined {\n        const device = this.pipeline.device;\n        if (device === undefined) return undefined;\n        const cached = this.pipeline.depthTexture;\n        if (cached?.width === width && cached.height === height) return cached;\n        const texture = device.createTexture({\n            label: \"Render Depth Texture\", size: { width, height },\n            format: \"depth32float\", usage: GPUTextureUsage.RENDER_ATTACHMENT,\n        });\n        const resource: DepthTextureLike = { texture, view: texture.createView(), width, height };\n        cached?.texture.destroy();\n        this.pipeline.depthTexture = resource;\n        return resource;\n    }\n}\n\nexport default DepthManager;\n"],"mappings":";;AAIA,IAAM,eAAuB;;AAG7B,IAAM,eAAN,MAAmB;CACf;;CAGA,YAAmB,UAAwB;EAAE,KAAK,WAAW;CAAU;;;;;;CAOvE,QAAe,OAAoB;EAC/B,MAAM,SAAS,KAAK,SAAS;EAC7B,IAAI,WAAW,KAAA,GAAW;EAC1B,IAAI,QAAgB;EACpB,KAAK,MAAM,QAAQ,MAAM,UAAU,SAAS,KAAK;EACjD,IAAI,CAAC,OAAO,cAAc,KAAK,KAAK,SAAS,cACzC,MAAM,IAAI,WAAW,+CAA+C;EAExE,IAAI,OAAe;EACnB,KAAK,MAAM,QAAQ,MAAM,UAAU;GAC/B,MAAM,WAAW,KAAK;GACtB,MAAM,QAAgB,KAAK;GAC3B,IAAI,QAAQ,KAAK,aAAa,KAAA,GAAW;IACrC,MAAM,UAAkB,OAAO,SAAS,aAAa,SAAS,cAAc,CAAC,SAAS,WAAW;IACjG,IAAI,SAAS,KAAK,SAAS,QAAQ,UAAU,IAAI,KAAK,EAAE;IACxD,IAAI,WAAW,KAAA,GAAW;KACtB,MAAM,OAAiC,IAAI,YAAY;MAAC;MAAM;MAAO;MAAS;KAAC,CAAC;KAChF,MAAM,SAAS,OAAO,aAAa;MAC/B,OAAO,UAAU,OAAO,KAAK,EAAE,IAAI;MAAqB,MAAM;MAC9D,OAAO,eAAe,UAAU,eAAe;KACnD,CAAC;KACD,OAAO,MAAM,YAAY,QAAQ,GAAG,IAAI;KACxC,SAAS;MAAE,QAAQ,KAAK;MAAI;MAAQ;KAAK;KACzC,KAAK,SAAS,QAAQ,UAAU,IAAI,KAAK,IAAI,MAAM;IACvD,OAAO,IAAI,OAAO,KAAK,OAAO,QAAQ,OAAO,KAAK,OAAO,SAAS,OAAO,KAAK,OAAO,SAAS;KAC1F,OAAO,KAAK,IAAI;MAAC;MAAM;MAAO;MAAS;KAAC,CAAC;KACzC,OAAO,MAAM,YAAY,OAAO,QAAQ,GAAG,OAAO,IAAI;IAC1D;GACJ;GACA,QAAQ;EACZ;CACJ;;;;;;;CAQA,cAAqB,OAAe,QAA8C;EAC9E,MAAM,SAAS,KAAK,SAAS;EAC7B,IAAI,WAAW,KAAA,GAAW,OAAO,KAAA;EACjC,MAAM,SAAS,KAAK,SAAS;EAC7B,IAAI,QAAQ,UAAU,SAAS,OAAO,WAAW,QAAQ,OAAO;EAChE,MAAM,UAAU,OAAO,cAAc;GACjC,OAAO;GAAwB,MAAM;IAAE;IAAO;GAAO;GACrD,QAAQ;GAAgB,OAAO,gBAAgB;EACnD,CAAC;EACD,MAAM,WAA6B;GAAE;GAAS,MAAM,QAAQ,WAAW;GAAG;GAAO;EAAO;EACxF,QAAQ,QAAQ,QAAQ;EACxB,KAAK,SAAS,eAAe;EAC7B,OAAO;CACX;AACJ"}

package/lib/Render/DestroyManager.d.ts

@@ -0,0 +1,74 @@
+import type { GeoData } from "../Geometry";
+import type { Material2d } from "../global-types";
+import type { MeshLike } from "../Mesh";
+import type Scene from "../Scene";
+import type { TextureResource } from "../Texture/Layers";
+import type { PipelineLike } from "./types";
+interface DestroyManagerLike {
+    destroyMesh(mesh: MeshLike | number): boolean;
+    destroyTexture(texture: TextureResource | number): boolean;
+    destroyMaterial(material: Material2d | number): boolean;
+    destroyGeometry(geometry: GeoData | number): boolean;
+    trim(scene: Scene): void;
+    destroyAll(): void;
+}
+/**
+ * 统一负责当前 Render 的 GPU 资源销毁与无引用缓存回收。
+ * @class
+ */
+declare class DestroyManager implements DestroyManagerLike {
+    private readonly pipeline;
+    /**
+     * 创建销毁管理器。
+     * @param pipeline 当前 Render 的共享管线资源
+     */
+    constructor(pipeline: PipelineLike);
+    /**
+     * 销毁指定 Mesh 的模型矩阵缓冲及可取得的关联资源。
+     * @param mesh Mesh 对象或全局 ID
+     * @returns 是否销毁了任意资源
+     */
+    destroyMesh(mesh: MeshLike | number): boolean;
+    /**
+     * 销毁指定 Texture 的 GPUTexture 缓存。
+     * @param texture Texture 对象或全局 ID
+     * @returns 是否找到并销毁了对应资源
+     */
+    destroyTexture(texture: TextureResource | number): boolean;
+    /**
+     * 销毁所有关联此 Material 的 Mesh 实例样式缓冲，并在可取得对象时销毁其基础、边框和点型贴图。
+     * @param material Material 对象或全局 ID
+     * @returns 是否销毁了任意资源
+     */
+    destroyMaterial(material: Material2d | number): boolean;
+    /**
+     * 销毁指定 Geometry 的全部 GPUBuffer。
+     * @param geometry Geometry 对象或全局 ID
+     * @returns 是否找到并销毁了对应资源
+     */
+    destroyGeometry(geometry: GeoData | number): boolean;
+    /**
+     * 更新场景资源使用记录并回收所有场景均未引用的缓存。
+     * @param scene 需要同步资源记录的场景
+     * @returns 无返回值
+     */
+    trim(scene: Scene): void;
+    /**
+     * 销毁当前 Render 持有的全部 WebGPU 资源和设备。
+     * @returns 无返回值
+     */
+    destroyAll(): void;
+    /**
+     * 销毁 Geometry 所有绘制模式已经创建的全部缓冲。
+     * @param geometryBuffer Geometry GPU 缓存集合
+     * @returns 无返回值
+     */
+    private destroyGeometryBuffer;
+    /**
+     * 解除引用某个纹理视图的缓存绑定，不影响其他 Mesh。
+     * @param view 即将销毁的 GPU 纹理视图
+     */
+    private releaseTextureBindings;
+}
+export default DestroyManager;
+export type { DestroyManagerLike };