|
|
              
Qt3D Troubleshooting GuideQt3D 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. Common Qt3D ProblemsPROBLEM 1: I Can't See Warnings from my QML/3D ApplicationMany 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:
For Windows
PROBLEM 2: Qt3D Plugin File Not FoundBy 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: file:///C:/path/to/qml/app/my_app.qml:42:1: module "Qt3D" plugin "qthreedqmlplugin" not found import Qt3D 1.0 ^ To resolve this problem try each of the Resolution Actions listed, one at a time, retrying your application after each step. PROBLEM 3: Qt3D Not InstalledThis is related to the Problem 2, though is characterised by error messages containing the following: module "Qt3D" is not installed To resolve this problem try each of the Resolution Actions listed, one at a time, retrying your application after each step. PROBLEM 4: The Specified Module Could Not Be FoundThis is related to Problem 2, though in this case it is characterised by error messages similar to the following: 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.
To resolve this problem try each of the Resolution Actions listed, one at a time, retrying your application after each step. PROBLEM 5: 3D Models Fail to LoadUsually this problem will be accompanied by a message similar to this one: 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) In this case the problem is that the plugins for various scene formats are missing. Follow the instructions in Resolution Action 4 onward. PROBLEM 6: Build Keys Do Not MatchSometimes users may encounter an error similar to the one shown below: 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" 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. PROBLEM 7: Case mis-match on loading QML pluginsYou get a blank screen when the Qt3D application runs. The debug output (see Problem 1 above) reveals a message similar to 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 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 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. Resolution ActionsACTION 1: Ensure that Qt3D is Building CorrectlyAs 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. ACTION 2: Ensure Import Files Are Correctly LocatedEnsure that the Qt3D import libraries are in the directory specified by the QtQuick import path. The core Qt3D import directory is: imports\Qt3D in the directory where Qt is installed. This directory should contain the files as shown in the following diagram:
Here for the sake of illustration it is assumed Qt 4.7.3 is intalled under 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. ACTION 3: Ensure Qt3D Libraries Are Correctly LocatedEnsure that the Qt3D libraries can be found by the application. The files that should be found are:
There are three ways to make these files available to your application:
The Qt binaries directory is: \path\to\qt\bin Having executed one of these fixes, retry your application before trying any other troubleshooting tips. ACTION 4: Ensure Additional Plugin Libraries Are Correctly LocatedEnsure 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: \path\to\qt\plugins\sceneformats This should contain the following files:
Additional Qt3D image format plugins (which are responsible for loading some image files) should be found in: \path\to\qt\plugins\imageformats This should contain the following files:
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. ACTION 5: Check Your Build ConfigurationIt 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:
After making this change, retry your Qt3D application before implementing other troubleshooting tips. ACTION 6: Clear the Plugin CacheQt 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: HKEY_CURRENT_USER\Software\Trolltech\OrganizationDefaults\Qt Plugin Cache 4.2.debug HKEY_CURRENT_USER\Software\Trolltech\OrganizationDefaults\Qt Plugin Cache 4.2.false Delete these entries and retry your Qt3D application. |
