ScreenSpaceInsetBlackout

Inherits ScreenSpaceRenderable

A ScreenSpaceInsetBlackout can be used to render a screen-space shape used to black out part of the rendering. This can be useful in a dome environment where you have a secondary presentation projector that can project on the dome surface. The blackout is used to avoid overlapping rendering between the dome projectors and the presentation projector.

Members

Name	Documentation	Type	Description	Optional
Blackoutshape		Table	Table parameters	No

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 Blackoutshape

• Optional: No

Name	Documentation	Type	Description	Optional
Bottom	List of points between the Bottom-Right and Bottom-Left corners that will be used to define bottom spline of the blackout shape. Each point is specified in the range of 0 to 1, where {1,0} is the Bottom-Right corner and {0,0} is the Bottom-Left corner.	Table	Table parameters	Yes
CalibrationTexturePath	File path for the texture that should be used when displaying the calibration grid.	File	Value of type ‘File’	Yes
Corners	List of corner positions for the blackout shape. The order of corner points are Top-Left, Top-Right, Bottom-Right, Bottom-Left with the range of 0 to 1 for {X,Y}, where {0,1} is the Top-Left corner and {1,0} is the Bottom-Right corner.	Table	Table parameters	No
Left	List of points between the Bottom-Left and Top-Left corners that will be used to define left spline of the blackout shape. Each point is specified in the range of 0 to 1, where {0,0} is the Bottom-Left corner and {0,1} is the Top-Left corner.	Table	Table parameters	Yes
Right	List of points between the Top-Right and Bottom-Right corners that will be used to define right spline of the blackout shape. Each point is specified in the range of 0 to 1, where {1,1} is the Top-Right corner and {1,0} is the Bottom-Right corner.	Table	Table parameters	Yes
Top	List of points between the Top-Left and Top-Right corners that will be used to define top spline of the blackout shape. Each point is specified in the range of 0 to 1, where {0,1} is the Top-Left corner and {1,1} is the Top-Right corner.	Table	Table parameters	Yes

Table parameters for Bottom

List of points between the Bottom-Right and Bottom-Left corners that will be used to define bottom spline of the blackout shape. Each point is specified in the range of 0 to 1, where {1,0} is the Bottom-Right corner and {0,0} is the Bottom-Left corner.

• Optional: Yes

Name	Documentation	Type	Description	Optional
*		Vector2<double>	Value of type ‘Vector2’	Yes

Table parameters for Corners

List of corner positions for the blackout shape. The order of corner points are Top-Left, Top-Right, Bottom-Right, Bottom-Left with the range of 0 to 1 for {X,Y}, where {0,1} is the Top-Left corner and {1,0} is the Bottom-Right corner.

• Optional: No

Name	Documentation	Type	Description	Optional
*		Vector2<double>	Value of type ‘Vector2’	Yes

Table parameters for Left

List of points between the Bottom-Left and Top-Left corners that will be used to define left spline of the blackout shape. Each point is specified in the range of 0 to 1, where {0,0} is the Bottom-Left corner and {0,1} is the Top-Left corner.

• Optional: Yes

Name	Documentation	Type	Description	Optional
*		Vector2<double>	Value of type ‘Vector2’	Yes

Table parameters for Right

List of points between the Top-Right and Bottom-Right corners that will be used to define right spline of the blackout shape. Each point is specified in the range of 0 to 1, where {1,1} is the Top-Right corner and {1,0} is the Bottom-Right corner.

• Optional: Yes

Name	Documentation	Type	Description	Optional
*		Vector2<double>	Value of type ‘Vector2’	Yes

Table parameters for Top

List of points between the Top-Left and Top-Right corners that will be used to define top spline of the blackout shape. Each point is specified in the range of 0 to 1, where {0,1} is the Top-Left corner and {1,1} is the Top-Right corner.

• Optional: Yes

Name	Documentation	Type	Description	Optional
*		Vector2<double>	Value of type ‘Vector2’	Yes

Asset Examples

Basic

Creates a screenspace image plane with controls to for a blackout shape. Can be used when using a secondary projector to project content on a dome surface.

local inset = {
  Identifier = "ScreenSpaceInsetBlackout_Example",
  Type = "ScreenSpaceInsetBlackout",
  Name = "ScreenSpaceInsetBlackout Example - Basic",
  Blackoutshape = {
    -- Must always contain four corners in the following order: 
    -- top-left, top-right, bottom-right, bottom-left
    Corners = { {0.0, 1.0}, {1.0, 1.0}, {1.0, 0.0}, {0.0, 0.0} }
  },
  Scale = 1.0
}

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

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

Calibration Pattern

Creates a screenspace image plane with controls to for a blackout shape. Can be used when using a secondary projector to project content on a dome surface.

local texturePath = asset.resource({
  Type = "HttpSynchronization",
  Identifier = "calibration_pattern",
  Name = "ScreenSpaceInsetBlackout Calibration Pattern",
  Version = 1
})

local inset = {
  Identifier = "ScreenSpaceInsetBlackout_Example_Calibration_Pattern",
  Type = "ScreenSpaceInsetBlackout",
  Name = "ScreenSpaceInsetBlackout Example - Calibration Pattern",
  Blackoutshape = {
    -- Must always contain four corners in the following order: 
    -- top-left, top-right, bottom-right, bottom-left
    Corners = { {0.0, 1.0}, {1.0, 1.0}, {1.0, 0.0}, {0.0, 0.0} },

    CalibrationTexturePath = texturePath .. "calibration-pattern.png";
  },
  Scale = 1.0
}

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

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

Points

Creates a screenspace image plane with controls to for a blackout shape. Can be used when using a secondary projector to project content on a dome surface.

local inset = {
  Identifier = "ScreenSpaceInsetBlackout_Example_Points",
  Type = "ScreenSpaceInsetBlackout",
  Name = "ScreenSpaceInsetBlackout Example - Points",
  Blackoutshape = {
    -- Must always contain four corners in the following order: 
    -- top-left, top-right, bottom-right, bottom-left
    Corners = { {0.0, 0.9}, {1.0, 0.9}, {0.9, 0.1}, {0.1, 0.1} },

    -- Contains control points for top spline in order left to right
    Top = { {0.5, 1.0} },

    -- Contains control points for right spline in order top to bottom
    Right = { },

    -- Contains control points for bottom spline in order right to left
    Bottom = { {0.7, 0.2}, {0.3, 0.2} },

    -- Contains control points for left spline in order bottom to top
    Left = { }
  },
  Scale = 1.0
}

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

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