RealityServer® Client

Class: Stream

RS.Stream

Represents an image stream from a render loop.

NOTE: Users do not create Streams directly, streams are obtained using RS.Service#stream

Extends

Members

cancel_level Number

When commands are executed on a stream the actual execution occurs between renders. Consequently there can be a (possibly considerable) delay before execution occurs. Specifying a cancel level causes any current render to be cancelled so command execution can occur as soon as possible. If set to 0 then rendering is cancelled, and if possible rendering continues without restarting progression. If 1 then cancelling will occur faster at the expense of always needing to restart. Any other value will not cancel rendering when executing commands

Default Value:
  • -1

continue_on_error Boolean

Controls error handling when an error occurs during command execution. If true then commands will continue to be processed, if false processing will end at the first error and any subsequent commands will be aborted and get error resposes. Defaults to true.

Default Value:
  • true

paused Number readonly

The pause count for this stream. When evaluated in a truthy manner will be true if paused and false if not.

render_loop_name String readonly

The name of the render loop this stream is providing images from. Is \c undefined if the stream has not yet been started.

streaming Boolean

Whether this loop is streaming or not.

Methods

execute_command (command, options)Promise

Executes a single command on this render loop and returns a Promise that resolves to an iterable. The iterable will contain up to 2 results

  • if want_response is true then the first iterable will be the result of the command or a RS.Command_error.
  • if wait_for_render is true then the last iterable will be a RS.Stream~Rendered_result containing the first rendered image that contains the result of the command.

