/****************************************************************************
**
** 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/teapot
    \title Teapot Example

    The Teapot example shows how \l{Qt 3D} can be used to draw a simple
    teapot object with a perspective camera view in C++.  There is
    also a \l{Teapot Example in QML}{QML version} of the teapot
    example.

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

    \snippet qt3d/teapot/teapotview.h class-defn
    \dots
    \quotefromfile qt3d/teapot/main.cpp
    \skipuntil [main]
    \printto [main-args]
    \skipuntil [main-args-end]
    \printto [main]

    When the application starts up, we set up some scene parameters
    in the \c{initializeGL()} function:

    \quotefromfile qt3d/teapot/teapotview.cpp
    \skipuntil [initialize]
    \printto [build-geometry]

    The first line of the function selects a standard rendering
    effect that lights material colors with the default OpenGL
    two-sided lighting algorithm and the default light.

    The \c{teapot} member variable is an instance of QGLSceneNode,
    which we create using QGLBuilder during \c{initializeGL()}:

    \quotefromfile qt3d/teapot/teapotview.cpp
    \skipuntil [build-geometry]
    \printto [initialize]

    The QGLTeapot class represents the geometry for the teapot,
    which is added to the builder with the \c{<<} operator.

    We then call QGLBuilder::finalizedSceneNode() to finalize the
    object, prepare it to be uploaded to the GL server as a
    vertex buffer, and hand over ownership of the scene node.

    We have to take care to clean up our scene after we're done with it
    and here that is done in the destructor:

    \snippet qt3d/teapot/teapotview.cpp destructor

    Finally, we paint the teapot every time the window is refreshed:

    \snippet qt3d/teapot/teapotview.cpp paint

    The QGLView class has in-built support for camera navigation
    using the mouse and keyboard.  By clicking and dragging the mouse,
    the teapot can be rotated into any position.  The image on the
    left shows the view in its startup default position, and the
    image on the right shows the view after rotation using the mouse:

    \table
    \row
        \li \image teapot-screenshot.png
        \li \image teapot-rotated.png
    \endtable

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