KHR_draco_mesh_compression

extensions/Khronos/KHR_draco_mesh_compression/README.md

@@ -8,6 +8,8 @@
 * Kai Ninomiya, Google, <mailto:[email protected]>
 * Patrick Cozzi, Cesium, [@pjcozzi](https://twitter.com/pjcozzi)
 
+Copyright (C) 2013-2017 The Khronos Group Inc. All Rights Reserved. glTF is a trademark of The Khronos Group Inc.
+See [Appendix](#appendix-full-khronos-copyright-statement) for full Khronos Copyright Statement.
 ## Status
 
 Draft
@@ -18,20 +20,29 @@ Written against the glTF 2.0 spec.
 
 ## Overview
 
-This extension defines a schema to use [Draco geometry compression](https://github.com/google/draco) libraries in glTF format. This allows glTF to support streaming compressed geometry data instead of the raw data. This extension specification is based on [Draco bitestream version 2.0](https://google.github.io/draco/spec/).
+This extension defines a schema to use [Draco geometry compression (non-normative)](https://github.com/google/draco) libraries in glTF format. This allows glTF to support streaming compressed geometry data instead of the raw data. This extension specification is based on [Draco bitestream version 2.2 (normative)](https://google.github.io/draco/spec/).
 
 The [conformance](#conformance) section specifies what an implementation must do when encountering this extension, and how the extension interacts with the attributes defined in the base specification.
 
 ## glTF Schema Updates
 
-Draco geometry compression library could be used for `primitive` by adding an `extension` property to a primitive, and defining its `KHR_draco_mesh_compression` property.
+Draco geometry compression library could be used for `primitive` by adding an `extension` property to a primitive, and defining its `KHR_draco_mesh_compression` property. If a `primitive` contains an `extension` property and the `extension` property defines its `KHR_draco_mesh_compression` property, then the Draco geometry compression must be used.
 
 The following picture shows the structure of the schema update. 
 
 **Figure 1**: Structure of geometry compression extension.
 ![](figures/structure.png)
 
-In general, we will use the extension to point to the buffer that contains the compressed data. One of the requirements is that a loader/engine should be able to load the glTF assets no matter it supports the extension or not. To achieve that, all the existing components of the glTF specification stays the same when the extension exists, so that a loader doesn't support decoding compressed assets could just ignore the extension.
+The Draco extension points to the `bufferView` that contains the compressed data.
+If the uncompressed version of the asset is not provided, then `KHR_draco_mesh_compression` must be added to `extensionRequired`.
+```javascript
+"extensionsRequired" : [
+    "KHR_draco_mesh_compression"
+]
+
+```
+If the `KHR_draco_mesh_compression` property is set in `extensionRequired` then the primitive must only contain the Draco compressed data.
+If a Draco compressed version of the asset is provided then `KHR_draco_mesh_compression` must be added to `extensionUsed`.
 
 Usage of the extension must be listed in the `extensionUsed`. 
 
@@ -42,8 +53,7 @@ Usage of the extension must be listed in the `extensionUsed`.
 
 ```
 
-The extension then could be used like the following, note that all other nodes stay the same
-except `primitives`:
+Below is an example of what a part of a glTF file my look like if the Draco extension is set. Note that all other nodes stay the same except `primitives`:
 
 ```javascript
 
@@ -87,52 +97,96 @@ except `primitives`:
 }
 
 ```
-We will explain each of the property in the following sections.
 #### bufferView
-The `bufferView` property points to the buffer containing compressed data. The data should be passed to a mesh decoder and decompressed to a
-mesh.
+The `bufferView` property points to the buffer containing compressed data. The data must be passed to a mesh decoder and decompressed to a mesh.
 
 ### attributes
-`attributes` defines the attributes stored in the decompressed geometry. E.g, in the example above, `POSITION`, `NORMAL`, `TEXCOORD_0`, `WEIGHTS_0` and `JOINTS_0`. Each attribute is associated with an attribute id which is its unique id in the compressed data. The `attributes` defined in the extension must be a subset of the attributes of the primitive. To request an attribute, loaders should be able to use the correspondent attribute id specified in the `attributes` to get the attribute from the compressed data.
+`attributes` defines the attributes stored in the decompressed geometry. E.g, in the example above, `POSITION`, `NORMAL`, `TEXCOORD_0`, `WEIGHTS_0` and `JOINTS_0`. Each attribute is associated with an attribute id which is its unique id in the compressed data. The `attributes` defined in the extension must be a subset of the attributes of the primitive. To request an attribute, loaders must be able to use the correspondent attribute id specified in the `attributes` to get the attribute from the compressed data.
 
 #### Restrictions on geometry type
-When using this extension, the `mode` of `primitive` could only be one of `TRIANGLES` and `TRIANGLE_STRIP` and the mesh data will be decoded accordingly.
+When using this extension, the `mode` of `primitive` could be either `TRIANGLES` or `TRIANGLE_STRIP` and the mesh data will be decoded accordingly.
 
 ### JSON Schema
 
 For full details on the `KHR_draco_mesh_compression` extension properties, see the schema:
 
-* [extension property](schema/node.KHR_draco_mesh_compression.schema.json) `KHR_draco_mesh_compression` extensions object.
+* [extension property (normative)](schema/node.KHR_draco_mesh_compression.schema.json) `KHR_draco_mesh_compression` extensions object.
 
 ## Conformance
 
-To process this extension, there are some changes need to be made in loading a glTF asset.
-* If `KHR_draco_mesh_compression` is in `extensionsRequired` then the loader must support the extension or it will fail loading the assets.
-* If `KHR_draco_mesh_compression` is in `extensionsUsed` but not `extensionsRequired`:
-    * Check if the loader supports the extension. If not, then load the glTF asset ignoring the compression extension in `primitive`.
-    * If the loader supports the extension, then process the extension and ignore the attributes and indices of the primitive that are contained in the extension.
-* When encountering a `primitive` with the extension the first time, you must process the extension first. Get the data from the pointed `bufferView` in the extension and decompress the data to a geometry of a specific format, e.g. Draco geometry.
-* Then, process `attributes` and `indices` properties of the `primitive`. When loading each `accessor`, go to the previously decoded geometry in the `primitive` to get indices and attributes data. A loader could use the decompressed data to overwrite `accessors` or render the decompressed geometry directly (e.g. ThreeJS).
+*This section is non-normative.*
 
-It is pretty straightforward for top-down loading of a glTF asset, e.g. only
-decompress the geometry data when a `primitive` is met for the first time. However, for
-bottom-up loading, loading `accessor` before `primitive` will not get the data. It could only be handled when processing its parent `primitive`. This is based on the consideration that it will rarely happen that
-loading an `accessor` without knowing its parent `primitive`. And it should be
-easy enough to change the loader to ignore `accessor` without `bufferView` in glTF 2.0. But we are
-definitely open to change this if there actually are some use cases that require
-loading `accessor` independently. 
+Below is the process when a loader encounters a glTF asset with the Draco extension set:
 
-The extension provides compressed alternatives to one or more of a primitive's uncompressed attributes. A loader may choose to use the uncompressed attributes instead — when the extension is not supported, or for other reasons. When using compressed Draco data, the corresponding uncompressed attributes defined by the primitive should be ignored. If additional uncompressed attributes are defined by the primitive, but are not provided by the Draco extension, the loader must proceed to use these additional attributes as usual.
+* If `KHR_draco_mesh_compression` is in `extensionRequired` and the loader does not support the Draco extension, then the loader must fail loading the asset.
+* If the loader does not support the Draco extension and `KHR_draco_mesh_compression` is not in `extensionRequired`, then load the glTF asset ignoring `KHR_draco_mesh_compression` in `primitive`.
+* If the loader does support the Draco extension, but will not process `KHR_draco_mesh_compression`, then the loader must load the glTF asset ignoring `KHR_draco_mesh_compression` in `primitive`.
+* If the loader does support the Draco extension, and will process `KHR_draco_mesh_compression` then:
+    * The loader must process `KHR_draco_mesh_compression` first. The loader must get the data from `KHR_draco_mesh_compression`'s `bufferView` property and decompress the data using a Draco decoder to a Draco geometry.
+    * Then the loader must process `attributes` and `indices` properties` of the `primitive`. When loading each `accessor`, you must ignore the `bufferView` and go to the previously decoded Draco geometry in the `primitive` to get the data of indices and attributes. A loader must use the decompressed data to fill the `accessors` or render the decompressed Draco geometry directly (e.g. [ThreeJS (non-normative)](https://github.com/mrdoob/three.js/blob/dev/examples/js/loaders/draco/DRACOLoader.js)).
+    * If additional attributes are defined in `primitive`'s `attributes`, but not defined in `KHR_draco_mesh_compression`'s `attributes`, then the loader must process the additional attributes as usual.
 
 * Implementation note: To prevent transmission of redundant data, exporters should generally write compressed Draco data into a separate buffer from the uncompressed fallback, and shared data into a third buffer. Loaders may then optimize to request only the necessary buffers.
 
-If the uncompressed version of asset is not provided for the fallback described above, then the extension must be added to `extensionsRequired` so that the loaders/engines don't support the extension could report failure.
-
 ## Resources
 
+*This section is non-normative.*
+
 * [Draco Open Source Library](https://github.com/google/draco)
 * [ThreeJS
-  Loader](https://github.com/mrdoob/three.js/blob/dev/examples/js/loaders/DRACOLoader.js)
+  Loader](https://github.com/mrdoob/three.js/blob/dev/examples/js/loaders/draco/DRACOLoader.js)
   and
   [example](https://github.com/mrdoob/three.js/blob/dev/examples/webgl_loader_draco.html)
 
+## Appendix: Full Khronos Copyright Statement
+
+Copyright 2013-2017 The Khronos Group Inc. 
+
+Some parts of this Specification are purely informative and do not define requirements
+necessary for compliance and so are outside the Scope of this Specification. These
+parts of the Specification are marked as being non-normative, or identified as 
+**Implementation Notes**.
+
+Where this Specification includes normative references to external documents, only the
+specifically identified sections and functionality of those external documents are in
+Scope. Requirements defined by external documents not created by Khronos may contain
+contributions from non-members of Khronos not covered by the Khronos Intellectual
+Property Rights Policy.
+
+This specification is protected by copyright laws and contains material proprietary 
+to Khronos. Except as described by these terms, it or any components 
+may not be reproduced, republished, distributed, transmitted, displayed, broadcast 
+or otherwise exploited in any manner without the express prior written permission 
+of Khronos. 
+
+This specification has been created under the Khronos Intellectual Property Rights 
+Policy, which is Attachment A of the Khronos Group Membership Agreement available at
+www.khronos.org/files/member_agreement.pdf. Khronos grants a conditional 
+copyright license to use and reproduce the unmodified specification for any purpose, 
+without fee or royalty, EXCEPT no licenses to any patent, trademark or other 
+intellectual property rights are granted under these terms. Parties desiring to 
+implement the specification and make use of Khronos trademarks in relation to that 
+implementation, and receive reciprocal patent license protection under the Khronos 
+IP Policy must become Adopters and confirm the implementation as conformant under 
+the process defined by Khronos for this specification; 
+see https://www.khronos.org/adopters.
+
+Khronos makes no, and expressly disclaims any, representations or warranties, 
+express or implied, regarding this specification, including, without limitation: 
+merchantability, fitness for a particular purpose, non-infringement of any 
+intellectual property, correctness, accuracy, completeness, timeliness, and 
+reliability. Under no circumstances will Khronos, or any of its Promoters, 
+Contributors or Members, or their respective partners, officers, directors, 
+employees, agents or representatives be liable for any damages, whether direct, 
+indirect, special or consequential damages for lost revenues, lost profits, or 
+otherwise, arising from or in connection with these materials.
+
+Vulkan is a registered trademark and Khronos, OpenXR, SPIR, SPIR-V, SYCL, WebGL, 
+WebCL, OpenVX, OpenVG, EGL, COLLADA, glTF, NNEF, OpenKODE, OpenKCAM, StreamInput, 
+OpenWF, OpenSL ES, OpenMAX, OpenMAX AL, OpenMAX IL, OpenMAX DL, OpenML and DevU are 
+trademarks of The Khronos Group Inc. ASTC is a trademark of ARM Holdings PLC, 
+OpenCL is a trademark of Apple Inc. and OpenGL and OpenML are registered trademarks 
+and the OpenGL ES and OpenGL SC logos are trademarks of Silicon Graphics 
+International used under license by Khronos. All other product names, trademarks, 
+and/or company names are used solely for identification and belong to their 
+respective owners.