Webxr: The Great Bikeshedding II: XRFrameOfReference and XRCoordinateSystem

[NellWaliczek]

Now that #409 has been merged, it’s time to bikeshed all the names! Here’s the list of what is being reviewed in this issue:

• XRFrameOfReference
  
  
  
  • XRStationaryFrameOfReference
  
  
  • XRStationaryFrameOfReferenceSubtype
    
    
    
    
    
    • position-disabled
    
    
    
    • eye-level
    
    
    
    • floor-level
    
    
    
  
  
  • XRBoundedFrameOfReference
  
  
  • XRUnboundedFrameOfReference
  
  
• XRCoordinateSystem

I'm feeling fairly good about the terms "stationary", "bounded", "unbounded", "eye-level", "floor-level", and "position-disabled" (though please chime in if you disagree!). However, I'd really like to find better terms for "frame of reference" and "coordinate system".

As we dig into this, part of the difficulty is that there are a lot of common concepts with OpenXR and I’d like to avoiding picking a name for a WebXR type that’s used to represent a different concept in OpenXR. For example, while my original inclination was to propose something like this:

• XRFrameOfReference -> XRStage
• XRCoordinateSystem -> XRSpatialRoot

I’m got feedback that in OpenXR the term “XRStage” is more closely mapped to the WebXR concept of “XRBoundedFrameOfReference. In response, I started to consider

• XRFrameOfReference -> XRSpace
• XRCoordinateSystem -> XRSpatialRoot

But then I got the feedback that in OpenXR the term “XRSpace” is more closely mapped to the WebXR concept of “XRCoordinateSystem”.

At this point I have tried and discarded about 2 dozen names (XROrigin, XRTracking, XRSubstrate, XRSpatialSubstrate, XRHelpImDrowningInBikeshedding, etc.), and I personally keep coming back to the same things. So, keeping in mind that this may be confusing with OpenXR, I'd like to propose it as a starting point anyway.

• XRFrameOfReference -> XRStage
• XRCoordinateSystem -> XRSpatialRoot

Other suggestions?

[thetuvix]

To answer @NellWaliczek's challenge from the call, I am proposing three strawman alternatives here. The intent here is to spur discussion, so please respond with your own proposals!

I encourage others proposing naming alternatives to consider XRCoordinateSystem and XRFrameOfReference holistically, including whether an "is-a" vs. "has-a" pattern better fits the naming pattern, and whether an XRCoordinateSystem can track dynamically moving objects such as a head or controller, as discussed in #384.

Idea 1:

• XRSpace (replaces XRCoordinateSystem)
  
  
  
  • XRReferenceSpace (replaces XRFrameOfReference)
  
  
  • XRStationaryReferenceSpace
    
    
    
    
    
    • XRStationaryReferenceSpaceSubtype
    
    
    
    • "position-disabled"
    
    
    
    • "eye-level"
    
    
    
    • "floor-level"
    
    
    
  
  
  • XRBoundedReferenceSpace
  
  
  • XRUnboundedReferenceSpace
  
  

Has one or more XRSpace attributes:

• XRAnchor
  
  
  
  • XRPlaneAnchor (with extents attribute, etc.)
  
  
  • XRFaceAnchor (with getGeometry() method, etc.)
  
  
  • XRMeshAnchor (with getVertexBuffer() method, etc.)
  
  
• XRViewer
• XRInputSource (has grip and pointer spaces, etc.)

This approach explicitly establishes an XRReferenceSpace as a special core type of XRSpace that you make first, within which you reason about any other space. This feels meaningful even if types like XRInputSource are not subtypes of XRSpace - reference spaces are fundamentally about core spatial reasoning, while an XRInputSource will have lots of other members that are not about spatial reasoning.

Idea 2:

• XREntity (replaces XRCoordinateSystem)
  
  
  
  • XRAnchor
  
  
  • XRPlaneAnchor (with extents attribute, etc.)
  
  
  • XRFaceAnchor (with getGeometry() method, etc.)
  
  
  • XRMeshAnchor (with getVertexBuffer() method, etc.)
  
  
  • XRViewer
  
  
  • XRInputSource (has grip and pointer spaces, etc.)
  
  

Has a rootEntity attribute of type XREntity:

