V8 Javascript API

Scene Class Reference

[Elements]

Description

A RealityServer scene.

A RealityServer scene Element.A RealityServer scene Element.

Constructor

 Scene( String name, bool create, bool block, if expiry_delay)
More...

Functions

varying as( String type_name)
Upcasts an element to a specific element type. More...
the copy( String name, Number privacy_level)
Make a copy of this element in the database. More...
 create( String element_type, Number privacy_level)
Creates a scene element called name. More...
Render_context create_render_context( String name, Number timeout, String renderer)
Creates a new render context for the scene. More...
 delete()
Remove this element from the database.
bool  exists( String element_type)
Returns whether the element exists or not. More...
Array export( String filename, Object options)
Exports the scene to disk. More...
Object frame_camera( Number fill, bool apply)
Frames the scenes camera to fit all objects within the view. More...
Render_context get_render_context( String name)
Retrieves a named render context for the scene. More...
 localize( Number privacy_level)
Localizes this element. More...
varying property_get( String cache, String command, String element_name_arg, Function as_a)
Retrieves and caches a property of an element. More...
 property_set( String cache, String command, String element_name_arg, String value_arg_name, varying value, Function from_a)
Sets and caches a property of an element. More...
Binary render( String renderer, String format, String pixel_type, String quality, Canvas_definition canvas_definition, Object options)
Renders and returns an encoded image using an anonymous render context. More...
String render_to_ascii( Number width, Number height, String renderer, Canvas_definition canvas_definition, Object options)
Renders and returns a string based on an ASCII art conversion of the rendered image using an anonymous render context. More...
String render_to_base64( String renderer, String format, String pixel_type, String quality, bool datauri, Canvas_definition canvas_definition, Object options)
Renders and returns an encoded image as a base64 string using an anonymous render context. More...
Canvas render_to_canvas( String renderer, Number width, Number height, Canvas_definition canvas_definition, Object options)
Renders and returns an Canvas containing the rendered image using an anonymous render context. More...
Canvas render_to_canvases( String renderer, Number width, Number height, Canvas_definition[] canvas_definitions, Object options)
Renders and returns an array of Canvases containing the rendered images using an anonymous render context. More...
 render_to_disk( String filename, String renderer, String format, String pixel_type, String quality, Canvas_definition canvas_definition, Object options)
Renders and encodes an image which is then saved to disk using an anonymous render context. More...

Static Functions

Scene import( String scene_name, String filename, Object options)
Import a scene from disk. More...
Object import_elements( String filename, Object options)
Import scene elements from disk. More...

Properties

Attributes attributes
The attributes associated with this element.
BBox3  bounding_box
The bounding box of the scene.
Instance camera_instance
The camera instance for this scene or undefined if no camera instance is set on the scene. More...
bool  exists
Returns whether the scene exists or not. More...
String  name
The name of the element. More...
Options options
The options for this scene or undefined if no options are set on the scene. More...
Group root_group
The root group for this scene or undefined if no root group is set on the scene. More...
String  type_name
The type name of the element. More...

Constructor

Scene( String name, bool create, bool block, if expiry_delay)

Parameters

name
The name of the scene
create
if true then create the scene, otherwise it is assumed it already exists.
block
if creating the scene then creation will block if true.
expiry_delay
creating the scene then this is time, in seconds, after which the scene will be deleted if inactive. Specify 0 (the default) to never delete the scene

Functions

varying Scene.as( String type_name)

Upcasts an element to a specific element type. If this element is not of the given type then undefined is returned. If type_name does not have a matching element implementation an error is thrown. Note that this is not strictly an upcast but will return a new instance of the specific class representing type_name.

Parameters

type_name
the element type name to convert to.

Returns

the specific Element implementation for this element.

the Scene.copy( String name, Number privacy_level)

Make a copy of this element in the database.

Parameters

name
The name of the new element to copy to.
privacy_level
The privacy level to which the element will be copied. Defaults to the privacy level of the current scope.

Returns

copied element

Scene.create( String element_type, Number privacy_level)

Creates a scene element called name. Throws on error.

Parameters

element_type
the type of element to create
privacy_level
The privacy level to create the element at. Defaults to the privacy level of the current scope.
Render_context Scene.create_render_context( String name, Number timeout, String renderer)

Creates a new render context for the scene.

Parameters

