Exposed up vector in sf::Listener API

Closes #545

include/SFML/Audio/Listener.hpp

@@ -104,46 +104,96 @@ public :
     static Vector3f getPosition();
 
     ////////////////////////////////////////////////////////////
-    /// \brief Set the orientation of the listener in the scene
+    /// \brief Set the forward vector of the listener in the scene
     ///
-    /// The orientation defines the 3D axes of the listener
+    /// The direction (also called "at vector") is the vector
-    /// (left, up, front) in the scene. The orientation vector
+    /// pointing forward from the listener's perspective. Together
-    /// doesn't have to be normalized.
+    /// with the up vector, it defines the 3D orientation of the
-    /// The default listener's orientation is (0, 0, -1).
+    /// listener in the scene. The direction vector doesn't
+    /// have to be normalized.
+    /// The default listener's direction is (0, 0, -1).
     ///
-    /// \param x X coordinate of the listener's orientation
+    /// \param x X coordinate of the listener's direction
-    /// \param y Y coordinate of the listener's orientation
+    /// \param y Y coordinate of the listener's direction
-    /// \param z Z coordinate of the listener's orientation
+    /// \param z Z coordinate of the listener's direction
     ///
-    /// \see getDirection, setPosition
+    /// \see getDirection, setUpVector, setPosition
     ///
     ////////////////////////////////////////////////////////////
     static void setDirection(float x, float y, float z);
 
     ////////////////////////////////////////////////////////////
-    /// \brief Set the orientation of the listener in the scene
+    /// \brief Set the forward vector of the listener in the scene
     ///
-    /// The orientation defines the 3D axes of the listener
+    /// The direction (also called "at vector") is the vector
-    /// (left, up, front) in the scene. The orientation vector
+    /// pointing forward from the listener's perspective. Together
-    /// doesn't have to be normalized.
+    /// with the up vector, it defines the 3D orientation of the
-    /// The default listener's orientation is (0, 0, -1).
+    /// listener in the scene. The direction vector doesn't
+    /// have to be normalized.
+    /// The default listener's direction is (0, 0, -1).
     ///
-    /// \param direction New listener's orientation
+    /// \param direction New listener's direction
     ///
-    /// \see getDirection, setPosition
+    /// \see getDirection, setUpVector, setPosition
     ///
     ////////////////////////////////////////////////////////////
     static void setDirection(const Vector3f& direction);
 
     ////////////////////////////////////////////////////////////
-    /// \brief Get the current orientation of the listener in the scene
+    /// \brief Get the current forward vector of the listener in the scene
     ///
-    /// \return Listener's orientation
+    /// \return Listener's forward vector (not normalized)
     ///
     /// \see setDirection
     ///
     ////////////////////////////////////////////////////////////
     static Vector3f getDirection();
+
+    ////////////////////////////////////////////////////////////
+    /// \brief Set the upward vector of the listener in the scene
+    ///
+    /// The up vector is the vector that points upward from the
+    /// listener's perspective. Together with the direction, it
+    /// defines the 3D orientation of the listener in the scene.
+    /// The up vector doesn't have to be normalized.
+    /// The default listener's up vector is (0, 1, 0). It is usually
+    /// not necessary to change it, especially in 2D scenarios.
+    ///
+    /// \param x X coordinate of the listener's up vector
+    /// \param y Y coordinate of the listener's up vector
+    /// \param z Z coordinate of the listener's up vector
+    ///
+    /// \see getUpVector, setDirection, setPosition
+    ///
+    ////////////////////////////////////////////////////////////
+    static void setUpVector(float x, float y, float z);
+
+    ////////////////////////////////////////////////////////////
+    /// \brief Set the upward vector of the listener in the scene
+    ///
+    /// The up vector is the vector that points upward from the
+    /// listener's perspective. Together with the direction, it
+    /// defines the 3D orientation of the listener in the scene.
+    /// The up vector doesn't have to be normalized.
+    /// The default listener's up vector is (0, 1, 0). It is usually
+    /// not necessary to change it, especially in 2D scenarios.
+    ///
+    /// \param upVector New listener's up vector
+    ///
+    /// \see getUpVector, setDirection, setPosition
+    ///
+    ////////////////////////////////////////////////////////////
+    static void setUpVector(const Vector3f& upVector);
+
+    ////////////////////////////////////////////////////////////
+    /// \brief Get the current upward vector of the listener in the scene
+    ///
+    /// \return Listener's upward vector (not normalized)
+    ///
+    /// \see setUpVector
+    ///
+    ////////////////////////////////////////////////////////////
+    static Vector3f getUpVector();
 };
 
 } // namespace sf
@@ -163,8 +213,8 @@ public :
 /// same position, orientation, etc.). 
 ///
 /// sf::Listener is a simple interface, which allows to setup the
-/// listener in the 3D audio environment (position and direction),
+/// listener in the 3D audio environment (position, direction and
-/// and to adjust the global volume.
+/// up vector), and to adjust the global volume.
 ///
 /// Because the listener is unique in the scene, sf::Listener only
 /// contains static functions and doesn't have to be instantiated.

src/SFML/Audio/Listener.cpp

@@ -32,8 +32,9 @@
 namespace
 {
     float        listenerVolume = 100.f;
-    sf::Vector3f listenerPosition(0.f, 0.f, 0.f);
+    sf::Vector3f listenerPosition (0.f, 0.f, 0.f);
     sf::Vector3f listenerDirection(0.f, 0.f, -1.f);
+    sf::Vector3f listenerUpVector (0.f, 1.f, 0.f);
 }
 
 
@@ -100,7 +101,7 @@ void Listener::setDirection(const Vector3f& direction)
     {
         priv::ensureALInit();
 
-        float orientation[] = {direction.x, direction.y, direction.z, 0.f, 1.f, 0.f};
+        float orientation[] = {direction.x, direction.y, direction.z, listenerUpVector.x, listenerUpVector.y, listenerUpVector.z};
         alCheck(alListenerfv(AL_ORIENTATION, orientation));
         listenerDirection = direction;
     }
@@ -113,4 +114,32 @@ Vector3f Listener::getDirection()
     return listenerDirection;
 }
 
+
+////////////////////////////////////////////////////////////
+void Listener::setUpVector(float x, float y, float z)
+{
+    setUpVector(sf::Vector3f(x, y, z));
+}
+
+
+////////////////////////////////////////////////////////////
+void Listener::setUpVector(const Vector3f& upVector)
+{
+    if (upVector != listenerUpVector)
+    {
+        priv::ensureALInit();
+
+        float orientation[] = {listenerDirection.x, listenerDirection.y, listenerDirection.z, upVector.x, upVector.y, upVector.z};
+        alCheck(alListenerfv(AL_ORIENTATION, orientation));
+        listenerUpVector = upVector;
+    }
+}
+
+
+////////////////////////////////////////////////////////////
+Vector3f Listener::getUpVector()
+{
+    return listenerUpVector;
+}
+
 } // namespace sf