For `tracked-pointer` input sources, it is often appropriate for the application to render a contextually appropriate model (such as a racket in a tennis game). Other times it's desirable for the application to render a device that matches what the user is holding, especially when relaying instructions about it's use. Finally, there are times when it's best to not render anything at all, such as when the XR device uses a transparent display and the user can see their hands and/or any tracked devices without app assistance. See [Handling non-opaque displays](explainer.md#Handling-non-opaque-displays) in the main explainer for more details.

The majority of `tracked-pointer` input sources will have a non-null `gamepad` attribute on the `XRInputSource` object. The `Gamepad`'s `id` is used to determine what should be rendered if the app intends to visualize the input source itself, rather than an alternative virtual object. (See the section on [Button and Axis State](#button-and-axis-state) for more details.)

The WebXR Device API currently does not offer any way to retrieve renderable resources that represent the input devices from the API itself, and as such the `Gamepad`'s `id` must be used as a key to load an appropriate resources from the application's server or a CDN. The example below presumes that the `getInputSourceRenderableModel` call would do the required lookup and caching.

function loadRenderableInputModels(xrInputSource) {

// Don't load renderable models if the input source doesn't have a gamepad.

if (!inputSource.gamepad)

return;

// Retrieve a mesh to render based on the gamepad object's id.

let renderableModel = getInputSourceRenderableModel(inputSource.gamepad.id);

if (!renderableModel)

return;

// Add the model to the imaginary 3D engine's scene.

scene.inputObjects.add(renderableModel, xrInputSource);

}

Finally, rendered models of input sources should generally only be shown if the `XRSession`'s `environmentBlendMode` is `'opaque'`, as any other mode implies that the user can see any physical device they may be holding. Rendering cursors, highlights, and pointing rays may still be desirable, depending on the application's needs.

// Don't display input models if the blend mode is not 'opaque'

if (xrFrame.session.environmentBlendMode != 'opaque')

return;

