# gizlang/gltf

glTF data, independent from a renderer or application. The caller supplies bytes; this module never fetches assets.

```gizlang
import * as Gltf from "gizlang/gltf";
```

## Types

### `Document`

```gizlang
type Document = { json: Json; buffers: Vec<bytes>; }
```

A parsed glTF 2.0 asset and the buffers resolved by its host.

- `json`: `gizlang_json.Json`
- `buffers`: `Vec<bytes>`

### `Accessor`

```gizlang
type Accessor = { count: i64; width: i64; componentType: i64; normalized: bool; values: Vec<f64>; }
```

An accessor decoded to scalar values in element order. WIDTH is the scalar lane count of one element.

- `count`: `i64`
- `width`: `i64`
- `componentType`: `i64`
- `normalized`: `bool`
- `values`: `Vec<f64>`

### `Primitive`

```gizlang
type Primitive = { attributes: Map<string, Accessor>; indices: Vec<i64>; material: i64; mode: i64; targets: Vec<Map<string, Accessor>>; }
```

One mesh primitive; semantic names retain the standard glTF spelling.

- `attributes`: `_gizlang_sdk_collections.Map<string, gizlang_gltf.Accessor>`
- `indices`: `Vec<i64>`
- `material`: `i64`
- `mode`: `i64`
- `targets`: `Vec<_gizlang_sdk_collections.Map<string, gizlang_gltf.Accessor>>`

### `Node`

```gizlang
type Node = { local: Matrix4; children: Vec<i64>; mesh: i64; skin: i64; weights: Vec<f64>; name: string; }
```

A file's node data. Local transforms and hierarchy do not imply an ECS or another application state store.

- `local`: `gizlang_geometry.Matrix4`
- `children`: `Vec<i64>`
- `mesh`: `i64`
- `skin`: `i64`
- `weights`: `Vec<f64>`
- `name`: `string`

### `Skin`

```gizlang
type Skin = { joints: Vec<i64>; inverseBind: Vec<Matrix4>; skeleton: i64; }
```

A skin binds node transforms to mesh joints; inverse bind matrices use the shared graphics layout.

- `joints`: `Vec<i64>`
- `inverseBind`: `Vec<gizlang_geometry.Matrix4>`
- `skeleton`: `i64`

### `NodeChannel`

```gizlang
type NodeChannel = { node: i64; path: string; channel: Channel; }
```

A decoded channel and its glTF node target. Sampling is shared with non-game animation tools.

- `node`: `i64`
- `path`: `string`
- `channel`: `gizlang_animation.Channel`

### `TextureUse`

```gizlang
type TextureUse = { texture: i64; coordinates: i64; scale: f64; }
```

A texture use retains its UV set and scale. The application resolves the image through its existing asset graph.

- `texture`: `i64`
- `coordinates`: `i64`
- `scale`: `f64`

### `Material`

```gizlang
type Material = { color: Vec<f64>; metallic: f64; roughness: f64; emissive: Vec<f64>; alphaMode: string; alphaCutoff: f64; doubleSided: bool; baseTexture: TextureUse; metalRoughTexture: TextureUse; normalTexture: TextureUse; occlusionTexture: TextureUse; emissiveTexture: TextureUse; }
```

Standard metallic/roughness data in linear color; texture contents are not duplicated in material objects.

- `color`: `Vec<f64>`
- `metallic`: `f64`
- `roughness`: `f64`
- `emissive`: `Vec<f64>`
- `alphaMode`: `string`
- `alphaCutoff`: `f64`
- `doubleSided`: `bool`
- `baseTexture`: `gizlang_gltf.TextureUse`
- `metalRoughTexture`: `gizlang_gltf.TextureUse`
- `normalTexture`: `gizlang_gltf.TextureUse`
- `occlusionTexture`: `gizlang_gltf.TextureUse`
- `emissiveTexture`: `gizlang_gltf.TextureUse`

### `ImageSource`

```gizlang
type ImageSource = { index: i64; body: bytes; mime: string; }
```

Encoded image content, supplied by the app's existing asset resolver or an embedded GLB buffer view.

- `index`: `i64`
- `body`: `bytes`
- `mime`: `string`

### `Deformation`

```gizlang
type Deformation = { influences: Vec<Influence>; joints: i64; morphs: Vec<bytes>; }
```

