Bug in the Audio Module with listeners?

[therocode]

I hope this hasn't been discussed before, I couldn't search because I get an error every time I try (DATABASE ERROR Please try again. If you come back to this error screen, report the error to an administrator.).

Anyway, I am curious on this thing which might be a flaw in SFML.

It is regarding the function Listener::setDirection which is implemented like this:

void Listener::setDirection(float x, float y, float z)
{
    priv::ensureALInit();

    float orientation[] = {x, y, z, 0.f, 1.f, 0.f};
    alCheck(alListenerfv(AL_ORIENTATION, orientation));
}
 

Now, what it does is defining two vectors that are passed to OpenAL. The first vector (which is the one given by the user) is the "at" vector which is the direction the listener is facing in the scene. The second vector is the "up" vector which points to the upside relative to the listener. This can be thought of as having the "at" vector pointing out from your nose, and the "up" vector pointing up the top of your head.

Anyway, the function _always_ uses the (0, 1, 0) vector for up which to me looks like it poses a problem. Because the OpenAL specification states this about setting the orientation:

. OpenAL expects two vectors that are linearly
independent. These vectors are not expected to be normalized. If the two vectors are
linearly dependent, behavior is undefined.

The important bit being that they have to be linearly independent. However, with the implementation in SFML, if you would call setDirection(0.0f, 1.0f, 0.0f) or even setDirection(0.0f, 0.5f, 0.0f) etc, they would be linearly dependent and would according to the OpenAL specification cause undefined behaviour.

Is there something I am missing or is this just overlooked by SFML?

[Laurent]

Yes, there's a limitation. And what? What is your feature request?

[therocode]

Ah, dang I must have clicked the wrong subforum! Meant to put it in "general discussion". Sorry about that.

Feel free to move it if you please.

But then is this limitation intended? And why so?
And shouldn't it at least be mentioned in the documentation?

[Laurent]

Ah, dang I must have clicked the wrong subforum! Meant to put it in "general discussion".

"Audio" would be even better

But then is this limitation intended? And why so?

There must be an "up" vector, so there must be a direction which is forbidden for the other axis. That's how it works. If your question is "why is the up vector hard-coded?", then it's to make the API simpler, as in most cases it is +Y.

And shouldn't it at least be mentioned in the documentation?

Yep.

[therocode]

There must be an "up" vector, so there must be a direction which is forbidden for the other axis. That's how it works. If your question is "why is the up vector hard-coded?", then it's to make the API simpler, as in most cases it is +Y.

Yep, I know they have to be different.

I suspected that the reason was to make a simpler API. Personally I disagree with that solution since I find it unacceptable to just accept that one arbitrarily chosen specific number is forbidden and just doesn't work. As you said the axes having to be different is "how it works" so why not let the API reflect this instead of letting the users being in a problematic "ignorance is bliss" situation? It is not much more compex anyway.

But yeah, that is just my opinion and how I would go about things. Fair enough if you pick the other approach. I was mostly just curious anyway.

[Laurent]

It's much simpler (to code and understand) to just have to choose a direction, rather than a pair of vectors that have to be linearly independent. Explaining what an "up" vector is, and what "linearly independent" involves, can be complicated for beginners. Explaining what the listener direction is, is really straight-forward to understand for everybody.

Of course I'll change my mind if one day I get complains about particular use cases that don't work because they need a listener direction on Y axis. But so far it has never been an issue.

[therocode]

Yep, I know what you are saying, but that is where we disagree simply put.

I don't think that newbie-friendliness is an excuse in this case. It is not much to understand really, and going through that learning of how orientations work seems imo more worth than hiding it for the sake of newbies.

IMO programming is a lot about learning and if you abandon a library because it forces you to learn things, then the newbie is at fault, not the library API.

Also this doesn't mean that I don't see the value of simple APIs. I am very much for simple APIs, but not purely for the sake of newbies.

But yeah, as I said, I was mostly curious and I am not trying to argue to make you change your mind. I would have done it differently sure, but this is your library, not mine.

[Tank]

I have to agree to therocode. Allowing undefined behavior without even documenting it should be avoided at all costs. Not only it's possible to have bugs, it might also lead to beginners not understanding why the hell their stuff is not working, even if they use SFML correctly.

