This directory contains the Qt3D project for Qt 4.x:
   * Qt3D QML bindings and
   * Qt3D C++ APIs


Building Qt3D
==================

Check the building instructions in doc/src/qt3d-building.qdoc also available
online at: http://doc-snapshot.qt-project.org/qt3d-1.0/qt3d-building.html


Whats in Qt3D
==================

Directory structure:

src/threed/
    This is the main library of the Qt3D project, containing abstractions
    for cross-platform GL, shaders, lighting models, and so on.
src/plugins/
    Scene format loading plugins.
src/imports/
    QML import plugins.
util/
    Various utilities that are useful when working with Qt3D.
examples/
    Some examples of using Qt3D (QML bindings) and Qt3D (C++ API).
demos/
    Some more complex demos of using Qt3D (QML bindings) and Qt3D (C++ API).
tests/auto/qml3d/
    Unit tests for the Qt3D bindings.
tests/auto/threed/
    Unit tests for the Qt3D C++ API
doc/
    Documentation.
devices/symbian/
    Symbian deployment file
qtc_harmattan
    Harmattan (N9) support


Documentation
=============

The documentation can be generated with "make docs".  It will be placed
into "doc/html" in the build directory.


Packages
========

This section is only for those developing Qt3D.  Read on to discover how
the building of packages works.  This section is also important if you want to
change how the structure of the Qt3D pro files work.

Qt3D is intended to be built in one of two ways:

1) Normal developer way:
        qmake && make
2) Package creation way:
        qmake CONFIG+=package && INSTALL_ROOT=tmp make install

In 1) the .pro files will cause the toolchain to place the libraries, plugins
header files and other components of Qt3D directly into place, as part of
the compile process.  What does "in place" mean?  Run "qmake -query" to see
the paths where the files are placed - QML plugins go in $$[QT_INSTALL_IMPORTS]
for example.  In this mode, there is no need to run "make install" because the
files are already in their target destination.  Here the "target destination"
means the Qt which is being built against.

First note that Qt3D has to be installed into the target Qt.  This is because
Qt3D has QML plugins and resources, as well as shared libraries, all of which
must be resolved by the QMLViewer of the target Qt at runtime.  Here where "qmake"
is referred to it means the qmake inside the target Qt.  Since QtDeclarative
recommends using QMLViewer when developing and debugging QML Apps, in the developer
case - which is what Qt3D is for - it has to install directly into the target Qt.

In this mode 1) after the main library is compiled subsequent targets can simply
resolve includes and link time dependencies by use of qt3d.prf and qt3dquick.prf.
These two files are installed into the target Qt's makespecs/features directory
during the processing of the qt3d.pro file.

In 2) the libraries, plugins and so on are sitting inside the build tree after
the compile step.  As a result in order to resolve includes and dependencies
the build system has to navigate the build tree with paths like "-L../../../threed"
to locate the Qt3D libraries.

Actually there is one build artifact that is not just left where it lands in the
build tree - the header files.  These are actually copied into an "include"
directory inside the build root directory.  This is because at present the header
files all live inside their own seperate subdirectories under "threed" and would
be too cumbersome to path in explicitly.

After building the tree the install step is invoked using the INSTALL_ROOT environment
export to cause the installation rules to place all the files into a sandboxed
install tree, ready for packaging.