Merge pull request #56 from CesiumGS/ext-mesh-features-revision

Splitting EXT_mesh_features into multiple extensions

extensions/2.0/Vendor/EXT_instance_features/README.md

@@ -0,0 +1,75 @@
+# EXT_instance_features
+
+## Contributors
+
+* Peter Gagliardi, Cesium
+* Sean Lilley, Cesium
+* Sam Suhag, Cesium
+* Don McCurdy, Independent
+* Marco Hutter, Cesium
+* Bao Tran, Cesium
+* Samuel Vargas, Cesium
+* Patrick Cozzi, Cesium
+
+## Status
+
+Draft
+
+## Dependencies
+
+Written against the glTF 2.0 specification. It depends on the [`EXT_mesh_gpu_instancing`](../EXT_mesh_gpu_instancing) extension. Each node that is extended with `EXT_instance_features` must also define an `EXT_mesh_gpu_instancing` extension object, and is invalid without this dependency.
+
+## Overview
+
+In most realtime 3D contexts, performance requirements demand minimizing the number of nodes and meshes in an asset. These requirements compete with interactivity, as applications may wish to merge static objects while still supporting interaction or inspection on those objects. A common performance optimizations is GPU instancing, using the `EXT_mesh_gpu_instancing` extension. But this does not allow to uniquely identify the instances that are created during rendering. 
+
+This extension defines a means of associating GPU instances that are created using the `EXT_mesh_gpu_instancing` extension with unique identifiers. These allow identifying the GPU instances as individual _features_, and are therefore referred to as _feature IDs_. These feature IDs are similar to the concept that is introduced in the [`EXT_mesh_features`](../EXT_mesh_features) extension. But instead of defining the feature IDs based on vertex attributes, the feature IDs are here defined using instance attributes. 
+
+### Feature ID by GPU Instance
+
+*Defined in [node.EXT_instance_features.schema.json](./schema/node.EXT_instance_features.schema.json).*
+
+Feature IDs may be assigned to individual GPU instances using an instance attribute, or generated implicitly by instance index.
+
+When the feature ID definition does not refer to an instance attribute, then the feature IDs that are assigned to the instances are equal to their index, in the range [0, count), where `count` is the `count` of the instance attribute accessors. When the feature ID definition refers to an instance attribute, then this attribute contains `count` feature ID values. Note that these values do not necessarily have to be distinct; this makes it possible to define _groups_ of instances that share the same identifier. 
+
+> **Example:** A node defining instances of mesh `0`, with each instance having a feature ID in the `_FEATURE_ID_0` instance attribute.
+>
+> ```jsonc
+> {
+>   "nodes": [
+>     {
+>       "mesh": 0,
+>       "extensions": {
+>         "EXT_mesh_gpu_instancing": {
+>           "attributes": {
+>             "TRANSLATION": 0,
+>             "ROTATION": 1,
+>             "SCALE": 2,
+>             "_FEATURE_ID_0": 3
+>           },
+>         },
+>         "EXT_instance_features": {
+>           "featureIds": [{
+>             "featureCount": 10,
+>             "attribute": 0
+>           }]
+>         }
+>       }
+>     }
+>   ]
+> }
+> ```
+
+## Optional vs. Required
+
+This extension is optional, meaning it should be placed in the `extensionsUsed` list, but not in the `extensionsRequired` list.
+
+## Schema
+
+* [node.EXT_instance_features.schema.json](./schema/node.EXT_instance_features.schema.json)
+
+## Revision History
+
+This extension was originally part of a the `EXT_mesh_features` proposal extension. The revision history of this extension can be found in the [common revision history of the 3D Tiles Next extensions](https://github.com/CesiumGS/3d-tiles/blob/main/next/REVISION_HISTORY.md).
+

extensions/2.0/Vendor/EXT_instance_features/schema/featureId.schema.json

@@ -0,0 +1,43 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "featureId.schema.json",
+    "title": "Feature ID in EXT_instance_features",
+    "type": "object",
+    "description": "Feature IDs stored in a GPU mesh instancing attribute",
+    "allOf": [
+        {
+            "$ref": "glTFProperty.schema.json"
+        }
+    ],
+    "properties": {
+        "featureCount": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "The number of unique features in the attribute."
+        },
+        "nullFeatureId": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "A value that indicates that no feature is associated with this instance."
+        },
+        "label": {
+            "type": "string",
+            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+            "description": "A label assigned to this feature ID set. Labels must be alphanumeric identifiers matching the regular expression `^[a-zA-Z_][a-zA-Z0-9_]*$`."
+        },
+        "attribute": {
+            "description": "An attribute containing feature IDs. When this is omitted, then the feature IDs are assigned to the GPU instances by their index.",
+            "$ref": "featureIdAttribute.schema.json"
+        },
+        "propertyTable": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "The index of the property table containing per-feature property values. Only applicable when using the `EXT_structural_metadata` extension."
+        },
+        "extensions": {},
+        "extras": {}
+    },
+    "required": [
+        "featureCount"
+    ]
+}

extensions/2.0/Vendor/EXT_instance_features/schema/featureIdAttribute.schema.json

@@ -0,0 +1,8 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "featureIdAttribute.schema.json",
+    "title": "Feature ID Attribute in EXT_instance_features",
+    "type": "integer",
+    "minimum": 0,
+    "description": "An integer value used to construct a string in the format `_FEATURE_ID_<set index>` which is a reference to a key in `EXT_mesh_gpu_instancing.attributes` dictionary (e.g. a value of `0` corresponds to `_FEATURE_ID_0`)."
+}

extensions/2.0/Vendor/EXT_instance_features/schema/node.EXT_instance_features.schema.json

@@ -0,0 +1,27 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "node.EXT_instance_features.schema.json",
+    "title": "EXT_instance_features glTF Node extension",
+    "type": "object",
+    "description": "An object describing per-instance feature IDs.",
+    "allOf": [
+        {
+            "$ref": "glTFProperty.schema.json"
+        }
+    ],
+    "properties": {
+        "featureIds": {
+            "type": "array",
+            "description": "An array of feature ID sets.",
+            "minProperties": 1,
+            "additionalProperties": {
+                "$ref": "featureId.schema.json"
+            }
+        },
+        "extensions": {},
+        "extras": {}
+    },
+    "required": [
+        "featureIds"
+    ]
+}