diff options
Diffstat (limited to 'doc/src')
120 files changed, 5494 insertions, 0 deletions
diff --git a/doc/src/acceptance/qt3d-acceptance.qdoc b/doc/src/acceptance/qt3d-acceptance.qdoc new file mode 100644 index 000000000..82a94b6c6 --- /dev/null +++ b/doc/src/acceptance/qt3d-acceptance.qdoc @@ -0,0 +1,196 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \page qt3d-acceptance.html + \title Acceptance tests for Qt/3D + \keyword Acceptance + + This section of the documentation contains some recommended + acceptance tests for use when verifying that Qt/3D has been + successfully ported to a new platform or device, and to + determine if the major features of Qt/3D work correctly prior + to a release. The list of tests is not intended to be exhaustive. + + When \l{Contributing to Qt/3D}{reporting bugs}, please include + as much information as possible about your platform and particularly + its OpenGL implementation. The \c{qglinfo} program in the Qt/3D + source tree can be used to collect up information about the OpenGL + version, features, and extensions. On X11 systems, usually + \c{glxinfo} can be run to obtain similar information. + + \section1 Basic bring-up + + A pre-requisite for the acceptance tests is that Qt and Qt/3D have + been built and installed in accordance with the + \l{Building Qt/3D}{build instructions}. In particular, Qt must + be configured with OpenGL support and QGLWidget must be working. + + First, run all unit tests on the platform or device and verify that + they all pass (\l{Contributing to Qt/3D}{report bugs} for those that + do not pass). The "make check" rule can be used to run the + unit tests if you are not cross-compiling. For cross-compile + environments, copy all of the \c{tst_*} binaries under \c{tests/auto} + to the device and run them. + + Next, run the \l{Teapot Example} and verify that it looks similar + to the following picture: + + \image teapot-screenshot.png + + Verify that there is no horizontal or vertical distortion, + as shown in the following pictures: + + \raw HTML + <center><table><tr><td> + \endraw + \image teapot-distortion.png + \raw HTML + </td><td> + \endraw + \image teapot-distortion2.png + \raw HTML + </td></tr></table></center> + \endraw + + Resize the window if possible. The teapot should change scale but + keep its relative horizontal and vertical size without distortion. + Next, verify that the teapot can be rotated using either the mouse + or the cursor keys: + + \image teapot-rotated.png + + If the teapot does not appear at all, then check stdout for any + error and warning messages from the GLSL shader compiler. + + \section1 Animations + + Run the \l{Basket Example} and verify that the basket spins on + its vertical axis, and continues to do so as the window is + resized or the orientiation is changed with the mouse or keyboard. + The model should also be textured with a basket weave pattern: + + \image basket-screenshot.png + + Running the basket example with the environment variable + \c{QT3D_LOG_EVENTS} set to 1 should produce some qDebug() + output that indicates the number of milliseconds per frame, + and hence the frame rate: + + \code + $ QT3D_LOG_EVENTS=1 ./basket + ... + LOG[0:00:01.681]: ENTER: QGLView::paintGL (16 ms since last enter) + LOG[0:00:01.681]: LEAVE: QGLView::paintGL (0 ms elapsed) + LOG[0:00:01.696]: ENTER: QGLView::paintGL (15 ms since last enter) + LOG[0:00:01.696]: LEAVE: QGLView::paintGL (0 ms elapsed) + LOG[0:00:01.713]: ENTER: QGLView::paintGL (17 ms since last enter) + ... + \endcode + + If the basket does not spin, then try to determine if + \c{BasketView::paintGL()} is being called every frame or not. + If it is being called over and over, then the problem + may be in Qt/3D. But if it is not being called repeatedly, then + it could be a problem in Qt's animation framework or QGLWidget + update processing. + + \section1 Rendering into a framebuffer object + + Run the \l{nesting}{Nesting} example to test if rendering into a + framebuffer object works: + + \image nesting-screenshot.png + + The teapot on the side of the blue cube is the part of the scene + that uses a framebuffer object. The teapot should be spinning. + + This test also checks that alpha blending works in the underlying + OpenGL implementation. + + \section1 Model loading + + Run the \l{Loading a 3DS model with Qt/3D}{Penguin} example + to check that 3DS model loading basically works: + + \image penguin-screenshot.png + + If the model fails to appear, it is possible that the 3DS + plug-in has not been installed correctly or it could not + be located at runtime. It is recommended that you set the + \c{QT_DEBUG_PLUGINS} environment variable to 1 to get extra + information about why the plug-in could not be loaded. + + \section1 QML/3D + + Run the QML/3D version of the bouncing + \l{Teapot Example in QML/3D}{Teapot Example} using + "qmlviewer -opengl teapot-bounce.qml". The teapot should have a + shiny appearence (compared to the grey teapot above) and bounce + up and down: + + \image teapot-china-screenshot.png + + It should be possible to rotate the teapot using the mouse + and keyboard. + + Note that when running QML/3D examples on a device that both the + QML files and the model files must be copied to the device (the model + file is "teapot.bez" in the case of the bouncing teapot example). + + \section1 Object picking + + Run the QML/3D \l{Tea Service Demo in QML}{Tea Service} demo + with "qmlviewer -opengl teaservice.qml". Click on the teapot, teacups, + and teaspoons to make them jump up, and click on the teapot + spout and handle for other effects. This example tests object + picking and QML animations. + + \image teaservice-qml-screenshot.png + + Note: It may be necessary to adjust the width and height properties + in teaservice.qml to match the device's screen size. + + \section1 Build tests + + The Qt/3D code base contains a number of \c{#ifdef} statements + that may cause the build to fail in non-default Qt configurations + or when strict API options are enabled. It is recommended that + these configurations be verified periodically, particularly + prior to a release. + + \code + qmake opengl.pro \ + DEFINES+=QT_NO_DEBUG_STREAM \ + DEFINES+=QT_NO_DATASTREAM \ + DEFINES+=QT_NO_CAST_FROM_BYTEARRAY \ + DEFINES+=QT_NO_CAST_TO_ASCII \ + DEFINES+=QT_NO_CAST_FROM_ASCII + \endcode + + \l{index.html}{Return to the main Qt/3D page}. +*/ diff --git a/doc/src/classes.qdoc b/doc/src/classes.qdoc new file mode 100644 index 000000000..fe3a5b8f5 --- /dev/null +++ b/doc/src/classes.qdoc @@ -0,0 +1,101 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + + +/*! + \group classlists + \title Class and Function Documentation + \brief Lists and Indexes of classes, functions, and types. + + Links to indexes and lists for finding class and function + reference documentation. + + \section2 Class Lists + + \annotatedlist classlists + + \section2 Function Lists + + \annotatedlist funclists + +*/ + +/*! + \page classes.html + \title All Qt3D Classes + \ingroup classlists + + \brief If you know the name of the class you want, find it here. + + This is a list of all Qt/3d classes. + + \generatelist classes + +*/ + +/*! + \page annotated.html + \title Annotated Class List + \ingroup classlists + + \brief If you don't know the name of the class you want, but you + know what the class should do, you might try looking here. + + Qt3D API classes with brief descriptions: + + \generatelist annotatedclasses +*/ + + +/*! + \page hierarchy.html + + \title Inheritance Hierarchy + \ingroup classlists + + \brief The C++ class inheritance hierarchy for all classes in the + Qt/3d API. + + \generatelist classhierarchy +*/ + + + +/*! + \page functions.html + \title All Functions + \ingroup funclists + + \brief All documented Qt/3d functions listed alphabetically with a + link to where each one is declared. + + This is the list of all documented member functions and global + functions in the Qt/3d API. Each function has a link to the class or + header file where it is declared and documented. + + \generatelist functionindex +*/ diff --git a/doc/src/classic.css b/doc/src/classic.css new file mode 100644 index 000000000..59fa9dc32 --- /dev/null +++ b/doc/src/classic.css @@ -0,0 +1,284 @@ +BODY,H1,H2,H3,H4,H5,H6,P,CENTER,TD,TH,UL,DL,DIV { + font-family: Arial, Geneva, Helvetica, sans-serif; +} +H1 { + text-align: center; + font-size: 160%; +} +H2 { + font-size: 120%; +} +H3 { + font-size: 100%; +} + +h3.fn,span.fn +{ + background-color: #eee; + border-width: 1px; + border-style: solid; + border-color: #ddd; + font-weight: bold; + padding: 6px 0px 6px 10px; + margin: 42px 0px 0px 0px; +} + +hr { + border: 0; + color: #a0a0a0; + background-color: #ccc; + height: 1px; + width: 100%; + text-align: left; + margin: 34px 0px 34px 0px; +} + +table.valuelist { + border-width: 1px 1px 1px 1px; + border-style: solid; + border-color: #dddddd; + border-collapse: collapse; + background-color: #f0f0f0; +} + +table.indextable { + border-width: 1px 1px 1px 1px; + border-style: solid; + border-collapse: collapse; + background-color: #f0f0f0; + border-color:#555; + font-size: 100%; +} + +table td.largeindex { + border-width: 1px 1px 1px 1px; + border-collapse: collapse; + background-color: #f0f0f0; + border-color:#555; + font-size: 120%; +} + +table.valuelist th { + border-width: 1px 1px 1px 2px; + padding: 4px; + border-style: solid; + border-color: #666; + color:white; + background-color:#666; +} + +th.titleheader { + border-width: 1px 0px 1px 0px; + padding: 2px; + border-style: solid; + border-color: #666; + color:white; + background-color:#555; + background-image:url('images/gradient.png')}; + background-repeat: repeat-x; + font-size: 100%; +} + + +th.largeheader { + border-width: 1px 0px 1px 0px; + padding: 4px; + border-style: solid; + border-color: #444; + color:white; + background-color:#555555; + font-size: 120%; +} + +p { + + margin-left: 4px; + margin-top: 8px; + margin-bottom: 8px; +} + +a:link +{ + color: #0046ad; + text-decoration: none +} + +a:visited +{ + color: #672967; + text-decoration: none +} + +a.obsolete +{ + color: #661100; + text-decoration: none +} + +a.compat +{ + color: #661100; + text-decoration: none +} + +a.obsolete:visited +{ + color: #995500; + text-decoration: none +} + +a.compat:visited +{ + color: #995500; + text-decoration: none +} + +body +{ + background: #ffffff; + color: black +} + +table.generic, table.annotated +{ + border-width: 1px; + border-color:#bbb; + border-style:solid; + border-collapse:collapse; +} + +table td.memItemLeft { + width: 180px; + padding: 2px 0px 0px 8px; + margin: 4px; + border-width: 1px; + border-color: #E0E0E0; + border-style: none; + font-size: 100%; + white-space: nowrap +} + +table td.memItemRight { + padding: 2px 8px 0px 8px; + margin: 4px; + border-width: 1px; + border-color: #E0E0E0; + border-style: none; + font-size: 100%; +} + +table tr.odd { + background: #f0f0f0; + color: black; +} + +table tr.even { + background: #e4e4e4; + color: black; +} + +table.annotated th { + padding: 3px; + text-align: left +} + +table.annotated td { + padding: 3px; +} + +table tr pre +{ + padding-top: 0px; + padding-bottom: 0px; + padding-left: 0px; + padding-right: 0px; + border: none; + background: none +} + +tr.qt-style +{ + background: #96E066; + color: black +} + +body pre +{ + padding: 0.2em; + border: #e7e7e7 1px solid; + background: #f1f1f1; + color: black +} + +table tr.qt-code pre +{ + padding: 0.2em; + border: #e7e7e7 1px solid; + background: #f1f1f1; + color: black +} + +span.preprocessor, span.preprocessor a +{ + color: darkblue; +} + +span.comment +{ + color: darkred; + font-style: italic +} + +span.string,span.char +{ + color: darkgreen; +} + +.title +{ + text-align: center +} + +.subtitle +{ + font-size: 0.8em +} + +.small-subtitle +{ + font-size: 0.65em +} + +.qmlitem { + padding: 0; +} + +.qmlname { + white-space: nowrap; +} + +.qmltype { + text-align: center; + font-size: 160%; +} + +.qmlproto { + background-color: #eee; + border-width: 1px; + border-style: solid; + border-color: #ddd; + font-weight: bold; + padding: 6px 10px 6px 10px; + margin: 42px 0px 0px 0px; +} + +.qmlreadonly { + float: right; + color: red +} + +.qmldoc { +} + +*.qmlitem p { +} diff --git a/doc/src/demos/monkeygod.qdoc b/doc/src/demos/monkeygod.qdoc new file mode 100644 index 000000000..d8084159c --- /dev/null +++ b/doc/src/demos/monkeygod.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example declarative/monkeygod + \title Monkey God in QML + + The Monkey God demo in QML shows how QML/3D can be used to build + up complex 3D scenes including materials and animations. + + \image monkeygod-screenshot.png + + \l{qt3d-examples.html}{Return to Examples}. +*/ diff --git a/doc/src/demos/pageflip.qdoc b/doc/src/demos/pageflip.qdoc new file mode 100644 index 000000000..56e195ceb --- /dev/null +++ b/doc/src/demos/pageflip.qdoc @@ -0,0 +1,39 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example pageflip + \title Page Flip Demo + + The Page Flip demo shows how Qt/3D can be used to animate + flipping pages in a book. A shader program is used to combine a + gradient texture with the page textures to create a curl effect. + + \image pageflip-screenshot.png + + \l{qt3d-examples.html}{Return to Examples}. +*/ diff --git a/doc/src/demos/shapes.qdoc b/doc/src/demos/shapes.qdoc new file mode 100644 index 000000000..4c5190dcf --- /dev/null +++ b/doc/src/demos/shapes.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example shapes + \title Shapes Demo + + The Shapes demo shows many of the basic shapes that can be + drawn using Qt/3D. + + \image shapes-screenshot.png + + \l{qt3d-examples.html}{Return to Examples}. +*/ diff --git a/doc/src/demos/teaservice-qml.qdoc b/doc/src/demos/teaservice-qml.qdoc new file mode 100644 index 000000000..28cbfbf01 --- /dev/null +++ b/doc/src/demos/teaservice-qml.qdoc @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example declarative/teaservice + \title Tea Service Demo in QML + + The Tea Service demo in QML shows how QML/3D can be used to draw a complex + scene made up of several objects. It also demonstrates object picking, + animations, states and transitions. + + \image teaservice-qml-screenshot.png + + There is also a \l{Tea Service Demo}{C++ version} of this demo, + which is not as visually interesting as the QML/3D version. + It is much easier to implement interaction models and + animations in QML than in C++. + + \l{qt3d-examples.html}{Return to Examples}. +*/ diff --git a/doc/src/demos/teaservice.qdoc b/doc/src/demos/teaservice.qdoc new file mode 100644 index 000000000..d4da3464f --- /dev/null +++ b/doc/src/demos/teaservice.qdoc @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example teaservice + \title Tea Service Demo + + The Tea Service demo shows how Qt/3D can be used to draw a complex + scene made up of several objects. It also demonstrates object picking. + + \image teaservice-screenshot.png + + There is also a \l{Tea Service Demo in QML}{QML version} of the + Tea Service demo which has more advanced object picking, animations, + states, and transitions. It is much easier to add complex + interaction models and animations in QML than in C++. + + \l{qt3d-examples.html}{Return to Examples}. +*/ diff --git a/doc/src/examples/basket.qdoc b/doc/src/examples/basket.qdoc new file mode 100644 index 000000000..cf6381109 --- /dev/null +++ b/doc/src/examples/basket.qdoc @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example basket + \title Basket Example + + \section2 Basket in C++ + + The Basket example shows how Qt/3D can be used to draw an animated + object covered in a texture. The basic application shell is similar + to the \l{teapot}{Hello Teapot} example. In this case, we create + the basket object and add a texture to it as follows: + + \snippet basket/basketview.cpp 1 + + For this animation, we want to spin the basket around its Y axis, + once every 2 seconds. We first declare an \c angle property in the + class declaration (calling \c{update()} will force the view to + redraw whenever the angle changes): + + \snippet basket/basketview.h 1 + + Then we create a QPropertyAnimation object that will update + \c angle every time through the event loop with a new value + between 0 and 360 degrees: + + \snippet basket/basketview.cpp 2 + + Now all we have to do is draw the basket using the \c angle + property every time \c{paintGL()} is called: + + \snippet basket/basketview.cpp 3 + + \image basket-screenshot.png + + \section2 Basket in QML/3D + + The QML/3D version of the basket example is very similar in + structure to the C++ version above, but much simpler. + We start by defining a viewport with a specific camera position: + + \snippet declarative/basket.qml 1 + + We then add an \l Item3D object to load the basket model and + apply the desired texture to it: + + \snippet declarative/basket.qml 2 + + And then we apply an animation to the rotation component of + the item's transform property: + + \snippet declarative/basket.qml 3 + + \l{qt3d-examples.html}{Return to Examples}. +*/ diff --git a/doc/src/examples/nesting.qdoc b/doc/src/examples/nesting.qdoc new file mode 100644 index 000000000..c34e332fc --- /dev/null +++ b/doc/src/examples/nesting.qdoc @@ -0,0 +1,135 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example nesting + \title Drawing into framebuffer objects + + The Nesting example shows how Qt/3D can be used to draw into a + framebuffer object and then use the associated texture in + subsequent drawing operations. It is assumed that the reader + is already familar with the following examples: + + \list + \o \l{Teapot Example}{Hello Teapot} - drawing a basic object in 3D. + \o \l{Applying transformations and materials to objects}{Cube} - applying transformations and materials to objects. + \o \l{basket}{Basket} - animating objects in 3D. + \endlist + + In this example we are going to draw two rotating and transparent + cubes. One cube will display a simple texture as in the + \l{Applying transformations and materials to objects}{Cube} example, + and the other cube will display a nested scene containing a + rotating teapot. + + \image nesting-screenshot.png + + As with the other examples, we start by creating the geometric objects + we need in the constructor (we will share the cube geometry between + the two cubes we will be drawing): + + \snippet nesting/cubeview.cpp 1 + + We also need three QPropertyAnimation objects to drive our + animations; rotation angle for the teapot, rotation angle for + the cube; orbit angle of the two cubes around each other: + + \snippet nesting/cubeview.cpp 2 + + The final step in the constructor is to create a camera for + the nested scene we will be drawing into the framebuffer object. + This is in addition to the default QGLView::camera() object that + provides the camera for the main scene. + + \snippet nesting/cubeview.cpp 3 + + To draw the nested scene, we of course need a framebuffer object, + which we create in the \c{initializeGL()} method: + + \snippet nesting/cubeview.cpp 4 + + Note that we also set the framebuffer object on an instance of + QGLFramebufferObjectSurface. We will use this fact later when + we render the nested scene. + + For the other cube, we need a regular texture. And we'll also + turn on blending to make our cubes transparent: + + \snippet nesting/cubeview.cpp 5 + + Now it is time to paint the scene in \c{paintGL()}. The first + thing we want to do is draw the teapot into the framebuffer object. + To do that, we need to establish a nested drawing state: + + \snippet nesting/cubeview.cpp 6 + + In the code above, we first push the main scene's modelview and + projection matrices. And then we push a new drawing surface onto + the painter's surface stack. Everything we draw from now on will + be written to \c{fboSurface} and thus the framebuffer object. + To do that, we set the inner camera position, adjust the painter + state, clear the framebuffer object, and draw the teapot: + + \snippet nesting/cubeview.cpp 7 + + Now that the nested scene has been drawn to the framebuffer object, + we pop the surface and matrix stacks to return to the main scene: + + \snippet nesting/cubeview.cpp 8 + + Because our cubes are transparent, we need to make sure we draw + the objects in the scene from back to front. Otherwise the result + will not look correct. To do this, we check which of the cube + mid-points is furtherest away from the camera and draw that cube first + (the more negative the z value, the further away it is): + + \snippet nesting/cubeview.cpp 9 + + Drawing the first cube with the simple texture is very similar to + the \l{Applying transformations and materials to objects}{Cube} example: + + \snippet nesting/cubeview.cpp 10 + + The main interesting wrinkle is that we draw the cube twice, + once with front faces culled, and the second time with back + faces culled. This effectively causes the cube to be drawn + back to front for proper blending. + + The second cube is drawn in a similar way except that we bind + the framebuffer object's texture to the state instead of a static + texture: + + \snippet nesting/cubeview.cpp 11 + + Face culling is a simple way to draw transparent objects, but it + really only works on non-intersecting convex objects like our cubes. + For concave objects (like the teapot) or objects that intersect, + we would need to break the objects up into smaller convex pieces + and then order the pieces from back to front. + + \l{qt3d-examples.html}{Return to Examples}. +*/ diff --git a/doc/src/examples/painter.qdoc b/doc/src/examples/painter.qdoc new file mode 100644 index 000000000..91810df12 --- /dev/null +++ b/doc/src/examples/painter.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example painter + \title Painter Example + + The Painter example shows how Qt/3D can be used to draw basic + orthographic and perspective objects using QGLPainter. + + \image painter-screenshot.png + + \l{qt3d-examples.html}{Return to Examples}. +*/ diff --git a/doc/src/examples/teapot-qml.qdoc b/doc/src/examples/teapot-qml.qdoc new file mode 100644 index 000000000..0f8d0eaf2 --- /dev/null +++ b/doc/src/examples/teapot-qml.qdoc @@ -0,0 +1,73 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example tutorials/teapot-qml + \title Teapot Example in QML/3D + + This example shows to use QML/3D to display a teapot on + the screen. The QML is fairly simple: + + \snippet tutorials/teapot-qml/teapot.qml 1 + + \image teapot-qml-screenshot.png + + The example starts by importing the Qt and Qt/3D QML modules: + + \snippet tutorials/teapot-qml/teapot.qml 2 + + Then we create a viewport of size 640x480 to display the teapot: + + \snippet tutorials/teapot-qml/teapot.qml 3 + + And now we create a \l Item3D to display the teapot with a + default lit material effect: + + \snippet tutorials/teapot-qml/teapot.qml 4 + + The teapot data itself is loaded from \c{teapot.bez}, which contains + Bezier patch data that describes the geometry of the teapot. + + Let's make the teapot a little more interesting by adding a + material to simulate bone china: + + \snippet tutorials/teapot-qml/teapot-bounce.qml 1 + \snippet tutorials/teapot-qml/teapot-bounce.qml 2 + + \image teapot-china-screenshot.png + + To make the teapot even more interesting, we can cause it to + bounce up and down using a QML animation item: + + \snippet tutorials/teapot-qml/teapot-bounce.qml 3 + + This QML teapot example can be compared with the \l{teapot}{C++ version}. + Using QML is briefer than C++, and easier to modify to adjust + materials and add new features like animations. + + \l{qt3d-examples.html}{Return to Examples}. +*/ diff --git a/doc/src/examples/teapot.qdoc b/doc/src/examples/teapot.qdoc new file mode 100644 index 000000000..e4a889f44 --- /dev/null +++ b/doc/src/examples/teapot.qdoc @@ -0,0 +1,101 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example teapot + \title Teapot Example + + The Teapot example shows how Qt/3D can be used to draw a simple + teapot object with a perspective camera view in C++. There is + also a \l{Teapot Example in QML/3D}{QML/3D version} of the teapot + example. + + We start by defining a class that inherits from QGLView, which + provides some basic scene setup logic and 3D camera navigation: + + \snippet teapot/teapotview.h class-defn + \dots + \quotefromfile teapot/main.cpp + \skipuntil [main] + \printto [main-args] + \skipuntil [main-args-end] + \printto [main] + + When the application starts up, we set up some scene parameters + in the \c{initializeGL()} function: + + \quotefromfile teapot/teapotview.cpp + \skipuntil [initialize] + \printto [create-display-list] + + The first line of the function selects a standard rendering + effect that lights material colors with the default OpenGL + two-sided lighting algorithm and the default light. + + The \c{teapot} member variable is an instance of QGLSceneNode, + which we create using QGLBuilder during \c{initializeGL()}: + + \quotefromfile teapot/teapotview.cpp + \skipuntil [create-display-list] + \printto [initialize] + + The QGLTeapot class represents the geometry for the teapot, + which is added to the builder with the \c{<<} operator. + + We then call QGLBuilder::finalizedSceneNode() to finalize the + object, prepare it to be uploaded to the GL server as a + vertex buffer, and hand over ownership of the scene node. + + We have to take care to clean up our scene after we're done with it + and here that is done in the destructor: + + \snippet teapot/teapotview.cpp destructor + + Finally, we paint the teapot every time the window is refreshed: + + \snippet teapot/teapotview.cpp paint + + The QGLView class has in-built support for camera navigation + using the mouse and keyboard. By clicking and dragging the mouse, + the teapot can be rotated into any position. The image on the + left shows the view in its startup default position, and the + image on the right shows the view after rotation using the mouse: + + \raw HTML + <center><table><tr><td> + \endraw + \image teapot-screenshot.png + \raw HTML + </td><td> + \endraw + \image teapot-rotated.png + \raw HTML + </td></tr></table></center> + \endraw + + \l{qt3d-examples.html}{Return to Examples}. +*/ diff --git a/doc/src/images/REAME-ODF b/doc/src/images/REAME-ODF new file mode 100644 index 000000000..6d1a820b2 --- /dev/null +++ b/doc/src/images/REAME-ODF @@ -0,0 +1,5 @@ +The *.odf files here are OpenOffice formula files. + +To edit the formulas shown here as png's, open the corresponding odf file +with OpenOffices formula editor, edit, save, then export as PDF. The +PDF can be opened with gimp to create a PNG. diff --git a/doc/src/images/affine-transform.odf b/doc/src/images/affine-transform.odf Binary files differnew file mode 100644 index 000000000..4ead5ccae --- /dev/null +++ b/doc/src/images/affine-transform.odf diff --git a/doc/src/images/affine-transform.png b/doc/src/images/affine-transform.png Binary files differnew file mode 100644 index 000000000..c520623f0 --- /dev/null +++ b/doc/src/images/affine-transform.png diff --git a/doc/src/images/attenuation.odf b/doc/src/images/attenuation.odf Binary files differnew file mode 100644 index 000000000..a3c35333f --- /dev/null +++ b/doc/src/images/attenuation.odf diff --git a/doc/src/images/attenuation.png b/doc/src/images/attenuation.png Binary files differnew file mode 100644 index 000000000..fa64ebed9 --- /dev/null +++ b/doc/src/images/attenuation.png diff --git a/doc/src/images/basket-screenshot.png b/doc/src/images/basket-screenshot.png Binary files differnew file mode 100644 index 000000000..21d72a287 --- /dev/null +++ b/doc/src/images/basket-screenshot.png diff --git a/doc/src/images/cube-screenshot.png b/doc/src/images/cube-screenshot.png Binary files differnew file mode 100644 index 000000000..564646753 --- /dev/null +++ b/doc/src/images/cube-screenshot.png diff --git a/doc/src/images/cylinder-texture-coords.png b/doc/src/images/cylinder-texture-coords.png Binary files differnew file mode 100644 index 000000000..8ad69b43e --- /dev/null +++ b/doc/src/images/cylinder-texture-coords.png diff --git a/doc/src/images/faceted-q.png b/doc/src/images/faceted-q.png Binary files differnew file mode 100644 index 000000000..a809976bc --- /dev/null +++ b/doc/src/images/faceted-q.png diff --git a/doc/src/images/forest-screenshot.png b/doc/src/images/forest-screenshot.png Binary files differnew file mode 100644 index 000000000..9984d0bea --- /dev/null +++ b/doc/src/images/forest-screenshot.png diff --git a/doc/src/images/forest-screenshot2.png b/doc/src/images/forest-screenshot2.png Binary files differnew file mode 100644 index 000000000..3de77cfa8 --- /dev/null +++ b/doc/src/images/forest-screenshot2.png diff --git a/doc/src/images/forest-screenshot3.png b/doc/src/images/forest-screenshot3.png Binary files differnew file mode 100644 index 000000000..5589e2adf --- /dev/null +++ b/doc/src/images/forest-screenshot3.png diff --git a/doc/src/images/gradient.png b/doc/src/images/gradient.png Binary files differnew file mode 100644 index 000000000..2ef36edd0 --- /dev/null +++ b/doc/src/images/gradient.png diff --git a/doc/src/images/line-int-1.png b/doc/src/images/line-int-1.png Binary files differnew file mode 100644 index 000000000..74e9be24f --- /dev/null +++ b/doc/src/images/line-int-1.png diff --git a/doc/src/images/line-int-2.png b/doc/src/images/line-int-2.png Binary files differnew file mode 100644 index 000000000..9ca443740 --- /dev/null +++ b/doc/src/images/line-int-2.png diff --git a/doc/src/images/line-intersection.odf b/doc/src/images/line-intersection.odf Binary files differnew file mode 100644 index 000000000..4e0fe2d49 --- /dev/null +++ b/doc/src/images/line-intersection.odf diff --git a/doc/src/images/line-intersection.pdf b/doc/src/images/line-intersection.pdf Binary files differnew file mode 100644 index 000000000..cf9ef0b43 --- /dev/null +++ b/doc/src/images/line-intersection.pdf diff --git a/doc/src/images/line-intersection2.odf b/doc/src/images/line-intersection2.odf Binary files differnew file mode 100644 index 000000000..4e959aff6 --- /dev/null +++ b/doc/src/images/line-intersection2.odf diff --git a/doc/src/images/line-intersection2.pdf b/doc/src/images/line-intersection2.pdf Binary files differnew file mode 100644 index 000000000..bd624790b --- /dev/null +++ b/doc/src/images/line-intersection2.pdf diff --git a/doc/src/images/monkeygod-screenshot.png b/doc/src/images/monkeygod-screenshot.png Binary files differnew file mode 100644 index 000000000..de8a73d06 --- /dev/null +++ b/doc/src/images/monkeygod-screenshot.png diff --git a/doc/src/images/moon-screenshot.png b/doc/src/images/moon-screenshot.png Binary files differnew file mode 100644 index 000000000..cafeffff3 --- /dev/null +++ b/doc/src/images/moon-screenshot.png diff --git a/doc/src/images/mouse3dtest-screenshot.png b/doc/src/images/mouse3dtest-screenshot.png Binary files differnew file mode 100644 index 000000000..518a915e4 --- /dev/null +++ b/doc/src/images/mouse3dtest-screenshot.png diff --git a/doc/src/images/nesting-screenshot.png b/doc/src/images/nesting-screenshot.png Binary files differnew file mode 100644 index 000000000..9e60ddf1f --- /dev/null +++ b/doc/src/images/nesting-screenshot.png diff --git a/doc/src/images/normalized.odf b/doc/src/images/normalized.odf Binary files differnew file mode 100644 index 000000000..d75e70448 --- /dev/null +++ b/doc/src/images/normalized.odf diff --git a/doc/src/images/pageflip-screenshot.png b/doc/src/images/pageflip-screenshot.png Binary files differnew file mode 100644 index 000000000..2a081a217 --- /dev/null +++ b/doc/src/images/pageflip-screenshot.png diff --git a/doc/src/images/painter-screenshot.png b/doc/src/images/painter-screenshot.png Binary files differnew file mode 100644 index 000000000..e11a5a34f --- /dev/null +++ b/doc/src/images/painter-screenshot.png diff --git a/doc/src/images/penguin-0-screenshot.png b/doc/src/images/penguin-0-screenshot.png Binary files differnew file mode 100644 index 000000000..d65d590f0 --- /dev/null +++ b/doc/src/images/penguin-0-screenshot.png diff --git a/doc/src/images/penguin-screenshot.png b/doc/src/images/penguin-screenshot.png Binary files differnew file mode 100644 index 000000000..eb3349803 --- /dev/null +++ b/doc/src/images/penguin-screenshot.png diff --git a/doc/src/images/pvcolor.png b/doc/src/images/pvcolor.png Binary files differnew file mode 100644 index 000000000..380a19a3c --- /dev/null +++ b/doc/src/images/pvcolor.png diff --git a/doc/src/images/pyramid-screenshot.png b/doc/src/images/pyramid-screenshot.png Binary files differnew file mode 100644 index 000000000..6a585a6ce --- /dev/null +++ b/doc/src/images/pyramid-screenshot.png diff --git a/doc/src/images/qray3d-project.png b/doc/src/images/qray3d-project.png Binary files differnew file mode 100644 index 000000000..1288f204f --- /dev/null +++ b/doc/src/images/qray3d-project.png diff --git a/doc/src/images/qt-creator-config-3ds.png b/doc/src/images/qt-creator-config-3ds.png Binary files differnew file mode 100644 index 000000000..87ac89fd9 --- /dev/null +++ b/doc/src/images/qt-creator-config-3ds.png diff --git a/doc/src/images/qt-creator-lib-path.png b/doc/src/images/qt-creator-lib-path.png Binary files differnew file mode 100644 index 000000000..5f988437e --- /dev/null +++ b/doc/src/images/qt-creator-lib-path.png diff --git a/doc/src/images/qt-creator-plugins.png b/doc/src/images/qt-creator-plugins.png Binary files differnew file mode 100644 index 000000000..8b469ab02 --- /dev/null +++ b/doc/src/images/qt-creator-plugins.png diff --git a/doc/src/images/qt-creator-shadow-build.png b/doc/src/images/qt-creator-shadow-build.png Binary files differnew file mode 100644 index 000000000..9b231d5f4 --- /dev/null +++ b/doc/src/images/qt-creator-shadow-build.png diff --git a/doc/src/images/qt-logo.png b/doc/src/images/qt-logo.png Binary files differnew file mode 100644 index 000000000..14ddf2a02 --- /dev/null +++ b/doc/src/images/qt-logo.png diff --git a/doc/src/images/quad-extrude.png b/doc/src/images/quad-extrude.png Binary files differnew file mode 100644 index 000000000..c4b6ee445 --- /dev/null +++ b/doc/src/images/quad-extrude.png diff --git a/doc/src/images/quad-extrude.xcf b/doc/src/images/quad-extrude.xcf Binary files differnew file mode 100644 index 000000000..0d1650ac2 --- /dev/null +++ b/doc/src/images/quad-extrude.xcf diff --git a/doc/src/images/quads.png b/doc/src/images/quads.png Binary files differnew file mode 100644 index 000000000..28a030999 --- /dev/null +++ b/doc/src/images/quads.png diff --git a/doc/src/images/shapes-screenshot.png b/doc/src/images/shapes-screenshot.png Binary files differnew file mode 100644 index 000000000..ad0a0f433 --- /dev/null +++ b/doc/src/images/shapes-screenshot.png diff --git a/doc/src/images/soup.png b/doc/src/images/soup.png Binary files differnew file mode 100644 index 000000000..c84c07295 --- /dev/null +++ b/doc/src/images/soup.png diff --git a/doc/src/images/sphere-detail.png b/doc/src/images/sphere-detail.png Binary files differnew file mode 100644 index 000000000..90e40fb45 --- /dev/null +++ b/doc/src/images/sphere-detail.png diff --git a/doc/src/images/spiky-teapot.png b/doc/src/images/spiky-teapot.png Binary files differnew file mode 100644 index 000000000..2871d83e9 --- /dev/null +++ b/doc/src/images/spiky-teapot.png diff --git a/doc/src/images/stereo-nhd-screenshot.png b/doc/src/images/stereo-nhd-screenshot.png Binary files differnew file mode 100644 index 000000000..74df719e6 --- /dev/null +++ b/doc/src/images/stereo-nhd-screenshot.png diff --git a/doc/src/images/stereo-screenshot-qml.png b/doc/src/images/stereo-screenshot-qml.png Binary files differnew file mode 100644 index 000000000..d7e8f7a39 --- /dev/null +++ b/doc/src/images/stereo-screenshot-qml.png diff --git a/doc/src/images/stereo-screenshot-qml2.png b/doc/src/images/stereo-screenshot-qml2.png Binary files differnew file mode 100644 index 000000000..d91f959f3 --- /dev/null +++ b/doc/src/images/stereo-screenshot-qml2.png diff --git a/doc/src/images/stereo-screenshot.png b/doc/src/images/stereo-screenshot.png Binary files differnew file mode 100644 index 000000000..020fcb683 --- /dev/null +++ b/doc/src/images/stereo-screenshot.png diff --git a/doc/src/images/stereo-wide-screenshot.png b/doc/src/images/stereo-wide-screenshot.png Binary files differnew file mode 100644 index 000000000..f9e165a66 --- /dev/null +++ b/doc/src/images/stereo-wide-screenshot.png diff --git a/doc/src/images/teapot-china-screenshot.png b/doc/src/images/teapot-china-screenshot.png Binary files differnew file mode 100644 index 000000000..d38602fcc --- /dev/null +++ b/doc/src/images/teapot-china-screenshot.png diff --git a/doc/src/images/teapot-distortion.png b/doc/src/images/teapot-distortion.png Binary files differnew file mode 100644 index 000000000..76b4a3db7 --- /dev/null +++ b/doc/src/images/teapot-distortion.png diff --git a/doc/src/images/teapot-distortion2.png b/doc/src/images/teapot-distortion2.png Binary files differnew file mode 100644 index 000000000..573503bdc --- /dev/null +++ b/doc/src/images/teapot-distortion2.png diff --git a/doc/src/images/teapot-logo.png b/doc/src/images/teapot-logo.png Binary files differnew file mode 100644 index 000000000..a82c33c1a --- /dev/null +++ b/doc/src/images/teapot-logo.png diff --git a/doc/src/images/teapot-qml-screenshot.png b/doc/src/images/teapot-qml-screenshot.png Binary files differnew file mode 100644 index 000000000..cb9dea919 --- /dev/null +++ b/doc/src/images/teapot-qml-screenshot.png diff --git a/doc/src/images/teapot-qt-screenshot.png b/doc/src/images/teapot-qt-screenshot.png Binary files differnew file mode 100644 index 000000000..2a5c2ead9 --- /dev/null +++ b/doc/src/images/teapot-qt-screenshot.png diff --git a/doc/src/images/teapot-rotated.png b/doc/src/images/teapot-rotated.png Binary files differnew file mode 100644 index 000000000..f66a93efd --- /dev/null +++ b/doc/src/images/teapot-rotated.png diff --git a/doc/src/images/teapot-screenshot.png b/doc/src/images/teapot-screenshot.png Binary files differnew file mode 100644 index 000000000..07922e9e9 --- /dev/null +++ b/doc/src/images/teapot-screenshot.png diff --git a/doc/src/images/teaservice-qml-screenshot.png b/doc/src/images/teaservice-qml-screenshot.png Binary files differnew file mode 100644 index 000000000..ee2b935a1 --- /dev/null +++ b/doc/src/images/teaservice-qml-screenshot.png diff --git a/doc/src/images/teaservice-screenshot.png b/doc/src/images/teaservice-screenshot.png Binary files differnew file mode 100644 index 000000000..35e6fc8ee --- /dev/null +++ b/doc/src/images/teaservice-screenshot.png diff --git a/doc/src/images/texture-coords-gen.png b/doc/src/images/texture-coords-gen.png Binary files differnew file mode 100644 index 000000000..5f155b1a2 --- /dev/null +++ b/doc/src/images/texture-coords-gen.png diff --git a/doc/src/images/texture-coords-gen.xcf b/doc/src/images/texture-coords-gen.xcf Binary files differnew file mode 100644 index 000000000..b6540bb41 --- /dev/null +++ b/doc/src/images/texture-coords-gen.xcf diff --git a/doc/src/images/texture-seam.png b/doc/src/images/texture-seam.png Binary files differnew file mode 100644 index 000000000..2cd97233b --- /dev/null +++ b/doc/src/images/texture-seam.png diff --git a/doc/src/images/triangle3d-center.png b/doc/src/images/triangle3d-center.png Binary files differnew file mode 100644 index 000000000..da6fabb03 --- /dev/null +++ b/doc/src/images/triangle3d-center.png diff --git a/doc/src/images/triangle3d-dimensions.png b/doc/src/images/triangle3d-dimensions.png Binary files differnew file mode 100644 index 000000000..5efe28ec2 --- /dev/null +++ b/doc/src/images/triangle3d-dimensions.png diff --git a/doc/src/images/triangle3d.xcf b/doc/src/images/triangle3d.xcf Binary files differnew file mode 100644 index 000000000..798fafd29 --- /dev/null +++ b/doc/src/images/triangle3d.xcf diff --git a/doc/src/images/triangulated-face.png b/doc/src/images/triangulated-face.png Binary files differnew file mode 100644 index 000000000..fab481265 --- /dev/null +++ b/doc/src/images/triangulated-face.png diff --git a/doc/src/images/triangulated-face.xcf b/doc/src/images/triangulated-face.xcf Binary files differnew file mode 100644 index 000000000..74b08edf1 --- /dev/null +++ b/doc/src/images/triangulated-face.xcf diff --git a/doc/src/images/tutorials/converting-screenshot.png b/doc/src/images/tutorials/converting-screenshot.png Binary files differnew file mode 100644 index 000000000..9fb738ff4 --- /dev/null +++ b/doc/src/images/tutorials/converting-screenshot.png diff --git a/doc/src/images/tutorials/cube1-screenshot.png b/doc/src/images/tutorials/cube1-screenshot.png Binary files differnew file mode 100644 index 000000000..a0da12f07 --- /dev/null +++ b/doc/src/images/tutorials/cube1-screenshot.png diff --git a/doc/src/images/tutorials/cube2-screenshot.png b/doc/src/images/tutorials/cube2-screenshot.png Binary files differnew file mode 100644 index 000000000..20e05d1b3 --- /dev/null +++ b/doc/src/images/tutorials/cube2-screenshot.png diff --git a/doc/src/images/tutorials/cube3-screenshot.png b/doc/src/images/tutorials/cube3-screenshot.png Binary files differnew file mode 100644 index 000000000..49cf8cbcd --- /dev/null +++ b/doc/src/images/tutorials/cube3-screenshot.png diff --git a/doc/src/images/tutorials/cube4-screenshot.png b/doc/src/images/tutorials/cube4-screenshot.png Binary files differnew file mode 100644 index 000000000..4f71452db --- /dev/null +++ b/doc/src/images/tutorials/cube4-screenshot.png diff --git a/doc/src/images/tutorials/shader-tutorial-varying.png b/doc/src/images/tutorials/shader-tutorial-varying.png Binary files differnew file mode 100644 index 000000000..6e0c78e91 --- /dev/null +++ b/doc/src/images/tutorials/shader-tutorial-varying.png diff --git a/doc/src/images/tutorials/shader-tutorial.png b/doc/src/images/tutorials/shader-tutorial.png Binary files differnew file mode 100644 index 000000000..97db13d32 --- /dev/null +++ b/doc/src/images/tutorials/shader-tutorial.png diff --git a/doc/src/images/vector-mag.odf b/doc/src/images/vector-mag.odf Binary files differnew file mode 100644 index 000000000..96222af07 --- /dev/null +++ b/doc/src/images/vector-mag.odf diff --git a/doc/src/images/vector-mag.png b/doc/src/images/vector-mag.png Binary files differnew file mode 100644 index 000000000..0d913ee69 --- /dev/null +++ b/doc/src/images/vector-mag.png diff --git a/doc/src/images/vector-normalized.png b/doc/src/images/vector-normalized.png Binary files differnew file mode 100644 index 000000000..c1c4b968d --- /dev/null +++ b/doc/src/images/vector-normalized.png diff --git a/doc/src/images/vector-point.odf b/doc/src/images/vector-point.odf Binary files differnew file mode 100644 index 000000000..6b73097c3 --- /dev/null +++ b/doc/src/images/vector-point.odf diff --git a/doc/src/images/vector-point.png b/doc/src/images/vector-point.png Binary files differnew file mode 100644 index 000000000..c78410fd0 --- /dev/null +++ b/doc/src/images/vector-point.png diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc new file mode 100644 index 000000000..d9d6ded93 --- /dev/null +++ b/doc/src/index.qdoc @@ -0,0 +1,102 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \page index.html + \title Quick3D Reference Documentation + \keyword Quick3D Reference Documentation + + Quick3D adds 3D content to Qt Quick's cross-platform ability and coding power. + Developers of fluid user interfaces can now enhance their applications with 3D + content in the same way icons and pixmaps would be used in a 2D application. + + OpenGL hardware was designed for 3D acceleration and Quick3D allows applications + to utilise that 3D hardware fully. + + Quick3D is the Qt Quick product for scripting 3D applications in QML. Apps can be + 2D QML applications with a small amount of simple 3D content; through to complex + 3D scenes, containing 3D assets - such as complex 3D models, and shader effects. + + In Quick3D scripts are written in QML, and rendered with the power of Qt & C++. + + Quick3D is a product resulting from the Qt3D project. Qt3D is a set of powerful + cross-platform C++ API's for 3D programming using OpenGL. Qt3D may be used to + extend Quick3D by creating new user-defined 3D items using C++. + + Qt3D research continues and if the features you're looking for are not in Quick3D + yet you may find them in the \l{http://doc.qt.nokia.com/qt3d-snapshot/index.html}{Qt3D research project}. + + See the \l{Tutorials and Examples} for an introduction to using Quick3D and Qt3D. + + \raw HTML + <table cellpadding="2" cellspacing="1" border="0" width="100%" class="indextable"> + <tr> + <th class="titleheader" width="33%"> + Getting Started + </th> + <th class="titleheader" width="33%"> + Functionality Areas + </th> + <th class="titleheader" width="33%"> + API Reference + </th> + </tr> + <tr> + <td valign="top"> + <ul> + <li><a href="qt3d-building.html">Building</a></li> + <li><a href="qt3d-examples.html">Tutorials and Examples</a></li> + <li><a href="sceneformats-obj.html">Scene format plug-ins</a></li> + <li><a href="qt3d-contrib.html">Contributing</a></li> + <li><a href="qt3d-acceptance.html">Acceptance tests</a></li> + </ul> + </td> + <td valign="top"> + <ul> + <li><a href="qt3d-arrays.html">Arrays and Vertex Buffers</a></li> + <li><a href="qt3d-geometry.html">Geometry Building</a></li> + <li><a href="qt3d-graphicsview.html">Graphics View Integration</a></li> + <li><a href="qt3d-materials.html">Materials</a></li> + <li><a href="qt3d-math.html">Mathematical Primitives</a></li> + <li><a href="qt3d-painting.html">Painting in 3D</a></li> + <li><a href="qt3d-scene.html">Scene Management</a></li> + <li><a href="qt3d-textures.html">Texture Management</a></li> + <li><a href="qt3d-viewing.html">Viewing Widgets</a></li> + </ul> + </td> + <td valign="top"> + <ul> + <li><a href="qt3d-all-classes.html">All Classes</a></li> + <li><a href="qgl.html">QGL Namespace</a></li> + <li><a href="qt3d-qml3d.html">Quick3D Elements</a></li> + <li><a href="qt3d-qml3d-shapes.html">QML/3D Stock Shapes</a></li> + </ul> + </td> + </tr> + </table> + \endraw +*/ diff --git a/doc/src/qline3d-math.qdoc b/doc/src/qline3d-math.qdoc new file mode 100644 index 000000000..0a21580ce --- /dev/null +++ b/doc/src/qline3d-math.qdoc @@ -0,0 +1,211 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \ingroup qt3d + \ingroup qt3d::math + \since 4.8 + \title 3D Math Basis + \page qt3d-math-basis.html + \keyword 3D Math Basis + \brief Math foundations for the Qt3D math classes. + + The math classes provide basic operations in 3-space useful for graphics: + \list + \o QLine3D + \o QLineSegment3D + \o QPlane3D + \o QTriangle3D + \o QBox3D + \endlist + + This is a basic discussion of the mathematics behind these classes. + + \section1 Vectors and Points + + There are two important building blocks in 3D: the \bold vector and the + \bold point in cartesian 3-space. + + Both are comprised by 3 values in \bold R, the real numbers. + + So programatically in Qt both vectors and points are stored in a QVector3D instance, + since that class can store 3 qreal values. + + But there are important differences between points and vectors: + \list + \o a point \bold P is a 3D \i location, and makes sense in terms of a 3D cartesian + coordinate system. A real-world example is a map-location given in terms + of a map cross-reference. The location has no inherent magnitude, unless you + provide another location and find the distance between the two. + \o a vector \bold v is a 3D \i direction and magnitude. It makes no sense to talk + about a vector being located somewhere. A vector can represent for example + some directions like "go 3 north-west 3 kilometers", but this can be done from + \bold {anywhere on the map} - it is not anchored like the point is. + \endlist + + In 3D math points and vectors are represented by column vectors: + + \image vector-point.png + + In normal text where the over-arrow symbol is not available the vector is just a + bolded lower-case letter. A point is a capital letter, non-bolded. + + The fourth element in the column vectors above, w = 1 for points and w = 0 for vectors + means that vectors are not altered by certain affine transformations such + as \c{translate()}. + + \image affine-transform.png + + This affine transform T comprises a rotation and a translation. Remember that applying + the transform is done by the + \l{http://www.intmath.com/Matrices-determinants/4_Multiplying-matrices.php}{matrix multiplication} + \c{P * T = P'}. + + Notice how the 1 in the column for the translation multiplies out to zero against + the vectors last 0 value, so the vector is "immune" to the translation. + + In the case of the point the w = 1 "triggers" the translation values in the matrix. + + So the take away principle is that points and vectors, while represented by the same + data structure are different and behave differently in 3D math. + + \section2 Vector Magnitude and Normal Vectors + + Another important difference between points and vectors is that a vector has a magnitude, + whereas a point does not. + + Consider the vector v = (v0, v1, v2) to be rooted at + the origin O = (0, 0, 0) and pointing to the point P = (v0, v1, v2), then + its magnitude is the length of the line O to P. Magnitude is represented by + vertical bars and is found by this formula: + + \image vector-mag.png + + Unit vectors are those with a magnitude of exactly 1. The math notation is a "hat" + (or circumflex) over the bolded vector symbol. + + A unit vector parallel to one of the axes is easy to form without any division: + \raw HTML + <center><b>î</b> = (1, 0, 0)</center> + \endraw + + More typically such a vector is found by dividing by its own length: + + \image vector-normalized.png + + Vectors used for 3D normals are usually normalized to unit length. Confusingly + enough, since that is two different uses of the word "normal". + + A \i normal is simply a vector perpendicular to something. For example a plane normal is + perpendicular to the plane. + + Typically a normal vector is unit length, for convenience in 3D applications (but + there is nothing mathematically to say a normal vector has to be unit length). + + A vertex normal is perpendicular to the surface modelled by the vertex, and is used + in lighting calculations. + + \section1 Reviewing Operations on Vectors + + The QVector3D class provides two very useful functions - the vector dot-product and the + vector cross-product. Here's a quick review of their uses: + \list + \o QVector3D::crossProduct(const QVector3D &, const QVector3D &) + \list + \o The cross-product of two vectors produces a \i vector as a result and is + written \bold w = \bold u x \bold v. The result \bold w is perpendicular to both + \bold u and \bold v. Consider a plane N containing point P, with the tails of \bold u + and \bold v at P, and both lying in N, then \bold u x \bold v is a normal to N. + \endlist + \o QVector3D::dotProduct(const QVector3D &, const QVector3D &) + \list + \o The dot-product of two vectors produces a \i scalar as a result and is written + \c{t = \bold u . \bold v}. The result t = |u| |v| cos(A), where A is the angle + between u and v. When \bold u and \bold v have magnitude 1, they are called + unit vectors, and \bold u . \bold v = cos(A). + \endlist + \endlist + + A vector has the following operations defined on it in 3-space + \list + \o multiplication by a scalar, eg v' = s * \bold v + \o addition with another vector, eg \bold u = \bold v + \bold w + \endlist + + Multiplying and dividing by vectors is not defined - these operations make no sense in + 3-D space. + + Although you cannot add a vector to a point as such, you can consider the vector from the + origin to the point, and add the vector to that. Thus rather than out-lawing adding a + vector to a point it is simply defined as such. This allows the convenient notation for + lines and planes introduced in the next section. + + \section1 Representing Lines and Planes + + The QLine3D is represented by a point and a vector: the point anchors the line in + cartesian 3-space; and the vector is the direction the line is oriented in through that + point. The line is infinite. + + The QPlane3D is represented also by a point and a vector. Again the point anchors the line + in cartesian 3-space; but the vector this time is a normal to the plane. The plane is + infinite. + + This representation turns out to make many types of calculations required for 3D graphics + very straight forward. + + For example to find if a point P lies on a plane take the vector \bold p from the point to + the planes origin, and find the dot-product with the planes normal \bold n. + + If \bold {p . n} is zero, then \bold p is perpendicular to \bold n, and P is on the plane. + + \target vector-and-point-arithmetic + \section1 Vector and Point Arithmetic + + Slightly more complex arithmetic with the components of QLine3D and QPlane3D is possible, + with some care about what operations can be performed. + + As an example look at the implementation for QLine3D::intersection(const QLine3D &) : the + two lines are defined as: + + \image line-int-1.png + + If the two lines intersect then P(t) == Q(s) and for some ordered pair \bold s, \bold t + is a solution to the equations for both lines. + + The aim is to solve for \bold s and \bold t. + + The equations can be rearranged algebraically as shown in the last line above. + + But since dividing by a vector is not defined, tempting options such as dividing by \bold v + to solve for t are not possible. In the implementation the next step is breaking the points + and vectors down into their x, y and z components giving 3 simultaneous equations: + + \image line-int-2.png + + This can be readily solved using gaussian elimination to get a solution for s, and + substituting back gives t. +*/ diff --git a/doc/src/qt3d-all-classes.qdoc b/doc/src/qt3d-all-classes.qdoc new file mode 100644 index 000000000..864614a40 --- /dev/null +++ b/doc/src/qt3d-all-classes.qdoc @@ -0,0 +1,41 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \page qt3d-all-classes.html + \title Qt/3D Classes + \keyword Qt/3D Classes + + \generatelist classes +*/ + +/*! + \group qt3d + \title Qt/3D Classes + + \generatelist{related} +*/ diff --git a/doc/src/qt3d-arrays.qdoc b/doc/src/qt3d-arrays.qdoc new file mode 100644 index 000000000..c5ad77056 --- /dev/null +++ b/doc/src/qt3d-arrays.qdoc @@ -0,0 +1,34 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \group qt3d::arrays + \title Qt/3D Arrays and Vertex Buffers + \keyword Vertex Buffer + + \generatelist{related} +*/ diff --git a/doc/src/qt3d-building.qdoc b/doc/src/qt3d-building.qdoc new file mode 100644 index 000000000..9cf5ffd09 --- /dev/null +++ b/doc/src/qt3d-building.qdoc @@ -0,0 +1,252 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \page qt3d-building.html + \title Building Qt/3D + \keyword Building Qt/3D + + \section1 Obtaining Qt/3D sources + + The source for Qt/3D is hosted on Gitorious as the git repository + \l{http://qt.gitorious.org/qt-labs/qt3d}{\c{qt-labs/qt3d.git}}. + It can be cloned as follows: + + \code + $ mkdir -p $HOME/depot/qt-labs + $ cd $HOME/depot/qt-labs + $ git clone git://gitorious.org/qt-labs/qt3d.git + \endcode + + Once Qt/3D becomes a part of Qt it will be available with Qt binary packages. Until + then it must be built from sources. + + \section1 Obtaining and building Qt sources for Qt/3D + + \bold{Important: A Qt build, compiled from source is required for Qt/3D}. + + This is because Qt/3D requires access to source files that do not ship + with an SDK. Until Qt/3D becomes a regular part of Qt, either download an official + Qt 4.7 source package (\l{http://get.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.7.1.tar.gz}{tar.gz}, \l{http://get.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.7.1.zip}{zip}), + or a source tarball from our + \l{http://qt.gitorious.org/qt/qt/}{gitorious repository}. + + Configure your Qt 4.7 source tree with the \c{-opengl} option. An example: + \code + mkdir $HOME/build/qt + cd $HOME/build/qt + tar zxf qt-everywhere-opensource-src-4.7.1.tar.gz + ln -s qt* 4.7 + cd qt* + ./configure -opengl + make + \endcode + + The \c{-developer-build} option is recommended to get debug support, + and to ensure that your version of Qt is used and not the system + version of Qt. + + On Windows refer to the + \l{http://doc.qt.nokia.com/4.7/install-win.html}{build documentation} + (but do not use the \c{-opengl} command line option). + + \section1 Obtaining Qt Declarative UI for Qt/3D with QML bindings + + Qt/3D has experimental integration with + \l{http://labs.trolltech.com/page/Projects/Graphics/Kinetic/DeclarativeUI}{Declarative UI} + via QML bindings. To experiment with these bindings, ensure you have a source tarball + \l{http://qt.gitorious.org/qt/kinetic/}{from our Qt Declarative UI repository} + and build as appropriate for your platform. + + Then simply build Qt/3D as described below using the qmake from the Declarative UI + build tree. Once Qt/3D is build you can experiment with the examples in the + \c{examples/declarative} directory. + + \section1 Building Qt/3D + + Assuming that you have built Qt 4.7 in + \c{$HOME/build/qt/4.7}, you would configure and build Qt/3D as follows: + + \code + $ mkdir -p $HOME/build/qt-labs/qt3d + $ cd $HOME/build/qt-labs/qt3d + $ $HOME/build/qt/4.7/bin/qmake $HOME/depot/qt-labs/qt3d/opengl.pro + $ make + $ make install + $ export LD_LIBRARY_PATH=$PWD/lib:$LD_LIBRARY_PATH + \endcode + + The last line exports the library path so that you can run applications + from Qt/3D, and is needed so those applications can find the Qt/3D libraries. + + The "\c{make install}" step is required to make plug-ins work, + particularly the model loading and QML/3D plug-ins. + + On Windows (with Visual Studio) those commands look like this: + + \code + mkdir \build\qt-labs\qt3d + cd \build\qt-labs\qt3d + \build\qt\4.7\bin\qmake \depot\qt-labs\qt3d\opengl.pro + nmake + set PATH=%PATH%;\build\qt-labs\qt3d\bin + \endcode + + On Symbian (with RVCT) those commands look like this: + + \code + cd C:\depot\qt-labs\qt3d + qmake CONFIG+=old_importer + sbs -c armv5_urel + cd devices\symbian + createpackage Qt3D_template.pkg release-armv5 + runonphone --sis Qt3D.sis + \endcode + + Once you have built Qt/3D, you can run the "teapot" example to test + it as follows (ensure you've exported the library path as above): + + \code + $ cd $HOME/build/qt-labs/qt3d + $ bin/teapot + \endcode + + If all goes well, you should see something like the following + on the screen: + + \image teapot-screenshot.png + + Qt/3D has been tested with Qt/X11 and Qt/Embedded under Linux, on MacOSX + and Windows XP. Patches for other platforms are welcome. + + \section1 Installing plugins + + Qt/3D has support for loading 3D model files. This is enabled via + plugins for the various formats. + + 3DS files are supported using the open source + \l{http://lib3ds.org}{lib3ds} library. A copy of version 1.3 of this + library is included with the Qt/3D sources under the \c{3rdparty} + directory. + + If you already have lib3ds installed on your system and you wish to use + that instead of the version included with Qt/3D, you can pass the + \c{system_3ds} option to qmake: + + \code + $ $HOME/build/qt/4.7/bin/qmake $HOME/depot/qt-labs/qt3d/opengl.pro CONFIG+=system_3ds + $ make + $ make install + \endcode + + The last step above will install the plugins into Qt's plugin + directory so that the Qt plugin loader can find them at run-time. + + Note that the imageformats plugins include a rudimentary read-only TGA + format reader which is required for many model files that use TGA for + textures. If you know for sure that your model files don't use TGA + then this step can be skipped. + + See the instructions in \c{plugins/sceneformats/3ds/README.txt} for + more information on using the system lib3ds. + + \section1 Building Qt/3D Using QtCreator + + Here is a step-by-step guide to building Qt/3D using the + \l{http://qt.nokia.com/products/appdev/developer-tools/developer-tools}{QtCreator IDE}. + Read and refer to the above command line section for the full details + of building Qt/3D. + + \bold{Step 1} - Open the Qt/3D project. + + Choose \c{Open} from the \c{File} menu and navigate to the qt3d project + file \c {$HOME/depot/qt-labs/qt3d/opengl.pro}. Click \c{Open}. + + \bold{Step 2} - Select Qt, and specify a build directory. + + Now the Qt/3D project is displayed in the \c{Project} listing. Click the + \c{Projects} button on the left-hand side of the screen, and under the + \c{Build Settings} tab, choose \c{General} from the \c{Debug} category. + Set the Qt build to use, making sure it has OpenGL enabled. Also + specify a build directory, and check the "Shadow Build" box. + + \image qt-creator-shadow-build.png + + Note these screen shots apply to QtCreator v1.3 (beta) on MacOSX, but similar + functionality is available in later QtCreator versions, even if the + screen appears different. + + \bold{Step 3} - Add the system_3ds switch to qmake + + Only do this step if you have lib3ds installed on your system, as + described above, and you want to use the system lib3ds instead of + the one included with Qt/3D. + + Do this in QtCreator from the \c{Projects} mode, under the + \c{Build Steps} category. Add \c{CONFIG+=system_3ds} to the "Additional arguments" + for the "QMake build configuration". + + \image qt-creator-config-3ds.png + + \bold{Step 4} - Add Qt/3D libraries to the path + + As shown above you'll need to specify the Qt/3D libraries so that they can + be found. Do this in QtCreator from the \c{Projects} mode, under the + \c{Build Environment} category. This will also propagate to the + \c{Run Environment}. On MacOSX the name of the environment variable is + \c{DYLD_LIBRARY_PATH}, on Linux it is \c{LD_LIBRARY_PATH}. On Windows, + you'll need to add the \c{bin} directory to the \c{PATH} variable. + + \image qt-creator-lib-path.png + + \bold{Step 5} - Specify the plugin install + + Only do this step if you want to use the Qt/3D model loading plugins, + as described above. + + Do this in QtCreator from the \c{Projects} mode, under the + \c{Build Steps} category. Use the + drop-down under the steps list-box + to add a \c{Custom Process Step}, and move it below \c{QMake} and \c{Make}. + Set the name appropriately, set the command to \c{/usr/bin/make} and + the arguments to \c{-C plugins install}. Note that the + name you set may not display in the list box until you restart QtCreator. + + \image qt-creator-plugins.png + + In Windows set the command to the full path to your make program, eg: + \c{C:\Program Files\Microsoft Visual Studio 9.0\VC\bin\nmake} and set + the "Working Directory" to the imageformats directory: eg + \c{C:\build\qt-labs\qt3d\plugins\imageformats}. The "Command Arguments" + are now simply \c{install}. + + \bold{Step 6} - Build Qt/3D + + Click the "Build All" button now to build Qt/3D. + + \l{index.html}{Return to the main Qt/3D page} or + \l{qt3d-examples.html}{Continue to the Tutorials and Examples}. +*/ diff --git a/doc/src/qt3d-contrib.qdoc b/doc/src/qt3d-contrib.qdoc new file mode 100644 index 000000000..7f297fbfd --- /dev/null +++ b/doc/src/qt3d-contrib.qdoc @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \page qt3d-contrib.html + \title Contributing to Qt/3D + \keyword Contributing to Qt/3D + + Qt/3D is being developed primarily in the Brisbane office of Qt + Development Frameworks, but anyone is welcome to join the effort with + patches, new examples, and major feature development. + + Contact Rhys Weatherley in the Brisbane office for more information + on how you can contribute to Qt/3D. + + Because Qt/3D may eventually become part of Qt, all contributions + need to conform with the + \l{http://qt.gitorious.org/qt/pages/QtContributionGuidelines}{Qt Contribution Model Guidelines}. + + The source for Qt/3D is hosted on Gitorious at + \l{http://qt.gitorious.org/qt-labs/qt3d}. + + Bugs can be reported against the "Qt3D" component of the "Qt" project + at \l{http://bugreports.qt.nokia.com/}. + + The Qt/3D project has an open mailing list, which can be subscribed + to at \l{http://lists.trolltech.com/mailman/listinfo/qt-3d}. + + \l{index.html}{Return to the main Qt/3D page}. +*/ diff --git a/doc/src/qt3d-examples.qdoc b/doc/src/qt3d-examples.qdoc new file mode 100644 index 000000000..6358e8dad --- /dev/null +++ b/doc/src/qt3d-examples.qdoc @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \page qt3d-examples.html + \title Qt3D Tutorials and Examples + \keyword Qt3D Examples + + Using C++ to build applications with Qt/3D: + + \list + \o \l{Teapot Example}{Hello Teapot} - drawing a basic object in 3D. + \o \l{Applying transformations and materials to objects}{Cube} - applying transformations and materials to objects. + \o \l{basket}{Basket} - animating objects in 3D. + \o \l{nesting}{Nesting} - drawing into framebuffer objects. + \o \l{Loading a 3DS model with Qt/3D}{Penguin} - loading a 3DS model with Qt/3D. + \o \l{painter}{Painter} - basic painting operations using QGLPainter. + \o \l{stereo}{Stereo} - using stereoscopic displays. + \o \l{pvcolor}{Per-vertex Color} - building models with QGLBuilder + that have per-vertex color values. + \o \l{pageflip}{Page Flip} - using shaders to combine textures. + \o \l{shapes}{Shapes} - paints all of the basic OpenGL shapes. + \o \l{teaservice}{Tea Service} - complex scenes and object picking. + \endlist + + Using QML to build applications with Qt/3D: + + \list + \o \l{Teapot Example in QML/3D}{Hello Teapot} in QML/3D + \o \l{basket#Basket in QML/3D}{Basket} in QML/3D + \o \l{Applying transformations and materials to objects#Cube in QML/3D}{Cube} in QML/3D + \o \l{QML Stereo Viewing Example}{Stereo} - using stereoscopic displays in QML, and mixing 2D and 3D content. + \o \l{Monkey God in QML}{Monkey God} in QML/3D + \o \l{Tea Service Demo in QML}{Tea Service} in QML/3D + \o \l{Forest Example}{Forest} - creating billboard objects. + \o \l{Using GLSL shaders in QML/3D} + \endlist + + Other topics: + + \list + \o \l{Converting raw GL applications to use QGLPainter} + \o \l{Writing a scene format plug-in for Qt/3D} + \endlist + + \l{index.html}{Return to the main Qt/3D page}. +*/ diff --git a/doc/src/qt3d-geometry.qdoc b/doc/src/qt3d-geometry.qdoc new file mode 100644 index 000000000..ab7b2dddf --- /dev/null +++ b/doc/src/qt3d-geometry.qdoc @@ -0,0 +1,34 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\group qt3d::geometry +\title Qt/3D Geometry +\keyword Qt/3D Geometry + +\generatelist{related} +*/ diff --git a/doc/src/qt3d-graphicsview.qdoc b/doc/src/qt3d-graphicsview.qdoc new file mode 100644 index 000000000..a696f7eb0 --- /dev/null +++ b/doc/src/qt3d-graphicsview.qdoc @@ -0,0 +1,34 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \group qt3d::graphicsview + \title Qt/3D Graphics View Integration + \keyword Qt/3D Graphics View Integration + + \generatelist{related} +*/ diff --git a/doc/src/qt3d-materials.qdoc b/doc/src/qt3d-materials.qdoc new file mode 100644 index 000000000..203b4e18a --- /dev/null +++ b/doc/src/qt3d-materials.qdoc @@ -0,0 +1,34 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\group qt3d::materials +\title Qt/3D Materials +\keyword Qt/3D Materials + +\generatelist{related} +*/ diff --git a/doc/src/qt3d-math.qdoc b/doc/src/qt3d-math.qdoc new file mode 100644 index 000000000..bc424903a --- /dev/null +++ b/doc/src/qt3d-math.qdoc @@ -0,0 +1,34 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\group qt3d::math +\title Qt/3D Math +\keyword Qt/3D Math + +\generatelist{related} +*/ diff --git a/doc/src/qt3d-painting.qdoc b/doc/src/qt3d-painting.qdoc new file mode 100644 index 000000000..6006e745f --- /dev/null +++ b/doc/src/qt3d-painting.qdoc @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\group qt3d::painting +\title Qt/3D Painting +\keyword Qt/3D Painting + +Porting between desktop OpenGL and embedded OpenGL/ES has traditionally +been difficult. The usual sequence of operations for a drawing request +in OpenGL consists of: + +\list + \o Select an appropriate shader program, or fixed-function pipeline + rendering options. + \o Set or adjust the current projection and modelview matrices. + \o Specify vertex, normal, texture co-ordinate, and other attribute arrays. + \o Specify textures, variables, and other rendering objects needed + by the shader program. + \o Draw fragments: triangles, triangle fans, quads, etc. + \o Disable the arrays, textures, and modes that were selected. +\endlist + +Desktop OpenGL, OpenGL/ES 1.1, and OpenGL/ES 2.0 all posses functionality +for the above, but they are all different. OpenGL/ES 2.0 in particular +presents unique problems because it lacks a fixed-function pipeline mode +to perform common painting operations. + +In Qt/3D the QGLPainter class wraps OpenGL to present a consistent +OpenGL painting API across all platforms. Shaders and fixed-function +options are supplied as an instance of QGLAbstractEffect. Several +built-in standard effects are provided for drawing with flat colors, +material-based lighting, and simple texturing. + +The tutorial "\l{Converting raw GL applications to use QGLPainter}" +compares a raw GL application that draws a triangle with its +QGLPainter counterpart. + +\generatelist{related} +*/ diff --git a/doc/src/qt3d-qml3d.qdoc b/doc/src/qt3d-qml3d.qdoc new file mode 100644 index 000000000..e80cbf5b2 --- /dev/null +++ b/doc/src/qt3d-qml3d.qdoc @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\group qt3d::qml3d +\title QML Support in Qt/3D +\keyword Qt/3D QML + +The following QML elements are provided by the \c{Qt3D} namespace +for importing 3D elements into QML applications: + +\generatelist{related} + +See the \l{Teapot Example in QML/3D}{Teapot} example for an introduction +to using these elements in QML. + +QML/3D also provides some \l{Stock Shapes for QML/3D}{stock shapes} +in the \c{Qt3D.Shapes} namespace as convenience elements. +*/ + +/*! +\group qt3d::qml3d::shapes +\title Stock Shapes for QML/3D + +The following QML elements are provided by the \c{Qt3D.Shapes} namespace +as convenience elements: + +\generatelist{related} + +See the \l{Applying transformations and materials to objects#Cube in QML/3D}{Cube} example for an introduction to using these convenience shapes in QML. +*/ diff --git a/doc/src/qt3d-scene.qdoc b/doc/src/qt3d-scene.qdoc new file mode 100644 index 000000000..0aa0cb7c1 --- /dev/null +++ b/doc/src/qt3d-scene.qdoc @@ -0,0 +1,34 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\group qt3d::scene +\title Qt/3D Scene Management +\keyword Qt/3D Scene Management + +\generatelist{related} +*/ diff --git a/doc/src/qt3d-textures.qdoc b/doc/src/qt3d-textures.qdoc new file mode 100644 index 000000000..e38424379 --- /dev/null +++ b/doc/src/qt3d-textures.qdoc @@ -0,0 +1,34 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \group qt3d::textures + \title Qt/3D Texture Handling + \keyword Qt/3D Texture Handling + + \generatelist{related} +*/ diff --git a/doc/src/qt3d-viewing.qdoc b/doc/src/qt3d-viewing.qdoc new file mode 100644 index 000000000..6d3146a9c --- /dev/null +++ b/doc/src/qt3d-viewing.qdoc @@ -0,0 +1,34 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\group qt3d::viewing +\title Qt/3D Viewing +\keyword Qt/3D Viewing + +\generatelist{related} +*/ diff --git a/doc/src/style/OfflineStyle.css b/doc/src/style/OfflineStyle.css new file mode 100644 index 000000000..2fb357ce8 --- /dev/null +++ b/doc/src/style/OfflineStyle.css @@ -0,0 +1,251 @@ +@media screen +{ + + .wrapper + { + top:50px; + background: none; + + } + .wrapper .bd + { + background: none; + position: relative; + } + + + + + body.offline + { + background-image: none; + background-color: #FFFFFF; + + } + + .offline .footer { + margin: 0; + } + .offline .header + { + width: 100%; + margin: 0; + height: auto; + background-color: #ffffff; + padding: 10px 0 5px 0; + overflow: visible; + border-bottom: solid #E5E5E5 1px; + z-index:1; + position:fixed; + } + + .offline .header .content + { + } + .offline .header .qtref + { + color: #00732F; + position: static; + float: left; + margin-left: 5px; + font: bold 18px/1 Arial; + } + + .offline .header .qtref:visited + { + color: #00732F; + } + .offline .header .qtref:hover + { + color: #00732F; + text-decoration:none; + } + .offline .header .qtref span + { + background-image: none; + text-indent: 0; + text-decoration:none; + } + + .offline .wrap + { + margin: 0 5px 0 5px; + } + + .offline .wrap .toolbar + { + display:block; + padding-top:5px; + } + + .offline .wrap .breadcrumb ul li { + font-weight: normal; + } + + .offline .wrap .breadcrumb ul li a { + /*color: #44a51c;*/ + } + + .offline .wrap .breadcrumb ul li.last a { + /*color: #363534;*/ + } + + + + .narrow .indexboxcont .section { + width: 64%; + padding-left: 0; + } + + .narrow .indexboxcont .sectionlist { + width: 32.5%; + } + + .header .icon, + .sidebar, + .feedback, + .t_button, + .feedback, + #feedbackBox, + #feedback, + #blurpage, + .indexbox .indexIcon span, + .wrapper .hd, + .offline .indexbox .indexIcon, + .offline .header #nav-logo, + #offlinemenu, + #offlinesearch, + .offline .header #nav-topright, + .offline .header #shortCut , + .offline .wrapper .hd, + .offline .wrapper .ft, + .offline .sidebar, + .offline .wrap .feedback + { + display:none; + } + + /* end offline mode */ +#narrowmenu { + display: none; + float: right; + margin: 15px 40px 0 0; + font-size: 11px; + } + + .narrow #narrowmenu { + display: block; + } + + #narrowsearch{ + display:none; + } + + #narrowmenu ul + { + border-bottom:solid 1px #E5E5E5; + border-left:solid 1px #E5E5E5; + border-right:solid 1px #E5E5E5; + } + + #narrowmenu a { + line-height: 1.1; + background: url(../images/arrow_down.png) no-repeat 100% 50%; + white-space: nowrap; + padding: 0 16px 0 5px; + } + + #narrowmenu li { + margin-left: 20px; + } + + #narrowmenu li li { + margin: 0 0 5px 0; + } + + #narrowmenu li li a { + padding: 0; + background-image: none; + } + + #narrowmenu li, + #narrowmenu li ul { + background-color: #fff; + } + + #narrowmenu li ul { + width: auto; + padding: 5px; + margin-top:-15px; + } + + .sf-menu li:hover ul, .sf-menu li.sfHover ul { + top: 1.2em; + } +.sf-menu, .sf-menu * { + margin: 0; + padding: 0; + list-style: none; +} +.sf-menu { + line-height: 1.0; +} +.sf-menu ul { + position: absolute; + top: -999em; + width: 10em; /* left offset of submenus need to match (see below) */ +} +.sf-menu ul li { + width: 100%; +} +.sf-menu li:hover { + visibility: inherit; /* fixes IE7 'sticky bug' */ +} +.sf-menu li { + float: left; + position: relative; +} +.sf-menu a { + display: block; + position: relative; +} +.sf-menu li:hover ul, +.sf-menu li.sfHover ul { + left: 0; + top: 2.5em; /* match top ul list item height */ + z-index: 99; +} +ul.sf-menu li:hover li ul, +ul.sf-menu li.sfHover li ul { + top: -999em; +} +ul.sf-menu li li:hover ul, +ul.sf-menu li li.sfHover ul { + left: 10em; /* match ul width */ + top: 0; +} +ul.sf-menu li li:hover li ul, +ul.sf-menu li li.sfHover li ul { + top: -999em; +} +ul.sf-menu li li li:hover ul, +ul.sf-menu li li li.sfHover ul { + left: 10em; /* match ul width */ + top: 0; +} + .wrap .content ol li { + background:none; + font:400 10pt/1 Verdana; + margin-bottom:10px; + margin-left:12px; + } + .wrap .content ol li { + list-style-type:decimal; + + } + + + +} +/* end of screen media */ + diff --git a/doc/src/style/narrow.css b/doc/src/style/narrow.css new file mode 100644 index 000000000..7544c4ae8 --- /dev/null +++ b/doc/src/style/narrow.css @@ -0,0 +1,250 @@ + /* start narrow mode */ + + body.narrow + { + background-image: none; + } + + .narrow a { + color: #44a51c; + } + + .narrow .header, .narrow .header .content, .narrow .footer, .narrow .wrapper { + margin: 0 7px; + min-width: 300px; + } + + .narrow .footer { + margin: 0; + } + .narrow .header + { + width: 100%; + margin: 0; + height: auto; + background: #fff url(../images/header_bg.png) repeat-x 0 100%; + padding: 10px 0 5px 0; + overflow: visible; + } + + .narrow .header .content + { + } + + .narrow .header #nav-logo + { + display: none; + } + + .narrow .header .qtref + { + width: auto; + height: auto; + color: #363534; + position: static; + float: left; + margin-left: 25px; + font: bold 18px/1 Arial; + } + + .narrow .header .qtref a + { + color: #363534; + } + + .narrow .header .qtref span + { + background-image: none; + text-indent: 0; + } + + .narrow .header #nav-topright + { + display: none; + } + + .narrow .header #shortCut + { + clear: both; + font-weight: normal; + position: static; + float: left; + margin: 15px 0 0 25px; + overflow: hidden; + padding: 0; + height: auto; + } + + .narrow .header #shortCut ul + { + float: none; + margin: 0; + width: auto; + font-size: 11px; + } + + .narrow .header #shortCut ul li + { + background-image: none; + } + + .narrow .header #shortCut ul .shortCut-topleft-active, + .narrow .header #shortCut ul .shortCut-topleft-inactive + { + background-image: none; + height: auto; + padding: 0; + width: auto; + } + .narrow .header #shortCut ul li a + { + color: #44a51c; + } + + .narrow .wrapper .hd + { + background: url(../images/bg_ul_blank.png) no-repeat 0 0; + } + + .narrow .wrapper .bd + { + background: url(../images/bg_l_blank.png) repeat-y 0 0; + } + + .narrow .wrapper .ft + { + background: url(../images/bg_ll_blank.png) no-repeat 0 0; + } + + .narrow .sidebar + { + display: none; + } + + .narrow .wrap + { + margin: 0 5px 0 5px; + } + + .narrow .wrap .toolbar + { + border-bottom: none; + } + + .narrow .wrap .content + { + padding-top: 15px; + } + + .narrow .wrap .feedback + { + display: none; + } + + .narrow .wrap .breadcrumb ul li { + font-weight: normal; + } + + .narrow .wrap .breadcrumb ul li a { + color: #44a51c; + } + + .narrow .wrap .breadcrumb ul li.last a { + color: #363534; + } + + #narrowsearch { + display: none; + } + + .narrow #narrowsearch { + display: block; + float: right; + margin-right: 25px; + _position: relative; + } + + .narrow #narrowsearch fieldset { + _position: absolute; + _margin-top: -1px; + } + + .narrow #narrowsearch { + background: url("http://doc.qt.nokia.com/prototype/html/images/sprites-combined.png") no-repeat scroll -6px -348px transparent; + height: 21px; + padding: 2px 0 0 5px; + width: 167px; + } + + .narrow #narrowsearch input { + border: none; + font: 13px/1.2 Verdana; + height: 19px; + outline: none; + padding: 0; + width: 158px; + *border: 1px solid #fff; + *height: 17px; + _height: 18px; + } + + .narrow .indexbox .indexIcon { + display: none; + } + + .narrow .indexboxcont .section { + width: 64%; + padding-left: 0; + } + + .narrow .indexboxcont .sectionlist { + width: 32.5%; + } + + #narrowmenu { + display: none; + float: right; + margin: 15px 40px 0 0; + font-size: 11px; + } + + .narrow #narrowmenu { + display: block; + } + + #narrowmenu a { + line-height: 1.1; + background: url(../images/arrow_down.png) no-repeat 100% 50%; + white-space: nowrap; + padding: 0 16px 0 5px; + } + + #narrowmenu li { + margin-left: 20px; + } + + #narrowmenu li li { + margin: 0 0 5px 0; + } + + #narrowmenu li li a { + padding: 0; + background-image: none; + } + + #narrowmenu li, + #narrowmenu li ul { + background-color: #fff; + margin-top:-1px; + } + + #narrowmenu li ul { + width: auto; + padding: 5px; + } + + .sf-menu li:hover ul, .sf-menu li.sfHover ul { + top: 1.2em; + } + + /* end narrow mode */ diff --git a/doc/src/style/style.css b/doc/src/style/style.css new file mode 100644 index 000000000..f520e6add --- /dev/null +++ b/doc/src/style/style.css @@ -0,0 +1,1567 @@ +@media screen +{ + +/* basic elements */ + html + { + color: #000000; + background: #FFFFFF; + } + body, div, dl, dt, dd, ul, ol, li, h1, h2, h3, h4, h5, h6, pre, code, form, fieldset, legend, input, button, textarea, p, blockquote, th, td + { + margin: 0; + padding: 0; + } + table + { + border-collapse: collapse; + border-spacing: 0; + } + fieldset, img + { + border: 0; + max-width:100%; + } + address, caption, cite, code, dfn, em, strong, th, var, optgroup + { + font-style: inherit; + font-weight: inherit; + } + del, ins + { + text-decoration: none; + } + li + { + list-style: none; + } + caption, th + { + text-align: left; + } + h1, h2, h3, h4, h5, h6 + { + font-size: 100%; + } + q:before, q:after + { + content: ''; + } + abbr, acronym + { + border: 0; + font-variant: normal; + } + sup, sub + { + vertical-align: baseline; + } + tt, .qmlreadonly span, .qmldefault span + { + word-spacing:5px; + } + legend + { + color: #000000; + } + input, button, textarea, select, optgroup, option + { + font-family: inherit; + font-size: inherit; + font-style: inherit; + font-weight: inherit; + } + input, button, textarea, select + { + font-size: 100%; + } + strong + { + font-weight: bold; + } + em + { + font-style: italic; + } + + /* adding Qt theme */ + html + { + /* background-color: #e5e5e5;*/ + } + body + { + background: #e6e7e8 url(../images/page_bg.png) repeat-x 0 0; + font: normal 13px/1.2 Verdana; + color: #363534; + } + a + { + color: #00732f; + text-decoration: none; + } + hr + { + background-color: #E6E6E6; + border: 1px solid #E6E6E6; + height: 1px; + width: 100%; + text-align: left; + margin: 15px 0px 15px 0px; + } + + pre + { + border: 1px solid #DDDDDD; + -moz-border-radius: 7px 7px 7px 7px; + margin: 0 20px 10px 10px; + padding: 20px 15px 20px 20px; + overflow-x: auto; + } + table, pre + { + -moz-border-radius: 7px 7px 7px 7px; + background-color: #F6F6F6; + border: 1px solid #E6E6E6; + border-collapse: separate; + font-size: 11px; + margin-bottom: 25px; + } + pre.highlightedCode { + display: block; + overflow:hidden; + } + thead + { + margin-top: 5px; + font:600 12px/1.2 Arial; + } + th + { + padding: 5px 15px 5px 15px; + background-color: #E1E1E1; + border-left: 1px solid #E6E6E6; + } + td + { + padding: 3px 15px 3px 20px; + } + tr.odd td:hover, tr.even td:hover {} + + td.rightAlign + { + padding: 3px 5px 3px 10px; + } + table tr.odd + { + border-left: 1px solid #E6E6E6; + background-color: #F6F6F6; + color: #66666E; + } + table tr.even + { + border-left: 1px solid #E6E6E6; + background-color: #ffffff; + color: #66666E; + } + table tr.odd td:hover, table tr.even td:hover + { + /* background-color: #E6E6E6;*/ /* disabled until further notice */ + } + + span.comment + { + color: #8B0000; + font-style: italic; + } + span.string, span.char + { + color: #254117; + } + + +/* end basic elements */ + +/* font style elements */ + .heading + { + font: normal bold 16px/1.0 Arial; + padding-bottom: 15px; + } + .subtitle + { + font-size: 13px; + } + .small-subtitle + { + font-size: 13px; + } +/* end font style elements */ + +/* global settings*/ + .header, .footer, .wrapper + { + min-width: 600px; + max-width: 1500px; + margin: 0 30px; + } + .header, .footer + { + display: block; + clear: both; + overflow: hidden; + } + .header:after, .footer:after, .breadcrumb:after, .wrap .content:after, .group:after + { + content: "."; + display: block; + height: 0; + clear: both; + visibility: hidden; + } + +/* end global settings*/ +/* header elements */ + .header + { + height: 115px; + position: relative; + } + .header .icon + { + position: absolute; + top: 13px; + left: 0; + } + .header .qtref + { + position: absolute; + top: 28px; + left: 88px; + width: 302px; + height: 22px; + } + .header .qtref span + { + display: block; + width: 302px; + height: 22px; + text-indent: -999em; + background: url(../images/sprites-combined.png) no-repeat -78px -235px; + } + .content a:visited + { + color: #4c0033; + text-decoration: none; + } + .content a:visited:hover + { + color: #4c0033; + text-decoration: underline; + } + + #nav-topright + { + height: 70px; + } + + #nav-topright ul + { + list-style-type: none; + float: right; + width: 370px; + margin-top: 11px; + } + + #nav-topright li + { + display: inline-block; + margin-right: 20px; + float: left; + } + + #nav-topright li.nav-topright-last + { + margin-right: 0; + } + + #nav-topright li a + { + background: transparent url(../images/sprites-combined.png) no-repeat; + height: 18px; + display: block; + overflow: hidden; + text-indent: -9999px; + } + + #nav-topright li.nav-topright-home a + { + width: 65px; + background-position: -2px -91px; + } + + #nav-topright li.nav-topright-home a:hover + { + background-position: -2px -117px; + } + + + #nav-topright li.nav-topright-dev a + { + width: 30px; + background-position: -76px -91px; + } + + #nav-topright li.nav-topright-dev a:hover + { + background-position: -76px -117px; + } + + + #nav-topright li.nav-topright-labs a + { + width: 40px; + background-position: -114px -91px; + } + + #nav-topright li.nav-topright-labs a:hover + { + background-position: -114px -117px; + } + + #nav-topright li.nav-topright-doc a + { + width: 32px; + background-position: -162px -91px; + } + + #nav-topright li.nav-topright-doc a:hover, #nav-topright li.nav-topright-doc-active a + { + background-position: -162px -117px; + } + + #nav-topright li.nav-topright-blog a + { + width: 40px; + background-position: -203px -91px; + } + + #nav-topright li.nav-topright-blog a:hover, #nav-topright li.nav-topright-blog-active a + { + background-position: -203px -117px; + } + + #nav-topright li.nav-topright-shop a + { + width: 40px; + background-position: -252px -91px; + } + + #nav-topright li.nav-topright-shop a:hover, #nav-topright li.nav-topright-shop-active a + { + background-position: -252px -117px; + } + + #nav-logo + { + background: transparent url(../images/sprites-combined.png ) no-repeat 0 -225px; + left: -3px; + position: absolute; + width: 75px; + height: 75px; + top: 13px; + } + #nav-logo a + { + width: 75px; + height: 75px; + display: block; + text-indent: -9999px; + overflow: hidden; + } + + + .shortCut-topleft-inactive + { + padding-left: 3px; + background: transparent url( ../images/sprites-combined.png) no-repeat 0px -58px; + height: 20px; + width: 47px; + } + .shortCut-topleft-inactive span + { + font-variant: normal; + } + .shortCut-topleft-inactive span a:hover, .shortCut-topleft-active a:hover + { + text-decoration:none; + } + #shortCut + { + padding-top: 10px; + font-weight: bolder; + color: #b0adab; + } + #shortCut ul + { + list-style-type: none; + float: left; + width: 347px; + margin-left: 100px; + } + #shortCut li + { + display: inline-block; + margin-right: 25px; + float: left; + white-space: nowrap; + } + #shortCut li a + { + color: #b0adab; + } + #shortCut li a:hover + { + color: #44a51c; + } + + + +/* end header elements */ +/* content and sidebar elements */ + .wrapper + { + background: url(../images/bg_r.png) repeat-y 100% 0; + } + .wrapper .hd + { + padding-left: 216px; + height: 15px; + background: url(../images/page.png) no-repeat 0 0; + overflow: hidden; + } + + + + + .wrapper .hd span + { + height: 15px; + display: block; + overflow: hidden; + background: url(../images/page.png) no-repeat 100% -30px; + } + .wrapper .bd + { + background: url(../images/bg_l.png) repeat-y 0 0; + position: relative; + } + + + + + .wrapper .ft + { + padding-left: 216px; + height: 15px; + background: url(../images/page.png) no-repeat 0 -75px; + overflow: hidden; + } + + + + + .wrapper .ft span + { + height: 15px; + display: block; + background: url(../images/page.png) no-repeat 100% -60px; + overflow: hidden; + } + .navTop{ + float:right; + display:block; + padding-right:15px; + + + } + + + +/* end content and sidebar elements */ +/* sidebar elements */ + .sidebar + { + float: left; + margin-left: 5px; + width: 200px; + font-size: 11px; + } + + + + + + + .sidebar .searchlabel + { + padding: 0 0 2px 17px; + font: normal bold 11px/1.2 Verdana; + } + + .sidebar .search + { + padding: 0 15px 0 16px; + } + + .sidebar .search form + { + background: url(../images/sprites-combined.png) no-repeat -6px -348px; + height:21px; + padding:2px 0 0 5px; + width:167px; + } + + .sidebar .search form input#pageType + { + width: 158px; + height: 19px; + padding: 0; + border: 0px; + outline: none; + font: 13px/1.2 Verdana; + } + + .sidebar .box + { + padding: 17px 15px 5px 16px; + } + + .sidebar .box .first + { + background-image: none; + } + + .sidebar .box h2 + { + font: bold 16px/1.2 Arial; + padding: 0; + } + .sidebar .box h2 span + { + overflow: hidden; + display: inline-block; + } + .sidebar .box#lookup h2 + { + background-image: none; + } + .sidebar #lookup.box h2 span + { + } + .sidebar .box#topics h2 + { + background-image: none; + } + .sidebar #topics.box h2 span + { + } + .sidebar .box#examples h2 + { + background-image: none; + } + .sidebar #examples.box h2 span + { + } + + .sidebar .box .list + { + display: block; + max-height:200px; + min-height:120px; + overflow-y:auto; + overflow-x:none; + } + .list li a:hover + { + text-decoration: underline; + } + .sidebar .box ul + { + padding-bottom:5px; + padding-left:10px; + padding-top:5px; + } + .sidebar .box ul li + { + padding-left: 12px; + background: url(../images/bullet_gt.png) no-repeat 0 5px; + margin-bottom: 5px; + } + .sidebar .bottombar + { + background: url(../images/box_bg.png) repeat-x 0 bottom; + } + .sidebar .box ul li.noMatch + { + background: none; + color:#FF2A00; + font-style:italic; + } + .sidebar .box ul li.hit + { + background: none; + color:#AAD2F0; + font-style:italic; + } + .sidebar .search form input.loading + { + background:url("../images/spinner.gif") no-repeat scroll right center transparent; + } + +.floatingResult{ + z-index:1; + position:relative; + padding-top:0px; + background-color:white; + border:solid 1px black; + height:250px; + width:600px; + overflow-x:hidden; + overflow-y:auto; +} + + .floatingResult:hover{ + display:block; + } + .floatingResult:hover{ + } + +/* end sidebar elements */ +/* content elements */ + .wrap + { + margin: 0 5px 0 208px; + overflow: visible; + } + + + + + .wrap .toolbar + { + background-color: #fafafa; + border-bottom: 1px solid #d1d1d1; + height: 20px; + position: relative; + } + .wrap .toolbar .toolblock + { + position: absolute; + } + .wrap .toolbar .breadcrumb + { + font-size: 11px; + line-height: 1; + padding: 0 0 10px 21px; + height: 10px; + } + .wrap .toolbar .toolbuttons + { + padding: 0 0 10px 21px; + right: 5px; + vertical-align: middle; + overflow: hidden; + } + .wrap .toolbar .toolbuttons .active + { + color: #00732F; + } + .wrap .toolbar .toolbuttons ul + { + float: right; + } + .wrap .toolbar .toolbuttons li + { + float: left; + text-indent: -10px; + margin-top: -5px; + margin-right: 15px; + font-weight: bold; + color: #B0ADAB; + } + + .toolbuttons #print + { + border-left: 1px solid #c5c4c4; + margin-top: 0; + padding-left: 7px; + text-indent: 0; + } + .toolbuttons #print a + { + width: 16px; + height: 16px; + } + + .toolbuttons #print a span + { + width: 16px; + height: 16px; + text-indent: -999em; + display: block; + overflow: hidden; + background: url(../images/sprites-combined.png) no-repeat -137px -311px; + } + + .toolbuttons #smallA + { + font-size: 10pt; + } + .toolbuttons #medA + { + font-size: 12pt; + } + .toolbuttons #bigA + { + font-size: 14pt; + margin-right: 7px; + } + + #smallA:hover, #medA:hover, #bigA:hover + { + color: #00732F; + } + + + .wrap .content + { + padding: 30px; + word-wrap:break-word; + } + + .wrap .breadcrumb ul + { + } + .wrap .breadcrumb ul li + { + float: left; + background: url(../images/breadcrumb.png) no-repeat 0 3px; + padding-left: 15px; + margin-left: 15px; + font-weight: bold; + } + .wrap .breadcrumb ul li.last + { + font-weight: normal; + } + .wrap .breadcrumb ul li a + { + color: #363534; + } + .wrap .breadcrumb ul li.first + { + background-image: none; + padding-left: 0; + margin-left: 0; + } + + + + + .wrap .content ol li { + background:none; + font:normal 10pt/1 Verdana; + + margin-bottom:10px; + margin-left:12px; + /*list-style-type:disc;*/ + } + + .wrap .content li + { + background: url(../images/bullet_sq.png) no-repeat 0 5px; + font: normal 400 10pt/1 Verdana; + margin-bottom: 10px; + padding-left:12px; + } + + + + + + + + + + .content li:hover {} + + .wrap .content h1 + { + font: bold 18px/1.2 Arial; + } + .wrap .content h2 + { + border-bottom:1px solid #DDDDDD; + font:600 16px/1.2 Arial; + margin-top:15px; + width:100%; + } + .wrap .content h3 + { + font: bold 14px/1.2 Arial; + font:600 16px/1.2 Arial; + margin-top:15px; + width:100%; + } + .wrap .content p + { + line-height: 20px; + padding: 5px; + } + .wrap .content table p + { + line-height: 20px; + padding: 0px; + } + .wrap .content ul + { + padding-left: 25px; + padding-top: 10px; + } + a:hover + { + color: #4c0033; + text-decoration: underline; + } + .feedback + { + float: none; + position: absolute; + right: 15px; + bottom: 10px; + font: normal 8px/1 Verdana; + color: #B0ADAB; + } + .feedback:hover + { + float: right; + font: normal 8px/1 Verdana; + color: #00732F; + text-decoration: underline; + } + .alphaChar{ + width:100%; + background-color:#F6F6F6; + border:1px solid #E6E6E6; + -moz-border-radius: 7px 7px 7px 7px; + font-size:12pt; + padding-left:10px; + margin-top:10px; + margin-bottom:10px; + } + .flowList{ + vertical-align:top; + } + + .flowList dl{ + } + .flowList dd{ + display:inline-block; + margin-left:10px; + width:250px; + } + .wrap .content .flowList p{ + padding:0px; + } + + .content .alignedsummary + { + margin: 15px; + } + + + .qmltype + { + text-align: center; + font-size: 160%; + } + .qmlreadonly + { + padding-left: 5px; + float: right; + color: #254117; + } + + .qmldefault + { + padding-left: 5px; + float: right; + color: red; + } + + .qmldoc + { + } + + *.qmlitem p + { + } + #feedbackBox + { + display: none; + -moz-border-radius: 7px 7px 7px 7px; + border: 1px solid #DDDDDD; + position: fixed; + top: 100px; + left: 33%; + height: 230px; + width: 400px; + padding: 5px; + background-color: #e6e7e8; + z-index: 4; + } + #feedcloseX + { + display: inline; + padding: 5px 5px 0 0; + margin-bottom: 3px; + color: #363534; + font-weight: 600; + float: right; + text-decoration: none; + } + + #feedbox + { + display: inline; + width: 370px; + height: 120px; + margin: 0px 25px 10px 15px; + } + #noteHead + { + font-weight:bold; + padding:10px 10px 10px 20px; + } + #feedsubmit + { + display: inline; + float: right; + margin: 4px 32px 0 0; + } + + .note + { + font-size:7pt; + padding-bottom:3px; + padding-left:20px; + } + + #blurpage + { + display: none; + position: fixed; + float: none; + top: 0px; + left: 0px; + right: 0px; + bottom: 0px; + background: transparent url(../images/feedbackground.png) 0 0; + z-index: 3; + } + .toc + { + float: right; + -moz-border-radius: 7px 7px 7px 7px; + background-color: #F6F6F6; + border: 1px solid #DDDDDD; + margin: 0 20px 10px 10px; + padding: 20px 15px 20px 20px; + height: auto; + width: 200px; + } + + .toc h3, .generic a + { + font: bold 12px/1.2 Arial; + } + + .generic{ + } + .generic td{ + padding:5px; + } + .generic .alphaChar{ + margin-top:5px; + } + + .generic .odd .alphaChar{ + background-color: #F6F6F6; + } + + .generic .even .alphaChar{ + background-color: #FFFFFF; + } + + .alignedsummary{} + .propsummary{} + .memItemLeft{} + .memItemRight{ + padding:3px 15px 3px 0; + } + .bottomAlign{} + .highlightedCode + { + margin:10px; + } + .LegaleseLeft{} + .valuelist{} + .annotated td{ + padding: 3px 5px 3px 5px; + } + .obsolete{} + .compat{} + .flags{} + .qmlsummary{} + .qmlitem{} + .qmlproto{} + .qmlname{} + .qmlreadonly{} + .qmldefault{} + .qmldoc{} + .qt-style{} + .redFont{} + code{} + + .wrap .content .toc ul + { + padding-left: 0px; + } + + .wrap .content .toc h3{ + border-bottom:0px; + margin-top:0px; + } + + .wrap .content .toc h3 a:hover{ + color:#00732F; + text-decoration:none; + } + + + .wrap .content .toc .level2 + { + margin-left: 15px; + } + + .wrap .content .toc .level3 + { + margin-left: 30px; + } + + .content .toc li + { + font: normal 10px/1.2 Verdana; + background: url(../images/bullet_dn.png) no-repeat 0 5px; + } + .relpage + { + -moz-border-radius: 7px 7px 7px 7px; + border: 1px solid #DDDDDD; + padding: 25px 25px; + clear: both; + } + .relpage ul + { + float: none; + padding: 15px; + } + .content .relpage li + { + font: normal 11px/1.2 Verdana; + } + h3.fn, span.fn + { + -moz-border-radius:7px 7px 7px 7px; + background-color: #F6F6F6; + border-width: 1px; + border-style: solid; + border-color: #E6E6E6; + font-weight: bold; + word-spacing:3px; + padding:3px 5px; + } + + .functionIndex { + font-size:12pt; + word-spacing:10px; + margin-bottom:10px; + background-color: #F6F6F6; + border-width: 1px; + border-style: solid; + border-color: #E6E6E6; + -moz-border-radius: 7px 7px 7px 7px; + width:100%; + } + + .centerAlign + { + text-align:center; + } + + .rightAlign + { + text-align:right; + } + + + .leftAlign + { + text-align:left; + } + + .topAlign{ + vertical-align:top + } + + .functionIndex a{ + display:inline-block; + } + +/* end content elements */ +/* footer elements */ + + .footer + { + min-height: 100px; + color: #797775; + font: normal 9px/1 Verdana; + text-align: center; + padding-top: 40px; + background-color: #E6E7E8; + margin: 0; + } +/* end footer elements */ + + + + + /* start index box */ + .indexbox + { + width: 100%; + display:inline-block; + } + + .indexboxcont + { + display: block; + + } + + .indexboxbar + { + background: transparent url(../images/horBar.png ) repeat-x left bottom; + margin-bottom: 25px; + + + } + + .indexboxcont .section + { + display: inline-block; + width: 49%; + *width:42%; + _width:42%; + padding:0 2% 0 1%; + vertical-align:top; + +} + + .indexboxcont .indexIcon + { + width: 11%; + *width:18%; + _width:18%; + overflow:hidden; + +} + +.indexboxcont .section { + float: left; +} + + .indexboxcont .section p + { + padding-top: 20px; + padding-bottom: 20px; + } + .indexboxcont .sectionlist + { + display: inline-block; + vertical-align:top; + width: 32.5%; + padding: 0; + } + .indexboxcont .sectionlist ul + { + margin-bottom: 20px; + } + + .indexboxcont .sectionlist ul li + { + line-height: 12px; + } + + .content .indexboxcont li + { + font: normal bold 13px/1 Verdana; + } + + .indexbox a:hover, .indexbox a:visited:hover + { + color: #4c0033; + text-decoration: underline; + } + + .indexbox a:visited + { + color: #00732f; + text-decoration: none; + } + + .indexbox .indexIcon { + width: 11%; + } + + + .indexbox .indexIcon span + { + display: block; + } + + .indexbox.guide .indexIcon span + { + width: 96px; + height: 137px; + background: url(../images/sprites-combined.png) no-repeat -5px -376px; + padding: 0; + } + + .indexbox.tools .indexIcon span + { + width: 115px; + height: 137px; + background: url(../images/sprites-combined.png) no-repeat -111px -376px; + padding: 0; + } + .indexboxcont:after + { + content: "."; + display: block; + height: 0; + clear: both; + visibility: hidden; + } + + + +/* start of offline spec*/ + .offline .wrapper .hd + { + background: url(../images/page.png) no-repeat 0 -15px; + } + .offline .wrapper .bd + { + background: url(../images/bg_l_blank.png) repeat-y 0 0; + } + .offline .wrapper .ft + { + background: url(../images/page.png) no-repeat 0 -90px; + } + .offline .sidebar, + .offline .feedback, + .offline .t_button, + .offline #narrowsearch, + .offline #narrowmenu + { + display: none; + } + .offline .wrap + { + margin: 0 5px 0 5px; + } + .offline .wrap .breadcrumb + { + } + + .offline .wrap .content + { + padding-top: 15px; + } + + +/* end of offline spec*/ + +/* start of creator spec*/ + .creator + { + margin-left:0px; + margin-right:0px; + padding-left:0px; + padding-right:0px; + } + .creator .wrap .content ol li { + list-style-type:decimal; + + } + .creator .header .icon, + .creator .feedback, + .creator .t_button, + .creator .feedback, + .creator #feedbackBox, + .creator #feedback, + .creator #blurpage, + .creator .indexbox .indexIcon span, + .creator .wrapper .hd, + .creator .indexbox .indexIcon, + .creator .header #nav-logo, + .creator #offlinemenu, + .creator #offlinesearch, + .creator .header #nav-topright, + .creator .header #shortCut , + .creator .wrapper .hd, + .creator .wrapper .ft, + .creator .sidebar, + .creator .wrap .feedback + { + display:none; + } + + body.creator + { + background: none; + + font: normal 13px/1.2 Verdana; + color: #363534; + background-color: #FFFFFF; + } + + + + .creator .header, .footer, .wrapper + { + max-width: 1500px; + margin: 0px; + } + + .creator .wrapper + { + position:relative; + top:50px; + } + .creator .wrapper .bd + { + + background:#FFFFFF; + } + + + .creator .header, .footer + { + display: block; + clear: both; + overflow: hidden; + } + .creator .wrap .content p + + { + line-height: 20px; + padding: 5px; + } + + .creator .header .qtref span + { + background:none; + } + + + + .creator .footer + { + border-top:1px solid #E5E5E5; + min-height: 100px; + margin:0px; + } + + .creator .wrap + { + + padding:0 5px 0 5px; + margin: 0px; + } + .creator .wrap .toolbar + { + + + border-bottom:1px solid #E5E5E5; + width:100%, + } + .creator .wrap .breadcrumb ul li a + { + /* color: #363534;*/ + color: #00732F; + } + + .creator .wrap .content + { + padding: 0px; + word-wrap:break-word; + } + + .creator .wrap .content ol li { + background:none; + font: inherit; + padding-left: 0px; + } + + .creator .wrap .content .descr ol li { + margin-left: 45px; + + } + .creator .content .alignedsummary + { + margin: 5px; + width:100%; + } + .creator .generic{ + max-width:75%; + } + .creator .generic td{ + padding:0; + } + .creator .indexboxbar + { + border-bottom:1px solid #E5E5E5; + margin-bottom: 25px; + background: none; + } + + + + .creator .header + { + width: 100%; + margin: 0; + height: auto; + background-color: #ffffff; + padding: 10px 0 5px 0; + overflow: visible; + border-bottom: solid #E5E5E5 1px; + z-index:1; + + + + + + + + + position:fixed; + } + + + .creator .header .content + { + } + .creator .header .qtref + { + color: #00732F; + position: static; + float: left; + margin-left: 5px; + font: bold 18px/1 Arial; + } + + .creator .header .qtref:visited + { + color: #00732F; + } + .creator .header .qtref:hover + { + color: #00732F; + text-decoration:none; + } + .creator .header .qtref span + { + background-image: none; + text-indent: 0; + text-decoration:none; + } + + + + + + + .creator .wrap .toolbar + { + display:block; + padding-top:0px; + } + + + + .creator .wrap .breadcrumb ul li { + font-weight: normal; + } + + .creator .wrap .breadcrumb ul li a { + /*color: #44a51c;*/ + } + + .creator .wrap .breadcrumb ul li.last a { + /*color: #363534;*/ + } + + .creator #narrowmenu ul + { + border-bottom:solid 1px #E5E5E5; + border-left:solid 1px #E5E5E5; + border-right:solid 1px #E5E5E5; + } + + .creator #narrowmenu li ul { + margin-top:-15px; + } + + + .creator .toc { + margin:10px 20px 10px 10px; + } +/* end of creator spec*/ + +} + +/* end of screen media */ + +/* start of print media */ + +@media print +{ + input, textarea, .header, .footer, .toolbar, .feedback, .wrapper .hd, .wrapper .bd .sidebar, .wrapper .ft + { + display: none; + background: none; + } + .content + { + position: absolute; + top: 0px; + left: 0px; + background: none; + display: block; + } +} +/* end of print media */ diff --git a/doc/src/style/style_ie6.css b/doc/src/style/style_ie6.css new file mode 100644 index 000000000..16fb8505d --- /dev/null +++ b/doc/src/style/style_ie6.css @@ -0,0 +1,54 @@ +.indexbox, .indexboxcont, .group { + zoom: 1; + height: 1%; +} + +.sidebar { + margin-left: 3px; + width: 199px; + overflow: hidden; +} + +.sidebar .search form { + position: relative; +} + +.sidebar .search form fieldset { + position: absolute; + margin-top: -1px; +} + +.sidebar .search form input#searchstring { + border: 1px solid #fff; + height: 18px; +} + +.wrap { + zoom: 1; +} + +.content, +.toolbar { + zoom: 1; + margin-left: -3px; + position: relative; +} + +.indexbox { + clear: both; +} + +.indexboxcont .section { + zoom: 1; + float: left; +} + +.indexboxcont .sectionlist { + zoom: 1; + float: left; +} + +.wrap .toolbar .toolbuttons li { + text-indent: 0; + margin-right: 8px; +}
\ No newline at end of file diff --git a/doc/src/style/style_ie7.css b/doc/src/style/style_ie7.css new file mode 100644 index 000000000..afbff5f88 --- /dev/null +++ b/doc/src/style/style_ie7.css @@ -0,0 +1,19 @@ +.indexbox, .indexboxcont, .group { + min-height: 1px; +} + +.sidebar .search form input#searchstring { + border: 1px solid #fff; + height: 17px; +} + + +.indexboxcont .section { + zoom: 1; + float: left; +} + +.indexboxcont .sectionlist { + zoom: 1; + float: left; +} diff --git a/doc/src/style/style_ie8.css b/doc/src/style/style_ie8.css new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/doc/src/style/style_ie8.css diff --git a/doc/src/style/superfish.css b/doc/src/style/superfish.css new file mode 100644 index 000000000..a9939090d --- /dev/null +++ b/doc/src/style/superfish.css @@ -0,0 +1,51 @@ +.sf-menu, .sf-menu * { + margin: 0; + padding: 0; + list-style: none; +} +.sf-menu { + line-height: 1.0; +} +.sf-menu ul { + position: absolute; + top: -999em; + width: 10em; /* left offset of submenus need to match (see below) */ +} +.sf-menu ul li { + width: 100%; +} +.sf-menu li:hover { + visibility: inherit; /* fixes IE7 'sticky bug' */ +} +.sf-menu li { + float: left; + position: relative; +} +.sf-menu a { + display: block; + position: relative; +} +.sf-menu li:hover ul, +.sf-menu li.sfHover ul { + left: 0; + top: 2.5em; /* match top ul list item height */ + z-index: 99; +} +ul.sf-menu li:hover li ul, +ul.sf-menu li.sfHover li ul { + top: -999em; +} +ul.sf-menu li li:hover ul, +ul.sf-menu li li.sfHover ul { + left: 10em; /* match ul width */ + top: 0; +} +ul.sf-menu li li:hover li ul, +ul.sf-menu li li.sfHover li ul { + top: -999em; +} +ul.sf-menu li li li:hover ul, +ul.sf-menu li li li.sfHover ul { + left: 10em; /* match ul width */ + top: 0; +} diff --git a/doc/src/style/superfish_skin.css b/doc/src/style/superfish_skin.css new file mode 100644 index 000000000..112b26ae2 --- /dev/null +++ b/doc/src/style/superfish_skin.css @@ -0,0 +1,83 @@ + +/*** DEMO SKIN ***/ +.sf-menu { + float: left; + margin-bottom: 1em; +} +.sf-menu a { + border-left: 1px solid #fff; + border-top: 1px solid #CFDEFF; + padding: .75em 1em; + text-decoration:none; +} +.sf-menu a, .sf-menu a:visited { /* visited pseudo selector so IE6 applies text colour*/ + color: #13a; +} +.sf-menu li { + background: #BDD2FF; +} +.sf-menu li li { + background: #AABDE6; +} +.sf-menu li li li { + background: #9AAEDB; +} +.sf-menu li:hover, .sf-menu li.sfHover, +.sf-menu a:focus, .sf-menu a:hover, .sf-menu a:active { + background: #CFDEFF; + outline: 0; +} + +/*** arrows **/ +.sf-menu a.sf-with-ul { + padding-right: 2.25em; + min-width: 1px; /* trigger IE7 hasLayout so spans position accurately */ +} +.sf-sub-indicator { + position: absolute; + display: block; + right: .75em; + top: 1.05em; /* IE6 only */ + width: 10px; + height: 10px; + text-indent: -999em; + overflow: hidden; + background: url('../images/arrows-ffffff.png') no-repeat -10px -100px; /* 8-bit indexed alpha png. IE6 gets solid image only */ +} +a > .sf-sub-indicator { /* give all except IE6 the correct values */ + top: .8em; + background-position: 0 -100px; /* use translucent arrow for modern browsers*/ +} +/* apply hovers to modern browsers */ +a:focus > .sf-sub-indicator, +a:hover > .sf-sub-indicator, +a:active > .sf-sub-indicator, +li:hover > a > .sf-sub-indicator, +li.sfHover > a > .sf-sub-indicator { + background-position: -10px -100px; /* arrow hovers for modern browsers*/ +} + +/* point right for anchors in subs */ +.sf-menu ul .sf-sub-indicator { background-position: -10px 0; } +.sf-menu ul a > .sf-sub-indicator { background-position: 0 0; } +/* apply hovers to modern browsers */ +.sf-menu ul a:focus > .sf-sub-indicator, +.sf-menu ul a:hover > .sf-sub-indicator, +.sf-menu ul a:active > .sf-sub-indicator, +.sf-menu ul li:hover > a > .sf-sub-indicator, +.sf-menu ul li.sfHover > a > .sf-sub-indicator { + background-position: -10px 0; /* arrow hovers for modern browsers*/ +} + +/*** shadows for all but IE6 ***/ +.sf-shadow ul { + background: url('../images/shadow.png') no-repeat bottom right; + padding: 0 8px 9px 0; + -moz-border-radius-bottomleft: 17px; + -moz-border-radius-topright: 17px; + -webkit-border-top-right-radius: 17px; + -webkit-border-bottom-left-radius: 17px; +} +.sf-shadow ul.sf-shadow-off { + background: transparent; +} diff --git a/doc/src/tutorials/converting.qdoc b/doc/src/tutorials/converting.qdoc new file mode 100644 index 000000000..715f2bf26 --- /dev/null +++ b/doc/src/tutorials/converting.qdoc @@ -0,0 +1,172 @@ +/**************************************************************************** +** +** 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 Converting raw GL applications to use QGLPainter + \example tutorials/converting + + \raw HTML + <table align="left" width="100%"> + <tr><td> + \endraw + In this tutorial, we will show how to convert an existing application + that uses QGLWidget and raw GL function calls to use QGLPainter. + In the process, we will show some of the portability challenges that + are presented by raw GL and how QGLPainter addresses them. + + The application we are going to build does the following during + each paint event: + + \list + \o Clear the window to the background role color from the window's palette. + \o Set up a standard orthographic projection. + \o Draw a green triangle in the upper left corner of the window. + \endlist + + \raw HTML + </td><td align="right"> + \endraw + \image tutorials/converting-screenshot.png + \raw HTML + </td></tr> + </table> + \endraw + + \section1 Widget definition and viewport setup + + We start by defining a class that inherits from QGLWidget: + + \quotefromfile tutorials/converting/converting-rawgl.cpp + \skipuntil class-defn + \printto QT_OPENGL_ES_2 + \skipuntil endif + \printto class-defn + + The only difference for using QGLPainter is the inclusion of + the \c{qglpainter.h} header: + + \snippet tutorials/converting/converting.cpp includes + + Then we override QGLWidget::resizeGL() to set the viewport + every time the window changes size: + + \snippet tutorials/converting/converting-rawgl.cpp set-viewport + + It isn't necessary to set the viewport with QGLPainter because + QGLPainter::begin() will take care of setting the correct viewport + for the drawing surface. + + QGLPainter is a wrapper around QGLContext objects. In this case, + we are creating a painter object for the QGLContext associated + with \c{this} widget. Multiple QGLPainter objects can be created + for the same QGLContext, and they will all refer to the same + shared context state. + + \section1 Painting the scene + + The next step is to start implementing our QGLWidget::paintGL() + override by clearing the window to the background color. + First, for raw GL: + + \snippet tutorials/converting/converting-rawgl.cpp clear-window + + With QGLPainter, clearing to the background color is similar: + + \snippet tutorials/converting/converting.cpp clear-window + + As in \c{resizeGL()}, we create a QGLPainter instance for the current + widget, and then QGLPainter takes care of the platform issues + for us. + + Now we need to set up the projection and modelview matrices for the view: + + \snippet tutorials/converting/converting-rawgl.cpp set-matrices + + Here we see the difficulty of writing portable GL code: the function + for setting up an orthographic projection changes in name from + \c{glOrtho()} for desktop OpenGL to \c{glOrthof()} for + OpenGL/ES 2.0. We should also note that the above won't work with + OpenGL/ES 2.0 which uses shaders instead of fixed function operations + like \c{glLoadIdentity()} and \c{glOrtho()}. The QGLPainter equivalent + is a lot simpler, and will work on all OpenGL platforms, including + OpenGL/ES 2.0: + + \snippet tutorials/converting/converting.cpp set-matrices + + \raw HTML + The OpenGL/ES 2.0 equivalent using shaders is given in the + <a href="tutorials-converting-converting-rawgl-cpp.html">converting-rawgl.cpp</a> source file. + \endraw + + Finally, we select a color and draw the triangle: + + \snippet tutorials/converting/converting-rawgl.cpp draw + + The QGLPainter equivalent is similar in structure and will also + work on OpenGL/ES 2.0: + + \snippet tutorials/converting/converting.cpp draw-all + + The code first selects a standard drawing effect. All QGLPainter drawing + operations make use of QGLAbstractEffect objects, and there are a number + of built-in effects for common drawing operations. In this case, + we select the QGL::FlatColor effect and set the color. See + QGLPainter::setStandardEffect() and QGLAbstractEffect for more + information on how QGLPainter uses effects. + + Next, the code creates a QVector3DArray instance containing the vertex + position values. The positions are then added to the array with + QVector3DArray::append(). + + QVector3DArray is essentially QArray<QVector3D>. QArray + is a highly efficient data structure for building large arrays + of simple vector values. The array starts by appending to + preallocated storage on the stack and then moves the data + to the heap as the array grows in size. + + There is a slight difference to the raw GL example, which used a + static constant array of vertex values. The QArray::fromRawData() + function can be used to load data from static constant arrays. + In this example, we are building the QVector3DArray on the stack + every time the scene is painted. + + Last, we set the vertex array and draw the triangle defined by + the three vertices. It isn't necessary to explictly enable and + disable the vertex array: the effect takes care of that for us + automatically. + + The full \c{paintGL()} function is as follows: + + \snippet tutorials/converting/converting.cpp paintGL + + This code will work on all OpenGL platforms. Under OpenGL/ES 2.0, + QGLPainter will transparently implement the QGL::FlatColor effect + using shaders. On all other platforms, the fixed function pipeline + is used to implement the QGL::FlatColor effect. + + \l{qt3d-examples.html}{Return to the main Tutorials page}. +*/ diff --git a/doc/src/tutorials/penguin.qdoc b/doc/src/tutorials/penguin.qdoc new file mode 100644 index 000000000..babdbf724 --- /dev/null +++ b/doc/src/tutorials/penguin.qdoc @@ -0,0 +1,106 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example tutorials/penguin + \title Loading a 3DS model with Qt/3D + + This tutorial shows how Qt/3D can be used to load a simple + model object in 3D Studio Max (3DS) format with a perspective + camera view. + + We start by defining a class that inherits from QGLView, which + provides some basic scene setup logic and 3D camera navigation: + + \snippet tutorials/penguin/modelview.h class-defn + + Refer first to the \l{Teapot Example} for the basics of using + the QGLView class, lighting and so on. + + When the application starts up, we load the scene from its + resource file, and store the result in a member variable, so + we can refer to it in the paint function: + + \snippet tutorials/penguin/modelview.cpp initialize + + In the teapot example we had to specify appropriate effects but + the model loader sets appropriate effects on the scene for us. + + \snippet tutorials/penguin/modelview.cpp paint + + Here in the paint function we call the \c{draw()} function of + the scene's main object, in order to display the fully + loaded model. + + This was really just two lines of code: one to load the model + (once off, when the application initialized) and another line to + display the model (every time the paint function is called). + + \image penguin-0-screenshot.png + + The result is pretty good for two lines of code, but it could + stand some improvements. + + Here we are looking down onto the top of our penguin's head, and + even when we stand him on his feet, he is too close to the camera + to all fit in the frame. + + Let's make a few changes to have our penguin display nicely + when the application opens. + + \snippet tutorials/penguin_advanced/modelview.cpp initialize + + First of all, let move the camera away from the penguin and up + so he fits in the frame and we can get a better angle on him, + when the application loads. + + If use dragging and so on in the QGLView this will change the + camera from these intial settings, but this setup means the camera + will be well positioned at the moment the application opens. + + We don't want to position the camera in the paintGL function, + because that would defeat QGLViews camera dragging features and + we would not be able to interact with the view properly. + + We'll also save the main object away in a member variable so that + the overhead of searching the scene is not incurred every paint. + + Finally a pose for our penguin is calculated - its a turn around the + x axis, so he is standing up on his feet; and a turn around the y + axis, so he shows a bit more of his profile. The pose is + calculated and stored as a quaternion - we want the x twist first + so that goes last in the product of the two quaternions. + + \snippet tutorials/penguin_advanced/modelview.cpp paint + + Now all that remains in the updated paint function is to apply the + new pose, and then paint the penguin. + + \image penguin-screenshot.png + + \l{qt3d-examples.html}{Return to Tutorials}. +*/ diff --git a/doc/src/tutorials/sceneformat.qdoc b/doc/src/tutorials/sceneformat.qdoc new file mode 100644 index 000000000..b16b60702 --- /dev/null +++ b/doc/src/tutorials/sceneformat.qdoc @@ -0,0 +1,115 @@ +/**************************************************************************** +** +** 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 Qt/3D + \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 Qt/3D. + + 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 Qt/3D + 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 Qt/3D 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 Qt/3D + 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}. +*/ diff --git a/doc/src/tutorials/shaders.qdoc b/doc/src/tutorials/shaders.qdoc new file mode 100644 index 000000000..55395e96e --- /dev/null +++ b/doc/src/tutorials/shaders.qdoc @@ -0,0 +1,388 @@ +/**************************************************************************** +** +** 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 Using GLSL shaders in QML/3D + \example tutorials/shaders + + + In this tutorial, we will show how to apply QML property animations to + GLSL shaders in a QML/3D application. + + Starting with a relatively simple shader program, we are going to + manipulate various parameters to explain how both the shader and the QML + integration work (This is quite a lot to start a tutorial with, but we'll + focus on each small piece of it in turn): + + \raw HTML + <table align="left" width="100%"> + <tr class="qt-code"><td> + \endraw + \quotefile tutorials/shaders/shader-tutorial.qml + \raw HTML + </td><td align="right"> + \endraw + \inlineimage tutorials/shader-tutorial.png + \raw HTML + </td></tr> + </table> + \endraw + + At the highest level, shaders in QML/3D are created using the ShaderProgram + element. The ShaderProgram element in this example has the id \a program, + and applying it to the teapot is as simple as assigning it to the \c effect + property of an Item3D derived element. + + The two most important properties of the ShaderProgram element are the + \c vertexShader and \c fragmentShader properties, which are strings + containing the code for the respective shader programs. Broadly speaking, + the vertex shader is run on each vertex in a model (for example, the 8 + corners of a cube) to calculate the final position of each point, while the + fragment shader is run on each pixel visible onscreen to calculate it's + color. + + The other attribute we use in this tutorial is the \c texture property. + This property is connected to the \c qt_Texture0 attribute in our shader + programs, and we'll cover how it's used shortly. + + \section1 Texture Coordinates and Textures (shader-tutorial-1-textures.qml) + + To start with, there are a couple of obvious problems with our starting + point - the Qt is upside down and back to front, and it's also boring + (before you ask, the reasons for the image being the wrong way around are + also boring). + + First, let's get the logo the right way up. The key here is the texture + coordinates. Let's look at it's declaration in the vertex shader for a + moment: \code attribute highp vec4 qt_MultiTexCoord0; \endcode + + The \c attribute declaration indicates that this is a per-vertex value + that we get from our model. Our teapot has a position, a normal, and + texture coordinates for each vertex, and qt3d automatically provides + these to us through the \c qt_Vertex, \c qt_MultiTexCoord0, and \c + qt_Normal attributes. (we don't care about normals until we get to + lighting). + + The \c mediump tag indicates that we want pretty good accuracy on this + attribute, but it doesn't need double precision. It's a hint for + embedded systems to save bandwidth (highp is usually used for positions, + and lowp is generally only suitable for colors, and the rule of thumb is + to use as little memory as you can get away with). + + \c vec4 indicates that the value is a 4-element vector. Our texture is + 2D, so we only care about the first two elements, but there are 3D + textures and cube maps out there. + + To fix the image's orientation we can simply reverse the sign when we + pass the texture coordinate to our fragment shader because the default + behaviour is for texture coordinates wrap around if they are higher than + 1.0 or lower than 0.0: + \code texCoord = -qt_MultiTexCoord0; \endcode + + In order to fix the boring, we're going to have to add a bit more QML + first. We need to add a property to our ShaderProgram element, and a + matching variable to the shader program. The types match up exactly + between QML and GLSL, but if the variables have the same name they + should automatically be hooked up, so we just add this to the + ShaderProgram element: + \code property real textureOffsetX : 1.0 + NumberAnimation on textureOffsetX + { + running: true; loops: Animation.Infinite + from: 0.0; to: 1.0; + duration: 1000 + } + \endcode + and we add this to the vertex shader: + \code uniform mediump float textureOffsetX; \endcode + + The final step is to work our new variable into the program, by changing + the texCoord assignment. We'll add our animated variable to our horizontal + texture coordinate, which will effectively scroll our texture around our + teapot: + \code + texCoord = vec4(-qt_MultiTexCoord0.s - textureOffsetX, + -qt_MultiTexCoord0.t, + 0,0); + \endcode + + Adding an additional texture is done by adding another uniform. The + ShaderProgram element interprets string properties as URIs for texture + resources, so adding a second texture is as easy as: + \code + property string texture2: "textures/basket.jpg" + \endcode + In order to have a smooth transition back and forth, we'll add and animate + a second property to use to blend the two textures: + \code + property real interpolationFactor : 1.0 + SequentialAnimation on interpolationFactor + { + running: true; loops: Animation.Infinite + NumberAnimation { + from: 0.0; to: 1.0; + duration: 2000 + } + PauseAnimation { duration: 500 } + NumberAnimation { + from: 1.0; to: 0.0; + duration: 2000 + } + PauseAnimation { duration: 500 } + } + \endcode + + Next we need to use all of that information in the fragment shader: + \code + varying highp vec4 texCoord; + uniform sampler2D qt_Texture0; + uniform sampler2D texture2; + uniform mediump float interpolationFactor; + + void main(void) + { + mediump vec4 texture1Color = texture2D(qt_Texture0, texCoord.st); + mediump vec4 texture2Color = texture2D(texture2, texCoord.st); + mediump vec4 textureColor = mix(texture1Color, texture2Color, + interpolationFactor); + gl_FragColor = textureColor; + } + \endcode + + In general, textures needs to have the same name in the shaders as in the + ShaderProgram element in order to be automatically connected, but \c + qt_Texture0 is special cased and very slightly faster, so it's good to use + it first. + + \c mix() is another handy built in GLSL function that interpolates linearly + between two values or vectors. (You can find details of all the built in + functions in the official OpenGL Shader Language specification available at + http://www.khronos.org/opengl/ ) + + Finally, let's make one more change to make this example pop. If you're + a performance fanatic, it just might have rankled that we padded out our + texture coordinates with two zeros, and passed them in for processing + on every single pixel of our teapot. + + Let's make use of that space by putting a second set of co-ordinates in + there to use with our second texture. Let's change our texture assignment + to this: + \code + texCoord.st = vec2(-qt_MultiTexCoord0.s - textureOffsetX, + -qt_MultiTexCoord0.t); + texCoord.pq = vec2(-qt_MultiTexCoord0.s + textureOffsetX, + -qt_MultiTexCoord0.t); + \endcode + Now the top half of our vector contains co-ordianates spinning in the + opposite direction. Back in the fragment shader, we just need use these + instead for our second texture color, so let's change the \c texture2Color + assignment to this, and really fix that boring: + \code + mediump vec4 texture2Color = texture2D(texture2, texCoord.pq); + \endcode + + \section1 Varying values (shader-tutorial-varying.qml) + + The left hand side value is our \c varying attribute \c texCoord. + \c varying values are how the vertex shader communicates with the + fragment shader, and the declaration has to be identical in both shaders. + \c varying values are calculated once for each + vertex, but the values are interpolated across the shapes. The + shader-tutorial-varying.qml shows this visually using the Pane + class and a neat debugging trick - using the texture coordinates as + a color. Even with only 4 vertexes the texture coordinates are smeared + smoothly across the shape: + \table + \row + \o \code gl_FragColor = vec4(mod(texCoord.x, 1.0), + mod(texCoord.y, 1.0), 0.0, 1.0); \endcode + \o + \o \image tutorials/shader-tutorial-varying.png + \endtable + + + \section1 Vertexes and Matrices (shader-tutorial-2-vertex-shader.qml) + + Let's go back to the vertex shader. As already mentioned, the + vertex shader's primary function is to generate the final position of a + vertex. + + First, let's look at \c qt_Vertex. This is the value we're getting out + of our model, the actual points on our shape. Manipulating this value + will lets us change the position of the points somewhat independantly. + + For this tutorial, we'll create a squashing effect that might work for + something rising out of water, or something rubbery being squashed down. + + What we need to do is create a floor, where vertexes above the floor + retain their position, and vertexes below it are clamped to (nearly) that + value. Then we move the model relative to this floor to create a nice + effect. + + We need to use some knowledge that we have about the model for this to + work - most notably it's height, and it's bottom. A bit of experimenting + suggests that 2.0 for height and -1.0 for bottom are close enough. + + We need to introduce a couple more GLSL things here. \c max() is one of + the GL SL built in functions, selecting the higher of the two arguments as + you might expect. + + The \c foo.xyzw are called \i twiddles, and are + convenient and efficient ways to pull out specific elements of vector + areguments. You can see in this example, that we use twiddles to get out + the x, z, and w values from our original vector and substitute in our own + y value. For convenience, there are 3 different sets of twiddles that are + all equivalent: foo.xyzw (co-ordinates), foo.rgba (colors), and + foo.stpq (texture coordinates). As far as GLSL is concerned, though, + they're just vectors, and effectively just commenting your code. + + The \c vec4() function will accept whatever combination of values and + twiddles you throw at it, and mold them back into a 4 element vector. + + What this function is doing is moving the model down the screen (which for + us, here, is along the y axis in the negative direction). + We draw an imaginary line where the bottom of the model used to be, and if + the vertex ends up below that line, we move it back to just past the line. + + "Just past" is important. Graphics cards get confused if vertexes are too + close together, and the result is ugly. Try taking out the + "\c {qt_Vertex.y * 0.01}" if you'd like to see what it looks like. + + \code + float newY = max(qt_Vertex.y - squashFactor * modelSize, + qt_Vertex.y * 0.01 + modelBottom); + \endcode + + + \code + const float modelSize = 2.0; + const float modelBottom = -1.0; + float newY = max(qt_Vertex.y - squashFactor * modelSize, + qt_Vertex.y * 0.01 + modelBottom); + + gl_Position = qt_ModelViewProjectionMatrix * + vec4(qt_Vertex.x, newY, qt_Vertex.zw); + \endcode + + Hopefully, that makes the function of the \c qt_Vertex attribute clear, so + next we'll look at the Model/View/Projection matrices. + + The model matrix is generally used to place an object in a scene. In the + simplest case, this might just be "up and to the left a bit", but it's + often inherited from a parent. It's very easy mathematically to combine + the matrices in such a way that one object is always in the same relative + position to another ("The hip bones connected to the thigh bone"). + + The view matrix is generally used much like a camera is in a movie, for + panning around a whole scene at once. Manipulating the view matrix is also + commonly used for effects like mirrors. + + The projection matrix (\c qt_ProjectionMatrix) functions much like a + camera does when you take a + picture, converting all the 3d points in a scene into the 2d points on the + screen. + + We won't be exploring the matrices individually, but let's explore what + happens if we use the same effect that we just used on the vertex after + the transformation matrices are applied. + + Firstly, we're going to need multiple teapots to see the difference, so + let's add those in. We want to move them all together, so we'll wrap + them in an Item3D, and apply our animations to that item instead of + the teapots directly. + \code + + Item3D { + z: -8.0 + transform: [ + Rotation3D { + NumberAnimation on angle { + running: true; loops: Animation.Infinite + from: 0; to: 360; duration: 5000 + } + axis: Qt.vector3d(0, 0, 1.0) + } + ] + + TutorialTeapot {id: teapot1; effect: program; y:2.0; x:0.0} + TutorialTeapot {id: teapot2; effect: program; y:-1.0; x:-1.732} + TutorialTeapot {id: teapot3; effect: program; y:-1.0; x:1.732} + } + \endcode + + In order to show the difference, what we want to do now is the same sort + of effect as the previous example, only applied to the positions after + the matrices have been applied, so our new vertex shader looks like this: + \code + attribute highp vec4 qt_Vertex; + uniform mediump mat4 qt_ModelViewProjectionMatrix; + + attribute mediump vec4 qt_MultiTexCoord0; + varying mediump vec4 texCoord; + + void main(void) + { + const float modelBottom = -4.0; + + vec4 workingPosition = qt_ModelViewProjectionMatrix * qt_Vertex; + float newY = max(workingPosition.y, + workingPosition.y * 0.15 + modelBottom); + workingPosition.y = newY; + gl_Position = workingPosition; + + texCoord = -qt_MultiTexCoord0; + } + \endcode + + There's nothing new here, we're just tweaking a few numbers for the new + effect and manipulating the vertexes after the matrices have been applied. + The result is an imaginary line across the whole scene, and when any part + of any teapot dips below that line we deform it as though it's being + squished or refracted. + + The obvious difference is that when you're manipulating \c qt_Vertex, + the inputs, outputs, and changes are relative to the model. After the + matrices are applied, + + We'll leave adding a pretty watery surface as an exercise for the reader. + + + + \section1 Lighting + + Finally, we'll add lighting. We've left lighting till last because it + requires a lot of additional variables, and it is not within the scope of + this tutorial to explore them all individually. There are many better + resources readily available, and the techniques already covered can be + used to explore each element. + + + For further reading, the full specification for the OpenGL Shader Language + is available from the Khronos website at http://www.khronos.org/opengl/ + + \l{qt3d-examples.html}{Return to the main Tutorials page}. +*/ diff --git a/doc/src/tutorials/simpleobject.qdoc b/doc/src/tutorials/simpleobject.qdoc new file mode 100644 index 000000000..07f14c788 --- /dev/null +++ b/doc/src/tutorials/simpleobject.qdoc @@ -0,0 +1,101 @@ +/**************************************************************************** +** +** 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 Applying transformations and materials to objects + \example tutorials/cube4 + + In this tutorial we will apply transformations and materials to a + simple cube object to demonstrate how to modify the QGLPainter + state to achieve different effects. We start by declaring a + view class to show our cube on the screen: + + \snippet tutorials/cube1/cubeview.h 1 + + QGLView provides most of the logic for initializing the view, + setting the camera position, and handling navigation via + keyboard and mouse events. In the constructor we use + QGLBuilder to create the geometry for the cube object that + we will be using in later steps: + + \snippet tutorials/cube1/cubeview.cpp 1 + + Then it is a simple matter to draw the object in our \c{paintGL()} + method: + + \snippet tutorials/cube1/cubeview.cpp 2 + + If we run the program now, we get the following output, which isn't + very cube-like: + + \image tutorials/cube1-screenshot.png + + The problem is that we are looking at the cube straight onto its + front face. So the rest of the cube is hidden from our view and + it looks like a square. Let's modify the modelview transformation + matrix a little bit to apply a 45 degree rotation around the + axis (1, 1, 1): + + \snippet tutorials/cube2/cubeview.cpp 2 + + Now the results are a little better: + + \image tutorials/cube2-screenshot.png + + The cube is still a little odd-looking however. This is because + up until now we have been using the default flat color effect + in QGLPainter that colors the faces with a uniform color + (white in this case). So let's change to a lit material effect + with a nice green color: + + \snippet tutorials/cube3/cubeview.cpp 2 + + That's much better; now it looks like a cube: + + \image tutorials/cube3-screenshot.png + + To complete this tutorial, let's make the cube a little more + interesting by adding a texture to the side: + + \snippet tutorials/cube4/cubeview.h 1 + \dots + \snippet tutorials/cube4/cubeview.h 2 + \snippet tutorials/cube4/cubeview.cpp 1 + \dots + \snippet tutorials/cube4/cubeview.cpp 2 + \snippet tutorials/cube4/cubeview.cpp 3 + + \image tutorials/cube4-screenshot.png + + \section2 Cube in QML/3D + + It is quite simple to achieve the same effect in QML: + + \snippet tutorials/cube4/cube.qml 1 + + \l{qt3d-examples.html}{Return to the main Tutorials page}. +*/ |