• XRWorldOrigin (replaces XRFrameOfReference)
  
  
  
  • XRStationaryWorldOrigin
  
  
  • XRStationaryWorldOriginSubtype
    
    
    
    
    
    • "position-disabled"
    
    
    
    • "eye-level"
    
    
    
    • "floor-level"
    
    
    
  
  
  • XRBoundedWorldOrigin
  
  
  • XRUnboundedWorldOrigin
  
  

This approach explicitly embraces the mental model of a traditional game engine, which needs to establish a single world origin for its single scene hierarchy, within which you reason about entities. In this model, the fundamental thing you are choosing is the XRWorldOrigin to serve as that scene root, which would have a rootEntity attribute that returns an XREntity that can serve as the root node in your scene graph. You'd likely then reason about all other XREntity instances as model transforms within that world origin.

Idea 3:

• XRSpace (replaces XRCoordinateSystem)

Has one or more XRSpace attributes:

• XRRoot (replaces XRFrameOfReference)
  
  
  
  • XRStationaryRoot
  
  
  • XRStationaryRootSubtype
    
    
    
    
    
    • "position-disabled"
    
    
    
    • "eye-level"
    
    
    
    • "floor-level"
    
    
    
  
  
  • XRBoundedRoot
  
  
  • XRUnboundedRoot
  
  
• XRAnchor
  
  
  
  • XRPlaneAnchor (with extents attribute, etc.)
  
  
  • XRFaceAnchor (with getGeometry() method, etc.)
  
  
  • XRMeshAnchor (with getVertexBuffer() method, etc.)
  
  
• XRViewer
• XRInputSource (has grip and pointer spaces, etc.)

This approach optimizes for terseness. Developers start off in WebXR by choosing an XRRoot, which establishes the base for all their other reasoning about XRSpace instances. This results in very short type and method names, though perhaps they end up too short to be meaningful without more extra context (e.g. xrSession.requestRoot(...)).

[toji]

I'll put up a vote of support for XRSpace replacing XRCoordinateSystem, with either XRRoot or XRReferenceSpace as the XRFrameOfReference replacement. (With a preference for the latter since, despite it's length, it establishes the relationship to XRSpace better).

Nell's suggestion of XRSpatialRoot works for me too, but it sounds more natural to me if it replaces XRFrameOrReference instead of XRCoordinateSystem as was the original suggestion.

[toji]

In an effort to try and keep this moving so we can wrap it up soon, I'm going to formally suggest that we follow Alex's Idea 1 naming for frames of reference/coordinate systems. I'll partially repeat it here for easy reference:

Idea 1:

• XRSpace (replaces XRCoordinateSystem)
  
  
  
  • XRReferenceSpace (replaces XRFrameOfReference)
  
  
  • XRStationaryReferenceSpace
    
    
    
    
    
    • XRStationaryReferenceSpaceSubtype
    
    
    
  
  
  • XRBoundedReferenceSpace
  
  
  • XRUnboundedReferenceSpace
  
  

Alex also implied that this naming suggests a "is-a" pattern, in that the XRReferenceSpace would extend the XRSpace, which is I don't see as a problem. (The current explainer has them as a "has-a" pattern, but I think the primary impact of that is avoiding some WebIDL-induced silliness around which type extends EventTarget).

I'm still open to hearing dissenting opinions, but given that this issue has been pretty quiet I doubt I'll get to many complaints if I take the initiative to put together a PR to wrap it up at this point.

[NellWaliczek]

Sounds good to me! I did a quick straw poll around the office and folks seemed to dig this naming scheme.

Are folks happy with "Stationary", "Bounded", and "Unbounded"?
What about "Subtype"?

[TrevorFSmith]

Yes! I like these new names (and the is-a pattern) 💯 more than the old names for reasons of newbie developer clarity and ease of future extension.

[thetuvix]

This is great - I'm glad we've converged here!

One other note is that the design we landed on, with the following having one or more XRSpace attributes, implies that an XRSpace for a type like XRFaceAnchor can be a dynamic space, as discussed in #384:

• XRAnchor
  
  
  
  • XRPlaneAnchor (with extents attribute, etc.)
  
  
  • XRFaceAnchor (with getGeometry() method, etc.)
  
  
  • XRMeshAnchor (with getVertexBuffer() method, etc.)
  
  
• XRViewer
• XRInputSource (has grip and pointer spaces, etc.)

After #435 is merged, we should continue discussion on #384 to make sure that the API is ready for such dynamic spaces.