/****************************************************************************

**

** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the Qt3D module of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:BSD$

** You may use this file under the terms of the BSD license as follows:

**

** "Redistribution and use in source and binary forms, with or without

** modification, are permitted provided that the following conditions are

** met:

**   * Redistributions of source code must retain the above copyright

**     notice, this list of conditions and the following disclaimer.

**   * Redistributions in binary form must reproduce the above copyright

**     notice, this list of conditions and the following disclaimer in

**     the documentation and/or other materials provided with the

**     distribution.

**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor

**     the names of its contributors may be used to endorse or promote

**     products derived from this software without specific prior written

**     permission.

**

** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."

** $QT_END_LICENSE$

**

****************************************************************************/

#include "camera.h"

#include <QtGui/qquaternion.h>

#include <QtCore/qmath.h>

/*!

    \class Camera

    \brief The Camera class defines the projection to apply to simulate a camera's position, orientation, and optics.

    \since 4.7

    \ingroup qt3d

    \ingroup qt3d::viewing

    \section1 Modelview and projection transformations

    A Camera instance is applied to the scene in two phases:

    modelview transformation and projection transformation.

    During the modelview transformation, the eye(), center(), and

    upVector() are used to generate a 4x4 transformation matrix that

    reflects the viewer's current position and orientation.

    During the projection transformation, the projectionType(),

    nearPlane(), farPlane(), fieldOfView(), and viewSize() are used

    to define a viewing volume as a 4x4 transformation matrix.

    The modelview transformation matrix is returned by modelViewMatrix().

    The projection transformation matrix is returned by projectionMatrix().

    \section1 Positioning and orienting the view

    The viewer position and orientation are defined by eye(), center(),

    and upVector().  The location of the viewer in world co-ordinates is

    given by eye(), the viewer is looking at the object of interest located

    at center(), and the upVector() specifies the direction that should

    be considered "up" with respect to the viewer.

    The vector from the eye() to the center() is called the "view vector",

    and the cross-product of the view vector and upVector() is called

    the "side vector".  The view vector specifies the direction the

    viewer is looking, and the side vector points off to the right of

    the viewer.

    It is recommended that the view vector and upVector() be at right angles

    to each other, but this is not required as long as the angle between

    them is close to 90 degrees.

    The most common use of view and up vectors that are not at right angles

    is to simulate a human eye at a specific height above the ground looking

    down at a lower object or up at a higher object.  In this case, the

    the view vector will not be true horizontal, but the upVector() indicating

    the human's upright stance will be true vertical.

    \section1 Zooming the camera image

    There are two ways to zoom the image seen through the camera: either

    the camera eye() position can be moved closer to the object of interest,

    or the field of view of the camera lens can be changed to make it appear

    as though the object is moving closer.

    Changing the eye() position changes the lighting calculation in the

    scene because the viewer is in a different position, changing the

    angle of light reflection on the object's surface.

    The setFieldOfView() function can be used to simulate the effect of a

    camera lens.  The smaller the fieldOfView(), the closer the object

    will appear.  The lighting calculation will be the same as for the

    unzoomed scene.

    If fieldOfView() is zero, then a standard perspective frustum of

    viewSize() is used to define the viewing volume.  The viewSize()

    can be adjusted with setViewSize() to zoom the view.  A smaller

    viewSize() will make the the object appear closer.

    The fieldOfView() or viewSize() is applied as part of the

    projectionMatrix().

    \section1 Rotating the viewer or object of interest

    Rotating a viewer in 3D space is a very delicate process.  It is very

    easy to construct the rotation incorrectly and end up in a "gimbal lock"

    state where further rotations are impossible in certain directions.

    To help alleviate this problem, Camera uses a quaternion-based

    approach to generate rotations.  A quaternion is a compact representation

    of a rotation in 3D space.  Rotations can be combined through quaternion

    multiplication.  More information on quaternions can be found in the

    documentation for QQuaternion.

    Before rotating the view, you should first decide the type

    of rotation you want to perform:

    \list

    \i Tilting or panning a fixed eye to reveal the scene in different

       directions and orientations.  This is equivalent to mounting a camera

       on a fixed tripod and then adjusting the direction of view and

       orientation with the tripod controls.

    \i Rotating a moving viewer about the object of interest.  This is

       equivalent to moving the viewer around the object at a fixed distance,

       but with the viewer always pointing at the object.

    \endlist

    In the Camera class, the first type of rotation is performed with

    rotateEye() and the second with rotateCenter().  Each of these functions

    take a quaternion argument that defines the type of rotation to perform.

    The tilt(), pan(), and roll() functions return values that can help with

    constructing the rotation quaternions to pass to rotateEye() and

    rotateCenter().  Tilt and pan are also known as "pitch" and "yaw" in

    flight dynamics.

    Three axes of rotation are used to compute the quaternions.  The tilt()

    quaternion is computed with respect to the side vector, the pan()

    quaterion is computed with respect to the upVector(), and the roll()

    quaternion is computed with respect to the view vector.

    The following example tilts the direction the eye() is pointing

    by 5 degrees, and then pans by 45 degrees:

    \code

    camera.rotateEye(camera.tilt(5));

    camera.rotateEye(camera.pan(45));

    \endcode

    The next example performs the two rotations in a single fluid step

    (note that the rotation to be performed first is multiplied last):

    \code

    camera.rotateEye(camera.pan(45) * camera.tilt(5));

    \endcode

    These two examples will not produce the same visual result, even though

    it looks like they might.  In the first example, the upVector() is tilted

    before the pan() quaternion is computed.  In the second example, the pan()

    quaternion is computed using the original upVector().

    This difference in behavior is useful in different situations.  Some

    applications may wish to perform all rotations relative to the original

    viewer orientation, and other applications may wish to perform rotations

    relative to the current viewer orientation.  These application types

    correspond to the second and first examples above.

    \section1 Moving the viewer or object of interest

    The simplest way to move the viewer or object of interest is to call

    setEye() or setCenter() respectively and supply a new position in

    world co-ordinates.  However, this can lead to non-intuitive movements

    if the viewer orientation is not aligned with the world co-ordinate axes.

    For example, subtracting 3 from the eye() x co-ordinate will appear to

    move the eye left 3 units if the viewer orientation is aligned with the

    world co-ordinate axes.  But it will not appear to move the eye left 3

    units in any other orientation.

    The translation() function can be used to construct a translation

    vector that is aligned with the viewer's current orientation.

    Movement in the x direction will move along the side vector, movement in

    the y direction will move along upVector(), and movement in the z

    direction will move along the view vector.

    The translation() function is useful when implementing operations such

    as "step left", "jump up", and so on where the movement should be

    interpreted relative to the viewer's current orientation, not the

    world co-ordinate axes,

    In other words, the following two lines of code are not equivalent

    unless the view is oriented with the world co-ordinate axes:

    \code

    camera.translateEye(camera.translation(x, y, z));

    camera.translateEye(QVector3D(x, y, z));

    \endcode

    The following example translates the eye() position while

    keeping the object of interest at the original center():

    \code

    camera.translateEye(camera.translation(x, y, z));

    \endcode

    The following example translates the object of interest at

    center() while keeping the eye() position fixed:

    \code

    camera.translateCenter(camera.translation(x, y, z));

    \endcode

    The following example translates both the eye() and the center()

    by the same amount, which will maintain the original view vector.

    \code

    QVector3D vector = camera.translation(x, y, z);

    camera.translateEye(vector);

    camera.translateCenter(vector);

    \endcode

    It is important that the translation vector for center() be computed

    before eye() is translated if both eye() and center() must move by the

    same amount.  The following code translates center() in the viewer

    orientation after the eye() is translated:

    \code

    camera.translateEye(camera.translation(x, y, z));

    camera.translateCenter(camera.translation(x, y, z));

    \endcode

    Translating both eye() and center() by the same amount can be used

    to simulate sliding a viewer past a scene while always looking in the

    same direction (for example, filming a scene from a moving vehicle).

    An alternative is to fix the viewer and move the scene itself:

    the negation of the translation() vector can be applied to the

    scene's modelview transformation.

    \section1 Motion tracking

    Viewing of 3D scenes can be enhanced if there is some way to track

    the motion of the viewer or the orientation of the display device.

    Applications can use setMotionAdjustment() to alter the position

    of the camera to account for the viewer's motion.  This indicates

    the viewer's position relative to the center of the screen.

    The motionAdjustment() vector is used to determine by how much

    the camera position should be adjusted.  The distance of the viewer

    from the screen is ignored.

    On handheld devices that use accelerometers to determine the

    orientation of the device, the down vector due to gravity

    can be adjusted to serve as a motion tracking vector.

    The output of motion tracking hardware can be very noisy,

    with minor fluctuations due to viewer twitch movements or

    environmental factors.  The application is responsible for

    cleaning up the signal and removing these fluctuations before

    setMotionAdjustment() is called.

*/

