Q3DSPresentation Class | OpenGL Runtime 2.8.0

- OpenGL Runtime
- OpenGL Runtime
- C++ Classes
- Q3DSPresentation
- Qt 3D Studio OpenGL Runtime 2.8 Manual

# Q3DSPresentation Class

Represents a Qt 3D Studio presentation. More...

Header: | #include <Q3DSPresentation>
Since: | Qt 3D Studio 2.0
Inherits: | QObject

- List of all members, including inherited members
- Obsolete members

## Properties

- createdElements : const QStringList
- createdMaterials : const QStringList
- createdMeshes : const QStringList
- delayedLoading : bool

- shaderCacheFile : QUrl
- source : QUrl
- variantList : QStringList

- 1 property inherited from QObject

## Public Functions

| Q3DSPresentation(QObject *parent = nullptr)
virtual | ~Q3DSPresentation()
void | addImageProvider(const QString &providerId, QQmlImageProviderBase *provider)
void | createElement(const QString &parentElementPath, const QString &slideName, const QHash<QString, QVariant> &properties)
void | createElements(const QString &parentElementPath, const QString &slideName, const QVector<QHash<QString, QVariant> > &properties)
void | createMaterial(const QString &materialDefinition, const QString &subPresId = {})
void | createMaterials(const QStringList &materialDefinitions, const QString &subPresId = {})
void | createMesh(const QString &meshName, const Q3DSGeometry &geometry)
void | createMeshes(const QHash<QString, const Q3DSGeometry *> &meshData)
QStringList | createdElements() const
QStringList | createdMaterials() const
QStringList | createdMeshes() const
QVector<Q3DSDataInput *> | dataInputs() const
QVector<Q3DSDataInput *> | dataInputs(const QString &metadataKey) const
QVector<Q3DSDataOutput *> | dataOutputs() const
bool | delayedLoading() const
void | deleteElement(const QString &elementPath)
void | deleteElements(const QStringList &elementPaths)
void | deleteMaterial(const QString &materialName)
void | deleteMaterials(const QStringList &materialNames)
void | deleteMesh(const QString &meshName)
void | deleteMeshes(const QStringList &meshNames)
void | exportShaderCache(const QUrl &shaderCacheFile, bool binaryShaders)
void | exportShaderCache(bool binaryShaders)
void | exportShaderCache(QByteArray &cacheData, bool binaryShaders)
void | exportShaderCache(const QUrl &shaderCacheFile, bool binaryShaders, int compressionLevel)
void | exportShaderCache(bool binaryShaders, int compressionLevel)
void | exportShaderCache(QByteArray &cacheData, bool binaryShaders, int compressionLevel)
QVariantList | getDataInputs() const
QVariantList | getDataInputs(const QString &metadataKey) const
QVariantList | getDataOutputs() const
void | preloadSlide(const QString &elementPath)
void | setDelayedLoading(bool enable)
void | setShaderCacheData(const QByteArray &shaderCache)
QUrl | shaderCacheFile() const
QUrl | source() const
uint | textureId(const QString &elementPath)
uint | textureId(const QString &elementPath, QSize &size, GLenum &format)
void | unloadSlide(const QString &elementPath)
QStringList | variantList() const

- 31 public functions inherited from QObject

## Public Slots

void | fireEvent(const QString &elementPath, const QString &eventName)
void | goToSlide(const QString &elementPath, unsigned int index)
void | goToSlide(const QString &elementPath, const QString &name)
void | goToSlide(const QString &elementPath, bool next, bool wrap)
void | goToTime(const QString &elementPath, float time)
void | setAttribute(const QString &elementPath, const QString &attributeName, const QVariant &value)
void | setDataInputValue(const QString &name, const QVariant &value, bool force = false)
void | setGlobalAnimationTime(qint64 milliseconds)
void | setPresentationActive(const QString &id, bool active)
void | setShaderCacheFile(const QUrl &fileName)
void | setSource(const QUrl &source)
void | setVariantList(const QStringList &variantList)

- 1 public slot inherited from QObject

## Signals

