-
Notifications
You must be signed in to change notification settings - Fork 1.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
KHR_draco_mesh_compression #874
Changes from 44 commits
acfd558
6472e25
41432dc
66dfde1
eae186d
3dff72b
54db399
65e79d3
b132fa0
7c48fb7
007e570
7e7ff5d
ca7c8ee
ddf534f
1d4ab96
251452d
260534e
ea273be
198792f
5956b53
f60ff63
61bd686
2c3a051
3c14401
a502855
fba95f4
c765c2f
0cd8f60
6102695
63f07ee
a8f4e06
d0d5fa8
1da7ae2
85673d4
99b131c
306e5bc
ae9c8d6
9039f52
0cdbd3c
d643d96
ae30e83
2cba5c2
e71f0d8
e3cce40
66bfc6d
734b3cb
e42d251
8e9a344
1eba79a
cb478d9
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,192 @@ | ||
# KHR_draco_mesh_compression | ||
|
||
## Contributors | ||
|
||
* Fan Zhang, Google, <mailto:[email protected]> | ||
* Ondrej Stava, Google, <mailto:[email protected]> | ||
* Frank Galligan, Google, <mailto:[email protected]> | ||
* 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 | ||
|
||
## Dependencies | ||
|
||
Written against the glTF 2.0 spec. | ||
|
||
## Overview | ||
|
||
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. 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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Remove this "Draco geometry compression library could be used for There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done |
||
|
||
The following picture shows the structure of the schema update. | ||
|
||
**Figure 1**: Structure of geometry compression extension. | ||
![](figures/structure.png) | ||
|
||
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`. | ||
|
||
```javascript | ||
"extensionsUsed" : [ | ||
"KHR_draco_mesh_compression" | ||
] | ||
|
||
``` | ||
|
||
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 | ||
|
||
"mesh" : { | ||
"primitives" : [ | ||
{ | ||
"attributes" : { | ||
"POSITION" : 11, | ||
"NORMAL" : 12, | ||
"TEXCOORD_0" : 13, | ||
"WEIGHTS_0" : 14, | ||
"JOINTS_0" : 15, | ||
}, | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The attributes above are ignored when the extension is present, correct? Or do these accessors have some special meaning to the Draco extension? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. In practical, for an implementation of loader like ThreeJS, it might be OK to ignore the attributes. But it is preferred not to ignore There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. So I assume you mean that the primitive might list additional attributes here, beyond those encoded in the Draco buffer? If so, then let's clarify this example by changing
... in which case, a loader would be expected to load POSITION, NORMAL, and TEXCOORD_0 from the Draco buffer, and then to add TEXCOORD_1 from a traditional accessor. Alternatively, do we consider it valid to include POSITION in In previous comments, |
||
"indices" : 10, | ||
"mode" : 4 | ||
"extensions" : { | ||
"KHR_draco_mesh_compression" : { | ||
"bufferView" : 5, | ||
"attributes" : { | ||
"POSITION" : 0, | ||
"NORMAL" : 1, | ||
"TEXCOORD_0" : 2, | ||
"WEIGHTS_0" : 3, | ||
"JOINTS_0" : 4 | ||
}, | ||
} | ||
} | ||
}, | ||
] | ||
} | ||
|
||
"bufferViews" : [ | ||
// ... | ||
// bufferView of Id 5 | ||
{ | ||
"buffer" : 10, | ||
"byteOffset" : 1024, | ||
"byteLength" : 10000 | ||
} | ||
// ... | ||
} | ||
|
||
``` | ||
#### bufferView | ||
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 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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. When using this extension, the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done |
||
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: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It could be cool to try the latest wetzel (CesiumGS/wetzel#4) to generate reference doc to paste in here like the glTF spec has. |
||
|
||
* [extension property (normative)](schema/node.KHR_draco_mesh_compression.schema.json) `KHR_draco_mesh_compression` extensions object. | ||
|
||
## Conformance | ||
|
||
*This section is non-normative.* | ||
|
||
Below is the process when a loader encounters a glTF asset with the Draco extension set: | ||
|
||
* 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)). | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. " There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done |
||
* 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. | ||
|
||
## 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/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. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
{ | ||
"$schema": "http://json-schema.org/draft-04/schema", | ||
"title": "KHR_draco_mesh_compression extension", | ||
"type": "object", | ||
"properties": { | ||
"bufferView": { | ||
"allOf": [ { "$ref" : "glTFid.schema.json" } ], | ||
"description": "The index of the bufferView." | ||
}, | ||
"attributes": { | ||
"type": "object", | ||
"minProperties": 1, | ||
"additionalProperties": { | ||
"$ref": "glTFid.schema.json" | ||
}, | ||
"description": "A dictionary object, where each key corresponds to an attribute and its unique attribute id stored in the compressed geometry." | ||
} | ||
}, | ||
"additionalProperties": false, | ||
"required": [ "bufferView", "attributes" ] | ||
} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
All Khronos specifications should contain the standard Copyright Header:
https://www.khronos.org/members/login/groups/Agreements%20and%20Licenses/Open%20Source%20Repository%20Resources/Khronos%20Specification%20Copyright%20License%20Header%20V3%20May17.txt
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As the Draco extension is referring to significant external documents – namely the Bitstream specification we should also include, and be consistent with the additional header wording for normative clarity:
https://www.khronos.org/members/login/groups/Agreements%20and%20Licenses/Open%20Source%20Repository%20Resources/Khronos%20Copyright%20License%20Header%20Addition%20for%20NORMATIVE%20CLARITY%20Oct17.txt Note - this has some boiler plate that needs to be tweaked to fit the spec.
The key text in the header is:
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 by the "
Note
" icon or designated "Informative
"<replace/insert specific conventions for the specification here>.
And
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done