.. _stdlib_gltf_processed:

====================================================================================
Backend-neutral glTF geometry and texture preprocessing, validation, and persistence
====================================================================================

.. das:module:: gltf_processed

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



+++++++++
Constants
+++++++++

.. _global-gltf_processed-DAS_GLTF_VERSION:

.. das:attribute:: DAS_GLTF_VERSION = 1

DAS_GLTF_VERSION:int const

.. _global-gltf_processed-DAS_GLTF_PROCESSOR_VERSION:

.. das:attribute:: DAS_GLTF_PROCESSOR_VERSION = 2

DAS_GLTF_PROCESSOR_VERSION:int const

.. _global-gltf_processed-VERTEX_UV:

.. das:attribute:: VERTEX_UV = 1

VERTEX_UV:int const

.. _global-gltf_processed-VERTEX_TANGENT:

.. das:attribute:: VERTEX_TANGENT = 2

VERTEX_TANGENT:int const

.. _global-gltf_processed-VERTEX_SKIN:

.. das:attribute:: VERTEX_SKIN = 4

VERTEX_SKIN:int const

.. _global-gltf_processed-VERTEX_UV1:

.. das:attribute:: VERTEX_UV1 = 8

VERTEX_UV1:int const

.. _global-gltf_processed-VERTEX_COLOR:

.. das:attribute:: VERTEX_COLOR = 16

VERTEX_COLOR:int const


++++++++++
Structures
++++++++++

.. _struct-gltf_processed-ProcessingProfile:

.. das:attribute:: 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.



.. _struct-gltf_processed-ProcessedPrimitive:

.. das:attribute:: ProcessedPrimitive

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

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

         * **mode** :  :ref:`GltfPrimitiveMode <enum-gltf_types-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.



.. _struct-gltf_processed-ProcessedMesh:

.. das:attribute:: ProcessedMesh

A named mesh containing portable processed primitives.

:Fields: * **name** : string - Source mesh name.

         * **primitives** : array< :ref:`ProcessedPrimitive <struct-gltf_processed-ProcessedPrimitive>`> - Processed primitives in source order.



.. _struct-gltf_processed-ProcessedAsset:

.. das:attribute:: 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** :  :ref:`GltfScene <struct-gltf_types-GltfScene>` - Nodes, materials, skins, animations, samplers, and texture references.

         * **meshes** : array< :ref:`ProcessedMesh <struct-gltf_processed-ProcessedMesh>`> - Portable geometry addressed by scene nodes.

         * **images** : array< :ref:`BlockTexture <struct-texture_blocks-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.



.. _struct-gltf_processed-ProcessedCatalogEntry:

.. das:attribute:: 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.



.. _struct-gltf_processed-ProcessedCatalog:

.. das:attribute:: ProcessedCatalog

Versioned list of processed assets for tooling and package manifests.

:Fields: * **version** : int - Catalog schema version.

         * **assets** : array< :ref:`ProcessedCatalogEntry <struct-gltf_processed-ProcessedCatalogEntry>`> - Catalog entries in author-defined order.



.. _struct-gltf_processed-ProcessedManifest:

.. das:attribute:: 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.




++++++++++++++++++++++++++
Validation and persistence
++++++++++++++++++++++++++

  *  :ref:`load_and_process_gltf (path: string; profile: ProcessingProfile = ProcessingProfile()) : ProcessedAsset <function-gltf_processed_load_and_process_gltf_string_ProcessingProfile>`
  *  :ref:`load_processed (path: string) : ProcessedAsset <function-gltf_processed_load_processed_string>`
  *  :ref:`processed_valid (a: ProcessedAsset) : bool <function-gltf_processed_processed_valid_ProcessedAsset>`
  *  :ref:`save_processed (asset: ProcessedAsset; path: string; shared_directory: string = "") : bool <function-gltf_processed_save_processed_ProcessedAsset_string_string>`

.. _function-gltf_processed_load_and_process_gltf_string_ProcessingProfile:

.. das:function:: 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: * **path** : string

            * **profile** :  :ref:`ProcessingProfile <struct-gltf_processed-ProcessingProfile>`

.. _function-gltf_processed_load_processed_string:

.. das:function:: 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

.. _function-gltf_processed_processed_valid_ProcessedAsset:

.. das:function:: 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: * **a** :  :ref:`ProcessedAsset <struct-gltf_processed-ProcessedAsset>`

.. _function-gltf_processed_save_processed_ProcessedAsset_string_string:

.. das:function:: 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: * **asset** :  :ref:`ProcessedAsset <struct-gltf_processed-ProcessedAsset>`

            * **path** : string

            * **shared_directory** : string


+++++++++++++++++++
Geometry processing
+++++++++++++++++++

  *  :ref:`process_gltf (raw: GltfScene; source: string; profile: ProcessingProfile) : ProcessedAsset <function-gltf_processed_process_gltf_GltfScene_string_ProcessingProfile>`
  *  :ref:`process_primitive (p: GltfPrimitive; flags: int; encode: bool; optimize_order: bool = true) : ProcessedPrimitive <function-gltf_processed_process_primitive_GltfPrimitive_int_bool_bool>`
  *  :ref:`processed_indices (p: ProcessedPrimitive) : array\<uint\> <function-gltf_processed_processed_indices_ProcessedPrimitive>`
  *  :ref:`processed_stride (flags: int) : int <function-gltf_processed_processed_stride_int>`
  *  :ref:`processed_vertex_bytes (p: ProcessedPrimitive) : array\<uint8\> <function-gltf_processed_processed_vertex_bytes_ProcessedPrimitive>`
  *  :ref:`unpack_processed_geometry (asset: ProcessedAsset) : GltfScene <function-gltf_processed_unpack_processed_geometry_ProcessedAsset>`

.. _function-gltf_processed_process_gltf_GltfScene_string_ProcessingProfile:

.. das:function:: 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: * **raw** :  :ref:`GltfScene <struct-gltf_types-GltfScene>`

            * **source** : string

            * **profile** :  :ref:`ProcessingProfile <struct-gltf_processed-ProcessingProfile>`

.. _function-gltf_processed_process_primitive_GltfPrimitive_int_bool_bool:

.. das:function:: 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** :  :ref:`GltfPrimitive <struct-gltf_types-GltfPrimitive>`

            * **flags** : int

            * **encode** : bool

            * **optimize_order** : bool

.. _function-gltf_processed_processed_indices_ProcessedPrimitive:

.. das:function:: 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: * **p** :  :ref:`ProcessedPrimitive <struct-gltf_processed-ProcessedPrimitive>`

.. _function-gltf_processed_processed_stride_int:

.. das:function:: 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

.. _function-gltf_processed_processed_vertex_bytes_ProcessedPrimitive:

.. das:function:: processed_vertex_bytes(p: ProcessedPrimitive) : array<uint8>

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


:Arguments: * **p** :  :ref:`ProcessedPrimitive <struct-gltf_processed-ProcessedPrimitive>`

.. _function-gltf_processed_unpack_processed_geometry_ProcessedAsset:

.. das:function:: 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: * **asset** :  :ref:`ProcessedAsset <struct-gltf_processed-ProcessedAsset>`