void | customSignalEmitted(const QString &elementPath, const QString &name)
void | dataInputsReady()
void | dataOutputsReady()
void | delayedLoadingChanged(bool enable)
void | elementsCreated(const QStringList &elementPaths, const QString &error)
void | materialsCreated(const QStringList &materialNames, const QString &error)
void | meshesCreated(const QStringList &meshNames, const QString &error)
void | shaderCacheExported(bool success)
void | shaderCacheFileChanged(const QUrl &fileName)
void | shaderCacheLoadErrors(const QString &errors)
void | slideEntered(const QString &elementPath, unsigned int index, const QString &name)
void | slideExited(const QString &elementPath, unsigned int index, const QString &name)
void | sourceChanged(const QUrl &source)
void | variantListChanged(const QStringList &variantList)

- 2 signals inherited from QObject

## Static Public Members

const QMetaObject | staticMetaObject

- 9 static public members inherited from QObject

### Additional Inherited Members

- 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 subpresentations. The subpresentations 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` presentation file. When present, the `.uia` project file ties these together by specifying a name for each of the (sub-)presentations and specifies which one is the main one.

The `.uia` project also defines DataInputs and DataOutputs that are exported by the presentations. DataInputs provide a way to provide input to the presentation to e.g. control a timeline of a subpresentation from code. `DataOutput`s provide a way to get notified when an attribute is changed in the presentation by animation timeline, by behavior scripts or by a DataInput.

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 creates a Q3DSPresentation instance implicitly. This can be queried via Q3DSSurfaceViewer::presentation().

## Property Documentation

### createdElements : const QStringList

This property contains a list of all dynamically created elements on this presentation.

This property is read-only.

Access functions:

QStringList | createdElements() const

Notifier signal:

void | elementsCreated(const QStringList &elementPaths, const QString &error)

See also createElement() and createElements().

### createdMaterials : const QStringList

This property contains a list of all dynamically created materials on this presentation.

This property is read-only.

Access functions:

QStringList | createdMaterials() const

Notifier signal:

void | materialsCreated(const QStringList &materialNames, const QString &error)

See also createMaterial() and createMaterials().

### createdMeshes : const QStringList

This property contains a list of all dynamically created meshes on this presentation.

This property is read-only.

Access functions:

QStringList | createdMeshes() const

Notifier signal:

void | meshesCreated(const QStringList &meshNames, const QString &error)

See also createMesh() and createMeshes().

### 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 | delayedLoading() const
void | setDelayedLoading(bool enable)

Notifier signal:

void | delayedLoadingChanged(bool enable)

### shaderCacheFile : QUrl

Specifies the shader cache file to be used for initial shader initialization. This property value must be set before the presentation is shown. Using cached shaders improves presentation initialization speed.

If this property is not set and setShaderCacheData is not called, all shaders are generated normally.

If this property points to a valid shader cache file, new shader cache generation is not supported.

The default value is an empty url.

This property was introduced in Qt 3D Studio 2.5.

Access functions:

QUrl | shaderCacheFile() const
void | setShaderCacheFile(const QUrl &fileName)

Notifier signal:

void | shaderCacheFileChanged(const QUrl &fileName)

See also exportShaderCache() and setShaderCacheData.

### 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.

Currently set variantList will modify which variant groups and tags are loaded from the presentations. See Q3DSPresentation::variantList property.

Access functions:

QUrl | source() const
void | setSource(const QUrl &source)

Notifier signal:

void | sourceChanged(const QUrl &source)

### 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(const QStringList &variantList)

## Member Function Documentation

### Q3DSPresentation::Q3DSPresentation(QObject *parent = nullptr)

Constructs a new Q3DSPresentation with the given parent.

### `[virtual]` Q3DSPresentation::~Q3DSPresentation()

Destructor.

### void Q3DSPresentation::addImageProvider(const QString &providerId, QQmlImageProviderBase *provider)

Sets the provider to use for images requested via the image: url scheme, with host providerId. The runtime takes ownership of provider.

Texture sourcepaths can then be set using the image url scheme. For example "image://colors/blue" where "image://" tells the runtime to look for an image provider, "colors" is the image provider id and rest are the image id the provider uses to create the image.

Usage is similar to the examples in https://doc.qt.io/qt-5/qquickimageprovider.html

     // Example implementation of a request function
     // This returns a 50 x 50 px size green texture as a QPixmap
     QPixmap ImageProvider::requestPixmap(const QString &id, QSize *size, const QSize &requestedSize)
     {
         // Size needs to be more than 0,0 or nothing will be drawn
         if (size)
             *size = QSize(50, 50);

         QPixmap pixmap(50, 50);
         pixmap.fill(QColor("green"));
         return pixmap;
     }

     // Image providers are added to the presentation after viewer creation
     viewer.create(&window, &context);
     viewer.presentation()->addImageProvider("green", new ImageProvider());

     // Use as texture
     viewer.presentation()->setAttribute("Scene.Layer.Rectangle.Material.diffusemap", "sourcepath", "image://green");

This function was introduced in Qt 3D Studio 2.5.

### void Q3DSPresentation::createElement(const QString &parentElementPath, const QString &slideName, const QHash<QString, QVariant> &properties)

Adds a new child element for the element specified by parentElementPath to the slide specified with slideName. Only model and group element creation is currently supported. The properties hash table specifies the name-value pairs of the properties of the new element. The property names are the same the setAttribute() recognizes.

A referenced material element is also created for the new model element. The source material name can be specified with custom "material" attribute in the properties hash. The source material must exist in the same presentation where the element is created.

The mesh for a model is specified with the `sourcepath` property. This can be a local file path to `.mesh` file, a studio mesh primitive (e.g. `#Cube`), or the name of a mesh created dynamically with createMesh().

