GLTFKit2

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, 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.

Usage

Using the Framework

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.

Loading Assets

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.

Interoperating with SceneKit

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:].

Status and Conformance

Below is a checklist of glTF features and their current level of support.

Status

• Import
• Export

Encodings

• JSON
• Binary (.glb)

Buffer Storage

• External references (buffer.uri)
• Base-64 encoded buffers

Well-Known Vertex Accessor Semantics

• POSITION
• NORMAL
• TANGENT
• TEXCOORD_0
• TEXCOORD_1
• COLOR_0
• JOINTS_0
• WEIGHTS_0

Primitive Types

• Points
• Lines
• Line Loop
• Line Strip
• Triangles
• Triangle Strip
• Triangle Fan

Images

• External image references (image.uri)
• Base-64 encoded images
• PNG
• JPEG
• TIFF

Materials

• 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

Samplers

• Wrap mode
• Minification/magnification filters
• Mipmaps

Cameras

• Perspective cameras
• Orthographic cameras

Morph Targets

• Morph targets

Animation

• Translation animations
• Rotation animations
• Scale animations
• Morph target weight animations
• Linear interpolation
• Discrete animations
• Cubic spline interpolation

Skinning

• Joint matrix calculation

Sparse Accessors

• Sparse accessors

Extensions

• KHR_draco_mesh_compression
• KHR_lights_punctual
• KHR_materials_clearcoat
• KHR_materials_ior
• 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.

Conformance

This implementation is known to be non-conforming to the glTF 2.0 specification and is under active development.

Contributing

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.

License

Copyright (c) 2021—2022 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.