QShaderImage Class

class Qt3DRender::QShaderImage

Provides Image access to shader programs. More...

Header: #include <QShaderImage>
CMake: find_package(Qt6 COMPONENTS 3drender REQUIRED) target_link_libraries(mytarget PRIVATE Qt6::3drender)
qmake: QT += 3drender
Since: Qt 5.14
Instantiated By: ShaderImage
Inherits: Qt3DCore::QNode

Public Types

enum Access { ReadOnly, WriteOnly, ReadWrite }
enum ImageFormat { NoFormat, Automatic, R8_UNorm, RG8_UNorm, RGBA8_UNorm, …, RGB10A2U }

Properties

Public Functions

Qt3DRender::QShaderImage::Access access() const
Qt3DRender::QShaderImage::ImageFormat format() const
int layer() const
bool layered() const
int mipLevel() const
Qt3DRender::QAbstractTexture * texture() const

Public Slots

void setAccess(Qt3DRender::QShaderImage::Access access)
void setFormat(Qt3DRender::QShaderImage::ImageFormat format)
void setLayer(int layer)
void setLayered(bool layered)
void setMipLevel(int mipLevel)
void setTexture(Qt3DRender::QAbstractTexture *texture)

Signals

void accessChanged(Qt3DRender::QShaderImage::Access access)
void formatChanged(Qt3DRender::QShaderImage::ImageFormat format)
void layerChanged(int layer)
void layeredChanged(bool layered)
void mipLevelChanged(int mipLevel)
void textureChanged(Qt3DRender::QAbstractTexture *texture)

Detailed Description

To make the content of textures available for read and write operations in a shader, they need to exposed as QShaderImage. Textures can be composed of several mip levels, layers and faces. Additionally declaring a QShaderImage allows specifying which level, layer or face of the texture content we want to access.

QShaderImage has to be assigned as a QParameter's value and reference a valid Qt3DRender::QAbstractTexture to work properly.

If the referenced texture is a one-dimensional array, two-dimensional array, three-dimensional, cube map, cube map array, or two-dimensional multisample array texture, it is possible to bind either the entire texture level or a single layer or face of the texture level. This can be controlled with the layered property.

Support for QShaderImage is only supported with OpenGL 4 and partially with OpenGL ES 3.1 and 3.2.

OpenGL 4 supports the following image types:

GLSL Type OpenGL Type Enum Texture Type
image1D GL_IMAGE_1D QTexture1D
image2D GL_IMAGE_2D QTexture2D
image3D GL_IMAGE_3D QTexture3D
image2DRect GL_IMAGE_2D_RECT QTextureRectangle
imageCube GL_IMAGE_CUBE QTextureCubeMap
imageBuffer GL_IMAGE_BUFFER QTextureBuffer
image1DArray GL_IMAGE_1D_ARRAY QTexture1DArray
image2DArray GL_IMAGE_2D_ARRAY QTexture2DArray
imageCubeArray GL_IMAGE_CUBE_MAP_ARRAY QTextureCubeMapArray
image2DMS GL_IMAGE_2D_MULTISAMPLE QTexture2DMultisample
image2DMSArray GL_IMAGE_2D_MULTISAMPLE_ARRAY QTexture2DMultisampleArray
iimage1D GL_INT_IMAGE_1D QTexture1D
iimage2D GL_INT_IMAGE_2D QTexture2D
iimage3D GL_INT_IMAGE_3D QTexture3D
iimage2DRect GL_INT_IMAGE_2D_RECT QTextureRectangle
iimageCube GL_INT_IMAGE_CUBE QTextureCubeMap
iimageBuffer GL_INT_IMAGE_BUFFER QTextureBuffer
iimage1DArray GL_INT_IMAGE_1D_ARRAY QTexture1DArray
iimage2DArray GL_INT_IMAGE_2D_ARRAY QTexture2DArray
iimageCubeArray GL_INT_IMAGE_CUBE_MAP_ARRAY QTextureCubeMapArray
iimage2DMS GL_INT_IMAGE_2D_MULTISAMPLE QTexture2DMultisample
iimage2DMSArray GL_INT_IMAGE_2D_MULTISAMPLE_ARRAY QTexture2DMultisampleArray
uimage1D GL_UNSIGNED_INT_IMAGE_1D QTexture1D
uimage2D GL_UNSIGNED_INT_IMAGE_2D QTexture2D
uimage3D GL_UNSIGNED_INT_IMAGE_3D QTexture3D
uimage2DRect GL_UNSIGNED_INT_IMAGE_2D_RECT QTextureRectangle
uimageCube GL_UNSIGNED_INT_IMAGE_CUBE QTextureCubeMap
uimageBuffer GL_UNSIGNED_INT_IMAGE_BUFFER QTextureBuffer
uimage1DArray GL_UNSIGNED_INT_IMAGE_1D_ARRAY QTexture1DArray
uimage2DArray GL_UNSIGNED_INT_IMAGE_2D_ARRAY QTexture2DArray
uimageCubeArray GL_UNSIGNED_INT_IMAGE_CUBE_MAP_ARRAY QTextureCubeMapArray
uimage2DMS GL_UNSIGNED_INT_IMAGE_2D_MULTISAMPLE QTexture2DMultisample
uimage2DMSArray GL_UNSIGNED_INT_IMAGE_2D_MULTISAMPLE_ARRAY QTexture2DMultisampleArray

