framebufferScaleFactor is inconsistently documented

[klausw]

Does setting framebufferScaleFactor to 1.0 mean using the maximum supported by the device, or does it mean "full resolution" in the sense of a 1:1 pixel mapping? The explainer is inconsistent and appears to assume that this is equivalent, but in practice these can be very different.

https://github.com/immersive-web/webxr/blob/master/explainer.md says:

While in exclusive sessions, the UA is responsible for providing a framebuffer that is correctly optimized for presentation to the XRSession in each XRPresentationFrame. Developers can optionally request either the buffer size or viewport size be scaled, though the UA may not respect the request. Even when the UA honors the scaling requests, the result is not guaranteed to be the exact percentage requested.

The first scaling mechanism is done by specifying a framebufferScaleFactor at XRWebGLLayer creation time. In response, the UA may create a framebuffer that is based on the requested percentage of the maximum size supported by the XRDevice. On some platforms such as Daydream, the UA may set the default value of framebufferScaleFactor to be less 1.0 for performance reasons. Developers explicitly wishing to use the full resolution on these devices can do so by requesting the framebufferScaleFactor be set to 1.0.

On a desktop VR system, it's common to use a framebuffer scale greater than 1.0 to get supersampling, and there may not be a hardcoded maximum, or the maximum may be unrealistically large for typical applications. Just to add to the complication, there may well be a default scaling factor supplied by the VR system, such as SteamVR's automatic resolution adjustment, so that a value of 1.0 may actually result in high supersampling on one system and low supersampling on another, and the details will also depend on user config overrides outside the browser.

Daydream on Android uses 1.0 to mean 1:1 resolution. That's currently also the maximum supported (I think), but it's entirely possible that future devices could support greater-than-1:1 resolutions.

[klausw]

Based on Brandon's offline comments, it sounds as if the framebufferScaleFactor is supposed to be 1.0 for 1:1 pixel mapping, with both larger and smaller values being possible.

One more issue is how this value is scaled. Daydream applies the scale factor to each dimension separately, so a scale of 2.0 means 4 times the pixel count. OpenVR uses a pixel count ratio for its internal supersampling settings, where a scale of 2.0 means twice the pixels and a 1.41 scale factor for each dimension. Either one would work for this purpose, but the spec needs to be clear which one is being used so that implementations can handle it consistently.

[toji]

Should be resolved by #353. A framebufferScaleFactor of 1.0 is now always the recommended value. To get a scale factor that would yield a 1:1 buffer developers can query XRWebGLLayer.getNativeFramebufferScaleFactor(xrSession).