-
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
Merged
pjcozzi
merged 50 commits into
KhronosGroup:master
from
fanzhanggoogle:KHR_mesh_compression
Feb 14, 2018
Merged
Changes from all commits
Commits
Show all changes
50 commits
Select commit
Hold shift + click to select a range
acfd558
Initial commit
fanzhanggoogle 6472e25
Finished most of the Readme
fanzhanggoogle 41432dc
Added json schema file
66dfde1
Finished the first version
eae186d
Fix style issue
3dff72b
Changed extension name
fanzhanggoogle 54db399
Removed support for multiple compression libraries
fanzhanggoogle 65e79d3
Added support for point cloud in the spec
fanzhanggoogle b132fa0
Fix
fanzhanggoogle 7c48fb7
Refined alternative option
fanzhanggoogle 007e570
Removed unused file
fanzhanggoogle 7e7ff5d
Changes on lexaknyazev's comment
fanzhanggoogle ca7c8ee
Fixes
fanzhanggoogle ddf534f
Renaming
fanzhanggoogle 1d4ab96
Fix
fanzhanggoogle 251452d
Address Patrick's comments
fanzhanggoogle 260534e
Added version property and description
fanzhanggoogle ea273be
Changed indicesCount to indexCount
fanzhanggoogle 198792f
grammar fix
fanzhanggoogle 5956b53
minor fix
fanzhanggoogle f60ff63
Removed indexCount and vertexCount
fanzhanggoogle 61bd686
Removed attributes in the extension
fanzhanggoogle 2c3a051
Define order of attributes
fanzhanggoogle 3c14401
Fix
fanzhanggoogle a502855
minor fix
fanzhanggoogle fba95f4
Merge branch 'master' into KHR_mesh_compression
fanzhanggoogle c765c2f
Added draco extension to extension README
fanzhanggoogle 0cd8f60
Fix for comments
fanzhanggoogle 6102695
Add fallback for loaders not support the extension.
fanzhanggoogle 63f07ee
Changed last paragraph about the fallback
fanzhanggoogle a8f4e06
Added support for gltf attribute types that are not defined in Draco
fanzhanggoogle d0d5fa8
Fixed comma
fanzhanggoogle 1da7ae2
Fix duplicate description
fanzhanggoogle 85673d4
fix nit and added 1) attributes in extension must be subset of attrib…
fanzhanggoogle 99b131c
Removed version property, specify draco bitstream version for the ext…
fanzhanggoogle 306e5bc
Refine conformance
fanzhanggoogle ae9c8d6
removed version in schema; removed alternative approach
fanzhanggoogle 9039f52
Force to consistently use attribute id to get data
fanzhanggoogle 0cdbd3c
Fix example
fanzhanggoogle d643d96
minor fix
fanzhanggoogle ae30e83
Removed point cloud.
fanzhanggoogle 2cba5c2
typo
fanzhanggoogle e71f0d8
Removed unused image
fanzhanggoogle e3cce40
Wording fix
fanzhanggoogle 66bfc6d
more wording fixes
fanzhanggoogle 734b3cb
more fixes
fanzhanggoogle e42d251
Change Draft to Complete
fanzhanggoogle 8e9a344
Change Conformance to Recommended Loader Process; change normative
fanzhanggoogle 1eba79a
Make conformance normative
fanzhanggoogle cb478d9
Merge branch 'master' into KHR_mesh_compression
pjcozzi File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
194 changes: 194 additions & 0 deletions
194
extensions/Khronos/KHR_draco_mesh_compression/README.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,194 @@ | ||
# 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 | ||
|
||
Complete | ||
|
||
## 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 bitstream version 2.2 (the entirety of this specification is normative and included in Scope)](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 | ||
|
||
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) | ||
|
||
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, | ||
}, | ||
"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 | ||
When using this extension, the `mode` of `primitive` must 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 (the entirety of this specification is normative and included in Scope)](schema/node.KHR_draco_mesh_compression.schema.json) | ||
|
||
## Conformance | ||
|
||
Below is the recommended 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)). | ||
* 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 | ||
|
||
*This section is non-normative.* | ||
|
||
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. |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
21 changes: 21 additions & 0 deletions
21
...ons/Khronos/KHR_draco_mesh_compression/schema/node.KHR_draco_mesh_compression.schema.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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" ] | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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