Skip to content
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
merged 50 commits into from
Feb 14, 2018
Merged
Show file tree
Hide file tree
Changes from 44 commits
Commits
Show all changes
50 commits
Select commit Hold shift + click to select a range
acfd558
Initial commit
fanzhanggoogle Mar 10, 2017
6472e25
Finished most of the Readme
fanzhanggoogle Mar 10, 2017
41432dc
Added json schema file
Mar 10, 2017
66dfde1
Finished the first version
Mar 10, 2017
eae186d
Fix style issue
Mar 10, 2017
3dff72b
Changed extension name
fanzhanggoogle Mar 13, 2017
54db399
Removed support for multiple compression libraries
fanzhanggoogle Mar 13, 2017
65e79d3
Added support for point cloud in the spec
fanzhanggoogle Mar 13, 2017
b132fa0
Fix
fanzhanggoogle Mar 13, 2017
7c48fb7
Refined alternative option
fanzhanggoogle Mar 13, 2017
007e570
Removed unused file
fanzhanggoogle Mar 13, 2017
7e7ff5d
Changes on lexaknyazev's comment
fanzhanggoogle Mar 14, 2017
ca7c8ee
Fixes
fanzhanggoogle Mar 14, 2017
ddf534f
Renaming
fanzhanggoogle Mar 14, 2017
1d4ab96
Fix
fanzhanggoogle Mar 14, 2017
251452d
Address Patrick's comments
fanzhanggoogle Mar 14, 2017
260534e
Added version property and description
fanzhanggoogle Mar 14, 2017
ea273be
Changed indicesCount to indexCount
fanzhanggoogle Mar 15, 2017
198792f
grammar fix
fanzhanggoogle Mar 15, 2017
5956b53
minor fix
fanzhanggoogle Mar 19, 2017
f60ff63
Removed indexCount and vertexCount
fanzhanggoogle Apr 19, 2017
61bd686
Removed attributes in the extension
fanzhanggoogle Apr 20, 2017
2c3a051
Define order of attributes
fanzhanggoogle Apr 24, 2017
3c14401
Fix
fanzhanggoogle Apr 24, 2017
a502855
minor fix
fanzhanggoogle Apr 24, 2017
fba95f4
Merge branch 'master' into KHR_mesh_compression
fanzhanggoogle Jul 27, 2017
c765c2f
Added draco extension to extension README
fanzhanggoogle Jul 27, 2017
0cd8f60
Fix for comments
fanzhanggoogle Aug 8, 2017
6102695
Add fallback for loaders not support the extension.
fanzhanggoogle Aug 9, 2017
63f07ee
Changed last paragraph about the fallback
fanzhanggoogle Aug 9, 2017
a8f4e06
Added support for gltf attribute types that are not defined in Draco
fanzhanggoogle Aug 10, 2017
d0d5fa8
Fixed comma
fanzhanggoogle Aug 10, 2017
1da7ae2
Fix duplicate description
fanzhanggoogle Aug 10, 2017
85673d4
fix nit and added 1) attributes in extension must be subset of attrib…
fanzhanggoogle Aug 10, 2017
99b131c
Removed version property, specify draco bitstream version for the ext…
fanzhanggoogle Aug 10, 2017
306e5bc
Refine conformance
fanzhanggoogle Aug 10, 2017
ae9c8d6
removed version in schema; removed alternative approach
fanzhanggoogle Aug 16, 2017
9039f52
Force to consistently use attribute id to get data
fanzhanggoogle Aug 16, 2017
0cdbd3c
Fix example
fanzhanggoogle Aug 29, 2017
d643d96
minor fix
fanzhanggoogle Sep 12, 2017
ae30e83
Removed point cloud.
fanzhanggoogle Oct 4, 2017
2cba5c2
typo
fanzhanggoogle Oct 9, 2017
e71f0d8
Removed unused image
fanzhanggoogle Oct 9, 2017
e3cce40
Wording fix
fanzhanggoogle Nov 1, 2017
66bfc6d
more wording fixes
fanzhanggoogle Nov 1, 2017
734b3cb
more fixes
fanzhanggoogle Nov 1, 2017
e42d251
Change Draft to Complete
fanzhanggoogle Nov 1, 2017
8e9a344
Change Conformance to Recommended Loader Process; change normative
fanzhanggoogle Nov 2, 2017
1eba79a
Make conformance normative
fanzhanggoogle Nov 2, 2017
cb478d9
Merge branch 'master' into KHR_mesh_compression
pjcozzi Feb 8, 2018
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 192 additions & 0 deletions extensions/Khronos/KHR_draco_mesh_compression/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,192 @@
# KHR_draco_mesh_compression

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

## 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove this "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."

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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,
},
Copy link
Contributor

Choose a reason for hiding this comment

The 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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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 accessors since there are other properties. For example, WebGL might require these properties to render the assets correctly.
Another reason we don't explicitly omit the attributes is that we want to minimize the change in the spec when Draco extension is presented. In our design, the accessors of attributes could even have other extensions as long as they use the decompressed data instead of from bufferView.

Copy link
Contributor

@donmccurdy donmccurdy Aug 7, 2017

Choose a reason for hiding this comment

The 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 attributes to avoid duplication:

"attributes" : {
    "TEXCOORD_1" : 11
}

... 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 attributes, even if it's already in the Draco buffer? This would enable loaders to treat the Draco extension as optional, and to either load the compressed Draco data, or uncompressed data from another buffer, depending on runtime needs/capabilities. Or we could disallow this case, to keep things simple for the initial version, and say that attributes must be omitted when the Draco extension is used.

In previous comments, attributes was removed, and later re-added to specify Draco attribute order. With the observance that object properties aren't ordered, we then added attributeOrder as well. I'm not sure that we need both. Perhaps we don't need either one?

"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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When using this extension, the mode of primitive must be either TRIANGLES or TRIANGLE_STRIP and the mesh data will be decoded accordingly.

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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:
Copy link
Member

Choose a reason for hiding this comment

The 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)).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"indices propertiesof theprimitive" -> "indicesproperties of theprimitive`"

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
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" ]
}
1 change: 1 addition & 0 deletions extensions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@

#### Draft Khronos extensions
_Draft Khronos extensions are not ratified yet._
* [KHR_draco_mesh_compression](Khronos/KHR_draco_mesh_compression/README.md)
* [KHR_materials_common](Khronos/KHR_materials_common/README.md)
* [KHR_technique_webgl](Khronos/KHR_technique_webgl/README.md)

Expand Down