Merge branch 'master' into compatibility

doc/best-practices.dox

@@ -1,6 +1,9 @@
-/** @page best-practices Best practices in OpenGL
+namespace Magnum {
+/** @page best-practices Best practices and platform-specific information
 
-@brief Platform-specific and general performance advices
+@brief Performance advices and solutions for platform-specific issues
+
+@tableofcontents
 
 Here is collection of carefully selected links to official guidelines and
 other articles with valuable information to help developers create better
@@ -8,8 +11,32 @@ applications. Feel free to add one, if it contains new unique information.
 
 @section best-practices-platform Platform-specific
 
-- Mac OS - [Best Practices for Working with Vertex Data](https://developer.apple.com/library/mac/#documentation/graphicsimaging/Conceptual/OpenGL-MacProgGuide/opengl_vertexdata/opengl_vertexdata.html), [Best Practices for Working with Texture Data](https://developer.apple.com/library/mac/#documentation/graphicsimaging/Conceptual/OpenGL-MacProgGuide/opengl_texturedata/opengl_texturedata.html)
+Some platforms need special care, see their respective sections for more
-- iOS - [Best Practices for Working with Vertex Data](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/TechniquesforWorkingwithVertexData/TechniquesforWorkingwithVertexData.html), [Best Practices for Working with Texture Data](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/TechniquesForWorkingWithTextureData/TechniquesForWorkingWithTextureData.html), [Best Practices for Shaders](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/BestPracticesforShaders/BestPracticesforShaders.html#//apple_ref/doc/uid/TP40008793-CH7-SW3)
+information.
-- Google Chrome Native Client - [Best practices for 3D graphics](https://developers.google.com/native-client/beta/devguide/coding/3D-graphics#best-practices)
+
+@subsection best-practices-mac Mac OS
+
+- [Best Practices for Working with Vertex Data](https://developer.apple.com/library/mac/#documentation/graphicsimaging/Conceptual/OpenGL-MacProgGuide/opengl_vertexdata/opengl_vertexdata.html)
+- [Best Practices for Working with Texture Data](https://developer.apple.com/library/mac/#documentation/graphicsimaging/Conceptual/OpenGL-MacProgGuide/opengl_texturedata/opengl_texturedata.html)
+
+@subsection best-practices-ios iOS
+
+- [Best Practices for Working with Vertex Data](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/TechniquesforWorkingwithVertexData/TechniquesforWorkingwithVertexData.html)
+- [Best Practices for Working with Texture Data](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/TechniquesForWorkingWithTextureData/TechniquesForWorkingWithTextureData.html)
+- [Best Practices for Shaders](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/BestPracticesforShaders/BestPracticesforShaders.html#//apple_ref/doc/uid/TP40008793-CH7-SW3)
+
+@subsection best-practices-nacl Google Chrome Native Client
+
+- [Best practices for 3D graphics](https://developers.google.com/native-client/beta/devguide/coding/3D-graphics#best-practices)
+
+@subsubsection best-practices-nacl-buffer-types Native Client requires unique buffer binding
+
+As noted in the above link, buffers in NaCl implementation need to be bound
+only to one unique target, i.e., Buffer bound to @ref Buffer::Target "Target::Array"
+cannot be later rebound to @ref Buffer::Target "Target::Element". However,
+%Magnum by default uses any sufficient target when binding the buffer
+internally (e.g. for setting data or copying). To avoid this, set target hint
+to desired target, either in constructor or using Buffer::setTargetHint().
 
 */
+}

doc/coding-style.dox

@@ -29,6 +29,15 @@ When writing wrappers for OpenGL functions and defines, try to match the
 original name as closely as possible, although expanding abbrevations (and
 removing redundant prefixes) is encouraged.
 
+@subsubsection cpp-forward-declarations Forward declarations and forward declaration headers
+
+Use forward declarations in headers as much as possible, as it can
+significantly reduce time of incremental compilation. When an namespace has
+classes which are commonly forward-declared, consider making a forward
+declaration header - it should have the same name as the namespace itself and
+contain foward declarations for all classes, enums and copies of all
+meaningful typedefs. See SceneGraph/SceneGraph.h for an example.
+
 @section documentation Doxygen documentation
 
 @subsection documentation-commands Special documentation commands

doc/compilation-speedup.dox

@@ -20,6 +20,7 @@ typedefs etc. In this case a header with forward declarations is usually
 available, each namespace has its own:
 
  - Magnum.h
