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

/*!
    \page qt3d-index.html
    \title Qt 3D
    \ingroup technology-apis
    \ingroup overviews
    \ingroup qt-gui-concepts

    \brief The Qt 3D module provides a set of APIs to make 3D graphics programming easy and declarative.


    \section1 Overview

    \section1 What is Qt 3D?
    The Qt 3D module provides a set of APIs to make 3D graphics programming easy and declarative. Seamless integration
    with the Qt Quick module allows for developers to add 3D contents to any Qt application in the same way icons and
    pixmaps are used in a regular Qt application. At the same time, Qt 3D is powerful enough for creating full scale
    3D applications or games. To guarantee the graphics performance on various platforms, Qt 3D is hardware accelerated
    using GPU. For more direct and low-level access to 3D graphics hardware, please see OpenGL ES APIs.


    \section1 Common Use Cases
    \list
    \li Adding 3D models to 2D applications - Qt 3D's ViewPort item that defines the logical viewport for a 3D scene can be
    placed in any 2D application. For example, it is possible to place a 3D avatar on a 2D contacts application.
    \li 3D User Interface Elements - Qt 3D handles external inputs such as touch or key events so that it is possible to
    interact with any Qt 3D items on the screen.
    \li 3D Visualizations in media player - Qt 3D's QML API supports regular QML features such as property bindings and QML
    animation framework. Therefore, developers can create a 3D visualization application with less code.
    \li Casual games - Combining Qt 3D features with other Qt modules such as Qt Sensors allows developers to create interactive
    3D games easily.
    \endlist


    \section1 C++ and QML APIs
    Qt 3D consists of two libraries which support the same features in C++ interface and QML respectively. Both libraries
    share the same primary goal which is to make the 3D graphics programming easy. Qt 3D's C++ API  is originally developed
    to make the OpenGL programming as cross-platform as possible.  Traditionally porting between desktop and embedded OpenGL
    variants has been difficult due to differing function names, as well as a shader-based versus fixed function rendering
    pipeline.  The C++ API for Qt 3D eases this difficulty by abstracting these differences away beneath a Qt like API layer. The QML bindings for Qt 3D takes this further and make the 3D programming declarative.

    To use the C++ library in your application, add the following configuration option to your .pro file.

    \code
    QT += 3d
    \endcode

    To use Qt 3D in your QML application you need the following import statement in your qml file.

    \code
    import Qt3D 2.0

    \endcode

    Asset loading, built-in shapes, shaders and texture management are the main features and they are explained below in
    details. Developers may choose a suitable interface depending on requirements or preference.


    \section1 Asset Loading
    Using Qt 3D it is easy to load 3D content from a standard interchange file format into your application. Currently
    supported formats are:

    \table
    \header
        \li \b {Developed by}
        \li \b {File Extension}
        \li \b {Description}
    \row
        \li Waterfront Technologies
        \li .obj
        \li Originally developed for Advanced Visualizer by Waterfront Technologies. The OBJ file format that represents 3D geometry is open and widely adopted.
    \row
        \li Autodesk
        \li .3ds
        \li Format used in 3D Studio MAX. This format is popular among video game developers.
    \row
        \li COLLADA
        \li .dae
        \li COLLADA(COLLAborative Design Activity) is managed by Khronos Group.
    \row
        \li id Software
        \li .MD2
        \li Format used by Quake II and many other games.
    \row
        \li Inivis
        \li .ac
        \li Popular format for games and simulations.
    \row
        \li N/A
        \li .bez
        \li Bezier Surface File specifices collection of bezier patches.
    \endtable

    A QML Example that loads a teapot shaped 3D model:

    \code
    import QtQuick 2.0
    import Qt3D 2.0

    Viewport {
        width: 640; height: 480
        Item3D {
            id: teapot
            mesh: Mesh { source: "teapot.bez" }
            effect: Effect {}
        }
    }
    \endcode


    \section1 Built-in Shapes
    Qt 3D comes with a number of built-in primitive shapes. To use these shapes in your application you need the following import statement in your QML application.

    \code
    import Qt3D.Shapes 2.0
    \endcode

    \image sampleshapes.png


    \section1 Shader and Textures
    Both external 3D models and built-in shapes can be decorated using ShaderProgram and Effect element. The ShaderProgram item is derivative class of the more general Effect class in QML Qt 3D. Whereas the Effect class provides support for standard effects under OpenGL, the ShaderProgram supports effects based on custom shader programs for the GPU.


    \section1 3D Asset Viewer
    Qt 3D comes with a 3D Asset Viewer application which helps the developer to visually scale, rotate, and position a 3D model before adding it to a viewport. The application can then auto create a QML file that can later be used as a component in a QML application. 3D Asset Viewer is launched from Qt Creator as an external application by clicking Tools and External options from the menu tab.


    \section1 Getting Started
    \list
    \li \l {Building Qt 3D}{Building}
    \li \l {Qt 3D Tutorials and Examples}{Tutorials and Examples}
    \li \l {Writing a scene format plug-in for Qt 3D}{Scene format plug-ins}
    \li \l {QGL}{QGL Namespace}
    \li \l {Acceptance tests for Qt 3D}{Acceptance tests}
    \li \l {Qt 3D Troubleshooting Guide}{Troubleshooting Qt 3D}
    \endlist

    \section1 Qt 3D Core Concepts
    \list
    \li \l {Qt 3D Arrays and Vertex Buffers}{Arrays and Vertex Buffers}
    \li \l {Qt 3D Geometry}{Geometry Building}
    \li \l {Qt 3D Graphics View Integration}{Graphics View Integration}
    \li \l {Qt 3D Materials}{Materials}
    \li \l {Qt 3D Math}{Mathematical Primitives}
    \li \l {Qt 3D Painting}{Painting in 3D}
    \li \l {Qt 3D Scene Management}{Scene Management}
    \li \l {Qt 3D Texture Handling}{Texture Management}
    \li \l {Qt 3D Viewing}{Viewing Widgets}
    \endlist

    \section1 API Reference documentation
    \list
    \li \l {Qt 3D Classes}{C++ APIs}
    \li \l {Qt 3D for Scripting 3D Apps in QML}{QML APIs}
    \endlist

    \section1 Extending Qt 3D
    Adding new 3D file format - Qt 3D has a plugin based system so that new format can be supported easily.

    Physics Integration - Physics integration is not officially supported yet, but you can integrate the commonly used Bullet physics engine with C++ Qt 3D.


    \section1 Future Roadmap & Contributions
    Please visit \l{http://bugreports.qt-project.org}{Qt bugreports system, JIRA}, to see our future roadmap.

    We would like to hear your feedback and accept any contributions in forms of code, documentation, examples and bugs reports. Please contact us on the \l{http://lists.qt.nokia.com/mailman/listinfo/qt-3d}{Qt 3D mailing list}.

    See \l{Other Licenses Used in Qt 3D} for details of Qt 3D licensing, and also of 3rd party code used in Qt 3D, including acknowledgements.
*/
