Replace vertex instances with bindings

Author: aaronfranke

specification/parts/data.md

@@ -116,7 +116,7 @@ The component type SHOULD be some kind of primitive numeric data type, such as f
 - `"uint64"`: 64-bit or 8-byte unsigned integer.
 - `"uint128"`: 128-bit or 16-byte unsigned integer.
 
-Support for reading `"float32"`, `"int32"`, and `"uint32"` is REQUIRED, due to how common they are. For the remaining types, they are defined, but not required. 8-bit integers and 16-bit integers are very highly recommended, and all 64-bit types are highly recommended. Implementations MAY support only a subset of these types. If an implementation does not want to support `"float8"`, `"float128"`, `"int128"`, or any other type, the implementation MAY skip this accessor, failing to load any objects that use it, or MAY refuse to load the entire file.
+Support for reading `"float32"`, `"int32"`, and `"uint32"` is REQUIRED, due to how common they are. For the remaining types, they are defined, but not required. 8-bit integers and 16-bit integers are very highly recommended, 16-bit floats are highly recommended, and all 64-bit types are recommended. Implementations MAY support only a subset of these types. If an implementation does not want to support `"float8"`, `"float128"`, `"int128"`, or any other type, the implementation MAY skip this accessor, failing to load any objects that use it, or MAY refuse to load the entire file.
 
 Implementations MAY truncate or round types to fit into a supported type. For example, it is allowed to read `"float64"` components which get converted to `"float32"` at import time, rounding the values to fit into the smaller type. Accessor component types only define how the data is stored in the file, not how it is represented in memory at runtime, and do not impose restrictions on mathematical operations or other usage.
 

specification/parts/mesh/bindings.md

