Class XrHitTest

The Hit Test interface allows initiating hit testing against real-world geometry from various sources: the view, input sources, or an arbitrary ray in space. Results reflect the underlying AR system's understanding of the real world.

Hierarchy (View Summary)

Properties

sources

Accessors

available supported

Methods

fire hasEvent off on once start

Events

EVENT_ADD EVENT_AVAILABLE EVENT_ERROR EVENT_REMOVE EVENT_RESULT EVENT_UNAVAILABLE

Properties

sources

sources: XrHitTestSource[] = []

List of active XrHitTestSource.

Accessors

available

supported

Methods

fire

  • fire(
        name: string,
        arg1?: any,
        arg2?: any,
        arg3?: any,
        arg4?: any,
        arg5?: any,
        arg6?: any,
        arg7?: any,
        arg8?: any,
    ): EventHandler

  • 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.

    Example

    obj.fire('test', 'This is the message');

hasEvent

  • hasEvent(name: string): boolean

  • 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.

    Example

    obj.on('test', function () { }); // bind an event to 'test'
    obj.hasEvent('test'); // returns true
    obj.hasEvent('hello'); // returns false

off

  • off(name?: string, callback?: HandleEventCallback, scope?: object): EventHandler

  • 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.

    Example

    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

on

  • on(name: string, callback: HandleEventCallback, scope?: object): EventHandle

  • 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.

    Example

    obj.on('test', function (a, b) {
        console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console

    Example

    const evt = obj.on('test', function (a, b) {
        console.log(a + b);
    });
    // some time later
    evt.off();

once

  • once(name: string, callback: HandleEventCallback, scope?: object): EventHandle

  • 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.

    Example

    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

start

  • start(
        options?: {
            callback?: XrHitTestStartCallback;
            entityTypes?: string[];
            offsetRay?: Ray;
            profile?: string;
            spaceType?: string;
        },
    ): void

  • Attempts to start hit test with provided reference space.

    Parameters

    • Optionaloptions: {
          callback?: XrHitTestStartCallback;
          entityTypes?: string[];
          offsetRay?: Ray;
          profile?: string;
          spaceType?: string;
      } = {}

      Optional object for passing arguments.

      • Optionalcallback?: XrHitTestStartCallback

        Optional callback function called once hit test source is created or failed.

      • OptionalentityTypes?: string[]

        Optional list of underlying entity types against which hit tests will be performed. Defaults to [ XRTRACKABLE_PLANE ]. Can be any combination of the following:

        • XRTRACKABLE_POINT: Point - indicates that the hit test results will be computed based on the feature points detected by the underlying Augmented Reality system.
        • XRTRACKABLE_PLANE: Plane - indicates that the hit test results will be computed based on the planes detected by the underlying Augmented Reality system.
        • XRTRACKABLE_MESH: Mesh - indicates that the hit test results will be computed based on the meshes detected by the underlying Augmented Reality system.
      • OptionaloffsetRay?: Ray

        Optional ray by which hit test ray can be offset.

      • Optionalprofile?: string

        if hit test source meant to match input source instead of reference space, then name of profile of the XrInputSource should be provided.

      • OptionalspaceType?: string

        Reference space type. Defaults to XRSPACE_VIEWER. Can be one of the following:

        • XRSPACE_VIEWER: Viewer - hit test will be facing relative to viewers space.
        • XRSPACE_LOCAL: Local - represents a tracking space with a native origin near the viewer at the time of creation.
        • XRSPACE_LOCALFLOOR: Local Floor - represents a tracking space with a native origin at the floor in a safe position for the user to stand. The y axis equals 0 at floor level. Floor level value might be estimated by the underlying platform.
        • XRSPACE_BOUNDEDFLOOR: Bounded Floor - represents a tracking space with its native origin at the floor, where the user is expected to move within a pre-established boundary.
        • XRSPACE_UNBOUNDED: Unbounded - represents a tracking space where the user is expected to move freely around their environment, potentially long distances from their starting point.

    Returns void

    Example

    // start hit testing from viewer position facing forwards
    app.xr.hitTest.start({
        spaceType: pc.XRSPACE_VIEWER,
        callback: function (err, hitTestSource) {
            if (err) return;
            hitTestSource.on('result', function (position, rotation) {
                // position and rotation of hit test result
            });
        }
    });

    Example

    // start hit testing using an arbitrary ray
    const ray = new pc.Ray(new pc.Vec3(0, 0, 0), new pc.Vec3(0, -1, 0));
    app.xr.hitTest.start({
        spaceType: pc.XRSPACE_LOCAL,
        offsetRay: ray,
        callback: function (err, hitTestSource) {
            // hit test source that will sample real world geometry straight down
            // from the position where AR session started
        }
    });

    Example

    // start hit testing for touch screen taps
    app.xr.hitTest.start({
        profile: 'generic-touchscreen',
        callback: function (err, hitTestSource) {
            if (err) return;
            hitTestSource.on('result', function (position, rotation, inputSource) {
                // position and rotation of hit test result
                // that will be created from touch on mobile devices
            });
        }
    });

Events

StaticEVENT_ADD

EVENT_ADD: string = 'add'

Fired when new XrHitTestSource is added to the list. The handler is passed the XrHitTestSource object that has been added.

Example

app.xr.hitTest.on('add', (hitTestSource) => {
    // new hit test source is added
});

StaticEVENT_AVAILABLE

EVENT_AVAILABLE: string = 'available'

Fired when hit test becomes available.

Example

app.xr.hitTest.on('available', () => {
    console.log('Hit Testing is available');
});

StaticEVENT_ERROR

EVENT_ERROR: string = 'error'

Fired when failed create hit test source. The handler is passed the Error object.

Example

app.xr.hitTest.on('error', (err) => {
    console.error(err.message);
});

StaticEVENT_REMOVE

EVENT_REMOVE: string = 'remove'

Fired when XrHitTestSource is removed to the list. The handler is passed the XrHitTestSource object that has been removed.

Example

app.xr.hitTest.on('remove', (hitTestSource) => {
    // hit test source is removed
});

StaticEVENT_RESULT

EVENT_RESULT: string = 'result'

Fired when hit test source receives new results. It provides transform information that tries to match real world picked geometry. The handler is passed the XrHitTestSource that produced the hit result, the Vec3 position, the Quat rotation and the XrInputSource (if it is a transient hit test source).

Example

app.xr.hitTest.on('result', (hitTestSource, position, rotation, inputSource) => {
    target.setPosition(position);
    target.setRotation(rotation);
});

StaticEVENT_UNAVAILABLE

EVENT_UNAVAILABLE: string = 'unavailable'

Fired when hit test becomes unavailable.

Example

app.xr.hitTest.on('unavailable', () => {
    console.log('Hit Testing is unavailable');
});

Settings

Member Visibility

On This Page

Properties
Accessors
Methods
Events