Org.simantics.scenegraph.loader

org.simantics.scenegraph.loader (SVN) is a set of utilities for loading and automatically updating structural org.simantics.scenegraph (SVN) models defined in org.simantics.scenegraph.ontology (SVN) .

Overview

The main goal of the scenegraph loader is to move the definition of scene graphs from code into the semantic data model. The main functionality is

• Instantiation of a scene graph structure from semantic graph with automatic change listening
• Automatic synchronization of scene graph node properties from semantic graph

Key features are

• Procedural properties and structure (via Layer0 Values and the runtime context resource)
• Reusable scene graph components (via Variable context)
• Support for multiple implementations of the same semantic model

Usage

Loading

The main entrypoint is org.simantics.scenegraph.loader.ScenegraphLoaderProcess. The public load methods are used to create a scene graph given a structural configuration resource (instance of http://www.simantics.org/Scenegraph-0.0/Node) and a (normally virtual) runtime context resource, which can be specific to each instance of a loaded scene graph.

ScenegraphLoaderProcess can be extended to customize

• The creation of the root node for the resulting scene graph
• The node loading logic. Standard node loading uses the adapter org.simantics.scenegraph.loader.ScenegraphLoader bound to node configuration resources. The logic can also be totally changed but the most common customization is to supply a subclass of ScenegraphLoader into which the resources are adapted. This makes it possible to define multiple adapters for the same node type (e.g. SWTScenegraphLoader->SWTNode, AWTScenegraphLoader->AWTNode).

Scene graph structure

The structure of the loaded scene graph is determined by the property relation http://www.simantics.org/Scenegraph-0.0/Node/children, which is evaluated in Variable context to a value with SCL type [Resource]. The given child resources are further adapted into Variable, loaded, and recursively traversed for children.

Unless the modeler has customized anything the standard variable implementation for scene graph nodes is org.simantics.scenegraph.loader.ScenegraphVariable, which is a standard graph-based variable with additional support for retrieving the runtime context resource discussed later. Customization can be done in standard adapters.xml fashion.

Typical non-procedural children for a node are defined by a standard http://www.simantics.org/Layer0-0.0/List.

Node loaders

A common node loading logic is defined in org.simantics.scenegraph.loader.ScenegraphLoaderUtils.create and used by org.simantics.scenegraph.loader.StandardScenegraphLoader. The loader receives a target class to instantiate and goes on to listen changes in all graph-defined properties. The loader expects the instantiated node to implement org.simantics.scenegraph.LoaderNode which provides a generic method getPropertyFunction for transferring values into the node. Implementation of LoaderNode is supported by e.g. org.simantics.scenegraph.ScenegraphUtils.getMethodPropertyFunction which uses reflection to call a specifically named method of the node in a specific thread each time a value changes. This method also does some datatype conversion black art so that the node can receive values in convenient Java classes which correspond to the wanted data type e.g.

public void synchronizeColor(RGB.Integer color) {
  this.color = Colors.awt(color);
  // do other state changes related to color changing here
}

The association of StandardScenegraphLoader with types is done in adapters.xml with e.g.

<target interface="org.simantics.scenegraph.loader.ScenegraphLoader">
  <type uri="http://www.simantics.org/Views-0.0/Composite" 
           class="org.simantics.scenegraph.loader.StandardScenegraphLoader">
    <this/>
    <bundle />
    <string>org.simantics.views.swt.client.impl.SWTComposite</string>
  </type>
</target>

Runtime context resource

The loader evaluates all properties of the nodes in Variable context, where the variable represents the flattened tree structure of the scene graph. The standard implementation (org.simantics.scenegraph.loader.ScenegraphVariable) supports an additional adapter class org.simantics.scenegraph.loader.ScenegraphContext, which gives access to the runtime context resource. The context can be used in property evaluation for e.g.

• Performing computations based on external input e.g. workspace selection
• Performing computations based on location e.g. diagram composite instance in a structural model.

Standard utilities for property value functions are collected in org.simantics.scenegraph.ScenegraphUtils and org.simantics.scenegraph.loader.ScenegraphLoaderUtils.