Viewport

Class representing a viewport in the canvas. The viewport is associated to a single camera entity and represents a drawing area in the canvas where a frame is rendered according to the point of view of the camera. The canvas may display several viewports.

You cannot directly instantiate a Viewport object by calling the constructor. To set up a viewport, use one of the following methods: startSession, joinSession, joinOrStartSession, setViewports, setMainCamera. To get an existing viewport, use getViewports or getViewportById.

Classes

Viewport

Methods

(async) focusOn(entity, optionsopt)

Focus on the entity. Uses travel to animate the camera traveling from a starting position and orientation to the entity.

Parameters:
NameTypeAttributesDefaultDescription
entityEntity
optionsobject<optional>
{}

Travel animation options

startPositionSDK_Vec3<optional>

Initial position of camera, defaults to its current position

startOrientationSDK_Quat<optional>

Initial orientation of camera, defaults to its current orientation

speedFactorfloat<optional>
4

Travel animation speed

distanceShiftfloat<optional>
0

Distance before entity to stop camera animation

Fires:
Example
const viewport = SDK3DVerse.engineAPI.cameraAPI.getViewports()[0];
viewport.focusOn(entity, { speedFactor : 10 });

getAreaSize() → {SDK_Vec2_uint}

Get the viewport area size within the canvas.

Returns:

[width, height] in pixels.

Type: 
SDK_Vec2_uint

getCamera() → {Entity}

Get the camera entity associated with the viewport.

Returns:

The camera entity.

Type: 
Entity

getControllerType() → {SDK3DVerse.cameraControllerType|null}

Get the camera controller type of the camera. If the camera doesn't have a controller, null is returned.

Returns:
Type: 
SDK3DVerse.cameraControllerType | null
Example
const viewport = SDK3DVerse.engineAPI.cameraAPI.getViewports()[0];
const controllerType = viewport.getControllerType();

getGlobalTransform() → {Transform}

Get the global transform of the camera. This transform is updated each frame and provided by the metadata of the frame sent by the rendering service.

Returns:

The global transform of the viewport's camera.

Type: 
Transform

getId() → {uint}

Get the viewport id.

Returns:

The viewport id.

Type: 
uint

getOffset() → {SDK_Vec2_uint}

Get the viewport offset within the canvas.

Returns:

[left, top] in pixels.

Type: 
SDK_Vec2_uint

getProjection() → {object}

Get the lens component of the camera, e.g. perspective_lens component.

Returns:

The lens component value.

Type: 
object

getProjectionMatrix() → {mat4}

Get the projection matrix of the camera, which transforms coordinates from view space (or camera space) to clip space.

Clip space is represented by a cuboid with [-1;1] dimensions for every axis and used for clipping vertices: all vertices inside this volume will be rendered on the screen. In this space, the Z coordinate of each vertex specifies how far away a vertex is from the screen.

Returns:

The projection matrix.

Type: 
mat4

getViewProjectionMatrix() → {mat4}

Get the view projection matrix of the camera, which transforms coordinates from world space to clip space.

The view projection matrix is the product of the the view matrix and the projection matrix. The view matrix transforms coordinates from world space to view space (or camera space), and is equal to the inverse camera world matrix i.e. the inverse of getWorldMatrix. For more info on the projection matrix see getProjectionMatrix.

Returns:

The view projection matrix.

Type: 
mat4

getWorldMatrix() → {mat4}

Get the world matrix of the camera.

Returns:

The world matrix.

Type: 
mat4

isInArea(position) → {boolean}

Check if a position within the canvas is within the viewport area. It can be used to determine the hovered viewports, as shown in the example below.

Parameters:
NameTypeDescription
positionSDK_Vec2_uint

The canvas position in pixels

Returns:

True if the position is within viewport area.

Type: 
boolean
Example
const canvas = document.getElementById("display_canvas");
canvas.addEventListener("mousedown", (event) => {
    const viewport = SDK3DVerse.engineAPI.cameraAPI.getViewportById(0);
    const position = [event.offsetX, event.offsetY];
    console.log("position clicked in canvas:", position);
    console.log("clicked inside viewport of id 0?", viewport.isInArea(position));
});

lookAt(targetPosition)

Set the global orientation of the camera to make it look at the target position.

Parameters:
NameTypeDescription
targetPositionSDK_Vec3

Position to look at in world space

Fires:
Example
const viewport = SDK3DVerse.engineAPI.cameraAPI.getViewports()[0];
viewport.lookAt([0, 0, 0]);

project(position) → {SDK_Vec3}

Project a position in world space to a point in the viewport screen space.

Parameters:
NameTypeDescription
positionSDK_Vec3

Position in world space

Returns:

Projected point in the viewport screen space. [0, 0] = Top left, [canvas width, canvas height] = Bottom right, [0, canvas height] = Bottom left, [canvas width, 0] = Top right.

Type: 
SDK_Vec3

(async) resetTransform(travelingDurationInSecopt)

Reset the camera to its default transform.

Parameters:
NameTypeAttributesDefaultDescription
travelingDurationInSecuint<optional>
0

If superior to zero, then animate a camera traveling to its default transform for the specified duration using travel

Fires:

setAreaRatio(widthRatio, heightRatio, triggerViewportUpdateopt)

