GizStack
View .mdOpen in ChatGPTOpen in Claude

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.