The promise will reject in the following circumstances:

  • there is no WebSocket connection.
  • the WebSocket connection has not started (IE: RS.Service#connect has not yet resolved).
Name Type Description
command RS.Command

The command to execute.
options Object optional
Name Type Default Description
want_response Boolean optional

If true then the returned promise will not resolve until the command response is available and the response will be in the first iterable.
wait_for_render Boolean optional

If true, the promise will not resolve until the RS.Service#event:image event that contains the result of this command is about to be emitted. The last iterable in the resolved value will be contain the rendered image.
cancel_level Number this.cancel_level optional

If provided then this overrides the streams cancel level.
continue_on_error Boolean this.continue_on_error optional

If provided then this overrides the streams continue on error.
Fires:
Returns:
Type Description
Promise A Promise that resolves to an iterable.

pause ()Number

Pauses emiting RS.Service#event:image events for this stream. Note the images are still transmitted from the server, the callback is just not called. Pause calls are counted so you need to call RS.Stream#resume the same number of times as pause before events are emitted begins again.

Returns:
Type Description
Number The pause count, IE: the number of times resume will need to be called to start emitting events again.

pick (position, size, cancel_level)Promise Deprecated : This variant of pick is deprecated in favour of the two argument version below.

Executes a pick operation on the render loop. The returned promise resolves with an array of pick results. If no objects were under the point then the array will be empty.

Note that stream picking is only supported in RealityServer 6.2 and above.

The returned promise will reject in the following circumstances:

  • there is no WebSocket connection.
  • the WebSocket connection has not started (IE: RS.Service#connect has not yet resolved).
  • this stream is not yet streaming
  • no position is provided.
  • arguments are the wrong type or \p position has a negative coordinate
  • the render loop is no longer available.
  • the connected RealityServer does not support picking on a stream.
Name Type Description
position Vector2

The screen space position of the pick.
size Vector2 optional

The screen space rectangular size of the pick. Defaults to a 1x1 pixel area.
cancel_level Number optional

The cancel level override. Defaults to 1.
Returns:
Type Description
Promise A Promise that resolves to an array of pick results. Each element in the pick result array will be an object containing the following properties: world_point (Vector3), picked_object_name (String), path (String[]).

pick (pick, cancel_level)Promise

Executes a pick operation on the render loop. The returned promise resolves with an array of pick results. If no objects were under the point then the array will be empty.

Note that stream picking is only supported in RealityServer 6.2 and above.

The returned promise will reject in the following circumstances:

  • there is no WebSocket connection.
  • the WebSocket connection has not started (IE: RS.Service#connect has not yet resolved).
  • this stream is not yet streaming
  • no position is provided.
  • arguments are the wrong type or \p position has a negative coordinate
  • the render loop is no longer available.
  • the connected RealityServer does not support picking on a stream.
Name Type Description
pick Object

Object defining what to pick

Name Type Description
position Vector2

The screen space position of the pick.
size Vector2 optional

The screen space rectangular size of the pick. Defaults to a 1x1 pixel area.
max_levels Number optional

Controls the number of rays that may be cast, per ray, during the picking operation. A level of 1 will only trace primary rays. Any other value will continue tracing rays through the scene until nothing was hit or the maximum depth is exhausted, with a value of 0 indicating unconstrained depth. This parameter has no effect when using versions of RealityServer prior to 6.3.
params Object optional

Render loop handler defined parameters used to control the pick operation.
cancel_level Number optional

The cancel level override. Defaults to 1.
Returns:
Type Description
Promise A Promise that resolves to an array of pick results. Each element in the pick result array will be an object containing the following properties: world_point (Vector3), picked_object_name (String), path (String[]).

queue_commands (options)RS.Command_queue

Returns a RS.Command_queue that can be used to queue up a series of commands to be executed on this render loop

Name Type Description
options Object optional
Name Type Default Description
wait_for_render Boolean optional

If true then when this queue is executed it will also generate a Promise that will resolve when the RS.Service#event:image event that contains the results of the commands is about to be emitted.
cancel_level Number this.cancel_level optional

If provided then this overrides the streams cancel level.
continue_on_error Boolean this.continue_on_error optional

If provided then this overrides the streams continue on error.
Returns:
Type Description
RS.Command_queue The command queue to add commands to and then execute.

resume (force)Number

Resumes emiting RS.Service#event:image events for this stream if the pause count has reduced to 0.

Name Type Default Description
force Boolean false optional

If true then forces display to resume regardless of the pause count.
Returns:
Type Description
Number The pause count, IE: the number of times resume will need to be called to start emitting events again.

send_command (command, options)Array.<Promise>

Sends a single command to execute on this render loop and returns an Array of Promises that will resolve with the responses. The array will contain up to 2 Promises.

  • if want_response is true then the first Promise will resolve to the result of the command or a RS.Command_error.
  • if wait_for_render is true then the last Promise will resolve to a RS.Stream~Rendered_image when the first rendered image that contains the results of the commands is generated.
Name Type Description
command RS.Command

The command to execute.
options Object optional
Name Type Default Description
want_response Boolean optional

If true then the reponse promise resolves to the response of the command. If false then the promise resolves immediately to undefined.
wait_for_render Boolean optional

If true, then the render promise resolves to a RS.Stream~Rendered_result just before the RS.Service#event:image event that contains the result of this command is emitted.
cancel_level Number this.cancel_level optional

If provided then this overrides the streams cancel level.
continue_on_error Boolean this.continue_on_error optional

If provided then this overrides the streams continue on error.
Fires:
Throws:

This call will throw an error in the following circumstances:

  • there is no WebSocket connection.
  • the WebSocket connection has not started (IE: RS.Service#connect has not yet resolved).
Type
RS.Error
Returns:
Type Description
Array.<Promise> An Array of Promises. These promises will not reject.

set_parameters (parameters)Promise

Sets parameters on a stream. Returns a promise that resolves with the parameters have been set. The returned promise will reject in the following circumstances:

  • there is no WebSocket connection.
  • the WebSocket connection has not started (IE: RS.Service#connect has not yet resolved).
  • this stream is not yet streaming
  • updating the parameters failed
Name Type Description
parameters Object

The parameter to set. Supported parameters include:

Name Type Description
encoder_name String optional

the name of the stream encoder to modify or the default encoder if omitted.
image_format String optional

the streamed image format.
pixel_type String optional

the streamed image pixel type.
quality String optional

the streamed image quality.
encoders Object optional

named encoder parameters.
Returns:
Type Description
Promise A promise that resolves with the set parameter response or rejects with the error message.

start (render_loop)Promise

Starts streaming images from a render loop on this stream. Note that a stream can only stream images from one render loop at a time. Returns a promise that resolves when the stream has started. The promise will reject in the following circumstances:

  • there is no WebSocket connection.
  • the WebSocket connection has not started (IE: RS.Service#connect has not yet resolved).
  • if the given render loop is already being streamed by this service.
  • starting the stream failed, usually this occurs if the render loop cannot be found or invalid streaming data is provided.

Once the stream has started RS.Stream#event:image events will be emitted on both the stream object and the original RS.Service object every time a rendered image is received from the server.

Starting from version 2.0.1 the special image_format value of NONE can be supplied. This will establish a 'command and control' stream that will not send images to the client but can still be used to edit the RealityServer scene. Note that it is not possible to start or stop streaming images once a stream has started.

Name Type Description
render_loop String | Object

If a String then the name of the render loop to stream. Provide an object to specify additional streaming data.

Name Type Description
render_loop_name String

the name of the render loop to stream.
image_format String optional

the streamed image format.
pixel_type String optional

the streamed image pixel type.
quality String optional

the streamed image quality.
encoders Object optional

an object containing named stream encoder settings, each defining image_format, pixel_type and quality parameters. Note that all possible named encoders must be specified at start time. It is not possible to add new named encoders using RS.Stream#set_parameters, only modify existing settings.
Fires:
Returns:
Type Description
Promise A promise that resolves when the stream has started.

stop ()Promise

Stops streaming from a render loop.

Returns:
Type Description
Promise A promise that resolves when the stream is stopped or rejects on error.

update_camera (data)Promise

Utility function to update the camera on this stream's render loop.

While it is possible to simply use individual commands to update the camera this method is more efficient as changes will be collated on the server and applied as a single update between render calls.

The returned promise will reject in the following circumstances:

  • there is no WebSocket connection.
  • the WebSocket connection has not started (IE: RS.Service#connect has not yet resolved).
  • this stream is not yet streaming
  • no data is provided.
  • updating the camera information failed
  • wait for render is true but the connected RealityServer does not support this with update camera.
Name Type Description
data Object

Object specifying the camera to update. Supported format is:

Name Type Description
cancel_level Number optional

Cancel level to use when updating.
wait_for_render Boolean optional

If true then the promise will resolve when the new camera data is available in a rendered image.
camera Object optional

Properties to update on the camera

Name Type Description
name String

The name of the camera to update
aperture Number optional

The aperture width of the camera.
aspect Number optional

The aspect ratio of the camera.
clip_max Number optional

The yon clipping distance.
clip_min Number optional

The hither clipping distance.
focal Number optional

The focal length to set.
frame_time Number optional

The frame time of the camera, in seconds.
offset_x Number optional

The horizontal plane shift.
offset_y Number optional

The vertical plane shift.
orthographicn Number optional

If the camera is orthographic or not.
resolution_x Number optional

The width of the camera.
resolution_y Number optional

The height of the camera.
window_xh Number optional

The right edge of the render sub-window in raster space.
window_xl Number optional

The left edge of the render sub-window in raster space.
window_yh Number optional

The top edge of the render sub-window in raster space.
window_yl Number optional

The bottom edge of the render sub-window in raster space.
attributes Object optional

Arbitrary attributes to set on the camera. Property names are the attribute names to set. Each property value should be an object containing the following:

Name Type Description
value *

The attribute value to set.
type String

The type of the attribute to set.
camera_instance Object optional

Properties to update on the camera instance.

Name Type Description
name String

The name of the camera instance to update.
transform RS.Math.Matrix4x4 optional

The camera instance transform to set
attributes Object optional

Arbitrary attributes to set on the camera instance. Property names are the attribute names to set. Each property value should be an object containing the following:

Name Type Description
value *

The attribute value to set.
type String

The type of the attribute to set.
Returns:
Type Description
Promise A promise that resolves with the result of the camera update or when the camera data is available in a render if \c wait_for_render is c true.

Type Definitions

Rendered_image Object

A single image of a render result.

Properties:
Name Type Description
width Number

The image width.
height Number

The image height.
image Uint8Array

The rendered image
mime_type String

The mime type of the rendered image.
render_type String

The renderer defined type for the image. Typically 'result'.

Rendered_result Object

The result of an image render.

Properties:
Name Type Description
render_loop_name String

The name of the render loop this image was rendered by.
result Number

The render result, 0 for success, 1 for converged, -1 cancelled render, other negative values indicate errors.
images Array.<RS.Stream~Rendered_image>

An array of images that have been rendered.
statistics Object

Rendering statistics.

Events

image

Image event.

Fired whenever a renderer image is available on a stream. This event will be fired on RS.Service for all streams and on each individual RS.Stream

Name Type Description
image RS.Stream~Rendered_result

The rendered result