Immutable deformation streams in the common compute renderer's layout.

- `influences`: `Vec<gizlang_meshdraw.Influence>`
- `joints`: `i64`
- `morphs`: `Vec<bytes>`

### `Blend`

```gizlang
type Blend = { channels: Vec<NodeChannel>; time: f64; weight: f64; }
```

A second clip that a pose blends in: its CHANNELS at TIME, by WEIGHT (0 is the first clip alone, 1 this one).

- `channels`: `Vec<gizlang_gltf.NodeChannel>`
- `time`: `f64`
- `weight`: `f64`

### `Fade`

```gizlang
type Fade = { clip: string; time: f64; weight: f64; }
```

A clip that a pose still shows by WEIGHT at TIME (seconds into it, looping), as Rig.palettes blends it.

- `clip`: `string`
- `time`: `f64`
- `weight`: `f64`

### `Rig`

```gizlang
class Rig { parts: Vec<Part>; clips: Vec<string> = []; private document: Document; private all: Vec<Node>; private skins: Vec<Skin | undefined>; private channels: Vec<Vec<NodeChannel>> = []; private lengths: Vec<f64> = []; constructor(document: Document, all: Vec<Node>, parts: Vec<Part>, skins: Vec<Skin | undefined>) throws string { this.document = document; this.all = all; this.parts = parts; this.skins = skins; const animations = document.json.field("animations"); const count = animations.kind === "null" ? 0: animations.list().length; for (const index of range(0, count)) { const named = animations.list()[index].field("name"); this.clips.push(named.kind === "null" || named.text() === "" ? `clip ${index }`: named.text()); const decoded = animation(document, index); this.channels.push(decoded); let last = 0.0; for (const channel of decoded) { last = Math.max(last, channel.channel.times[channel.channel.times.length-1]); } this.lengths.push(last); } } length(name: string): f64 throws string { return this.lengths[this.clip(name)]; } palettes(name: string, time: f64, from: Fade | undefined = undefined): Vec<Vec<Matrix4>> throws string { const at = this.clip(name); const blend: Blend | undefined = from === undefined ? undefined: { channels: this.channels[this.clip(from!.clip)], time: this.moment(this.clip(from!.clip), from!.time), weight: from!.weight }; const matrices = transforms(pose(this.document, this.all, this.channels[at], this.moment(at, time), blend)); let out: Vec<Vec<Matrix4>> = []; for (const bound of this.skins) { out.push(bound === undefined ? []: palette(bound!, matrices, identity())); } return out; } private moment(at: i64, time: f64): f64 { const length = this.lengths[at]; return length> 0.0 ? time-Math.floor(time/length)*length: 0.0; } private clip(name: string): i64 throws string { const at = this.clips.indexOf(name); if (at <0) { throw `No clip ${name }:  ${ this.clips.join(", ") }`; } return at; } }
```

A skinned, animated model: its parts for Stage.model, its clips by name, and the joint matrices of a moment of a
clip for Stage.pose. A rigid part keeps its rest pose.

- `parts`: `Vec<gizlang_meshdraw.Part>` — The parts, as Stage.model declares them (with maximum 1).
- `clips`: `Vec<string>` — The names of the clips; a clip without a name is `clip N`.
- `document`: `gizlang_gltf.Document`
- `all`: `Vec<gizlang_gltf.Node>`
- `skins`: `Vec<_gizlang_sdk_core.Option<gizlang_gltf.Skin>>`
- `channels`: `Vec<Vec<gizlang_gltf.NodeChannel>>`
- `lengths`: `Vec<f64>`

## Functions

### `load`

```gizlang
function load(bytes: bytes, resolve: (uri: string) => bytes throws string): Document throws string
```

Parses JSON glTF or GLB. RESOLVE supplies external buffer URIs through the application's existing asset graph.

Effects: fail, read, write, console, io, alloc.

### `accessor`

```gizlang
function accessor(document: Document, index: i64): Accessor throws string
```

Reads dense, interleaved, matrix-padded and sparse accessors with exact buffer bounds.

Effects: fail, read, write, alloc.

### `mesh`

```gizlang
function mesh(document: Document, index: i64): Vec<Primitive> throws string
```

Decodes a mesh's primitives, including skin attributes and morph deltas, without choosing a renderer layout.

Effects: fail, read, write, alloc.

### `packed`

