ScreenSpaceRenderableRenderable

Inherits ScreenSpaceRenderable

This ScreenSpaceRenderable object can render any Renderable type into an image that is shown in screen space. This can be used to display a rendered object as an overlay in front of the regular 3D rendering of the scene.

Note that to use this ScreenSpaceRenderable, it might be necessary to specify the size parameter, which determines the resolution of the inset window into which the Renderable is rendered. For many use cases, the default should suffice, however.

A possible use-case for the ScreenSpaceRenderable would be to show a 3D model of a spacecraft without the need to place it at a position in the 3D scene with the need to fly to that object to talk about it.

Members

Name	Documentation	Type	Description	Optional
Renderable	The Renderable object that is shown in this ScreenSpace object. See the list of creatable renderable objects for options that can be used for this type.	Table	Renderable	No
CameraCenter	The location of the camera’s focal point. The camera’s view direction will always be pointing at the provided center location. This position is provided in meters.	Vector3<double>	Value of type ‘Vector3’	Yes
CameraFov	The camera’s field of view in degrees.	Double	Value of type ‘Double’	Yes
CameraPosition	Specifies the location of the virtual camera that is showing the renderable class. This position is provided in meters.	Vector3<double>	Value of type ‘Vector3’	Yes
CameraUp	The direction that is ‘up’ for the provided camera. This value does not have any units.	Vector3<double>	Value of type ‘Vector3’	Yes
Identifier		String	Value of type ‘String’	Yes
Time	Specifies the start date that is used to control the renderable and the transforms. If no value is specified the date of 2000 JAN 01 12:00:00 is used instead.	Date and time	Value of type ‘Date and time’	Yes
Transform	The collection of transformations that are applied to the Renderable before it is shown on screen.	Table	Table parameters	Yes

Inherited members from ScreenSpaceRenderable

Name	Documentation	Type	Description	Optional
Type	The type of the ScreenSpaceRenderable that is to be created.	String	Must name a valid ScreenSpaceRenderable	No
BackgroundColor	A fixed color that is combined with the screen space renderable to create the final color. The actual color of the screen space renderable is alpha-blended with the background color to produce the final result.	Color4	Value of type ‘Color4’	Yes
BorderColor	The color of the border.	Color3	Value of type ‘Color3’	Yes
BorderFeather	If this value is enabled and a border width is set, the border will be rendered as a feathered border rather than a hard corner.	Boolean	Value of type ‘Boolean’	Yes
BorderWidth	The width of the border.	Double	Greater than: 0	Yes
CartesianPosition	Determines the position of this screen space plane in Cartesian three-dimensional coordinates (meters).	Vector3<double>	Value of type ‘Vector3’	Yes
Enabled	Determines whether this sceen space object will be rendered or not.	Boolean	Value of type ‘Boolean’	Yes
FaceCamera	If enabled, the object will be rotated to face the camera position. Any local rotation is then applied after this rotation.	Boolean	Value of type ‘Boolean’	Yes
GammaOffset	Sets the gamma correction of the texture that is applied in addition to the global gamma value.	Double	Value of type ‘Double’	Yes
Identifier	The unique identifier for this screen space renderable. It has to be unique amongst all existing screen space nodes that have been added to the scene.	Identifier	An identifier string. May not contain ‘.’, spaces, newlines, or tabs	Yes
MultiplyColor	If set, the plane’s texture is multiplied with this color. Useful for applying a color grayscale images.	Color3	Value of type ‘Color3’	Yes
Name	The name of the ScreenSpaceRenderable, which will be shown in the GUI. This does not have to be unique to the scene, but it is recommended to be.	String	Value of type ‘String’	Yes
Opacity	The opacity of the screen space object. If 1, the object is completely opaque. If 0, the object is completely transparent.	Double	In range: ( 0,1 )	Yes
RadiusAzimuthElevation	Determines the position of this screen space plane in a coordinate system based on radius (meters), azimuth (radians), and elevation (radians).	Vector3<double>	Value of type ‘Vector3’	Yes
RenderDuringBlackout	If true, this screen space renderable is going to ignore the global blackout factor from the Render Engine and will always render at full opacity. If false, it will adhere to the factor and fade out like the rest of the 3D rendering.	Boolean	Value of type ‘Boolean’	Yes
Rotation	An Euler rotation (x, y, z) to apply to the screen space object.	Vector3<double>	Value of type ‘Vector3’	Yes
Scale	A scale factor for the plane that can be used to increase or decrease the visual size. The default size is determined separately for each screen space renderable type and may for example be affected by the size of an image being displayed.	Double	Value of type ‘Double’	Yes
Tag	Defines either a single or multiple tags that apply to this ScreenSpaceRenderable, thus making it possible to address multiple, separate Renderables with a single property change.	String, or Table	Value of type ‘String’, or Value of type ‘Table’	Yes
UsePerspectiveProjection	Determines whetether the z/radius values affects the size of the plane or not.	Boolean	Value of type ‘Boolean’	Yes
UseRadiusAzimuthElevation	Determines whether the location of this screen space plane will be specified using radius, azimuth and elevation (if ‘true’) or using Cartesian coordinates. The Cartesian coordinate system is useful if a regular rendering is applied, whereas the radius azimuth elevation are most useful in a planetarium environment.	Boolean	Value of type ‘Boolean’	Yes

