/****************************************************************************
**
** 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$
**
****************************************************************************/

/*!
    \example qt3d/penguin_advanced
    \title Loading a 3DS model with Qt 3D

    This tutorial shows how \l{Qt 3D} can be used to load a simple
    model object in 3D Studio Max (3DS) format with a perspective
    camera view.

    We start by defining a class that inherits from QGLView, which
    provides some basic scene setup logic and 3D camera navigation:

    \snippet qt3d/penguin/modelview.h class-defn

    Refer first to the \l{Teapot Example} for the basics of using
    the QGLView class, lighting and so on.

    When the application starts up, we load the scene from its
    resource file, and store the result in a member variable, so
    we can refer to it in the paint function:

    \snippet qt3d/penguin/modelview.cpp initialize

    In the teapot example we had to specify appropriate effects but
    the model loader sets appropriate effects on the scene for us.

    \snippet qt3d/penguin/modelview.cpp paint

    Here in the paint function we call the \c{draw()} function of
    the scene's main object, in order to display the fully
    loaded model.

    This was really just two lines of code: one to load the model
    (once off, when the application initialized) and another line to
    display the model (every time the paint function is called).

    \image penguin-0-screenshot.png

    The result is pretty good for two lines of code, but it could
    stand some improvements.

    Here we are looking down onto the top of our penguin's head, and
    even when we stand him on his feet, he is too close to the camera
    to all fit in the frame.

    Let's make a few changes to have our penguin display nicely
    when the application opens.

    \snippet penguin_advanced/modelview.cpp initialize

    First of all, let move the camera away from the penguin and up
    so he fits in the frame and we can get a better angle on him,
    when the application loads.

    If we use dragging and so on in the QGLView this will change the
    camera from these intial settings,  but this setup means the camera
    will be well positioned at the moment the application opens.

    We don't want to position the camera in the paintGL function,
    because that would defeat QGLViews camera dragging features and
    we would not be able to interact with the view properly.

    We'll also save the main object away in a member variable so that
    the overhead of searching the scene is not incurred every paint.

    Finally a pose for our penguin is calculated - its a turn around the
    x axis, so he is standing up on his feet; and a turn around the y
    axis, so he shows a bit more of his profile.  The pose is
    calculated and stored as a quaternion - we want the x twist first
    so that goes last in the product of the two quaternions.

    \snippet penguin_advanced/modelview.cpp paint

    Now all that remains in the updated paint function is to apply the
    new pose, and then paint the penguin.

    \image penguin-screenshot.png

    \l{Qt 3D Tutorials and Examples}{Return to Tutorials}.
*/
