QShaderImage Class

class Qt3DRender::QShaderImage

Provides Image access to shader programs. More...

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

List of all members, including inherited members

Public Types

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

Properties

access : Access
format : ImageFormat
layer : int

layered : bool
mipLevel : int

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)

© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.