class CameraPrivate

{

public:

    CameraPrivate();

    Camera::ProjectionType projectionType;

    qreal fieldOfView;

    qreal nearPlane;

    qreal farPlane;

    QSizeF viewSize;

    QSizeF minViewSize;

    int screenRotation;

    QVector3D eye;

    QVector3D upVector;

    QVector3D center;

    QVector3D viewVector;

    qreal eyeSeparation;

    QVector3D motionAdjustment;

    QQuaternion motionQuaternion;

    bool adjustForAspectRatio;

};

CameraPrivate::CameraPrivate()

    : projectionType(Camera::Perspective),

      fieldOfView(0.0f),

      nearPlane(5.0f),

      farPlane(1000.0f),

      viewSize(2.0f, 2.0f),

      minViewSize(0.0001f, 0.0001f),

      screenRotation(0),

      eye(0.0f, 0.0f, 10.0f),

      upVector(0.0f, 1.0f, 0.0f),

      center(0.0f, 0.0f, 0.0f),

      viewVector(0.0f, 0.0f, -10.0f),

      eyeSeparation(0.0f),

      motionAdjustment(0.0f, 0.0f, 1.0f),

      adjustForAspectRatio(true)

{

}

/*!

    Constructs a Camera with the default properties and

    attaches it to \a parent.

*/

