dali-scene-loader/README.md

   1 # Table of contents
   2    * [Overview](#overview)
   3    * [`scenes`](#scenes)
   4    * [`nodes`](#nodes)
   5       * [Transformations](#transformations)
   6       * [Size](#size)
   7       * [Visibility](#visibility)
   8       * [`children`](#children)
   9       * [`customization`](#customization)
  10       * [Renderables](#renderables)
  11          * [`model`](#model)
  12          * [`arc`](#arc)
  13       * [`inverseBindPoseMatrix`](#inversebindposematrix)
  14    * [`materials`](#materials)
  15    * [`meshes`](#meshes)
  16    * [`shaders`](#shaders)
  17       * [`rendererState`](#rendererState)
  18       * [`defines`](#defines)
  19       * [`hints`](#hints)
  20       * [Uniforms](#uniforms)
  21    * [`skeletons`](#skeletons)
  22    * [`cameras`](#cameras)
  23       * [Perspective cameras](#perspective-cameras)
  24       * [Orthographic cameras](#orthographic-cameras)
  25    * [`lights`](#lights)
  26    * [`animations`](#animations)
  27       * [`properties`](#properties)
  28          * [`keyFramesBin`](#keyframesbin)
  29          * [`keyFrames`](#keyFrames)
  30          * [`value`](#value)
  31    * [`animationGroups`](#animationGroups)
  32
  33 # Overview
  34 DLI is a JSON based format for representing 3D scenes.
  35    * Like glTF, the DLI document defines a set of scenes, which in turn define a hierarchical structure of nodes, and the additional data required to render them - meshes, geometry.
  36    * Unlike glTF, it allows definitions of shaders, environment maps, and lighting parameters as well;
  37    * Unlike glTF, DLI does not concern itself with buffers, buffer views and accessors;
  38    * It supports customizations, which allow replacing parts of the scene based on customization tags and options, without reloading the whole scene.
  39    * It supports the processing of custom categories, which can be scheduled to take place prior to or after the processing of the scene data, as well as custom node and animation processors.
  40
  41 # `scenes`
  42 The "scenes" element is an array of JSON objects, each of which must define a `nodes` array with the index of the definition of the root node.
  43 :warning: The array must not be empty. Only the first element is used.
  44 An optional `scene` element with an integer value may be defined to specify the index of the first scene to be created.
  45 The rest of the scenes are created in the order of their definition (from index 0 to the highest, skipping the default - already created - scene).
  46 ```js
  47 {
  48     "scene": 0,
  49     "scenes": [ { "nodes": [ 0 ] } ],
  50     "nodes": [ {
  51         "name": "some_unique_name"
  52     } ]
  53 }
  54 ```
  55
  56 # `nodes`
  57 The 3D scene is built using a hierarchy of nodes, which are used to position the objects to render.
  58 :warning: Each node must have a `name` string that 1, is not an empty string and 2, is unique within the DLI document. The use of alpha-numeric characters and underscore only is highly recommeneded.
  59
  60 ## Transformations
  61 There are two ways to define the local transform of each nodes. Both are optional, defaulting to a position at the origin, a scale of one and no rotation.
  62    * A `matrix` array of 16 numerical values defining a column-major 4x4 matrix;
  63    * A `position` array of 3 numerical values defining a 3D vector and an `angle` array of 3 numerical values defining euler angles of rotation along the 3 axes.
  64
  65 ## Size
  66 The size of the bounding box of a node may be specified using either of the optional `size` or `bounds` properties, as arrays of 2 or 3 numerical values. Its default value is the unit vector.
  67
  68 ## Visibility
  69 The `visible` optional boolean property defines whether a node and its children are rendered (`true`) or not (`false`).
  70
  71 ## `children`
  72 An array of 0 or more indices into the top level `nodes` array, which shall inherit the transform and visibility of their parent node.
  73 :warning: Nodes are processed in the order they are encountered during the depth-first traversal of the hierarchy.
  74 ```js
  75   "nodes": [ {
  76     "name": "hip",
  77     "children": [ 3, 1, 2 ]
  78   }, {
  79     "name": "spine"
  80   }, {
  81     "name": "left leg"
  82   }, {
  83     "name": "right leg"
  84   } ]
  85 ```
  86
  87 ## `customization`
  88 Customizations may allow creating a different sub-tree of each node that define them, based on application specific configuration settings known at the time of creating the scene.
  89 The definition of a `customization` is a single string tag:
  90 ```js
  91   "nodes": [ {
  92     "name": "Soup du jour",
  93     "customization": "flavor", // this one
  94     "children": [ 1, 2, 3 ]
  95   }, {
  96     "name": "Broccoli and Stilton",
  97   }, {
  98     "name": "Butternut Squash",
  99   }, {
 100     "name": "Strawberry and Cream",
 101   } ]
 102 ```
 103 :warning: Customizations and renderables are mutually exclusive on the same node.
 104
 105 ## Renderables
 106 There is support for two types of nodes that define renderable content.
 107 The definition of these renderables come in sub-objects.
 108 All of them support a `color` property, which is an array of 3 or 4 numerical values for RGB or RGBA components. For the alpha value to take effect, alpha blending must be enabled; this is controlled by the [material](#materiaL).
 109 :warning: Customizations and renderables are mutually exclusive on the same node.
 110
 111 ### `model`
 112 Provides definition for a 3D object, which requires a `mesh`, `shader` and `material`.
 113 Each of these are provided in form of an integer index into the related top-level array of the DLI document.
 114 :warning: `mesh` must be provided; the rest are optional and default to 0.
 115 ```js
 116   "nodes": [ {
 117     "name": "Sphere",
 118     "model": {
 119       "mesh": 0, // required
 120       "shader": 0, // optional, defaults to 0
 121       "material": 1 // optional, defaults to 0
 122     }
 123   } ]
 124 ```
 125
 126 ### `arc`
 127 Arc is a specialisation of a model that allows the rendering of circular progress bars. As such, it also must provide a `mesh` ID.
 128 ```js
 129   "nodes": [ {
 130     "name": "Any Name",
 131     "arc": {
 132       "mesh": 0, // required
 133       "shader": 0, // optional, defaults to 0
 134       "material": 1 // optional, defaults to 0
 135       "antiAliasing": true,
 136       "radius": -0.928,
 137       "startAngle": -81.0,
 138       "endAngle": 261
 139     }
 140   } ]
 141 ```
 142    * `startAngle` and `endAngle` are the angular positions where the arc starts and ends, in degrees.
 143    * `radius` is the inner radius of the arc, the outer radius being defined by the [`size`](#size) of the node.
 144    * `antiAliasing` defines whether the edges of the arc should be smoothed.
 145
 146 ## `inverseBindPoseMatrix`
 147 Nodes that serve as joints of a [skeleton](#skeleton) must define this property as an array of 16 numerical values for a column major 4x4 matrix.
 148 ```js
 149   "nodes": [ {
 150     "name" : "l_shoulder_JNT",
 151     "inverseBindPoseMatrix" : [ 0.996081, -0.0407448, 0.0785079, 0.0, 0.0273643, 0.985992, 0.164531, 0.0, -0.0841121, -0.161738, 0.983242, 0.0, -0.0637747, -1.16091, -0.161038, 1.0 ]
 152   } ]
 153 ```
 154
 155 # `environment`
 156 An array of environment map definitions, which have the following format:
 157 ```js
 158   "environment": [{
 159     "cubeSpecular": "Studio_001/Radiance.ktx",
 160     "cubeDiffuse": "Studio_001/Irradiance.ktx",
 161     "cubeInitialOrientation": [ 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0 ]
 162   } ]
 163 ```
 164 `cubeSpecular` and `cubeDiffuse` are the names of the respective cube map files that will be attempted to be located from the _environment_ path, which is up to the application. A 1x1x1 white RGB888 cubemap is created in place of either that was omitted.
 165 `cubeInitialOrientation` may be used to inform the (PBR) shader of a matrix which describes the initial orientation of the cube map. Defaults to the identity matrix.
 166
 167 # `materials`
 168 Defines configurations of textures (and their samplers) that form materials. These can be created from single values or image files (in the formats that DALi supports).
 169 ```js
 170   "materials": [ {
 171     "environment": 0,
 172     "albedoMap": "A.png",
 173     "normal": "N.png",
 174     "metallicRoughnessMap": "MR.png",
 175     "color": [ 1.0, 0.8, 0.7, 0.5 ]
 176   } ]
 177 ```
 178    * `environment`: The index of the [environment map](#environments) to use. Single integer, defaults to `0`.
 179    * `mipmap`: A boolean to speficy if the creation and sampling of mipmaps should be enabled. Off by default.
 180    * `color`: Base color, which the color of the node gets multiplied by. Defaults to white.
 181    * `metallic` and `roughness`: Properties for PBR materials; both are expected to be a single numerical value and default to `1.0`.
 182
 183 ## Texture maps
 184 `albedoMap` / `albedoMetallicMap` / `normalMap` / `normalRoughnessMap` / `metallicRoughnessMap` / `subsurfaceMap`: define various texture semantics, i.e. the role of the texture, which shall be loaded from an image _inside the materials path_, which is up to the application. All of them are optional.
 185 :warning: Semantics shall not overlap within the same material, e.g. multiple albedo definitions, or albedo and albedoMetallic.
 186
 187 # `meshes`
 188 Defines an array of meshes which are used to access geometry data stored in a binary file. The `uri` property is used to locate each file _inside the mesh path_, which is up to the application; alternatively it can be set to `"quad"`, resulting in the creation of a unit quad.
 189 Those models loaded from a file may provide an accessor, and flag its presence in the `attributes` bitmask property. The following are supported:
 190 |Attribute Name|Bit|Decimal value|Type|Remarks|
 191 |-|-|-|-|-|
 192 |`indices`  |0|  1|unsigned short||
 193 |`positions`|1|  2|Vector3||
 194 |`normals`  |2|  4|Vector3||
 195 |`textures` |3|  8|Vector2|UVs|
 196 |`tangents` |4| 16|Vector3||
 197 |           |5| 32||Ignored, but reserved for bitangents|
 198 |`joints0`  |6| 64|Vector4|Joint IDs for skinned meshes|
 199 |`weights0` |7|128|Vector4|Joint weights for skinned meshes|
 200 E.g. if positions, normals and tangents are provided, the `attributes` property must have a value of 2 + 4 + 16 = 22.
 201 Each attribute must provide a `byteOffset` and `byteLength` property, which must be correctly sized for the type of the given attribute.
 202 Finally, to specify what primitives should the geometry be rendered as, a `primitive` property may be provided with one of the following values: `TRIANGLES` (default), `LINES`, `POINTS`.
 203
 204 ## Skinned meshes
 205 DLI supports meshes that allow deformation by skeletal animation. These must define a few additional properties:
 206    * `joints0` and `weights0` attributes, as above.
 207    * A [`skeleton`](#skeletons) ID, to specify which (joint) nodes' transformations affect the mesh.
 208
 209 :warning: The maximum number of bones supported by DALi Scene Loader is `64`.
 210
 211 ## Blend shapes
 212 Blend shapes provide alternate configurations of vertex `positions`, `normals` and/or `tangents` that may be blended with the same attributes of the base mesh, controlled by an animatable `weight`.
 213 ```js
 214   "meshes": [ {
 215       "uri": "example.bin",
 216       "attributes": 2,
 217       "positions": {
 218           "byteOffset": 0,
 219           "byteLength": 12000
 220       },
 221       "blendShapesHeader": {
 222           "version": "2.0",
 223           "byteOffset": 12000,
 224           "byteLEngth": 4
 225       },
 226       "blendShapes": [ {
 227           "weight": 0.0,
 228           "positions": {
 229               byteOffset: 12004,
 230               byteLength: 12000
 231           }
 232       } ]
 233   } ]
 234 ```
 235 A `blendShapesHeader`, if present, must define:
 236    * the `version` of the blend shapes; supported values are `1.0` and `2.0`. The difference between the versions is that v1.0 requires a per-blend shape definition of an un-normalization factor.
 237    * the `byteOffset` and `byteLength` of a buffer in the binary which defines the width (2 bytes) and height (2 bytes) of the texture that dali-scene-loader creates for blend shape data.
 238
 239 The `blendShapes` array then defines the shapes that are available to blend between, comprising of:
 240    * An initial `weight` numerical, the default is 0;
 241    * `position` / `normals` / `tangents` attributes, which must be also present in the base mesh and are the same format (`byteOffset` / `byteLength`);
 242
 243 :warning: The size of the attributes of the blend shape must match that of the base mesh (and each other) - i.e. they must define the same number of vertices.
 244
 245 # `shaders`
 246 Provides an array of shader programs that renderables may use for rendering.
 247 For each shader, `vertex` and `fragment` are required string properties pointing to the shader files _inside the shader path_, which is up to the application.
 248    * `rendererState`: This string defines the options for configuring the settings of the renderer. Refer to public-api/renderer-state.h for details.
 249    * `defines`: An optional array of strings which will be used to create #defines into the vertex and fragment shaders.
 250    * `hints`: An optional array of strings that map to `Dali::Shader::Hint` values. Therefore two values are supported - `MODIFIES_GEOMETRY` and `OUTPUT_IS_TRANSPARENT`.
 251
 252 ## Uniforms
 253 Every property that is not one of the reserved keys above, will be attempted to be registered as a uniform of the same name.
 254 :warning: boolean values will be converted to floating point 1.0 (for `true`) or 0.0 (for `false`).
 255 :warning: integer values will be converted to floating point.
 256 :warning: arrays of numerical values will be treated as one of the vec2 / vec3 / vec4 / mat3 / mat4 types, depending on what do they define sufficient components for.
 257 ```js
 258   "shader": [ {
 259     "vertex": "dli_pbr.vsh",
 260     "fragment": "dli_pbr.fsh",
 261     "defines": [ "HIGHP", SKINNING" ],
 262     "rendererState": "DEPTH_WRITE|DEPTH_TEST|CULL_BACK",
 263     "hints":
 264     "uMaxLOD": 6
 265   } ]
 266 ```
 267
 268 # `skeletons`
 269 Skeletons in DLI simply define the name of a `node` that shall serve as the _root joint_ of the given skeleton.
 270 ```js
 271   "skeletons": [ {
 272     "node": "hipJoint"
 273   } ]
 274 ```
 275 The Joint IDs in skinned mesh data relate to the descendants of the [node](#nodes) identified as the root joint that are joints, i.e. define [`inverseBindPoseMatrix`](#inversebindposematrix), in depth-first traversal order.
 276
 277 # `cameras`
 278 Define the transformation of viewers and the projection used by them.
 279 All cameras may define:
 280    * `matrix`: an array of 16 numerical values for the transform matrix
 281    * `near` and `far` values for the position of the respective clipping planes. These default to `0.1` and `1000.0`, respectively.
 282
 283 ## Perspective cameras
 284 This projection type - and a vertical field of view of `60` degrees - is the default.
 285 The (V)FOV can be specified in the `fov` property, as a single numerical value.
 286
 287 ## Orthographic cameras
 288 If the `orthographic` is defined with an array of four numerical values for the left, right, bottom and top clipping planes (in this order), then orthographic projection is used, and `fov` is ignored.
 289
 290 # `lights`
 291 Define parameters for a single light source - the implementation is up to the application. The following properties are supported.
 292    * `transform`: matrix of 16 numerical values for the positioning / directing of the light;
 293    * `color`: array of 3 components for RGB;
 294    * `intensity`: single float;
 295    * `shadowIntensity`: single float;
 296    * `shadowMapSize`: unsigned integer size (same width & height) of shadow map.
 297    * `orthographicSize`: single float to define the size (same width & height) of orthographic position.
 298
 299 # `animations`
 300 Animations provide a way to change properties of nodes (and those of their renderables) over time.
 301 ```js
 302   "animations": [ {
 303      "name": "Idle",
 304      "loopCount": 0,
 305      "duration": 4.0,
 306      "endAction": "DISCARD",
 307      "disconnectAction": "DISCARD",
 308      "properties": []
 309   } ]
 310 ```
 311    * `name`: the identifier to look the animation up by;
 312    * `loopCount`: the number of times that the animation should be played. The default is `1`; `0` signifies infinity repetitions.
 313    * `duration`: the duration of the animation in seconds. If not provided, it will be calculated from the properties.
 314    * `endAction` and `disconnectAction`: the supported values, defaults and their meaning are described in the `Dali::Animation::EndAction` enum;
 315
 316 ## `properties`
 317 An array of animation property definitions.
 318    * `node`: the name of the node whose property shall be animated;
 319    * `property`: the name that the property was registered under.
 320    * `alphaFunction`: the name of an alpha function which shall be used in animating a value, or between key frames;
 321    * `timePeriod`: `delay` (defaults to `0.0`) and `duration` (defaults to the `duration` of the animation) of the property animation, in sceonds;
 322
 323 The property may be animated using one of the following methods. They are listed in priority order; if e.g. a property defines `keyFramesBin` and `keyFrames`, then only `keyFramesBin` is used.
 324
 325 ### `keyFramesBin`
 326 JSON object that defines a keyframe animation in a binary buffer, with the following properties:
 327    * `url` the path to the file containing the buffer;
 328    * `numKeys`: the number of keys.
 329    * `byteOffset`: offset to the start of the buffer
 330
 331 The size of the buffer depends on the property being animated, where  the property value for each frame follows a 4 byte floating point value determining progress (between 0 and 1).
 332 :warning: Only `position` (3D vector of floats, 12 bytes), `rotation` (Quaternion, 12 bytes), and `scale` (3D vector, 12 bytes) properties are supported.
 333
 334 ### `keyFrames`
 335 JSON array of keyframe objects defined with the following properties:
 336    * `progress`: a scalar between `0` and `1` to apply to the duration to get the time stamp of the frame;
 337    * `value`: array of 3 or 4 numerical values depending on which property is being animated;
 338 :warning: Only `position`, `rotation`, and `scale` properties are supported.
 339
 340 ### `value`
 341 Value animations animate a property using a single value that may be absolute or relative.
 342 The properties it supports are the following:
 343    * `value`: the value to animate to (if absolute) or by (if `relative`);
 344    * `relative`: whether `value` is a target, or an offset;
 345
 346 # `animationGroups`
 347 Animation groups simply group animations together by name, under another name, which may be used to trigger them at the same time.
 348 ```js
 349   "animationGroups": [ {
 350     "name": "Idle",
 351     "animations": [ "IdleBody", "IdleFace" ]
 352   } ]
 353 ```