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()

Static Public Members

const QMetaObject staticMetaObject
  • 9 static public members inherited from QObject

Additional Inherited Members

  • 1 public slot inherited from QObject
  • 9 protected functions inherited from QObject

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.