A property/properties of the element can be bound to be controlled by an existing datainput. Control bindings can be indicated with custom "controlledproperty" attribute in the properties hash. The format for attribute value is "$<datainputname> <attributename>", i.e. "$Datainput_1 rotation $Datainput_2 diffusecolor". If datainput name does not match with any of the datainputs defined in UIA file, binding has no impact.

The element is ready for use once elementsCreated() signal is received for it.

Note: If your application is creating and deleting a lot of elements, it is recommended that you reuse previously deleted element names when creating new elements. This is because the internal string table implementation of Qt 3D Studio ogl-runtime doesn't support removing strings for performance reasons, so always using new unique names will leak memory.

See also createElements(), createMaterial(), createMesh(), elementsCreated(), setAttribute(), and dataInputs().

### void Q3DSPresentation::createElements(const QString &parentElementPath, const QString &slideName, const QVector<QHash<QString, QVariant> > &properties)

Adds multiple new child elements for the element specified by parentElementPath to the slide specified with slideName. Element properties are specified in properties. For more details, see createElement().

See also Q3DSPresentation::createElement() and Q3DSPresentation::elementsCreated().

### void Q3DSPresentation::createMaterial(const QString &materialDefinition, const QString &subPresId = {})

Creates a material specified by the materialDefinition parameter into the subpresentation specified by the subPresId parameter. If subPresId is empty, the material is created into the main presentation.

The materialDefinition parameter can contain either the file path to a Qt 3D Studio material definition file or the actual material definition in the Qt 3D Studio material definition format. The material definition is a XML file that specifies the material properties. They are not meant to be hand crafted - to create one, simply create a new basic material in the Qt 3D Studio editor and edit the material properties in the inspector. The properties are stored into `materialName.materialdef` file in `materials` folder of the project, which you can include into the resources of you application and use with this method.

After creation, the material can be used for new elements created via createElement() by setting `material` property of the new element to the name of the created material. The material name is specified by the `name` property of the material definition.

The material is ready for use once materialsCreated() signal is received for it.

Note: If your application is creating and deleting a lot of materials, it is recommended that you reuse previously deleted material names when creating new materials. This is because the internal string table implementation of Qt 3D Studio ogl-runtime doesn't support removing strings for performance reasons, so always using new unique names will leak memory.

Note: Creating materials that utilise custom shaders with mipmapped textures can in some cases corrupt the textures on other elements if the same textures are already used by existing basic materials in the scene, as basic materials do not create mipmaps for their textures. Typical symptom of this is black texture on another element after creating a new element using the custom material.

See also createMaterials(), createElement(), and materialsCreated().

### void Q3DSPresentation::createMaterials(const QStringList &materialDefinitions, const QString &subPresId = {})

Creates multiple materials specified by the materialDefinitions parameter into the subpresentation specified by the subPresId parameter. If subPresId is empty, the materials are created into the main presentation.

For more details, see createMaterial().

See also createMaterial() and materialsCreated().

### void Q3DSPresentation::createMesh(const QString &meshName, const Q3DSGeometry &geometry)

Creates a mesh specified by given geometry. The given meshName can be used as `sourcepath` property value for model elements created with future createElement() calls.

