Instancing - Provide Symbol and Instance Nodes

A SceneJS.Symbol is a scene node that marks its subgraph as a "symbol" which can be then instanced with SceneJS.Instance nodes.

This node type is useful for keeping scene size small, while also simplifying editing of a scene; when you edit content within a Symbol, all instances of the Symbol update to reflect the edits.

Function

When rendered, SceneJS will register this node against its specified name and prevents SceneJS from traversing into its subgraph. The content defined within the Symbol will therefore only be rendered when it is instanced. The registered name will be actually be the concatenation of the specified name with the namespace formed by
any enclosing SceneJS.Name nodes. When SceneJS then finds a SceneJS.Instance node that refers to the registered name, it will instantiate the Symbol's child nodes as if they were children of the Instance node.

Impact on Memoisation

Memoisation will be synchronised accordingly. Within every subgraph, SceneJS internally memoises whatever state it determines will not change between scene traversals. SceneJS may therefore be restricted in what state it can memoise within a Symbol's subgraph when it is likely to be dynamically affected by the different scene locations it which it is instanced.

Example Usage

Here we're defining a Symbol in a Name, then instantiating it three times with Instance nodes to show variations on how an Instance node can refer to a Symbol, relative to a namespace created by a Name node:

// Define a "teapot" symbol inside a namespace.
// Note that the Name is not mandatory.

SceneJS.name({name: "mySymbols"},
    SceneJS.symbol({ name: "teapot" },
        SceneJS.objects.teapot()
    ),

    // Instance the teapot Symbol from inside the namespace.
    // See how the symbol reference is relative, where it
    // does not start with a '/'.

    SceneJS.instance({name: "teapot" })
),

// Instance the teapot Symbol again, from outside the namespace

SceneJS.instance({name: "mySymbols/teapot"}),

// Instance the teapot Symbol one more time from outside the
// namespace to show how an absolute path can be specified to
// the Symbol

SceneJS.instance({name: "/mySymbols/teapot"})