Use consistent language and approach to document algorithms

[chrislo]

The following issue was raised by the W3C TAG as part of their review of the Web Audio API

---

What language are the examples in Section 11 written in? Can it be executed?

[olivierthereaux]

What language are the examples in Section 11 written in?

Since section numbering changes now and then, let me clarify that this refers to Section 11. Spatialization / Panning (http://www.w3.org/TR/webaudio/#Spatialization)

I am not an expert on pseudo-code, but this looks like c++, assuming usage of a vector library such as https://code.google.com/p/slmath/.

Unsurprisingly, it is derived very closely from Chrome source:
https://chromium.googlesource.com/chromium/blink/+/master/Source/modules/webaudio/PannerNode.cpp
Look for

void PannerNode::getAzimuthElevation(double* outAzimuth, double* outElevation)

Can it be executed?

Not really, seeing as the actual data the example is supposed to process is not present. I don't think this is the actual problem - it is describing an algorithm which is to be followed to calculate azimuth and elevation.

My question would be more along the lines of - do we need this pseudo-code at all, seeing as azimuth and elevation are fairly well-defined mathematical constructs?

[padenot]

I'd rather keep it. If needed we can convert it to Javascript.

Note that we are going to modify it slightly, as we have found a couple problems while implementing it in Gecko. There is an ML thread about that by Karl, iirc.

[olivierthereaux]

Is this the thread you refer to?
http://lists.w3.org/Archives/Public/public-audio/2013JulSep/0570.html

[ghost]

Olivier Thereaux writes:

Is this the thread you refer to?
http://lists.w3.org/Archives/Public/public-audio/2013JulSep/0570.html

That thread was about what to do when the input directions didn't
allow azimuth and elevation to be defined.

There was also the fact that azimuth is not defined when elevation
is ±90° [1].

Really the bug here is in the "equalpower" model, where the axis
of symmetry should be the left-right axis, instead of the down-up
axis. That would remove the singularities when the source is
above or below the listener.

Olivier Thereaux writes:

What language are the examples in Section 11 written in?
My question would be more along the lines of - do we need this pseudo-code at
all, seeing as azimuth and elevation are fairly well-defined mathematical
constructs?

I'm not sure that "azimuth" is necessarily defined to be zero when
the point of interest is in front of the listener. I could
imagine a definition where azimuth is zero when the point of
interest is to the right.

Perhaps the full algorithm is not necessary, but if that is
removed then I think we'd still need to spell out some details.

All of this would be kind of irrelevant if we fix the equalpower
model. That really needs quite a different angle, like an
elevation but on the left-right axis, and that would need to be
defined clearly.

Karl.

[1] https://bugzilla.mozilla.org/show_bug.cgi?id=907986#c8

[joeberkovitz]

Are these examples still relevant given the changes to PannerNode?

[padenot]

We could simply unify all the codes in the spec (whether normative or informative) to be JavaScript. We may need to define the vector operations. Then, it's very possible that it could be executed.

[joeberkovitz]

Resolution: we will use JavaScript