The mesh is ready for use once meshesCreated() signal is received for it.

See also createElement(), createMeshes(), and meshesCreated().

### void Q3DSPresentation::createMeshes(const QHash<QString, const Q3DSGeometry *> &meshData)

Creates multiple meshes specified by given meshData. The data is mesh name and geometry pairs. For more details, see createMesh().

The ownership of supplied geometries stays with the caller.

Note: If your application is creating and deleting a lot of meshes, it is recommended that you reuse previously deleted mesh names when creating new materials. This is because the internal string table implementation of Qt 3D Studio OpenGL Runtime doesn't support removing strings for performance reasons, so always using new unique names will leak memory.

See also createMesh() and meshesCreated().

### `[signal]` void Q3DSPresentation::customSignalEmitted(const QString &elementPath, const QString &name)

Emitted when an action with the `Emit Signal` handler is executed in the Qt 3D Studio presentation. elementPath specifies `Target Object`, and name specifies `Signal Name`.

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

Returns a list of datainputs defined for this presentation. Use setDataInputValue() interface to set a datainput value using datainput name, or call Q3DSDataInput::setValue directly for a specific datainput.

See also setDataInputValue() and Q3DSDataInput.

### QVector<Q3DSDataInput *> Q3DSPresentation::dataInputs(const QString &metadataKey) const

Returns a list of datainputs defined for this presentation that have the specified metadataKey.

See also setDataInputValue() and Q3DSDataInput.

### `[signal]` void Q3DSPresentation::dataInputsReady()

Emitted when DataInputs in the Studio project have been parsed and data inputs are available through dataInputs() and getDataInputs() methods.

### QVector<Q3DSDataOutput *> Q3DSPresentation::dataOutputs() const

Returns a list of dataoutputs defined for this presentation. Use Qt's connect() method to connect slots to the valueChanged() signal in the required DataOutputs to get notified when the value tracked by the DataOutput is changed.

See also Q3DSDataOutput.

### `[signal]` void Q3DSPresentation::dataOutputsReady()

Emitted when DataOutputs in the Studio project have been parsed and data outputs are available through dataOutputs() and getDataOutputs() methods.

### void Q3DSPresentation::deleteElement(const QString &elementPath)

Deletes the element specified by elementPath and all its child elements. Deleting elements is supported only for elements that have been dynamically created with createElement() or createElements().

See also deleteElements() and createElement().

### void Q3DSPresentation::deleteElements(const QStringList &elementPaths)

Deletes multiple elements specified by elementPaths and all their child elements. Deleting elements is supported only for elements that have been dynamically created with createElement() or createElements().

See also deleteElement().

### void Q3DSPresentation::deleteMaterial(const QString &materialName)

Deletes the material specified by materialName from the presentation. To delete material from a subpresentation, prefix materialName with the subpresentation ID similarly to the element paths. For example: `"SubPresentationOne:MyMaterial"`.

Deleting materials is supported only for materials that have been dynamically created with createMaterial() or createMaterials().

See also deleteMaterials() and createMaterial().

### void Q3DSPresentation::deleteMaterials(const QStringList &materialNames)

Deletes materials specified by materialNames from the presentation. To delete material from a subpresentation, prefix the material name with the subpresentation ID similarly to the element paths. For example: `"SubPresentationOne:MyMaterial"`.

Deleting materials is supported only for materials that have been dynamically created with createMaterial() or createMaterials().

See also deleteMaterial().

### void Q3DSPresentation::deleteMesh(const QString &meshName)

Deletes the mesh specified by meshName. Deleting meshes is supported only for meshes that have been dynamically created with createMesh() or createMeshes().

See also deleteMeshes() and createMesh().

### void Q3DSPresentation::deleteMeshes(const QStringList &meshNames)

Deletes meshes specified by meshNames. Deleting meshes is supported only for meshes that have been dynamically created with createMesh() or createMeshes().

See also deleteMesh().

### `[signal]` void Q3DSPresentation::elementsCreated(const QStringList &elementPaths, const QString &error)

Emitted when one or more elements have been created in response to createElement() or createElements() calls. The elementPaths list contains the element paths of the created elements. If creation failed, error string indicates the reason.

Note: Notifier signal for property createdElements.

See also createElement() and createElements().

### void Q3DSPresentation::exportShaderCache(const QUrl &shaderCacheFile, bool binaryShaders)

