538 lines
31 KiB
TypeScript
538 lines
31 KiB
TypeScript
import { normalizeProjectAssetPath } from "./asset-path";
|
|
import { blockedGate, capabilityIssue, readyGate, type CapabilityGateResult } from "./capability-gates";
|
|
import type { ErrorCode } from "./error";
|
|
import type { VolumeGridMetadataIR } from "./scene-ir";
|
|
|
|
export const VDB_PIPELINE_SCHEMA = 1;
|
|
export const VDB_MAX_RESOURCE_BYTES = 512 * 1024 * 1024;
|
|
export const VDB_MAX_ACTIVE_VOXELS = 64_000_000;
|
|
export const VDB_MAX_GRIDS = 64;
|
|
export const NANOVDB_MAX_BUNDLE_BYTES = 1024 * 1024 * 1024;
|
|
export const NANOVDB_MAX_CHUNKS = 8192;
|
|
export const NANOVDB_MAX_CHUNK_BYTES = 16 * 1024 * 1024;
|
|
export const NANOVDB_MAX_GPU_RESIDENT_BYTES = 512 * 1024 * 1024;
|
|
|
|
const ID_PATTERN = /^[a-zA-Z0-9._-]+$/;
|
|
const SHA256_PATTERN = /^[a-f0-9]{64}$/;
|
|
const SUPPORTED_GRID_TYPES = new Set<NanoVDBGridValueType>(["FLOAT32", "FLOAT16", "VEC3F32", "VEC4F32"]);
|
|
|
|
export type VDBExecutionTarget = "DESKTOP" | "SERVER";
|
|
export type NanoVDBGridValueType = "FLOAT32" | "FLOAT16" | "VEC3F32" | "VEC4F32";
|
|
export type NanoVDBGridClass = "FOG_VOLUME" | "LEVEL_SET" | "STAGGERED" | "UNKNOWN";
|
|
export type NanoVDBGridSemantic = "DENSITY" | "TEMPERATURE" | "COLOR" | "EMISSION" | "VELOCITY" | "CUSTOM";
|
|
export type NanoVDBPipelineStage =
|
|
| "RAW_VDB_BROWSER_DECODE"
|
|
| "DESKTOP_CONVERSION"
|
|
| "SERVER_CONVERSION"
|
|
| "NANOVDB_STREAM"
|
|
| "WEBGPU_VOLUME_RENDER";
|
|
|
|
export class VDBPipelineError extends Error {
|
|
constructor(public readonly code: ErrorCode, message: string) {
|
|
super(`${code}: ${message}`);
|
|
this.name = "VDBPipelineError";
|
|
}
|
|
}
|
|
|
|
export interface VDBResourceManifest {
|
|
projectId: string;
|
|
sourcePath: string;
|
|
byteLength: number;
|
|
sha256: string;
|
|
grids: VolumeGridMetadataIR[];
|
|
}
|
|
|
|
export interface VDBConversionInput extends VDBResourceManifest {
|
|
data: ArrayBuffer;
|
|
}
|
|
|
|
export interface PreparedVDBConversionInput {
|
|
metadata: VDBResourceManifest;
|
|
data: ArrayBuffer;
|
|
}
|
|
|
|
export interface VDBConverterIdentityIR {
|
|
target: VDBExecutionTarget;
|
|
blenderVersion: string;
|
|
openVDBVersion: string;
|
|
nanoVDBVersion: string;
|
|
executableSha256: string;
|
|
}
|
|
|
|
export interface VDBConversionRequestIR {
|
|
schemaVersion: typeof VDB_PIPELINE_SCHEMA;
|
|
jobId: string;
|
|
source: VDBResourceManifest;
|
|
sourceBlendSha256?: string;
|
|
outputPath: string;
|
|
selectedGrids: string[];
|
|
quantization: "LOSSLESS" | "FP16" | "FP8";
|
|
chunkByteLength: number;
|
|
converter: VDBConverterIdentityIR;
|
|
}
|
|
|
|
export interface NanoVDBChunkIR {
|
|
index: number;
|
|
byteOffset: number;
|
|
byteLength: number;
|
|
sha256: string;
|
|
}
|
|
|
|
export interface NanoVDBGridIR {
|
|
name: string;
|
|
valueType: NanoVDBGridValueType;
|
|
gridClass: NanoVDBGridClass;
|
|
semantic: NanoVDBGridSemantic;
|
|
activeVoxelCount: number;
|
|
segmentByteOffset: number;
|
|
segmentByteLength: number;
|
|
byteOffset: number;
|
|
byteLength: number;
|
|
indexBounds: { min: [number, number, number]; max: [number, number, number] };
|
|
worldBounds: { min: [number, number, number]; max: [number, number, number] };
|
|
voxelSize: [number, number, number];
|
|
indexToWorld: [number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number];
|
|
}
|
|
|
|
export interface NanoVDBMaterialIR {
|
|
densityGrid: string;
|
|
temperatureGrid?: string;
|
|
colorGrid?: string;
|
|
emissionGrid?: string;
|
|
velocityGrid?: string;
|
|
densityScale: number;
|
|
emissionScale: number;
|
|
temperatureScale: number;
|
|
anisotropy: number;
|
|
interpolation: "NEAREST" | "LINEAR";
|
|
color?: [number, number, number];
|
|
emissionColor?: [number, number, number];
|
|
}
|
|
|
|
export interface NanoVDBGpuLayoutIR {
|
|
representation: "NANOVDB_STORAGE_BUFFER";
|
|
byteAlignment: 32;
|
|
pageByteLength: number;
|
|
maxResidentBytes: number;
|
|
shaderSemanticVersion: "volume-wgsl-v1";
|
|
float32TreeLayout?: NanoVDBFloat32TreeLayoutIR;
|
|
vec3fTreeLayout?: NanoVDBFloat32TreeLayoutIR;
|
|
}
|
|
|
|
export interface NanoVDBFloat32TreeLayoutIR {
|
|
gridDataBytes: number;
|
|
treeDataBytes: number;
|
|
treeRootOffsetOffset: number;
|
|
rootDataBytes: number;
|
|
rootTableSizeOffset: number;
|
|
rootTileBytes: number;
|
|
rootTileKeyOffset: number;
|
|
rootTileChildOffset: number;
|
|
rootTileStateOffset: number;
|
|
rootTileValueOffset: number;
|
|
upperNodeBytes: number;
|
|
upperValueMaskOffset: number;
|
|
upperChildMaskOffset: number;
|
|
upperTableOffset: number;
|
|
lowerNodeBytes: number;
|
|
lowerValueMaskOffset: number;
|
|
lowerChildMaskOffset: number;
|
|
lowerTableOffset: number;
|
|
leafNodeBytes: number;
|
|
leafValueMaskOffset: number;
|
|
leafValuesOffset: number;
|
|
}
|
|
|
|
export interface NanoVDBBundleManifestIR {
|
|
schemaVersion: typeof VDB_PIPELINE_SCHEMA;
|
|
projectId: string;
|
|
sourcePath: string;
|
|
sourceSha256: string;
|
|
conversionRequestSha256: string;
|
|
bundlePath: string;
|
|
bundleByteLength: number;
|
|
bundleSha256: string;
|
|
converter: VDBConverterIdentityIR;
|
|
grids: NanoVDBGridIR[];
|
|
chunks: NanoVDBChunkIR[];
|
|
material: NanoVDBMaterialIR;
|
|
gpu: NanoVDBGpuLayoutIR;
|
|
}
|
|
|
|
export interface VDBProjectBindingIR {
|
|
schemaVersion: typeof VDB_PIPELINE_SCHEMA;
|
|
projectId: string;
|
|
sourceBlendSha256: string;
|
|
sourcePath: string;
|
|
sourceSha256: string;
|
|
conversionRequestSha256: string;
|
|
bundleSha256: string;
|
|
bundleByteLength: number;
|
|
manifestSha256: string;
|
|
converter: VDBConverterIdentityIR;
|
|
shaderSemanticVersion: NanoVDBGpuLayoutIR["shaderSemanticVersion"];
|
|
material: NanoVDBMaterialIR;
|
|
committedAt: string;
|
|
}
|
|
|
|
export interface VDBProjectReopenContextIR {
|
|
projectId: string;
|
|
sourceBlendSha256: string;
|
|
sourcePath: string;
|
|
sourceSha256: string;
|
|
converter: VDBConverterIdentityIR;
|
|
shaderSemanticVersion: NanoVDBGpuLayoutIR["shaderSemanticVersion"];
|
|
}
|
|
|
|
export interface VDBProjectBindingStatusIR {
|
|
status: "READY" | "BLOCKED";
|
|
code?: "VDB_BINDING_MISSING" | "VDB_SOURCE_CHANGED" | "VDB_CONVERTER_CHANGED" | "NANOVDB_HASH_MISMATCH" | "VOLUME_SHADER_UNAVAILABLE";
|
|
message?: string;
|
|
}
|
|
|
|
export interface NanoVDBRangeIR {
|
|
chunkIndex: number;
|
|
start: number;
|
|
endExclusive: number;
|
|
sha256: string;
|
|
}
|
|
|
|
export interface NanoVDBPipelineContext {
|
|
desktopConverterConfigured?: boolean;
|
|
serverConverterConfigured?: boolean;
|
|
manifestValidated?: boolean;
|
|
rangeReaderAvailable?: boolean;
|
|
webgpuAvailable?: boolean;
|
|
volumeRendererAvailable?: boolean;
|
|
}
|
|
|
|
function fail(code: ErrorCode, message: string): never {
|
|
throw new VDBPipelineError(code, message);
|
|
}
|
|
|
|
function safeInteger(value: number, name: string, min: number, max: number): number {
|
|
if (!Number.isSafeInteger(value) || value < min || value > max) fail("NANOVDB_MANIFEST_INVALID", `${name} is outside the bounded integer range`);
|
|
return value;
|
|
}
|
|
|
|
function finite(value: number, name: string): number {
|
|
if (!Number.isFinite(value)) fail("NANOVDB_MANIFEST_INVALID", `${name} must be finite`);
|
|
return value;
|
|
}
|
|
|
|
function projectPath(sourcePath: string, extension: string, label: string): string {
|
|
let normalized: string;
|
|
try {
|
|
normalized = normalizeProjectAssetPath(sourcePath);
|
|
}
|
|
catch {
|
|
fail("NON_MESH_RESOURCE_OUTSIDE_PROJECT", `${label} path is outside the project asset root`);
|
|
}
|
|
if (!normalized.toLowerCase().endsWith(extension)) fail("NON_MESH_BINARY_INVALID", `${label} must use the ${extension} extension`);
|
|
return normalized;
|
|
}
|
|
|
|
function validateIdentity(value: VDBConverterIdentityIR): VDBConverterIdentityIR {
|
|
if (value.target !== "DESKTOP" && value.target !== "SERVER") fail("VDB_CONVERSION_INVALID", "Converter target is invalid");
|
|
for (const [name, version] of Object.entries({ blenderVersion: value.blenderVersion, openVDBVersion: value.openVDBVersion, nanoVDBVersion: value.nanoVDBVersion })) {
|
|
if (typeof version !== "string" || version.length === 0 || version.length > 128) fail("VDB_CONVERSION_INVALID", `${name} is invalid`);
|
|
}
|
|
if (!SHA256_PATTERN.test(value.executableSha256)) fail("VDB_CONVERSION_INVALID", "Converter executable SHA-256 is invalid");
|
|
return { ...value };
|
|
}
|
|
|
|
function validateBounds(
|
|
bounds: { min: [number, number, number]; max: [number, number, number] },
|
|
name: string,
|
|
integer: boolean,
|
|
): void {
|
|
if (!bounds || bounds.min.length !== 3 || bounds.max.length !== 3) fail("NANOVDB_MANIFEST_INVALID", `${name} bounds are invalid`);
|
|
bounds.min.forEach((value, index) => {
|
|
if (!Number.isFinite(value) || value > bounds.max[index] || (integer && (!Number.isSafeInteger(value) || !Number.isSafeInteger(bounds.max[index])))) {
|
|
fail("NANOVDB_MANIFEST_INVALID", `${name} bounds are invalid`);
|
|
}
|
|
});
|
|
}
|
|
|
|
function validateColor(value: [number, number, number] | undefined, name: string): void {
|
|
if (value === undefined) return;
|
|
if (!Array.isArray(value) || value.length !== 3 || value.some((channel) => !Number.isFinite(channel) || channel < 0 || channel > 1000000)) {
|
|
fail("NANOVDB_MANIFEST_INVALID", `${name} must contain three finite non-negative channels`);
|
|
}
|
|
}
|
|
|
|
function hex(bytes: Uint8Array): string {
|
|
return Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
|
|
}
|
|
|
|
async function sha256(data: ArrayBuffer): Promise<string> {
|
|
if (!globalThis.crypto?.subtle) fail("NON_MESH_BINARY_INVALID", "SHA-256 is unavailable");
|
|
return hex(new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", data)));
|
|
}
|
|
|
|
export function validateVDBManifest(manifest: VDBResourceManifest): VDBResourceManifest {
|
|
if (!manifest.projectId || !ID_PATTERN.test(manifest.projectId)) fail("NON_MESH_BINARY_INVALID", "VDB projectId is invalid");
|
|
const sourcePath = projectPath(manifest.sourcePath, ".vdb", "VDB resource");
|
|
if (!Number.isSafeInteger(manifest.byteLength) || manifest.byteLength <= 0 || manifest.byteLength > VDB_MAX_RESOURCE_BYTES) fail("NON_MESH_VDB_BUDGET_EXCEEDED", "VDB resource size is outside the bounded range");
|
|
if (!SHA256_PATTERN.test(manifest.sha256)) fail("NON_MESH_BINARY_INVALID", "VDB SHA-256 is invalid");
|
|
if (!Array.isArray(manifest.grids) || manifest.grids.length === 0 || manifest.grids.length > VDB_MAX_GRIDS) fail("NON_MESH_VDB_BUDGET_EXCEEDED", "VDB grid count is outside the bounded range");
|
|
const names = new Set<string>();
|
|
let activeVoxels = 0;
|
|
for (const grid of manifest.grids) {
|
|
if (!grid.name || names.has(grid.name) || !grid.valueType) fail("NON_MESH_BINARY_INVALID", "VDB grid identity is missing or duplicated");
|
|
names.add(grid.name);
|
|
const count = grid.activeVoxelCount ?? grid.voxelCount;
|
|
if (!Number.isSafeInteger(count) || count < 0) fail("NON_MESH_BINARY_INVALID", `VDB grid ${grid.name} has an invalid active voxel count`);
|
|
activeVoxels += count;
|
|
if (!Number.isSafeInteger(activeVoxels) || activeVoxels > VDB_MAX_ACTIVE_VOXELS) fail("NON_MESH_VDB_BUDGET_EXCEEDED", "VDB active voxel budget exceeded");
|
|
if (grid.bounds) validateBounds(grid.bounds, `VDB grid ${grid.name}`, false);
|
|
}
|
|
return { ...manifest, sourcePath, grids: manifest.grids.map((grid) => ({ ...grid })) };
|
|
}
|
|
|
|
export async function prepareVDBConversionInput(request: VDBConversionInput, signal: AbortSignal): Promise<PreparedVDBConversionInput> {
|
|
const metadata = validateVDBManifest(request);
|
|
if (signal.aborted) throw new DOMException("VDB source validation cancelled", "AbortError");
|
|
if (!(request.data instanceof ArrayBuffer) || request.data.byteLength !== metadata.byteLength) fail("NON_MESH_BINARY_INVALID", "VDB byte length does not match its manifest");
|
|
if (await sha256(request.data) !== metadata.sha256) fail("NANOVDB_HASH_MISMATCH", "VDB bytes do not match the source manifest SHA-256");
|
|
if (signal.aborted) throw new DOMException("VDB source validation cancelled", "AbortError");
|
|
return { metadata, data: request.data };
|
|
}
|
|
|
|
export function validateVDBConversionRequest(request: VDBConversionRequestIR): VDBConversionRequestIR {
|
|
if (request.schemaVersion !== VDB_PIPELINE_SCHEMA || !ID_PATTERN.test(request.jobId)) fail("VDB_CONVERSION_INVALID", "Conversion request schema or job ID is invalid");
|
|
const source = validateVDBManifest(request.source);
|
|
const outputPath = projectPath(request.outputPath, ".nvdb", "NanoVDB output");
|
|
if (request.sourceBlendSha256 !== undefined && !SHA256_PATTERN.test(request.sourceBlendSha256)) fail("VDB_CONVERSION_INVALID", "Source blend SHA-256 is invalid");
|
|
if (!Array.isArray(request.selectedGrids) || request.selectedGrids.length === 0 || request.selectedGrids.length > VDB_MAX_GRIDS) fail("VDB_CONVERSION_INVALID", "Selected grid list is invalid");
|
|
const available = new Set(source.grids.map((grid) => grid.name));
|
|
const selected = new Set<string>();
|
|
request.selectedGrids.forEach((name) => {
|
|
if (!available.has(name) || selected.has(name)) fail("VDB_CONVERSION_INVALID", `Selected grid ${name} is missing or duplicated`);
|
|
selected.add(name);
|
|
});
|
|
if (!["LOSSLESS", "FP16", "FP8"].includes(request.quantization)) fail("VDB_CONVERSION_INVALID", "NanoVDB quantization is invalid");
|
|
if (!Number.isSafeInteger(request.chunkByteLength) || request.chunkByteLength < 64 * 1024 || request.chunkByteLength > NANOVDB_MAX_CHUNK_BYTES || request.chunkByteLength % 32 !== 0) fail("VDB_CONVERSION_INVALID", "Chunk size must be 32-byte aligned and within 64 KiB to 16 MiB");
|
|
return { ...request, source, outputPath, selectedGrids: [...request.selectedGrids], converter: validateIdentity(request.converter) };
|
|
}
|
|
|
|
export function serializeVDBConversionRequest(value: VDBConversionRequestIR): string {
|
|
const request = validateVDBConversionRequest(value);
|
|
return JSON.stringify({
|
|
schemaVersion: request.schemaVersion,
|
|
source: {
|
|
byteLength: request.source.byteLength,
|
|
sha256: request.source.sha256,
|
|
grids: request.source.grids.map((grid) => ({
|
|
name: grid.name,
|
|
valueType: grid.valueType,
|
|
voxelCount: grid.voxelCount,
|
|
...(grid.activeVoxelCount === undefined ? {} : { activeVoxelCount: grid.activeVoxelCount }),
|
|
...(grid.bounds === undefined ? {} : { bounds: grid.bounds }),
|
|
})),
|
|
},
|
|
...(request.sourceBlendSha256 === undefined ? {} : { sourceBlendSha256: request.sourceBlendSha256 }),
|
|
selectedGrids: request.selectedGrids,
|
|
quantization: request.quantization,
|
|
chunkByteLength: request.chunkByteLength,
|
|
converter: request.converter,
|
|
});
|
|
}
|
|
|
|
export async function hashVDBConversionRequest(value: VDBConversionRequestIR): Promise<string> {
|
|
const encoded = new TextEncoder().encode(serializeVDBConversionRequest(value));
|
|
return sha256(encoded.buffer.slice(encoded.byteOffset, encoded.byteOffset + encoded.byteLength) as ArrayBuffer);
|
|
}
|
|
|
|
export function validateNanoVDBBundleManifest(manifest: NanoVDBBundleManifestIR): NanoVDBBundleManifestIR {
|
|
if (manifest.schemaVersion !== VDB_PIPELINE_SCHEMA || !ID_PATTERN.test(manifest.projectId)) fail("NANOVDB_MANIFEST_INVALID", "NanoVDB schema or project ID is invalid");
|
|
const sourcePath = projectPath(manifest.sourcePath, ".vdb", "VDB source");
|
|
const bundlePath = projectPath(manifest.bundlePath, ".nvdb", "NanoVDB bundle");
|
|
if (!SHA256_PATTERN.test(manifest.sourceSha256) || !SHA256_PATTERN.test(manifest.conversionRequestSha256) || !SHA256_PATTERN.test(manifest.bundleSha256)) fail("NANOVDB_MANIFEST_INVALID", "NanoVDB source, conversion request, or bundle SHA-256 is invalid");
|
|
safeInteger(manifest.bundleByteLength, "bundleByteLength", 1, NANOVDB_MAX_BUNDLE_BYTES);
|
|
const converter = validateIdentity(manifest.converter);
|
|
if (!Array.isArray(manifest.chunks) || manifest.chunks.length === 0 || manifest.chunks.length > NANOVDB_MAX_CHUNKS) fail("NANOVDB_MANIFEST_INVALID", "NanoVDB chunk count is outside the bounded range");
|
|
let nextOffset = 0;
|
|
const chunks = manifest.chunks.map((chunk, position) => {
|
|
if (chunk.index !== position || chunk.byteOffset !== nextOffset || chunk.byteOffset % 32 !== 0) fail("NANOVDB_STREAM_INCOMPLETE", `NanoVDB chunk ${position} is not contiguous or aligned`);
|
|
safeInteger(chunk.byteLength, `chunks[${position}].byteLength`, 1, NANOVDB_MAX_CHUNK_BYTES);
|
|
if (position < manifest.chunks.length - 1 && chunk.byteLength % 32 !== 0) fail("NANOVDB_STREAM_INCOMPLETE", `NanoVDB chunk ${position} length is not aligned`);
|
|
if (!SHA256_PATTERN.test(chunk.sha256)) fail("NANOVDB_MANIFEST_INVALID", `NanoVDB chunk ${position} SHA-256 is invalid`);
|
|
nextOffset += chunk.byteLength;
|
|
if (!Number.isSafeInteger(nextOffset) || nextOffset > manifest.bundleByteLength) fail("NANOVDB_STREAM_INCOMPLETE", "NanoVDB chunk ranges exceed the bundle");
|
|
return { ...chunk };
|
|
});
|
|
if (nextOffset !== manifest.bundleByteLength) fail("NANOVDB_STREAM_INCOMPLETE", "NanoVDB chunks do not cover the complete bundle");
|
|
|
|
if (!Array.isArray(manifest.grids) || manifest.grids.length === 0 || manifest.grids.length > VDB_MAX_GRIDS) fail("NANOVDB_MANIFEST_INVALID", "NanoVDB grid count is outside the bounded range");
|
|
const names = new Set<string>();
|
|
let activeVoxels = 0;
|
|
const grids = manifest.grids.map((grid) => {
|
|
if (!grid.name || names.has(grid.name)) fail("NANOVDB_MANIFEST_INVALID", "NanoVDB grid identity is missing or duplicated");
|
|
names.add(grid.name);
|
|
if (!SUPPORTED_GRID_TYPES.has(grid.valueType)) fail("NANOVDB_GRID_UNSUPPORTED", `NanoVDB grid ${grid.name} uses unsupported value type ${grid.valueType}`);
|
|
if (!["FOG_VOLUME", "LEVEL_SET", "STAGGERED", "UNKNOWN"].includes(grid.gridClass) || !["DENSITY", "TEMPERATURE", "COLOR", "EMISSION", "VELOCITY", "CUSTOM"].includes(grid.semantic)) fail("NANOVDB_MANIFEST_INVALID", `NanoVDB grid ${grid.name} class or semantic is invalid`);
|
|
safeInteger(grid.activeVoxelCount, `${grid.name}.activeVoxelCount`, 0, VDB_MAX_ACTIVE_VOXELS);
|
|
activeVoxels += grid.activeVoxelCount;
|
|
if (!Number.isSafeInteger(activeVoxels) || activeVoxels > VDB_MAX_ACTIVE_VOXELS) fail("NON_MESH_VDB_BUDGET_EXCEEDED", "NanoVDB active voxel budget exceeded");
|
|
safeInteger(grid.segmentByteOffset, `${grid.name}.segmentByteOffset`, 0, manifest.bundleByteLength - 1);
|
|
safeInteger(grid.segmentByteLength, `${grid.name}.segmentByteLength`, 1, manifest.bundleByteLength);
|
|
safeInteger(grid.byteOffset, `${grid.name}.byteOffset`, 0, manifest.bundleByteLength - 1);
|
|
safeInteger(grid.byteLength, `${grid.name}.byteLength`, 1, manifest.bundleByteLength);
|
|
if (grid.segmentByteOffset + grid.segmentByteLength > manifest.bundleByteLength || grid.byteOffset < grid.segmentByteOffset || grid.byteOffset + grid.byteLength > grid.segmentByteOffset + grid.segmentByteLength) fail("NANOVDB_MANIFEST_INVALID", `NanoVDB grid ${grid.name} segment or payload range is invalid`);
|
|
validateBounds(grid.indexBounds, `NanoVDB grid ${grid.name} index`, true);
|
|
validateBounds(grid.worldBounds, `NanoVDB grid ${grid.name} world`, false);
|
|
if (grid.voxelSize.length !== 3 || grid.voxelSize.some((value) => !Number.isFinite(value) || value <= 0)) fail("NANOVDB_MANIFEST_INVALID", `NanoVDB grid ${grid.name} voxel size is invalid`);
|
|
if (grid.indexToWorld.length !== 16 || grid.indexToWorld.some((value) => !Number.isFinite(value))) fail("NANOVDB_MANIFEST_INVALID", `NanoVDB grid ${grid.name} transform is invalid`);
|
|
return { ...grid, indexBounds: { min: [...grid.indexBounds.min], max: [...grid.indexBounds.max] }, worldBounds: { min: [...grid.worldBounds.min], max: [...grid.worldBounds.max] }, voxelSize: [...grid.voxelSize], indexToWorld: [...grid.indexToWorld] } as NanoVDBGridIR;
|
|
});
|
|
const orderedRanges = [...grids].sort((left, right) => left.segmentByteOffset - right.segmentByteOffset);
|
|
for (let index = 1; index < orderedRanges.length; index += 1) {
|
|
if (orderedRanges[index - 1].segmentByteOffset + orderedRanges[index - 1].segmentByteLength > orderedRanges[index].segmentByteOffset) fail("NANOVDB_MANIFEST_INVALID", "NanoVDB grid segments overlap");
|
|
}
|
|
|
|
const material = { ...manifest.material };
|
|
const references: Array<[keyof NanoVDBMaterialIR, NanoVDBGridSemantic]> = [
|
|
["densityGrid", "DENSITY"], ["temperatureGrid", "TEMPERATURE"], ["colorGrid", "COLOR"],
|
|
["emissionGrid", "EMISSION"], ["velocityGrid", "VELOCITY"],
|
|
];
|
|
for (const [field, semantic] of references) {
|
|
const gridName = material[field];
|
|
if (typeof gridName !== "string") continue;
|
|
const grid = grids.find((candidate) => candidate.name === gridName);
|
|
if (!grid || grid.semantic !== semantic) fail("NANOVDB_MANIFEST_INVALID", `Material ${field} does not reference a ${semantic} grid`);
|
|
}
|
|
finite(material.densityScale, "material.densityScale");
|
|
finite(material.emissionScale, "material.emissionScale");
|
|
finite(material.temperatureScale, "material.temperatureScale");
|
|
validateColor(material.color, "material.color");
|
|
validateColor(material.emissionColor, "material.emissionColor");
|
|
if (material.densityScale < 0 || material.emissionScale < 0 || material.temperatureScale < 0 || !Number.isFinite(material.anisotropy) || material.anisotropy < -0.99 || material.anisotropy > 0.99 || !["NEAREST", "LINEAR"].includes(material.interpolation)) fail("NANOVDB_MANIFEST_INVALID", "NanoVDB material parameters are invalid");
|
|
|
|
const gpu = { ...manifest.gpu };
|
|
if (gpu.representation !== "NANOVDB_STORAGE_BUFFER" || gpu.byteAlignment !== 32 || gpu.shaderSemanticVersion !== "volume-wgsl-v1") fail("NANOVDB_MANIFEST_INVALID", "NanoVDB GPU representation is unsupported");
|
|
if (!Number.isSafeInteger(gpu.pageByteLength) || gpu.pageByteLength < 64 * 1024 || gpu.pageByteLength > NANOVDB_MAX_CHUNK_BYTES || gpu.pageByteLength % 32 !== 0) fail("NANOVDB_MANIFEST_INVALID", "NanoVDB GPU page size is invalid");
|
|
if (!Number.isSafeInteger(gpu.maxResidentBytes) || gpu.maxResidentBytes < gpu.pageByteLength || gpu.maxResidentBytes > NANOVDB_MAX_GPU_RESIDENT_BYTES) fail("NANOVDB_GPU_BUDGET_EXCEEDED", "NanoVDB GPU resident budget is invalid");
|
|
if (gpu.float32TreeLayout !== undefined) {
|
|
const layout = gpu.float32TreeLayout;
|
|
const expected: NanoVDBFloat32TreeLayoutIR = {
|
|
gridDataBytes: 672, treeDataBytes: 64, treeRootOffsetOffset: 24,
|
|
rootDataBytes: 64, rootTableSizeOffset: 24, rootTileBytes: 32, rootTileKeyOffset: 0, rootTileChildOffset: 8, rootTileStateOffset: 16, rootTileValueOffset: 20,
|
|
upperNodeBytes: 270400, upperValueMaskOffset: 32, upperChildMaskOffset: 4128, upperTableOffset: 8256,
|
|
lowerNodeBytes: 33856, lowerValueMaskOffset: 32, lowerChildMaskOffset: 544, lowerTableOffset: 1088,
|
|
leafNodeBytes: 2144, leafValueMaskOffset: 16, leafValuesOffset: 96,
|
|
};
|
|
for (const [name, expectedValue] of Object.entries(expected)) if (!Number.isSafeInteger(layout[name as keyof NanoVDBFloat32TreeLayoutIR]) || layout[name as keyof NanoVDBFloat32TreeLayoutIR] !== expectedValue) fail("NANOVDB_GRID_UNSUPPORTED", `NanoVDB Float32 layout ${name} is unsupported`);
|
|
}
|
|
if (gpu.vec3fTreeLayout !== undefined) {
|
|
const layout = gpu.vec3fTreeLayout;
|
|
const expected: NanoVDBFloat32TreeLayoutIR = {
|
|
gridDataBytes: 672, treeDataBytes: 64, treeRootOffsetOffset: 24,
|
|
rootDataBytes: 96, rootTableSizeOffset: 24, rootTileBytes: 32, rootTileKeyOffset: 0, rootTileChildOffset: 8, rootTileStateOffset: 16, rootTileValueOffset: 20,
|
|
upperNodeBytes: 532544, upperValueMaskOffset: 32, upperChildMaskOffset: 4128, upperTableOffset: 8256,
|
|
lowerNodeBytes: 66624, lowerValueMaskOffset: 32, lowerChildMaskOffset: 544, lowerTableOffset: 1088,
|
|
leafNodeBytes: 6272, leafValueMaskOffset: 16, leafValuesOffset: 128,
|
|
};
|
|
for (const [name, expectedValue] of Object.entries(expected)) if (!Number.isSafeInteger(layout[name as keyof NanoVDBFloat32TreeLayoutIR]) || layout[name as keyof NanoVDBFloat32TreeLayoutIR] !== expectedValue) fail("NANOVDB_GRID_UNSUPPORTED", `NanoVDB Vec3f layout ${name} is unsupported`);
|
|
}
|
|
|
|
return { ...manifest, sourcePath, bundlePath, converter, chunks, grids, material, gpu };
|
|
}
|
|
|
|
export function validateVDBProjectBinding(value: VDBProjectBindingIR): VDBProjectBindingIR {
|
|
if (value.schemaVersion !== VDB_PIPELINE_SCHEMA || !ID_PATTERN.test(value.projectId)) fail("NANOVDB_MANIFEST_INVALID", "VDB project binding schema or project id is invalid");
|
|
const sourcePath = projectPath(value.sourcePath, ".vdb", "VDB binding source");
|
|
for (const [name, digest] of Object.entries({
|
|
sourceBlendSha256: value.sourceBlendSha256,
|
|
sourceSha256: value.sourceSha256,
|
|
conversionRequestSha256: value.conversionRequestSha256,
|
|
bundleSha256: value.bundleSha256,
|
|
manifestSha256: value.manifestSha256,
|
|
})) if (!SHA256_PATTERN.test(digest)) fail("NANOVDB_MANIFEST_INVALID", `VDB binding ${name} is invalid`);
|
|
safeInteger(value.bundleByteLength, "binding.bundleByteLength", 1, NANOVDB_MAX_BUNDLE_BYTES);
|
|
if (value.shaderSemanticVersion !== "volume-wgsl-v1") fail("NANOVDB_MANIFEST_INVALID", "VDB binding shader semantic version is unsupported");
|
|
if (typeof value.committedAt !== "string" || !Number.isFinite(Date.parse(value.committedAt))) fail("NANOVDB_MANIFEST_INVALID", "VDB binding commit timestamp is invalid");
|
|
const converter = validateIdentity(value.converter);
|
|
const synthetic: NanoVDBBundleManifestIR = {
|
|
schemaVersion: VDB_PIPELINE_SCHEMA,
|
|
projectId: value.projectId,
|
|
sourcePath,
|
|
sourceSha256: value.sourceSha256,
|
|
conversionRequestSha256: value.conversionRequestSha256,
|
|
bundlePath: "//cache/binding.nvdb",
|
|
bundleByteLength: value.bundleByteLength,
|
|
bundleSha256: value.bundleSha256,
|
|
converter,
|
|
grids: [{ name: value.material.densityGrid, valueType: "FLOAT32", gridClass: "FOG_VOLUME", semantic: "DENSITY", activeVoxelCount: 0, segmentByteOffset: 0, segmentByteLength: 1, byteOffset: 0, byteLength: 1, indexBounds: { min: [0, 0, 0], max: [0, 0, 0] }, worldBounds: { min: [0, 0, 0], max: [0, 0, 0] }, voxelSize: [1, 1, 1], indexToWorld: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1] }],
|
|
chunks: [{ index: 0, byteOffset: 0, byteLength: value.bundleByteLength, sha256: value.bundleSha256 }],
|
|
material: { ...value.material, temperatureGrid: undefined, colorGrid: undefined, emissionGrid: undefined, velocityGrid: undefined },
|
|
gpu: { representation: "NANOVDB_STORAGE_BUFFER", byteAlignment: 32, pageByteLength: Math.min(NANOVDB_MAX_CHUNK_BYTES, Math.max(64 * 1024, Math.ceil(Math.min(value.bundleByteLength, NANOVDB_MAX_CHUNK_BYTES) / 32) * 32)), maxResidentBytes: NANOVDB_MAX_GPU_RESIDENT_BYTES, shaderSemanticVersion: value.shaderSemanticVersion },
|
|
};
|
|
// Reuse bounded scalar material checks without requiring all referenced grids in this binding record.
|
|
finite(synthetic.material.densityScale, "binding.material.densityScale");
|
|
finite(synthetic.material.emissionScale, "binding.material.emissionScale");
|
|
finite(synthetic.material.temperatureScale, "binding.material.temperatureScale");
|
|
validateColor(synthetic.material.color, "binding.material.color");
|
|
validateColor(synthetic.material.emissionColor, "binding.material.emissionColor");
|
|
if (synthetic.material.densityScale < 0 || synthetic.material.emissionScale < 0 || synthetic.material.temperatureScale < 0 || !Number.isFinite(synthetic.material.anisotropy) || synthetic.material.anisotropy < -0.99 || synthetic.material.anisotropy > 0.99 || !["NEAREST", "LINEAR"].includes(synthetic.material.interpolation)) fail("NANOVDB_MANIFEST_INVALID", "VDB binding material is invalid");
|
|
return { ...value, sourcePath, converter, material: { ...value.material } };
|
|
}
|
|
|
|
export function evaluateVDBProjectBinding(value: VDBProjectBindingIR | undefined, context: VDBProjectReopenContextIR): VDBProjectBindingStatusIR {
|
|
if (!value) return { status: "BLOCKED", code: "VDB_BINDING_MISSING", message: "The project has no committed NanoVDB binding" };
|
|
const binding = validateVDBProjectBinding(value);
|
|
if (binding.projectId !== context.projectId || binding.sourcePath !== projectPath(context.sourcePath, ".vdb", "VDB reopen source") || binding.sourceBlendSha256 !== context.sourceBlendSha256 || binding.sourceSha256 !== context.sourceSha256) {
|
|
return { status: "BLOCKED", code: "VDB_SOURCE_CHANGED", message: "The blend or VDB source changed after conversion" };
|
|
}
|
|
const converter = validateIdentity(context.converter);
|
|
if (serializeIdentity(binding.converter) !== serializeIdentity(converter)) return { status: "BLOCKED", code: "VDB_CONVERTER_CHANGED", message: "The VDB converter identity changed" };
|
|
if (binding.shaderSemanticVersion !== context.shaderSemanticVersion) return { status: "BLOCKED", code: "VOLUME_SHADER_UNAVAILABLE", message: "The volume shader semantic version changed" };
|
|
return { status: "READY" };
|
|
}
|
|
|
|
function serializeIdentity(value: VDBConverterIdentityIR): string {
|
|
return `${value.target}\n${value.blenderVersion}\n${value.openVDBVersion}\n${value.nanoVDBVersion}\n${value.executableSha256}`;
|
|
}
|
|
|
|
export function planNanoVDBRanges(value: NanoVDBBundleManifestIR): NanoVDBRangeIR[] {
|
|
const manifest = validateNanoVDBBundleManifest(value);
|
|
return manifest.chunks.map((chunk) => ({ chunkIndex: chunk.index, start: chunk.byteOffset, endExclusive: chunk.byteOffset + chunk.byteLength, sha256: chunk.sha256 }));
|
|
}
|
|
|
|
export async function verifyNanoVDBChunk(chunk: NanoVDBChunkIR, data: ArrayBuffer): Promise<void> {
|
|
if (!(data instanceof ArrayBuffer) || data.byteLength !== chunk.byteLength) fail("NANOVDB_STREAM_INCOMPLETE", `NanoVDB chunk ${chunk.index} byte length is incomplete`);
|
|
if (await sha256(data) !== chunk.sha256) fail("NANOVDB_HASH_MISMATCH", `NanoVDB chunk ${chunk.index} SHA-256 mismatch`);
|
|
}
|
|
|
|
export async function verifyNanoVDBBundle(manifestValue: NanoVDBBundleManifestIR, data: ArrayBuffer): Promise<void> {
|
|
const manifest = validateNanoVDBBundleManifest(manifestValue);
|
|
if (!(data instanceof ArrayBuffer) || data.byteLength !== manifest.bundleByteLength) fail("NANOVDB_STREAM_INCOMPLETE", "NanoVDB bundle byte length is incomplete");
|
|
if (await sha256(data) !== manifest.bundleSha256) fail("NANOVDB_HASH_MISMATCH", "NanoVDB bundle SHA-256 mismatch");
|
|
}
|
|
|
|
export function gateNanoVDBPipeline(stage: NanoVDBPipelineStage, context: NanoVDBPipelineContext = {}): CapabilityGateResult {
|
|
if (stage === "RAW_VDB_BROWSER_DECODE") {
|
|
return blockedGate("N-015", stage, [capabilityIssue("VDB_CONVERSION_REQUIRED", "Raw OpenVDB must be converted by the desktop or server OpenVDB toolchain; browser decoding is intentionally unavailable")]);
|
|
}
|
|
if (stage === "DESKTOP_CONVERSION") {
|
|
return context.desktopConverterConfigured
|
|
? readyGate("N-015", stage)
|
|
: blockedGate("N-015", stage, [capabilityIssue("VDB_CONVERTER_UNAVAILABLE", "The desktop OpenVDB to NanoVDB converter is not configured")]);
|
|
}
|
|
if (stage === "SERVER_CONVERSION") {
|
|
return context.serverConverterConfigured
|
|
? readyGate("N-015", stage)
|
|
: blockedGate("N-015", stage, [capabilityIssue("VDB_CONVERTER_UNAVAILABLE", "The server OpenVDB to NanoVDB job endpoint is not configured")]);
|
|
}
|
|
if (stage === "NANOVDB_STREAM") {
|
|
return context.manifestValidated && context.rangeReaderAvailable
|
|
? readyGate("N-015", stage)
|
|
: blockedGate("N-015", stage, [capabilityIssue("NANOVDB_STREAM_INCOMPLETE", "A validated NanoVDB manifest and bounded range reader are required")]);
|
|
}
|
|
if (!context.webgpuAvailable) return blockedGate("N-015", stage, [capabilityIssue("WEBGPU_RENDERER_UNAVAILABLE", "WebGPU is unavailable in this browser or device")]);
|
|
if (!context.manifestValidated || !context.rangeReaderAvailable) return blockedGate("N-015", stage, [capabilityIssue("NANOVDB_STREAM_INCOMPLETE", "Volume rendering requires a validated and readable NanoVDB stream")]);
|
|
return context.volumeRendererAvailable
|
|
? readyGate("N-015", stage)
|
|
: blockedGate("N-015", stage, [capabilityIssue("VOLUME_SHADER_UNAVAILABLE", "The NanoVDB WGSL traversal and volume material renderer have not been installed")]);
|
|
}
|