Set viewport area ratio within the canvas. For example, widthRatio=0.5 and heightRatio=0.5 means the viewport takes 1/4 of the canvas.

Parameters:
NameTypeAttributesDefaultDescription
widthRatiofloat

The width ratio normalized into the 0.0 to 1.0 range

heightRatiofloat

The height ratio normalized into the 0.0 to 1.0 range

triggerViewportUpdateboolean<optional>
true

Update the viewport to make the rendering service adapt it immediately. Set to false to avoid unnecessary updates

setAreaSize(width, height, triggerViewportUpdateopt)

Set viewport area size within the canvas.

Parameters:
NameTypeAttributesDefaultDescription
widthuint

Width in pixels

heightuint

Height in pixels

triggerViewportUpdateboolean<optional>
true

Update the viewport to make the rendering service adapt it immediately. Set to false to avoid unnecessary updates

setCamera(camera)

Set the camera entity associated with the viewport.

Parameters:
NameTypeDescription
cameraEntity

The camera entity

setControllerType(controllerType)

Set the camera controller type of the camera.

Parameters:
NameTypeDescription
controllerTypeSDK3DVerse.cameraControllerType

The camera controller type

Example
const viewport = SDK3DVerse.engineAPI.cameraAPI.getViewports()[0];
viewport.setControllerType(SDK3DVerse.cameraControllerType.orbit);

setGlobalTransform(globalTransform)

Set the camera global transform.

Parameters:
NameTypeDescription
globalTransformTransform

The transform component value

Fires:

setLocalTransform(transform)

Set the camera local transform.

Parameters:
NameTypeDescription
transformTransform

The transform component value

Fires:

setOffset(left, top, triggerViewportUpdateopt)

Set viewport offset within the canvas.

Parameters:
NameTypeAttributesDefaultDescription
leftuint

Left offset in pixels

topuint

Top offset in pixels

triggerViewportUpdateboolean<optional>
true

Update the viewport to make the rendering service adapt it immediately. Set to false to avoid unnecessary updates

setOffsetRatio(leftRatio, topRatio, triggerViewportUpdateopt)

Set viewport offset ratio within the canvas. For example, leftRatio=0.5 and topRatio=0.5 means the top left of the viewport is at the center of the canvas.

Parameters:
NameTypeAttributesDefaultDescription
leftRatiofloat

Left offset ratio normalized into the 0.0 to 1.0 range

topRatiofloat

Top offset ratio normalized into the 0.0 to 1.0 range

triggerViewportUpdateboolean<optional>
true

Update the viewport to make the rendering service adapt it immediately. Set to false to avoid unnecessary updates

(async) smoothLookAt(targetPosition)

Same as Viewport.lookAt but with a travelling animation of the camera using travel.

Parameters:
NameTypeDescription
targetPositionSDK_Vec3

Position to look at in world space

Fires:
Example
const viewport = SDK3DVerse.engineAPI.cameraAPI.getViewports()[0];
viewport.smoothLookAt([0, 0, 0]);

stopTravel()

Stop the camera mid-travel and re-enable inputs. This can be used after a call to travel, or any other functions that call travel such as focusOn or smoothLookAt.

(async) travel(destinationPosition, destinationOrientation, speed, startPositionopt, startOrientationopt)

Animate camera traveling from starting position and orientation to destination position and orientation at a specified speed. Inputs are disabled during travel.

Parameters:
NameTypeAttributesDescription
destinationPositionSDK_Vec3

Destination position of camera

destinationOrientationSDK_Quat

Destination orientation of camera

speednumber

Travel speed. Duration of travel is equal to distance / speed

startPositionSDK_Vec3<optional>

Start position of camera, defaults to current position

startOrientationSDK_Quat<optional>

Start orientation of camera, defaults to current orientation

Fires:
Example
const viewport = SDK3DVerse.engineAPI.cameraAPI.getViewports()[0];
await viewport.travel([0,0,0], [0,0,0,1], 10);

(async) travelToClient(clientUUID, speed)

Animate camera traveling from current position to specified client's camera. The client camera used is the first camera returned by getClientCameras. Inputs are disabled during travel.

Parameters:
NameTypeDescription
clientUUIDstring

UUID of client being traveled to

speednumber

Travel speed. Duration of travel is equal to distance / speed

See
Fires:
Example
const viewport = SDK3DVerse.engineAPI.cameraAPI.getViewports()[0];
const currentClientUUID = SDK3DVerse.getClientUUID();
const otherClientUUID = SDK3DVerse.getClientUUIDs().find(uuid => uuid !== currentClientUUID);
await viewport.travelToClient(otherClientUUID, 10);

unproject(screenCoordinate, normalizedDepth) → {SDK_Vec3}

Project a position in the viewport screen space to a point in world space.

Parameters:
NameTypeDescription
screenCoordinateSDK_Vec2_uint

Position in viewport screen space. [0, 0] = Top left, [canvas width, canvas height] = Bottom right, [0, canvas height] = Bottom left, [canvas width, 0] = Top right

normalizedDepthfloat

Depth between the near and far planes of the camera frustum, normalized in the [0.0, 1.0] range

Returns:

Projected point in world space at a distance equal to normalizedDepth.

Type: 
SDK_Vec3