name
the name of the new render context
timeout
the timeout in seconds after which the render context will expire
renderer
the renderer to be used by the render context

Returns

the newly created render context

Scene.delete()

Remove this element from the database.

bool Scene.exists( String element_type)

Returns whether the element exists or not.

Note:

element_type of 'Scene' is not supported. To test if a Scene exists use this.as('Scene') !== undefined

Parameters

element_type
if provided then the element must also be of this type.
Array Scene.export( String filename, Object options)

Exports the scene to disk.

Parameters

filename
the name of the file to export to relative to content_root
options
export options, see export_scene command for details

Returns

array containing objects representing import messages with code, message and severity

Object Scene.frame_camera( Number fill, bool apply)

Frames the scenes camera to fit all objects within the view.

Parameters

fill
amount of the image to fill with the scene, 1.0 will completely fill, lower values will leave space around the scene, higher values will cause the scene to be clipped
apply
if true then the scenes camera will be modified with the computed values, if false the scene camera will not be changed

Returns

map containing the results of the camera framing with properties for aspect , aperture , orthographic , focal , transform and target point

Render_context Scene.get_render_context( String name)

Retrieves a named render context for the scene.

Parameters

name
the name of the render context to retrieve

Returns

the retrieved render context

Scene Scene.import( String scene_name, String filename, Object options) [static]

Import a scene from disk.

Parameters

scene_name
the name to call the scene.
filename
the filename to import
options
import options. Supported options are:
  • add_scene_shader_paths bool if true (the default) then default shader and resource paths for the scene are added before import.
  • block bool if true (the default) then block scene access while importing
  • expiry_delay Number The time, in seconds, after which the scene will be deleted if inactive. Defaults to 0 which disables expiry.
  • import_options Object A map of options to pass to the importer.
  • errors_as_warnings bool If true then import errors are downgraded to warnings.

Returns

the imported scene. Additionally, the scene will have an import_result property detailing the results of the import.

Object Scene.import_elements( String filename, Object options) [static]

Import scene elements from disk.

Parameters

filename
the filename to import
options
import options. Supported options are:
  • add_scene_shader_paths bool if true (the default) then default shader and resource paths for the scene are added before import.
  • import_options Object A map of options to pass to the importer.
  • errors_as_warnings bool If true then import errors are downgraded to warnings.

Returns

the results of the scene import

Scene.localize( Number privacy_level)

Localizes this element.

Parameters

privacy_level
The privacy level to which the element will be localized. Defaults to the privacy level of the current scope.
varying Scene.property_get( String cache, String command, String element_name_arg, Function as_a)

Retrieves and caches a property of an element. The value of the property must be retrievable via a command that takes a single argument which is the name of the element to retrieve the property from. The name of this Element is used. If the returned property is another named scene Element then the element's constructor can be provided to return the element itself rather than it's name. On error this will return undefined.

Parameters

cache
name of the property to cache the result to
command
name of the RS command to get the property value
element_name_arg
name of the command argument to use for the element name
as_a
if the property being retrieved is an RS Element then the element constructor should be passed in here. The result of the command is assumed to be the element name and this is used to create an Element instance to return rather than the name of the element. Use undefined if the retrieved value is not an element.

Returns

the property value if it exists or undefined

Scene.property_set( String cache, String command, String element_name_arg, String value_arg_name, varying value, Function from_a)

Sets and caches a property of an element. The value of the property must be set via a command that takes two arguments, one being the name of the element to set and the other being the property's value. The names of these arguments are passed in. If the property is another named scene Element then the element's constructor can be provided and value can either be the element itself or it's name. Will throw on error.

Parameters

cache
name of the property to cache the result to
command
name of the RS command to set the property value
element_name_arg
name of the command argument to use for the element name
value_arg_name
name of the value argument to use for the value
value
the value to set
from_a
if the property being set is a RealityServer Element then the element constructor should be passed in here. value can then either be the name of the scene element or the Element itself. If value is a name then an Element is constructed and cache rather than the name itself. Use undefined if the value does not represent an Element .
Binary Scene.render( String renderer, String format, String pixel_type, String quality, Canvas_definition canvas_definition, Object options)

Renders and returns an encoded image using an anonymous render context.

Parameters

