Bug in the Audio Module with listeners?

[Tank]

This is called 2D, and is the main target of SFML

What about this then?

void setOrientation( sf::Vector2f position );

It's for 2D only (so SFML's scope) and does simply not allow to specify wrong values. If you want to allow 3D spartialisation, then I'd still suggest to force setting the compound of forward and up vectors, like:

void setOrientation( sf::Vector3f forwardVector, sf::Vector3f upVector );

Edit: This is an overload of course!

And, of course, the getters:

sf::Vector3f getForwardVector() const;
sf::Vector3f getUpVector() const;

Personally I would still use a compound data type, but I guess that's out of question already, because you've decided not to use such.

I'm also aware that you will for sure disagree on the fact that there are different setters and getters, i.e. setOrientation() vs. getForwardVector()/getUpVector(). That's why setOrientation() might be renamed to something like orientTo(), making it clear that this is an operation and not setting a property.

[therocode]

I still think that having an Orientation property should be considered. Even the OpenAL API treats it as a single property, which makes sense since that is how it was meant to be used. So if SFLM decides to _not_ treat it like a property there should be a good reason for separating it imo.

I also had a new idea on how the API could be which is quite different to what has been proposed. My idea is based on the fact that SFML seems to want to have a simple/consistent 2D API but also have 3D spatialisation capability, so why try to come with a weird compromise API instead of actually treating them differently? I got the idea from tank's void setOrientation( sf::Vector2f position ); overload.

What is actually needed for the listener on a 2D scene? Not much. Only positioning (i.e. walking around with the player) and rotating (i.e. the player flips upside down with the whole view). Positioning can be set with a vec2 overloaded setPosition and rotation only sets the angle of the upvector. the at-vector is always looking straight at the scene. This causes proper audio positioning in _all_ cases and there are no cases with undefined behaviour. The functions could be:

void setPosition(sf::Vector2f position);
void set2DRotation(float angle); //this internally sets the at-vector to 0,0,-1 and angles the upvector accordingly

Then for 3D users, there is simply another overload of the setPosition function with a 3D vector, and then a setOrientation(at, up) to set a standard 3D orientation and this one can have an assert for linear dependency. Then for the 3D case, the users get the expected functionality and have full control over the vectors. This group of users will also not be confused by 2 vectors since they are making a 3D application. The orientation function of course mentions which at/up values are forbidden. In other words:

void setPosition(sf::Vector3f position);
void set3DOrientation(sf::Vector3f at, sf::Vetor3f up);

Now there are no weird half-way inbetween functions and the 2D user can use the simple functions and be happy with a safe easy API whilst the 3D users get the expected functionality.

What about backwards compatibility?
Well, that is possible if SFML accepts deprecation. If it does, then the current Listener:: functions can all become deprecated and the new ones can be under Listener2D:: and Listener3D:: which even further emphasises the idea that there are two different ways to go about audio in SFML: 2D and 3D. Which would ease confusion even more, and this would mean that the fix would be fully backwards compatible and SFML could get this issue fixed pretty soon.

[Tank]

therocode, what about the getters?

[therocode]

Ah right. Not sure.  Possibly:

Vector2f getPosition() //in Listener2D::
float getRotation() //in Listener2D::
Vector3f getPosition() //in Listener3D::
Vector3f getAtVector() //in Listener3D::
Vector3f getUpVector() //in Listener3D::

And if that is too inconsistent, having 2 getters for one setter, I would again propose having a struct Orientation for the 3D case, leaving the 2D case as proposed.

[Nexus]

Using a listener for 2D space is not as simple as setting it to a position in the z=0 plane. You need 3D spatialization even for 2D games. See this article for more information.

I don't like having two classes if one does its job perfectly without a bloated interface or too many responsibilities, it only complicates the API. Furthermore, it introduces issues because there is only a single global listener.

SFML should provide a simple API that provides enough functionality for complex scenarios, and this works well with the new API. Users that need specific features (such as a simplified 2D sound spatializer front-end) can write their own abstractions on top of SFML. It might even be a candidate for a future version of Thor.

[therocode]

Using a listener for 2D space is not as simple as setting it to a position in the z=0 plane. You need 3D spatialization even for 2D games. See this article for more information.

The article only mentions that an additional parameter depth is needed. He always orients the listener to look right at the scene with the at vector being (0,0,1) so real orientation is not needed. However it would indeed be good to in that case add a depth parameter which imo would still make sense for the API.

I don't like having two classes if one does its job perfectly without a bloated interface or too many responsibilities, it only complicates the API. Furthermore, it introduces issues because there is only a single global listener.

Sure if it does its job perfectly without a bloated interface but it doesn't right now. The listener is broken due to the issue this thread is about, and IMO your suggested API which tries to mix the 3D and 2D case by using 3D input but still focussing on 2D-friendliness is not the way to go to have a clean design.

True with issues with a global listener but that is another issue in itself. I would personally scrap the global listener (and a lot of other global things in SFML like the problematic global rendering context) and make a listener class that can be set to be active, but this would need a lot of rework in many parts of the API/style of SFML. This won't of course happen.

This is also why I find it hard to partake in a discussion about an API with you guys, because many parts of SFML are designed with a "user friendly and simple" approach instead of approaches that I would take, so there are fundamental disagreements.

SFML should provide a simple API that provides enough functionality for complex scenarios, and this works well with the new API.

This is what imo my API proposal does as well.

Users that need specific features (such as a simplified 2D sound spatializer front-end) can write their own abstractions on top of SFML. It might even be a candidate for a future version of Thor.

So you are saying that it should _not_ have simplified 2D features now? I thought the whole deal with the standard 3D based API proposed before was that SFML focusses mainly on 2D and should hence aim to make it simple for 2D users?

But anyway, I am getting tired of discussing this and I don't think I can contribute to the discussion anyway due to aforementioned disagreements in how to design an API. Best of luck in fixing!

[Tank]

Using a listener for 2D space is not as simple as setting it to a position in the z=0 plane. You need 3D spatialization even for 2D games. See this article for more information.

Just like it's not as simple as hardcoding the up vector to {0, 1, 0}. Are you seriously linking to an article that states the following as a requirement in order to understand what's being taught?

Have basic algebra notions (3D, what a vector is, right hand rule...).

And that also explains the forward and up vectors? May I remind you that it's what you described as being "too complicated for newbies" in the first place?

I don't like having two classes if one does its job perfectly without a bloated interface or too many responsibilities, it only complicates the API. Furthermore, it introduces issues because there is only a single global listener.

I kinda agree that the API would be bloated in that case, because one listener can easily handle both the "easy" and "complex" cases. The single global listener (just like the global OGL context), while that's another topic, is an issue in itself however. Maybe I'll open a thread for discussing that at some time, not sure though as I don't expect it to turn out in any productive way.

SFML should provide a simple API that provides enough functionality for complex scenarios, and this works well with the new API.

It still allows undefined behavior and doesn't make clear that you have to call two functions in order to make 3D spatialization work properly (documenting it is all good, but in this case we indeed have the option to solve this issue in code).

Users that need specific features (such as a simplified 2D sound spatializer front-end) can write their own abstractions on top of SFML. It might even be a candidate for a future version of Thor.

I'm really confused... Aren't those "specific 2D features" exactly what SFML has been doing until, well, now? You even argued that you don't want an OpenAL wrapper, but something that fits into SFML's 2D scope. At least that's what Laurent said. And now you argue the exact other way around, i.e. that all complex scenarios are possible, and that 2D stuff can be added on top..?

Spatialisation that's limited to 2 axes is probably what "most SFML games" need. They don't have depth -- hence 2D.. I'm just saying this because it's what has driven me to provide a Vector2f overload.

Could you please exactly state what you want to achieve now? Your opinions have changed during this thread massively, and I'm unsure what you are after right now.

[Nexus]

So you are saying that it should _not_ have simplified 2D features now? I thought the whole deal with the standard 3D based API proposed before was that SFML focusses mainly on 2D and should hence aim to make it simple for 2D users?

It should not have an full-featured 2D listener as described in the article I linked, with all the distance and depth stuff in the background. It should only provide a minimal API that allows to achieve sound spatialization -- 2D and 3D.

Are you seriously linking to an article that states the following as a requirement in order to understand what's being taught?

Have basic algebra notions (3D, what a vector is, right hand rule...).

And that also explains the forward and up vectors? May I remind you that it's what you described as being "too complicated for newbies" in the first place?

The article explains why a z=0 listener is a bad idea and why a Listener2D won't work as easily as one might imagine. It was an answer to therocode's suggestion and has nothing to do with "too complicated", because it's not what SFML will provide in any way. Please don't take sentences out of context; furthermore I wasn't the one who wrote it would be too complicated for beginners.

I kinda agree that the API would be bloated in that case, because one listener can easily handle both the "easy" and "complex" cases.

Just like when the up vector is implemented -- you can achieve everything, both easy and complex cases.

And it would be nice if we could avoid that aggressive tone. I always get the feeling that the motif is not progress in SFML, but showing as much things as possible that have been done wrong -- especially since nobody was directly concerned by the original problem, but suddenly everyone used it as an opportunity to criticize SFML in general. I really like discussing about API design, but please keep it objective and focused (flaws in other parts of SFML don't belong into this thread, nor do they make arguments any better). Thank you

[Tank]

It should not have an full-featured 2D listener as described in the article I linked, with all the distance and depth stuff in the background. It should only provide a minimal API that allows to achieve sound spatialization -- 2D and 3D.

Good, then we have the same goal in mind. The only difference then is your 2 functions compared to one function.

furthermore I wasn't the one who wrote it would be too complicated for beginners.

True.

Just like when the up vector is implemented -- you can achieve everything, both easy and complex cases.

That's what I suggested in my first post(!) in this thread. My only additional request is a function that makes it clear that the orientation is built from two vectors, not one, and that error checking is done. (I proposed several approaches: two arguments, a compound, default argument.)

And it would be nice if we could avoid that aggressive tone. I always get the feeling that the motif is not progress in SFML, but showing as much things as possible that have been done wrong -- especially since nobody was directly concerned by the original problem, but suddenly everyone used it as an opportunity to criticize SFML in general. I really like discussing about API design, but please keep it objective and focused (flaws in other parts of SFML don't belong into this thread, nor do they make arguments any better). Thank you

Sorry if I sound aggressive -- I can assure you I am not, I'm sitting in a nice chair, in front of a screen while the sun is touching my face -- I'm relaxed. But I don't see why I should step away from my opinion or principles when I want to bring them into the solution? You do that as well, and even some sentences of you sound sarcastic as well, but that's alright.

The motif for me has always been to get this bug out of the library and replace it with the best solution. When I recognize the well-known SFML-ish reaction to this, then yes, I will criticize exactly that. There have been similar discussions in the past years. Discussions about requests that have been rejected in the first place but implemented in one of the later versions. So I would find it nice if, before rejecting things, either by saying "too complicated", "out of scope" or "nobody complained so far", you could consider a change.

Especially in requests as this one, where a bug has been found. I really can't and will never accept the fact that a bug is kept just because nobody has complained so far, and that a bug itself is not a valid reason to change an API. I'm so much against that, does that explain my attitude? I'm too pragmatic to ignore that.

Feel free to ignore my posts however, if you think they don't help with the discussion or are not productive at all. It's okay. But I won't stop to use "uncomfortable" arguments if I think they fit. None of them are meant to be personal.

[Nexus]

Okay, then it's fine

I'm not uncomfortable with the arguments, as stated earlier I do see the advantage of a compound (namely that it forces the user to think about up vector as well when setting the direction), but there are also other considerations (expressivity of code for example). I'm sure that if we implemented a different API there would be another user complaining
It's always a trade-off between different designs.

Concerning the "out of scope" or "too complicated" reaction: I can't say too much about this since I haven't been in charge of SFML for a long time, but there are indeed many features that are completely off (the popular ones being a 3D engine, GUI library and filesystem). On the other hand, there are also a lot of feature requests that actually improve the library, and if you look at GitHub, you'll see that I'm currently negotiating several pull requests. The "too complicated" argument is not always a definitive and absolute statement; as you noticed, some features were still implemented later. I think this has to do with two points: ensuring that there is an actual need and convincing arguments before simply accepting a feature, in order to ensure a high-quality API; as well as setting its priority with respect to other open issues -- there are tons of bug reports and feature requests pending, but often people who request a new feature only have their specific use case in mind. However I agree that especially for bugs we can't just say "it's out of scope" and not consider a fix at all, but here there will be a change. Apart from that, in my opinion, the listener up vector rather a feature than a bugfix. The problem of linearly dependent vectors exists in the past and future, and it can be avoided in both. The difference is that in the future, the user has more freedom to set a coordinate system.

...this is at least my interpretation of the situation.

[wintertime]

The article explains why a z=0 listener is a bad idea and why a Listener2D won't work as easily as one might imagine. It was an answer to therocode's suggestion and has nothing to do with "too complicated", because it's not what SFML will provide in any way. Please don't take sentences out of context; furthermore I wasn't the one who wrote it would be too complicated for beginners.

I would think when implementing a 2D listener one would automatically map the 2D vector to x and z, if the up vector is still hardcoded to (x,y,z)=(0,1,0), to make it possible to position it anywhere on the y=0 plane.


Btw., if you dont want to change the interface atm, I think fixing up weird inputs in a way similar to this might be a good idea:

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

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

[eXpl0it3r]

So for all the people saying "nobody complained" and "the main purpose is 2D" here you go:

I can't be the only one being annoyed, am I? I'm talking about the Listener up vector in #sfml always being (0, 1, 0). #programming #gamedev

For the next version I'll be dropping SFML audio, and writing my own sound lib again. No real 3D sound is simply a no-go.
...
On the other hand, it offers so much utility. Argh I don't know what to do.
...
I think I'll just make a patch and hope he'll accept it. That's much easier than writing my own sound stuff.

And I can kind of agree with this:

I really have to say that I don't like the maintainer's attitude about this. It was requested multiple times but he refused to add it.

Let's see what happens, because I doubt he will have the possibility to just wait for SFML 3 to come around... in 2 years or so...

[Tank]

Well there's still the chance of pulling out a minor version. Git branching is really easy and useful for exactly such things.

[therocode]

That tweet.

Given the issue in the audio module I am not surprised at all. And I also agree that this shouldn't have been an issue in the first place. But oh well.

[Laurent]

I think you can stop bashing SFML and myself. A new feature has been scheduled.