```gizlang
function packed(primitive: Primitive): Geometry throws string
```

Packs a glTF triangle primitive into the shared graphics layout. The format layer owns this conversion.

Effects: fail, alloc.

### `deformation`

```gizlang
function deformation(primitive: Primitive, jointCount: i64): Deformation throws string
```

Packs four-joint influences and position/normal morphs. Extra influence sets are refused rather than discarded.

Effects: fail, alloc.

### `nodes`

```gizlang
function nodes(document: Document): Vec<Node> throws string
```

Decodes and validates the complete node hierarchy once, including disconnected nodes.

Effects: fail, alloc.

### `roots`

```gizlang
function roots(document: Document, scene: i64 = -1): Vec<i64> throws string
```

The selected scene's root nodes. A missing scene selects the file's default, then scene zero.

Effects: fail, alloc.

### `transforms`

```gizlang
function transforms(nodes: Vec<Node>): Vec<Matrix4> throws string
```

Derives world transforms from validated local data, with no renderer-specific scene tree.

Effects: fail, alloc.

### `skin`

```gizlang
function skin(document: Document, index: i64): Skin throws string
```

Decodes one skin with explicit joint identities and inverse bind matrices.

Effects: fail, read, write, alloc.

### `palette`

```gizlang
function palette(skin: Skin, transforms: Vec<Matrix4>, mesh: Matrix4): Vec<Matrix4> throws string
```

Derives joint matrices in the mesh node's local space, from the same posed node transforms used for rendering.

Effects: fail, alloc.

### `pose`

```gizlang
function pose(document: Document, base: Vec<Node>, channels: Vec<NodeChannel>, time: f64, blend: Blend | undefined = undefined): Vec<Node> throws string
```

Samples asset channels into a derived node pose, blended toward BLEND when there is one (translation and scale
mixed, rotation by the shorter way, weights mixed). The immutable document remains the source of untouched TRS lanes.

Effects: fail, read, write, alloc.

### `animation`

```gizlang
function animation(document: Document, index: i64): Vec<NodeChannel> throws string
```

Decodes node animation through the common keyframe sampler. Each node/path has one channel per animation.

Effects: fail, read, write, alloc.

### `material`

```gizlang
function material(document: Document, index: i64 = -1): Material throws string
```

Decodes standard PBR factors and texture references without allocating a GPU object.

Effects: fail, alloc.

### `image`

```gizlang
function image(document: Document, texture: i64, resolve: (uri: string) => bytes throws string): ImageSource throws string
```

Reads one texture's image bytes. No fetching, decoding, cache or GPU allocation is introduced here.

Effects: fail, read, write, console, io, alloc.

### `sampler`

```gizlang
function sampler(document: Document, texture: i64): Json throws string
```

Converts standard glTF filtering into the common WebGPU sampler descriptor.

Effects: fail, alloc.

### `model`

```gizlang
function model(path: string, read: (path: string) => bytes throws string): Vec<Part> throws string
```

The static parts of the glTF or GLB file at PATH, as a Stage draws them as one model: the triangles of its scene with
each node's transform applied, their materials and their maps. READ gives a file's bytes by its path; a URI in the
file is relative to PATH's folder. A model that bends and moves is a rig.

Effects: fail, read, write, console, io, alloc.

### `constructor`

```gizlang
constructor(document: Document, all: Vec<Node>, parts: Vec<Part>, skins: Vec<Skin | undefined>) throws string
```

The rig of DOCUMENT: its NODES, its PARTS and the SKINS that bend them, part by part (rig reads them).

Effects: fail, read, write, alloc.

### `rig`

```gizlang
function rig(path: string, read: (path: string) => bytes throws string): Rig throws string
```

The rig of the glTF or GLB file at PATH, read as model reads it.

Effects: fail, read, write, console, io, alloc.

## Methods

### `Rig.length`

```gizlang
length(name: string): f64 throws string
```

The length of clip NAME in seconds.

Effects: fail, read, alloc.

### `Rig.palettes`

```gizlang
palettes(name: string, time: f64, from: Fade | undefined = undefined): Vec<Vec<Matrix4>> throws string
```

Each part's joint matrices TIME seconds into clip NAME, which loops; a rigid part's list is empty. FROM is a clip
that the pose still shows by its weight, as a change of clip fades out the old one.

Effects: fail, read, write, alloc.