if(xrInputSource.gripSpace) {

Some applications need more than point-and-click style interaction provided by the `select` events. For input sources with buttons and axes, more complete information about the state of those inputs can be observed via the `XRInputSource`'s `gamepad` attribute. `gamepad` is an instance of the [`Gamepad`](https://w3c.github.io/gamepad/#gamepad-interface) interface if the input source has buttons and axes to report, and `null` otherwise.

Examples of input sources that may expose their state this way include Oculus Touch, Vive wands, Oculus Go and Daydream controllers, or other similar devices. Input devices not directly associated with the XR device, such as the majority of traditional gamepads, and tracked devices without discreet inputs, such as optical hand tracking, must not be exposed using this interface.

`Gamepad` instances reported in this way have several notable behavioral changes vs. the ones reported by `navigator.getGamepads()`:

- `Gamepad` instances connected to an `XRInputSource` must not be included in the array returned by `navigator.getGamepads()`.

- The `Gamepad`'s `index` attribute must be `-1`.

- The `Gamepad`'s `connected` attribute must be `true` unless the related `XRInputSource` is removed from the `inputSources` array or the related `XRSession` is ended.

Finally, the `id` attribute for `Gamepad`s surfaced by the WebXR API are more strictly formatted than those of traditional gamepads in order to make them a more appropriate key for determining rendering assets.

- The `id` MAY be `'unknown'` if the type of input source cannot be reliably identified or the UA determines that the input source type must be masked for any reason. Applications should render a generic input device in this case.

- Inline sessions MUST only expose `id`s of `'unknown'`.

- Otherwise the `id` must be a lower-case string that describes the physical input source.

- The exact format is [still under discussion](https://github.com/immersive-web/webxr/issues/550), but will probably need to include at least an indication of the input device's manufacturer and model. (Such as `oculus-touch`)

- It must not include an indication of the handedness of the input source (such as `oculus-touch-left`), as that can be determined from the `handedness` attribute.

- UAs SHOULD make an effort to align on the strings that are returned for any given device.

All other attributes behave as described in the [Gamepad](https://w3c.github.io/gamepad/) specification.

function onXRFrame(timestamp, frame) {

let inputSource = primaryInputSource;

// Check to see if the input source has gamepad data.

if (inputSource && inputSource.gamepad) {

let gamepad = inputSource.gamepad;

// Use joystick or touchpad values for movement.

if (gamepad.axes.length >= 2) {

MoveUser(gamepad.axes[0], gamepad.axes[1]);

}

// If the first gamepad button is pressed, perform an action.

if (gamepad.buttons.length >= 1 && gamepad.buttons[0].pressed) {

EmitPaint();

}

// etc.

}

// Do the rest of typical frame processing...

}

If the application includes interactions that require user activation (such as starting media playback), the application can listen to the `XRInputSource`s `select` events, which fire for every pressed and released button on the controller. When triggered by a controller input, the `XRInputSourceEvent` will include a `buttonIndex` other than `-1` to indicate which button on the gamepad triggered the event.

The UA may update the `gamepad` state at any point, but it must remain constant while running a batch of `XRSession` `requestAnimationFrame` callbacks or event callbacks which provide an `XRFrame`.

The WebXR Device API also introduces a new standard controller layout indicated by the `mapping` value of `xr-standard`. (Additional mapping variants may be added in the future if necessary.) This defines a specific layout for the inputs most commonly found on XR controller devices today. The following table describes the buttons/axes and their physical locations:

| Button | `xr-standard` Location |

| ---------- | --------------------------------- |

| buttons[0] | Primary trigger |

| buttons[1] | Primary Touchpad/Joystick click |

| buttons[2] | Grip/Secondary trigger |

| buttons[3] | Secondary Touchpad/Joystick click |

| Axis | `xr-standard` Location |

| ------- | ----------------------------- |

| axes[0] | Primary Touchpad/Joystick X |

| axes[1] | Primary Touchpad/Joystick Y |

| axes[2] | Secondary Touchpad/Joystick X |

| axes[3] | Secondary Touchpad/Joystick Y |

Additional device-specific inputs may be exposed after these reserved indices, but devices that lack one of the canonical inputs must still preserve their place in the array. If a device has both a touchpad and a joystick the UA should designate one of them to be the primary axis-based input and expose the other at axes[2] and axes[3] with an associated button at button[3].

In order to make use of the `xr-standard` mapping, a device must meet **at least** the following criteria:

- Is a `tracked-pointer` device.

- Has a trigger or similarly accessed button

- Has at least one touchpad or joystick

devices that lack one of those elements may still expose `gamepad` data, but must not claim the `xr-standard` mapping. For example: The controls on the side of a Gear VR would not qualify for the `xr-standard` mapping because they represent a `gaze`-style input. Similarly, a Daydream controller would not qualify for the `xr-standard` mapping since it lacks a trigger.

Some native APIs rely on what's commonly referred to as an "action mapping" system to handle controller input. In action map systems the developer creates a list of application-specific actions (such as "undo" or "jump") and suggested input bindings (like "left hand touchpad") that should trigger the related action. Such systems may allow users to re-bind the inputs associated with each action, and may not provide a mechanism for enumerating or monitoring the inputs outside of the action map.

When using an API that limits reading controller input to use of an action map, it is suggested that a mapping be created with one action per possible input, given the same name as the target input. For example, an similar mapping to the following may be used for each device:

| Button/Axis | Action name | Sample binding |

|-------------|------------------|---------------------------|

| button[0] | "trigger" | "[device]/trigger" |

| button[1] | "touchpad-click" | "[device]/touchpad/click" |

| button[2] | "grip" | "[device]/grip" |

| axis[0] | "touchpad-x" | "[device]/touchpad/x" |

| axis[1] | "touchpad-y" | "[device]/touchpad/y" |

If the API does not provided a way to enumerate the available input devices, the UA should provide bindings for the left and right hand instead of a specific device and expose a `Gamepad` for any hand that has at least one non-`null` input.

The UA must not make any attempt to circumvent user remapping of the inputs.