OpenGL ES 3.1 supports the following image types:

GLSL Type OpenGL Type Enum Texture Type
image2D GL_IMAGE_2D QTexture2D
image3D GL_IMAGE_3D QTexture3D
imageCube GL_IMAGE_CUBE QTextureCubeMap
image2DArray GL_IMAGE_2D_ARRAY QTexture2DArray
iimage2D GL_INT_IMAGE_2D QTexture2D
iimage3D GL_INT_IMAGE_3D QTexture3D
iimageCube GL_INT_IMAGE_CUBE QTextureCubeMap
iimage2DArray GL_INT_IMAGE_2D_ARRAY QTexture2DArray
uimage2D GL_UNSIGNED_INT_IMAGE_2D QTexture2D
uimage3D GL_UNSIGNED_INT_IMAGE_3D QTexture3D
uimageCube GL_UNSIGNED_INT_IMAGE_CUBE QTextureCubeMap
uimage2DArray GL_UNSIGNED_INT_IMAGE_2D_ARRAY QTexture2DArray

OpenGL ES 3.2 supports all of the OpenGL ES 3.1 image types as well as the following:

GLSL Type OpenGL Type Enum Texture Type
imageBuffer GL_IMAGE_BUFFER QTextureBuffer
imageCubeArray GL_IMAGE_CUBE_MAP_ARRAY QTextureCubeMapArray
iimageBuffer GL_IMAGE_BUFFER QTextureBuffer
iimageCubeArray GL_INT_IMAGE_CUBE_MAP_ARRAY QTextureCubeMapArray
uimageBuffer GL_UNSIGNED_INT_IMAGE_BUFFER QTextureBuffer
uimageCubeArray GL_UNSIGNED_INT_IMAGE_CUBE_MAP_ARRAY QTextureCubeMapArray

Expected use would look like:

Qt3DRender::QTexture2D *tex2D = new Qt3DRender::QTexture2D();
...
Qt3DRender::QMaterial *material = new Qt3DRender::QMaterial();
...
Qt3DRender::QParameter *imageParameter = new Qt3DRender::QParameter();
Qt3DRender::QShaderImage *shaderImage = new Qt3DRender::QShaderImage();

shaderImage->setTexture(tex2D);

imageParameter->setName("imageUniformName");
imageParameter->setValue(QVariant::fromValue(shaderImage));

material->addParameter(imageParamenter);

Member Type Documentation

enum QShaderImage::Access