renderer
name of the renderer to be used
format
the image format for the encoded data.
pixel_type
the pixel type of the encoded image.
quality
quality of the encoded image if the chosen format supports variable quality.
canvas_definition
the definition of the canvas to be rendered. Must
options
render context options to be passed to the rendering. contain properties name, pixel_type and content. The content property is a Canvas_parameters object which contains a type and params property.

Returns

the encoded image of the render.

String Scene.render_to_ascii( Number width, Number height, String renderer, Canvas_definition canvas_definition, Object options)

Renders and returns a string based on an ASCII art conversion of the rendered image using an anonymous render context.

Parameters

width
the width in characters of the output.
height
the height in characters of the output.
renderer
name of the renderer to be used
canvas_definition
the definition of the canvas to be rendered. Must contain properties name, pixel_type and content. The content property is a Canvas_parameters object which contains a type and params property.
options
render context options to be passed to the rendering.

Returns

the string of the ASCII art image of the render.

String Scene.render_to_base64( String renderer, String format, String pixel_type, String quality, bool datauri, Canvas_definition canvas_definition, Object options)

Renders and returns an encoded image as a base64 string using an anonymous render context.

Parameters

renderer
name of the renderer to be used
format
the image format for the encoded data.
pixel_type
the pixel type of the encoded image.
quality
quality of the encoded image if the chosen format supports variable quality.
datauri
if true then the datauri format is used for the resulting image.
canvas_definition
the definition of the canvas to be rendered. Must contain properties name, pixel_type and content. The content property is a Canvas_parameters object which contains a type and params property.
options
render context options to be passed to the rendering.

Returns

the base64 encoded string of the image of the render.

Canvas Scene.render_to_canvas( String renderer, Number width, Number height, Canvas_definition canvas_definition, Object options)

Renders and returns an Canvas containing the rendered image using an anonymous render context.

Parameters

renderer
name of the renderer to be used
width
the width in pixels of the output canvas. If not provided uses the camera.
height
the height in pixels of the output canvas. If not provided uses the camera.
canvas_definition
the definition of the canvas to be rendered. Must contain properties name, pixel_type and content. The content property is a Canvas_parameters object which contains a type and params property.
options
render context options to be passed to the rendering.

Returns

a canvas containing the rendered image.

Canvas Scene.render_to_canvases( String renderer, Number width, Number height, Canvas_definition[] canvas_definitions, Object options)

Renders and returns an array of Canvases containing the rendered images using an anonymous render context.

Parameters

renderer
name of the renderer to be used
width
the width in pixels of the output canvas. If not provided uses the camera.
height
the height in pixels of the output canvas. If not provided uses the camera.
canvas_definitions
an array of canvas definitions to be rendered. Each, must contain properties name, pixel_type and content. The content property is a Canvas_parameters object which contains a type and params property.
options
render context options to be passed to the rendering.

Returns

an array of canvases containing the rendered images.

Scene.render_to_disk( String filename, String renderer, String format, String pixel_type, String quality, Canvas_definition canvas_definition, Object options)

Renders and encodes an image which is then saved to disk using an anonymous render context.

Parameters

filename
the file name including path within content root to save the image to. The file must be within the content root directory. A relative path will automatically be resolved within the content root. An absolute path must terminate within the content root or else save will fail. A file URI (file://) may be used instead of a filename in which case the path will always be interpreted as relative to content root.
renderer
name of the renderer to be used
format
the image format for the encoded data.
pixel_type
the pixel type of the encoded image.
quality
quality of the encoded image if the chosen format supports variable quality.
canvas_definition
the definition of the canvas to be rendered. Must contain properties name, pixel_type and content. The content property is a Canvas_parameters object which contains a type and params property.
options
render context options to be passed to the rendering.

Properties

Attributes Scene.attributes

The attributes associated with this element.

BBox3 Scene.bounding_box

The bounding box of the scene.

Instance Scene.camera_instance

The camera instance for this scene or undefined if no camera instance is set on the scene. Throws if this is not a Scene element.

bool Scene.exists

Returns whether the scene exists or not. This test is type checked.

String Scene.name

The name of the element. Read only.

Options Scene.options

The options for this scene or undefined if no options are set on the scene. Throws if this is not a Scene element.

Group Scene.root_group

The root group for this scene or undefined if no root group is set on the scene. Throws if this is not a Scene element.

String Scene.type_name

The type name of the element. If the element does not exists returns undefined. Read only.

Note:

For a Scene element this will return 'Attribute_container', not 'Scene'.