From 6306459b2d193d7951e52ffb10bdfb3c10cdbea8 Mon Sep 17 00:00:00 2001 From: Don McCurdy Date: Thu, 2 Feb 2017 06:24:13 -0500 Subject: [PATCH] Add gltf-model component and system. (#2333) * Add gltf-model component and system. Fixes #2261. * Set *.bin extension as binary. * Remove model; reference assets repo. * Rename system API to (un)registerModel. * Add component docs. * Add primitive wrapper, and docs. * Revert .gitattributes changes. * Add registration for . * Add tests. * what other tests * Fix errors in docs. * Add formats to meta title/desc. * Remove material extensions from collada and gltf primitives. * Add tests for gltf-model system. * Add labels to models demo. * Add 'Why use glTF' section. * Wording tweak. * sigh --- docs/components/gltf-model.md | 81 ++++++ docs/primitives/a-gltf-model.md | 33 +++ examples/test/model/index.html | 12 +- src/components/gltf-model.js | 37 +++ src/components/index.js | 1 + src/extras/primitives/index.js | 1 + .../primitives/primitives/a-collada-model.js | 6 +- .../primitives/primitives/a-gltf-model.js | 7 + src/lib/three.js | 2 + src/systems/gltf-model.js | 41 +++ src/systems/index.js | 1 + tests/assets/box/Box.bin | Bin 0 -> 648 bytes tests/assets/box/Box.gltf | 250 ++++++++++++++++++ tests/assets/box/Box0FS.glsl | 17 ++ tests/assets/box/Box0VS.glsl | 12 + tests/components/gltf-model.test.js | 58 ++++ tests/systems/gltf-model.test.js | 37 +++ 17 files changed, 590 insertions(+), 6 deletions(-) create mode 100644 docs/components/gltf-model.md create mode 100644 docs/primitives/a-gltf-model.md create mode 100644 src/components/gltf-model.js create mode 100644 src/extras/primitives/primitives/a-gltf-model.js create mode 100644 src/systems/gltf-model.js create mode 100755 tests/assets/box/Box.bin create mode 100755 tests/assets/box/Box.gltf create mode 100755 tests/assets/box/Box0FS.glsl create mode 100755 tests/assets/box/Box0VS.glsl create mode 100644 tests/components/gltf-model.test.js create mode 100644 tests/systems/gltf-model.test.js diff --git a/docs/components/gltf-model.md b/docs/components/gltf-model.md new file mode 100644 index 0000000000..4185228e9a --- /dev/null +++ b/docs/components/gltf-model.md @@ -0,0 +1,81 @@ +--- +title: gltf-model +type: components +layout: docs +parent_section: components +--- + +[about-gltf]: https://www.khronos.org/gltf + +[glTF][about-gltf] (GL Transmission Format) is an open project by Khronos providing a common, extensible format for 3D assets that is both efficient and highly interoperable with modern web technologies. + +The `gltf-model` component loads a 3D model using a glTF (.gltf or .glb) file. + +## Why use glTF? + +[obj-model]: ./obj-model.md +[collada-model]: ./collada-model.md + +In comparison to the older [OBJ][obj-model] format, which supports only vertices, normals, texture coords, and basic materials, glTF provides a more powerful set of features. In addition to all of the above, glTF offers: + +- Hierarchical objects +- Scene information (light sources, cameras) +- Skeletal structure and animation +- More robust materials and shaders + +For simple models with no animation, OBJ is nevertheless a common and reliable choice. + +In comparison to [COLLADA][collada-model], the supported features are very similar. However, because glTF focuses on providing a "transmission format" rather than an editor format, it is more interoperable with web technologies. By analogy, the .PSD (Adobe Photoshop) format is helpful for editing 2D images, but images are converted to .JPG for use on the web. In the same way, glTF is a simpler way of transmitting 3D assets while rendering the same result. + +In short, expect glTF models to work with A-Frame more reliably than COLLADA models. + +## Example + +Load a glTF model by pointing to an asset that specifies the `src` for a glTF file. + +```html + + + + + + + +``` + +## Values + +| Type | Description | +|----------|--------------------------------------| +| selector | Selector to an `` | +| string | `url()`-enclosed path to a glTF file | + +## Events + +| Event Name | Description | +|--------------|--------------------------------------------| +| model-loaded | glTF model has been loaded into the scene. | + +## Loading Inline + +Alternatively, load a glTF model by specifying the path directly within `url()`. This is less performant than using the asset management system. + +```html + +``` + +## More Resources + +The glTF format is fairly new, and few editors will export a `.gltf` file directly. Instead, various converters are available or in progress: + +[fbx-converter]: http://gltf.autodesk.io/ +[collada-converter]: http://cesiumjs.org/convertmodel.html +[obj-converter]: https://github.com/AnalyticalGraphicsInc/obj2gltf + +- [FBX → glTF][fbx-converter] - coming soon. +- [COLLADA → glTF][collada-converter]. +- [OBJ → glTF][obj-converter]. + +[spec]: https://github.com/KhronosGroup/glTF + +See the [official glTF specification][spec] for available features, community resources, and ways to contribute. diff --git a/docs/primitives/a-gltf-model.md b/docs/primitives/a-gltf-model.md new file mode 100644 index 0000000000..cfdbb5e3fd --- /dev/null +++ b/docs/primitives/a-gltf-model.md @@ -0,0 +1,33 @@ +--- +title: +type: primitives +layout: docs +parent_section: primitives +--- + +The glTF model primitive displays a 3D glTF model created from a 3D +modeling program or downloaded from the web. + +## Example + +```html + + + + + + + + + + + +``` + +## Attribute + +[gltf]: ../components/gltf-model.md + +| Attribute | Component Mapping | Default Value | +|-----------|------------------------|---------------| +| src | [gltf-model][gltf].src | null | diff --git a/examples/test/model/index.html b/examples/test/model/index.html index 461cf8833b..f48336a062 100644 --- a/examples/test/model/index.html +++ b/examples/test/model/index.html @@ -2,8 +2,8 @@ - Model - + Models (glTF, OBJ, COLLADA) + @@ -11,15 +11,23 @@ + + + + + + + + diff --git a/src/components/gltf-model.js b/src/components/gltf-model.js new file mode 100644 index 0000000000..9d0433a1ca --- /dev/null +++ b/src/components/gltf-model.js @@ -0,0 +1,37 @@ +var registerComponent = require('../core/component').registerComponent; +var THREE = require('../lib/three'); + +/** + * glTF model loader. + */ +module.exports.Component = registerComponent('gltf-model', { + schema: {type: 'model'}, + + init: function () { + this.model = null; + this.loader = new THREE.GLTFLoader(); + }, + + update: function () { + var self = this; + var el = this.el; + var src = this.data; + + if (!src) { return; } + + this.remove(); + + this.loader.load(src, function gltfLoaded (gltfModel) { + self.model = gltfModel.scene; + self.system.registerModel(self.model); + el.setObject3D('mesh', self.model); + el.emit('model-loaded', {format: 'gltf', model: self.model}); + }); + }, + + remove: function () { + if (!this.model) { return; } + this.el.removeObject3D('mesh'); + this.system.unregisterModel(this.model); + } +}); diff --git a/src/components/index.js b/src/components/index.js index 988ed11b89..d9f52aeb0e 100644 --- a/src/components/index.js +++ b/src/components/index.js @@ -3,6 +3,7 @@ require('./camera'); require('./collada-model'); require('./cursor'); require('./geometry'); +require('./gltf-model'); require('./hand-controls'); require('./light'); require('./look-controls'); diff --git a/src/extras/primitives/index.js b/src/extras/primitives/index.js index 95d37975ab..3ee15aa8b4 100644 --- a/src/extras/primitives/index.js +++ b/src/extras/primitives/index.js @@ -2,6 +2,7 @@ require('./primitives/a-camera'); require('./primitives/a-collada-model'); require('./primitives/a-cursor'); require('./primitives/a-curvedimage'); +require('./primitives/a-gltf-model'); require('./primitives/a-image'); require('./primitives/a-light'); require('./primitives/a-obj-model'); diff --git a/src/extras/primitives/primitives/a-collada-model.js b/src/extras/primitives/primitives/a-collada-model.js index 7746ed6371..75c3e45d12 100644 --- a/src/extras/primitives/primitives/a-collada-model.js +++ b/src/extras/primitives/primitives/a-collada-model.js @@ -1,9 +1,7 @@ -var getMeshMixin = require('../getMeshMixin'); var registerPrimitive = require('../primitives').registerPrimitive; -var utils = require('../../../utils/'); -registerPrimitive('a-collada-model', utils.extendDeep({}, getMeshMixin(), { +registerPrimitive('a-collada-model', { mappings: { src: 'collada-model' } -})); +}); diff --git a/src/extras/primitives/primitives/a-gltf-model.js b/src/extras/primitives/primitives/a-gltf-model.js new file mode 100644 index 0000000000..986d8bf5ba --- /dev/null +++ b/src/extras/primitives/primitives/a-gltf-model.js @@ -0,0 +1,7 @@ +var registerPrimitive = require('../primitives').registerPrimitive; + +registerPrimitive('a-gltf-model', { + mappings: { + src: 'gltf-model' + } +}); diff --git a/src/lib/three.js b/src/lib/three.js index 6b0d8cd17c..2e636124bf 100644 --- a/src/lib/three.js +++ b/src/lib/three.js @@ -19,6 +19,7 @@ if (THREE.Cache) { } // TODO: Eventually include these only if they are needed by a component. +require('three/examples/js/loaders/GLTFLoader'); // THREE.GLTFLoader require('three/examples/js/loaders/OBJLoader'); // THREE.OBJLoader require('three/examples/js/loaders/MTLLoader'); // THREE.MTLLoader require('three/examples/js/BlendCharacter'); // THREE.BlendCharacter @@ -27,6 +28,7 @@ require('../../vendor/VRControls'); // THREE.VRControls require('../../vendor/VREffect'); // THREE.VREffect THREE.ColladaLoader.prototype.crossOrigin = 'anonymous'; +THREE.GLTFLoader.prototype.crossOrigin = 'anonymous'; THREE.MTLLoader.prototype.crossOrigin = 'anonymous'; THREE.OBJLoader.prototype.crossOrigin = 'anonymous'; diff --git a/src/systems/gltf-model.js b/src/systems/gltf-model.js new file mode 100644 index 0000000000..031e538f4b --- /dev/null +++ b/src/systems/gltf-model.js @@ -0,0 +1,41 @@ +var registerSystem = require('../core/system').registerSystem; +var THREE = require('../lib/three'); + +/** + * glTF model system. + */ +module.exports.System = registerSystem('gltf-model', { + init: function () { + this.models = []; + }, + + /** + * Updates shaders for all glTF models in the system. + */ + tick: function () { + var sceneEl = this.sceneEl; + if (sceneEl.hasLoaded && this.models.length) { + THREE.GLTFLoader.Shaders.update(sceneEl.object3D, sceneEl.camera); + } + }, + + /** + * Registers a glTF asset. + * @param {object} gltf Asset containing a scene and (optional) animations and cameras. + */ + registerModel: function (gltf) { + this.models.push(gltf); + }, + + /** + * Unregisters a glTF asset. + * @param {object} gltf Asset containing a scene and (optional) animations and cameras. + */ + unregisterModel: function (gltf) { + var models = this.models; + var index = models.indexOf(gltf); + if (index >= 0) { + models.splice(index, 1); + } + } +}); diff --git a/src/systems/index.js b/src/systems/index.js index b96fb23b2f..8a64b19dc2 100755 --- a/src/systems/index.js +++ b/src/systems/index.js @@ -1,5 +1,6 @@ require('./camera'); require('./geometry'); +require('./gltf-model'); require('./light'); require('./material'); require('./tracked-controls'); diff --git a/tests/assets/box/Box.bin b/tests/assets/box/Box.bin new file mode 100755 index 0000000000000000000000000000000000000000..29a29e1385f5c15edd4d0e456c375f61a13c7fd6 GIT binary patch literal 648 zcmb7;0SdxE3