Merge pull request #1 from javagl/master

Initial commit of first glTF tutorial

gltfTutorial/README.md

@@ -0,0 +1,35 @@
+# glTF Tutorial
+
+This tutorial gives an introduction to [glTF](https://www.khronos.org/gltf), the GL transmission format. It summarizes the most important features and application cases of glTF, and describes the structure of the files that are related to glTF. It explains how glTF assets may be read, processed, and used to display 3D graphics efficiently.
+
+Some basic knowledge about [JSON](http://json.org/), the JavaScript Object Notation, is assumed. Additionally, a basic understanding of common graphics APIs, like OpenGL or WebGL, is required.
+
+- [Introduction](gltfTutorial_001_Introduction.md)
+- [Basic glTF Structure](gltfTutorial_002_BasicGltfStructure.md)
+- [Example: A Minimal glTF File](gltfTutorial_003_MinimalGltfFile.md)
+- [Scenes and Nodes](gltfTutorial_004_ScenesNodes.md)
+- [Buffers, BufferViews, and Accessors](gltfTutorial_005_BuffersBufferViewsAccessors.md)
+- [Example: A Simple Animation](gltfTutorial_006_SimpleAnimation.md)
+- [Animations](gltfTutorial_007_Animations.md)
+- [Example: Simple Meshes](gltfTutorial_008_SimpleMeshes.md)
+- [Meshes](gltfTutorial_009_Meshes.md)
+- [Materials](gltfTutorial_010_Materials.md)
+- [Example: A Simple Material](gltfTutorial_011_SimpleMaterial.md)
+- [Textures, Images, and Samplers](gltfTutorial_012_TexturesImagesSamplers.md)
+- [Example: A Simple Texture](gltfTutorial_013_SimpleTexture.md)
+- [Example: An Advanced Material](gltfTutorial_014_AdvancedMaterial.md)
+- [Example: Simple Cameras](gltfTutorial_015_SimpleCameras.md)
+- [Cameras](gltfTutorial_016_Cameras.md)
+- [Example: A Simple Morph Target](gltfTutorial_017_SimpleMorphTarget.md)
+- [Morph Targets](gltfTutorial_018_MorphTargets.md)
+- [Example: Simple Skin](gltfTutorial_019_SimpleSkin.md)
+- [Skins](gltfTutorial_020_Skins.md)
+
+
+**Acknowledgements:**
+
+- Patrick Cozzi, Cesium, [@pjcozzi](https://twitter.com/pjcozzi)
+- Alexey Knyazev, [lexaknyazev](https://github.com/lexaknyazev)
+- Sarah Chow, [slchow](https://github.com/slchow)
+
+

gltfTutorial/gltfTutorial_001_Introduction.md

@@ -0,0 +1,54 @@
+[Table of Contents](README.md) | Next: [Basic glTF Structure](gltfTutorial_002_BasicGltfStructure.md)
+
+
+
+
+
+# Introduction to glTF using WebGL
+
+An increasing number of applications and services are based on 3D content. Online shops offer product configurators with a 3D preview. Museums digitize their artifacts with 3D scans and allow visitors to explore their collections in virtual galleries. City planners use 3D city models for planning and information visualization. Educators create interactive, animated 3D models of the human body. Many of these applications run directly in the web browser, which is possible because all modern browsers support efficient rendering with WebGL.
+
+<p align="center">
+<img src="images/applications.png" /><br>
+<a name="applications-png"></a>Image 1a: Screenshots of various websites and applications showing 3D models.
+</p>
+
+Demand for 3D content in various applications is constantly increasing. In many cases, the 3D content has to be transferred over the web, and it has to be rendered efficiently on the client side. But until now, there has been a gap between the 3D content creation and efficient rendering of that 3D content in the runtime applications.
+
+
+## 3D content pipelines
+
+3D content that is rendered in client applications comes from different sources and is stored in different file formats. The [list of 3D graphics file formats on Wikipedia](https://en.wikipedia.org/wiki/List_of_file_formats#3D_graphics) shows an overwhelming number, with more than 70 different file formats for 3D data, serving different purposes and application cases.  
+
+For example, raw 3D data may be obtained with a 3D scanner. These scanners usually provide the geometry data of a single object, which is stored in [OBJ](https://en.wikipedia.org/wiki/Wavefront_.obj_file), [PLY](https://en.wikipedia.org/wiki/PLY_(file_format)), or [STL](https://en.wikipedia.org/wiki/STL_(file_format)) files. These file formats do not contain information about the scene structure or how the objects should be rendered.
+
+More sophisticated 3D scenes can be created with authoring tools. These tools allow one to edit the structure of the scene, the light setup, cameras, animations, and, of course, the 3D geometry of the objects that appear in the scene. Applications store this information in their own, custom file formats. For example, [Blender](https://www.blender.org/) stores the scenes in `.blend` files, [LightWave3D](https://www.lightwave3d.com/) uses the `.lws` file format, [3ds Max](http://www.autodesk.com/3dsmax) uses the `.max` file format, and [Maya](http://www.autodesk.com/maya) uses `.ma` files.
+
+In order to render such 3D content, the runtime application must be able to read different input file formats. The scene structure has to be parsed, and the 3D geometry data has to be converted into the format required by the graphics API. The 3D data has to be transferred to the graphics card memory, and then the rendering process can be described with sequences of graphics API calls. Thus, each runtime application has to create importers, loaders, or converters for all file formats that it will support, as shown in Image 1b.
+
+<p align="center">
+<img src="images/contentPipeline.png" /><br>
+<a name="contentPipeline-png"></a>Image 1b: The 3D content pipeline today.
+</p>
+
+
+## glTF: A transmission format for 3D scenes
+
+The goal of glTF is to define a standard for representing 3D content, in a form that is suitable for use in runtime applications. The existing file formats are not appropriate for this use case: some of do not contain any scene information, but only geometry data; others have been designed for exchanging data between authoring applications, and their main goal is to retain as much information about the 3D scene as possible, resulting in files that are usually large, complex, and hard to parse. Additionally, the geometry data may have to be preprocessed so that it can be rendered with the client application.
+
+None of the existing file formats were designed for the use case of efficiently transferring 3D scenes over the web and rendering them as efficiently as possible. But glTF is not "yet another file format." It is the definition of a *transmission* format for 3D scenes:
+
+- The scene structure is described with JSON, which is very compact and can easily be parsed.
+- The 3D data of the objects are stored in a form that can be directly used by the common graphics APIs, so there is no overhead for decoding or pre-processing the 3D data.
+
+Different content creation tools may now provide 3D content in the glTF format. And an increasing number of client applications are able to consume and render glTF. Some of these applications are shown in [Image 1b](#applications-png). So glTF may help to bridge the gap between content creation and rendering, as shown in Image 1c. 
+
+<p align="center">
+<img src="images/contentPipelineWithGltf.png" /><br>
+<a name="contentPipelineWithGltf-png"></a>Image 1c: The 3D content pipeline with glTF.
+</p>
+
+An increasing number of content creation tools will be able to provide glTF directly. Alternatively, other file formats can be used to create glTF assets, using one of the open-source conversion utilities listed in the [Khronos glTF repository](https://github.com/KhronosGroup/glTF#converters). For example, nearly all authoring applications can export their scenes in the [COLLADA](https://www.khronos.org/collada/) format. So the [COLLADA2GLTF](https://github.com/KhronosGroup/glTF/tree/master/COLLADA2GLTF) tool can be used to convert scenes and models from these authoring applications to glTF. `OBJ` files may be converted to glTF using [obj2gltf](https://github.com/AnalyticalGraphicsInc/obj2gltf). For other file formats, custom converters can be used to create glTF assets, thus making the 3D content available for a broad range of runtime applications.
+
+
+[Table of Contents](README.md) | Next: [Basic glTF Structure](gltfTutorial_002_BasicGltfStructure.md)

gltfTutorial/gltfTutorial_002_BasicGltfStructure.md

@@ -0,0 +1,109 @@
+Previous: [Introduction](gltfTutorial_001_Introduction.md) | [Table of Contents](README.md) | Next: [A Minimal glTF File](gltfTutorial_003_MinimalGltfFile.md)
+
+
+# The Basic Structure of glTF
+
+The core of glTF is a JSON file. This file describes the whole contents of the 3D scene. It consists of a description of the scene structure itself, which is given by a hierarchy of nodes that define a scene graph. The 3D objects that appear in the scene are defined using meshes that are attached to the nodes. Materials define the appearance of the objects. Animations describe how the 3D objects are transformed (e.g., rotated to translated) over time, and skins define how the geometry of the objects is deformed based on a skeleton pose. Cameras describe the view configuration for the renderer.
+
+## The JSON structure
+
+The scene objects are stored in arrays in the JSON file. They can be accessed using the index of the respective object in the array:
+
+```javascript
+"meshes" : 
+[
+    { ... }
+    { ... }
+    ...
+],
+```
+
+These indices are also used to define the *relationships* between the objects. The example above defines multiple meshes, and a node may refer to one of these meshes, using the mesh index, to indicate that the mesh should be attached to this node:
+
+```javascript
+"nodes:" 
+[
+    { "mesh": 0, ... },
+    { "mesh": 5, ... },
+    ...
+}
+```
+
+The following image (adapted from the [glTF concepts section](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#concepts)) gives an overview of the top-level elements of the JSON part of a glTF asset:
+
+<p align="center">
+<img src="images/gltfJsonStructure.png" /><br>
+<a name="gltfJsonStructure-png"></a>Image 2a: The glTF JSON structure
+</p>
+
+
+These elements are summarized here quickly, to give an overview, with links to the respective sections of the glTF specification. More detailed explanations of the relationships between these elements will be given in the following sections.
+
+- The [`scene`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-scene) is the entry point for the description of the scene that is stored in the glTF. It refers to the `node`s that define the scene graph.
+- The [`node`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-node) is one node in the scene graph hierarchy. It can contain a transformation (e.g., rotation or translation), and it may refer to further (child) nodes. Additionally, it may refer to `mesh` or `camera` instances that are "attached" to the node, or to a `skin` that describes a mesh deformation.
+- The [`camera`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-camera) defines the view configuration for rendering the scene.
+- A [`mesh`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-mesh) describes a geometric object that appears in the scene. It refers to `accessor` objects that are used for accessing the actual geometry data, and to `material`s that define the appearance of the object when it is rendered.
+- The [`skin`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-skin) defines parameters that are required for vertex skinning, which allows the deformation of a mesh based on the pose of a virtual character. The values of these parameters are obtained from an `accessor`.
+- An [`animation`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-animation) describes how transformations of certain nodes (e.g., rotation or translation) change over time.
+- The [`accessor`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-accessor) is used as an abstract source of arbitrary data. It is used by the `mesh`, `skin`, and `animation`, and provides the geometry data, the skinning parameters and the time-dependent animation values. It refers to a [`bufferView`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-bufferView), which is a part of a [`buffer`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-buffer) that contains the actual raw binary data.
+- The [`material`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-material) contains the parameters that define the appearance of an object. It usually refers to `texture` objects that will be applied to the rendered geometry.
+- The [`texture`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-texture) is defined by a [`sampler`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-sampler) and an [`image`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-image). The `sampler` defines how the texture `image` should be placed on the object.   
+
+
+
+
+## References to external data
+
+The binary data, like geometry and textures of the 3D objects, are usually not contained in the JSON file. Instead, they are stored in dedicated files, and the JSON part only contains links to these files. This allows the binary data to be stored in a form that is very compact and can efficiently be transferred over the web. Additionally, the data can be stored in a format that can be used directly in the renderer, without having to parse, decode, or preprocess the data.    
+
+<p align="center">
+<img src="images/gltfStructure.png" /><br>
+<a name="gltfStructure-png"></a>Image 2b: The glTF structure
+</p>
+
+As shown in the image above, there are two types of objects that may contain such links to external resources, namely `buffers` and `images`. These objects will later be explained in more detail.
+
+
+
+## Reading and managing external data
+
+Reading and processing a glTF asset starts with parsing the JSON structure. After the structure has been parsed, the [`buffer`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-buffer) and [`image`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-image) objects are available in the top-level `buffers` and `images` arrays, respectively. Each of these objects may refer to blocks of binary data. For further processing, this data is read into memory. Usually, the data will be be stored in an array so that they may be looked up using the same index that is used for referring to the `buffer` or `image` object that they belong to. 
+
+
+## Binary data in `buffers`
+
+A [`buffer`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-buffer) contains a URI that points to a file containing the raw, binary buffer data:
+
+```javascript
+"buffer01": {
+    "byteLength": 12352,
+    "type": "arraybuffer",
+    "uri": "buffer01.bin"
+}
+```
+
+This binary data is just a raw block of memory that is read from the URI of the `buffer`, with no inherent meaning or structure. The [Buffers, BufferViews, and Accessors](gltfTutorial_005_BuffersBufferViewsAccessors.md) section will show how this raw data is extended with information about data types and the data layout. With this information, one part of the data may, for example, be interpreted as animation data, and another part may be interpreted as geometry data. Storing the data in a binary form allows it to be transferred over the web much more efficiently than in the JSON format, and the binary data can be passed directly to the renderer without having to decode or pre-process it. 
+
+
+
+## Image data in `images`
+
+An [`image`](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0/#reference-image) may refer to an external image file that can be used as the texture of a rendered object:
+
+```javascript
+"image01": {
+    "uri": "image01.png"
+}
+```
+
+The reference is given as a URI that usually points to a PNG or JPG file. These formats significantly reduce the size of the files so that they may efficiently be transferred over the web. In some cases, the `image` objects may not refer to an external file, but to data that is stored in a `buffer`. The details of this indirection will be explained in the [Textures, Images, and Samplers](gltfTutorial_016_TexturesImagesSamplers.md) section. 
+
+
+
+
+## Binary data in data URIs
+
+Usually, the URIs that are contained in the `buffer` and `image` objects will point to a file that contains the actual data. As an alternative, the data may be *embedded* into the JSON, in binary format, by using a [data URI](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs).
+
+
+Previous: [Introduction](gltfTutorial_001_Introduction.md) | [Table of Contents](README.md) | Next: [A Minimal glTF File](gltfTutorial_003_MinimalGltfFile.md)