## Native models

Add a `.glb` file, or a self-contained `.gltf` file, to the version. Declare it as an asset with `id`, `u` and `p`, like an image, but with no `w`, `h` or `t`. A `ty:16` layer whose `refId` names the asset draws the model. A `.gltf` has its buffers embedded as base64 `data:` URIs and its images in buffer views.

This example assumes you uploaded `models/product.glb`, a model about one unit across:

```json
{
  "v":"5.12.2","nm":"Product rotation","w":1080,"h":1080,"fr":30,"ip":0,"op":90,"ddd":0,
  "assets":[{"id":"product","u":"models/","p":"product.glb"}],
  "layers":[{
    "ty":16,"ind":1,"nm":"Product","refId":"product","ip":0,"op":90,"st":0,"sr":1,"bm":0,
    "ks":{
      "p":{"a":0,"k":[540,540,0]},"a":{"a":0,"k":[0,0,0]},"s":{"a":0,"k":[100,100,100]},
      "o":{"a":0,"k":100},"or":{"a":0,"k":[0,0,0]},
      "rx":{"a":0,"k":0},"ry":{"a":1,"k":[{"t":0,"s":[0]},{"t":90,"s":[360]}]},"rz":{"a":0,"k":0}
    }
  }]
}
```

- One glTF unit (one metre) is 512 composition pixels, times the layer's scale.
- The GLB's origin is the layer's own (0,0,0). With anchor `ks.a` at `[0,0,0]`, it lands on the layer's position. A nonzero anchor, in those pixels, is the pivot `ks.p` places. The engine does not recenter the model.
- glTF's up (+Y) points up the composition.
- Lighting is fixed: a built-in studio environment lights every model the same way. There are no lights, exposure or environment settings, and lights or cameras in the GLB are not used.
- The layer's 3D transforms move and turn the model, animated or static: three-component position, anchor and scale, `rx`, `ry`, `rz` and `or`. So does the composition camera. Without a camera layer, the default perspective camera shows the model, not an orthographic view.
- Each model layer draws in its own pass. Model layers don't hide each other, or 2D layers, by depth: they stack by `ind` like other layers. Put parts that must pass through each other in one GLB.
- A model layer takes its layer opacity, blend mode and track matte. It draws no effects or layer styles (`warnings`).
- Masks on a model layer may not apply. To clip a model, use a [track matte](#track-mattes), and render a frame to check.
- Each model asset loads once, however many layers show it, and takes one [mesh](#render-limits). Two asset ids naming one file load it twice. Its textures count toward the [texture limit](#textures).

### What the engine draws

| Part of the GLB | Drawn |
| --- | --- |
| Meshes | The triangle meshes of the default scene, with their node hierarchy. Without a default, the first scene draws, and a file with no scenes draws every root node. A node that repeats a mesh draws it again. Only triangle lists draw: points, lines, strips and fans are skipped. |
| Materials | Metallic-roughness: base color, metallic and roughness factors and textures, normal maps, occlusion, emissive color and texture (with `KHR_materials_emissive_strength`), `OPAQUE`, `MASK` and `BLEND` alpha, and double-sided materials |
| Transparency | `MASK` discards texels below the cutoff but keeps the alpha of the rest, so they draw partly transparent, not opaque. `BLEND` surfaces are not sorted back to front, so overlapping transparent parts can hide what is behind them. |
| Textures | Embedded PNG or JPEG images, read with `TEXCOORD_0`, linear filtering and mipmaps. The sampler's horizontal wrap applies in both directions: clamp-to-edge clamps, and any other wrap, or no sampler, repeats. |
| Texture coordinates | A texture that names another coordinate set still draws, with `TEXCOORD_0`. A primitive without `TEXCOORD_0` shows one texel of each texture. |
| Normals, tangents | From the file. A mesh without normals gets flat ones. Tangents come from the file only together with its normals, and are generated otherwise. |
| Animations, skins, morph targets | Not played: the model renders in the pose the file stores, without its default morph weights |
| Vertex colors, other texture coordinate sets, texture transforms, other optional extensions | Ignored |

The engine reads an image stored in a buffer view, in the GLB's binary chunk or in an embedded base64 buffer. The image's `mimeType` must be `image/png`, `image/jpeg` or absent. The engine decodes PNG, JPEG, BMP, TGA, PSD, PNM, Softimage PIC and Radiance HDR content.

A texture the engine cannot read is left out, and the model still renders. That covers an image with another `mimeType` or that is not valid, and an image given as a `data:` URI. It also covers an image the decoder cannot hold: over about 41.9 megapixels (such as 8192 × 8192), or about 21 for a 16-bit PNG. Nothing reports these, so check the textures before you add a GLB, and keep each at most 4096 pixels a side.

### Models Blitframe refuses

Blitframe checks a model when you add it, and refuses a GLB the engine cannot load:

- not a valid GLB container of glTF version 2 or later, a truncated GLB, or empty JSON
- a key repeated in one JSON object
- a buffer whose URI is not a base64 `data:` URI holding its size, or without a positive `byteLength`
- a buffer view outside its buffer, or a first buffer larger than the binary chunk
- an image linked by URI to another file, or by a `data:` URI that is not valid base64
- accessors outside their buffer view, or that break glTF's accessor type and sparse storage rules
- index values outside their primitive's vertices (or their sparse accessor's elements)
- index data that is interleaved, or not unsigned byte, short or int scalars
- a primitive `mode` above 6
- references to missing elements
- no meshes or nodes, or a mesh without primitives
- vertex attributes of one primitive with different counts
- primitives of one mesh with different morph target counts
- a morph target whose vertex count differs from its primitive's
- `targetNames` or default `weights` whose count differs from the morph target count
- an animation sampler whose output count does not match its input
- an animation sampler or channel missing its input, output, sampler or target, or a weights animation on a node without a mesh
- a node that contains itself or has two parents, or a scene root node that has a parent
- a required extension other than `KHR_materials_emissive_strength`
- no triangles to draw
- more than these limits:

| Resource | Limit |
| --- | --- |
| One GLB | 100 MB, with its JSON at most 8 MB and nested at most 64 deep (Blitframe's limits) |
| One `.gltf` | 8 MB |
| Drawn geometry | 22,369,621 vertices and 268,435,455 indices across the drawn scene, and 67,108,863 vertices in one primitive (the engine's limits). A node counts every time the scene reaches it, up to one draw per node and primitive in the file. A mesh without normals counts one vertex per index. |

### Edge cases

- A model layer without a text `refId`: `problems`. So is one whose `refId` names no asset, an asset without a file `p` (such as a precomposition), an asset whose `p` is a `data:` URI, or an asset that is not a `.glb` or `.gltf` file in the version (such as an image).
- A model the engine cannot load stops the render ([models Blitframe refuses](#models-blitframe-refuses)).
- With a repeated model `id`, the first declaration is used.
