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
  44 :warning: The array must not be empty. Only the first element is used.
  45 An optional `scene` element with an integer value may be defined to specify the index of the first scene to be created.
  46 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).
  47 ```js
  48 {
  49     "scene": 0,
  50     "scenes": [ { "nodes": [ 0 ] } ],
  51     "nodes": [ {
  52         "name": "some_unique_name"
  53     } ]
  54 }
  55 ```
  56
  57 # `nodes`
  58 The 3D scene is built using a hierarchy of nodes, which are used to position the objects to render.
  59
  60 :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.
  61
  62 ## Transformations
  63 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.
  64    * A `matrix` array of 16 numerical values defining a column-major 4x4 matrix;
  65    * 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.
  66
  67 ## Size
  68 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.
  69
  70 ## Visibility
  71 The `visible` optional boolean property defines whether a node and its children are rendered (`true`) or not (`false`).
  72
  73 ## `children`
  74 An array of 0 or more indices into the top level `nodes` array, which shall inherit the transform and visibility of their parent node.
  75
  76 :warning: Nodes are processed in the order they are encountered during the depth-first traversal of the hierarchy.
  77 ```js
  78   "nodes": [ {
  79     "name": "hip",
  80     "children": [ 3, 1, 2 ]
  81   }, {
  82     "name": "spine"
  83   }, {
  84     "name": "left leg"
  85   }, {
  86     "name": "right leg"
  87   } ]
  88 ```
  89
  90 ## `customization`
  91 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.
  92 The definition of a `customization` is a single string tag:
  93 ```js
  94   "nodes": [ {
  95     "name": "Soup du jour",
  96     "customization": "flavor", // this one
  97     "children": [ 1, 2, 3 ]
  98   }, {
  99     "name": "Broccoli and Stilton",
 100   }, {
 101     "name": "Butternut Squash",
 102   }, {
 103     "name": "Strawberry and Cream",
 104   } ]
 105 ```
 106 :warning: Customizations and renderables are mutually exclusive on the same node.
 107
 108 ## Renderables
 109 There is support for two types of nodes that define renderable content.
 110 The definition of these renderables come in sub-objects.
 111 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).
 112
 113 :warning: Customizations and renderables are mutually exclusive on the same node.
 114
 115 ### `model`
 116 Provides definition for a 3D object, which requires a `mesh`, `shader` and `material`.
 117 Each of these are provided in form of an integer index into the related top-level array of the DLI document.
 118
 119 :warning: `mesh` must be provided; the rest are optional and default to 0.
 120 ```js
 121   "nodes": [ {
 122     "name": "Sphere",
 123     "model": {
 124       "mesh": 0, // required
 125       "shader": 0, // optional, defaults to 0
 126       "material": 1 // optional, defaults to 0
 127     }
 128   } ]
 129 ```
 130
 131 ### `arc`
 132 Arc is a specialisation of a model that allows the rendering of circular progress bars. As such, it also must provide a `mesh` ID.
 133 ```js
 134   "nodes": [ {
 135     "name": "Any Name",
 136     "arc": {
 137       "mesh": 0, // required
 138       "shader": 0, // optional, defaults to 0
 139       "material": 1 // optional, defaults to 0
 140       "antiAliasing": true,
 141       "radius": -0.928,
 142       "startAngle": -81.0,
 143       "endAngle": 261
 144     }
 145   } ]
 146 ```
 147    * `startAngle` and `endAngle` are the angular positions where the arc starts and ends, in degrees.
 148    * `radius` is the inner radius of the arc, the outer radius being defined by the [`size`](#size) of the node.
 149    * `antiAliasing` defines whether the edges of the arc should be smoothed.
 150
 151 ## `inverseBindPoseMatrix`
 152 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.
 153 ```js
 154   "nodes": [ {
 155     "name" : "l_shoulder_JNT",
 156     "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 ]
 157   } ]
 158 ```
 159
 160 # `environment`
 161 An array of environment map definitions, which have the following format:
 162 ```js
 163   "environment": [{
 164     "cubeSpecular": "Studio_001/Radiance.ktx",
 165     "cubeDiffuse": "Studio_001/Irradiance.ktx",
 166     "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 ]
 167   } ]
 168 ```
 169 `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.
 170 `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.
 171
 172 # `materials`
 173 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).
 174 ```js
 175   "materials": [ {
 176     "environment": 0,
 177     "albedoMap": "A.png",
 178     "normal": "N.png",
 179     "metallicRoughnessMap": "MR.png",
 180     "color": [ 1.0, 0.8, 0.7, 0.5 ]
 181   } ]
 182 ```
 183    * `environment`: The index of the [environment map](#environments) to use. Single integer, defaults to `0`.
 184    * `mipmap`: A boolean to speficy if the creation and sampling of mipmaps should be enabled. Off by default.
 185    * `color`: Base color, which the color of the node gets multiplied by. Defaults to white.
 186    * `metallic` and `roughness`: Properties for PBR materials; both are expected to be a single numerical value and default to `1.0`.
 187
 188 ## Texture maps
 189 `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.
 190
 191 :warning: Semantics shall not overlap within the same material, e.g. multiple albedo definitions, or albedo and albedoMetallic.
 192
 193 # `meshes`
 194 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.
 195 Those models loaded from a file may provide an accessor, and flag its presence in the `attributes` bitmask property. The following are supported:
 196 |Attribute Name|Bit|Decimal value|Type|Remarks|
 197 |-|-|-|-|-|
 198 |`indices`  |0|  1|unsigned short||
 199 |`positions`|1|  2|Vector3||
 200 |`normals`  |2|  4|Vector3||
 201 |`textures` |3|  8|Vector2|UVs|
 202 |`tangents` |4| 16|Vector3||
 203 |           |5| 32||Ignored, but reserved for bitangents|
 204 |`joints0`  |6| 64|Vector4|Joint IDs for skinned meshes|
 205 |`weights0` |7|128|Vector4|Joint weights for skinned meshes|
 206
 207 E.g. if positions, normals and tangents are provided, the `attributes` property must have a value of 2 + 4 + 16 = 22.
 208 Each attribute must provide a `byteOffset` and `byteLength` property, which must be correctly sized for the type of the given attribute.
 209 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`.
 210
 211 ## Skinned meshes
 212 DLI supports meshes that allow deformation by skeletal animation. These must define a few additional properties:
 213    * `joints0` and `weights0` attributes, as above.
 214    * A [`skeleton`](#skeletons) ID, to specify which (joint) nodes' transformations affect the mesh.
 215
 216 :warning: The maximum number of bones supported by DALi Scene Loader is `64`.
 217
 218 ## Blend shapes
 219 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`.
 220 ```js
 221   "meshes": [ {
 222       "uri": "example.bin",
 223       "attributes": 2,
 224       "positions": {
 225           "byteOffset": 0,
 226           "byteLength": 12000
 227       },
 228       "blendShapesHeader": {
 229           "version": "2.0",
 230           "byteOffset": 12000,
 231           "byteLEngth": 4
 232       },
 233       "blendShapes": [ {
 234           "weight": 0.0,
 235           "positions": {
 236               byteOffset: 12004,
 237               byteLength: 12000
 238           }
 239       } ]
 240   } ]
 241 ```
 242 A `blendShapesHeader`, if present, must define:
 243    * 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.
 244    * 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.
 245
 246 The `blendShapes` array then defines the shapes that are available to blend between, comprising of:
 247    * An initial `weight` numerical, the default is 0;
 248    * `position` / `normals` / `tangents` attributes, which must be also present in the base mesh and are the same format (`byteOffset` / `byteLength`);
 249
 250 :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.
 251
 252 # `shaders`
 253 Provides an array of shader programs that renderables may use for rendering.
 254 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.
 255    * `rendererState`: This string defines the options for configuring the settings of the renderer. Refer to public-api/renderer-state.h for details.
 256    * `defines`: An optional array of strings which will be used to create #defines into the vertex and fragment shaders.
 257    * `hints`: An optional array of strings that map to `Dali::Shader::Hint` values. Therefore two values are supported - `MODIFIES_GEOMETRY` and `OUTPUT_IS_TRANSPARENT`.
 258
 259 ## Uniforms
 260 Every property that is not one of the reserved keys above, will be attempted to be registered as a uniform of the same name.
 261
 262 :warning: Boolean values will be converted to floating point 1.0 (for `true`) or 0.0 (for `false`).
 263
 264 :warning: Integer values will be converted to floating point.
 265
 266 :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.
 267 ```js
 268   "shaders": [ {
 269     "vertex": "dli_pbr.vsh",
 270     "fragment": "dli_pbr.fsh",
 271     "defines": [ "HIGHP", SKINNING" ],
 272     "rendererState": "DEPTH_WRITE|DEPTH_TEST|CULL_BACK",
 273     "hints":
 274     "uMaxLOD": 6
 275   } ]
 276 ```
 277
 278 # `skeletons`
 279 Skeletons in DLI simply define the name of a `node` that shall serve as the _root joint_ of the given skeleton.
 280 ```js
 281   "skeletons": [ {
 282     "node": "hipJoint"
 283   } ]
 284 ```
 285 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.
 286
 287 # `cameras`
 288 Define the transformation of viewers and the projection used by them.
 289 All cameras may define:
 290    * `matrix`: an array of 16 numerical values for the transform matrix
 291    * `near` and `far` values for the position of the respective clipping planes. These default to `0.1` and `1000.0`, respectively.
 292
 293 ## Perspective cameras
 294 This projection type - and a vertical field of view of `60` degrees - is the default.
 295 The (V)FOV can be specified in the `fov` property, as a single numerical value.
 296
 297 ## Orthographic cameras
 298 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.
 299
 300 # `lights`
 301 Define parameters for a single light source - the implementation is up to the application. The following properties are supported.
 302    * `transform`: matrix of 16 numerical values for the positioning / directing of the light;
 303    * `color`: array of 3 components for RGB;
 304    * `intensity`: single float;
 305    * `shadowIntensity`: single float;
 306    * `shadowMapSize`: unsigned integer size (same width & height) of shadow map.
 307    * `orthographicSize`: single float to define the size (same width & height) of orthographic position.
 308
 309 # `animations`
 310 Animations provide a way to change properties of nodes (and those of their renderables) over time.
 311 ```js
 312   "animations": [ {
 313      "name": "Idle",
 314      "loopCount": 0,
 315      "duration": 4.0,
 316      "endAction": "DISCARD",
 317      "disconnectAction": "DISCARD",
 318      "properties": []
 319   } ]
 320 ```
 321    * `name`: the identifier to look the animation up by;
 322    * `loopCount`: the number of times that the animation should be played. The default is `1`; `0` signifies infinity repetitions.
 323    * `duration`: the duration of the animation in seconds. If not provided, it will be calculated from the properties.
 324    * `endAction` and `disconnectAction`: the supported values, defaults and their meaning are described in the `Dali::Animation::EndAction` enum;
 325
 326 ## `properties`
 327 An array of animation property definitions.
 328    * `node`: the name of the node whose property shall be animated;
 329    * `property`: the name that the property was registered under.
 330    * `alphaFunction`: the name of an alpha function which shall be used in animating a value, or between key frames;
 331    * `timePeriod`: `delay` (defaults to `0.0`) and `duration` (defaults to the `duration` of the animation) of the property animation, in sceonds;
 332
 333 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.
 334
 335 ### `keyFramesBin`
 336 JSON object that defines a keyframe animation in a binary buffer, with the following properties:
 337    * `url` the path to the file containing the buffer;
 338    * `numKeys`: the number of keys.
 339    * `byteOffset`: offset to the start of the buffer
 340
 341 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).
 342
 343 :warning: Only `position` (3D vector of floats, 12 bytes), `rotation` (Quaternion, 12 bytes), and `scale` (3D vector, 12 bytes) properties are supported.
 344
 345 ### `keyFrames`
 346 JSON array of keyframe objects defined with the following properties:
 347    * `progress`: a scalar between `0` and `1` to apply to the duration to get the time stamp of the frame;
 348    * `value`: array of 3 or 4 numerical values depending on which property is being animated;
 349
 350 :warning: Only `position`, `rotation`, and `scale` properties are supported.
 351
 352 ### `value`
 353 Value animations animate a property using a single value that may be absolute or relative.
 354 The properties it supports are the following:
 355    * `value`: the value to animate to (if absolute) or by (if `relative`);
 356    * `relative`: whether `value` is a target, or an offset;
 357
 358 # `animationGroups`
 359 Animation groups simply group animations together by name, under another name, which may be used to trigger them at the same time.
 360 ```js
 361   "animationGroups": [ {
 362     "name": "Idle",
 363     "animations": [ "IdleBody", "IdleFace" ]
 364   } ]
 365 ```