/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the Qt3D documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \ingroup qt3d
    \ingroup qt3d::math
    \since 4.8
    \title 3D Math Basis
    \page qt3d-math-basis.html
    \keyword 3D Math Basis
    \brief Math foundations for the Qt 3D math classes.

    The math classes provide basic operations in 3-space useful for graphics:
    \list
    \li QLine3D
    \li QLineSegment3D
    \li QPlane3D
    \li QTriangle3D
    \li QBox3D
    \endlist

    This is a basic discussion of the mathematics behind these classes.

    \section1 Vectors and Points

    There are two important building blocks in 3D: the \b vector and the
    \b point in cartesian 3-space.

    Both are comprised by 3 values in \b R, the real numbers.

    So programatically in Qt both vectors and points are stored in a QVector3D instance,
    since that class can store 3 qreal values.

    But there are important differences between points and vectors:
    \list
    \li a point \b P is a 3D \e location, and makes sense in terms of a 3D cartesian
        coordinate system.  A real-world example is a map-location given in terms
        of a map cross-reference.  The location has no inherent magnitude, unless you
        provide another location and find the distance between the two.
    \li a vector \b v is a 3D \e direction and magnitude.  It makes no sense to talk
        about a vector being located somewhere.  A vector can represent for example
        some directions like "go 3 north-west 3 kilometers", but this can be done from
        \b {anywhere on the map} - it is not anchored like the point is.
    \endlist

    In 3D math points and vectors are represented by column vectors:

    \image vector-point.png

    In normal text where the over-arrow symbol is not available the vector is just a
    bolded lower-case letter.  A point is a capital letter, non-bolded.

    The fourth element in the column vectors above, w = 1 for points and w = 0 for vectors
    means that vectors are not altered by certain affine transformations such
    as \c{translate()}.

    \image affine-transform.png

    This affine transform T comprises a rotation and a translation.  Remember that applying
    the transform is done by the
    \l{http://www.intmath.com/Matrices-determinants/4_Multiplying-matrices.php}{matrix multiplication}
    \c{P * T = P'}.

    Notice how the 1 in the column for the translation multiplies out to zero against
    the vectors last 0 value, so the vector is "immune" to the translation.

    In the case of the point the w = 1 "triggers" the translation values in the matrix.

    So the take away principle is that points and vectors, while represented by the same
    data structure are different and behave differently in 3D math.

    \section2 Vector Magnitude and Normal Vectors

    Another important difference between points and vectors is that a vector has a magnitude,
    whereas a point does not.

    Consider the vector v = (v0, v1, v2) to be rooted at
    the origin O = (0, 0, 0) and pointing to the point P = (v0, v1, v2), then
    its magnitude is the length of the line O to P.  Magnitude is represented by
    vertical bars and is found by this formula:

    \image vector-mag.png

    Unit vectors are those with a magnitude of exactly 1.  The math notation is a "hat"
    (or circumflex) over the bolded vector symbol.

    A unit vector parallel to one of the axes is easy to form without any division:
    \raw HTML
    <center><b>&#238;</b> = (1, 0, 0)</center>
    \endraw

    More typically such a vector is found by dividing by its own length:

    \image vector-normalized.png

    Vectors used for 3D normals are usually normalized to unit length.  Confusingly
    enough, since that is two different uses of the word "normal".

    A \e normal is simply a vector perpendicular to something.  For example a plane normal is
    perpendicular to the plane.

    Typically a normal vector is unit length, for convenience in 3D applications (but
    there is nothing mathematically to say a normal vector has to be unit length).

    A vertex normal is perpendicular to the surface modelled by the vertex, and is used
    in lighting calculations.

    \section1 Reviewing Operations on Vectors

    The QVector3D class provides two very useful functions - the vector dot-product and the
    vector cross-product.  Here's a quick review of their uses:
    \list
    \li QVector3D::crossProduct(const QVector3D &, const QVector3D &)
        \list
        \li The cross-product of two vectors produces a \e vector as a result and is
        written \b w = \b u x \b v. The result \b w is perpendicular to both
        \b u and \b v.  Consider a plane N containing point P, with the tails of \b u
        and \b v at P, and both lying in N, then \b u x \b v is a normal to N.
        \endlist
    \li QVector3D::dotProduct(const QVector3D &, const QVector3D &)
        \list
        \li The dot-product of two vectors produces a \e scalar as a result and is written
        \c{t = \b u . \b v}.  The result t = |u| |v| cos(A), where A is the angle
        between u and v.  When \b u and \b v have magnitude 1, they are called
        unit vectors, and \b u . \b v = cos(A).
        \endlist
    \endlist

    A vector has the following operations defined on it in 3-space
    \list
    \li multiplication by a scalar, eg v' = s * \b v
    \li addition with another vector, eg \b u = \b v + \b w
    \endlist

    Multiplying and dividing by vectors is not defined - these operations make no sense in
    3-D space.

    Although you cannot add a vector to a point as such, you can consider the vector from the
    origin to the point, and add the vector to that.  Thus rather than out-lawing adding a
    vector to a point it is simply defined as such.  This allows the convenient notation for
    lines and planes introduced in the next section.

    \section1 Representing Lines and Planes

    The QLine3D is represented by a point and a vector: the point anchors the line in
    cartesian 3-space; and the vector is the direction the line is oriented in through that
    point.  The line is infinite.

    The QPlane3D is represented also by a point and a vector.  Again the point anchors the line
    in cartesian 3-space; but the vector this time is a normal to the plane.  The plane is
    infinite.

    This representation turns out to make many types of calculations required for 3D graphics
    very straight forward.

    For example to find if a point P lies on a plane take the vector \b p from the point to
    the planes origin, and find the dot-product with the planes normal \b n.

    If \b {p . n} is zero, then \b p is perpendicular to \b n, and P is on the plane.

    \target vector-and-point-arithmetic
    \section1 Vector and Point Arithmetic

    Slightly more complex arithmetic with the components of QLine3D and QPlane3D is possible,
    with some care about what operations can be performed.

    As an example look at the implementation for QLine3D::intersection(const QLine3D &) : the
    two lines are defined as:

    \image line-int-1.png

    If the two lines intersect then P(t) == Q(s) and for some ordered pair \b s, \b t
    is a solution to the equations for both lines.

    The aim is to solve for \b s and \b t.

    The equations can be rearranged algebraically as shown in the last line above.

    But since dividing by a vector is not defined, tempting options such as dividing by \b v
    to solve for t are not possible.  In the implementation the next step is breaking the points
    and vectors down into their x, y and z components giving 3 simultaneous equations:

    \image line-int-2.png

    This can be readily solved using gaussian elimination to get a solution for s, and
    substituting back gives t.
*/
