KhronosGroup / KhronosGroup/glTF

Define conventions and best practices for naming and data layout in glTF extensions

Open
#2,311 6 comments 2 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
7.8k
Forks
1.2k
Avg merge
17h 26m
Merged PRs (30d)
5

Description

When designing a new glTF extension, it would be nice to have guidelines for how to structure the data "the glTF way". These guidelines would be helpful to everyone for both Khronos extensions and vendor extensions.

Let me give an example. Does Khronos recommend using a `"type"` string enum to describe the behavior of an object, or are boolean flags preferred? For example, [glTF cameras](https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_016_Cameras.md) are defined using `"type": "perspective"` or `"type": "orthographic"`. Is this the recommended way extensions should define types? What about `"isOrthographic"` or `"isPerspective"` booleans? Similarly, [KHR_lights_punctual](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_lights_punctual) uses `"type"`. Context: There is ongoing debate on whether physics body motion should have its behavior type defined with a string-based enum like `"type": "dynamic"` or `"type": "kinematic"`, or if it should use an `"isKinematic"` boolean. Since "not kinematic" isn't the same meaning as "dynamic", an enum makes sense to me.

Another example, type-specific data. From looking at glTF cameras, it seems like the glTF way is to combine a type enum with sub-JSON, like `{ "type": "perspective", "perspective": { ... } }`. However, I have seen other proposed layouts, including key-only `{ "perspective": { ... } }` and flat `{ "type": "perspective", ... }`. Which is preferred for new extensions?

Yet another example, extension name plurality. Do we want extension names to be singular, plural, or does it depend on the context? The current list of extensions are mixed. For example, we have extensions prefixed with `KHR_materials_` and `KHR_texture_`. This is a weird inconsistency, why not `KHR_material_` or `KHR_textures_`? There is no difference in usage, I looked at both `KHR_materials_sheen` and `KHR_texture_basisu`, each instance of the extension defines properties for only one thing (a material or a texture).

Last example, extension name prefixes. Do we want to group together related extensions with the same prefix? For example, `KHR_materials_`, `KHR_mesh_`, and `KHR_texture_`. The names of the physics extensions is currently an ongoing debate, I personally would like to see them all prefixed with `KHR_physics_`, but there is resistance to this.

To be clear, I am not suggesting that we rename or change existing ratified extensions, but I am suggesting to create guidelines to be consistent for all new extensions. It's better to have a guideline that all extension authors can follow rather than having debates about conventions for each extension. It's not productive to be stuck debating these minor details when we could instead agree on a guideline for all new extensions to follow.

---

The conventions and best practices for glTF extensions would have the following goals:

* Ensure that the data is laid out in a consistent way between extensions, so that extension implementers are not surprised when implementing a new extension.

* Ensure that data in an extension is designed with a similar level of flexibility as other extensions or glTF itself.

* Minimize the friction if an extension is moved into a new namespace, such as if Khronos adopts the extension. If the original spec used a boolean flag, and Khronos uses a type enum, that's more friction compared to if the original spec started out with the data formatted in a way that Khronos considers best practice for glTF.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the cited glTF camera tutorial and the extensions/2.0/Khronos/KHR_lights_punctual example, then compare the naming and data-layout patterns described in the issue. Done means producing agreed conventions and best practices for new glTF and vendor extensions without changing existing ratified extensions.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.