Writes the shaders currently in use to the file specified by shaderCacheFile URL. If binaryShaders property is `true`, precompiled shaders are exported. Otherwise, compressed shader source code is exported.

The shaderCacheExported signal is emitted when the export is complete.

Exporting shader cache should be done at the point of application execution where all the shaders that should be initialized at application startup have been initialized.

Note: Exporting shader cache is only supported if no shaders have been originally loaded from a shader cache. Specifying no shader cache file or an empty or invalid shader cache file with shaderCacheFile property allows shader generation.

This function was introduced in Qt 3D Studio 2.5.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also shaderCacheFile, shaderCacheExported, and qCompress.

### void Q3DSPresentation::exportShaderCache(bool binaryShaders)

Exports the shaders currently in use and dumps the resulting cache encoded with base64 into stderr. This function is provided as a means to extract the shader cache from environments without a writable disk. The base64 output needs to be converted back to binary representation to be usable as a shader cache file. The Qt 3D Studio Viewer provides a command line parameter `--convert-shader-cache` to do this conversion.

If binaryShaders property is `true`, precompiled shaders are exported. Otherwise, compressed shader source code is exported.

The shaderCacheExported signal is emitted when the export is complete.

Exporting shader cache should be done at the point of application execution where all the shaders that should be initialized at application startup have been initialized.

Note: Exporting shader cache is only supported if no shaders have been originally loaded from a shader cache. Specifying no shader cache file or an empty or invalid shader cache file with shaderCacheFile property allows shader generation.

This function was introduced in Qt 3D Studio 2.5.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also shaderCacheFile, shaderCacheExported, and qCompress.

### void Q3DSPresentation::exportShaderCache(QByteArray &cacheData, bool binaryShaders)

Exports the shaders currently in use to a byte array specified by cacheData parameter. If binaryShaders property is `true`, precompiled shaders are exported. Otherwise, compressed shader source code is exported.

The shaderCacheExported signal is emitted when the export is complete.

Exporting shader cache should be done at the point of application execution where all the shaders that should be initialized at application startup have been initialized.

Note: Exporting shader cache is only supported if no shaders have been originally loaded from a shader cache.

This function was introduced in Qt 3D Studio 2.6.

See also setShaderCacheData, shaderCacheExported, and qCompress.

### void Q3DSPresentation::exportShaderCache(const QUrl &shaderCacheFile, bool binaryShaders, int compressionLevel)

Writes the shaders currently in use to the file specified by shaderCacheFile URL. If binaryShaders property is `true`, precompiled shaders are exported. Otherwise, compressed shader source code is exported. The exported shaders are compressed using compression level specified by compressionLevel. `-1` means default qCompress compression level. `0` means no compression.

The shaderCacheExported signal is emitted when the export is complete.

Exporting shader cache should be done at the point of application execution where all the shaders that should be initialized at application startup have been initialized.

Note: Exporting shader cache is only supported if no shaders have been originally loaded from a shader cache. Specifying no shader cache file or an empty or invalid shader cache file with shaderCacheFile property allows shader generation.

This function was introduced in Qt 3D Studio 2.7.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also shaderCacheFile, shaderCacheExported, and qCompress.

### void Q3DSPresentation::exportShaderCache(bool binaryShaders, int compressionLevel)

Exports the shaders currently in use and dumps the resulting cache encoded with base64 into stderr. This function is provided as a means to extract the shader cache from environments without a writable disk. The base64 output needs to be converted back to binary representation to be usable as a shader cache file. The Qt 3D Studio Viewer provides a command line parameter `--convert-shader-cache` to do this conversion.

If binaryShaders property is `true`, precompiled shaders are exported. Otherwise, compressed shader source code is exported. The exported shaders are compressed using compression level specified by compressionLevel. `-1` means default qCompress compression level. `0` means no compression.

The shaderCacheExported signal is emitted when the export is complete.

Exporting shader cache should be done at the point of application execution where all the shaders that should be initialized at application startup have been initialized.

Note: Exporting shader cache is only supported if no shaders have been originally loaded from a shader cache. Specifying no shader cache file or an empty or invalid shader cache file with shaderCacheFile property allows shader generation.

This function was introduced in Qt 3D Studio 2.7.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also shaderCacheFile, shaderCacheExported, and qCompress.

