GLTFKit2 is an efficient glTF loader and exporter for Objective-C and Swift.
This project is a spiritual successor of the GLTFKit project, with many of the same aims, but some notable differences. GLTFKit2:
- includes import and export (WIP), while GLTFKit was read-only.
- strives to be as interoperable as possible, with extensions for Model I/O, SceneKit, and QuickLook.
- tries to retain all of the information from the asset file, meaning extensions and extras are available to client code even if they are unrecognized by the loader.
- uses cgltf and JSMN internally to load the JSON portion of glTF files, which is more efficient than parsing with
NSJSONSerialization.
The GLTFKit2 Xcode project is completely self-contained and can be used to build a Cocoa framework for macOS. If you want to use GLTFKit2 as a framework, link to it and embed it in your target. You can also opt to include the source directly in your app target.
To load a glTF 2.0 model, import <GLTFKit2/GLTFKit2.h> and use the GLTFAsset class. Since assets can take a while to load, prefer to use the async loading methods.
Objective-C:
[GLTFAsset loadAssetWithURL:url
options:@{}
handler:^(float progress, GLTFAssetStatus status, GLTFAsset *asset, NSError *error, BOOL *stop)
{
// Check for completion and/or error, use asset if complete, etc.
}Swift:
GLTFAsset.load(with: url, options:[:]){(progress, status, maybeAsset, maybeError, _)in
// Check for completion and/or error, use asset if complete, etc.
}The URL must be a local file URL. Loading of remote assets and resources is not supported.
The framework can be used to easily transform glTF assets into SCNScenes to interoperate with SceneKit.
First, load the asset as shown above. Then, to get the default scene of a glTF asset, use the SCNScene class extension method +[SCNScene sceneWithGLTFAsset:].
GLTFKit2 supports meshes compressed with the Draco geometry compression library through a plugin system. To activate Draco decompression support, implement the GLTFDracoMeshDecompressor protocol in your target, then set the dracoDecompressorClassName property on GLTFAsset to the name of the conforming class. The framework will then use the supplied class to convert compressed mesh data into glTF primitives which are suitable for rendering. A sample Draco decompressor class is provided in the macOS GLTFViewer target. You are responsible for compiling and linking to the Draco library itself in your own target. If you would prefer not to compile the library yourself, consider using DracoSwift.
GLTFKit2 optionally supports the KHR_texture_basisu extension for loading KTX2 with Basis Universal textures via libktx. This repository contains a pre-built XCFramework with Universal binaries for macOS and iOS. If you wish to use KTX2 textures in your target, simply add GLTFKit2/deps/libktx/ktx.xcframework to the GLTFKit2 framework target, and it will automatically be detected and used to load KTX2 textures, whether embedded or stored externally in ktx2 files.
Below is a checklist of glTF features and their current level of support.
- Import
- Export
- JSON
- Binary (.glb)
- External references (
buffer.uri) - Base-64 encoded buffers
- POSITION
- NORMAL
- TANGENT
- TEXCOORD_0
- TEXCOORD_1
- COLOR_0
- JOINTS_0
- WEIGHTS_0
- Points
- Lines
- Line Loop
- Line Strip
- Triangles
- Triangle Strip
- Triangle Fan
- External image references (
image.uri) - Base-64 encoded images
- PNG
- JPEG
- TIFF
- Base color factor
- Metallic factor
- Roughness factor
- Emissive factor
- Base color map
- Metallic-roughness map
- Occlusion map
- Emissive map
- Normal texture scale
- Alpha mode
- Opaque alpha mode
- Mask alpha mode
- Blend alpha mode
- Double-sided materials
- Wrap mode
- Minification/magnification filters
- Mipmaps
- Perspective cameras
- Orthographic cameras
- Morph targets
- Translation animations
- Rotation animations
- Scale animations
- Morph target weight animations
- Linear interpolation
- Discrete animations
- Cubic spline interpolation
- Joint matrix calculation
- Sparse accessors
- EXT_mesh_gpu_instancing
- EXT_meshopt_compression
- KHR_draco_mesh_compression (via plug-in)
- KHR_emissive_strength
- KHR_lights_punctual
- KHR_materials_anisotropy
- KHR_materials_clearcoat
- KHR_materials_diffuse_transmission
- KHR_materials_dispersion
- KHR_materials_ior
- KHR_materials_iridescence
- KHR_materials_sheen
- KHR_materials_specular
- KHR_materials_transmission
- KHR_materials_unlit
- KHR_materials_variants
- KHR_materials_volume
- KHR_mesh_quantization
- KHR_texture_basisu
- KHR_texture_transform
- KHR_xmp_json_ld
Extension support indicates that an extension's features are available as first-class objects through the GLTFAsset API. Not all features are available after an asset is bridged to another framework (e.g. SceneKit) that does not have support for such features. In particular, no Apple-provided rendering engine supports transmission or volume rendering at this time.
This implementation is known to be non-conforming to the glTF 2.0 specification and is under active development.
Pull requests are welcome, but will be audited strictly in order to maintain code style. If you have any concerns about contributing, please raise an issue on Github so we can talk about it.
Copyright (c) 2021—2024 Warren Moore
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.