Code Structure#

Libraries#

Here is an incomplete list of libraries that are involved to build the OpenSpace executable.

classDiagram Ghoul --> openspace-core Ghoul --> openspace-module-atmosphere Ghoul --> openspace-module-base Ghoul --> openspace-module-globebrowsing Ghoul --> openspace-module-space openspace-core --> openspace-module-atmosphere openspace-module-atmosphere --> openspace-module-collection openspace-core --> openspace-module-base openspace-module-base --> openspace-module-collection openspace-core --> openspace-module-space openspace-module-space --> openspace-module-collection openspace-core --> openspace-module-globebrowsing openspace-module-globebrowsing --> openspace-module-collection GDAL --> openspace-module-globebrowsing openspace-core --> openspace-module-volume openspace-core --> openspace-module-kameleon openspace-kameleon --> openspace-module-kameleonvolume openspace-volume --> openspace-module-kameleonvolume openspace-core --> openspace-module-kameleonvolume GLFW --> SGCT SGCT --> OpenSpace openspace-core --> OpenSpace openspace-module-collection --> OpenSpace

  • Ghoul is a helper library that contains classes and functions that are useful beyond just OpenSpace

  • SGCT is a library that helps with cluster synchronization and window creation

  • openspace-core contains the core elements of the “game engine” part of OpenSpace, such as the handling of the scene graph, scripting, rendering, interaction methods, navigation, and others

  • Functionality is divided into Modules that can that implement abstract classes defined in the openspace-core. Modules can depend on other modules and even other third-party libraries

  • Modules are collected in the openspace-module-collection which in itself does not contain any additional code

  • The OpenSpace application consists of SGCT, openspace-core, and the openspace-module-collection

Classes#

The openspace-core project contains all of the fundamental classes that are needed for the engine part of OpenSpace. These include a SceneGraphNode which is collected into a Scene. The Scene has one special SceneGraphNode called the Root, which is the only scene graph node without a parent. A few of these are abstract base classes which are then derived from in other modules and thus filled with functionality.

Examples of these abstract classes are:

  • Renderable: A class that represents anything that is rendered within the 3D scene and shows up on screen

  • Translation: A class that describes some form of translation relative to the scene graph node’s parent

  • Rotation: A class that describes some form of rotation relative to the scene graph node’s parent

  • Scale: A class that describes some form of scaling relative to the scene graph node’s parent

  • ScreenSpaceRenderable: A class that renders something on the screen but is not affected by the camera movement

classDiagram namespace core { class RenderEngine { +render() +renderOverlays() } class Scene { +update() +render() } class PropertyOwner { - std::string _identifier - std::string _guiName - PropertyOwner _owner - std::vector<PropertyOwner*> _subOwners } class Property { - std::string _identifier - _guiName + set(std::any) - std::any get() } class SceneGraphNode { +initialize() +initializeGL() +deinitialize() +deinitializeGL() +update(UpdateData) +render(RenderData) } class Renderable { +initialize() +initializeGL() +deinitialize() +deinitializeGL() +update() +render() } class Translation { +position() } class Rotation { +matrix() } class Scale { +scaleValue() } class ScreenSpaceRenderable { +initialize() +initializeGL() +deinitialize() +deinitializeGL() +update() +render() } } namespace openspace-base { class RenderableGrid class RenderableSphere class ScreenSpaceImageLocal class StaticTranslation class TimelineTranslation class StaticRotation class StaticScale } namespace openspace-space { class RenderableStars class SpiceTranslation } namespace openspace-globebrowsing { class RenderableGlobe } PropertyOwner <|-- SceneGraphNode PropertyOwner <|-- Renderable PropertyOwner <|-- Translation PropertyOwner <|-- Rotation PropertyOwner <|-- Scale PropertyOwner <|-- Scene PropertyOwner <|-- ScreenSpaceRenderable PropertyOwner <|-- RenderEngine PropertyOwner "1" --> "*" Property RenderEngine "1" --> "1" Scene RenderEngine "1" --> "0..1" ScreenSpaceRenderable Scene "1" --> "*" SceneGraphNode SceneGraphNode "1" --> "0..1" Renderable SceneGraphNode "1" --> "0..1" Translation SceneGraphNode "1" --> "0..1" Rotation SceneGraphNode "1" --> "0..1" Scale Renderable <|-- RenderableGrid Renderable <|-- RenderableSphere ScreenSpaceRenderable <|-- ScreenSpaceImageLocal Translation <|-- StaticTranslation Translation <|-- TimelineTranslation Rotation <|-- StaticRotation Scale <|-- StaticScale Renderable <|-- RenderableStars Translation <|-- SpiceTranslation Renderable <|-- RenderableGlobe