Table parameters for Transform

The collection of transformations that are applied to the Renderable before it is shown on screen.

• Optional: Yes

Name	Documentation	Type	Description	Optional
Rotation	The Rotation object that is used for the provided Renderable. If no value is specified, a StaticRotation is created instead.	Table	Rotation	Yes
Scale	The Scale object that is used for the provided Renderable. If no value is specified, a StaticScale is created instead.	Table	Scale	Yes
Translation	The Translation object that is used for the provided Renderable. If no value is specified, a StaticTranslation is created instead.	Table	Translation	Yes

Asset Examples

Axes

Creates a screenspace image that renders three Cartesian axes into the screen space window. This example also modifies the original camera position to give an oblique view onto the axes and increases the field of view of the camera to a wider degree. We also set the background color to be fully opaque to make it easier to see the axes.

local Object = {
  Type = "ScreenSpaceRenderableRenderable",
  Identifier = "ScreenSpaceRenderableRenderable_Example_Axes",
  Renderable = {
    Type = "RenderableCartesianAxes"
  },
  BackgroundColor = { 0.0, 0.0, 0.0, 1.0 },
  CameraPosition = { 1.0, 1.0, 1.0 },
  CameraFov = 80.0
}

asset.onInitialize(function()
  openspace.addScreenSpaceRenderable(Object)
end)

asset.onDeinitialize(function()
  openspace.removeScreenSpaceRenderable(Object)
end)

Basic

Creates a screenspace image that shows a spherical grid as an example for any Renderable that can be displayed.

local Object = {
  Type = "ScreenSpaceRenderableRenderable",
  Identifier = "ScreenSpaceRenderableRenderable_Example",
  Renderable = {
    Type = "RenderableSphericalGrid",
    Opacity = 1.0,
    Color = { 0.3, 0.84, 1.0 },
    LineWidth = 2.0
  }
}

asset.onInitialize(function()
  openspace.addScreenSpaceRenderable(Object)
end)

asset.onDeinitialize(function()
  openspace.removeScreenSpaceRenderable(Object)
end)

Model

Creates a screen space window into which 3D model of the Eiffel tower is rendered. As the objects are rendered in meter scale, and the Eiffel tower is about 300m tall, we both shrink the rendering to make the entire model fit into the view and also modify the position of the camera.

-- Download the model file for the Eiffel tower
local modelFolder = asset.resource({
  Name = "Scale Eiffel Tower",
  Type = "HttpSynchronization",
  Identifier = "scale_model_eiffel_tower",
  Version = 1
})

local Object = {
  Type = "ScreenSpaceRenderableRenderable",
  Identifier = "ScreenSpaceRenderableRenderable_Example_Model",
  Transform = {
    Scale = {
      Type = "StaticScale",
      Scale = 0.0002
    }
  },
  Renderable = {
    Type = "RenderableModel",
    GeometryFile = modelFolder .. "eiffeltower.osmodel",
    RotationVector = { 0.0, 45.0, 0.0 },
    LightSources = {
      {
        Identifier = "Camera",
        Type = "CameraLightSource",
        Intensity = 5.0
      }
    }
  },
  Scale = 1.25,
  CameraPosition = { 0.0, 1.0, 2.0 },
  CameraCenter = { 0.0, 0.5, 0.0 }
}

asset.onInitialize(function()
  openspace.addScreenSpaceRenderable(Object)
end)

asset.onDeinitialize(function()
  openspace.removeScreenSpaceRenderable(Object)
end)

Model Distance

Creates a screen space window into which 3D model of the Eiffel tower is rendered. As the objects are rendered in meter scale, and the Eiffel tower is about 300m tall, we place the camera at a great distance to be able to see the entire Eiffel tower at the same time.

-- Download the model file for the Eiffel tower
local modelFolder = asset.resource({
  Name = "Scale Eiffel Tower",
  Type = "HttpSynchronization",
  Identifier = "scale_model_eiffel_tower",
  Version = 1
})

local Object = {
  Type = "ScreenSpaceRenderableRenderable",
  Identifier = "ScreenSpaceRenderableRenderable_Example_ModelDistance",
  Renderable = {
    Type = "RenderableModel",
    GeometryFile = modelFolder .. "eiffeltower.osmodel",
    RotationVector = { 0.0, 45.0, 0.0 },
    LightSources = {
      {
        Identifier = "Camera",
        Type = "CameraLightSource",
        Intensity = 5.0
      }
    }
  },
  Scale = 1.25,
  CameraPosition = { 0.0, 3500.0, 9000.0 },
  CameraCenter = { 0.0, 2750.0, 0.0 }
}

asset.onInitialize(function()
  openspace.addScreenSpaceRenderable(Object)
end)

asset.onDeinitialize(function()
  openspace.removeScreenSpaceRenderable(Object)
end)