Add files ported from research/qt3d

Fill repo with some of the files from the research/qt3d project.  At
present the new project builds under MacOSX.  To-dos include getting it
building under linux, windows, harmattan and maemo/meego; updating the
documentation to reflect the new QtQuick focus; and fixing the issues
with private headers.

1 files changed, 252 insertions, 0 deletions

diff --git a/doc/src/qt3d-building.qdoc b/doc/src/qt3d-building.qdoc
new file mode 100644
index 000000000..9cf5ffd09
--- /dev/null
+++ b/doc/src/qt3d-building.qdoc
@@ -0,0 +1,252 @@
+/****************************************************************************
+**
+** 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 QtQuick3D documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Free Documentation License
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qt3d-building.html
+    \title Building Qt/3D
+    \keyword Building Qt/3D
+
+    \section1 Obtaining Qt/3D sources
+
+    The source for Qt/3D is hosted on Gitorious as the git repository
+    \l{http://qt.gitorious.org/qt-labs/qt3d}{\c{qt-labs/qt3d.git}}.
+    It can be cloned as follows:
+
+    \code
+    $ mkdir -p $HOME/depot/qt-labs
+    $ cd $HOME/depot/qt-labs
+    $ git clone git://gitorious.org/qt-labs/qt3d.git
+    \endcode
+
+    Once Qt/3D becomes a part of Qt it will be available with Qt binary packages.  Until
+    then it must be built from sources.
+
+    \section1 Obtaining and building Qt sources for Qt/3D
+
+    \bold{Important: A Qt build, compiled from source is required for Qt/3D}.
+
+    This is because Qt/3D requires access to source files that do not ship
+    with an SDK.  Until Qt/3D becomes a regular part of Qt, either download an official
+    Qt 4.7 source package (\l{http://get.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.7.1.tar.gz}{tar.gz}, \l{http://get.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.7.1.zip}{zip}),
+    or a source tarball from our
+    \l{http://qt.gitorious.org/qt/qt/}{gitorious repository}.
+
+    Configure your Qt 4.7 source tree with the \c{-opengl} option. An example:
+    \code
+    mkdir $HOME/build/qt
+    cd $HOME/build/qt
+    tar zxf qt-everywhere-opensource-src-4.7.1.tar.gz
+    ln -s qt* 4.7
+    cd qt*
+    ./configure -opengl
+    make
+    \endcode
+
+    The \c{-developer-build} option is recommended to get debug support,
+    and to ensure that your version of Qt is used and not the system
+    version of Qt.
+
+    On Windows refer to the
+    \l{http://doc.qt.nokia.com/4.7/install-win.html}{build documentation}
+    (but do not use the \c{-opengl} command line option).
+
+    \section1 Obtaining Qt Declarative UI for Qt/3D with QML bindings
+
+    Qt/3D has experimental integration with
+    \l{http://labs.trolltech.com/page/Projects/Graphics/Kinetic/DeclarativeUI}{Declarative UI}
+    via QML bindings.  To experiment with these bindings, ensure you have a source tarball
+    \l{http://qt.gitorious.org/qt/kinetic/}{from our Qt Declarative UI repository}
+    and build as appropriate for your platform.
+
+    Then simply build Qt/3D as described below using the qmake from the Declarative UI
+    build tree.  Once Qt/3D is build you can experiment with the examples in the
+    \c{examples/declarative} directory.
+
+    \section1 Building Qt/3D
+
+    Assuming that you have built Qt 4.7 in
+    \c{$HOME/build/qt/4.7}, you would configure and build Qt/3D as follows:
+
+    \code
+    $ mkdir -p $HOME/build/qt-labs/qt3d
+    $ cd $HOME/build/qt-labs/qt3d
+    $ $HOME/build/qt/4.7/bin/qmake $HOME/depot/qt-labs/qt3d/opengl.pro
+    $ make
+    $ make install
+    $ export LD_LIBRARY_PATH=$PWD/lib:$LD_LIBRARY_PATH
+    \endcode
+
+    The last line exports the library path so that you can run applications
+    from Qt/3D, and is needed so those applications can find the Qt/3D libraries.
+
+    The "\c{make install}" step is required to make plug-ins work,
+    particularly the model loading and QML/3D plug-ins.
+
+    On Windows (with Visual Studio) those commands look like this:
+
+    \code
+    mkdir \build\qt-labs\qt3d
+    cd \build\qt-labs\qt3d
+    \build\qt\4.7\bin\qmake \depot\qt-labs\qt3d\opengl.pro
+    nmake
+    set PATH=%PATH%;\build\qt-labs\qt3d\bin
+    \endcode
+
+    On Symbian (with RVCT) those commands look like this:
+
+    \code
+    cd C:\depot\qt-labs\qt3d
+    qmake CONFIG+=old_importer
+    sbs -c armv5_urel
+    cd devices\symbian
+    createpackage Qt3D_template.pkg release-armv5
+    runonphone --sis Qt3D.sis
+    \endcode
+
+    Once you have built Qt/3D, you can run the "teapot" example to test
+    it as follows (ensure you've exported the library path as above):
+
+    \code
+    $ cd $HOME/build/qt-labs/qt3d
+    $ bin/teapot
+    \endcode
+
+    If all goes well, you should see something like the following
+    on the screen:
+
+    \image teapot-screenshot.png
+
+    Qt/3D has been tested with Qt/X11 and Qt/Embedded under Linux, on MacOSX
+    and Windows XP.  Patches for other platforms are welcome.
+
+    \section1 Installing plugins
+
+    Qt/3D has support for loading 3D model files.  This is enabled via
+    plugins for the various formats.
+
+    3DS files are supported using the open source
+    \l{http://lib3ds.org}{lib3ds} library.  A copy of version 1.3 of this
+    library is included with the Qt/3D sources under the \c{3rdparty}
+    directory.
+
+    If you already have lib3ds installed on your system and you wish to use
+    that instead of the version included with Qt/3D, you can pass the
+    \c{system_3ds} option to qmake:
+
+    \code
+    $ $HOME/build/qt/4.7/bin/qmake $HOME/depot/qt-labs/qt3d/opengl.pro CONFIG+=system_3ds
+    $ make
+    $ make install
+    \endcode
+
+    The last step above will install the plugins into Qt's plugin
+    directory so that the Qt plugin loader can find them at run-time.
+
+    Note that the imageformats plugins include a rudimentary read-only TGA
+    format reader which is required for many model files that use TGA for
+    textures.  If you know for sure that your model files don't use TGA
+    then this step can be skipped.
+
+    See the instructions in \c{plugins/sceneformats/3ds/README.txt} for
+    more information on using the system lib3ds.
+
+    \section1 Building Qt/3D Using QtCreator
+
+    Here is a step-by-step guide to building Qt/3D using the
+    \l{http://qt.nokia.com/products/appdev/developer-tools/developer-tools}{QtCreator IDE}.
+    Read and refer to the above command line section for the full details
+    of building Qt/3D.
+
+    \bold{Step 1} - Open the Qt/3D project.
+
+    Choose \c{Open} from the \c{File} menu and navigate to the qt3d project
+    file \c {$HOME/depot/qt-labs/qt3d/opengl.pro}.  Click \c{Open}.
+
+    \bold{Step 2} - Select Qt, and specify a build directory.
+
+    Now the Qt/3D project is displayed in the \c{Project} listing.  Click the
+    \c{Projects} button on the left-hand side of the screen, and under the
+    \c{Build Settings} tab, choose \c{General} from the \c{Debug} category.
+    Set the Qt build to use, making sure it has OpenGL enabled.  Also
+    specify a build directory, and check the "Shadow Build" box.
+
+    \image qt-creator-shadow-build.png
+
+    Note these screen shots apply to QtCreator v1.3 (beta) on MacOSX, but similar
+    functionality is available in later QtCreator versions, even if the
+    screen appears different.
+
+    \bold{Step 3} - Add the system_3ds switch to qmake
+
+    Only do this step if you have lib3ds installed on your system, as
+    described above, and you want to use the system lib3ds instead of
+    the one included with Qt/3D.
+
+    Do this in QtCreator from the \c{Projects} mode, under the
+    \c{Build Steps} category.  Add \c{CONFIG+=system_3ds} to the "Additional arguments"
+    for the "QMake build configuration".
+
+    \image qt-creator-config-3ds.png
+
+    \bold{Step 4} - Add Qt/3D libraries to the path
+
+    As shown above you'll need to specify the Qt/3D libraries so that they can
+    be found.  Do this in QtCreator from the \c{Projects} mode, under the
+    \c{Build Environment} category.  This will also propagate to the
+    \c{Run Environment}.  On MacOSX the name of the environment variable is
+    \c{DYLD_LIBRARY_PATH}, on Linux it is \c{LD_LIBRARY_PATH}.  On Windows,
+    you'll need to add the \c{bin} directory to the \c{PATH} variable.
+
+    \image qt-creator-lib-path.png
+
+    \bold{Step 5} - Specify the plugin install
+
+    Only do this step if you want to use the Qt/3D model loading plugins,
+    as described above.
+
+    Do this in QtCreator from the \c{Projects} mode, under the
+    \c{Build Steps} category.  Use the + drop-down under the steps list-box
+    to add a \c{Custom Process Step}, and move it below \c{QMake} and \c{Make}.
+    Set the name appropriately, set the command to \c{/usr/bin/make} and
+    the arguments to \c{-C plugins install}.  Note that the
+    name you set may not display in the list box until you restart QtCreator.
+
+    \image qt-creator-plugins.png
+
+    In Windows set the command to the full path to your make program, eg:
+    \c{C:\Program Files\Microsoft Visual Studio 9.0\VC\bin\nmake} and set
+    the "Working Directory" to the imageformats directory: eg
+    \c{C:\build\qt-labs\qt3d\plugins\imageformats}.  The "Command Arguments"
+    are now simply \c{install}.
+
+    \bold{Step 6} - Build Qt/3D
+
+    Click the "Build All" button now to build Qt/3D.
+
+    \l{index.html}{Return to the main Qt/3D page} or
+    \l{qt3d-examples.html}{Continue to the Tutorials and Examples}.
+*/