@@ -0,0 +1,90 @@
+# G4MF Mesh Surface Bindings
+
+## Overview
+
+Mesh surface bindings define how data is associated with mesh elements such as vertices, edges, and simplexes. For example, the tetrahedra of a 4D mesh surface may have texture map coordinates, normals, colors, or other data associated with each corner of the tetrahedra.
+
+Bindings define an array of data stored in `"values"`. This array is then sampled by indices corresponding to specific mesh elements. For example, the `"simplexes"` property allows associating data with each corner of the simplex cells, the `"perSimplex"` property allows associating one value per entire simplex cell, the `"vertices"` property allows associating data with the shared vertices of the mesh, `"geometry"` allows associating data with polytope elements or their decompositions, and so on. The binding may contain any combination of these index properties, including one or multiple at once. Having none of them would be useless, but this is allowed, in case an extension defines another way to index into the values.
+
+## Example
+
+The following example defines.
+
+## Mesh Surface Binding Properties
+
+| Property       | Type       | Description                                                                            | Default                 |
+| -------------- | ---------- | -------------------------------------------------------------------------------------- | ----------------------- |
+| **edges**      | `integer`  | The index of the accessor for edge indices into the binding's values.                  | No edge indices.        |
+| **geometry**   | `object[]` | An array of geometry decomposition objects for associating values with geometry items. | No geometry indices.    |
+| **perEdge**    | `integer`  | The index of the accessor for per-edge indices into the binding's values.              | No per-edge indices.    |
+| **perSimplex** | `integer`  | The index of the accessor for per-simplex indices into the binding's values.           | No per-simplex indices. |
+| **simplexes**  | `integer`  | The index of the accessor for simplex indices into the binding's values.               | No simplex indices.     |
+| **values**     | `integer`  | The index of the accessor that contains the values associated with this binding.       | Required, no default.   |
+| **vertices**   | `integer`  | The index of the accessor for vertex indices into the binding's values.                | No vertex indices.      |
+
+### Edges
+
+The `"edges"` property is an integer index that references an accessor containing the bindings corresponding to edge indices for this surface. If not defined, the surface does not have explicit edges, but edges may be calculated from the simplexes if needed for visibility.
+
+### Geometry
+
+The `"geometry"` property is an array of geometry decomposition objects that define how binding values are associated with specific geometry's decomposed polytope elements of the mesh surface. Usually, this will have one item referring to the corners (vertices) of boundary geometry items, meaning for a 3D mesh surface, `index` will be set to 0 (the 2D faces), and for a 4D mesh surface, `index` will be set to 1 (the 3D cells).
+
+For more information, see [Geometry Decomposition](#geometry-decomposition) below.
+
+### Per Edge
+
+The `"perEdge"` property is an integer index that references an accessor containing the bindings corresponding to each edge of the mesh surface. If not defined, the surface does not have per-edge bindings.
+
+### Per Simplex
+
+The `"perSimplex"` property is an integer index that references an accessor containing the bindings corresponding to each simplex cell of the mesh surface. If not defined, the surface does not have per-simplex bindings.
+
+### Simplexes
+
+The `"simplexes"` property is an integer index that references an accessor containing the bindings corresponding to the simplexes of the mesh surface. If not defined, the surface does not have simplex bindings.
+
+### Values
+
+The `"values"` property is an integer index that references an accessor containing the values associated with this binding. This property is required and has no default value.
+
+The type and structure of the values depend on the specific use case of the binding. For example, the texture mapping of a 3D mesh surface would typically use a floating-point accessor with a `vectorSize` of 2 or 3, the texture mapping of a 4D mesh surface would typically use a floating-point accessor with a `vectorSize` of 3 or 4, the vertex normals of a 5D mesh would use a floating-point accessor with a `vectorSize` of 5, and so on.
+
+### Vertices
+
+The `"vertices"` property is an integer index that references an accessor containing the bindings corresponding to the vertices shared between all mesh surfaces. If not defined, the surface does not have per-vertex bindings.
+
+## Geometry Decomposition
+
+The geometry decomposition objects in the `"geometry"` property define how binding values are associated with specific geometry's decomposed polytope elements.
+
+| Property      | Type      | Description                                                                    | Default               |
+| ------------- | --------- | ------------------------------------------------------------------------------ | --------------------- |
+| **accessor**  | `integer` | The index of the accessor that contains indices into this binding's values.    | Required, no default. |
+| **dimension** | `integer` | The dimensional level to decompose to. MUST NOT be greater than `index` + 2.   | `0` (0D vertices)     |
+| **index**     | `integer` | The index into the mesh surface's geometry array that this binding references. | Required, no default. |
+
+### Accessor
+
+The `"accessor"` property is an integer index that references an accessor containing indices into this binding's values. Each element corresponds to a decomposed element at the specified dimension. This property is required and has no default value.
+
+### Dimension
+
+The `"dimension"` property is an integer that defines the dimensional level to decompose to. This property is optional and defaults to 0.
+
+When dimension is set to 0, this means to decompose down to vertices (corners), and each item in the accessor corresponds to a corner of the geometry item. When dimension is set to 1, this means to decompose down to edges, and each item in the accessor corresponds to an edge of the geometry item. When dimension is set to 2, this means to decompose down to polygons, and each item in the accessor corresponds to a polygon of the geometry item, and so on.
+
+The value MUST NOT be greater than `index` + 2, because a geometry item at index N has dimension N+2, and it cannot be decomposed into elements of higher dimension than itself. For example, a 3D polyhedron (geometry index 1, dimension 3) can be decomposed into vertices (0), edges (1), polygons (2), or itself (3), but not into 4D polytopes. In other words, a cube contains vertices, edges, faces, and one volume (itself), but zero hypercubes or beyond.
+
+For example, to store per-corner data for 3D mesh faces (geometry index 0), set `"index"` to 0 and `"dimension"` to 0. To store one value per entire face, set `"index"` to 0 and `"dimension"` to 2.
+
+### Index
+
+The `"index"` property is an integer that defines the index into the mesh surface's geometry array that this binding references. This property is required and has no default value.
+
+For example, if binding data to the corners of polygons, such as the boundary of a 3D mesh surface or the volume of a 2D mesh interior, `index` would be set to 0. If binding data to the corners of polyhedra, such as the boundary of a 4D mesh surface or the volume of a 3D mesh interior, `index` would be set to 1. If binding data to the corners of 4D polytopes, such as the boundary of a 5D mesh surface or the volume of a 4D mesh interior, `index` would be set to 2, and so on.
+
+## JSON Schema
+
+- See [g4mf.mesh.surface.binding.schema.json](../../schema/mesh/g4mf.mesh.surface.binding.schema.json) for the mesh surface binding properties JSON schema.
+- See [g4mf.mesh.surface.binding.geometry.schema.json](../../schema/mesh/g4mf.mesh.surface.binding.geometry.schema.json) for the geometry decomposition properties JSON schema.

specification/parts/mesh/blend.md

@@ -31,49 +31,31 @@ In addition to the below listed properties, blend shapes are highly recommended
 
 ## Blend Shape Properties
 
-| Property               | Type     | Description                                                               | Default          |
-| ---------------------- | -------- | ------------------------------------------------------------------------- | ---------------- |
-| **normal**             | `object` | The offset or displacement of the per-vertex-instance normals.            | No displacement. |
-| **position**           | `object` | The offset or displacement of the vertex positions.                       | No displacement. |
-| **textureMap**         | `object` | The offset or displacement of the per-vertex-instance texture map.        | No displacement. |
-| **topologyNormal**     | `object` | Like `"normal"` but for the per-topology-vertex-instance normals.         | No displacement. |
-| **topologyTextureMap** | `object` | Like `"textureMap"` but for the per-topology-vertex-instance texture map. | No displacement. |
+| Property       | Type     | Description                                                      | Default          |
+| -------------- | -------- | ---------------------------------------------------------------- | ---------------- |
+| **normal**     | `object` | The offset or displacement of the normal direction values.       | No displacement. |
+| **position**   | `object` | The offset or displacement of the vertex positions.              | No displacement. |
+| **textureMap** | `object` | The offset or displacement of the texture map coordinate values. | No displacement. |
 
 All of these properties use the [Blend Shape Target](#blend-shape-target-properties) schema to contain the indices and offsets.
 
 ### Normal
 
-The `"normal"` property is an object that defines the offset or displacement of the per-vertex-instance normals for the blend shape. This property is optional and defaults to no displacement.
+The `"normal"` property is an object that defines the offset or displacement of the normal direction values for the blend shape. This property is optional and defaults to no displacement.
 
-If the mesh has multiple surfaces, the blend shape target indices are a combination of the per-vertex-instance indices for all surfaces in the mesh. For example, for a 4D mesh with two surfaces, the first with 10 tetrahedral simplex cells and the second with 20 tetrahedral simplex cells, indices 0 to 39 refer to the first surface's vertex indices, and indices 40 to 119 refer to the second surface's vertex indices.
+For meshes with multiple surfaces, the target indices refer to a combination of all normal value accessors for all surfaces in the mesh. For example, if surface 0 has 5 normal values, then surface 1's normal values are referenced starting from the number 5 in the target indices.
 
-Normals MUST be re-normalized after applying all blend shapes for a mesh.
+Normals MUST be re-normalized before rendering after applying all blend shapes for a mesh.
 
 ### Position
 
 The `"position"` property is an object that defines the offset or displacement of the vertex positions for the blend shape relative to the base mesh's `vertices` property. This property is optional and defaults to no displacement.
 
 ### Texture Map
 
-The `"textureMap"` property is an object that defines the offset or displacement of the per-vertex-instance texture space coordinates for the blend shape. This property is optional and defaults to no displacement.
+The `"textureMap"` property is an object that defines the offset or displacement of the texture map's texture space coordinate values for the blend shape. This property is optional and defaults to no displacement.
 
-If the mesh has multiple surfaces, the blend shape target indices are a combination of the per-vertex-instance indices for all surfaces in the mesh. For example, for a 4D mesh with two surfaces, the first with 10 tetrahedral simplex cells and the second with 20 tetrahedral simplex cells, indices 0 to 39 refer to the first surface's vertex indices, and indices 40 to 119 refer to the second surface's vertex indices.
-
-### Topology Normal
-
-The `"topologyNormal"` property is an object that defines the offset or displacement of the per-topology-vertex-instance normals for the blend shape. This property is optional and defaults to no displacement.
-
-If the mesh has multiple surfaces, the blend shape target indices are a combination of the per-topology-vertex-instance indices for all boundary geometry items in all mesh surfaces. For example, for a 4D mesh with two surfaces, the first with 10 cubic cells and the second with 20 cubic cells, indices 0 to 79 refer to the first surface's topology vertex indices, and indices 80 to 239 refer to the second surface's topology vertex indices.
-
-Normals MUST be re-normalized after applying all blend shapes for a mesh.
-
-### Topology Texture Map
-
-The `"topologyTextureMap"` property is an object that defines the offset or displacement of the per-topology-vertex-instance texture space coordinates for the blend shape. This property is optional and defaults to no displacement.
-
-If the mesh has multiple surfaces, the blend shape target indices are a combination of the per-topology-vertex-instance indices for all boundary geometry items in all mesh surfaces. For example, for a 4D mesh with two surfaces, the first with 10 cubic cells and the second with 20 cubic cells, indices 0 to 79 refer to the first surface's topology vertex indices, and indices 80 to 239 refer to the second surface's topology vertex indices.
-
-This property may only be used when at least one mesh surface has the `"
+For meshes with multiple surfaces, the target indices refer to a combination of all texture map value accessors for all surfaces in the mesh. For example, if surface 0 has 5 texture map values, then surface 1's texture map values are referenced starting from the number 5 in the target indices.
 
 ## Blend Shape Target Properties
 
@@ -86,7 +68,7 @@ This property may only be used when at least one mesh surface has the `"
 
 The `"indices"` property is an integer that defines the index of the accessor that contains the indices for the mesh deformation blend shape morph target. This property is required and has no default value.
 
-This is a reference to an accessor in the G4MF file's document-level `"accessors"` array. The accessor MUST be of an unsigned integer component type, and MUST have the `"vectorSize"` property undefined or set to its default value of 1. Each index in this accessor corresponds to an item in the mesh that the blend shape morph target applies to, such as a vertex position, per-vertex-instance normal, or another attribute, and MUST NOT exceed the number of items in the targeted accessor.
+This is a reference to an accessor in the G4MF file's document-level `"accessors"` array. The accessor MUST be of an unsigned integer component type, and MUST have the `"vectorSize"` property undefined or set to its default value of 1. Each index in this accessor corresponds to an item in the mesh that the blend shape morph target applies to, such as a vertex position, normal direction value, or another attribute, and MUST NOT exceed the number of items in the targeted accessor.
 
 ### Offsets