1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
/****************************************************************************
**
** 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$
**
****************************************************************************/
/*!
\title Writing a scene format plug-in for Qt3D
\keyword Scene Format Plugin
\example sceneformats/obj
Scene format plugins are used to load external 3D model file
formats like \bold 3DS, \bold obj, and so on. In this tutorial we will
do a walk-through of the \bold obj scene format plugin to
demonstrate what is required to add a new format to Qt3D.
Models are loaded by QGLAbstractScene::loadScene(), which locates
a suitable plug-in for the format, and then asks the plug-in to
parse the data and create a QGLAbstractScene object that describes
the 3D objects in the scene.
We start by declaring an instance of QGLSceneFormatPlugin and
arranging for it to be registered with the Qt plug-in system:
\snippet sceneformats/obj/main.cpp 1
\snippet sceneformats/obj/main.cpp 4
The two functions we need to implement are
\l{QGLSceneFormatPlugin::keys()}{keys()} and
\l{QGLSceneFormatPlugin::create()}{create()}. The first of these
returns a lower-case list of the file extensions and MIME types
that are supported by the plug-in:
\snippet sceneformats/obj/main.cpp 2
The create function is called to create the QGLSceneFormatHandler
which is used to load the model data:
\snippet sceneformats/obj/main.cpp 3
The create function is passed the QIODevice for the data,
the URL of where the data was found, and the chosen format.
These parameters can be used by the plug-in to decide which
handler to return if multiple formats are supported by
the plug-in. In the case of obj, we always return the same
handler so we don't need to inspect the passed parameters.
QGLAbstractScene::loadScene() will set the parameters on
the QGLSceneFormatHandler object and then call
\l{QGLSceneFormatHandler::read()}{read()}:
\snippet sceneformats/obj/qglobjscenehandler.h 1
\dots
\snippet sceneformats/obj/qglobjscenehandler.h 2
The read function will typically construct a QGLBuilder
for the geometry in the scene and then parse all of the objects,
materials, textures, and so on. Ultimately, it needs to produce a
QGLAbstractScene object, populated with QGLSceneNode instances
for each of the objects in the model file. In our case, we create
an instance of \c QGLObjScene:
\snippet sceneformats/obj/qglobjscene.h 1
\dots
\snippet sceneformats/obj/qglobjscene.h 2
\dots
\snippet sceneformats/obj/qglobjscene.h 3
The most important function is the override for
QGLAbstractScene::objects(), which allows the rest of Qt3D
to query the full list of objects in the model file.
The scene object can also override QGLAbstractScene::object()
if it has an efficient method to quickly look up an object by name.
The scene should also override QGLAbstractScene::mainNode()
to return the main mesh node in the scene. Usually this is
the first element in the list returned by QGLAbstractScene::objects()
but doesn't have to be.
Note: the plug-in does not need to use QGLBuilder and the
other Qt3D classes to load the model if it doesn't want to.
It can instantiate subclasses of QGLSceneNode that override
the draw() method and draws the object using whatever technique
the plug-in chooses. It just needs to leave the OpenGL state
in the condition that it found it so that other parts of Qt3D
will not be confused.
Once you have written a plug-in for your new format, you should
install it into \c{$QTDIR/plugins/sceneformats}. You can test it
by running the \c{modelviewer} program and trying to load models
in your new format. When debugging, it can be useful to set the
\c{QT_DEBUG_PLUGINS} environment variable to 1.
\l{qt3d-examples.html}{Return to the main Tutorials page}.
*/
|