+ - Physics/Physics.h
  - SceneGraph/SceneGraph.h
  - Shaders/Shaders.h
 

src/Buffer.h

@@ -305,11 +305,13 @@ class MAGNUM_EXPORT Buffer {
 
         /**
          * @brief Constructor
+         * @param targetHint    Target hint, see setTargetHint() for more
+         *      information
          *
          * Generates new OpenGL buffer.
          * @see @fn_gl{GenBuffers}
          */
-        inline Buffer(): _targetHint(Target::Array) {
+        inline Buffer(Target targetHint = Target::Array): _targetHint(targetHint) {
             glGenBuffers(1, &_id);
         }
 

src/Physics/CMakeLists.txt

@@ -25,10 +25,11 @@ set(MagnumPhysics_HEADERS
     DebugDrawResourceManager.h
     Line.h
     LineSegment.h
-    Plane.h
-    Point.h
     ObjectShape.h
     ObjectShapeGroup.h
+    Physics.h
+    Plane.h
+    Point.h
     ShapeGroup.h
     Sphere.h
 

src/Physics/Capsule.h

@@ -21,14 +21,12 @@
 
 #include "Math/Vector3.h"
 #include "AbstractShape.h"
+#include "Physics.h"
 
 #include "magnumCompatibility.h"
 
 namespace Magnum { namespace Physics {
 
-template<std::uint8_t> class Point;
-template<std::uint8_t> class Sphere;
-
 /**
 @brief %Capsule defined by cylinder start and end point and radius
 

src/Physics/DebugDrawResourceManager.h

@@ -28,15 +28,12 @@
 #include "ResourceManager.h"
 
 #include "SceneGraph/SceneGraph.h"
+#include "Physics.h"
 
 #include "magnumPhysicsVisibility.h"
 
 namespace Magnum {
 
-class AbstractShaderProgram;
-class Buffer;
-class Mesh;
-
 #ifndef DOXYGEN_GENERATING_OUTPUT
 namespace Physics { namespace Implementation {
     struct Options {
@@ -50,14 +47,6 @@ extern template ResourceManager<AbstractShaderProgram, Buffer, Mesh, Physics::Im
 
 namespace Physics {
 
-template<std::uint8_t> class AbstractShape;
-typedef AbstractShape<2> AbstractShape2D;
-typedef AbstractShape<3> AbstractShape3D;
-
-template<std::uint8_t> class ObjectShape;
-typedef ObjectShape<2> ObjectShape2D;
-typedef ObjectShape<3> ObjectShape3D;
-
 /**
 @brief %Resource manager for physics debug draw
 

src/Physics/ObjectShape.h

@@ -26,9 +26,6 @@
 
 namespace Magnum { namespace Physics {
 
-template<std::uint8_t> class ObjectShapeGroup;
-template<std::uint8_t> class AbstractShape;
-
 /**
 @brief Object shape
 

src/Physics/ObjectShapeGroup.h

@@ -23,17 +23,15 @@
 #include <vector>
 
 #include "SceneGraph/FeatureGroup.h"
+#include "Physics.h"
 
 #include "magnumPhysicsVisibility.h"
 
 namespace Magnum { namespace Physics {
 
-template<std::uint8_t> class ObjectShape;
-
 /**
 @brief Group of object shapes
 
-
 @see ObjectShapeGroup2D, ObjectShapeGroup3D
 */
 template<std::uint8_t dimensions> class PHYSICS_EXPORT ObjectShapeGroup: public SceneGraph::FeatureGroup<dimensions, ObjectShape<dimensions>> {
@@ -84,4 +82,7 @@ typedef ObjectShapeGroup<3> ObjectShapeGroup3D;
 
 }}
 
+/* Make the definition complete */
+#include "ObjectShape.h"
+
 #endif

src/Physics/Physics.h

@@ -0,0 +1,76 @@
+#ifndef Magnum_Physics_Physics_h
+#define Magnum_Physics_Physics_h
+/*
+    Copyright © 2010, 2011, 2012 Vladimír Vondruš <mosra@centrum.cz>
+
+    This file is part of Magnum.
+
+    Magnum is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License version 3
+    only, as published by the Free Software Foundation.
+
+    Magnum is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+    GNU Lesser General Public License version 3 for more details.
+*/
+
+#include <cstdint>
+
+/** @file
+ * @brief Forward declarations for Magnum::Physics namespace
+ */
+
+namespace Magnum { namespace Physics {
+
+template<std::uint8_t> class AbstractShape;
+typedef AbstractShape<2> AbstractShape2D;
+typedef AbstractShape<3> AbstractShape3D;
+
+template<std::uint8_t> class AxisAlignedBox;
+typedef AxisAlignedBox<2> AxisAlignedBox2D;
+typedef AxisAlignedBox<3> AxisAlignedBox3D;
+
+template<std::uint8_t> class Box;
+typedef Box<2> Box2D;
+typedef Box<3> Box3D;
+
+template<std::uint8_t> class Capsule;
+typedef Capsule<2> Capsule2D;
+typedef Capsule<3> Capsule3D;
+
+class DebugDrawResourceManager;
+
+template<std::uint8_t> class Line;
+typedef Line<2> Line2D;
+typedef Line<3> Line3D;
+
+template<std::uint8_t> class LineSegment;
+typedef LineSegment<2> LineSegment2D;
+typedef LineSegment<3> LineSegment3D;
+
+template<std::uint8_t> class ObjectShape;
+typedef ObjectShape<2> ObjectShape2D;
+typedef ObjectShape<3> ObjectShape3D;
+
+template<std::uint8_t> class ObjectShapeGroup;
+typedef ObjectShapeGroup<2> ObjectShapeGroup2D;
+typedef ObjectShapeGroup<3> ObjectShapeGroup3D;
+
+class Plane;
+
+template<std::uint8_t> class Point;
+typedef Point<2> Point2D;
+typedef Point<3> Point3D;
+
+template<std::uint8_t> class ShapeGroup;
+typedef ShapeGroup<2> ShapeGroup2D;
+typedef ShapeGroup<3> ShapeGroup3D;
+
+template<std::uint8_t> class Sphere;
+typedef Sphere<2> Sphere2D;
+typedef Sphere<3> Sphere3D;
+
+}}
+
+#endif

src/Physics/Plane.cpp

@@ -28,7 +28,7 @@ using namespace Magnum::Math::Geometry;
 namespace Magnum { namespace Physics {
 
 void Plane::applyTransformation(const Matrix4& transformation) {
-    _transformedPosition = (transformation*Point3D(_position)).xyz();
+    _transformedPosition = (transformation*Magnum::Point3D(_position)).xyz();
     _transformedNormal = transformation.rotation()*_normal;
 }
 

src/Physics/Plane.h

@@ -21,16 +21,12 @@
 
 #include "Math/Vector3.h"
 #include "AbstractShape.h"
+#include "Physics.h"
 
 #include "magnumCompatibility.h"
 
 namespace Magnum { namespace Physics {
 
-template<std::uint8_t> class Line;
-typedef Line<3> Line3D;
-template<std::uint8_t> class LineSegment;
-typedef LineSegment<3> LineSegment3D;
-
 /** @brief Infinite plane, defined by position and normal (3D only) */
 class PHYSICS_EXPORT Plane: public AbstractShape<3> {
     public:

src/Physics/Sphere.h

@@ -21,15 +21,12 @@
 
 #include "Math/Vector3.h"
 #include "AbstractShape.h"
+#include "Physics.h"
 
 #include "magnumCompatibility.h"
 
 namespace Magnum { namespace Physics {
 
-template<std::uint8_t> class Line;
-template<std::uint8_t> class LineSegment;
-template<std::uint8_t> class Point;
-
 /**
 @brief %Sphere defined by position and radius
 

src/Platform/Sdl2Application.cpp

@@ -117,7 +117,7 @@ int Sdl2Application::exec() {
                     } break;
 
                 case SDL_MOUSEMOTION: {
-                    MouseMoveEvent e({event.motion.x, event.motion.y});
+                    MouseMoveEvent e({event.motion.x, event.motion.y}, {event.motion.xrel, event.motion.yrel});
                     mouseMoveEvent(e);
                     break;
                 }
@@ -135,4 +135,16 @@ int Sdl2Application::exec() {
     return 0;
 }
 
+Sdl2Application::InputEvent::Modifiers Sdl2Application::MouseEvent::modifiers() {
+    if(modifiersLoaded) return _modifiers;
+    modifiersLoaded = true;
+    return _modifiers = static_cast<Modifier>(SDL_GetModState());
+}
+
+Sdl2Application::InputEvent::Modifiers Sdl2Application::MouseMoveEvent::modifiers() {
+    if(modifiersLoaded) return _modifiers;
+    modifiersLoaded = true;
+    return _modifiers = static_cast<Modifier>(SDL_GetModState());
+}
+
 }}

src/Platform/Sdl2Application.h

@@ -122,6 +122,22 @@ class Sdl2Application {
 
         /** @{ @name Mouse handling */
 
+        /** @brief Whether mouse is locked */
+        inline bool isMouseLocked() const {
+            return SDL_GetRelativeMouseMode();
+        }
+
+        /**
+         * @brief Enable or disable mouse locking
+         *
+         * When mouse is locked, the cursor is hidden and only
+         * MouseMoveEvent::relativePosition() is changing, absolute position
+         * stays the same.
+         */
+        inline void setMouseLocked(bool enabled) {
+            SDL_SetRelativeMouseMode(enabled ? SDL_TRUE : SDL_FALSE);
+        }
+
         /**
          * @brief Mouse press event
          *
@@ -343,11 +359,20 @@ class Sdl2Application::MouseEvent: public Sdl2Application::InputEvent {
         /** @brief Position */
         inline Math::Vector2<int> position() const { return _position; }
 
+        /**
+         * @brief Modifiers
+         *
+         * Lazily populated on first request.
+         */
+        Modifiers modifiers();
+
     private:
-        inline MouseEvent(Button button, const Math::Vector2<int>& position): _button(button), _position(position) {}
+        inline MouseEvent(Button button, const Math::Vector2<int>& position): _button(button), _position(position), modifiersLoaded(false) {}
 
         const Button _button;
         const Math::Vector2<int> _position;
+        bool modifiersLoaded;
+        Modifiers _modifiers;
 };
 
 /**
@@ -362,10 +387,26 @@ class Sdl2Application::MouseMoveEvent: public Sdl2Application::InputEvent {
         /** @brief Position */
         inline Math::Vector2<int> position() const { return _position; }
 
+        /**
+         * @brief Relative position
+         *
+         * Position relative to previous event
+         */
+        inline Math::Vector2<int> relativePosition() const { return _relativePosition; }
+
+        /**
+         * @brief Modifiers
+         *
+         * Lazily populated on first request.
+         */
+        Modifiers modifiers();
+
     private:
-        inline MouseMoveEvent(const Math::Vector2<int>& position): _position(position) {}
+        inline MouseMoveEvent(const Math::Vector2<int>& position, const Math::Vector2<int>& relativePosition): _position(position), _relativePosition(relativePosition), modifiersLoaded(false) {}
 
-        const Math::Vector2<int> _position;
+        const Math::Vector2<int> _position, _relativePosition;
+        bool modifiersLoaded;
+        Modifiers _modifiers;
 };
 
 /** @hideinitializer

src/SceneGraph/AbstractCamera.h

@@ -32,7 +32,7 @@ namespace Magnum { namespace SceneGraph {
 
 @see AbstractCamera::setAspectRatioPolicy()
 */
-enum class AspectRatioPolicy {
+enum class AspectRatioPolicy: std::uint8_t {
     NotPreserved,   /**< Don't preserve aspect ratio (default) */
     Extend,         /**< Extend on larger side of view */
     Clip            /**< Clip on smaller side of view */

src/SceneGraph/AbstractObject.h

@@ -19,6 +19,7 @@
  * @brief Class Magnum::SceneGraph::AbstractObject, alias Magnum::SceneGraph::AbstractObject2D, Magnum::SceneGraph::AbstractObject3D
  */
 
+#include <vector>
 #include <Containers/LinkedList.h>
 
 #include "DimensionTraits.h"

src/SceneGraph/SceneGraph.h

@@ -25,6 +25,8 @@
 
 namespace Magnum { namespace SceneGraph {
 
+enum class AspectRatioPolicy: std::uint8_t;
+
 template<std::uint8_t dimensions, class T = GLfloat> class AbstractCamera;
 #ifndef MAGNUM_GCC46_COMPATIBILITY
 template<class T = GLfloat> using AbstractCamera2D = AbstractCamera<2, T>;
@@ -49,6 +51,8 @@ template<class T = GLfloat> using AbstractObject2D = AbstractObject<2, T>;
 template<class T = GLfloat> using AbstractObject3D = AbstractObject<3, T>;
 #endif
 
+enum class TransformationType: std::uint8_t;
+
 template<std::uint8_t dimensions, class T = GLfloat> class AbstractTransformation;
 #ifndef MAGNUM_GCC46_COMPATIBILITY
 template<class T = GLfloat> using AbstractTransformation2D = AbstractTransformation<2, T>;