Camera::Camera(QObject *parent)

    : QObject(parent), d_ptr(new CameraPrivate)

{

}

/*!

    Destroys this Camera object.

*/

Camera::~Camera()

{

    delete d_ptr;

}

/*!

    \enum Camera::ProjectionType

    This enum defines the type of view projection to use for a Camera.

    \value Perspective Use a perspective view.

    \value Orthographic Use an ortographic view.

*/

/*!

    \property Camera::projectionType

    \brief the projection type for this camera.  The default is Perspective.

*/

Camera::ProjectionType Camera::projectionType() const

{

    Q_D(const Camera);

    return d->projectionType;

}

void Camera::setProjectionType(Camera::ProjectionType value)

{

    Q_D(Camera);

    if (d->projectionType != value) {

        d->projectionType = value;

        emit projectionChanged();

    }

}

/*!

    \property Camera::fieldOfView

    \brief the field of view in degrees for a perspective projection.

    The default value is zero, which indicates a standard perspective

    frustum view volume of viewSize() in size.  If the value is not

    zero, then viewSize() is ignored.

    This value is ignored if projectionType() is Orthographic.

    \sa viewSize()

*/

qreal Camera::fieldOfView() const

{

    Q_D(const Camera);

    return d->fieldOfView;

}

void Camera::setFieldOfView(qreal angle)