Something as simple as "If you use (0, +x, 0) as direction it won't work" would at least be a workaround for the real problem of not explaining the user why there is the need for forward and up vectors.

Also I really wonder if SFML's only target audience is beginners? Because beginners won't be beginners forever, and not having the chance to do things right will probably make SFML being replaced by another library that's "better controllable".

Regarding this specific problem: What about providing default arguments/an overload to allow specifying an up vector?

Besides from that, therocode, I think this "request" will be one of those "won't fix"->"fixed" things, which is as follows:

• Feature request is suggested.
• It's declared as being "too complicated" or "out of SFML's scope".
• A couple of months later it'll be implemented anyway.

SCNR

[Laurent]

As I said, since so far (almost) nobody complained about the lack of control over the up vector, I don't see any reason to add it.

Of course the documentation will be improved

[eXpl0it3r]

As I said, since so far (almost) nobody complained about the lack of control over the up vector, I don't see any reason to add it.

Ever thought about that maybe nobody has been making something more advanced with SFML until now? Thus the fixed default was enough for all the simple games.
So is this really your way of arguing? Seeing such "logic" makes me rather sad to be honest.

[Tank]

As I said, since so far (almost) nobody complained about the lack of control over the up vector

therocode just did and gave a good reason.

I don't see any reason to add it.

"Undefined behavior" is a good reason in my opinion. What's the reason to ignore this? Please no "too complicated", there can be at least an overloaded function that allows eliminating the bug (that could be easily avoided for everybody). Or an assert. Or an exception. Anything, but please do not remain silent in case of a KNOWN error, which, in my eyes, feels negligent in terms of code safety.

[therocode]

Adding a settable up vector in the function with 0,1,0 as default value would probably be good enough. However _just_ mentioning that 0,1,0 as a value for the setDirection function is undefined behaviour is imo more confusion inducing than just explaining what the point of the up-vector is and then not hide it.

I can't even think how one would formulate it to make sense. The best I can think of would be "setDirection sets the direction of the listener blah blah. Due to internal details, the value 0,1,0 is undefined behaviour". That would make me think "uuhh why? and can i reliably use this function to orient my player?".

And the reason that it should not be fixed just because no one had complained about it seems like a weird approach to make a stable bug free library.

Furthermore, I really don't think that explaining the up-vector is complicated. I mean, most users who are newbies would not even change the listener orientation. They would make simple 2D games with the default listener. Someone who changes the listener orientation is someone making something more complicated, like a 3D camera or something, and if you do that and cannot understand an up-vector, you're going to have many more difficult issues to address.

I can't imagine why a newbie would want to change the orientation at all, honestly so i don't think the "too complicated for the newbies"-argument even applies for this part of the API.

[Nexus]

So is this really your way of arguing? Seeing such "logic" makes me rather sad to be honest.

From an design standpoint, it makes much more sense to start with a minimal API and extend it when the need comes, instead of providing a whole lot of things that might be useful some time in the future, but contribute to an confusing and cluttered API. This is not about this specific feature, rather in general.

"Undefined behavior" is a good reason in my opinion.

I agree that it's a good reason to add at least an error check (assert or alike) and a better documentation, and I'm sure Laurent is not against that. To implement a new feature I would say there need to be concrete use cases. I'm not saying there are none, but there have still not been any arguments in that direction.

So is anybody of you actually requring that feature, or is the main point of this discussion to criticize the way how feature requests are handled in SFML? I mean that's also a valid discussion, but then keep it separate from the audio up vector.

[eXpl0it3r]

From an design standpoint, it makes much more sense to start with a minimal API and extend it when the need comes, instead of providing a whole lot of things that might be useful some time in the future, but contribute to an confusing and cluttered API. This is not about this specific feature, rather in general.

I can fully agree with that, but that's not what's happening here. Some are making a push for changing something, thus making the API not really more complex, but instead of discussing the request at hand, the only counter argument is "nobody wanted it in the past". Personally I wouldn't even call that an argument - the past is the past, we're in the present now, so let's evaluate now and here. If that's the level of arguing we're going for here, then sorry that can only make me sad.

[Laurent]

Some are making a push for changing something

I don't see anybody here who needs this feature. Even the OP said it was just for curiosity.