### void Q3DSPresentation::exportShaderCache(QByteArray &cacheData, bool binaryShaders, int compressionLevel)

Exports the shaders currently in use to a byte array specified by cacheData parameter. If binaryShaders property is `true`, precompiled shaders are exported. Otherwise, compressed shader source code is exported. The exported shaders are compressed using compression level specified by compressionLevel. `-1` means default qCompress compression level. `0` means no compression.

The shaderCacheExported signal is emitted when the export is complete.

Exporting shader cache should be done at the point of application execution where all the shaders that should be initialized at application startup have been initialized.

Note: Exporting shader cache is only supported if no shaders have been originally loaded from a shader cache.

This function was introduced in Qt 3D Studio 2.7.

See also setShaderCacheData, shaderCacheExported, and qCompress.

### `[slot]` 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.

### QVariantList Q3DSPresentation::getDataInputs() const

Returns a list of datainputs defined for this presentation. Use setDataInputValue() interface to set a datainput value using datainput name, or call Q3DSDataInput::setValue directly for a specific datainput.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also setDataInputValue() and Q3DSDataInput.

### QVariantList Q3DSPresentation::getDataInputs(const QString &metadataKey) const

Returns a list of datainputs defined for this presentation that have the specified metadataKey.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also setDataInputValue() and Q3DSDataInput.

### QVariantList Q3DSPresentation::getDataOutputs() const

*

Q3DSPresentation::getDataOutputs Returns DataOutputs. Returns a list of dataoutputs defined for this presentation. Use Qt's connect() method to connect slots to the valueChanged() signal in the required DataOutputs to get notified when the value tracked by the DataOutput is changed.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also Q3DSDataOutput.

### `[slot]` void Q3DSPresentation::goToSlide(const QString &elementPath, unsigned int index)

