Stage

A stage in Helio is a 3D box in which you can place 3D objects that are outside the bounds of the browser viewport and aren't placed in their own prism, similar to a 3D canvas. The stage includes the browser window as an object within it and can never be smaller than the browser's viewport.

The default stage size is 1120w, 560h, 1120d, assuming the browser is the default size.

As an alternative to using the prismatic <ml-stage></ml-stage> HTML element, developers could also use the stage API to request permission to change the dimensions of the stage in which they can place 3D content.

Syntax

stageExtent()

This returns the current stage extent as defined by the MLStageExtent structure. The stage adds extra space to the current viewport size.

Define stage extents in meters.

MLStageExtent {
  top,    // expands stage in +y direction
  right,  // expands stage in +x direction
  bottom, // expands stage in -y direction
  left,   // expands stage in -x direction
  front,  // expands stage in +z direction
  back    // expands stage in -z direction
}

setStageExtent(MLStageExtent stageExt)

This requests permission from the user to change the stage size. If permission is granted, this sets a new stage extent specified by the stageExt parameter. It returns a token that is used to check the user’s decision on the permission dialog. This throws an exception if there's an error, such as setting the stage extents to less than 0.

var stageExt = new MLStageExtent(0.1, 0.2, 0.1, 0.2, 0.15, 0.15);

window.mlWorld.setStageExtent(stageExt).then((result) => {
 if (result.state == 'granted') {
   // For standard perm implementation
   console.log("Stage perm is granted"); // allow pressed
 } else if (result.state == 'denied') {
   console.log("Stage perm is denied"); // block pressed
 }
 console.log(
   "Stage after resize, width: " + window.mlWorld.stageSize.x +
   " height: " + window.mlWorld.stageSize.y +
   " breadth: " + window.mlWorld.stageSize.z);
}).catch((error) => {
 console.log("Stage resize failed: " + error.message);
});

resetStageExtent()

This call resets the stage extents to the default.

window.mlWorld.resetStageExtent();

stageSize()

This returns the current stage size, which includes the current stage extent. Internally, the stage size is calculated like this:

Stage width = viewport width + left_extent + right_extent;
Stage height = viewport height + top_extent + bottom_extent;
Stage breadth = max(viewport width, viewport height) + front_extent + back_extent;

window.mlWorld.stageSize.x // stage width
window.mlWorld.stageSize.y // stage height
window.mlWorld.stageSize.z // stage breadth

mlstage event

This event occurs when the stage extent has been changed. As a consequence of changing the extents, the stage size also changes. To get values use window.mlWorld.stageSize() and window.mlWorld.stageExtent().

document.addEventListener("mlstage", function(){
  console.log("Stage size has been changed!");
});