Represents an XR View which represents a screen (monoscopic scenario such as a mobile phone) or an eye (stereoscopic scenario such as an HMD context). It provides access to the view's color and depth information based on the capabilities of underlying AR system.

Hierarchy (view full)

Accessors

  • get depthUvMatrix(): Mat4
  • 4x4 matrix that should be used to transform depth texture UVs to normalized UVs in a shader. It is updated when the depth texture is resized. Refer to XrView#depthResize.

    Returns Mat4

    material.setParameter('matrix_depth_uv', view.depthUvMatrix.data);
    
  • get depthValueToMeters(): number
  • Multiply this coefficient number by raw depth value to get depth in meters.

    Returns number

    material.setParameter('depth_to_meters', view.depthValueToMeters);
    
  • get textureDepth(): Texture
  • Texture that contains packed depth information which is reconstructed using the underlying AR system. This texture can be used (not limited to) for reconstructing real world geometry, virtual object placement, occlusion of virtual object by the real world geometry, and more. The format of this texture is PIXELFORMAT_LA8 or PIXELFORMAT_R32F based on XrViews#depthFormat. It is UV transformed based on the underlying AR system which can be normalized using XrView#depthUvMatrix. Equals to null if camera depth is not supported.

    Returns Texture

    // GPU path, attaching texture to material
    material.setParameter('texture_depthSensingMap', view.textureDepth);
    material.setParameter('matrix_depth_uv', view.depthUvMatrix.data);
    material.setParameter('depth_to_meters', view.depthValueToMeters);
    // GLSL shader to unpack depth texture
    varying vec2 vUv0;

    uniform sampler2D texture_depthSensingMap;
    uniform mat4 matrix_depth_uv;
    uniform float depth_to_meters;

    void main(void) {
    // transform UVs using depth matrix
    vec2 texCoord = (matrix_depth_uv * vec4(vUv0.xy, 0.0, 1.0)).xy;

    // get luminance alpha components from depth texture
    vec2 packedDepth = texture2D(texture_depthSensingMap, texCoord).ra;

    // unpack into single value in millimeters
    float depth = dot(packedDepth, vec2(255.0, 256.0 * 255.0)) * depth_to_meters; // m

    // normalize: 0m to 8m distance
    depth = min(depth / 8.0, 1.0); // 0..1 = 0m..8m

    // paint scene from black to white based on distance
    gl_FragColor = vec4(depth, depth, depth, 1.0);
    }
  • get viewport(): Vec4
  • A Vec4 (x, y, width, height) that represents a view's viewport. For monoscopic screen it will define fullscreen view, but for stereoscopic views (left/right eye) it will define a part of a whole screen that view is occupying.

    Returns Vec4

Methods

  • Fire an event, all additional arguments are passed on to the event listener.

    Parameters

    • name: string

      Name of event to fire.

    • Optionalarg1: any

      First argument that is passed to the event handler.

    • Optionalarg2: any

      Second argument that is passed to the event handler.

    • Optionalarg3: any

      Third argument that is passed to the event handler.

    • Optionalarg4: any

      Fourth argument that is passed to the event handler.

    • Optionalarg5: any

      Fifth argument that is passed to the event handler.

    • Optionalarg6: any

      Sixth argument that is passed to the event handler.

    • Optionalarg7: any

      Seventh argument that is passed to the event handler.

    • Optionalarg8: any

      Eighth argument that is passed to the event handler.

    Returns EventHandler

    Self for chaining.

    obj.fire('test', 'This is the message');
    
  • Get depth value from depth information in meters. UV is in range of 0..1, with origin in top-left corner of a texture.

    Parameters

    • u: number

      U coordinate of pixel in depth texture, which is in range from 0.0 to 1.0 (left to right).

    • v: number

      V coordinate of pixel in depth texture, which is in range from 0.0 to 1.0 (top to bottom).

    Returns number

    Depth in meters or null if depth information is currently not available.

    const depth = view.getDepth(u, v);
    if (depth !== null) {
    // depth in meters
    }
  • Test if there are any handlers bound to an event name.

    Parameters

    • name: string

      The name of the event to test.

    Returns boolean

    True if the object has handlers bound to the specified event name.

    obj.on('test', function () { }); // bind an event to 'test'
    obj.hasEvent('test'); // returns true
    obj.hasEvent('hello'); // returns false
  • Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.

    Parameters

    • Optionalname: string

      Name of the event to unbind.

    • Optionalcallback: HandleEventCallback

      Function to be unbound.

    • Optionalscope: object

      Scope that was used as the this when the event is fired.

    Returns EventHandler

    Self for chaining.

    const handler = function () {
    };
    obj.on('test', handler);

    obj.off(); // Removes all events
    obj.off('test'); // Removes all events called 'test'
    obj.off('test', handler); // Removes all handler functions, called 'test'
    obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this
  • Attach an event handler to an event.

    Parameters

    • name: string

      Name of the event to bind the callback to.

    • callback: HandleEventCallback

      Function that is called when event is fired. Note the callback is limited to 8 arguments.

    • Optionalscope: object = ...

      Object to use as 'this' when the event is fired, defaults to current this.

    Returns EventHandle

    Can be used for removing event in the future.

    obj.on('test', function (a, b) {
    console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console
    const evt = obj.on('test', function (a, b) {
    console.log(a + b);
    });
    // some time later
    evt.off();
  • Attach an event handler to an event. This handler will be removed after being fired once.

    Parameters

    • name: string

      Name of the event to bind the callback to.

    • callback: HandleEventCallback

      Function that is called when event is fired. Note the callback is limited to 8 arguments.

    • Optionalscope: object = ...

      Object to use as 'this' when the event is fired, defaults to current this.

    Returns EventHandle

    • can be used for removing event in the future.
    obj.once('test', function (a, b) {
    console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console
    obj.fire('test', 1, 2); // not going to get handled

Events

EVENT_DEPTHRESIZE: string = 'depth:resize'

Fired when the depth sensing texture been resized. The XrView#depthUvMatrix needs to be updated for relevant shaders. The handler is passed the new width and height of the depth texture in pixels.

view.on('depth:resize', () => {
material.setParameter('matrix_depth_uv', view.depthUvMatrix);
});