Some new 3D utility classes: Vector3D, Matrix3D, Quaternion, Draggable3DOrientation.

extras/JuceDemo/Source/demos/OpenGLDemo.cpp

@@ -48,12 +48,23 @@ public:
         dynamicTextureImage = Image (Image::ARGB, 128, 128, true, OpenGLImageType());
     }
 
+    void mouseDown (const MouseEvent& e)
+    {
+        draggableOrientation.mouseDown (e.getPosition());
+    }
+
     void mouseDrag (const MouseEvent& e)
     {
+        draggableOrientation.mouseDrag (e.getPosition());
         delta = e.getDistanceFromDragStartX() / 100.0f;
         repaint();
     }
 
+    void resized()
+    {
+        draggableOrientation.setViewport (getLocalBounds());
+    }
+    
     void renderOpenGL()
     {
         OpenGLHelpers::clear (Colours::darkgrey.withAlpha (1.0f));
@@ -73,7 +84,7 @@ public:
         OpenGLHelpers::setPerspective (45.0, getWidth() / (double) getHeight(), 0.1, 100.0);
 
         glTranslatef (0.0f, 0.0f, -5.0f);
-        glRotatef (rotation, 0.5f, 1.0f, 0.0f);
+        draggableOrientation.applyToOpenGLMatrix();
 
         // logoImage and dynamicTextureImage are actually OpenGL images, so we can use this utility function to
         // extract the frame buffer which is their backing store, and use it directly.
@@ -155,6 +166,7 @@ public:
 private:
     Image logoImage, dynamicTextureImage;
     float rotation, delta, textScrollPos;
+    Draggable3DOrientation draggableOrientation;
 
     // Functions to create a couple of images to use as textures..
     static Image createLogoImage()

modules/juce_opengl/juce_opengl.h

@@ -83,6 +83,12 @@ BEGIN_JUCE_NAMESPACE
 #include "opengl/juce_OpenGLRenderingTarget.h"
 
 // START_AUTOINCLUDE opengl
+#ifndef __JUCE_DRAGGABLE3DORIENTATION_JUCEHEADER__
+ #include "opengl/juce_Draggable3DOrientation.h"
+#endif
+#ifndef __JUCE_MATRIX3D_JUCEHEADER__
+ #include "opengl/juce_Matrix3D.h"
+#endif
 #ifndef __JUCE_OPENGLCOMPONENT_JUCEHEADER__
  #include "opengl/juce_OpenGLComponent.h"
 #endif
@@ -110,6 +116,12 @@ BEGIN_JUCE_NAMESPACE
 #ifndef __JUCE_OPENGLTEXTURE_JUCEHEADER__
  #include "opengl/juce_OpenGLTexture.h"
 #endif
+#ifndef __JUCE_QUATERNION_JUCEHEADER__
+ #include "opengl/juce_Quaternion.h"
+#endif
+#ifndef __JUCE_VECTOR3D_JUCEHEADER__
+ #include "opengl/juce_Vector3D.h"
+#endif
 // END_AUTOINCLUDE
 
 END_JUCE_NAMESPACE

modules/juce_opengl/opengl/juce_Draggable3DOrientation.h

@@ -0,0 +1,152 @@
+/*
+  ==============================================================================
+
+   This file is part of the JUCE library - "Jules' Utility Class Extensions"
+   Copyright 2004-11 by Raw Material Software Ltd.
+
+  ------------------------------------------------------------------------------
+
+   JUCE can be redistributed and/or modified under the terms of the GNU General
+   Public License (Version 2), as published by the Free Software Foundation.
+   A copy of the license is included in the JUCE distribution, or can be found
+   online at www.gnu.org/licenses.
+
+   JUCE 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 General Public License for more details.
+
+  ------------------------------------------------------------------------------
+
+   To release a closed-source product which uses JUCE, commercial licenses are
+   available: visit www.rawmaterialsoftware.com/juce for more information.
+
+  ==============================================================================
+*/
+
+#ifndef __JUCE_DRAGGABLE3DORIENTATION_JUCEHEADER__
+#define __JUCE_DRAGGABLE3DORIENTATION_JUCEHEADER__
+
+#include "juce_Quaternion.h"
+
+
+//==============================================================================
+/**
+    Stores a 3D orientation, which can be rotated by dragging with the mouse.
+*/
+class Draggable3DOrientation
+{
+public:
+    typedef Vector3D<GLfloat> VectorType;
+
+    /** Creates a Draggable3DOrientation, initially set up to be aligned along the X axis. */
+    Draggable3DOrientation (float objectRadius = 0.5f) noexcept
+        : radius (jmax (0.1f, objectRadius)),
+          quaternion (VectorType::xAxis(), 0)
+    {
+    }
+
+    /** Resets the orientation, specifying the axis to align it along. */
+    void reset (const VectorType& axis) noexcept
+    {
+        quaternion = QuaternionType (axis, 0);
+    }
+
+    /** Sets the viewport area within which mouse-drag positions will occur.
+        You'll need to set this rectangle before calling mouseDown. The centre of the
+        rectangle is assumed to be the centre of the object that will be rotated, and
+        the size of the rectangle will be used to scale the object radius - see setRadius().
+    */
+    void setViewport (const Rectangle<int>& newArea) noexcept
+    {
+        area = newArea;
+    }
+
+    /** Sets the size of the rotated object, as a proportion of the viewport's size.
+        @see setViewport
+    */
+    void setRadius (float newRadius) noexcept
+    {
+        radius = jmax (0.1f, newRadius);
+    }
+
+    /** Begins a mouse-drag operation.
+        You must call this before any calls to mouseDrag(). The position that is supplied
+        will be treated as being relative to the centre of the rectangle passed to setViewport().
+    */
+    template <typename Type>
+    void mouseDown (const Point<Type>& mousePos) noexcept
+    {
+        lastMouse = mousePosToProportion (mousePos.toFloat());
+    }
+
+    /** Continues a mouse-drag operation.
+        After calling mouseDown() to begin a drag sequence, you can call this method
+        to continue it.
+    */
+    template <typename Type>
+    void mouseDrag (const Point<Type>& mousePos) noexcept
+    {
+        const VectorType oldPos (projectOnSphere (lastMouse));
+        lastMouse = mousePosToProportion (mousePos.toFloat());
+        const VectorType newPos (projectOnSphere (lastMouse));
+
+        quaternion *= rotationFromMove (oldPos, newPos);
+    }
+
+    /** Returns the matrix that should be used to apply the current orientation.
+        @see applyToOpenGLMatrix
+    */
+    Matrix3D<GLfloat> getRotationMatrix() const noexcept
+    {
+        return quaternion.getRotationMatrix();
+    }
+
+    /** Applies this rotation to the active OpenGL context's matrix. */
+    void applyToOpenGLMatrix() const noexcept
+    {
+        getRotationMatrix().applyToOpenGL();
+    }
+
+private:
+    typedef Quaternion<GLfloat> QuaternionType;
+    Rectangle<int> area;
+    float radius;
+    QuaternionType quaternion;
+    Point<float> lastMouse;
+
+    Point<float> mousePosToProportion (const Point<float>& mousePos) const noexcept
+    {
+        const int scale = (jmin (area.getWidth(), area.getHeight()) / 2);
+
+        // You must call setViewport() to give this object a valid window size before
+        // calling any of the mouse input methods!
+        jassert (scale > 0);
+
+        return Point<float> ((mousePos.x - area.getCentreX()) / scale,
+                             (area.getCentreY() - mousePos.y) / scale);
+    }
+
+    VectorType projectOnSphere (const Point<float>& pos) const noexcept
+    {
+        const GLfloat radiusSquared = radius * radius;
+        const GLfloat xySquared = pos.x * pos.x + pos.y * pos.y;
+
+        return VectorType (pos.x, pos.y,
+                           xySquared < radiusSquared * 0.5f ? std::sqrt (radiusSquared - xySquared)
+                                                            : (radiusSquared / (2.0f * std::sqrt (xySquared))));
+    }
+
+    QuaternionType rotationFromMove (const VectorType& from, const VectorType& to) const noexcept
+    {
+        VectorType rotationAxis (to ^ from);
+
+        if (rotationAxis.lengthIsBelowEpsilon())
+            rotationAxis = VectorType::xAxis();
+
+        const GLfloat d = jlimit (-1.0f, 1.0f, (from - to).length() / (2.0f * radius));
+
+        return QuaternionType::fromAngle (2.0f * std::asin (d), rotationAxis);
+    }
+};
+
+#endif   // __JUCE_DRAGGABLE3DORIENTATION_JUCEHEADER__

modules/juce_opengl/opengl/juce_Matrix3D.h

@@ -0,0 +1,98 @@
+/*
+  ==============================================================================
+
+   This file is part of the JUCE library - "Jules' Utility Class Extensions"
+   Copyright 2004-11 by Raw Material Software Ltd.
+
+  ------------------------------------------------------------------------------
+
+   JUCE can be redistributed and/or modified under the terms of the GNU General
+   Public License (Version 2), as published by the Free Software Foundation.
+   A copy of the license is included in the JUCE distribution, or can be found
+   online at www.gnu.org/licenses.
+
+   JUCE 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 General Public License for more details.
+
+  ------------------------------------------------------------------------------
+
+   To release a closed-source product which uses JUCE, commercial licenses are
+   available: visit www.rawmaterialsoftware.com/juce for more information.
+
+  ==============================================================================
+*/
+
+#ifndef __JUCE_MATRIX3D_JUCEHEADER__
+#define __JUCE_MATRIX3D_JUCEHEADER__
+
+//==============================================================================
+/**
+    A 4x4 transformation matrix.
+
+    @see AffineTransform
+*/
+template <typename Type>
+class Matrix3D
+{
+public:
+    Matrix3D() noexcept
+    {
+        zeromem (mat, sizeof (mat));
+        mat[0] = mat[1 + 1 * 4] = mat[2 + 2 * 4] = mat[3 + 3 * 4] = (Type) 1;
+    }
+
+    Matrix3D (const Matrix3D& other) noexcept
+    {
+        memcpy (mat, other.mat, sizeof (mat));
+    }
+
+    Matrix3D (const AffineTransform& transform) noexcept
+    {
+        mat[0]  = transform.mat00;  mat[1] =  transform.mat10;  mat[2]  = 0;         mat[3]  = 0;
+        mat[4]  = transform.mat01;  mat[5] =  transform.mat11;  mat[6]  = 0;         mat[7]  = 0;
+        mat[8]  = 0;                mat[9] =  0;                mat[10] = (Type) 1;  mat[11] = 0;
+        mat[12] = transform.mat02;  mat[13] = transform.mat12;  mat[14] = 0;         mat[15] = (Type) 1;
+    }
+
+    Matrix3D (const Type* values) noexcept
+    {
+        memcpy (mat, values, sizeof (mat));
+    }
+
+    Matrix3D (const Type& m00, const Type& m10, const Type& m20, const Type& m30,
+              const Type& m01, const Type& m11, const Type& m21, const Type& m31,
+              const Type& m02, const Type& m12, const Type& m22, const Type& m32,
+              const Type& m03, const Type& m13, const Type& m23, const Type& m33) noexcept
+    {
+        mat[0]  = m00;  mat[1]  = m10;  mat[2]  = m20;  mat[3]  = m30;
+        mat[4]  = m01;  mat[5]  = m11;  mat[6]  = m21;  mat[7]  = m31;
+        mat[8]  = m02;  mat[9]  = m12;  mat[10] = m22;  mat[11] = m32;
+        mat[12] = m03;  mat[13] = m13;  mat[14] = m23;  mat[15] = m33;
+    }
+
+    Matrix3D& operator= (const Matrix3D& other) noexcept
+    {
+        memcpy (mat, other.mat, sizeof (mat));
+        return *this;
+    }
+
+    /** Multiplies the active OpenGL context's matrix by this one. */
+    void applyToOpenGL() const noexcept
+    {
+        applyToGL (mat);
+    }
+
+    /** The 4x4 matrix values. These are stored in the standard OpenGL order. */
+    Type mat[16];
+
+private:
+    static void applyToGL (const GLfloat* const m) noexcept  { glMultMatrixf (m); }
+
+   #if ! JUCE_OPENGL_ES
+    static void applyToGL (const GLdouble* const m) noexcept { glMultMatrixd (m); }
+   #endif
+};
+
+
+#endif   // __JUCE_MATRIX3D_JUCEHEADER__

modules/juce_opengl/opengl/juce_Quaternion.h

@@ -0,0 +1,100 @@
+/*
+  ==============================================================================
+
+   This file is part of the JUCE library - "Jules' Utility Class Extensions"
+   Copyright 2004-11 by Raw Material Software Ltd.
+
+  ------------------------------------------------------------------------------
+
+   JUCE can be redistributed and/or modified under the terms of the GNU General
+   Public License (Version 2), as published by the Free Software Foundation.
+   A copy of the license is included in the JUCE distribution, or can be found
+   online at www.gnu.org/licenses.
+
+   JUCE 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 General Public License for more details.
+
+  ------------------------------------------------------------------------------
+
+   To release a closed-source product which uses JUCE, commercial licenses are
+   available: visit www.rawmaterialsoftware.com/juce for more information.
+
+  ==============================================================================
+*/
+
+#ifndef __JUCE_QUATERNION_JUCEHEADER__
+#define __JUCE_QUATERNION_JUCEHEADER__
+
+#include "juce_Matrix3D.h"
+#include "juce_Vector3D.h"
+
+//==============================================================================
+/**
+    Holds a quaternion (a 3D vector and a scalar value).
+*/
+template <typename Type>
+class Quaternion
+{
+public:
+    Quaternion() noexcept  : scalar() {}
+    Quaternion (const Quaternion& other) noexcept                                     : vector (other.vector), scalar (other.scalar) {}
+    Quaternion (const Vector3D<Type>& vector_, const Type& scalar_) noexcept          : vector (vector_), scalar (scalar_) {}
+    Quaternion (const Type& x, const Type& y, const Type& z, const Type& w) noexcept  : vector (x, y, z), scalar (w) {}
+
+    /** Creates a quaternion from an angle and an axis. */
+    static Quaternion fromAngle (const Type& angle, const Vector3D<Type>& axis) noexcept
+    {
+        return Quaternion (axis.normalised() * std::sin (angle / (Type) 2), std::cos (angle / (Type) 2));
+    }
+
+    Quaternion& operator= (const Quaternion& other) noexcept
+    {
+        vector = other.vector;
+        scalar = other.scalar;
+        return *this;
+    }
+
+    Quaternion& operator*= (const Quaternion& other) noexcept
+    {
+        const Type oldScalar (scalar);
+        scalar = (scalar * other.scalar) - (vector * other.vector);
+        vector = (other.vector * oldScalar) + (vector * other.scalar) + (vector ^ other.vector);
+        return *this;
+    }
+
+    Type length() const noexcept        { return std::sqrt (normal()); }
+    Type normal() const noexcept        { return scalar * scalar + vector.lengthSquared(); }
+
+    Quaternion normalised() const noexcept
+    {
+        const Type len (length());
+        jassert (len > 0);
+        return Quaternion (vector / len, scalar / len);
+    }
+
+    /** Returns the matrix that will perform the rotation specified by this quaternion. */
+    Matrix3D<Type> getRotationMatrix() const noexcept
+    {
+        const Type norm (normal());
+        const Type s (norm > 0 ? ((Type) 2) / norm : 0);
+        const Type xs (s * vector.x),  ys (s * vector.y),  zs (s * vector.z);
+        const Type wx (xs * scalar),   wy (ys * scalar),   wz (zs * scalar);
+        const Type xx (xs * vector.x), xy (ys * vector.x), xz (zs * vector.x);
+        const Type yy (ys * vector.y), yz (zs * vector.y), zz (zs * vector.z);
+
+        return Matrix3D<Type> (((Type) 1) - (yy + zz), xy - wz, xz + wy, 0,
+                               xy + wz, ((Type) 1) - (xx+ zz),  yz - wx, 0,
+                               xz - wy, yz + wx, ((Type) 1) - (xx + yy), 0,
+                               0, 0, 0, (Type) 1);
+    }
+
+    /** The vector part of the quaternion. */
+    Vector3D<Type> vector;
+
+    /** The scalar part of the quaternion. */
+    Type scalar;
+};
+
+
+#endif   // __JUCE_QUATERNION_JUCEHEADER__

modules/juce_opengl/opengl/juce_Vector3D.h

@@ -0,0 +1,82 @@
+/*
+  ==============================================================================
+
+   This file is part of the JUCE library - "Jules' Utility Class Extensions"
+   Copyright 2004-11 by Raw Material Software Ltd.
+
+  ------------------------------------------------------------------------------
+
+   JUCE can be redistributed and/or modified under the terms of the GNU General
+   Public License (Version 2), as published by the Free Software Foundation.
+   A copy of the license is included in the JUCE distribution, or can be found
+   online at www.gnu.org/licenses.
+
+   JUCE 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 General Public License for more details.
+
+  ------------------------------------------------------------------------------
+
+   To release a closed-source product which uses JUCE, commercial licenses are
+   available: visit www.rawmaterialsoftware.com/juce for more information.
+
+  ==============================================================================
+*/
+
+#ifndef __JUCE_VECTOR3D_JUCEHEADER__
+#define __JUCE_VECTOR3D_JUCEHEADER__
+
+//==============================================================================
+/**
+    A three-coordinate vector.
+*/
+template <typename Type>
+class Vector3D
+{
+public:
+    Vector3D() noexcept  : x(), y(), z() {}
+    Vector3D (const Type& xValue, const Type& yValue, const Type& zValue) noexcept  : x (xValue), y (yValue), z (zValue) {}
+    Vector3D (const Vector3D& other) noexcept   : x (other.x), y (other.y), z (other.z) {}
+    Vector3D& operator= (const Vector3D& other) noexcept     { x = other.x;  y = other.y;  z = other.z;  return *this; }
+
+    /** Returns a vector that lies along the X axis. */
+    static Vector3D xAxis() noexcept        { return Vector3D ((Type) 1, 0, 0); }
+    /** Returns a vector that lies along the Y axis. */
+    static Vector3D yAxis() noexcept        { return Vector3D (0, (Type) 1, 0); }
+    /** Returns a vector that lies along the Z axis. */
+    static Vector3D zAxis() noexcept        { return Vector3D (0, 0, (Type) 1); }
+
+    Vector3D& operator+= (const Vector3D& other) noexcept        { x += other.x;  y += other.y;  z += other.z;  return *this; }
+    Vector3D& operator-= (const Vector3D& other) noexcept        { x -= other.x;  y -= other.y;  z -= other.z;  return *this; }
+    Vector3D& operator*= (const Type& scaleFactor) noexcept      { x *= scaleFactor;  y *= scaleFactor;  z *= scaleFactor;  return *this; }
+    Vector3D& operator/= (const Type& scaleFactor) noexcept      { x /= scaleFactor;  y /= scaleFactor;  z /= scaleFactor;  return *this; }
+
+    Vector3D operator+ (const Vector3D& other) const noexcept    { return Vector3D (x + other.x, y + other.y, z + other.z); }
+    Vector3D operator- (const Vector3D& other) const noexcept    { return Vector3D (x - other.x, y - other.y, z - other.z); }
+    Vector3D operator* (const Type& scaleFactor) const noexcept  { return Vector3D (x * scaleFactor, y * scaleFactor, z * scaleFactor); }
+    Vector3D operator/ (const Type& scaleFactor) const noexcept  { return Vector3D (x / scaleFactor, y / scaleFactor, z / scaleFactor); }
+    Vector3D operator-() const noexcept                          { return Vector3D (-x, -y, -z); }
+
+    /** Returns the dot-product of these two vectors. */
+    Type operator* (const Vector3D& other) const noexcept        { return x * other.x + y * other.y + z * other.z; }
+
+    /** Returns the cross-product of these two vectors. */
+    Vector3D operator^ (const Vector3D& other) const noexcept    { return Vector3D (y * other.z - z * other.y, z * other.x - x * other.z, x * other.y - y * other.x); }
+
+    Type length() const noexcept            { return std::sqrt (lengthSquared()); }
+    Type lengthSquared() const noexcept     { return x * x + y * y + z * z; }
+
+    Vector3D normalised() const noexcept    { return *this / length(); }
+
+    /** Returns true if the vector is practically equal to the origin. */
+    bool lengthIsBelowEpsilon() const noexcept
+    {
+        const Type epsilon (std::numeric_limits<Type>::epsilon());
+        return ! (x < -epsilon || x > epsilon || y < -epsilon || y > epsilon || z < -epsilon || z > epsilon);
+    }
+
+    Type x, y, z;
+};
+
+
+#endif   // __JUCE_VECTOR3D_JUCEHEADER__