Configure WebXR camera layers

[ashconnell]

Is your feature request related to a problem? Please describe.

By default the WebXR cameras don't match the layers configured on your main scene camera.

This poses an issue if you make heavy use of layers to show and hide certain objects dynamically, as people in VR will see different things to people outside of VR.

The WebXRManager exposes the .getCamera() method which returns an empty ArrayCamera, and once XR starts ArrayCamera.cameras is populated with the left and right eye cameras.

All three of these XR cameras need to have their layers updated to match the same functionality as the non-XR camera.

To complicate this more, care is needed when modifying the layers of the child cameras as the left eye is hardcoded to use layer 1 and the right eye layer 2, and these shouldn't be modified.

Describe the solution you'd like

Ideally the WebXRManager would automatically inherit the layers used by the main camera, but this poses a problem when the xr cameras have a tight requirement/convention on layers 1 and 2 for the left and right eye. It might be more feasible to use layers 31 and 32 to reduce chance of end user issues.

A simpler solution might be to add something like WebXRManager.setLayers(bitmask) which updates all the cameras for you, and also checks to ensure you dont break the left and right eye layer convention.

An even simpler solution could be to just expose the left and right eye cameras, eg WebXRManager.getLeftCamera(). Ultimately this would provide maximum potential with the lowest effort ✅

Describe alternatives you've considered

For now we're resorting to a hack where before we render each frame we run this function, and exit early once the cameras are configured.

configureXRCamera() {
  /**
   * HACK
   * ----
   * The WebXRManager uses its own cameras and they don't match the layers
   * configured on our main scene camera.
   * This is worsened by the fact that we don't have an easy way to preconfigure
   * these camera layers as WebXRManager.getCamera() returns an empty ArrayCamera
   * that isn't populated until XR starts.
   * In addition, for some reason both the ArrayCamera and its sub-cameras need to
   * have layers all updated.
   */
  if (this.xrCameraConfigured) return
  if (this.xrCamera.cameras.length) {
    // configure main xr camera
    this.xrCamera.layers.enableAll()
    this.xrCamera.layers.disable(GraphicsLayers.GHOST)
    // configure left eye camera
    this.xrCamera.cameras[0].layers.enableAll()
    this.xrCamera.cameras[0].layers.disable(GraphicsLayers.XR_RIGHT_EYE)
    this.xrCamera.cameras[0].layers.disable(GraphicsLayers.GHOST)
    // configure right eye camera
    this.xrCamera.cameras[1].layers.enableAll()
    this.xrCamera.cameras[1].layers.disable(GraphicsLayers.XR_LEFT_EYE)
    this.xrCamera.cameras[1].layers.disable(GraphicsLayers.GHOST)
    // never run this again!
    this.xrCameraConfigured = true
  }
}

Additional context

None

[mrxz]

Faced the same issue. Setting the layers on the XR camera is very cumbersome and error-prone. You have to set the right layers on all three cameras (or two in case of smartphone AR), but the sub-cameras are only accessible once the session has started.

It might make sense to copy over the layers mask from the camera passed to render. Currently the following straightforward code already presents its first gotcha, as during the XR session the layers of camera don't apply.

// Configure the layer mask of camera
camera.layers.enable(10);

// Render the scene
renderer.render(scene, camera); // <--- camera.layers gets ignored during XR session