Canvas3DTextureProvider

Provides means to get QQuickItem as Canvas3DTexture. More...

Import Statement:	import QtCanvas3D 1.1
Since:	QtCanvas3D 1.1

List of all members, including inherited members

Signals

void textureReady(Item *source)

Methods

QJSValue createTextureFromSource(Item *source)

Detailed Description

An uncreatable QML type that provides an extension API that can be used to get QQuickItem as Canvas3DTexture. Only QQuickItems that implement QQuickItem::textureProvider() method can be used as a texture source, which in most cases means the layer.enabled property of the item must be set to true.

Typical usage would be something like this:

// In QML code, declare a layered item you wish to show as texture
Rectangle {
    id: textureSource
    layer.enabled: true
    // ...
}
.
.
// In JavaScript code, declare the variables for the extension and the texture
var textureProvider;
var myTexture;
.
.
// Get the extension after the context has been created in onInitializeGL().
textureProvider = gl.getExtension("QTCANVAS3D_texture_provider");
.
.
// Get the Canvas3DTexture object representing our source item
if (textureProvider)
    myTexture = textureProvider.createTextureFromSource(textureSource);
.
.
// If you just need to access the texture in onPaingGL(), the above is usually enough.
// However, in cases where you utilize synchronous OpenGL commands or dynamically enable
// the source item layer after canvas initialization, it is not guaranteed that the texture
// is valid immediately after calling createTextureFromSource().
// To ensure you don't use the texture before it is ready, connect the textureReady() signal
// to a handler function that will use the texture.
textureProvider.textureReady.connect(function(sourceItem) {
    if (sourceItem === textureSource) {
        gl.bindTexture(gl.TEXTURE_2D, myTexture);
        // ...
    }
});

See also Context3D.

Signal Documentation

void textureReady(Item *source)

Indicates that the texture created with createTextureFromSource() method for the source item is ready to be used.

Method Documentation

QJSValue createTextureFromSource(Item *source)

Creates and returns a Canvas3DTexture object for the supplied source item.

The source item must be of a type that implements a texture provider, which in most cases means the layer.enabled property of the item must be set to true. ShaderEffectSource items can also be used as texture sources. The texture provider of the source item owns the OpenGL texture. If the source item is deleted or the layer.enabled property is set to false while the texture is still in use in Canvas3D, the rendered texture contents become undefined.

Trying to bind the returned Canvas3DTexture object is not guaranteed to work until a textureReady() signal corresponding to the source item has been emitted. However, if you don't have any synchronous OpenGL calls between the first use of the texture and the end of your paingGL() handler, and if you can guarantee that the source item has been fully rendered at least once after its layer was enabled, you can immediately use the returned texture without waiting for the textureReady() signal.

Disabling the source item's layer will destroy the underlying texture provider, so it is necessary to call this method again for the source item if you re-enable its layer.

If this function is called twice for same source, it doesn't create a new Canvas3DTexture instance, but instead returns a reference to a previously created one, as long as the previous instance is still alive.

The generated texture is owned and managed by Qt Quick's scene graph, so attempting to modify its parameters is not guaranteed to work.

Note: Qt Quick uses texture coordinates where the origin is at top left corner, which is different from OpenGL default coordinate system, where the origin is at bottom left corner. You need to account for this when specifying the UV mapping for the texture. Alternatively, you can specify a suitable textureMirroring value for your layer or ShaderEffectSource item.

Contents