Classes
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.
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
entity | Entity | |||
options | object | <optional> | {} | Travel animation options |
startPosition | SDK_Vec3 | <optional> | Initial position of camera, defaults to its current position | |
startOrientation | SDK_Quat | <optional> | Initial orientation of camera, defaults to its current orientation | |
speedFactor | float | <optional> | 4 | Travel animation speed |
distanceShift | float | <optional> | 0 | Distance before entity to stop camera animation |
const viewport = SDK3DVerse.engineAPI.cameraAPI.getViewports()[0];
viewport.focusOn(entity, { speedFactor : 10 });
getAreaSize() → {SDK_Vec2_uint}
Get the viewport area size within the canvas.
[width, height]
in pixels.
- Type:
- SDK_Vec2_uint
getCamera() → {Entity}
Get the camera entity associated with the viewport.
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.
- Type:
- SDK3DVerse.
cameraControllerType |null
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.
The global transform of the viewport's camera.
- Type:
- Transform
getId() → {uint}
Get the viewport id.
The viewport id.
- Type:
- uint
getOffset() → {SDK_Vec2_uint}
Get the viewport offset within the canvas.
[left, top]
in pixels.
- Type:
- SDK_Vec2_uint
getProjection() → {object}
Get the lens component of the camera, e.g. perspective_lens component.
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.
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.
The view projection matrix.
- Type:
- mat4
getWorldMatrix() → {mat4}
Get the world matrix of the camera.
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.
Name | Type | Description |
---|---|---|
position | SDK_Vec2_uint | The canvas position in pixels |
True if the position is within viewport area.
- Type:
- boolean
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.
Name | Type | Description |
---|---|---|
targetPosition | SDK_Vec3 | Position to look at in world space |
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.
Name | Type | Description |
---|---|---|
position | SDK_Vec3 | Position in world space |
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.
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
travelingDurationInSec | uint | <optional> | 0 | If superior to zero, then animate a camera traveling to its default transform for the specified duration using travel |
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.
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
widthRatio | float | The width ratio normalized into the 0.0 to 1.0 range | ||
heightRatio | float | The height ratio normalized into the 0.0 to 1.0 range | ||
triggerViewportUpdate | boolean | <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.
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
width | uint | Width in pixels | ||
height | uint | Height in pixels | ||
triggerViewportUpdate | boolean | <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.
Name | Type | Description |
---|---|---|
camera | Entity | The camera entity |
setControllerType(controllerType)
Set the camera controller type of the camera.
Name | Type | Description |
---|---|---|
controllerType | SDK3DVerse. |
const viewport = SDK3DVerse.engineAPI.cameraAPI.getViewports()[0];
viewport.setControllerType(SDK3DVerse.cameraControllerType.orbit);
setGlobalTransform(globalTransform)
Set the camera global transform.
Name | Type | Description |
---|---|---|
globalTransform | Transform | The transform component value |
setLocalTransform(transform)
Set the camera local transform.
Name | Type | Description |
---|---|---|
transform | Transform | The transform component value |
setOffset(left, top, triggerViewportUpdateopt)
Set viewport offset within the canvas.
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
left | uint | Left offset in pixels | ||
top | uint | Top offset in pixels | ||
triggerViewportUpdate | boolean | <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.
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
leftRatio | float | Left offset ratio normalized into the 0.0 to 1.0 range | ||
topRatio | float | Top offset ratio normalized into the 0.0 to 1.0 range | ||
triggerViewportUpdate | boolean | <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.
Name | Type | Description |
---|---|---|
targetPosition | SDK_Vec3 | Position to look at in world space |
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.
Name | Type | Attributes | Description |
---|---|---|---|
destinationPosition | SDK_Vec3 | Destination position of camera | |
destinationOrientation | SDK_Quat | Destination orientation of camera | |
speed | number | Travel speed. Duration of travel is equal to distance / speed | |
startPosition | SDK_Vec3 | <optional> | Start position of camera, defaults to current position |
startOrientation | SDK_Quat | <optional> | Start orientation of camera, defaults to current orientation |
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.
Name | Type | Description |
---|---|---|
clientUUID | string | UUID of client being traveled to |
speed | number | Travel speed. Duration of travel is equal to distance / speed |
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.
Name | Type | Description |
---|---|---|
screenCoordinate | SDK_Vec2_uint | Position in viewport screen space. |
normalizedDepth | float | Depth between the near and far planes of the camera frustum, normalized in the [0.0, 1.0] range |
Projected point in world space at a distance equal to normalizedDepth
.
- Type:
- SDK_Vec3