Presentation QML Type | OpenGL Runtime 2.7.0

OpenGL Runtime | OpenGL Runtime | QML Types | Presentation QML Type

Qt 3D Studio OpenGL Runtime 2.7 Manual

# Presentation QML Type

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

Import Statement: | import QtStudio3D.OpenGL 2.7

- List of all members, including inherited members

## Properties

- createdElements : list<string>
- createdMaterials : list<string>
- createdMeshes : list<string>
- delayedLoading : bool
- shaderCacheFile : url
- source : string
- variantList : list<string>

## Signals

- customSignalEmitted(string elementPath, string name)
- elementsCreated(list<string> elementPaths, string error)
- materialsCreated(list<string> materialNames, string error)
- meshesCreated(list<string> meshNames, string error)
- shaderCacheExported(bool success)
- shaderCacheLoadErrors(string errors)
- slideEntered(string elementPath, int index, string name)
- slideExited(string elementPath, int index, string name)

## Methods

- exportShaderCache(url shaderCacheFile, bool binaryShaders)
- exportShaderCache(bool binaryShaders)
- exportShaderCache(url shaderCacheFile, bool binaryShaders, int compressionLevel)
- exportShaderCache(bool binaryShaders, int compressionLevel)
- var getDataInputs()
- var getDataInputs(string metadataKey)
- var getDataOutputs()
- preloadSlide(string elementPath)
- unloadSlide(string elementPath)

## Detailed Description

This item 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` 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. DataOutputs provide a way to get notified when an attribute is changed in the presentation by animation timeline, by behavior scripts or by a DataInput.

The Presentation type handles child objects of the types Element, SceneElement, DataInput, DataOutput, and SubPresentationSettings specially. These will get automatically associated with the presentation and can control certain aspects of it from that point on.

From the API point of view Presentation 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.

## Property Documentation

[read-only] createdElements : list<string>

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

This property is read-only.

Note: Elements can only be dynamically created via C++ API.

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

[read-only] createdMaterials : list<string>

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

This property is read-only.

Note: Materials can only be dynamically created via C++ API.

[read-only] createdMeshes : list<string>

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

This property is read-only.

Note: Meshes can only be dynamically created via C++ API.

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

shaderCacheFile : url

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, 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 QtStudio3D.OpenGL 2.5.

See also exportShaderCache().

source : string

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` property will modify which variant groups and tags are loaded from the presentations. See Q3DSPresentation::variantList property.

variantList : list<string>

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.

## Signal Documentation

customSignalEmitted(string elementPath, string 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")`.

elementsCreated(list<string> elementPaths, string 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: Elements can only be dynamically created via C++ API.

materialsCreated(list<string> materialNames, string 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 the material is created into a subpresentation, the name is prefixed with subpresentation ID followed by a colon.

If creation failed, error string indicates the reason.

Note: Materials can only be dynamically created via C++ API.

meshesCreated(list<string> meshNames, string 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: Meshes can only be dynamically created via C++ API.

shaderCacheExported(bool success)

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

This signal was introduced in QtStudio3D.OpenGL 2.5.

See also exportShaderCache() and shaderCacheFile.

shaderCacheLoadErrors(string errors)

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

This signal was introduced in QtStudio3D.OpenGL 2.7.

slideEntered(string elementPath, int index, string 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.

slideExited(string elementPath, int index, string 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.

## Method Documentation

exportShaderCache(url 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.

Exporting shader cache is an asynchronous operation. 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 method was introduced in QtStudio3D.OpenGL 2.5.

See also shaderCacheFile, shaderCacheExported, and qCompress.

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.

Exporting shader cache is an asynchronous operation. 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 method was introduced in QtStudio3D.OpenGL 2.5.

See also shaderCacheFile, shaderCacheExported, and qCompress.

exportShaderCache(url 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.

Exporting shader cache is an asynchronous operation. 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 method was introduced in QtStudio3D.OpenGL 2.7.

See also shaderCacheFile, shaderCacheExported, and qCompress.

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.

Exporting shader cache is an asynchronous operation. 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 method was introduced in QtStudio3D.OpenGL 2.7.

See also shaderCacheFile, shaderCacheExported, and qCompress.

var getDataInputs()

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

var getDataInputs(string metadataKey)

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

See also DataInput.

var getDataOutputs()

Returns a list of dataoutputs defined for this presentation. 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.

preloadSlide(string 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.

unloadSlide(string 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: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.