diff options
Diffstat (limited to 'doc/src/qt3d-troubleshooting.qdoc')
| -rw-r--r-- | doc/src/qt3d-troubleshooting.qdoc | 295 |
1 files changed, 0 insertions, 295 deletions
diff --git a/doc/src/qt3d-troubleshooting.qdoc b/doc/src/qt3d-troubleshooting.qdoc deleted file mode 100644 index 9fc2cb22..00000000 --- a/doc/src/qt3d-troubleshooting.qdoc +++ /dev/null @@ -1,295 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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$ -** 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 QtQuick3D Troubleshooting Guide - \keyword Building QML QtQuick3D - - Quick3D 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 Quick3D 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 Quick3D 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 Qt Quick 3D 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/quick3d/bin/resources/examples/basket_qml/qml/basket.qml - C:/Qt/4.7.3/quick3d/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 Quick3D 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 Quick3D - failing to build, even while the user's application itself builds without - error. - - Ensure that all of the components of Quick3D have built without error - before attempting further resolution actions. - - \section2 ACTION 2: Ensure Import Files Are Correctly Located - - Ensure that the Quick3D import libraries are in the directory specified by - the QtQuick import path. - - The core Quick3D 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 Quick3D 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 Quick3D 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 Quick3D plugin libraries are in the directory specified by - the QtQuick plugins path. - - The Quick3D 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 Quick3D 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 Quick3D application before moving on to - other fixes. - - \section2 ACTION 5: Check Your Build Configuration - - It is possible that Quick3D 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 Quick3D libraries use the same toolchain/compiler. - \o Ensure that the Qt Configuration used to build Quick3D matches that used in - your runtime Qt libraries. - \o Ensure that the Qt used to build Quick3D and the Qt runtimes are both either - Debug or Release, not a mixture of both. - \endlist - - After making this change, retry your Quick3D 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 Quick3D 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 Quick3D application. -*/ |