This function is for backwards compatibility. We recommend using DataInputs to control slide changes. DataInput provides stronger contract between the design and code as it avoids use of elementPath (a reference to design's internal structure).

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. Slide indexing starts from one.

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"`.

### `[slot]` void Q3DSPresentation::goToSlide(const QString &elementPath, const QString &name)

This function is for backwards compatibility. We recommend using DataInputs to control slide changes. DataInput provides stronger contract between the design and code as it avoids use of elementPath (a reference to design's internal structure).

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"`.

### `[slot]` void Q3DSPresentation::goToSlide(const QString &elementPath, bool next, bool wrap)

This function is for backwards compatibility. We recommend using DataInputs to control slide changes. DataInput provides stronger contract between the design and code as it avoids use of elementPath (a reference to design's internal structure).

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"`.

### `[slot]` void Q3DSPresentation::goToTime(const QString &elementPath, float time)

This function is for backwards compatibility. We recommend using DataInputs to control slide changes. DataInput provides stronger contract between the design and code as it avoids use of elementPath (a reference to design's internal structure).

Moves the timeline for a time context (a Scene or a Component element) to a specific position. The position is given in seconds in time.

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

### `[signal]` void Q3DSPresentation::materialsCreated(const QStringList &materialNames, const QString &error)

Emitted when one or more materials have been created in response to createMaterial() or createMaterials() calls. The materialNames list contains the names of the created materials.

If creation failed, error string indicates the reason.

Note: Notifier signal for property createdMaterials.

See also createMaterial() and createMaterials().

### `[signal]` void Q3DSPresentation::meshesCreated(const QStringList &meshNames, const QString &error)

Emitted when one or more meshes have been created in response to createMesh() or createMeshes() calls. The meshNames list contains the names of the created meshes.

If creation failed, error string indicates the reason.

Note: Notifier signal for property createdMeshes.

See also createMesh() and createMeshes().

### void Q3DSPresentation::preloadSlide(const QString &elementPath)

Preloads slide resources identified by elementPath to memory. All resources required by the given slide will load in the background.

elementPath is the identifier of a slide in a presentation and component.

The presentation, component and slide are separated by ":", for example My-presentation:Scene.Layer.Speedometer:Main-slide.

If elementPath does not contain any ":", then it specifies the name of a slide in the main presentation and main component. If it contains one ":", it specifies component:slide in the main presentation, and if it contains two ":", it specifies presentation:component:slide.

If you want to indicate the main slide in a sub-presentation, you will need to specify the full path. For example My-sub-presentation:Scene:Main-slide.

This function has effect only when delayed loading is enabled.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[slot]` void Q3DSPresentation::setAttribute(const QString &elementPath, const QString &attributeName, const QVariant &value)

This function is for backwards compatibility. We recommend using DataInputs to control attributes in the presentation. DataInput provides stronger contract between the design and code as it avoids use of elementPath (a reference to design's internal structure).

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 by name, 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`).

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`.

### `[slot]` void Q3DSPresentation::setDataInputValue(const QString &name, const QVariant &value, bool force = false)

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 internal 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.

Use force parameter to always create a change event. (The default behavior for datainput is to only forward the change event to runtime engine if the set value differs from the previously committed value.) Note that property changes from animations take precedence over datainput control regardless of force parameter.

See also DataInput.

### `[slot]` void Q3DSPresentation::setGlobalAnimationTime(qint64 milliseconds)

Set global animation time to manual value specified by milliseconds (if non-zero) or resume normal timer (if zero).

### `[slot]` void Q3DSPresentation::setPresentationActive(const QString &id, bool active)

Activate or deactivate the presentation identified by id depending on the value of active.

### void Q3DSPresentation::setShaderCacheData(const QByteArray &shaderCache)

Specifies the shaderCache data to be used for initial shader initialization. This method must be called before the presentation is shown. Using cached shaders improves presentation initialization speed.

If this method is not called and shaderCacheFile property is not set, all shaders are generated normally.

If this method is called, new shader cache generation is not supported.

This function was introduced in Qt 3D Studio 2.6.

See also exportShaderCache() and shaderCacheFile.

### `[signal]` void Q3DSPresentation::shaderCacheExported(bool success)

Emitted when a shader cache export is completed. The parameter success indicates whether or not the export was successful.

This function was introduced in Qt 3D Studio 2.5.

See also exportShaderCache() and shaderCacheFile.

### `[signal]` void Q3DSPresentation::shaderCacheLoadErrors(const QString &errors)

Emitted when a shader cache loading fails. The parameter errors contains the error message(s).

This function was introduced in Qt 3D Studio 2.7.

### `[signal]` void Q3DSPresentation::slideEntered(const QString &elementPath, unsigned int index, const QString &name)

Emitted when a slide in a presentation or component is entered. elementPath specifies the slide path. index and name contain the index and the name of the entered slide. Slide indexing starts from one.

This signal is emitted for each component, meaning that it can be emitted multiple times on one slide change.

### `[signal]` void Q3DSPresentation::slideExited(const QString &elementPath, unsigned int index, const QString &name)

Emitted when a slide in a presentation or component is exited. elementPath specifies the slide path. index and name contain the index and the name of the exited slide. Slide indexing starts from one.

This signal is emitted for each component, meaning that it can be emitted multiple times on one slide change.

### uint Q3DSPresentation::textureId(const QString &elementPath)

Returns the OpenGL texture id associated with a layer or an image specified by elementPath.

For example, `Scene.Layer` returns the texture id of a layer while `Scene.Layer.Rectangle.Material.diffusemap` returns the texture id of an image or a subpresentation.

This function was introduced in Qt 3D Studio 2.5.

### uint Q3DSPresentation::textureId(const QString &elementPath, QSize &size, GLenum &format)

Returns the OpenGL texture id associated with a layer or an image specified by elementPath. Texture size and format are returned in corresponding parameters.

For example, `Scene.Layer` returns the texture id of a layer while `Scene.Layer.Rectangle.Material.diffusemap` returns the texture id of an image or a subpresentation.

This function was introduced in Qt 3D Studio 2.7.

### void Q3DSPresentation::unloadSlide(const QString &elementPath)

Unloads slide resources identified by elementPath from memory. If the slide is current, the resources are unloaded when the slide is changed.

elementPath is the identifier of a slide in a presentation and component.

The presentation, component and slide are separated by ":", for example My-presentation:speedometer:main-slide.

If elementPath does not contain any ":", then it specifies the name of a slide in the main presentation and main component. If it contains one ":", it specifies component:slide in the main presentation, and if it contains two ":", it specifies presentation:Scene.Layer.Speedometer:Main-slide.

If you want to indicate the main slide in a sub-presentation, you will need to specify the full path. For example My-sub-presentation:Scene:Main-slide.

This function has effect only when delayed loading is enabled.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.