{

    Q_D(Camera);

    if (d->fieldOfView != angle) {

        d->fieldOfView = angle;

        emit projectionChanged();

    }

}

/*!

    \property Camera::nearPlane

    \brief the distance from the eye to the near clipping plane.

    The default value is 5.

    \sa farPlane()

*/

qreal Camera::nearPlane() const

{

    Q_D(const Camera);

    return d->nearPlane;

}

void Camera::setNearPlane(qreal value)

{

    Q_D(Camera);

    if (d->nearPlane != value) {

        d->nearPlane = value;

        emit projectionChanged();

    }

}

/*!

    \property Camera::farPlane

    \brief the distance from the eye to the far clipping plane.

    The default value is 1000.

    \sa nearPlane()

*/

qreal Camera::farPlane() const

{

    Q_D(const Camera);

    return d->farPlane;

}

void Camera::setFarPlane(qreal value)

{

    Q_D(Camera);

    if (d->farPlane != value) {

        d->farPlane = value;

        emit projectionChanged();

    }

}

/*!

    \property Camera::viewSize

    \brief the size of the front of the projection viewing volume.

    The viewing volume is assumed to be centered on the origin.

    The default value is (2, 2), which indicates a viewing volume front

    from (-1, -1) to (1, 1).

    If the width or height of the viewing volume is negative, then the

    co-ordinates will be swapped.  For example, a size of (2, -2) will

    flip the vertical axis upside down for a viewing volume from

    (-1, 1) to (1, -1).

    The view size will be further adjusted by the window's aspect ratio

    when projectionMatrix() is called.  For best results, the width and

    height of the view size should be the same to define an ideal square

    viewing volume, which is then extended to the final viewing volume

    width and height based on the window's aspect ratio.

    \sa projectionMatrix(), minViewSize()

*/

QSizeF Camera::viewSize() const

{

    Q_D(const Camera);

    return d->viewSize;

}

void Camera::setViewSize(const QSizeF& size)

{

    Q_D(Camera);

    QSizeF sz(size);

    if (sz.width() < d->minViewSize.width())

        sz.setWidth(d->minViewSize.width());

    if (sz.height() < d->minViewSize.height())

        sz.setHeight(d->minViewSize.height());

    if (d->viewSize != sz) {

        d->viewSize = sz;

        emit projectionChanged();

    }

}

/*!

    \property Camera::minViewSize

    \brief the minimum size of the front of the projection viewing volume.

    The minimum view size is used to clamp viewSize() when zooming

    the camera closer to an object to prevent it "passing through"

    the object and causing the scale factor to become infinite.

    The default value is (0.0001, 0.0001).

    \sa projectionMatrix(), viewSize()

*/

QSizeF Camera::minViewSize() const

{

    Q_D(const Camera);

    return d->minViewSize;

}

void Camera::setMinViewSize(const QSizeF& size)

{

    Q_D(Camera);

    if (d->viewSize != size) {

        d->viewSize = size;

        emit projectionChanged();

    }

}

/*!

    \property Camera::screenRotation

    \brief the screen rotation angle in degrees.  The default

    value is 0.  If this value is 90 or 270, then the view

    will be flipped width for height.  The only supported values

    are 0, 90, 180, and 270.  The screen is rotated around the

    positive z axis.

    This setting is intended for simple screen rotations on handheld

    devices that can be held in either portrait or landscape orientations.

    The entire screen image is rotated so that it can be viewed in a

    different device orientation.

    Use rotateEye() or rotateCenter() for more complex rotations

    that are not aligned with 0, 90, 180, or 270 degrees.

*/

int Camera::screenRotation() const

{

    Q_D(const Camera);

    return d->screenRotation;

}

void Camera::setScreenRotation(int angle)

{

    Q_D(Camera);

    if (d->screenRotation != angle) {

        d->screenRotation = angle;

        emit projectionChanged();

    }

}