1. Overview
2. SceneShareConnection
   • Usage Example
3. LiveSceneReader
4. LiveScene
   • LiveSceneEntry
   • LiveSceneMesh
   • LiveSceneMaterial
5. LiveSceneTranslator
   • LeftHandedSceneTranslator
   • Implementing a custom translator
6. LiveSceneEdits
   • LiveSceneEditOp
7. LiveSceneTransmitter
   • Implementing a custom transmitter
8. LiveStatistics
   • LiveCustomStatistics

Overview

The purpose of the scene share API is to allow developers to easily implement extensions that allow CET drawings to be shared with external renderers. The API and its related code is located in the cm.abstract.sceneShare package.

The scene share API consist of five main components:

• SceneShareConnection
• LiveSceneReader
• LiveScene
• LiveSceneTranslator
• LiveSceneTransmitter

The figure above shows how the data flows between the different components.

An overview of each component is provided in the following sections.

SceneShareConnection

The scene share pipeline is managed by the SceneShareConnection class. It uses the reader to populate or update a LiveScene object. The LiveScene object is then passed to the translator to prepare it for export. Once the scene is ready for export it is passed to the transmitter object.

    final public void configure(LiveSceneReader reader,
                                LiveSceneTranslator translator,
                                LiveSceneTransmitter transmitter) {

Configures the reader, translator and transmitter to be used by the connection. The reader and transmitter are required while the translator is optional, but usually needed since most external renderers use different coordinate systems and/or units.

    final public void linkTo(Space space) {

Links the connection to a space.

    final public void unlinkFrom(Space space) {

Unlinks the connection from a space.

    final public void flush() {

Flushes any outstanding changes to transmitter. A simplified overview of what the process looks like is provided below:

public void flush() {
    // ...

    if (!scene) {
        scene = reader.readFrom(space, stats);
    } else {
        reader.updateScene(scene, space, edits, stats);
    }

    // ...

    translator.translate(scene, edits, stats);

    // ...

    transmitter.send(scene, edits, stats);

    // ...
}

Usage Example

The following example shows how the main space can be exported:

{
    SceneShareConnection con = mainSceneShareConnection();
    Primitive3DSceneReader reader();

    // convert from right-handed to left-handed coordinate system and
    // scale units to centimeters.
    LeftHandedSceneTranslator translator(distanceUnit.cm);

    // just output trace of the scene
    TraceOnlySceneTransmitter transmitter();
    con.configure(reader, translator, transmitter);
    con.linkTo(mainSpace());
    con.flush();

    // we are done now, so unlink from the space
    con.unlinkFrom(con.space);
}

LiveSceneReader

The reader is responsible for fetching data from a space and populating the live scene with appropriate objects. An implementation of a reader is available in the form of the Primitive3DSceneReader class that should cover most use cases.

    extend public LiveScene readFrom(Space space, LiveStatistics stats) : abstract { }

Creates a new LiveScene object and populates it with data from a Space object.

    extend public LiveSceneEdits updateScene(LiveScene scene, Space space, LiveSceneEdits edits, LiveStatistics stats) : abstract { }

Updates an existing scene with changes from the space.

LiveScene

Contains the objects and materials that should be shared with the external renderer. It is populated by the scene reader and will be passed to the transmitter for export.

    public str->LiveSceneEntry entries;

Entries contained in the scene.

    public materialId->LiveSceneMaterial materials;

Maps materials identifiers to LiveSceneMaterial objects.

    public Material3D->materialId materialToId;

Maps Material3D objects to material identifiers.

    final public void put(LiveSceneEntry e) {

Adds a LiveSceneEntry to the scene.

    final public LiveSceneEntry get(str id) {

Returns the LiveSceneEntry with the specified id, or null if no such entry exists.

    final public void remove(str id) {

Removes the entry with the specified identifier.

    final public materialId put(Material3D m) {

Adds a Material3D to the scene.

LiveSceneEntry

Each LiveSceneEntry corresponds to an entity in the scene. These entries will be created by the reader and then possibly modified by the translator. The entries can contain one or more meshes that should be exported.

    public guid id;

Unique and persistent identifier for this entry.

    public str name;

User readable name for this entry.

    public point pos;

Absolute position of the entry in the world.

    public orientation rot;

Absolute orientation of the entry in the world.

    public point pivotPoint;

Pivot point of the entry.

    public LiveSceneMesh[] meshes = null;

Meshes associated with this entry. These will be the visual representation of the entry in the external renderer.

    final public void initMeshes(int capacity) {

Makes room for the specific number of meshes.

    final public void clearMeshes() {

Removes any meshes added to the entry.

    final public LiveSceneMesh[] operator<<(LiveSceneMesh imesh) {

Adds a mesh to the scene entry.

    final public LiveSceneMesh[] operator<<(LiveSceneMesh[] imeshes) {

Adds a number of meshes to the scene entry.

    extend public str uid() {

Returns the unique identifier for this scene entry.

LiveSceneMesh

Stores mesh related data for a scene entry.

    public ATriMeshF mesh;

Triangle mesh associated with this mesh object.

    public materialId material;

Id of the material used by this mesh. This should correspond to a key in the materials map in the LiveScene object.

    public str name;

Optional mesh name.

LiveSceneMaterial

Stores data related to materials that are to be exported. These objects are created by the scene reader in the readFrom and updateScene methods.

    public Material3D m;

Material3D object associated with this material object.

LiveSceneTranslator

The translator makes necessary adjustments to the scene to make it conform to the requirements of the external renderer. This includes things like unit conversion and changing coordinate system. If no translator is provided, the scene will retain the same coordinate system and units as those used by CET.

    extend public LiveSceneEdits translate(LiveScene scene, LiveSceneEdits edits, LiveStatistics stats) : abstract { }

Applies necessary adjustments to the scene.

LeftHandedSceneTranslator

This translator applies the following modifications to the scene:

• Converts from right-handed to left-handed coordinate system.
• Applies appropriate uniform scale depending on requested units

The change of coordinate system is done by negating the x-axis while leaving the other axes unchanged. A uniform scaling is then applied that converts the scene from meters to the requested unit.

    public constructor() {

Initializes the translator to use meters.

    public constructor(distanceUnit _unit) {

Initializes the translator to the specified unit.

    public distanceUnit unit;

Unit used by the targeted external renderer.

Implementing a custom translator

Most external renderers use slightly different coordinate systems or units, so it is likely that a new translator will be required when targeting a new external renderer.

To create a custom translator, extend the LiveSceneTranslator and implement the translate method. This method should modify the scene to match the requirements of the target renderer.

public class MySceneTranslator extends LiveSceneTranslator {

  public LiveSceneEdits translate(LiveScene scene,
                                  LiveSceneEdits edits,
                                  LiveStatistics stats) {
      // apply any changes required to the scene.
      for (k, e in scene.entries) {
          // modify LiveSceneEntry object e
      }
      return edits;
  }

}

LiveSceneEdits

The LiveSceneEdits class describes any changes that have been made to the scene. This allows the transmitter to potentially only send the entries that have been modified.

    public bool allInvalidated;

If set to true, any previous state should be regarded as invalid and the entire scene should be transmitted.

    final public bool any() {

Returns whether there have been any modifications to the scene.

    final public void invalidate() {

Invalidates the scene.

LiveSceneEditOp

This class contains information about an editing operation.

package enum editOperation : field access {
    none;
    moved;
    remove;
    add;
    update;
};

The different types of editing operations.

    public editOperation editOp;

The type of editing operation.

    public guid objectID;

Identifier of the original Snapper/Singularity/Vessel.

    public guid sceneEntryId;

Identifier of the affected scene entry.

LiveSceneTransmitter

The transmitter is responsible for actually sending the data to the external renderer. This means that each renderer targeted by the scene sharing functionality must have its own associated transmitter.

    extend public void send(LiveScene scene, LiveSceneEdits edits, LiveStatistics stats) : abstract { }

Invoked by the connection when there are changes that should be sent to the external renderer. Any custom transmitter is required to provide an implementation of this method.

Implementing a custom transmitter

Extend the LiveSceneTransmitter class and implement the send function.

/**
 * My Custom Scene Transmitter.
 */
public class MyCustomSceneTransmitter extends LiveSceneTransmitter {
    
    /**
     * Send scene.
     */
    public void send(LiveScene scene,
                     LiveSceneEdits edits,
                     LiveStatistics stats) {
        if (edits.allInvalidated) {
            // entire scene should be transmitted.
            for (k, e in scene.entries) {
                // send LiveSceneEntry e
            }
        } else {
            // only those changes specified by the edits parameter need
            // to be transmitted.
            for (editop in edits.editOps) {
                if (editop.editOp == editOperation.remove) {
                    // remove the scene entry from external renderer
                } else {
                    LiveSceneEntry entry = scene.entries.get(eop.sceneEntryId);
                    // handle other edit operations types here
                }
            }
            
        }
    }
}

    public int snapperCount;

    public int materialCount;

    public int meshCount;

    public int uniqueMeshes;

    public str->LiveCustomStatistics customStats();

    public timespan readerTime;

    public timespan translatorTime;

    public timespan transmitterTime;

    final public void putCustom(LiveCustomStatistics stats) {

    final public void appendDumpData(StrBuf buf, int n=4) {

    final public str dumpData() {

    final public void dump() {

    extend public str key() { return class.toS(); }

    extend public void appendDumpData(StrBuf buf, int n=4) { }