Assets#

All content is controlled through the inclusion of assets. Assets are fundamentally Lua scripts that have access to a special variable asset which is injected by OpenSpace. This variable has a few functions that allow the asset to affect OpenSpace. A selection of these functions are:

  • asset.require: Causes this asset to load another asset file, the path of which is provided either as a relative or absolute path. This function returns a table that contains all of the symbols that were asset.exported by the required asset (see below)

  • asset.onInitialize: This function takes a function as an argument which is executed when the asset is asked to initialize itself. A common use case for this is for the asset to add a scene graph node to the scene in OpenSpace

  • asset.onDeinitialize: Analogously to the onInitialize, the function passed as an argument into this function is called when the asset is to be unloaded

  • asset.export: Export a single element to anyone that asset.requires this asset.

Through the user of the asset.require function, assets form a tree where a Parent requires their Children.

Simple Example#

In this example, the child asset simply defines a variable that is then read by the parent asset and printed to the console.

-- Define a local table variable
local Green = { 0.0, 1.0, 0.0 }

-- Export the table under the name "Color", making it available to everyone requiring it
asset.export("Color", Green)

-- Include the child asset and store the resulting table in a local variable
local child = asset.require("./example1_child")

-- Register a function that is called when the asset should be initialized
asset.onInitialize(function()
  -- openspace.printInfo is a function defined that will print the passed parameter
  -- Here, we access the 'Color' variable out of the child's table
  openspace.printInfo(child.Color)
end)

Advanced Example#

In this example, the child asset is defining, adding, and exporting a scene graph node that is used in the parent asset to specify the parent of a scene graph node.

local Node = {
  -- Every scene graph node needs an identifier
  Identifier = "ExampleNode",
  -- Moving the scene graph node relative to its parent
  Transform = {
    Translation = {
      Type = "StaticTranslation",
      -- Moving the node by 10 meters along the x axis
      Position = { 10, 0, 0 }
    },
    Rotation = {
      Type = "StaticRotation",
      -- Use a rotation by 180 degrees around the y axis
      Rotation = { 0, math.pi / 4, 0 }
    },
    Scale = {
      Type = "StaticScale",
      -- Scale the node up by a factor of 2
      Scale = 2.0
    }
  },
  Renderable = {
    -- Just render three lines, one for each axis
    Type = "RenderableCartesianAxes"
  }
}

asset.onInitialize(function()
  -- We initializing the asset, we want to add the node to the scene graph
  openspace.addSceneGraphNode(Node)
end)

asset.onDeinitialize(function()
  -- When deinitializing, we remove the node from the scene graph
  openspace.removeSceneGraphNode(Node)
end)

-- Making the node available to others
asset.export("Node", Node)

-- We want to load the child asset first and store its result
local example = asset.require("./example2_child")

local Node = {
  Identifier = "Grid",
  -- To define the parent of this node, we access the 'Node' table exported by the child
  -- asset and access its 'Identifier' key
  Parent = example.Node.Identifier,
  Transform = {
    Rotation = {
      Type = "StaticRotation",
      -- Use a rotation by 90 degrees around the z axis
      Rotation = { 0, 0, math.pi / 8 }
    }
  },
  Renderable = {
    -- We want to render a grid
    Type = "RenderableGrid"
  }
}

asset.onInitialize(function()
  -- We initializing the asset, we want to add the node to the scene graph
  openspace.addSceneGraphNode(Node)
end)

asset.onDeinitialize(function()
  -- When deinitializing, we remove the node from the scene graph
  openspace.removeSceneGraphNode(Node)
end)