Constant Value Description
Qt3DRender::QShaderImage::ReadOnly 0 Image will only be read from in shaders
Qt3DRender::QShaderImage::WriteOnly 1 Image will only be written into from shaders
Qt3DRender::QShaderImage::ReadWrite 2 Image will only be read and written into from shaders

enum QShaderImage::ImageFormat

This list describes all possible image formats

Constant Value Description
Qt3DRender::QShaderImage::NoFormat 0 GL_NONE
Qt3DRender::QShaderImage::Automatic 1 Qt 3D will try to determine the format automatically based on the referenced texture.
Qt3DRender::QShaderImage::R8_UNorm 0x8229 GL_R8 (GLSL type r8, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RG8_UNorm 0x822B GL_RG8 (GLSL type rg8, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RGBA8_UNorm 0x8058 GL_RGBA8 (GLSL type rgba8, supported by OpenGL 4.2+, OpenGL ES 3.1+)
Qt3DRender::QShaderImage::R16_UNorm 0x822A GL_R16 (GLSL type r16, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RG16_UNorm 0x822C GL_RG16 (GLSL type rg16, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RGBA16_UNorm 0x805B GL_RGBA16 (GLSL type rgba16, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::R8_SNorm 0x8F94 GL_R8_SNORM (GLSL type r8_snorm, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RG8_SNorm 0x8F95 GL_RG8_SNORM (GLSL type rg8_snorm, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RGBA8_SNorm 0x8F97 GL_RGBA8_SNORM (GLSL type rgba8_snorm, supported by OpenGL 4.2+, OpenGL ES 3.1+)
Qt3DRender::QShaderImage::R16_SNorm 0x8F98 GL_R16_SNORM (GLSL type r16_snorm, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RG16_SNorm 0x8F99 GL_RG16_SNORM (GLSL type rg16_snorm, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RGBA16_SNorm 0x8F9B GL_RGBA16_SNORM (GLSL type rgba16_snorm, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::R8U 0x8232 GL_R8UI (GLSL type r8ui, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RG8U 0x8238 GL_RG8UI (GLSL type rg8ui, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RGBA8U 0x8D7C GL_RGBA8UI (GLSL type rgba8ui, supported by OpenGL 4.2+, OpenGL ES 3.1+)
Qt3DRender::QShaderImage::R16U 0x8234 GL_R16UI (GLSL type r16ui, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RG16U 0x823A GL_RG16UI (GLSL type rg16ui, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RGBA16U 0x8D76 GL_RGBA16UI (GLSL type rgba16ui, supported by OpenGL 4.2+, OpenGL ES 3.1+)
Qt3DRender::QShaderImage::R32U 0x8236 GL_R32UI (GLSL type r32ui, supported by OpenGL 4.2+, OpenGL ES 3.1)
Qt3DRender::QShaderImage::RG32U 0x823C GL_RG32UI (GLSL type rg32ui, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RGBA32U 0x8D70 GL_RGBA32UI (GLSL type rgba32ui, supported by OpenGL 4.2+, OpenGL ES 3.1+)
Qt3DRender::QShaderImage::R8I 0x8231 GL_R8I (GLSL type r8i, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RG8I 0x8237 GL_RG8I (GLSL type rg8i, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RGBA8I 0x8D8E GL_RGBA8I (GLSL type rgba8i, supported by OpenGL 4.2+, OpenGL ES 3.1+)
Qt3DRender::QShaderImage::R16I 0x8233 GL_R16I (GLSL type r16i, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RG16I 0x8239 GL_RG16I (GLSL type rg16i, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RGBA16I 0x8D88 GL_RGBA16I (GLSL type rgba16i, supported by OpenGL 4.2+, OpenGL ES 3.1)
Qt3DRender::QShaderImage::R32I 0x8235 GL_R32I (GLSL type r32i, supported by OpenGL 4.2+, OpenGL ES 3.1+)
Qt3DRender::QShaderImage::RG32I 0x823B GL_RG32I (GLSL type rg32i, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RGBA32I 0x8D82 GL_RGBA32I (GLSL type rgba32i, supported by OpenGL 4.2+, OpenGL ES 3.1+)
Qt3DRender::QShaderImage::R16F 0x822D GL_R16F (GLSL type r16f, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RG16F 0x822F GL_RG16F (GLSL type rg16f, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RGBA16F 0x881A GL_RGBA16F (GLSL type rgba16f, supported by OpenGL 4.2+, OpenGL ES 3.1+)
Qt3DRender::QShaderImage::R32F 0x822E GL_R32F (GLSL type r32f, supported by OpenGL 4.2+, OpenGL ES 3.1+)
Qt3DRender::QShaderImage::RG32F 0x8230 GL_RG32F (GLSL type rg32f, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RGBA32F 0x8814 GL_RGBA32F (GLSL type rgba32f, supported by OpenGL 4.2+, OpenGL ES 3.1+)
Qt3DRender::QShaderImage::RG11B10F 0x8C3A GL_R11F_G11F_B10F (GLSL type r11f_g11f_b10f, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RGB10A2 0x8059 GL_RGB10_A2 (GLSL type rgb10_a2, supported by OpenGL 4.2+)
Qt3DRender::QShaderImage::RGB10A2U 0x906F GL_RGB10_A2UI (GLSL type rgb10_a2ui, supported by OpenGL 4.2+)

Property Documentation

access : Access

Specifies the type of access we want to allow from our shader instances to the image. If a shader tries to write or read from an image that has incompatible access, the behavior is undefined.

The default value is QShaderImage::ReadWrite.

Access functions:

Qt3DRender::QShaderImage::Access access() const
void setAccess(Qt3DRender::QShaderImage::Access access)

Notifier signal:

void accessChanged(Qt3DRender::QShaderImage::Access access)

format : ImageFormat

Specifies the image format, which is essentially important when storing values in the Image from a shader.

The format doesn't have to be the same as the referenced texture's format. It however has to be compatible (matching in size but not necessarily by class type). For instance a texture of format R32F (size 32bits, class 1x32) could be used with an image of format RGBA8I (size 32bits, class 4x8). Table 8.27 of the OpenGL specifications shows the size and class for all supported Image formats.

By default Qt3D will try to set the image format to match that of the referenced texture.

The default value is QShaderImage::Automatic.

Access functions:

Qt3DRender::QShaderImage::ImageFormat format() const
void setFormat(Qt3DRender::QShaderImage::ImageFormat format)

Notifier signal:

void formatChanged(Qt3DRender::QShaderImage::ImageFormat format)

layer : int

Holds which layer out of the referenced texture should be used for the QShaderImage. This property does nothing if layered is set to true or if the reference texture's type isn't compatible with layers.

Note: When the referenced texture is of type cube map or cube map array and ĺayered is set to false, the face and layer are retrieved in the following manner:

cubeMapLayer = layer / 6
cubeMapFace = layer - (cubeMapLayer * 6)

The default value is 0.

Access functions:

int layer() const
void setLayer(int layer)

Notifier signal:

void layerChanged(int layer)

layered : bool

*

If set to true, if the referenced texture is a one-dimensional array, two-dimensional array, three-dimensional, cube map, cube map array, or two-dimensional multisample array texture, the entire level will be bound for all layers. If set to false, only the single layer specified by the layer property will be bound.

The default value is false.

Access functions:

bool layered() const
void setLayered(bool layered)

Notifier signal:

void layeredChanged(bool layered)

mipLevel : int

Holds which mipLevel out of the referenced texture should be used for the QShaderImage.

The default value is 0.

Access functions:

int mipLevel() const
void setMipLevel(int mipLevel)

Notifier signal:

void mipLevelChanged(int mipLevel)

© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/qt-6.0/qt3drender-qshaderimage.html