- Overview
- SceneShareConnection
- LiveSceneReader
- LiveScene
- LiveSceneTranslator
- LiveSceneEdits
- LiveSceneTransmitter
- LiveStatistics
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 } } } } }
LiveStatistics
Stores statistics related to the scene sharing.
public int snapperCount;
Number of snappers processed.
public int materialCount;
Number of materials.
public int meshCount;
Number of mesh instances.
public int uniqueMeshes;
Number of unique meshes.
public str->LiveCustomStatistics customStats();
Custom statistics.
public timespan readerTime;
Time spent in the reader.
public timespan translatorTime;
Time spent in the translator.
public timespan transmitterTime;
Time spent in the transmitter.
final public void putCustom(LiveCustomStatistics stats) {
Adds custom statistics.
final public void appendDumpData(StrBuf buf, int n=4) {
Dumps the statistics to a StrBuf
object using indentation of n.
final public str dumpData() {
Dumps the statistics to a string using default settings.
final public void dump() {
Dumps the statistics to the console using default settings.
LiveCustomStatistics
Allows extensions to store custom scene share statistics.
extend public str key() { return class.toS(); }
Returns unique identifier for the custom statistics object, which by default is the class name.
extend public void appendDumpData(StrBuf buf, int n=4) { }
Dumps the data to the specified StrBuf
, using the requested indentation. This method should be implemented by any custom statistics classes.
Comments
0 comments
Please sign in to leave a comment.