V8 Javascript API

Canvas Class Reference

[Types]

Description

The Canvas class represents an image within RealityServer, either the result of a render or obtained from a texture. Canvases can be edited by manipulating the pixels independently or via direct access to the underlying image data. it is also possible to convert between different pixel types and encode/decode any image format supported by RealityServer.

Note that canvases cannot be returned directly to the user via web services. They must be encoded to an image format first and then wrapped in a Binary to associate a mime-type with the image. EG: 

‎ var canvas = RS.render({scene_name: 'my_scene'});
 return new Binary(canvas.encode('png','Rgba'),'image/png');

Constructor

 Canvas( String type, Number width, Number height, Number layers, Boolean is_cubemap, Number gamma)
More...

Functions

 adjust_gamma( Number gamma)
Sets that gamma value to gamma and adjusts the image pixels to match. More...
Canvas clone()
Clones this canvas. More...
Canvas convert( String type)
Converts the pixel type of this canvas. More...
Canvas crop( Number xl, Number yl, Number xh, Number yh, String pixel_type)
Returns a copy of this canvas cropped to the region bounded by xl (left edge), yl (bottom edge), xh (right edge) and yh (top edge). More...
ArrayBuffer encode( String format, String type, String quality)
Encodes this canvas to the given image type. More...
ArrayBuffer get_data( Number layer)
The underlying pixel data for layer layer. More...
RS.​Math.​Color get_pixel( Number x, Number y, Number layer)
Returns the pixel at x, y in layer layer. More...
Canvas resize( String mode, Number width, Number height)
Returns a copy of this canvas resized to width x height pixels. More...
 set_pixel( Number x, Number y, RS.​Math.​Color color, Number layer)
Sets the pixel at x, y in layer layer to color. More...

Static Functions

Canvas decode( ArrayBuffer image, String format)
Decodes an image and returns a Canvas. More...

Properties

Number  bytes_per_component
The number of bytes used for each pixel component. More...
Number  components_per_pixel
The number of components that make up a pixel. More...
ArrayBuffer  data
The underlying pixel data at layer 0. More...
Number  gamma
The gamma value of the image. More...
Number  height
Alias for resolution_y.
Number  layers
The number of layers in the image.
Number  resolution_x
Returns the resolution of the canvas in the x direction.
Number  resolution_y
Returns the resolution of the canvas in the y direction.
Number  stride
The number of bytes per row. More...
String  type
The pixel type of the canvas. More...
Number  width
Alias for resolution_x.

Constructor

Canvas( String type, Number width, Number height, Number layers, Boolean is_cubemap, Number gamma)

Parameters

type
the pixel type for the canvas.
width
the width of the image.
height
the height of the image.
layers
the number of layers in the image. Defaults to 1.
is_cubemap
if true creates a cubemap canvas. In this case layers is hardcoded to be 6.
gamma
the gamma of the image, defaults to 0 which uses 2.2 for LDR pixel types and 1 for HDR pixel types.

Functions

Canvas.adjust_gamma( Number gamma)

Sets that gamma value to gamma and adjusts the image pixels to match.

Parameters

gamma
the gamma value to set.
Canvas Canvas.clone()

Clones this canvas.

Returns

a copy of this canvas.

Canvas Canvas.convert( String type)

Converts the pixel type of this canvas.

Parameters

type
the pixel type to convert to. See Types for a list of supported pixel types.

Returns

a copy of this canvas converted to pixel type type .

Canvas Canvas.crop( Number xl, Number yl, Number xh, Number yh, String pixel_type)

Returns a copy of this canvas cropped to the region bounded by xl (left edge), yl (bottom edge), xh (right edge) and yh (top edge). Values are relative to the bottom left corner of the image in raster space. If a pixel_type is specified then the canvas will be converted to the specified pixel type during the cropping process. By default the pixel type is retained. Infinite or NaN values will be interpreted as 0.

Parameters

xl
the left edge of the crop region
yl
the bottom edge of the crop region
xh
the right edge of the crop region
yh
the top edge of the crop region
pixel_type
the pixel type used for the cropped image (retains existing pixel type by default)

Returns

the cropped canvas

Canvas Canvas.decode( ArrayBuffer image, String format) [static]

Decodes an image and returns a Canvas.

Parameters

image
the image to decode. May be one of the following:
  • ArrayBuffer
  • Binary
format
the format of the image provided in image. Required if image is an ArrayBuffer. If image is a Binary then the format will be deduced from the mime-type if this parameter is not provided. Note that the type component of the mime-type must be image.

Returns

the decoded canvas

ArrayBuffer Canvas.encode( String format, String type, String quality)

Encodes this canvas to the given image type.

Parameters

format
the image format to encode to.
type
the pixel type to encode to. See Types for a list of supported pixel types. Defaults to the same type as this canvas.
quality
the quality to encode the image at, defaults to "100".

Returns

the encoded image. Note that to return the encoded image via web services it must first be wrapped in a Binary .

ArrayBuffer Canvas.get_data( Number layer)

The underlying pixel data for layer layer. This ArrayBuffer can be manipulated directly to edit the canvas. Use type to determine which type of ArrayBufferView should be used to access the returned buffer and components_per_pixel to determine pixel size.

Parameters

layer
the layer to retrieve pixel data for, defaults to 0.
RS.​Math.​Color Canvas.get_pixel( Number x, Number y, Number layer)

Returns the pixel at x, y in layer layer. Throws if any value is out of range.

Parameters

x
the x coordinate.
y
the y coordinate.
layer
the layer to retrieve the pixel from, defaults to 0.

Returns

the color at the requested location.

Canvas Canvas.resize( String mode, Number width, Number height)

Returns a copy of this canvas resized to width x height pixels.

Parameters

mode
the resizing mode, one of 'nearest_neighbor' (or 'nn'), 'linear' or 'cubic' (mitchell filter).
width
the width to resize to, or 0 to retain current width
height
the height to resize to, or 0 to retain current height

Returns

the resized canvas

Canvas.set_pixel( Number x, Number y, RS.​Math.​Color color, Number layer)

Sets the pixel at x, y in layer layer to color. Throws if any value is out of range.

Parameters

x
the x coordinate.
y
the y coordinate.
color
The color to set. If an Array is provided, it must have at least 3 Number components. May be one of the following:
  • RS.Math.Color
  • Array
layer
the layer to set the pixel on, defaults to 0.

Properties

Number Canvas.bytes_per_component

The number of bytes used for each pixel component. Note that for efficency this property should be stored in a local variable if it is to be referenced multiple times.

Number Canvas.components_per_pixel

The number of components that make up a pixel. Note that for efficency this property should be stored in a local variable if it is to be referenced multiple times.

ArrayBuffer Canvas.data

The underlying pixel data at layer 0. This ArrayBuffer can be manipulated directly to edit the canvas. Use type to determine which type of ArrayBufferView should be used to access the returned buffer and components_per_pixel to determine pixel size.

Number Canvas.gamma

The gamma value of the image. Note that setting this just sets the gamma value, it does not modify the pixel data itself. Use adjust_gamma to modify actual pixels.

Number Canvas.height

Alias for resolution_y.

Number Canvas.layers

The number of layers in the image.

Number Canvas.resolution_x

Returns the resolution of the canvas in the x direction.

Number Canvas.resolution_y

Returns the resolution of the canvas in the y direction.

Number Canvas.stride

The number of bytes per row. Note that for efficency this property should be stored in a local variable if it is to be referenced multiple times.

String Canvas.type

The pixel type of the canvas. See Types for a list of supported pixel types.

Number Canvas.width

Alias for resolution_x.