Explainer seems to under-explain API

[alice]

I'm coming here from the TAG review thread.

The "API details" section in the Explainer is a little hazy on the arguments for the two createAnchor() methods - arguments are alluded to but not listed in the method signatures, and the argument types aren't spelled out.

Also, this seems to be the first mention of "anchor space". What is an anchor space? What is its type?

Possibly relatedly, how would I use an anchor to position objects relative to the anchor?

Finally, why is createAnchor() asynchronous? When might it reject?

[bialpio]

Thanks for taking a look! Answers below, let me know if I have not addressed something appropriately.

I'm coming here from the TAG review thread.

The "API details" section in the Explainer is a little hazy on the arguments for the two createAnchor() methods - arguments are alluded to but not listed in the method signatures, and the argument types aren't spelled out.

I was under the impression that explainers should be a bit hazy on the details (i.e. we should not put Web IDL in the explainers, just provide a teaser on how the API could be used), but I'm OK with placing the IDL in the explainer if you think it would help.

Also, this seems to be the first mention of "anchor space". What is an anchor space? What is its type?

Possibly relatedly, how would I use an anchor to position objects relative to the anchor?

anchorSpace is of type XRSpace. I think it may be helpful to read the explainer with the context of WebXR specification - it would not help with directly establishing what type an anchorSpace is, but it could hopefully suggest that it is related to XRSpace (the fact that it is used with XRFrame.getPose() could also hint at this). Including Web IDL would clear this up.

If you know where the object should be placed relative to an anchor (presumably, you will have it available as a matrix representing a rigid transformation, or in some other format), then on every frame you can query the pose of an anchor and apply that transformation to determine where the object should be displayed. In general, it's up to the application to ensure that it maintains the position of the objects relative to an anchor in the way it wants.

Finally, why is createAnchor() asynchronous? When might it reject?

Mainly because it may require user agents to issue a call to the device that provides the capabilities used to implement anchors API. On Chrome (and most likely other browsers) that involves inter-process communication with the process that is allowed to interact with the device. There are various internal errors that may cause the API to reject (i.e. passing invalid parameters to the method, internal error related to math calculations, device rejecting the call for some reason like insufficient resources, etc.).

[alice]

I was under the impression that explainers should be a bit hazy on the details (i.e. we should not put Web IDL in the explainers, just provide a teaser on how the API could be used), but I'm OK with placing the IDL in the explainer if you think it would help.

Hmm, reasonable point! I filed an issue on us to figure out what the best guidance should be here: w3ctag/tag.w3.org#26

I think in this instance, just listing the arguments like you would in a function declaration would be fine, e.g.

XRFrame.createAnchor(anchorPose, referenceSpace)

and explain in prose that it returns an instance of XRAnchor.

anchorSpace is of type XRSpace.

This would be a good thing to note in the explainer.

I think it may be helpful to read the explainer with the context of WebXR specification - it would not help with directly establishing what type an anchorSpace is, but it could hopefully suggest that it is related to XRSpace (the fact that it is used with XRFrame.getPose() could also hint at this).

It would be helpful to explain all this in the explainer, with links into the relevant parts of the spec and/or related explainers - I have read the spec previously, but it was a long time ago and I've forgotten the details in the meantime. A refresher which doesn't require me to re-read the entire spec would be very useful!

on every frame you can query the pose of an anchor and apply that transformation to determine where the object should be displayed.

Could we have this as an example code snippet?

Also, does this imply that there is another member on XRAnchor other than anchorSpace, or are you using "pose" to refer to the transformation of anchorSpace relative to its reference space?

Mainly because it may require user agents to issue a call to the device that provides the capabilities used to implement anchors API. On Chrome (and most likely other browsers) that involves inter-process communication with the process that is allowed to interact with the device.

This seems worth noting in the "API Considerations" section.