summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLaszlo Agocs <laszlo.agocs@qt.io>2018-05-11 14:27:42 +0200
committerLaszlo Agocs <laszlo.agocs@qt.io>2018-05-14 10:55:25 +0000
commit576d6dc5166cc68a6fd07bec3f09ee41bf8f6d6d (patch)
treeb9cdca0252f62e4ec267e6dc531e8f584676b2fe
parentbc55de17a036c68cd6755280e216c144c4505a0f (diff)
more API docs
Also pull in the property name table (the up-to-dateness of which is questionable). The version number in the generated docs should be 2.0, not the Qt version. Will need to figure out later how to maintain this. Not everything is documented yet. Less important functions will get covered later. Many bits here and there are revised compared to the 1.1 docs. There are however chunks that have been taken as-is. These need to be cleaned up later on. Most importantly, an initial Getting Started page has been added. This, like the mobile/embedded page needs to be extended signficiantly later on. A set of unused constructors (the ones taking no presentation) are removed from Q3DSElement/SceneElement/DataInput. This is because the QML API does not use them while it is impossible to utilize these in a meaningful way from C++ (where are require setting the presentation up-front with no setter afterwards). There were a few qdoc warnings from the internal implementations due to useless /*! or backslashes that confused qdoc. These are removed. Task-number: QT3DS-1606 Change-Id: I141bdc774e5be3e4fed5c1d729cac9b68a02be3b Reviewed-by: Andy Nichols <andy.nichols@qt.io>
-rw-r--r--src/imports/studio3d/q3dsstudio3ditem.cpp81
-rw-r--r--src/imports/studio3d/q3dssubpresentationsettings.cpp82
-rw-r--r--src/runtime/api/q3dsdatainput.cpp87
-rw-r--r--src/runtime/api/q3dsdatainput.h1
-rw-r--r--src/runtime/api/q3dselement.cpp138
-rw-r--r--src/runtime/api/q3dselement.h1
-rw-r--r--src/runtime/api/q3dspresentation.cpp356
-rw-r--r--src/runtime/api/q3dssceneelement.cpp214
-rw-r--r--src/runtime/api/q3dssceneelement.h1
-rw-r--r--src/runtime/api/q3dssurfaceviewer.cpp139
-rw-r--r--src/runtime/api/q3dsviewersettings.cpp51
-rw-r--r--src/runtime/api/q3dswidget.cpp53
-rw-r--r--src/runtime/behaviorapi/q3dsbehaviorobject.cpp166
-rw-r--r--src/runtime/doc/Qt3DStudioRuntime2.qdocconf (renamed from src/doc/Qt3DStudioRuntime2.qdocconf)0
-rw-r--r--src/runtime/doc/doc.pri (renamed from src/doc/doc.pro)2
-rw-r--r--src/runtime/doc/online/Qt3DStudioRuntime2.qdocconf (renamed from src/doc/online/Qt3DStudioRuntime2.qdocconf)0
-rw-r--r--src/runtime/doc/qt3d-runtime-project.qdocconf (renamed from src/doc/qt3d-runtime-project.qdocconf)25
-rw-r--r--src/runtime/doc/src/attributenames.html1099
-rw-r--r--src/runtime/doc/src/attributenames.qdoc42
-rw-r--r--src/runtime/doc/src/copyright.qdoc (renamed from src/doc/src/copyright.qdoc)0
-rw-r--r--src/runtime/doc/src/embedded.qdoc (renamed from src/doc/src/embedded.qdoc)1
-rw-r--r--src/runtime/doc/src/examples.qdoc (renamed from src/doc/src/examples.qdoc)0
-rw-r--r--src/runtime/doc/src/gettingstarted.qdoc78
-rw-r--r--src/runtime/doc/src/index.qdoc (renamed from src/doc/src/index.qdoc)7
-rw-r--r--src/runtime/doc/src/mobile.qdoc (renamed from src/doc/src/mobile.qdoc)1
-rw-r--r--src/runtime/doc/src/module.qdoc (renamed from src/doc/src/module.qdoc)0
-rw-r--r--src/runtime/doc/src/toc.qdoc (renamed from src/doc/src/gettingstarted.qdoc)13
-rw-r--r--src/runtime/doc/style/qt5-sidebar.html (renamed from src/doc/style/qt5-sidebar.html)0
-rw-r--r--src/runtime/q3dsscenemanager.cpp4
-rw-r--r--src/runtime/q3dsuippresentation.cpp4
-rw-r--r--src/runtime/runtime.pro2
-rw-r--r--src/src.pro3
32 files changed, 2594 insertions, 57 deletions
diff --git a/src/imports/studio3d/q3dsstudio3ditem.cpp b/src/imports/studio3d/q3dsstudio3ditem.cpp
index 2326d1f..fe0bc3c 100644
--- a/src/imports/studio3d/q3dsstudio3ditem.cpp
+++ b/src/imports/studio3d/q3dsstudio3ditem.cpp
@@ -58,9 +58,67 @@ QT_BEGIN_NAMESPACE
\inqmlmodule QtStudio3D
\ingroup 3dstudioruntime2
\inherits Item
- \brief blah
- blah
+ \brief Qt 3D Studio presentation viewer.
+
+ This type enables developers to embed Qt 3D Studio presentations in Qt
+ Quick.
+
+ \section2 Example usage
+
+ \qml
+ Studio3D {
+ id: studio3D
+ Presentation {
+ source: "qrc:///presentation.uia"
+ SceneElement {
+ id: scene
+ elementPath: "Scene"
+ currentSlideIndex: 2
+ }
+ Element {
+ id: textLabel
+ elementPath: "Scene.Layer.myLabel"
+ }
+ }
+ ViewerSettings {
+ showRenderStats: true
+ }
+ onRunningChanged: {
+ console.log("Presentation ready!");
+ }
+ }
+ \endqml
+*/
+
+/*!
+ \qmlsignal Studio3D::frameUpdate()
+
+ This signal is emitted each time a frame has been updated regardless of
+ visibility. This allows a hidden Studio3D element to still process
+ information every frame, even though the renderer is not rendering.
+
+ The corresponding handler is \c onFrameUpdate.
+
+ To prevent expensive handlers from being processed when hidden, add an
+ early return to the top like:
+
+ \qml
+ onFrameUpdate: {
+ if (!visible) return;
+ ...
+ }
+ \endqml
+*/
+
+/*!
+ \qmlsignal Studio3D::presentationReady()
+
+ This signal is emitted when the viewer has been initialized and the
+ presentation is ready to be shown. The difference to \c running property is
+ that the viewer has to be visible for \c running to get \c{true}. This
+ signal is useful for displaying splash screen while viewer is getting
+ initialized.
*/
static bool engineCleanerRegistered = false;
@@ -94,11 +152,30 @@ Q3DSStudio3DItem::~Q3DSStudio3DItem()
{
}
+/*!
+ \qmlproperty Presentation Studio3D::presentation
+
+ Accessor for the presentation. Applications are expected to create a single
+ Presentation child object for Studio3D. If this is omitted, a presentation
+ is created automatically.
+
+ This property is read-only.
+*/
+
Q3DSPresentationItem *Q3DSStudio3DItem::presentation() const
{
return m_presentation;
}
+/*!
+ \qmlproperty bool Studio3D::running
+
+ The value of this property is \c true when the viewer has been initialized
+ and the presentation is running.
+
+ This property is read-only.
+*/
+
bool Q3DSStudio3DItem::isRunning() const
{
return m_running;
diff --git a/src/imports/studio3d/q3dssubpresentationsettings.cpp b/src/imports/studio3d/q3dssubpresentationsettings.cpp
index 0eabd1f..e8ffcea 100644
--- a/src/imports/studio3d/q3dssubpresentationsettings.cpp
+++ b/src/imports/studio3d/q3dssubpresentationsettings.cpp
@@ -47,4 +47,86 @@ QQmlListProperty<Q3DSInlineQmlSubPresentation> Q3DSSubPresentationSettings::qmlS
return QQmlListProperty<Q3DSInlineQmlSubPresentation>(this, m_list);
}
+/*!
+ \qmltype SubPresentationSettings
+ \inqmlmodule QtStudio3D
+ \ingroup 3dstudioruntime2
+ \brief Settings for sub-presentations.
+
+ This type enables specifying a QML sub-presentation directly in the QML.
+
+ A QML sub-presentation is a Qt Quick scene that is rendered to a texture
+ and then used either as the contents of Qt 3D Studio layer or as a texture
+ map. The contents of such a sub-presentation can be provided in two ways:
+ by a separate \c{.qml} file, or directly under the Studio3D element.
+ SubPresentationSettings is the enabler for the latter.
+
+ \section2 Usage
+
+ \qml
+ Studio3D {
+ id: studio3D
+ Presentation {
+ source: "file:///presentation.uia"
+ SubPresentationSettings {
+ qmlStreams: [
+ QmlStream {
+ presentationId: "sub-presentation-id"
+ Item {
+ width: 1024
+ height: 1024
+ // ... other Qt Quick items
+ }
+ }
+ ]
+ }
+ }
+ }
+ \endqml
+ */
+
+/*!
+ \qmlproperty list<QmlStream> SubPresentationSettings::qmlStreams
+
+ Holds the list of QmlStream children.
+ */
+
+/*!
+ \qmltype QmlStream
+ \inqmlmodule QtStudio3D
+ \ingroup 3dstudioruntime2
+ \brief QML stream.
+
+ This type allows attaching QML sub-presentation with a quick item. The item is rendered to a
+ texture and used as a part of a Qt 3D Studio presentation.
+
+ The sub-presentation element must be specified in the \e assets element of the presentation
+ .uia file:
+
+ \badcode
+ <assets ...>
+ <presentation-qml id="presentation-id" args="preview-presentation.qml" />
+ </assets>
+ \endcode
+
+ The \c presentation-id attribute must contain a unique ID of the sub-presentation.
+ The \c args attribute may contain an optional preview version of the item, which is only
+ used in the Viewer application.
+ */
+
+/*!
+ \qmlproperty string QmlStream::presentationId
+
+ Holds the string ID of the sub-presentation the item is attached to. The id must be one of
+ the \c presentation-qml IDs specified in the .uia file.
+ */
+
+/*!
+ \qmlproperty Item QmlStream::item
+
+ Holds the item attached to the sub-presentation. The item size is used as the the size of the
+ texture the item is rendered to. Default values \c{(256, 256)} are used if the item doesn't
+ specify a size.
+ */
+
QT_END_NAMESPACE
diff --git a/src/runtime/api/q3dsdatainput.cpp b/src/runtime/api/q3dsdatainput.cpp
index 9341c04..69cafe3 100644
--- a/src/runtime/api/q3dsdatainput.cpp
+++ b/src/runtime/api/q3dsdatainput.cpp
@@ -32,18 +32,31 @@
QT_BEGIN_NAMESPACE
-Q3DSDataInput::Q3DSDataInput(QObject *parent)
- : QObject(*new Q3DSDataInputPrivate, parent)
-{
-}
+/*!
+ \class Q3DSDataInput
+ \inmodule 3dstudioruntime2
+ \since Qt 3D Studio 2.0
+
+ \brief Controls a data input entry in a Qt 3D Studio presentation.
+
+ This class is a convenience class for controlling a data input in a presentation.
-Q3DSDataInput::Q3DSDataInput(const QString &name, QObject *parent)
+ \sa Q3DSPresentation
+*/
+
+/*!
+ \internal
+ */
+Q3DSDataInput::Q3DSDataInput(QObject *parent)
: QObject(*new Q3DSDataInputPrivate, parent)
{
- Q_D(Q3DSDataInput);
- d->name = name;
}
+/*!
+ Constructs a Q3DSDataInput instance and initializes the \a name. The
+ constructed instance is automatically associated with the specified \a
+ presentation. An optional \a parent object can be specified.
+ */
Q3DSDataInput::Q3DSDataInput(Q3DSPresentation *presentation, const QString &name, QObject *parent)
: QObject(*new Q3DSDataInputPrivate, parent)
{
@@ -52,15 +65,29 @@ Q3DSDataInput::Q3DSDataInput(Q3DSPresentation *presentation, const QString &name
d->presentation = presentation;
}
+/*!
+ \internal
+ */
Q3DSDataInput::Q3DSDataInput(Q3DSDataInputPrivate &dd, QObject *parent)
: QObject(dd, parent)
{
}
+/*!
+ Destructor.
+ */
Q3DSDataInput::~Q3DSDataInput()
{
}
+/*!
+ \property Q3DSDataInput::name
+
+ Specifies the name of the controlled data input element in the
+ presentation. This property must be set before setting the value property.
+ The initial value is provided via the constructor in practice, but the name
+ can also be changed later on, if desired.
+ */
QString Q3DSDataInput::name() const
{
Q_D(const Q3DSDataInput);
@@ -76,6 +103,19 @@ void Q3DSDataInput::setName(const QString &name)
}
}
+/*!
+ \property Q3DSDataInput::value
+
+ Specifies the value of the controlled data input element in the
+ presentation.
+
+ The value of this property only accounts for changes done via the same
+ Q3DSDataInput instance. If the value of the same data input in the
+ presentation is changed elsewhere, for example via presentation scripting,
+ those changes are not reflected in the value of this property. Due to this
+ uncertainty, this property treats all value sets as changes even if the
+ newly set value is the same value as the previous value.
+*/
QVariant Q3DSDataInput::value() const
{
Q_D(const Q3DSDataInput);
@@ -104,4 +144,37 @@ void Q3DSDataInputPrivate::sendValue()
presentation->setDataInputValue(name, value);
}
+/*!
+ \qmltype DataInput
+ \instantiates Q3DSDataInput
+ \inqmlmodule QtStudio3D
+ \ingroup 3dstudioruntime2
+ \brief Control type for data inputs in a Qt 3D Studio presentation.
+
+ This type is a convenience type for controlling a data input in a presentation.
+
+ \sa Studio3D, Presentation
+*/
+
+/*!
+ \qmlproperty string DataInput::name
+
+ Specifies the name of the controlled data input element in the presentation.
+ This property must be set as part of DataInput declaration.
+*/
+
+/*!
+ \qmlproperty variant DataInput::value
+
+ Specifies the value of the controlled data input element in the presentation.
+ The changes to the value property are queued and handled asynchronously before the
+ next frame is displayed.
+
+ The value of this property only accounts for changes done via the same DataInput instance.
+ If the value of the same data input in the presentation is changed elsewhere,
+ for example via presentation scripting, those changes are not reflected in
+ the value of this property. Due to this uncertainty, this property treats all value sets as
+ changes even if the newly set value is the same value as the previous value.
+*/
+
QT_END_NAMESPACE
diff --git a/src/runtime/api/q3dsdatainput.h b/src/runtime/api/q3dsdatainput.h
index e685f78..c869c9e 100644
--- a/src/runtime/api/q3dsdatainput.h
+++ b/src/runtime/api/q3dsdatainput.h
@@ -52,7 +52,6 @@ class Q3DSV_EXPORT Q3DSDataInput : public QObject
public:
explicit Q3DSDataInput(QObject *parent = nullptr);
- explicit Q3DSDataInput(const QString &name, QObject *parent = nullptr);
Q3DSDataInput(Q3DSPresentation *presentation, const QString &name, QObject *parent = nullptr);
~Q3DSDataInput();
diff --git a/src/runtime/api/q3dselement.cpp b/src/runtime/api/q3dselement.cpp
index ae119ae..3e72e83 100644
--- a/src/runtime/api/q3dselement.cpp
+++ b/src/runtime/api/q3dselement.cpp
@@ -32,18 +32,38 @@
QT_BEGIN_NAMESPACE
+/*!
+ \class Q3DSElement
+ \inmodule 3dstudioruntime2
+ \since Qt 3D Studio 2.0
+
+ \brief Controls a scene object in a Qt 3D Studio presentation.
+
+ This class is a convenience class for controlling the properties of a scene
+ object (such as, model, material, camera, layer) in a Qt 3D Studio
+ presentation.
+
+ \note The functionality of Q3DSElement is equivalent to
+ Q3DSPresentation::setAttribute(), Q3DSPresentation::getAttribute(), and
+ Q3DSPresentation::fireEvent().
+
+ \sa Q3DSPresentation, Q3DSWidget, Q3DSSurfaceViewer, Q3DSSceneElement
+ */
+
+/*!
+ \internal
+ */
Q3DSElement::Q3DSElement(QObject *parent)
: QObject(*new Q3DSElementPrivate, parent)
{
}
-Q3DSElement::Q3DSElement(const QString &elementPath, QObject *parent)
- : QObject(*new Q3DSElementPrivate, parent)
-{
- Q_D(Q3DSElement);
- d->elementPath = elementPath;
-}
-
+/*!
+ Constructs a Q3DSElement instance controlling the scene object specified by
+ \a elementPath. An optional \a parent object can be specified. The
+ constructed instance is automatically associated with the specified \a
+ presentation. An optional \a parent object can be specified.
+ */
Q3DSElement::Q3DSElement(Q3DSPresentation *presentation, const QString &elementPath, QObject *parent)
: QObject(*new Q3DSElementPrivate, parent)
{
@@ -52,15 +72,47 @@ Q3DSElement::Q3DSElement(Q3DSPresentation *presentation, const QString &elementP
d->presentation = presentation;
}
+/*!
+ \internal
+ */
Q3DSElement::Q3DSElement(Q3DSElementPrivate &dd, QObject *parent)
: QObject(dd, parent)
{
}
+/*!
+ Destructor.
+ */
Q3DSElement::~Q3DSElement()
{
}
+/*!
+ \property Q3DSElement::elementPath
+
+ Holds the element path of the presentation element.
+
+ An element path refers to an object in the scene either by name or id. The
+ latter is rarely used in application code since the unique IDs are not
+ exposed in the Qt 3D Studio application. To refer to an object by id,
+ prepend \c{#} to the name. Applications will typically refer to objects by
+ name.
+
+ Names are not necessarily unique, however. To access an object with a
+ non-unique name, the path can be specified, for example,
+ \c{Scene.Layer.Camera}. Here the right camera object gets chosen even if
+ the scene contains other layers with the default camera names (for instance
+ \c{Scene.Layer2.Camera}).
+
+ If the object is renamed to a unique name in the Qt 3D Studio application's
+ Timeline view, the path can be omitted. For example, if the camera in
+ question was renamed to \c MyCamera, applications can then simply pass \c
+ MyCamera as the element path.
+
+ To access an object in a sub-presentation, prepend the name of the
+ sub-presentation followed by a colon, for example,
+ \c{SubPresentationOne:Scene.Layer.Camera}.
+ */
QString Q3DSElement::elementPath() const
{
Q_D(const Q3DSElement);
@@ -76,6 +128,12 @@ void Q3DSElement::setElementPath(const QString &elementPath)
}
}
+/*!
+ Returns the current value of an attribute (property) of the scene
+ object specified by elementPath.
+
+ The \a attributeName is the \l{Attribute Names}{scripting name} of the attribute.
+ */
QVariant Q3DSElement::getAttribute(const QString &attributeName) const
{
Q_D(const Q3DSElement);
@@ -85,6 +143,12 @@ QVariant Q3DSElement::getAttribute(const QString &attributeName) const
return QVariant();
}
+/*!
+ Sets the \a value of an attribute (property) of the scene object
+ specified by elementPath.
+
+ The \a attributeName is the \l{Attribute Names}{scripting name} of the attribute.
+ */
void Q3DSElement::setAttribute(const QString &attributeName, const QVariant &value)
{
Q_D(Q3DSElement);
@@ -92,6 +156,14 @@ void Q3DSElement::setAttribute(const QString &attributeName, const QVariant &val
d->presentation->setAttribute(d->elementPath, attributeName, value);
}
+/*!
+ Dispatches an event with \a eventName on the scene object
+ specified by elementPath.
+
+ Appropriate actions created in Qt 3D Studio or callbacks registered using
+ the registerForEvent() method in attached (behavior) scripts will be
+ executed in response to the event.
+ */
void Q3DSElement::fireEvent(const QString &eventName)
{
Q_D(Q3DSElement);
@@ -104,4 +176,56 @@ void Q3DSElementPrivate::setPresentation(Q3DSPresentation *pres)
presentation = pres;
}
+/*!
+ \qmltype Element
+ \instantiates Q3DSElement
+ \inqmlmodule QtStudio3D
+ \ingroup 3dstudioruntime2
+ \brief Control type for elements in a Qt 3D Studio presentation.
+
+ This type is a convenience type for managing a presentation element.
+
+ All methods provided by this type are queued and handled asynchronously before the next
+ frame is displayed.
+
+ \sa Studio3D, Presentation, SceneElement
+*/
+
+/*!
+ \qmlproperty string Element::elementPath
+
+ Holds the element path of the presentation element.
+ This property must be set as part of Element declaration.
+ You can specify an element of a sub-presentation by adding "SubPresentationId:"
+ in front of the element path, for example \c{"SubPresentationOne:Scene"}.
+*/
+
+/*!
+ \qmlmethod void Element::setAttribute(string attributeName, variant value)
+
+ Sets the \a value of an attribute on an element specified by this instance.
+ The \a attributeName is the \l{Attribute Names}{scripting name} of the attribute.
+
+ The attribute must be preserved for scripting to be set by this function, or else it will fail.
+ An attribute is preserved if it is either \e{animated}, or
+ \e{an attribute on a master element that is unlinked and changed per-slide}.
+*/
+
+/*!
+ \qmlmethod void Element::fireEvent(string eventName)
+
+ Dispatches an event with \a eventName on the element specified by this instance.
+ Appropriate actions created in Qt 3D Studio or callbacks registered using the registerForEvent()
+ method in attached scripts will be executed in response to the event.
+*/
+
+/*!
+ \qmlsignal Element::elementPathChanged(string elementPath)
+
+ This signal is emitted when the element path property changes.
+ The new value is provided in the \a elementPath parameter.
+
+ The corresponding handler is \c onElementPathChanged.
+*/
+
QT_END_NAMESPACE
diff --git a/src/runtime/api/q3dselement.h b/src/runtime/api/q3dselement.h
index ec62590..7e5d0b8 100644
--- a/src/runtime/api/q3dselement.h
+++ b/src/runtime/api/q3dselement.h
@@ -51,7 +51,6 @@ class Q3DSV_EXPORT Q3DSElement : public QObject
public:
explicit Q3DSElement(QObject *parent = nullptr);
- explicit Q3DSElement(const QString &elementPath, QObject *parent = nullptr);
Q3DSElement(Q3DSPresentation *presentation, const QString &elementPath, QObject *parent = nullptr);
~Q3DSElement();
diff --git a/src/runtime/api/q3dspresentation.cpp b/src/runtime/api/q3dspresentation.cpp
index 0f0cf89..0a797b2 100644
--- a/src/runtime/api/q3dspresentation.cpp
+++ b/src/runtime/api/q3dspresentation.cpp
@@ -31,6 +31,40 @@
QT_BEGIN_NAMESPACE
+/*!
+ \class Q3DSPresentation
+ \inmodule 3dstudioruntime2
+ \since Qt 3D Studio 2.0
+
+ \brief Represents a Qt 3D Studio presentation.
+
+ This class provides properties and methods for controlling a
+ presentation.
+
+ Qt 3D Studio supports multiple presentations in one project. There
+ is always a main presentation and zero or more
+ sub-presentations. The sub-presentations are composed into the
+ main presentations either as contents of Qt 3D Studio layers or as
+ texture maps.
+
+ In the filesystem each presentation corresponds to one \c{.uip}
+ file. When present, the \c{.uia} file ties these together by
+ specifying a name for each of the (sub-)presentations and
+ specifies which one is the main one.
+
+ From the API point of view Q3DSPresentation corresponds to the
+ main presentation. The source property can refer either to a
+ \c{.uia} or \c{.uip} file. When specifying a file with \c{.uip}
+ extension and a \c{.uia} is present with the same name, the
+ \c{.uia} is loaded automatically and thus sub-presentation
+ information is available regardless.
+
+ \note This class should not be instantiated directly when working with the
+ C++ APIs. Q3DSSurfaceViewer and Q3DSWidget create a Q3DSPresentation
+ instance implicitly. This can be queried via
+ Q3DSSurfaceViewer::presentation() or Q3DSWidget::presentation().
+ */
+
// Unlike in 3DS1, Q3DSPresentation here does not own the engine. This is due
// to the delicate lifetime management needs due to Qt 3D under the hood: for
// instance the Studio3D element has to carefully manage the underlying
@@ -40,20 +74,41 @@ QT_BEGIN_NAMESPACE
// Q3DSPresentationController (for common functionality), or individually by
// Studio3D, Q3DSWidget, or Q3DSSurfaceViewer.
+/*!
+ Constructs a new Q3DSPresentation with the given \a parent.
+ */
Q3DSPresentation::Q3DSPresentation(QObject *parent)
: QObject(*new Q3DSPresentationPrivate, parent)
{
}
+/*!
+ \internal
+ */
Q3DSPresentation::Q3DSPresentation(Q3DSPresentationPrivate &dd, QObject *parent)
: QObject(dd, parent)
{
}
+/*!
+ Destructor.
+ */
Q3DSPresentation::~Q3DSPresentation()
{
}
+/*!
+ \property Q3DSPresentation::source
+
+ Holds the name of the main presentation file (\c{*.uia} or
+ \c{*.uip}). This may be either a local file or qrc URL.
+
+ The names of all further assets (image files for texture maps, qml
+ behavior scripts, mesh files) will be resolved relative to the
+ location of the presentation, unless they use absolute paths. This
+ allows bundling all assets next to the presentation in the Qt
+ resource system.
+*/
QUrl Q3DSPresentation::source() const
{
Q_D(const Q3DSPresentation);
@@ -128,6 +183,9 @@ void Q3DSPresentation::setProfileUiScale(float scale)
}
}
+/*!
+ Reloads the presentation.
+ */
void Q3DSPresentation::reload()
{
Q_D(Q3DSPresentation);
@@ -135,6 +193,21 @@ void Q3DSPresentation::reload()
d->controller->handlePresentationReload();
}
+/*!
+ Sets the \a value of a data input element \a name in the presentation.
+
+ Data input provides a higher level, designer-driven alternative to
+ Q3DSElement and setAttribute(). Instead of exposing a large set of
+ properties with their intenal engine names, data input allows designers to
+ decide which properties should be writable by the application, and can
+ assign custom names to these data input entries, thus forming a
+ well-defined contract between the designer and the developer.
+
+ In addition, data input also allows controlling the time line and the
+ current slide for time context objects (Scene or Component). Therefore it
+ is also an alternative to the goToSlide() and goToTime() family of APIs and
+ to Q3DSSceneElement.
+ */
void Q3DSPresentation::setDataInputValue(const QString &name, const QVariant &value)
{
Q_D(Q3DSPresentation);
@@ -142,6 +215,14 @@ void Q3DSPresentation::setDataInputValue(const QString &name, const QVariant &va
d->controller->handleDataInputValue(name, value);
}
+/*!
+ Dispatches an event with \a eventName on a specific element found in \a
+ elementPath. Appropriate actions created in Qt 3D Studio or callbacks
+ registered using the registerForEvent() method in attached (behavior)
+ scripts will be executed in response to the event.
+
+ See setAttribute() for a description of \a elementPath.
+ */
void Q3DSPresentation::fireEvent(const QString &elementPath, const QString &eventName)
{
Q_D(Q3DSPresentation);
@@ -149,6 +230,32 @@ void Q3DSPresentation::fireEvent(const QString &elementPath, const QString &even
d->controller->handleFireEvent(elementPath, eventName);
}
+/*!
+ Moves the timeline for a time context (a Scene or a Component element) to a
+ specific position. The position is given in seconds in \a timeSeconds.
+
+ If \a elementPath points to a time context, that element is
+ controlled. For all other element types the time context owning
+ that element is controlled instead. You can target the command to
+ a specific sub-presentation by adding "SubPresentationId:" in
+ front of the element path, for example
+ \c{"SubPresentationOne:Scene"}.
+
+ The behavior when specifying a time before 0 or after the end time
+ for the current slide depends on the play mode of the slide:
+
+ \list
+ \li \c{Stop at End} - values outside the valid time range instead clamp to the boundaries.
+ For example, going to time -5 is the same as going to time 0.
+ \li \c{Looping} - values outside the valid time range mod into the valid range. For example,
+ going to time -4 on a 10 second slide is the same as going to time 6.
+ \li \c{Ping Pong} - values outside the valid time range bounce off the ends. For example,
+ going to time -4 is the same as going to time 4 (assuming the time context is at least 4 seconds
+ long), while going to time 12 on a 10 second slide is the same as going to time 8.
+ \li \c{Ping} - values less than 0 are treated as time 0, while values greater than the endtime
+ bounce off the end (eventually hitting 0.)
+ \endlist
+ */
void Q3DSPresentation::goToTime(const QString &elementPath, float timeSeconds)
{
Q_D(Q3DSPresentation);
@@ -156,6 +263,17 @@ void Q3DSPresentation::goToTime(const QString &elementPath, float timeSeconds)
d->controller->handleGoToTime(elementPath, timeSeconds);
}
+/*!
+ Requests a time context (a Scene or a Component object) to change
+ to a specific slide by \a name. If the context is already on that
+ slide, playback will start over.
+
+ If \a elementPath points to a time context, that element is
+ controlled. For all other element types the time context owning
+ that element is controlled instead. You can target the command to
+ a specific sub-presentation by adding "SubPresentationId:" in
+ front of the element path, for example \c{"SubPresentationOne:Scene"}.
+ */
void Q3DSPresentation::goToSlide(const QString &elementPath, const QString &name)
{
Q_D(Q3DSPresentation);
@@ -163,6 +281,17 @@ void Q3DSPresentation::goToSlide(const QString &elementPath, const QString &name
d->controller->handleGoToSlideByName(elementPath, name);
}
+/*!
+ Requests a time context (a Scene or a Component object) to change
+ to a specific slide by \a index. If the context is already on that
+ slide, playback will start over.
+
+ If \a elementPath points to a time context, that element is
+ controlled. For all other element types the time context owning
+ that element is controlled instead. You can target the command to
+ a specific sub-presentation by adding "SubPresentationId:" in
+ front of the element path, for example \c{"SubPresentationOne:Scene"}.
+ */
void Q3DSPresentation::goToSlide(const QString &elementPath, int index)
{
Q_D(Q3DSPresentation);
@@ -170,6 +299,18 @@ void Q3DSPresentation::goToSlide(const QString &elementPath, int index)
d->controller->handleGoToSlideByIndex(elementPath, index);
}
+/*!
+ Requests a time context (a Scene or a Component object) to change to the
+ next or previous slide, depending on the value of \a next. If the context
+ is already at the last or first slide, \a wrap defines if wrapping over to
+ the first or last slide, respectively, occurs.
+
+ If \a elementPath points to a time context, that element is controlled. For
+ all other element types the time context owning that element is controlled
+ instead. You can target the command to a specific sub-presentation by
+ adding "SubPresentationId:" in front of the element path, for example
+ \c{"SubPresentationOne:Scene"}.
+ */
void Q3DSPresentation::goToSlide(const QString &elementPath, bool next, bool wrap)
{
Q_D(Q3DSPresentation);
@@ -177,6 +318,15 @@ void Q3DSPresentation::goToSlide(const QString &elementPath, bool next, bool wra
d->controller->handleGoToSlideByDirection(elementPath, next, wrap);
}
+/*!
+ Returns the value of an attribute (property) on the object specified by \a
+ elementPath. The \a attributeName is the \l{Attribute Names}{scripting
+ name} of the attribute.
+
+ See setAttribute() for a description of \a elementPath.
+
+ \sa setAttribute
+ */
QVariant Q3DSPresentation::getAttribute(const QString &elementPath, const QString &attributeName)
{
Q_D(Q3DSPresentation);
@@ -186,6 +336,34 @@ QVariant Q3DSPresentation::getAttribute(const QString &elementPath, const QStrin
return QVariant();
}
+/*!
+ Sets the \a value of an attribute (property) on the object specified by
+ \a elementPath. The \a attributeName is the \l{Attribute Names}{scripting
+ name} of the attribute.
+
+ An element path refers to an object in the scene either by name or id. The
+ latter is rarely used in application code since the unique IDs are not
+ exposed in the Qt 3D Studio application. To refer to an object by id,
+ prepend \c{#} to the name. Applications will typically refer to objects by
+ name.
+
+ Names are not necessarily unique, however. To access an object with a
+ non-unique name, the path can be specified, for example,
+ \c{Scene.Layer.Camera}. Here the right camera object gets chosen even if
+ the scene contains other layers with the default camera names (for instance
+ \c{Scene.Layer2.Camera}).
+
+ If the object is renamed to a unique name in the Qt 3D Studio application's
+ Timeline view, the path can be omitted. For example, if the camera in
+ question was renamed to \c MyCamera, applications can then simply pass \c
+ MyCamera as the element path.
+
+ To access an object in a sub-presentation, prepend the name of the
+ sub-presentation followed by a colon, for example,
+ \c{SubPresentationOne:Scene.Layer.Camera}.
+
+ \sa getAttribute
+ */
void Q3DSPresentation::setAttribute(const QString &elementPath, const QString &attributeName, const QVariant &value)
{
Q_D(Q3DSPresentation);
@@ -292,4 +470,182 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
inlineQmlSubPresentations += list;
}
+/*!
+ \qmltype Presentation
+ \instantiates Q3DSPresentation
+ \inqmlmodule QtStudio3D
+ \ingroup 3dstudioruntime2
+
+ \brief Control type for Qt 3D Studio presentations.
+
+ This type provides properties and methods for controlling a presentation.
+
+ All methods provided by this type are queued and handled asynchronously before the next
+ frame is displayed.
+
+ \sa Studio3D
+*/
+
+/*!
+ \qmlproperty url Presentation::source
+
+ Holds the presentation source (\c{*.uia} or \c{*.uip}) file location.
+ May be either a file URL or a qrc URL.
+*/
+
+/*!
+ \qmlproperty SubPresentationSettings Presentation::subPresentationSettings
+
+ Holds the settings for the subpresentations in the Qt 3D Studio presentation.
+
+ This property is read-only.
+*/
+
+/*!
+ \qmlmethod void Presentation::goToSlide(string elementPath, string name)
+
+ Requests a time context (a Scene or a Component element) to change to a specific slide
+ by \a name. If the context is already on that slide playback will start over.
+
+ If \a elementPath points to a time context, that element is controlled. For
+ all other element types the time context owning that element is controlled instead.
+ You can target the command to a specific sub-presentation by adding "SubPresentationId:" in
+ front of the element path, for example \c{"SubPresentationOne:Scene"}.
+*/
+
+/*!
+ \qmlmethod void Presentation::goToSlide(string elementPath, int index)
+
+ Requests a time context (a Scene or a Component element) to change to a specific slide by
+ index \a index. If the context is already on that slide playback will start over.
+
+ If \a elementPath points to a time context, that element is controlled. For
+ all other element types the time context owning that element is controlled instead.
+ You can target the command to a specific sub-presentation by adding "SubPresentationId:" in
+ front of the element path, for example \c{"SubPresentationOne:Scene"}.
+*/
+
+/*!
+ \qmlmethod void Presentation::goToSlide(string elementPath, bool next, bool wrap)
+
+ Requests a time context (a Scene or a Component element) to change to the next or the
+ previous slide, depending on the value of \a next. If the context is already at the
+ last or first slide, \a wrap defines if change occurs to the opposite end.
+
+ If \a elementPath points to a time context, that element is controlled. For
+ all other element types the time context owning that element is controlled instead.
+ You can target the command to a specific sub-presentation by adding "SubPresentationId:" in
+ front of the element path, for example \c{"SubPresentationOne:Scene"}.
+*/
+
+/*!
+ \qmlmethod void Presentation::goToTime(string elementPath, real time)
+
+ Sets a time context (a Scene or a Component element) to a specific playback \a time in seconds.
+
+ If \a elementPath points to a time context, that element is controlled. For
+ all other element types the time context owning that element is controlled instead.
+ You can target the command to a specific sub-presentation by adding "SubPresentationId:" in
+ front of the element path, for example \c{"SubPresentationOne:Scene"}.
+
+ The behavior when specifying a time before 0 or after the end time for the current slide depends
+ on the play mode of the slide:
+ \list
+ \li \c{Stop at End} - values outside the valid time range instead clamp to the boundaries.
+ For example, going to time -5 is the same as going to time 0.
+ \li \c{Looping} - values outside the valid time range mod into the valid range. For example,
+ going to time -4 on a 10 second slide is the same as going to time 6.
+ \li \c{Ping Pong} - values outside the valid time range ‘bounce’ off the ends. For example,
+ going to time -4 is the same as going to time 4 (assuming the time context is at least 4 seconds
+ long), while going to time 12 on a 10 second slide is the same as going to time 8.
+ \li \c{Ping} - values less than 0 are treated as time 0, while values greater than the endtime
+ bounce off the end (eventually hitting 0.)
+ \endlist
+*/
+
+/*!
+ \qmlmethod void Presentation::setAttribute(string elementPath, string attributeName,
+ variant value)
+
+ Sets the \a value of an attribute on an element found at \a elementPath. The \a attributeName is
+ the \l{Attribute Names}{scripting name} of the attribute.
+
+ You can target the command to a specific sub-presentation by adding "SubPresentationId:" in
+ front of the element path, for example \c{"SubPresentationOne:Scene.Mesh.Material"}.
+
+ The attribute must be preserved for scripting to be set by this function, or else it will fail.
+ An attribute is preserved if it is either \e{animated}, or
+ \e{an attribute on a master element that is unlinked and changed per-slide}.
+*/
+
+/*!
+ \qmlmethod void Presentation::setPresentationActive(string id, bool active)
+
+ Stops or starts updates to a sub-presentation based on the \a active flag. The presentation is
+ referenced to by the \a id, which is the name of the presentation without the \c{.uip}.
+
+ Making a presentation inactive prevents any elements, behaviors, and animations within it from
+ updating. It also prevents any events within that presentation from being processed. It does
+ not, however, prevent the presentation from rendering. An inactive presentation will continue
+ to render using its last-updated information.
+
+ Explicitly inactivating presentations can provide a significant performance increase, depending
+ on the number and size of the presentations that are inactive. Inactive presentations are not
+ ‘paused’. When the presentation is re-activated, animations will resume at the time they should
+ be had they been running, not where they were when the presentation was made inactive.
+*/
+
+/*!
+ \qmlmethod void Presentation::fireEvent(string elementPath, string eventName)
+
+ Dispatches an event with \a eventName on a specific element found in \a elementPath. Appropriate
+ Appropriate actions created in Qt 3D Studio or callbacks registered using the registerForEvent()
+ method in attached scripts will be executed in response to the event.
+
+ You can target the command to a specific sub-presentation by adding "SubPresentationId:" in
+ front of the element path, for example \c{"SubPresentationOne:Scene.Mesh"}.
+*/
+
+/*!
+ \qmlmethod void Presentation::setGlobalAnimationTime(int64 milliseconds)
+
+ Sets the global animation time to \a milliseconds. Setting the global animation time to a
+ non-zero value will disable the automatic animation timer. Setting the value to zero
+ resumes automatic animation timer.
+*/
+
+/*!
+ \qmlmethod void Presentation::setDataInputValue(string name, variant value)
+ \since QtStudio3D 1.1
+
+ Sets the \a value of a data input element \a name in the presentation.
+*/
+
+/*!
+ \qmlsignal Presentation::slideEntered(string elementPath, int index, string name)
+
+ This signal is emitted when a slide is entered in the presentation.
+ The \a elementPath specifies the time context (a Scene or a Component element) owning the
+ entered slide.
+ The \a index and \a name contain the index and the name of the entered slide.
+*/
+
+/*!
+ \qmlsignal Presentation::slideExited(string elementPath, int index, string name)
+
+ This signal is emitted when a slide is exited in the presentation.
+ The \a elementPath specifies the time context (a Scene or a Component element) owning the
+ exited slide.
+ The \a index and \a name contain the index and the name of the exited slide.
+*/
+
+/*!
+ \qmlsignal Presentation::sourceChanged(url source)
+
+ This signal is emitted when the source property has changed.
+ The new value is provided in the \a source parameter.
+
+ The corresponding handler is \c onSourceChanged.
+*/
+
QT_END_NAMESPACE
diff --git a/src/runtime/api/q3dssceneelement.cpp b/src/runtime/api/q3dssceneelement.cpp
index f8b3e23..6b3c161 100644
--- a/src/runtime/api/q3dssceneelement.cpp
+++ b/src/runtime/api/q3dssceneelement.cpp
@@ -32,18 +32,39 @@
QT_BEGIN_NAMESPACE
-Q3DSSceneElement::Q3DSSceneElement(QObject *parent)
- : Q3DSElement(*new Q3DSSceneElementPrivate, parent)
-{
-}
+/*!
+ \class Q3DSSceneElement
+ \inherits Q3DSElement
+ \inmodule 3dstudioruntime2
+ \since Qt 3D Studio 2.0
+
+ \brief Controls the special Scene or Component scene objects in a Qt 3D
+ Studio presentation.
+
+ This class is a convenience class for controlling the properties of Scene
+ and Component objects in the scene. These are special since they have a
+ time context, meaning they control a timline and a set of associated
+ slides.
+
+ \note The functionality of Q3DSSceneElement is equivalent to
+ Q3DSPresentation::goToTime() and Q3DSPresentation::goToSlide().
+
+ \sa Q3DSPresentation, Q3DSWidget, Q3DSSurfaceViewer, Q3DSElement
+ */
-Q3DSSceneElement::Q3DSSceneElement(const QString &elementPath, QObject *parent)
+/*!
+ \internal
+ */
+Q3DSSceneElement::Q3DSSceneElement(QObject *parent)
: Q3DSElement(*new Q3DSSceneElementPrivate, parent)
{
- Q_D(Q3DSSceneElement);
- d->elementPath = elementPath;
}
+/*!
+ Constructs a Q3DSSceneElement instance and associated it with the object
+ specified by \a elementPath and the given \a presentation. An optional \a
+ parent object can be specified.
+ */
Q3DSSceneElement::Q3DSSceneElement(Q3DSPresentation *presentation, const QString &elementPath, QObject *parent)
: Q3DSElement(*new Q3DSSceneElementPrivate, parent)
{
@@ -52,33 +73,77 @@ Q3DSSceneElement::Q3DSSceneElement(Q3DSPresentation *presentation, const QString
d->presentation = presentation;
}
+/*!
+ \internal
+ */
Q3DSSceneElement::Q3DSSceneElement(Q3DSSceneElementPrivate &dd, QObject *parent)
: Q3DSElement(dd, parent)
{
}
+/*!
+ Destructor.
+ */
Q3DSSceneElement::~Q3DSSceneElement()
{
}
+/*!
+ \property Q3DSSceneElement::currentSlideIndex
+
+ Holds the index of the currently active slide of the tracked time context.
+
+ \note If this property is set to something else than the default slide for
+ the scene at the initial declaration of SceneElement, a changed signal for
+ the default slide may stil be emitted before the slide changes to the
+ desired one. This happens in order to ensure we end up with the index of
+ the slide that is actually shown even if the slide specified in the initial
+ declaration is invalid.
+*/
int Q3DSSceneElement::currentSlideIndex() const
{
Q_D(const Q3DSSceneElement);
return d->currentSlideIndex;
}
+/*!
+ \property Q3DSSceneElement::previousSlideIndex
+
+ Holds the index of the previously active slide of the tracked time context.
+
+ This property is read-only.
+*/
int Q3DSSceneElement::previousSlideIndex() const
{
Q_D(const Q3DSSceneElement);
return d->previousSlideIndex;
}
+/*!
+ \property Q3DSSceneElement::currentSlideName
+
+ Holds the name of the currently active slide of the tracked time context.
+
+ \note If this property is set to something else than the default slide for
+ the scene at the initial declaration of SceneElement, a changed signal for
+ the default slide may stil be emitted before the slide changes to the
+ desired one. This happens in order to ensure we end up with the index of
+ the slide that is actually shown even if the slide specified in the initial
+ declaration is invalid.
+*/
QString Q3DSSceneElement::currentSlideName() const
{
Q_D(const Q3DSSceneElement);
return d->currentSlideName;
}
+/*!
+ \property Q3DSSceneElement::previousSlideName
+
+ Holds the name of the previously active slide of the tracked time context.
+
+ This property is read-only.
+*/
QString Q3DSSceneElement::previousSlideName() const
{
Q_D(const Q3DSSceneElement);
@@ -105,6 +170,12 @@ void Q3DSSceneElement::setCurrentSlideName(const QString &currentSlideName)
d->pendingSlideSetName = currentSlideName; // defer to sendPendingValues()
}
+/*!
+ Requests a time context (a Scene or a Component object) to change to the
+ next or previous slide, depending on the value of \a next. If the context
+ is already at the last or first slide, \a wrap defines if wrapping over to
+ the first or last slide, respectively, occurs.
+ */
void Q3DSSceneElement::goToSlide(bool next, bool wrap)
{
Q_D(Q3DSSceneElement);
@@ -112,6 +183,10 @@ void Q3DSSceneElement::goToSlide(bool next, bool wrap)
d->presentation->goToSlide(d->elementPath, next, wrap);
}
+/*!
+ Moves the timeline for a time context (a Scene or a Component element) to a
+ specific position. The position is given in seconds in \a timeSeconds.
+ */
void Q3DSSceneElement::goToTime(float timeSeconds)
{
Q_D(Q3DSSceneElement);
@@ -171,6 +246,131 @@ void Q3DSSceneElementPrivate::setPresentation(Q3DSPresentation *pres)
q, SLOT(_q_onSlideEntered(QString,int,QString)));
}
+/*!
+ \qmltype SceneElement
+ \instantiates Q3DSSceneElement
+ \inherits Element
+ \inqmlmodule QtStudio3D
+ \ingroup 3dstudioruntime2
+ \brief Control type for scene and component elements in a Qt 3D Studio presentation.
+
+ This type is a convenience type for managing the slides of a single
+ time context (a Scene or a Component element) of a presentation.
+
+ All methods provided by this type are queued and handled asynchronously before the next
+ frame is displayed.
+
+ \sa Studio3D, Presentation, Element
+*/
+
+/*!
+ \qmlproperty int SceneElement::currentSlideIndex
+
+ Holds the index of the currently active slide of the tracked time context.
+
+ Changing the current slide via this property is asynchronous. The property
+ value will not actually change until the next frame has been processed, and
+ even then only if the new slide was valid.
+
+ \note If this property is set to something else than the default slide for the scene at the
+ initial declaration of SceneElement, you will still get an extra changed signal for the
+ default slide before the slide changes to the desired one. This happens in order to ensure
+ we end up with the index of the slide that is actually shown even if the slide specified in the
+ initial declaration is invalid.
+*/
+
+/*!
+ \qmlproperty int SceneElement::previousSlideIndex
+
+ Holds the index of the previously active slide of the tracked time context.
+
+ This property is read-only.
+*/
+
+/*!
+ \qmlproperty string SceneElement::currentSlideName
+
+ Holds the name of the currently active slide of the tracked time context.
+
+ Changing the current slide via this property is asynchronous. The property
+ value will not actually change until the next frame has been processed, and
+ even then only if the new slide was valid.
+
+ \note If this property is set to something else than the default slide for the scene at the
+ initial declaration of SceneElement, you will still get an extra changed signal for the
+ default slide before the slide changes to the desired one. This happens in order to ensure
+ we end up with the name of the slide that is actually shown even if the slide specified in the
+ initial declaration is invalid.
+*/
+
+/*!
+ \qmlproperty string SceneElement::previousSlideName
+
+ Holds the name of the previously active slide of the tracked time context.
+
+ This property is read-only.
+*/
+
+/*!
+ \qmlsignal SceneElement::currentSlideIndexChanged(int currentSlideIndex)
+
+ This signal is emitted when the current slide changes.
+ The new value is provided in the \a currentSlideIndex parameter.
+
+ This signal is always emitted with currentSlideNameChanged.
+
+ The corresponding handler is \c onCurrentSlideIndexChanged.
+*/
+
+/*!
+ \qmlsignal SceneElement::previousSlideIndexChanged(int previousSlideIndex)
+
+ This signal is emitted when the previous slide changes.
+ The new value is provided in the \a previousSlideIndex parameter.
+
+ This signal is always emitted with previousSlideNameChanged.
+
+ The corresponding handler is \c onPreviousSlideIndexChanged.
+*/
+
+/*!
+ \qmlsignal SceneElement::currentSlideNameChanged(string currentSlideName)
+
+ This signal is emitted when the current slide changes.
+ The new value is provided in the \a currentSlideName parameter.
+
+ This signal is always emitted with currentSlideIndexChanged.
+
+ The corresponding handler is \c onCurrentSlideNameChanged.
+*/
+
+/*!
+ \qmlsignal SceneElement::previousSlideNameChanged(string previousSlideName)
+
+ This signal is emitted when the previous slide changes.
+ The new value is provided in the \a previousSlideName parameter.
+
+ This signal is always emitted with previousSlideIndexChanged.
+
+ The corresponding handler is \c onPreviousSlideNameChanged.
+*/
+
+/*!
+ \qmlmethod void SceneElement::goToSlide(bool next, bool wrap)
+
+ Requests a time context (a Scene or a Component element) to change to the next or the
+ previous slide, depending on the value of \a next. If the context is already at the
+ last or first slide, \a wrap defines if change occurs to the opposite end.
+*/
+
+/*!
+ \qmlmethod void SceneElement::goToTime(string elementPath, real time)
+
+ Sets a time context (a Scene or a Component element) to a specific playback \a time in seconds.
+
+ For behavior details, see Presentation::goToTime() documentation.
+*/
+
QT_END_NAMESPACE
#include "moc_q3dssceneelement.cpp"
diff --git a/src/runtime/api/q3dssceneelement.h b/src/runtime/api/q3dssceneelement.h
index d8eba18..b7726d3 100644
--- a/src/runtime/api/q3dssceneelement.h
+++ b/src/runtime/api/q3dssceneelement.h
@@ -52,7 +52,6 @@ class Q3DSV_EXPORT Q3DSSceneElement : public Q3DSElement
public:
explicit Q3DSSceneElement(QObject *parent = nullptr);
- explicit Q3DSSceneElement(const QString &elementPath, QObject *parent = nullptr);
Q3DSSceneElement(Q3DSPresentation *presentation, const QString &elementPath, QObject *parent = nullptr);
~Q3DSSceneElement();
diff --git a/src/runtime/api/q3dssurfaceviewer.cpp b/src/runtime/api/q3dssurfaceviewer.cpp
index 853b96b..8ecb6c3 100644
--- a/src/runtime/api/q3dssurfaceviewer.cpp
+++ b/src/runtime/api/q3dssurfaceviewer.cpp
@@ -45,6 +45,56 @@
QT_BEGIN_NAMESPACE
+/*!
+ \class Q3DSSurfaceViewer
+ \inmodule 3dstudioruntime2
+ \since Qt 3D Studio 2.0
+
+ \brief Renders a Qt 3D Studio presentation on a QWindow or an offscreen
+ render target using OpenGL.
+
+ Q3DSSurfaceViewer is used to render Qt 3D Studio presentations onto a
+ QSurface. In practice this means two types of uses: rendering to an
+ on-screen QWindow, or rendering to an offscreen render target (typically an
+ OpenGL texture via a framebuffer object and a QOffscreenSurface).
+
+ \section2 Example Usage
+
+ \code
+ int main(int argc, char *argv[])
+ {
+ QGuiApplication app(argc, argv);
+
+ QOpenGLContext context;
+ context.create();
+
+ QWindow window;
+ window.setSurfaceType(QSurface::OpenGLSurface);
+ window.setFormat(context.format());
+ window.create();
+
+ Q3DSSurfaceViewer viewer;
+ viewer.presentation()->setSource(QUrl(QStringLiteral("qrc:/my_presentation.uip")));
+ viewer.setUpdateInterval(0); // enable automatic updates
+
+ // Register a scene object for slide management (optional)
+ Q3DSSceneElement scene(viewer.presentation(), QStringLiteral("Scene"));
+
+ // Register an element object for attribute setting (optional)
+ Q3DSElement element(viewer.presentation(), QStringLiteral("myCarModel"));
+
+ viewer.create(&window, &context);
+
+ w.resize(1024, 768);
+ w.show();
+
+ return app.exec();
+ }
+ \endcode
+
+ \sa Q3DSWidget
+ */
+
Q3DSSurfaceViewer::Q3DSSurfaceViewer(QObject *parent)
: QObject(*new Q3DSSurfaceViewerPrivate, parent)
{
@@ -67,12 +117,35 @@ Q3DSSurfaceViewer::~Q3DSSurfaceViewer()
// "use this custom FBO as-is". Changing to int would be wrong too since the ID
// is a GLuint in practice.
+/*!
+ Initializes Q3DSSurfaceViewer to render the presentation to the given
+ \a surface using the \a context.
+
+ The source property of the attached presentation must be set before the
+ viewer can be initialized.
+
+ Returns whether the initialization succeeded.
+
+ \sa running, Q3DSPresentation::source, presentation()
+*/
bool Q3DSSurfaceViewer::create(QSurface *surface, QOpenGLContext *context)
{
Q_D(Q3DSSurfaceViewer);
return d->doCreate(surface, context, 0, false);
}
+/*!
+ Initializes Q3DSSurfaceViewer to render the presentation to the given
+ \a surface using the \a context and optional framebuffer id (\a fboId). If
+ \a fboId is omitted, it defaults to zero.
+
+ The source property of the attached presentation must be set before the
+ viewer can be initialized.
+
+ Returns whether the initialization succeeded.
+
+ \sa running, Q3DSPresentation::source, presentation()
+*/
bool Q3DSSurfaceViewer::create(QSurface *surface, QOpenGLContext *context, uint fboId)
{
Q_D(Q3DSSurfaceViewer);
@@ -114,12 +187,18 @@ void Q3DSSurfaceViewer::destroy()
d->fbo = 0;
}
+/*!
+ Returns the presentation object used by the Q3DSSurfaceViewer.
+*/
Q3DSPresentation *Q3DSSurfaceViewer::presentation() const
{
Q_D(const Q3DSSurfaceViewer);
return d->presentation;
}
+/*!
+ Returns the settings object used by the Q3DSSurfaceViewer.
+*/
Q3DSViewerSettings *Q3DSSurfaceViewer::settings() const
{
Q_D(const Q3DSSurfaceViewer);
@@ -132,6 +211,14 @@ QString Q3DSSurfaceViewer::error() const
return d->error;
}
+/*!
+ \property Q3DSSurfaceViewer::running
+
+ The value of this property is \c true when the viewer has been initialized
+ and the presentation is running.
+
+ This property is read-only.
+*/
bool Q3DSSurfaceViewer::isRunning() const
{
Q_D(const Q3DSSurfaceViewer);
@@ -153,6 +240,22 @@ void Q3DSSurfaceViewer::setSize(const QSize &size)
}
}
+/*!
+ \property Q3DSSurfaceViewer::autoSize
+
+ Specifies whether the viewer should change the size of the presentation
+ automatically to match the surface size when surface size changes. The
+ \l{Q3DSSurfaceViewer::size}{size} property is updated automatically
+ whenever the viewer is \l{Q3DSSurfaceViewer::update()}{updated} if this
+ property value is \c{true}.
+
+ When rendering offscreen, via a QOffscreenSurface, this property must be
+ set to \c{false} by the application since it is then up to the application
+ to provide a QOpenGLFramebufferObject with the desired size. The size of
+ the Q3DSSurfaceViewer must be set to the same value.
+
+ The default value is \c{true}.
+*/
bool Q3DSSurfaceViewer::autoSize() const
{
Q_D(const Q3DSSurfaceViewer);
@@ -168,6 +271,17 @@ void Q3DSSurfaceViewer::setAutoSize(bool autoSize)
}
}
+/*!
+ \property Q3DSSurfaceViewer::updateInterval
+
+ Holds the viewer update interval in milliseconds. If the value is negative,
+ the viewer doesn't update the presentation automatically.
+
+ The default value is -1, meaning there are no automatic updates and
+ update() must be called manually.
+
+ \sa update()
+*/
int Q3DSSurfaceViewer::updateInterval() const
{
Q_D(const Q3DSSurfaceViewer);
@@ -190,18 +304,33 @@ void Q3DSSurfaceViewer::setUpdateInterval(int interval)
}
}
+/*!
+ Returns the framebuffer id given in initialization.
+
+ \sa create()
+*/
uint Q3DSSurfaceViewer::fboId() const
{
Q_D(const Q3DSSurfaceViewer);
return d->fbo;
}
+/*!
+ Returns the surface given in initialization.
+
+ \sa create()
+*/
QSurface *Q3DSSurfaceViewer::surface() const
{
Q_D(const Q3DSSurfaceViewer);
return d->surface;
}
+/*!
+ Returns the context given in initialization.
+
+ \sa create()
+*/
QOpenGLContext *Q3DSSurfaceViewer::context() const
{
Q_D(const Q3DSSurfaceViewer);
@@ -210,6 +339,9 @@ QOpenGLContext *Q3DSSurfaceViewer::context() const
extern Q_GUI_EXPORT QImage qt_gl_read_framebuffer(const QSize &size, bool alpha_format, bool include_alpha);
+/*!
+ Updates the surface viewer with a new frame.
+*/
void Q3DSSurfaceViewer::update()
{
Q_D(Q3DSSurfaceViewer);
@@ -272,6 +404,13 @@ void Q3DSSurfaceViewer::update()
emit frameUpdate();
}
+/*!
+ Grabs the data rendered to the framebuffer into an image using the given \a
+ rect. The \a rect parameter is optional. If it is omitted, the whole
+ framebuffer is captured.
+
+ \note This is a potentially expensive operation.
+*/
QImage Q3DSSurfaceViewer::grab(const QRect &rect)
{
Q_D(Q3DSSurfaceViewer);
diff --git a/src/runtime/api/q3dsviewersettings.cpp b/src/runtime/api/q3dsviewersettings.cpp
index ba1249a..a0d91ea 100644
--- a/src/runtime/api/q3dsviewersettings.cpp
+++ b/src/runtime/api/q3dsviewersettings.cpp
@@ -32,6 +32,26 @@
QT_BEGIN_NAMESPACE
+/*!
+ \class Q3DSViewerSettings
+ \inmodule 3dstudioruntime2
+ \since Qt 3D Studio 2.0
+
+ \brief Qt 3D Studio presentation viewer settings.
+
+ Q3DSViewerSettings provides properties to define presentation independent
+ viewer settings.
+
+ \note As of Qt 3D Studio 2.0 this class is provided mainly for
+ compatibility reasons. Most functions are not applicable or are not
+ currently supported and will be silently ignored.
+
+ \note This class should not be instantiated directly when working with the
+ C++ APIs. Q3DSSurfaceViewer and Q3DSWidget create a Q3DSViewerSettings
+ instance implicitly. This can be queried via Q3DSSurfaceViewer::settings()
+ or Q3DSWidget::settings().
+ */
+
Q3DSViewerSettings::Q3DSViewerSettings(QObject *parent)
: QObject(*new Q3DSViewerSettingsPrivate, parent)
{
@@ -52,6 +72,17 @@ QColor Q3DSViewerSettings::matteColor() const
return d->matteColor;
}
+/*!
+ \property Q3DSViewerSettings::showRenderStats
+
+ If this property is set to \c{true}, the interactive statistics and profile
+ view is displayed in-scene, on top of the 3D content.
+
+ \note This feature can be disabled at build time, in which case this
+ property has no effect.
+
+ Default value is \c{false}.
+*/
bool Q3DSViewerSettings::isShowingRenderStats() const
{
Q_D(const Q3DSViewerSettings);
@@ -129,4 +160,24 @@ void Q3DSViewerSettings::load(const QString &group,
qWarning() << Q_FUNC_INFO << "not implemented";
}
+/*!
+ \qmltype ViewerSettings
+ \instantiates Q3DSViewerSettings
+ \inqmlmodule QtStudio3D
+ \ingroup 3dstudioruntime2
+ \brief Qt 3D Studio presentation viewer settings.
+
+ This type provides properties to define presentation independent viewer settings.
+
+ \sa Studio3D
+*/
+
+/*!
+ \qmlproperty bool ViewerSettings::showRenderStats
+
+ If this property is set to \c{true}, render statistics are displayed on the upper part
+ of the viewer.
+ Default value is \c{false}.
+*/
+
QT_END_NAMESPACE
diff --git a/src/runtime/api/q3dswidget.cpp b/src/runtime/api/q3dswidget.cpp
index 6fb6d3e..8cdd898 100644
--- a/src/runtime/api/q3dswidget.cpp
+++ b/src/runtime/api/q3dswidget.cpp
@@ -44,12 +44,35 @@ QT_BEGIN_NAMESPACE
/*!
\class Q3DSWidget
-
\inmodule 3dstudioruntime2
+ \since Qt 3D Studio 2.0
+ \inherits QOpenGLWidget
+
+ \brief A widget that renders Qt 3D Studio presentations using OpenGL.
+
+ Q3DSWidget is a widget that can be used to embed Qt 3D Studio presentations
+ into QWidget-based applications.
+
+ Q3DSWidget is used to specify a render widget for Qt 3D Studio
+ presentation. It subclasses QOpenGLWidget, which means all considerations
+ that should be taken when working with QOpenGLWidget apply to Q3DSWidget as
+ well. Refer to the QOpenGLWidget documentation for details.
+
+ \section2 Example Usage
- \brief Widget
+ \code
+ Q3DSWidget *viewer = new Q3DSWidget(parentWidget);
+ viewer->presentation()->setSource(QUrl(QStringLiteral("qrc:/my_presentation.uip")));
+ viewer->setUpdateInterval(0);
- blah
+ // Register a scene element object for slide management (optional)
+ Q3DSSceneElement scene(viewer->presentation(), QStringLiteral("Scene"));
+
+ // Register an element object for attribute setting (optional)
+ Q3DSElement element(viewer->presentation(), QStringLiteral("myCarModel"));
+ \endcode
+
+ \sa Q3DSSurfaceViewer
*/
Q3DSWidget::Q3DSWidget(QWidget *parent)
@@ -65,12 +88,18 @@ Q3DSWidget::~Q3DSWidget()
delete d_ptr;
}
+/*!
+ Returns the presentation object used by the Q3DSWidget.
+ */
Q3DSPresentation *Q3DSWidget::presentation() const
{
Q_D(const Q3DSWidget);
return d->presentation;
}
+/*!
+ Returns the settings object used by the Q3DSWidget.
+ */
Q3DSViewerSettings *Q3DSWidget::settings() const
{
Q_D(const Q3DSWidget);
@@ -83,12 +112,30 @@ QString Q3DSWidget::error() const
return d->error;
}
+/*!
+ \property Q3DSWidget::running
+
+ The value of this property is \c true when the viewer has been initialized
+ and the presentation is running.
+
+ This property is read-only.
+*/
bool Q3DSWidget::isRunning() const
{
Q_D(const Q3DSWidget);
return d->engine && d->sourceLoaded;
}
+/*!
+ \property Q3DSWidget::updateInterval
+
+ Holds the viewer update interval in milliseconds. If the value is negative,
+ the viewer doesn't update the presentation automatically.
+
+ The default value is 0, meaning automatic updates are enabled.
+
+ \sa QWidget::update()
+*/
int Q3DSWidget::updateInterval() const
{
Q_D(const Q3DSWidget);
diff --git a/src/runtime/behaviorapi/q3dsbehaviorobject.cpp b/src/runtime/behaviorapi/q3dsbehaviorobject.cpp
index 75ac946..9a31ce8 100644
--- a/src/runtime/behaviorapi/q3dsbehaviorobject.cpp
+++ b/src/runtime/behaviorapi/q3dsbehaviorobject.cpp
@@ -265,4 +265,170 @@ void Q3DSBehaviorObject::setDataInputValue(const QString &name, const QVariant &
m_engine->setDataInputValue(name, value);
}
+/*!
+ \qmltype Behavior
+ \inqmlmodule QtStudio3D
+ \ingroup 3dstudioruntime2
+
+ \brief Technology Preview Behavior Integration
+
+ This is a technology preview (API may change in upcoming version) of how
+ Qt 3D Studio could support writing custom behavior scripts using QML and
+ JavaScript. It enables interacting with the runtime using the Behavior
+ QML class exposed to each behavior script.
+
+ In QML behavior script, the integration to Qt 3D Studio is established by using
+ the metadata tag system similar to the \l {file-formats-effects.html}{effect}
+ and \l {file-formats-material.html}{material} files.
+
+ \badcode
+[[
+<Property name="somePropertyName" ... />
+
+<Handler name="someHandlerName" ... />
+
+<Event name="onSomeEvent" ... />
+...
+]]
+ \endcode
+
+ Secondly, the QML behavior script needs access to the QML module.
+ \badcode
+import QtStudio3D.Behavior 2.0
+ \endcode
+
+ Finally, the Behavior type needs to be implemented in the qml script.
+ \badcode
+Behavior {
+ id: mybehavior
+
+ function onInitialize() {
+ ...
+ }
+
+ function onActivate() {
+ ...
+ }
+
+ function onUpdate() {
+ ...
+ }
+
+ function onDeactivate() {
+ ...
+ }
+
+ function someHandlerName() {
+ ...
+ fireEvent("onSomeEvent")
+ }
+}
+ \endcode
+*/
+
+/*!
+ \qmlmethod float Behavior::getDeltaTime()
+
+ Returns the delta time between this and previous frame in milliseconds.
+*/
+
+/*!
+ \qmlmethod var Behavior::getAttribute(string attribute)
+
+ Returns the value of the given \a attribute.
+*/
+
+/*!
+ \qmlmethod var Behavior::getAttribute(string handle, string attribute)
+
+ Returns the value of the given \a attribute for a given \a handle.
+*/
+
+/*!
+ \qmlmethod void Behavior::setAttribute(string attribute, var value)
+
+ Sets the \a value of the given \a attribute.
+*/
+
+/*!
+ \qmlmethod void Behavior::setAttribute(string handle, string attribute, var value)
+
+ Sets the \a value of the given \a attribute for a given \a handle.
+*/
+
+/*!
+ \qmlmethod void Behavior::fireEvent(string event)
+
+ Fires the given \a event.
+*/
+
+/*!
+ \qmlmethod void Behavior::registerForEvent(string event, QJSValue function)
+
+ Registers the script for an \a event with the handler \a function.
+*/
+
+/*!
+ \qmlmethod void Behavior::registerForEvent(string handle, string event, QJSValue function)
+
+ Registers the script for an \a event with the handler \a function for a given \a handle.
+*/
+
+/*!
+ \qmlmethod void Behavior::unregisterForEvent(string event)
+
+ Unregisters the script from an \a event.
+*/
+
+/*!
+ \qmlmethod void Behavior::unregisterForEvent(string handle, string event)
+
+ Unregisters the script from an \a event for a given \a handle.
+*/
+
+/*!
+ \qmlmethod void Behavior::setDataInputValue(string name, variant value)
+
+ Sets the \a value of the data input identified with the \a name.
+ */
+
+/*!
+ \qmlsignal void Behavior::onInitialize()
+
+ This signal is emitted when the script becomes active the first time.
+ If multiple behaviors match this, the signal for parent elements will
+ occur before their children/descendants. \note Each behavior will
+ only have its \c{onInitialize} signaled once, even if it is deactivated and
+ later reactivated.
+ */
+
+/*!
+ \qmlsignal void Behavior::onActivate()
+
+ This signal is emitted when the script becomes active.
+ Any behaviors which were not active last frame that are active
+ this frame will have their \c{onActivate} signaled. If
+ multiple behaviors match this, the signal for parent elements will
+ occur before their descendants.
+ */
+
+/*!
+ \qmlsignal void Behavior::onDeactivate()
+
+ This signal is emitted when the script becomes inactive.
+ Any behaviors which were active last frame that are not active
+ this frame will have their \c{onDeactivate} signaled. If
+ multiple behaviors match this, the signal for parent elements will
+ occur before their descendants.
+ */
+
+/*!
+ \qmlsignal void Behavior::onUpdate()
+
+ This signal is emitted on each frame when the script is active.
+ Any behaviors that are active this frame will have their
+ \c{onUpdate} signaled. If multiple behaviors match this, the signal
+ for parent elements will occur before their descendants.
+ */
+
QT_END_NAMESPACE
diff --git a/src/doc/Qt3DStudioRuntime2.qdocconf b/src/runtime/doc/Qt3DStudioRuntime2.qdocconf
index 6f5f526..6f5f526 100644
--- a/src/doc/Qt3DStudioRuntime2.qdocconf
+++ b/src/runtime/doc/Qt3DStudioRuntime2.qdocconf
diff --git a/src/doc/doc.pro b/src/runtime/doc/doc.pri
index eba9ea3..d8615a5 100644
--- a/src/doc/doc.pro
+++ b/src/runtime/doc/doc.pri
@@ -1,5 +1,3 @@
-TEMPLATE = aux
-
build_online_docs: \
QMAKE_DOCS = $$PWD/online/Qt3DStudioRuntime2.qdocconf
else: \
diff --git a/src/doc/online/Qt3DStudioRuntime2.qdocconf b/src/runtime/doc/online/Qt3DStudioRuntime2.qdocconf
index 4602372..4602372 100644
--- a/src/doc/online/Qt3DStudioRuntime2.qdocconf
+++ b/src/runtime/doc/online/Qt3DStudioRuntime2.qdocconf
diff --git a/src/doc/qt3d-runtime-project.qdocconf b/src/runtime/doc/qt3d-runtime-project.qdocconf
index 1c69bf4..4787baf 100644
--- a/src/doc/qt3d-runtime-project.qdocconf
+++ b/src/runtime/doc/qt3d-runtime-project.qdocconf
@@ -1,29 +1,32 @@
project = Qt3DStudioRuntime2
description = Qt 3D Studio Runtime Reference Manual
-version = $QT_VERSION
+version = 2.0
sourcedirs += ./src
imagedirs += ./src/images
-sourcedirs += ../runtime/api
-headerdirs += ../runtime/api
+sourcedirs += ../api
+headerdirs += ../api
-sourcedirs += ../imports/studio3d
-headerdirs += ../imports/studio3d
+sourcedirs += ../../imports/studio3d
+headerdirs += ../../imports/studio3d
+
+sourcedirs += ../behaviorapi
+headerdirs += ../behaviorapi
depends = qtcore qtgui qtwidgets qtqml qtquick qtdoc qt3dcore qt3drender qt3dlogic qt3danimation
qhp.projects = 3dstudioruntime2
qhp.3dstudioruntime2.file = Qt3DStudioRuntime2.qhp
-qhp.3dstudioruntime2.namespace = io.qt.qt3dstudioruntime2.$QT_VERSION_TAG
+qhp.3dstudioruntime2.namespace = io.qt.qt3dstudioruntime2.20
qhp.3dstudioruntime2.virtualFolder = Qt3DStudioRuntime2
qhp.3dstudioruntime2.indexTitle = Qt 3D Studio Runtime
qhp.3dstudioruntime2.indexRoot =
-qhp.3dstudioruntime2.filterAttributes = Qt3DStudioRuntime2 $QT_VERSION
-qhp.3dstudioruntime2.customFilters.Qt.name = Qt3DStudioRuntime2 $QT_VERSION
-qhp.3dstudioruntime2.customFilters.Qt.filterAttributes = Qt3DStudioRuntime2 $QT_VERSION
+qhp.3dstudioruntime2.filterAttributes = Qt3DStudioRuntime2 2.0
+qhp.3dstudioruntime2.customFilters.Qt.name = Qt3DStudioRuntime2 2.0
+qhp.3dstudioruntime2.customFilters.Qt.filterAttributes = Qt3DStudioRuntime2 2.0
qhp.3dstudioruntime2.subprojects = manual qmltypes classes
@@ -47,9 +50,9 @@ HTML.stylesheets += style/qt5-sidebar.html
navigation.homepage = Qt 3D Studio Runtime
navigation.cppclassespage = Qt 3D Studio Runtime C++ Classes
navigation.qmltypespage = Qt 3D Studio Runtime QML Types
-buildversion = "Qt 3D Studio Runtime $QT_VER Manual"
+buildversion = "Qt 3D Studio Runtime 2.0 Manual"
examplesinstallpath = 3dstudioruntime2
-exampledirs += ../../examples/3dstudioruntime2
+exampledirs += ../../../examples/3dstudioruntime2
Cpp.ignoretokens += Q3DSV_EXPORT
diff --git a/src/runtime/doc/src/attributenames.html b/src/runtime/doc/src/attributenames.html
new file mode 100644
index 0000000..35212f7
--- /dev/null
+++ b/src/runtime/doc/src/attributenames.html
@@ -0,0 +1,1099 @@
+\raw HTML
+<table id='scripting-attributes'>
+<tbody></tbody>
+<tr><th colspan="4">Scenes</td></tr>
+<tr>
+<td class='formal'>Name</td>
+<td class='scripting'>name</td>
+<td class='type'>string</td>
+<td class='note'>
+always <code>"Scene"</code>
+</td>
+</tr>
+<tr>
+<td class='formal'></td>
+<td class='scripting'>path</td>
+<td class='type'>string</td>
+<td class='note'>
+always <code>"Scene"</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Enable Background Color</td>
+<td class='scripting'>bgcolorenable</td>
+<td class='type'>boolean</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Background Color R</td>
+<td class='scripting'>backgroundcolor.r</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Background Color G</td>
+<td class='scripting'>backgroundcolor.g</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Background Color B</td>
+<td class='scripting'>backgroundcolor.b</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tbody></tbody>
+<tr><th colspan="4">Elements other than Scenes</td></tr>
+<tr>
+<td class='formal'>Element Name</td>
+<td class='scripting'>name</td>
+<td class='type'>string</td>
+<td class='note'>
+always available
+</td>
+</tr>
+<tr>
+<td class='formal'></td>
+<td class='scripting'>path</td>
+<td class='type'>string</td>
+<td class='note'>
+full path to the element
+</td>
+</tr>
+<tr>
+<td class='formal'>(Eyeball)</td>
+<td class='scripting'>eyeball</td>
+<td class='type'>boolean</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Timebar Start</td>
+<td class='scripting'>starttime</td>
+<td class='type'>number</td>
+<td class='note'>
+in integer milliseconds; always available
+</td>
+</tr>
+<tr>
+<td class='formal'>Timebar End</td>
+<td class='scripting'>endtime</td>
+<td class='type'>number</td>
+<td class='note'>
+in integer milliseconds; always available
+</td>
+</tr>
+<tbody></tbody>
+<tr><th colspan="4">Layers</td></tr>
+<tr>
+<td class='formal'>Disable Depth Test</td>
+<td class='scripting'>disabledepthtest</td>
+<td class='type'>boolean</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Progressive AA</td>
+<td class='scripting'>progressiveaa</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'None'</code>, <code>'2x'</code>, <code>'4x'</code>, <code>'8x'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Multisample AA</td>
+<td class='scripting'>multisampleaa</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'None'</code>, <code>'2x'</code>, <code>'4x'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Temporal AA</td>
+<td class='scripting'>temporalaa</td>
+<td class='type'>boolean</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Layer Background</td>
+<td class='scripting'>background</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'Transparent'</code>, <code>'Unspecified'</code>, <code>'SolidColor'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Background Color R</td>
+<td class='scripting'>backgroundcolor.r</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Background Color G</td>
+<td class='scripting'>backgroundcolor.g</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Background Color B</td>
+<td class='scripting'>backgroundcolor.b</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Horizontal Fields</td>
+<td class='scripting'>horzfields</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'Left/Width'</code>, <code>'Left/Right'</code>, <code>'Width/Right'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Left</td>
+<td class='scripting'>left</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Left Units</td>
+<td class='scripting'>leftunits</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'pixels'</code>, <code>'percent'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Width</td>
+<td class='scripting'>width</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Width Units</td>
+<td class='scripting'>widthunits</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'pixels'</code>, <code>'percent'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Right</td>
+<td class='scripting'>right</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Right Units</td>
+<td class='scripting'>rightunits</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'pixels'</code>, <code>'percent'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Vertical Fields</td>
+<td class='scripting'>vertfields</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'Top/Height'</code>, <code>'Top/Bottom'</code>, <code>'Height/Bottom'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Top</td>
+<td class='scripting'>top</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Top Units</td>
+<td class='scripting'>topunits</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'pixels'</code>, <code>'percent'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Height</td>
+<td class='scripting'>height</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Height Units</td>
+<td class='scripting'>heightunits</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'pixels'</code>, <code>'percent'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Bottom</td>
+<td class='scripting'>bottom</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Bottom Units</td>
+<td class='scripting'>bottomunits</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'pixels'</code>, <code>'percent'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Ambient Occlusion</td>
+<td class='scripting'>aostrength</td>
+<td class='type'>number</td>
+<td class='note'>
+values between 0 and 100
+</td>
+</tr>
+<tr>
+<td class='formal'>AO Distance</td>
+<td class='scripting'>aodistance</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>AO Softness</td>
+<td class='scripting'>aosoftness</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>AO Threshold</td>
+<td class='scripting'>aobias</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>AO Sampling Rate</td>
+<td class='scripting'>aosamplerate</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>AO Dithering</td>
+<td class='scripting'>aodither</td>
+<td class='type'>boolean</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Shadow Strength</td>
+<td class='scripting'>shadowstrength</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Shadow Distance</td>
+<td class='scripting'>shadowdist</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Shadow Softness</td>
+<td class='scripting'>shadowsoftness</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Shadow Threshold</td>
+<td class='scripting'>shadowbias</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Light Probe</td>
+<td class='scripting'>lightprobe</td>
+<td class='type'>image element</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>IBL Horizon Cutoff</td>
+<td class='scripting'>probehorizon</td>
+<td class='type'>number</td>
+<td class='note'>
+values from -1 (no horizon) to -0.001 (hard edge)
+</td>
+</tr>
+<tr>
+<td class='formal'>Sub-Presentation</td>
+<td class='scripting'>sourcepath</td>
+<td class='type'>string</td>
+<td class='note'>
+id of the sub-presentation to display
+</td>
+</tr>
+<tbody></tbody>
+<tr><th colspan="4">Nodes</td></tr>
+<tr>
+<td class='formal'>Position X</td>
+<td class='scripting'>position.x</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Position Y</td>
+<td class='scripting'>position.y</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Position Z</td>
+<td class='scripting'>position.z</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Rotation X</td>
+<td class='scripting'>rotation.x</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Rotation Y</td>
+<td class='scripting'>rotation.y</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Rotation Z</td>
+<td class='scripting'>rotation.z</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Scale X</td>
+<td class='scripting'>scale.x</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Scale Y</td>
+<td class='scripting'>scale.y</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Scale Z</td>
+<td class='scripting'>scale.z</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Pivot X</td>
+<td class='scripting'>pivot.x</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Pivot Y</td>
+<td class='scripting'>pivot.y</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Pivot Z</td>
+<td class='scripting'>pivot.z</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Opacity</td>
+<td class='scripting'>opacity</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'></td>
+<td class='scripting'>orientation</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'Left Handed'</code>, <code>'Right Handed'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'></td>
+<td class='scripting'>rotationorder</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'XYZ'</code>, <code>'YZX'</code>, <code>'ZXY'</code>, <code>'XZY'</code>, <code>'YXZ'</code>, <code>'ZYX'</code>, <code>'XYZr'</code>, <code>'YZXr'</code>, <code>'ZXYr'</code>, <code>'XZYr'</code>, <code>'YXZr'</code>, <code>'ZYXr'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'></td>
+<td class='scripting'>ignoresparent</td>
+<td class='type'>boolean</td>
+<td class='note'>
+prevents parent transformation from being applied
+</td>
+</tr>
+<tbody></tbody>
+<tr><th colspan="4">Aliases</td></tr>
+<tr>
+<td class='formal'>Reference</td>
+<td class='scripting'>referencednode</td>
+<td class='type'>string</td>
+<td class='note'>
+relative or absolute element path
+</td>
+</tr>
+<tbody></tbody>
+<tr><th colspan="4">Cameras</td></tr>
+<tr>
+<td class='formal'>Orthographic</td>
+<td class='scripting'>orthographic</td>
+<td class='type'>boolean</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Field of View</td>
+<td class='scripting'>fov</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Clipping Start</td>
+<td class='scripting'>clipnear</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Clipping End</td>
+<td class='scripting'>clipfar</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Runtime Scale Mode</td>
+<td class='scripting'>scalemode</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'Fit'</code>, <code>'Same Size'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Runtime Scale Anchor</td>
+<td class='scripting'>scaleanchor</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'Center'</code>, <code>'NW'</code>, <code>'N'</code>, <code>'NE'</code>, <code>'E'</code>, <code>'SE'</code>, <code>'S'</code>, <code>'SW'</code>, <code>'W'</code>
+</td>
+</tr>
+<tbody></tbody>
+<tr><th colspan="4">Lights</td></tr>
+<tr>
+<td class='formal'>Scope</td>
+<td class='scripting'>scope</td>
+<td class='type'>string</td>
+<td class='note'>
+full path to the element
+</td>
+</tr>
+<tr>
+<td class='formal'>Light Type</td>
+<td class='scripting'>lighttype</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'Directional'</code>, <code>'Point'</code>, <code>'Area'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Light Color R</td>
+<td class='scripting'>lightdiffuse.r</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Light Color G</td>
+<td class='scripting'>lightdiffuse.g</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Light Color B</td>
+<td class='scripting'>lightdiffuse.b</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Specular Color R</td>
+<td class='scripting'>lightspecular.r</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Specular Color G</td>
+<td class='scripting'>lightspecular.g</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Specular Color B</td>
+<td class='scripting'>lightspecular.b</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Ambient Color R</td>
+<td class='scripting'>lightambient.r</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Ambient Color G</td>
+<td class='scripting'>lightambient.g</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Ambient Color B</td>
+<td class='scripting'>lightambient.b</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Brightness</td>
+<td class='scripting'>brightness</td>
+<td class='type'>number</td>
+<td class='note'>
+only applies to point lights
+</td>
+</tr>
+<tr>
+<td class='formal'>Linear Fade</td>
+<td class='scripting'>linearfade</td>
+<td class='type'>number</td>
+<td class='note'>
+only applies to point lights
+</td>
+</tr>
+<tr>
+<td class='formal'>Exponential Fade</td>
+<td class='scripting'>expfade</td>
+<td class='type'>number</td>
+<td class='note'>
+only applies to point lights
+</td>
+</tr>
+<tr>
+<td class='formal'>Cast Shadows?</td>
+<td class='scripting'>castshadow</td>
+<td class='type'>boolean</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Shadow Darkness</td>
+<td class='scripting'>shdwfactor</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Shadow Softness</td>
+<td class='scripting'>shdwfilter</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Shadow Resolution</td>
+<td class='scripting'>shdwmapres</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'256'</code>, <code>'512'</code>, <code>'1024'</code>, <code>'2048'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Shadow Depth Bias</td>
+<td class='scripting'>shdwbias</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Shadow Far Clip</td>
+<td class='scripting'>shdwmapfar</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+<tr>
+<td class='formal'>Shadow Field of View</td>
+<td class='scripting'>shdwmapfov</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tbody></tbody>
+<tr><th colspan="4">Groups</td></tr>
+<tr>
+<td class='formal'>Import</td>
+<td class='scripting'>sourcepath</td>
+<td class='type'>string</td>
+<td class='note'>
+</td>
+</tr>
+<tbody></tbody>
+<tr><th colspan="4">Text</td></tr>
+<tr>
+<td class='formal'>Text String</td>
+<td class='scripting'>textstring</td>
+<td class='type'>string</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Text Color R</td>
+<td class='scripting'>textcolor.r</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Text Color G</td>
+<td class='scripting'>textcolor.g</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Text Color B</td>
+<td class='scripting'>textcolor.b</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Font</td>
+<td class='scripting'>font</td>
+<td class='type'>string</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Font Size</td>
+<td class='scripting'>size</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Horizontal Alignment</td>
+<td class='scripting'>horzalign</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'Left'</code>, <code>'Center'</code>, <code>'Right'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Vertical Alignment</td>
+<td class='scripting'>vertalign</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'Top'</code>, <code>'Middle'</code>, <code>'Bottom'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Leading</td>
+<td class='scripting'>leading</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Tracking</td>
+<td class='scripting'>tracking</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tbody></tbody>
+<tr><th colspan="4">Models</td></tr>
+<tr>
+<td class='formal'>Mesh</td>
+<td class='scripting'>sourcepath</td>
+<td class='type'>string</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Tessellation Mode</td>
+<td class='scripting'>tessellation</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'None'</code>, <code>'Linear'</code>, <code>'Phong'</code>, <code>'NPatch'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Edge Tessellation Value</td>
+<td class='scripting'>edgetess</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Inner Tessellation Value</td>
+<td class='scripting'>innertess</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tbody></tbody>
+<tr><th colspan="4">Standard Materials</td></tr>
+<tr>
+<td class='formal'>Lighting</td>
+<td class='scripting'>shaderlighting</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'Vertex'</code>, <code>'Pixel'</code>, <code>'None'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Blending Mode</td>
+<td class='scripting'>blendmode</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'Normal'</code>, <code>'Screen'</code>, <code>'Multiply'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Diffuse Color R</td>
+<td class='scripting'>diffuse.r</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Diffuse Color G</td>
+<td class='scripting'>diffuse.g</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Diffuse Color B</td>
+<td class='scripting'>diffuse.b</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Diffuse Map</td>
+<td class='scripting'>diffusemap</td>
+<td class='type'>image element</td>
+<td class='note'>
+to change the image set the <code>sourcepath</code> attribute on the image element
+</td>
+</tr>
+<tr>
+<td class='formal'>Diffuse Map 2</td>
+<td class='scripting'>diffusemap2</td>
+<td class='type'>image element</td>
+<td class='note'>
+to change the image set the <code>sourcepath</code> attribute on the image element
+</td>
+</tr>
+<tr>
+<td class='formal'>Diffuse Map 3</td>
+<td class='scripting'>diffusemap3</td>
+<td class='type'>image element</td>
+<td class='note'>
+to change the image set the <code>sourcepath</code> attribute on the image element
+</td>
+</tr>
+<tr>
+<td class='formal'>Specular Reflection</td>
+<td class='scripting'>specularreflection</td>
+<td class='type'>image element</td>
+<td class='note'>
+to change the image set the <code>sourcepath</code> attribute on the image element
+</td>
+</tr>
+<tr>
+<td class='formal'>Specular Tint R</td>
+<td class='scripting'>speculartint.r</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Specular Tint G</td>
+<td class='scripting'>speculartint.g</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Specular Tint B</td>
+<td class='scripting'>speculartint.b</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Specular Amount</td>
+<td class='scripting'>specularamount</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Specular Map</td>
+<td class='scripting'>specularmap</td>
+<td class='type'>image element</td>
+<td class='note'>
+to change the image set the <code>sourcepath</code> attribute on the image element
+</td>
+</tr>
+<tr>
+<td class='formal'>Specular Model</td>
+<td class='scripting'>specularmodel</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'Default'</code>, <code>'KGGX'</code>, <code>'KWard'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>Fresnel Power</td>
+<td class='scripting'>fresnelPower</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Index of Refraction</td>
+<td class='scripting'>ior</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Specular Roughness</td>
+<td class='scripting'>specularroughness</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Bump Map</td>
+<td class='scripting'>bumpmap</td>
+<td class='type'>image element</td>
+<td class='note'>
+to change the image set the <code>sourcepath</code> attribute on the image element
+</td>
+</tr>
+<tr>
+<td class='formal'>Normal Map</td>
+<td class='scripting'>normalmap</td>
+<td class='type'>image element</td>
+<td class='note'>
+to change the image set the <code>sourcepath</code> attribute on the image element
+</td>
+</tr>
+<tr>
+<td class='formal'>Bump Amount</td>
+<td class='scripting'>bumpamount</td>
+<td class='type'>number</td>
+<td class='note'>
+affects both bump and normal maps
+</td>
+</tr>
+<tr>
+<td class='formal'>Displacement Map</td>
+<td class='scripting'>displacementmap</td>
+<td class='type'>image element</td>
+<td class='note'>
+to change the image set the <code>sourcepath</code> attribute on the image element
+</td>
+</tr>
+<tr>
+<td class='formal'>Displacement Amount</td>
+<td class='scripting'>displaceamount</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Opacity</td>
+<td class='scripting'>opacity</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Opacity Map</td>
+<td class='scripting'>opacitymap</td>
+<td class='type'>image element</td>
+<td class='note'>
+to change the image set the <code>sourcepath</code> attribute on the image element
+</td>
+</tr>
+<tr>
+<td class='formal'>Emissive Power</td>
+<td class='scripting'>emissivepower</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Emissive Map</td>
+<td class='scripting'>emissivemap</td>
+<td class='type'>image element</td>
+<td class='note'>
+to change the image set the <code>sourcepath</code> attribute on the image element
+</td>
+</tr>
+<tbody></tbody>
+<tr><th colspan="4">Material References</td></tr>
+<tr>
+<td class='formal'>Referenced Material</td>
+<td class='scripting'>referencedmaterial</td>
+<td class='type'>string</td>
+<td class='note'>
+relative or absolute element path
+</td>
+</tr>
+<tbody></tbody>
+<tr><th colspan="4">Images</td></tr>
+<tr>
+<td class='formal'>U Repeat</td>
+<td class='scripting'>scaleu</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>V Repeat</td>
+<td class='scripting'>scalev</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Texture Mapping</td>
+<td class='scripting'>mappingmode</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'UV Mapping'</code>, <code>'Environmental Mapping'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>U Tiling</td>
+<td class='scripting'>tilingmodehorz</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'Tiled'</code>, <code>'Mirrored'</code>, <code>'No Tiling'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>V Tiling</td>
+<td class='scripting'>tilingmodevert</td>
+<td class='type'>string</td>
+<td class='note'>
+values: <code>'Tiled'</code>, <code>'Mirrored'</code>, <code>'No Tiling'</code>
+</td>
+</tr>
+<tr>
+<td class='formal'>UV Rotation</td>
+<td class='scripting'>rotationuv</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>U Position</td>
+<td class='scripting'>positionu</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>V Position</td>
+<td class='scripting'>positionv</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>U Pivot</td>
+<td class='scripting'>pivotu</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>V Pivot</td>
+<td class='scripting'>pivotv</td>
+<td class='type'>number</td>
+<td class='note'>
+</td>
+</tr>
+<tr>
+<td class='formal'>Sub-Presentation</td>
+<td class='scripting'>subpresentation</td>
+<td class='type'>string</td>
+<td class='note'>
+id of the sub-presentation to display
+</td>
+</tr>
+<tr>
+<td class='formal'>Source Path</td>
+<td class='scripting'>sourcepath</td>
+<td class='type'>string</td>
+<td class='note'>
+path to the image
+</td>
+</tr>
+</table>
+\endraw
diff --git a/src/runtime/doc/src/attributenames.qdoc b/src/runtime/doc/src/attributenames.qdoc
new file mode 100644
index 0000000..ac24645
--- /dev/null
+++ b/src/runtime/doc/src/attributenames.qdoc
@@ -0,0 +1,42 @@
+/****************************************************************************
+**
+** Copyright (C) 1993-2009 NVIDIA Corporation.
+** Copyright (C) 2018 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qt 3D Studio.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+// This is a wrapper for getting script-generated
+// content in attributenames.html into qdoc.
+// (note: hand edited for 2.0)
+
+/*!
+ \page qt3d-runtime-attribute-names.html
+ \title Attribute Names
+ \keyword Attributes
+
+ Below is a list of the attributes that can be set on the various scene
+ objects via Q3DSPresentation::setAttribute() or Q3DSElement::setAttribute():
+
+ \include attributenames.html
+*/
diff --git a/src/doc/src/copyright.qdoc b/src/runtime/doc/src/copyright.qdoc
index 01275f1..01275f1 100644
--- a/src/doc/src/copyright.qdoc
+++ b/src/runtime/doc/src/copyright.qdoc
diff --git a/src/doc/src/embedded.qdoc b/src/runtime/doc/src/embedded.qdoc
index f665582..095a46d 100644
--- a/src/doc/src/embedded.qdoc
+++ b/src/runtime/doc/src/embedded.qdoc
@@ -29,5 +29,4 @@
\page qt3d-runtime-embedded.html
\title Using the Runtime on Embedded Devices
- embedded stuff (eglfs etc.)
*/
diff --git a/src/doc/src/examples.qdoc b/src/runtime/doc/src/examples.qdoc
index 86cab63..86cab63 100644
--- a/src/doc/src/examples.qdoc
+++ b/src/runtime/doc/src/examples.qdoc
diff --git a/src/runtime/doc/src/gettingstarted.qdoc b/src/runtime/doc/src/gettingstarted.qdoc
new file mode 100644
index 0000000..95acb17
--- /dev/null
+++ b/src/runtime/doc/src/gettingstarted.qdoc
@@ -0,0 +1,78 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qt 3D Studio.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page qt3d-runtime-gettingstarted.html
+ \title Getting Started
+
+ The Qt 3D Studio Runtime provides C++ and QML APIs for integrating Qt 3D
+ Studio scenes into Qt applications, as well as the viewer application that
+ is used in combination with the Qt 3D Studio application during the design
+ phase.
+
+ Once the design is done and the \c{.uia}, \c{.uip}, and other asset files
+ are available, these can be loaded, rendered, and manipulated in Qt
+ applications.
+
+ \section1 Rendering Scenes
+
+ APIs are provided for the following Qt UI technologies:
+
+ \list
+
+ \li Qt Quick: here applications import QtStudio3D 2.0 which provides the
+ Studio3D QML type, a Qt Quick item that can be added to Qt Quick scenes.
+ Under the hood this is similar to adding a Scene3D (when working directly
+ with the lower level Qt 3D framework) or a custom
+ QQuickFramebufferObject-based item into the scene.
+
+ \li Widgets: Q3DSWidget is a QOpenGLWidget subclass that displays Qt 3D
+ Studio scenes.
+
+ \li QWindow or offscreen render targets (OpenGL texture): Q3DSSurfaceViewer
+ can be used both to render to an on-screen QWindow, as well as off-screen
+ into an OpenGL texture. The latter allows reading back and saving the
+ frames, to generate pre-rendered video sequences for example.
+
+ \endlist
+
+ \section1 Manipulating Scenes
+
+ Rendering Qt 3D Studio scenes is only part of the story since many scenes
+ are not static and will not just display all their contents as they were
+ done by designers in the Qt 3D Studio application. Rather, properties of
+ scene objects (for example, the rotation of a 3D model or the diffuse color
+ of the material associated with such a model) may need to be changed
+ dynamically, at run time. The timeline or the current slide may also need
+ to be adjusted based on the user's actions or other application state.
+
+ As of Qt 3D Studio 2.0 such functionality is exposed via the
+ Q3DSPresentation (\l Presentation) objects, Q3DSElement (\l Element),
+ Q3DSSceneElement (\l SceneElement), and Q3DSDataInput (\l DataInput). Advanced
+ scene manipulation (for instance dynamically spawning and removing objects
+ in the 3D scene) will be introduced in future versions.
+*/
diff --git a/src/doc/src/index.qdoc b/src/runtime/doc/src/index.qdoc
index a2c5282..e2a6625 100644
--- a/src/doc/src/index.qdoc
+++ b/src/runtime/doc/src/index.qdoc
@@ -34,14 +34,13 @@
\list
\li \l {Getting Started}
- \li \l {Qt 3D Studio Runtime C++ Classes}
- \li \l {Qt 3D Studio Runtime QML Types}
\li \l {Using the Runtime on Android/iOS Devices}
\li \l {Using the Runtime on Embedded Devices}
+ \li \l {Qt 3D Studio Runtime C++ Classes}
+ \li \l {Qt 3D Studio Runtime QML Types}
+ \li \l {Attribute Names}{Scene object attribute list}
\li \l {Examples}
\li \l {Copyright Notices}
\endlist
-blah blah blah
-
*/
diff --git a/src/doc/src/mobile.qdoc b/src/runtime/doc/src/mobile.qdoc
index 1787b63..45fd6a0 100644
--- a/src/doc/src/mobile.qdoc
+++ b/src/runtime/doc/src/mobile.qdoc
@@ -29,5 +29,4 @@
\page qt3d-runtime-mobile.html
\title Using the Runtime on Android/iOS Devices
- mobile stuff
*/
diff --git a/src/doc/src/module.qdoc b/src/runtime/doc/src/module.qdoc
index d37417f..d37417f 100644
--- a/src/doc/src/module.qdoc
+++ b/src/runtime/doc/src/module.qdoc
diff --git a/src/doc/src/gettingstarted.qdoc b/src/runtime/doc/src/toc.qdoc
index 2f5ae37..9e28102 100644
--- a/src/doc/src/gettingstarted.qdoc
+++ b/src/runtime/doc/src/toc.qdoc
@@ -26,8 +26,15 @@
****************************************************************************/
/*!
- \page qt3d-runtime-gettingstarted.html
- \title Getting Started
+\contentspage {Qt 3D Studio Runtime}
+\page qt3d-runtime-toc.html
+\title Qt 3D Studio Runtime TOC
- Basic blah blah
+\omit
+This file is used for generating a TOC in a .qch file.
+\endomit
+
+\list
+ \li \l {index.html}{Overview}
+\endlist
*/
diff --git a/src/doc/style/qt5-sidebar.html b/src/runtime/doc/style/qt5-sidebar.html
index 89b8c0d..89b8c0d 100644
--- a/src/doc/style/qt5-sidebar.html
+++ b/src/runtime/doc/style/qt5-sidebar.html
diff --git a/src/runtime/q3dsscenemanager.cpp b/src/runtime/q3dsscenemanager.cpp
index f660e2c..6838189 100644
--- a/src/runtime/q3dsscenemanager.cpp
+++ b/src/runtime/q3dsscenemanager.cpp
@@ -575,7 +575,7 @@ void Q3DSSceneManager::prepareEngineResetGlobal()
Q3DSShaderManager::instance().invalidate();
}
-/*!
+/*
Builds and "runs" a Qt 3D scene. To be called once per SceneManager instance.
Ownership of the generated Qt 3D objects is managed primarily via parenting
@@ -796,7 +796,7 @@ Q3DSSceneManager::Scene Q3DSSceneManager::buildScene(Q3DSUipPresentation *presen
return sc;
}
-/*!
+/*
To be called on the scenemanager corresponding to the main presentation
once after all subpresentation buildScene() calls have succeeded. This is
where the association of textures and subpresentation layers happens. That
diff --git a/src/runtime/q3dsuippresentation.cpp b/src/runtime/q3dsuippresentation.cpp
index 5119b49..fe9cf5c 100644
--- a/src/runtime/q3dsuippresentation.cpp
+++ b/src/runtime/q3dsuippresentation.cpp
@@ -3878,8 +3878,8 @@ QHash<QString, bool> &Q3DSUipPresentation::imageTransparencyHash()
return m_imageTransparencyHash;
}
-/*!
- Maps a raw XML filename ref like ".\Headphones\meshes\Headphones.mesh#1"
+/*
+ Maps a raw XML filename ref like "./Headphones/meshes/Headphones.mesh#1"
onto a fully qualified filename that can be opened as-is (even if the uip
is in qrc etc.), and also decodes the optional part index.
*/
diff --git a/src/runtime/runtime.pro b/src/runtime/runtime.pro
index 483ce2b..8a0c957 100644
--- a/src/runtime/runtime.pro
+++ b/src/runtime/runtime.pro
@@ -96,4 +96,6 @@ include(shadergenerator/shadergenerator.pri)
qtConfig(q3ds-profileui): include(profileui/profileui.pri)
+include(doc/doc.pri)
+
load(qt_module)
diff --git a/src/src.pro b/src/src.pro
index d1f86eb..1b02d69 100644
--- a/src/src.pro
+++ b/src/src.pro
@@ -1,8 +1,7 @@
TEMPLATE = subdirs
SUBDIRS += \
- runtime \
- doc
+ runtime
qtHaveModule(quick) {
SUBDIRS += imports