15.9. Backend-neutral glTF geometry and texture preprocessing, validation, and persistence

Backend-neutral glTF preprocessing that packs and optionally encodes geometry, compresses textures, and persists validated monolithic or split-file assets.

15.9.1. Constants

DAS_GLTF_VERSION = 1

DAS_GLTF_VERSION:int const

DAS_GLTF_PROCESSOR_VERSION = 2

DAS_GLTF_PROCESSOR_VERSION:int const

VERTEX_UV = 1

VERTEX_UV:int const

VERTEX_TANGENT = 2

VERTEX_TANGENT:int const

VERTEX_SKIN = 4

VERTEX_SKIN:int const

VERTEX_UV1 = 8

VERTEX_UV1:int const

VERTEX_COLOR = 16

VERTEX_COLOR:int const

15.9.2. Structures

ProcessingProfile

Controls which optional vertex streams and storage encodings survive preprocessing.

Fields:

  • keep_uv1 : bool - Preserve secondary UVs and vertex colors when true.

  • keep_color : bool - Preserve secondary UVs and vertex colors when true.

  • compress_storage : bool = true - Encode triangle geometry with meshoptimizer when true.

  • texture_cache : string = “.jitted_scripts/assets/textures” - Directory for content-addressed block textures; empty disables cache I/O.

ProcessedPrimitive

Portable packed geometry for one primitive, optionally meshoptimizer-encoded.

Fields:

  • material : int = -1 - Index into the processed scene material array, or -1.

  • mode : GltfPrimitiveMode = gltf_types::GltfPrimitiveMode.triangles - Original glTF primitive topology.

  • attributes : int - Attribute flags, byte stride, and decoded element counts.

  • stride : int - Attribute flags, byte stride, and decoded element counts.

  • vertex_count : int - Attribute flags, byte stride, and decoded element counts.

  • index_count : int - Attribute flags, byte stride, and decoded element counts.

  • encoded : bool - True when both payload arrays use meshoptimizer codecs.

  • vertices : array<uint8> - Packed vertex bytes and uint32 index bytes, or their encoded forms.

  • indices : array<uint8> - Packed vertex bytes and uint32 index bytes, or their encoded forms.

  • lo : float3 - Object-space bounds of source positions, including unreferenced vertices.

  • hi : float3 - Object-space bounds of source positions, including unreferenced vertices.

ProcessedMesh

A named mesh containing portable processed primitives.

Fields:

  • name : string - Source mesh name.

  • primitives : array< ProcessedPrimitive> - Processed primitives in source order.

ProcessedAsset

Backend-neutral processed glTF data: scene metadata, packed geometry, and BC textures.

Fields:

  • version : int - Serialized asset layout version.

  • key : uint64 - Content and processing-profile key used by manifests and caches.

  • source : string - Source identifier included in the key and diagnostics.

  • scene : GltfScene - Nodes, materials, skins, animations, samplers, and texture references.

  • meshes : array< ProcessedMesh> - Portable geometry addressed by scene nodes.

  • images : array< BlockTexture> - Deduplicated compressed images addressed by scene textures.

  • lo : float3 - World-space bounds computed from the source scene.

  • hi : float3 - World-space bounds computed from the source scene.

  • source_vertices : int - Processing statistics for geometry and the texture cache.

  • processed_vertices : int - Processing statistics for geometry and the texture cache.

  • texture_hits : int - Processing statistics for geometry and the texture cache.

  • texture_misses : int - Processing statistics for geometry and the texture cache.

ProcessedCatalogEntry

Identifies one processed asset and the key that produced it.

Fields:

  • path : string - Asset path interpreted by the catalog consumer.

  • key : uint64 - Expected processed asset key.

ProcessedCatalog

Versioned list of processed assets for tooling and package manifests.

Fields:

  • version : int - Catalog schema version.

  • assets : array< ProcessedCatalogEntry> - Catalog entries in author-defined order.

ProcessedManifest

Split-file manifest for geometry and independently shared texture payloads.

Fields:

  • version : int - Manifest schema version.

  • key : uint64 - Expected key of the geometry payload.

  • geometry : string - Geometry filename relative to the manifest directory.

  • textures : array<string> - Texture filenames relative to the manifest directory.

15.9.3. Validation and persistence

load_and_process_gltf(path: string; profile: ProcessingProfile = ProcessingProfile() ): ProcessedAsset

Load an existing processed file by extension, otherwise parse and process a source glTF. Panics when the source is missing, unreadable, or contains no nodes, meshes, or animations.

Arguments:
load_processed(path: string ): ProcessedAsset

Load and validate a .das_glb binary or split .das_gltf manifest. Panics on missing, malformed, mismatched, or unsupported data.

Arguments:

  • path : string

processed_valid(a: ProcessedAsset ): bool

Check serialized version, size limits, packed strides and raw byte counts, compressed textures, and scene references. This is a cheap structural check; load_processed additionally decodes encoded geometry and validates every index before returning untrusted serialized data.

Arguments:
save_processed(asset: ProcessedAsset; path: string; shared_directory: string = "" ): bool

Save a validated asset as one .das_glb binary or as a .das_gltf manifest plus geometry and texture files. shared_directory allows textures to be shared across manifests.

Arguments:

15.9.4. Geometry processing

process_gltf(raw: GltfScene; source: string; profile: ProcessingProfile ): ProcessedAsset

Convert a loaded scene into backend-neutral processed geometry and block textures. source participates in the asset key; the returned scene retains hierarchy, materials, skins, and animation.

Arguments:
process_primitive(p: GltfPrimitive; flags: int; encode: bool; optimize_order: bool = true ): ProcessedPrimitive

Pack one glTF primitive according to flags, deduplicate triangle vertices, and optionally optimize ordering and encode storage. Non-triangle or unindexed primitives remain raw.

Arguments:

  • p : GltfPrimitive

  • flags : int

  • encode : bool

  • optimize_order : bool

processed_indices(p: ProcessedPrimitive ): array<uint>

Return decoded uint32 indices for p, rejecting codec failures and indices outside the declared vertex range with a panic.

Arguments:
processed_stride(flags: int ): int

Return the packed vertex stride for the VERTEX_* attribute bit mask. Position and normal are always present; optional streams add their fixed portable widths.

Arguments:

  • flags : int

processed_vertex_bytes(p: ProcessedPrimitive ): array<uint8>

Return decoded packed vertex bytes for p. Panics when an encoded payload fails validation.

Arguments:
unpack_processed_geometry(asset: ProcessedAsset ): GltfScene

Reconstruct ordinary GltfPrimitive vertex and index arrays from a processed asset while cloning its scene metadata. Panics if an encoded geometry payload cannot be decoded.

Arguments: