incorrect documentation of Sound::SetRelativeToListener!

[wilbefast]

Hi there,

Been beating my head against this for some time and thought I'd share the solution now that I've found it.

The documentation says that the argument 'Relative' in "SetRelativeToListener(bool Relative)" should be "True to set the position relative, false to set it absolute". 'False' is the default value.

In fact it's the opposite. In other words, sounds are played with spatialisation by default, and it is turned off and not on by with "SetRelativeToListener(true)". I figured this out thanks to the example at the bottom of this page: Laurent never turns on spatialisation!

Bit counter-intuitive though - and the documentation definately needs to be changed or people are doing to be as confused as I has, and lose many hours (not to mention hair) trying to figure out the problem!

William

[Laurent]

Nothing's wrong, I think you just misunderstood the documentation.

Spacialization is disabled (well, not really but let's keep things simple) when the sound's position is relative to the listener. In other words, when you enable this option the sound follows the listener, so no matter where the listener is, the sound will always be heard the same way.

[wilbefast]

Maybe I've misunderstood what "spatialisation" is but, unless I'm very much mistaken, a sound is "relative" to the listener when it is played with a varying volume and balance depending on its position relative to the listener.

If we agree on the above, then you have to admit that the expression "SetRelativeToListener(false);" making a sound relative to the listener, and "SetRelativeToListener(true)" making it absolute, is a little misleading :?

[Rock_Hardbuns]

The sound is always relative (in relation) to the listener, or there wouldn't be a sound.
What you are discussing is whether the sound is fixed relative to the listener or dynamic relative to the listener.

 

[Laurent]

Maybe I've misunderstood what "spatialisation" is

In fact you misunderstand what "relative" is. It doesn't mean that the sound will be spacialized according to the listener, spacialization is always on, and it is always according to the listener. It simply defines if the 3 coordinates that you pass as the sound's position are an absolute position, or an offset relative to the listener's position.

An example:

Code: [Select]

sf::Sound sound;
sound.SetRelativeToListener(false); // absolute position

sound.SetPosition(5, 10, 2);
sf::Listener::SetPosition(-1, 2, 7);

// --> sound's position in the 3D scene is (5, 10, 2)

Code: [Select]

sf::Sound sound;
sound.SetRelativeToListener(true); // relative position

sound.SetPosition(5, 10, 2);
sf::Listener::SetPosition(-1, 2, 7);

// --> sound's position in the 3D scene is (4, 12, 9)

So the effect of using SetRelativeToListener(true) is that the sound will always be heard the same way, regardless of the position of the listener. In practice it is often used to disable spacialization.

It's similar to 2D rendering over a 3D scene: wherever the camera is looking at, the 2D stuff will always appear at the same position on screen.

[wilbefast]

Ooooooh  :shock:

I see. Well, then, best leave it as is. Thought maybe explain in the documentation what you just explain here  - or am I the only person who was confused by this  :?