path: root/doc/src/qt3d-troubleshooting.qdoc

/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: http://www.qt-project.org/
**
** This file is part of the Qt3D documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qt3d-troubleshooting.html
    \title Qt3D Troubleshooting Guide
    \keyword Building QML Qt3D

    Qt3D has been developed with the intention of supporting a variety
    of platforms and systems, and in doing so leverages the plugin and
    import architecture used by Qt.

    This architecture occasionally causes confusion for newcomers to
    the Qt plugin architecture, however, which can cause runtime problems to
    occasionally arise.

    \section1 Common Qt3D Problems

    \section2 PROBLEM 1: I Can't See Warnings from my QML/3D Application

    Many problems with QML (both 2D and 3D) can only be diagnosed through
    warning and status messages.

    In the QMLViewer application these can be viewed by selecting the "Show
    Warnings" item in the "Debugging" menu.

    For QML applications which do not use the QMLViewer, however, no such
    option exists.

    For Linux & Mac:
    \list
    \o Run the application within QtCreator - the warning messages will be
    visible in the Application Output pane.
    \o Run the application from the command line - the warning messages
    will now be displayed directly in the terminal window.
    \endlist

    For Windows
    \list
    \o Run the application within QtCreator - the warning messages will be
    visible in the Application Output pane.
    \o Run the application from within Visual Studio - the warning messages
    will be visible in the Output window.
    \o Use an application such as Windows Sysinternals' "DebugView.exe" to
    capture warning and error messages from your QML application.
    \endlist

    \section2 PROBLEM 2: Qt3D Plugin File Not Found

    By far the most prevalant problems encountered by Qt3D newcomers are
    those relating to inability for an application to find the correct plugins
    at runtime.

    This problem is characterised by a blank screen being displayed, and the
    following warning message:

    \code
    file:///C:/path/to/qml/app/my_app.qml:42:1: module "Qt3D" plugin "qthreedqmlplugin" not found
     import Qt3D 1.0

     ^
    \endcode

    To resolve this problem try each of the Resolution Actions listed, one at
    a time, retrying your application after each step.

    \section2 PROBLEM 3: Qt3D Not Installed

    This is related to the Problem 2, though is characterised by error messages
    containing the following:

    \code
    module "Qt3D" is not installed
    \endcode

    To resolve this problem try each of the Resolution Actions listed, one at
    a time, retrying your application after each step.

    \section2 PROBLEM 4: The Specified Module Could Not Be Found

    This is related to Problem 2, though in this case it is characterised by error
    messages similar to the following:

    \code
    file:///path/to/quick3d/app.qml:10:1: plugin cannot be loaded for module "Qt3D": Cannot load library C:/path/to/Qt/imports/qthreedqmlplugin.dll: The specified module could not be found.
    \endcode

    To resolve this problem try each of the Resolution Actions listed, one at
    a time, retrying your application after each step.

    \section2 PROBLEM 5: 3D Models Fail to Load

    Usually this problem will be accompanied by a message similar to this one:

    \code
    Could not create handler for format - check plugins are installed correctly in /path/to/Qt/plugins
    Could not load file:///path/to/model/my_model.obj (possibly plugin could not be found)
    \endcode

    In this case the problem is that the plugins for various scene formats are
    missing.

    Follow the instructions in Resolution Action 4 onward.

    \section2 PROBLEM 6: Build Keys Do Not Match

    Sometimes users may encounter an error similar to the one shown below:

    \code
    plugin: my_plugin.dll: failed to load: The plugin 'C:/path/to/qt/plugins/my_plugin.dll' uses incompatible Qt library. Expected build key "Windows mingw debug full-config", got "Windows mingw release full-config"
    \endcode

    This error is caused by a mismatch between the Qt library against which the plugin
    was compiled, and the Qt library being used at runtime.

    To resolve this problem follow Resolution Action 5 onward, below.

    \section2 PROBLEM 7: Case mis-match on loading QML plugins

    You get a blank screen when the Qt3D application runs.  The debug output
    (see Problem 1 above) reveals a message similar to
    \code
    Starting C:\Qt\4.7.3\bin\qmlviewer.exe -I C:/Qt/4.7.3/imports C:/Qt/4.7.3/qt3d/bin/resources/examples/basket_qml/qml/basket.qml
    C:/Qt/4.7.3/qt3d/bin/resources/examples/basket_qml/qml/basket.qml: File name case mismatch
    \endcode

    This issue can occur when a custom install directory for Qt is used, which does not
    match the expected directory used by the Qt3D binary installer, but still installs
    without apparent error due to Windows tolerance for case error.

    For example you install Qt applications into \bold{C:\\qt} such as Qt Creator
    but then when you install Qt 4.7.3 you accept the default install location
    of "C:\\Qt" - this succeeds, even though the case preserved name of the
    directory is "C:\\qt".  When Qt Declarative's case checking code parses the
    import statement it refuses to load the qml file.

    This error is very difficult to diagnose and the best way to fix it is to
    uninstall everything from the directory in question, using the package uninstallers
    in the start menu, then remove the directory itself, the finally reinstall everything.

    \section1 Resolution Actions

    \section2 ACTION 1: Ensure that Qt3D is Building Correctly

    As obvious as this sounds, it is sometimes the case that a problem is
    caused simply by one of the runtime libraries or plugins for Qt3D
    failing to build, even while the user's application itself builds without
    error.

    Ensure that all of the components of Qt3D have built without error
    before attempting further resolution actions.

    \section2 ACTION 2: Ensure Import Files Are Correctly Located

    Ensure that the Qt3D import libraries are in the directory specified by
    the QtQuick import path.

    The core Qt3D import directory is: \c{imports\Qt3D} in the directory
    where Qt is installed.

    This directory should contain the files as shown in the following diagram:

    \image imports-dir.png

    Here for the sake of illustration it is assumed Qt 4.7.3 is intalled under
    \c{C:\Qt\4.7.3}.

    If these files are not in the correct locations copy them manually into the
    specified locations and retry your Qt3D application before moving on to
    other fixes.  The dll's should have been built as part of your build process
    and the other files are shipped in the source tree, and can be simply copied
    over if somehow the build process has failed to do this.

    \section2 ACTION 3: Ensure Qt3D Libraries Are Correctly Located

    Ensure that the Qt3D libraries can be found by the application.  The
    files that should be found are:

    \list
    \o Qt3D.dll
    \o Qt3DQuick.dll
    \endlist

    There are three ways to make these files available to your application:

    \list
    \o 1.  Copy these files into the same directory as your application executable.
    \o 2.  Add the current location of these files to your PATH environment variable.
    \o 3.  Copy these files into the Qt binaries directory.
    \endlist

    The Qt binaries directory is:
    \code
    \path\to\qt\bin
    \endcode

    Having executed one of these fixes, retry your application before trying any
    other troubleshooting tips.

    \section2 ACTION 4: Ensure Additional Plugin Libraries Are Correctly Located

    Ensure that the Qt3D plugin libraries are in the directory specified by
    the QtQuick plugins path.

    The Qt3D scene format plugins (which are responsible for loading model files)
    should be found in:

    \code
    \path\to\qt\plugins\sceneformats
    \endcode

    This should contain the following files:

    \list
    \o qsceneai4.dll
    \o qscenebezier4.dll
    \endlist

    Additional Qt3D image format plugins (which are responsible for loading some
    image files) should be found in:

    \code
    \path\to\qt\plugins\imageformats
    \endcode

    This should contain the following files:

    \list
    \o qtga4.dll
    \endlist

    If these files are not in the correct locations copy them manually into the
    specified locations and retry your Qt3D application before moving on to
    other fixes.

    \section2 ACTION 5: Check Your Build Configuration

    It is possible that Qt3D libraries which have been built against a given
    set of Qt libraries have problems when used with another build of Qt.

    This may be resolved by trying each of the following:

    \list
    \o Ensure that the Qt and Qt3D libraries use the same toolchain/compiler.
    \o Ensure that the Qt Configuration used to build Qt3D matches that used in
        your runtime Qt libraries.
    \o Ensure that the Qt used to build Qt3D and the Qt runtimes are both either
        Debug or Release, not a mixture of both.
    \endlist

    After making this change, retry your Qt3D application before implementing
    other troubleshooting tips.

    \section2 ACTION 6: Clear the Plugin Cache

    Qt stores certain information about plugins in the plugin cache.  The plugin
    cache is stored through QSettings, and so is platform independent.

    It is possible that obselete plugin data for an older version of your Qt3D
    plugins could be causing your Qt3D applications to fail.

    On Windows the entries in the plugin cache are stored in the registry, and
    typically begin with one of the following strings:

    \code
    HKEY_CURRENT_USER\Software\Trolltech\OrganizationDefaults\Qt Plugin Cache 4.2.debug
    HKEY_CURRENT_USER\Software\Trolltech\OrganizationDefaults\Qt Plugin Cache 4.2.false
    \endcode

    Delete these entries and retry your Qt3D application.
*/