.. index::
    pair: Scene; Pipeline

.. highlight:: javascript

==================
The Scene Pipeline
==================

The scene pipeline supports the export of scenes from 3D modeling packages via Collada.

For a given Collada scene the `dae2json` tool will export the following elements:

* Shapes
* Materials
* Effects
* Images
* Physics models
* Physics materials
* Physics bodies
* Animations
* Lights
* Cameras
* Nodes hierarchy

Materials, effects and lights can be overloaded at this stage or later at runtime.
The `dae2json` tool supports passing `include` files that provide material, effect and light overloads.
Overloads from the include files will be matched by name and will replace the elements from the Collada scene.

.. _scene_pipeline_json:

This is an example of how a JSON `include` file would look:::

    {
      "version": 1,
      "lights":
      {
        "point_light_1":
        {
          "type": "point",
          "color": [1, 1, 1],
          "material": "squarelight",
          "halfextents": [10, 20, 10]
        },
        "spot_light_1":
        {
          "type: "spot",
          "color": [0.89, 1, 0.99],
          "material": "conelight",
          "right": [0, 6, 26],
          "up": [21, 0, 0],
          "target": [0, -36, 9],
          "shadows": true
        }
        "directional_light":
        {
          "type": "directional",
          "color": [0.2, 0.2, 0.8],
          "direction": [0, -1, 0],
          "global": true
        },
        "red_ambient":
        {
          "type": "ambient",
          "color": [0.1, 0, 0],
          "global": true
        },
      },
      "effects":
      {
        "lambert-fx":
        {
          "type": "lambert",
          "meta":
          {
            "normals": true
          }
        }
      },
      "materials":
      {
        "squarelight":
        {
          "parameters":
          {
            "lightfalloff": "squarelight.dds",
            "lightprojection": "squarelight.dds"
          }
        },
        "conelight":
        {
          "parameters":
          {
            "lightfalloff": "white",
            "lightprojection": "roundlight.jpg"
          }
        },
        "rocket_colored":
        {
          "effect": "lambert-fx",
          "parameters":
          {
            "color": [1, 0.2, 0, 0.5],
            "diffuse": "textures/rocket.dds"
          },
          "meta":
          {
            "collisionFilter": [ "ALL" ],
            "noshadows": true,
            "transparent": true,
            "materialcolor": true
          }
        }
      },
    }

These include files can be generated by hand or exported from other source assets,
a Collada scene file can be exported passing as many of them as needed as parameters to the tool.

The :ref:`dae2json <dae2json>` tool automatically converts Collada scenes to have 1 unit per meter and the Y vector to point upwards,
some modeling packages may use different conventions.

For details on generating your own JSON files see the :ref:`Turbulenz Engine JSON formats <turbulenz_json_format>` documentation.

--------
Workflow
--------

* Model scene in 3D modeling package
* Export scenes to Collada (one or more Collada scene files)
* Create `include` files with an editor supporting JSON or JavaScript
* Execute `dae2json` on each Collada file, include files if required
* Load converted scenes into user application


---------------------------
Collada feature limitations
---------------------------

Certain features supported in the Collada specification are not supported or have limited support, these limitations
are documented below.

* `instance_node` with internal url - An instance_node in a Collada scene will be correctly inserted into the converted scene but will
  have been de-instanced. As a result any operations made to the source node at runtime will not be propagated
  automatically to its instances.

* `instance_node` with external url - References to other Collada scene files will be inserted into the converted scene
  and the whole external hierarchy will be de-instanced at runtime. This may not be the required result if the reference was
  not linking to the root node of the external scene.