View source for Introduction-to-Qt3D

[toc align_right=&quot;yes&amp;quot; depth=&quot;3&amp;quot;]<br />[[Category:Developing_with_Qt::Qt3D]]

= Introduction to Qt 3D =

''NOTE: '''Qt 3D''' (along with '''Qt Quick 3D''' project) is undergoing '''heavy development'''. They are '''not yet part of Qt 5''', and the API shown in this article may be subject to changes.''

''WARNING: The contents of this article were last updated in 2012. This article is heavily outdated.''

'''Qt 3D''' is a set of C++ APIs for 3D programming built on top of '''Qt OpenGL'''. The newest project is called '''Qt Quick 3D''' which creates QML bindings to '''Qt 3D'''.

First, we'll make a comparison of the previous '''OpenGL''' APIs: '''GLUT''' and '''Qt OpenGL'''.

== '''GLUT''' (OpenGL Utility Toolkit) ==

'''GLUT''' was one the first (if not the first) toolkit to provide a portable API to handle '''window management''' for '''OpenGL''' programs. It uses callbacks to register drawing functions and more. There were also routines provided for drawing geometric primitives (both in solid and wireframe state) such as cubes and spheres.

A simple '''OpenGL''' program with just a ''3D cube and some lighting'' could be as long as '''140 lines''' of code when developed with '''GLUT'''.

[[Image:https://gitorious.org/wiki-sources/wiki-sources/blobs/raw/284e0d0b70f0d4d786b16156f0ae0dba1d926e3e/images/3d-cube-screenshot.png|3D Hello World Cube]]<br />''3D cube drawn using OpenGL.''

<code>…

void initialize()<br />{<br /> float ambientLight[] = { 0.2, 0.2, 0.2, 1.0 };<br /> float specularLight[] = { 1.0, 1.0, 1.0, 1.0 };<br /> float specularity[] = { 1.0, 1.0, 1.0, 1.0 };<br /> float shininess[] = { 60.0 };<br /> float lightPosition[] = { 0.0, 50.0, 50.0, 1.0 };

…

// Enable lighting with one light source<br /> glEnable(GL_LIGHTING);<br /> glEnable(GL_LIGHT0);

…

// Properties of the objects' materials<br /> glMaterialfv(GL_FRONT, GL_SPECULAR, specularity); // Reflectance<br /> glMaterialfv(GL_FRONT, GL_SHININESS, shininess); // Shininess

// Enable ambient light usage<br /> glLightModelfv(GL_LIGHT_MODEL_AMBIENT, ambientLight);

glLightfv(GL_LIGHT0, GL_AMBIENT, ambientLight);<br /> glLightfv(GL_LIGHT0, GL_SPECULAR, specularLight);

// Position of the light source<br /> glLightfv(GL_LIGHT0, GL_POSITION, lightPosition);<br />}

…

void resize(int width, int height)<br />{<br /> …

// Set the viewport to be the entire window<br /> glViewport(0, 0, width, height);

…

// Defines the perspective projection<br /> glLoadIdentity();<br /> gluPerspective(45, aspectRatio, 1, 500);

…

// Defines the position of the camera and the target<br /> glLoadIdentity();<br /> gluLookAt(0, 80, 200, 0, 0, 0, 0, 1, 0);<br />}

void paint()<br />{<br /> glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

// Vertices<br /> static const float vertices[6][4][3] = {<br /> { { 1.0, –1.0, 1.0 }, { 1.0, –1.0, –1.0 }, { 1.0, 1.0, –1.0 }, { 1.0, 1.0, 1.0 } },<br /> { { –1.0, –1.0, –1.0 }, { –1.0, –1.0, 1.0 }, { –1.0, 1.0, 1.0 }, { –1.0, 1.0, –1.0 } },<br /> { { 1.0, –1.0, –1.0 }, { –1.0, –1.0, –1.0 }, { –1.0, 1.0, –1.0 }, { 1.0, 1.0, –1.0 } },<br /> { { –1.0, –1.0, 1.0 }, { 1.0, –1.0, 1.0 }, { 1.0, 1.0, 1.0 }, { –1.0, 1.0, 1.0 } },<br /> { { –1.0, –1.0, –1.0 }, { 1.0, –1.0, –1.0 }, { 1.0, –1.0, 1.0 }, { –1.0, –1.0, 1.0 } },<br /> { { –1.0, 1.0, 1.0 }, { 1.0, 1.0, 1.0 }, { 1.0, 1.0, –1.0 }, { –1.0, 1.0, –1.0 } }<br /> };

…

for (int i = 0; i &lt; 6; +''i) {<br /> glBegin(GL_QUADS);<br /> glNormal3fv(normals[i]);<br /> for (int j = 0; j &lt; 4;''+j)<br /> glVertex3fv(vertices[i][j]);<br /> glEnd();<br /> }

glutSwapBuffers();<br />}

int main(int argc, char **argv)<br />{<br /> …

initialize();

// Register the drawing function &quot;paint()&quot;<br /> glutDisplayFunc(paint);

// Register the resizing function &quot;resize()&quot;<br /> glutReshapeFunc(resize);

…<br />}</code> ''Drawing a 3D cube with GLUT.'' &quot;source code&amp;quot;:https://gitorious.org/wiki-sources/wiki-sources/trees/master/opengl

The code above follows a very basic '''OpenGL''' program structure. It has a '''''initialize''''' function (for doing some initial setup), a '''''resize''''' function (to handle window resizes) and a '''''paint''''' function (to draw the actual 3D objects).

== '''Qt OpenGL''' ==

'''Qt OpenGL''' is a port of the '''OpenGL''' API to the '''Qt''' toolkit. It does a fairly good job at translating all of '''OpenGL''' basic functions<br />to a '''Qt''' widget. Now, instead of several functions being registered for callbacks, it is possible to take advantage of the SIGNAL/SLOT system of '''Qt'''.

One of the most commonly used approches for '''Qt OpenGL''' to write a 3D program is to subclass '''QGLWidget'''. '''QGLWidget''' provides three convenience methods that you can reimplement to perform the typical OpenGL tasks: '''paintGL''', '''resizeGL''' and '''initializeGL''' (similar to the '''GLUT''' version of the program).

The program below follows the same basic structure of its '''GLUT''' previous version.

<code>…

class GLWidget : public QGLWidget<br />{<br /> Q_OBJECT

public:<br /> GLWidget(QWidget *parent = 0);

protected:<br /> void initializeGL();<br /> void resizeGL(int width, int height);<br /> void paintGL();<br />};

GLWidget::GLWidget(QWidget *parent)<br /> : QGLWidget(parent)<br />{<br /> setFormat(QGLFormat(QGL::Rgba | QGL::DoubleBuffer | QGL::DepthBuffer));<br />}

void GLWidget::initializeGL()<br />{<br /> float ambientLight[] = { 0.2, 0.2, 0.2, 1.0 };<br /> float specularLight[] = { 1.0, 1.0, 1.0, 1.0 };<br /> float specularity[] = { 1.0, 1.0, 1.0, 1.0 };<br /> float shininess[] = { 60.0 };<br /> float lightPosition[] = { 0.0, 50.0, 50.0, 1.0 };

…

// Enable lighting with one light source<br /> glEnable(GL_LIGHTING);<br /> glEnable(GL_LIGHT0);

…

// Properties of the objects' materials<br /> glMaterialfv(GL_FRONT, GL_SPECULAR, specularity); // Reflectance<br /> glMaterialfv(GL_FRONT, GL_SHININESS, shininess); // Shininess

// Enable ambient light usage<br /> glLightModelfv(GL_LIGHT_MODEL_AMBIENT, ambientLight);

glLightfv(GL_LIGHT0, GL_AMBIENT, ambientLight);<br /> glLightfv(GL_LIGHT0, GL_SPECULAR, specularLight);

// Position of the light source<br /> glLightfv(GL_LIGHT0, GL_POSITION, lightPosition);<br />}

void GLWidget::resizeGL(int width, int height)<br />{<br /> …

// Set the viewport to be the entire window<br /> glViewport(0, 0, width, height);

…

// Defines the perspective projection<br /> glLoadIdentity();<br /> gluPerspective(45, aspectRatio, 1, 500);

…

// Defines the position of the camera and the target<br /> glLoadIdentity();<br /> gluLookAt(0, 80, 200, 0, 0, 0, 0, 1, 0);<br />}

void GLWidget::paintGL()<br />{<br /> glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

// Vertices<br /> static const float vertices[6][4][3] = {<br /> { { 1.0, –1.0, 1.0 }, { 1.0, –1.0, –1.0 }, { 1.0, 1.0, –1.0 }, { 1.0, 1.0, 1.0 } },<br /> { { –1.0, –1.0, –1.0 }, { –1.0, –1.0, 1.0 }, { –1.0, 1.0, 1.0 }, { –1.0, 1.0, –1.0 } },<br /> { { 1.0, –1.0, –1.0 }, { –1.0, –1.0, –1.0 }, { –1.0, 1.0, –1.0 }, { 1.0, 1.0, –1.0 } },<br /> { { –1.0, –1.0, 1.0 }, { 1.0, –1.0, 1.0 }, { 1.0, 1.0, 1.0 }, { –1.0, 1.0, 1.0 } },<br /> { { –1.0, –1.0, –1.0 }, { 1.0, –1.0, –1.0 }, { 1.0, –1.0, 1.0 }, { –1.0, –1.0, 1.0 } },<br /> { { –1.0, 1.0, 1.0 }, { 1.0, 1.0, 1.0 }, { 1.0, 1.0, –1.0 }, { –1.0, 1.0, <s>1.0 } }<br /> };
<br /> …
<br /> for (int i = 0; i &lt; 6; +''i) {<br /> glBegin(GL_QUADS);<br /> glNormal3fv(normals[i]);<br /> for (int j = 0; j &lt; 4;''+j)<br /> glVertex3fv(vertices[i][j]);<br /> glEnd();<br /> }<br />}</code> ''GLWidget class for drawing the 3D cube.'' &quot;source code&amp;quot;:https://gitorious.org/wiki-sources/wiki-sources/trees/master/QtOpenGL/glwidget
<br />This version is still about '''140 lines''' of code. Except that now we have the convenience of using it within a '''Qt''' class. That means, the drawing of the 3D objects can still be done with '''OpenGL''' standard functions, while leaving the window management and input handling part to the '''Qt''' API.
<br />h2. Using '''Qt 3D'''
<br />'''Qt 3D''' was created to simplify the usage of the '''OpenGL''' standard API within a '''Qt''' application. It abstracts most of the setup previously required. Camera position, viewing volume, vertices definition and other initial settings become '''much simpler'''. Therefore, reduces the overall code needed for creating a basic 3D program.
<br />Similar to '''QGLWidget''', in '''Qt 3D''' there's a class named '''QGLView''' which does most of the work regarding this initial settings. All we need to do is subclass it.
<br /><code>/* Qt 3D headers */
<br />class GLView : public QGLView<br />{<br /> Q_OBJECT
<br />public:<br /> GLView(QWidget *parent = 0);<br /> ~GLView();
<br />protected:<br /> void initializeGL(QGLPainter *painter);<br /> void paintGL(QGLPainter *painter);
<br />private:<br /> QGLSceneNode *m_rootNode;<br />};

<br />GLView::GLView(QWidget *parent)<br /> : QGLView(parent)<br /> , m_rootNode(0)<br />{<br /> // Create the cube<br /> QGLBuilder builder;<br /> builder &lt;&lt; QGL::Faceted &lt;&lt; QGLCube(2);<br /> m_rootNode = builder.finalizedSceneNode();
<br /> // Setup the camera<br /> camera()</s>&gt;setFieldOfView(45);<br /> camera()<s>&gt;setNearPlane(1);<br /> camera()</s>&gt;setFarPlane(500);<br />}

GLView::~GLView()<br />{<br /> delete m_rootNode;<br />}

void GLView::initializeGL(QGLPainter *painter)<br />{<br /> QGLLightParameters *lightParameters = new QGLLightParameters(this);<br /> QGLMaterial *material = new QGLMaterial(this);<br /> QColor color;

// Setup the lighting for the scene<br /> painter-&gt;setStandardEffect(QGL::LitMaterial);<br /> color.setRgbF(0.2, 0.2, 0.2, 1.0);<br /> lightParameters-&gt;setAmbientColor(color);<br /> color.setRgbF(1.0, 1.0, 1.0, 1.0);<br /> lightParameters-&gt;setSpecularColor(color);<br /> lightParameters-&gt;setDirection(QVector3D(0.0, 50.0, 50.0));<br /> painter-&gt;setMainLight(lightParameters);

// Apply a material<br /> color.setRgbF(1.0, 1.0, 1.0, 1.0);<br /> material-&gt;setSpecularColor(color);<br /> material-&gt;setShininess(60);<br /> color.setRgbF(0.0, 0.0, 1.0, 1.0);<br /> material-&gt;setAmbientColor(color);<br /> material-&gt;setDiffuseColor(color);<br /> painter-&gt;setFaceMaterial(QGL::AllFaces, material);<br />}

void GLView::paintGL(QGLPainter *painter)<br />{<br /> // Perform some transformations<br /> painter-&gt;modelViewMatrix().translate(0.0, 0.0, 5.0);<br /> painter-&gt;modelViewMatrix().rotate(15.0, 1.0, 0.0, 0.0);<br /> painter-&gt;modelViewMatrix().rotate(30.0, 0.0, 1.0, 0.0);<br /> painter-&gt;modelViewMatrix().rotate(15.0, 0.0, 0.0, 1.0);

// Draw the cube<br /> m_rootNode-&gt;draw(painter);<br />}</code> ''GLView class for drawing the 3D cube.'' &quot;source code&amp;quot;:https://gitorious.org/wiki-sources/wiki-sources/trees/master/Qt3D/glview

The code now looks easier to understand than its previous versions. There was no need for setting the cube's vertices, no aspect ratio calculation, no lighting normals set. The real work is done by the '''QGLBuilder''' class and '''QGLPainter''' class. The first one ('''QGLBuilder''') creates the geometry of the cube and adds it to the scene, while the second ('''QGLPainter''') does the actual drawing of the cube.

The basic structure of the program is still there with the '''paintGL''' and '''initializeGL''' methods. There are also three more classes that handle typical '''OpenGL''' tasks: '''QGLCamera''', '''QGLLightParameters''' and '''QGLMaterial'''.

== References ==

The source code used in this article was based on examples from the following references:<br />&quot;OpenGL Programming Guide&amp;quot;:http://www.glprogramming.com/red/<br />&quot;GLUT&amp;quot;:http://www.opengl.org/resources/libraries/glut/<br />&quot;Qt OpenGL&amp;quot;:http://doc.qt.io/qt-5/qtopengl-index.html<br />&quot;Qt 3D&amp;quot;:http://doc.qt.nokia.com/qt-quick3d-snapshot/

'''Qt 3D''' latest snapshot can be obtained here: &quot;Qt Quick 3D&amp;quot;:http://doc.qt.nokia.com/qt-quick3d-snapshot/