C
Q3DSPresentation Class
Represents a Qt 3D Studio presentation. More...
Header: | #include <Q3DSPresentation> |
qmake: | QT += 3dstudioruntime2 |
Since: | Qt 3D Studio 2.0 |
Instantiated By: | Presentation |
Inherits: | QObject |
Properties
|
|
- 1 property inherited from QObject
Public Functions
Q3DSPresentation(QObject *parent = nullptr) | |
virtual | ~Q3DSPresentation() |
QVector<Q3DSDataInput *> | dataInputs() |
QVector<Q3DSDataInput *> | dataInputs(const QVariant &metadataKey) |
Q3DSEngine * | engine() const |
void | fireEvent(const QString &elementPath, const QString &eventName) |
QVariant | getAttribute(const QString &elementPath, const QString &attributeName) |
QVariantList | getDataInputs() |
void | goToSlide(const QString &elementPath, const QString &name) |
void | goToSlide(const QString &elementPath, int index) |
void | goToSlide(const QString &elementPath, bool next, bool wrap) |
void | goToTime(const QString &elementPath, float timeSeconds) |
bool | isDelayedLoadingEnabled() const |
bool | isProfileUiVisible() const |
bool | isProfilingEnabled() const |
void | keyPressEvent(QKeyEvent *e) |
void | keyReleaseEvent(QKeyEvent *e) |
void | mouseDoubleClickEvent(QMouseEvent *e) |
void | mouseMoveEvent(QMouseEvent *e) |
void | mousePressEvent(QMouseEvent *e) |
void | mouseReleaseEvent(QMouseEvent *e) |
void | preloadSlide(const QString &elementPath) |
float | profileUiScale() const |
void | reload() |
void | setAttribute(const QString &elementPath, const QString &attributeName, const QVariant &value) |
void | setDataInputValue(const QString &name, const QVariant &value) |
void | setDelayedLoading(bool enable) |
void | setProfileUiScale(float scale) |
void | setProfileUiVisible(bool visible) |
void | setProfilingEnabled(bool enable) |
void | setSource(const QUrl &source) |
void | setVariantList(const QStringList &variantList) |
QUrl | source() const |
void | tabletEvent(QTabletEvent *e) |
void | touchEvent(QTouchEvent *e) |
void | unloadSlide(const QString &elementPath) |
QStringList | variantList() const |
void | wheelEvent(QWheelEvent *e) |
- 31 public functions inherited from QObject
Signals
void | customSignalEmitted(const QString &elementPath, const QString &name) |
void | delayedLoadingChanged() |
void | profileUiScaleChanged() |
void | profileUiVisibleChanged() |
void | profilingEnabledChanged() |
void | slideEntered(const QString &elementPath, int index, const QString &name) |
void | slideExited(const QString &elementPath, int index, const QString &name) |
void | sourceChanged() |
void | variantListChanged() |
- 2 signals inherited from QObject
Static Public Members
const QMetaObject | staticMetaObject |
- 9 static public members inherited from QObject
Additional Inherited Members
Detailed Description
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 .uip
file. When present, the .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 .uia
or .uip
file. When specifying a file with .uip
extension and a .uia
is present with the same name, the .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().
Property Documentation
delayedLoading : bool
This property controls whether the presentation resources are loaded while loading the presentation(false) or afterwards when they are actually used in the presentation(true). The resources are loaded per slide basis so that all resources required by a slide will be loaded at once.
The resources can be images, subpresentations, materials, effects and meshes.
Default is false.
Access functions:
bool | isDelayedLoadingEnabled() const |
void | setDelayedLoading(bool enable) |
Notifier signal:
void | delayedLoadingChanged() |
profileUiScale : float
Controls the scale factor of the in-scene debug and profile views.
The default value is 1.0.
Access functions:
float | profileUiScale() const |
void | setProfileUiScale(float scale) |
Notifier signal:
void | profileUiScaleChanged() |
profileUiVisible : bool
When this property is 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 false
.
Access functions:
bool | isProfileUiVisible() const |
void | setProfileUiVisible(bool visible) |
Notifier signal:
void | profileUiVisibleChanged() |
profilingEnabled : bool
When enabled, Qt 3D objects managed by the runtime get tracked, and various statistics get collected internally. These are then exposed in the views that can be toggled by profileUiVisible.
The default value is false
.
Note: Changing the value after the presentation has been loaded has no effect for the already loaded presentation. Therefore the changing of this property must happen before calling setSource().
Note: In the Qt 3D Studio Viewer application presentations are opened with profiling enabled by default. Therefore, applications wishing to have an experience comparable to the Viewer, when it comes to the debug and profile views, should set this property to true
.
Access functions:
bool | isProfilingEnabled() const |
void | setProfilingEnabled(bool enable) |
Notifier signal:
void | profilingEnabledChanged() |
source : QUrl
Holds the name of the main presentation file (*.uia
or *.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.
Access functions:
QUrl | source() const |
void | setSource(const QUrl &source) |
Notifier signal:
void | sourceChanged() |
variantList : QStringList
Holds a list of (variant group):(variant) tags that are loaded when the source
property is set. If this list is left empty (default), no variant filtering is applied and all items are loaded regardless of variant tags in the presentation. Variant mechanism allows one presentation project to contain multiple variants of the presentation and the decision which variant set is loaded is determined during runtime based on the variantList
.
Variants are divided to variant groups, e.g. one variant group could be region
and the variants within that group could be e.g. US, EU, CH
. Another variant group could be e.g. power
and variants within that could be e.g. gas, electric, diesel
. To filter in this example an electric variant for the EU region, the variantList needs to contain two strings "region:EU" and "power:electric". Also of course the presentation project needs to contain these variant groups and tags applied appropriately to the presentation content.
When variant filters are used, the decision what gets loaded and what is not loaded is based on checking every item in the presentation:
- If the item has no variant tags, it will be loaded.
- If the item has no tags defined for the checked variant group(s), it will be loaded.
- If the item has tag(s) for the variant group, any of those tags must match any of the variants defined in the filter for that group.
If the item doesn't fulfill the above rules it will not be loaded.
Access functions:
QStringList | variantList() const |
void | setVariantList(const QStringList &variantList) |
Notifier signal:
void | variantListChanged() |
Member Function Documentation
Q3DSPresentation::Q3DSPresentation(QObject *parent = nullptr)
Constructs a new Q3DSPresentation with the given parent.
[virtual]
Q3DSPresentation::~Q3DSPresentation()
Destructor.
[signal]
void Q3DSPresentation::customSignalEmitted(const QString &elementPath, const QString &name)
This signal is emitted when an action with the Emit Signal
handler is executed in the Qt 3D Studio presentation. elementPath specifies the scene object on which the (Qt 3D Studio) "signal" name was triggered.
Connecting to this signal offers a way of reacting upon certain events in the Qt 3D Studio presentation.
In this example, pressing or tapping on the Cluster object will result in emitting customSignalEmitted("Cluster", "clusterPressed")
.
QVector<Q3DSDataInput *> Q3DSPresentation::dataInputs()
Returns a list of data inputs defined for this presentation. Use setDataInputValue() interface to set a data input value by name, or call Q3DSDataInput::setValue() directly on a specific data input.
See also setDataInputValue and Q3DSDataInput.
QVector<Q3DSDataInput *> Q3DSPresentation::dataInputs(const QVariant &metadataKey)
Returns a list of data inputs defined for this presentation which have metadata key metadataKey.
See also Q3DSDataInput.
Q3DSEngine *Q3DSPresentation::engine() const
Returns the underlying Q3DSEngine. See Advanced Scene Manipulation via the Qt 3D Studio Runtime Private C++ Classes for details on using such private APIs.
The engine is only available when a presentation is loaded, the return value is null
otherwise.
void Q3DSPresentation::fireEvent(const QString &elementPath, const QString &eventName)
Dispatches a Qt 3D Studio presentation event with eventName on scene object specified by elementPath. These events provide a way to communicate with the .qml
based behavior scripts
attached to scene objects since they can register to be notified via Behavior::registerForEvent().
See setAttribute() for a description of elementPath.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
QVariant Q3DSPresentation::getAttribute(const QString &elementPath, const QString &attributeName)
Returns the value of an attribute (property) on the object specified by elementPath. The attributeName is the scripting name of the attribute.
See setAttribute() for a description of elementPath.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
See also setAttribute.
QVariantList Q3DSPresentation::getDataInputs()
Returns a list of data inputs defined for this presentation as a QVariantList.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
See also dataInputs().
void Q3DSPresentation::goToSlide(const QString &elementPath, const QString &name)
Requests a time context (a Scene or a Component object) to change to a specific slide by name. If the context is already on that slide, playback will start over.
If 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 "SubPresentationOne:Scene"
.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
void Q3DSPresentation::goToSlide(const QString &elementPath, int index)
Requests a time context (a Scene or a Component object) to change to a specific slide by index. If the context is already on that slide, playback will start over.
If 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 "SubPresentationOne:Scene"
.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
void Q3DSPresentation::goToSlide(const QString &elementPath, bool next, bool wrap)
Requests a time context (a Scene or a Component object) to change to the next or previous slide, depending on the value of next. If the context is already at the last or first slide, wrap defines if wrapping over to the first or last slide, respectively, occurs.
If 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 "SubPresentationOne:Scene"
.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
void Q3DSPresentation::goToTime(const QString &elementPath, float timeSeconds)
Moves the timeline for a time context (a Scene or a Component element) to a specific position. The position is given in seconds in timeSeconds.
If 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 "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:
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.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.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.Ping
- values less than 0 are treated as time 0, while values greater than the endtime bounce off the end (eventually hitting 0.)
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
void Q3DSPresentation::keyPressEvent(QKeyEvent *e)
Passes a key press event e to the presentation.
Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.
void Q3DSPresentation::keyReleaseEvent(QKeyEvent *e)
Passes a key release event e to the presentation.
Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.
void Q3DSPresentation::mouseDoubleClickEvent(QMouseEvent *e)
Passes a mouse double click event e to the presentation.
Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.
void Q3DSPresentation::mouseMoveEvent(QMouseEvent *e)
Passes a mouse move event e to the presentation.
Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.
void Q3DSPresentation::mousePressEvent(QMouseEvent *e)
Passes a mouse press event e to the presentation.
Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.
void Q3DSPresentation::mouseReleaseEvent(QMouseEvent *e)
Passes a mouse release event e to the presentation.
Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.
void Q3DSPresentation::preloadSlide(const QString &elementPath)
Preloads slide resources to memory. The elementPath specifies the time context (a Scene or a Component element) owning the slide. All resources required by the given slide will be loaded in the background. This function has an effect only when delayed loading is enabled.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
void Q3DSPresentation::reload()
Reloads the presentation.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
void Q3DSPresentation::setAttribute(const QString &elementPath, const QString &attributeName, const QVariant &value)
Sets the value of an attribute (property) on the object specified by elementPath. The attributeName is the 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 #
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, Scene.Layer.Camera
. Here the right camera object gets chosen even if the scene contains other layers with the default camera names (for instance 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 MyCamera
, applications can then simply pass MyCamera
as the element path.
To reference an object stored in a property of another object, the dot syntax can be used. The most typical example of this is changing the source of a texture map by changing the sourcepath
property on the object selected by SomeMaterial.diffusemap
.
To access an object in a sub-presentation, prepend the name of the sub-presentation followed by a colon, for example, SubPresentationOne:Scene.Layer.Camera
.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
See also getAttribute.
void Q3DSPresentation::setDataInputValue(const QString &name, const QVariant &value)
Sets the value of a data input element 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.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[signal]
void Q3DSPresentation::slideEntered(const QString &elementPath, int index, const QString &name)
This signal is emitted when a slide is entered in the presentation. The elementPath specifies the time context (a Scene or a Component element) owning the entered slide. The index and name contain the index and the name of the entered slide.
[signal]
void Q3DSPresentation::slideExited(const QString &elementPath, int index, const QString &name)
This signal is emitted when a slide is exited in the presentation. The elementPath specifies the time context (a Scene or a Component element) owning the exited slide. The index and name contain the index and the name of the exited slide.
void Q3DSPresentation::tabletEvent(QTabletEvent *e)
Passes a tablet (pen) event e to the presentation.
Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.
void Q3DSPresentation::touchEvent(QTouchEvent *e)
Passes a touch event e to the presentation.
Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.
void Q3DSPresentation::unloadSlide(const QString &elementPath)
Unloads slide resources from memory. The elementPath specifies the time context (a Scene or a Component element) owning the slide. If the slide is current, then the resources are unloaded when the slide is changed. This function has an effect only when delayed loading is enabled.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
void Q3DSPresentation::wheelEvent(QWheelEvent *e)
Passes a mouse wheel event e to the presentation.
Note: The event forwarders in Q3DSPresentation are not normally needed since Q3DSWidget and Studio3D both pass mouse, keyboard and touch input on to the Qt 3D Studio engine. They may become useful however with Q3DSSurfaceViewer, or in special situations, in order to inject input events.
Available under certain Qt licenses.
Find out more.