cl-gltf
2024-10-12
A library to parse and serialize the glTF file format.
Upstream URL
Author
Yukari Hafner <[email protected]>
Maintainer
Yukari Hafner <[email protected]>
License
zlib
## About cl-gltf
This library implements the glTF file format both for parsing and serialising, as well as several extensions to the specification. glTF is a pretty good format for 3D scene interchange and delivery.
## How To
For the purposes of this tutorial we'll assume the package ``org.shirakumo.fraf.gltf`` has the local nickname ``gltf``. After loading the library, you can parse a glTF or GLB file as follows:
:: common lisp
(gltf:with-gltf (gltf #p"my-model.gltf")
(describe gltf))
::
``describe`` will emit the full structure of the parsed glTF file. From there you can use the accessors from this package to traverse the structures and convert the information as you need.
Of particular importance are the ``accessor``s, which provide a convenient way to parse out the information from the raw underlying byte buffers that they index into. An ``accessor`` is a ``sequence``, so you can simply use ``length`` and ``elt`` to traverse the data.
However, note that cl-gltf makes no assumptions about a math library or anything of the sort, so by default it will parse the data out to vectors of the respective element type (usually floats). That buffer will also be shared between ``elt`` calls to avoid excessive consing. Thus, if you are just copying the data out of the buffers to another place, this should be ideal.
However, if you would like to customise the way the data is read out, such as to convert it into other structures automatically, you can do so. Either set the ``element-reader`` function on the accessor, or provide a specialised method on the ``construct-element-reader`` function. See the respective docstrings for more info.
## Supported Extensions
The following official extension specs are explicitly supported:
- AGI_articulations
- EXT_lights_image_based
- KHR_animation_pointer
- KHR_lights_punctual
- KHR_collision_shapes
- KHR_rigid_bodies
- KHR_texture_transform
- SHIRAKUMO_trial
- MSFT_lod
- MSFT_packing_occlusionRoughnessMetallic