ShaderImage QML Type

Provides Image access to shader programs. More...

Import Statement:	import Qt3D.Render
Since:	Qt 5.14
Instantiates:	QShaderImage

• List of all members, including inherited members

Properties

• access : enumeration
• format : enumeration
• layer : int
• layered : bool
• mipLevel : int

Detailed Description

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

ShaderImage has to be assigned as a Parameter's value and reference a valid Qt3D.Render.AbstractTexture 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 ShaderImage 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	Texture1D
image2D	GL_IMAGE_2D	Texture2D
image3D	GL_IMAGE_3D	Texture3D
image2DRect	GL_IMAGE_2D_RECT	TextureRectangle
imageCube	GL_IMAGE_CUBE	TextureCubeMap
imageBuffer	GL_IMAGE_BUFFER	TextureBuffer
image1DArray	GL_IMAGE_1D_ARRAY	Texture1DArray
image2DArray	GL_IMAGE_2D_ARRAY	Texture2DArray
imageCubeArray	GL_IMAGE_CUBE_MAP_ARRAY	TextureCubeMapArray
image2DMS	GL_IMAGE_2D_MULTISAMPLE	Texture2DMultisample
image2DMSArray	GL_IMAGE_2D_MULTISAMPLE_ARRAY	Texture2DMultisampleArray
iimage1D	GL_INT_IMAGE_1D	Texture1D
iimage2D	GL_INT_IMAGE_2D	Texture2D
iimage3D	GL_INT_IMAGE_3D	Texture3D
iimage2DRect	GL_INT_IMAGE_2D_RECT	TextureRectangle
iimageCube	GL_INT_IMAGE_CUBE	TextureCubeMap
iimageBuffer	GL_INT_IMAGE_BUFFER	TextureBuffer
iimage1DArray	GL_INT_IMAGE_1D_ARRAY	Texture1DArray
iimage2DArray	GL_INT_IMAGE_2D_ARRAY	Texture2DArray
iimageCubeArray	GL_INT_IMAGE_CUBE_MAP_ARRAY	TextureCubeMapArray
iimage2DMS	GL_INT_IMAGE_2D_MULTISAMPLE	Texture2DMultisample
iimage2DMSArray	GL_INT_IMAGE_2D_MULTISAMPLE_ARRAY	Texture2DMultisampleArray
uimage1D	GL_UNSIGNED_INT_IMAGE_1D	Texture1D
uimage2D	GL_UNSIGNED_INT_IMAGE_2D	Texture2D
uimage3D	GL_UNSIGNED_INT_IMAGE_3D	Texture3D
uimage2DRect	GL_UNSIGNED_INT_IMAGE_2D_RECT	TextureRectangle
uimageCube	GL_UNSIGNED_INT_IMAGE_CUBE	TextureCubeMap
uimageBuffer	GL_UNSIGNED_INT_IMAGE_BUFFER	TextureBuffer
uimage1DArray	GL_UNSIGNED_INT_IMAGE_1D_ARRAY	Texture1DArray
uimage2DArray	GL_UNSIGNED_INT_IMAGE_2D_ARRAY	Texture2DArray
uimageCubeArray	GL_UNSIGNED_INT_IMAGE_CUBE_MAP_ARRAY	TextureCubeMapArray
uimage2DMS	GL_UNSIGNED_INT_IMAGE_2D_MULTISAMPLE	Texture2DMultisample
uimage2DMSArray	GL_UNSIGNED_INT_IMAGE_2D_MULTISAMPLE_ARRAY	Texture2DMultisampleArray

OpenGL ES 3.1 supports the following image types:

GLSL Type	OpenGL Type Enum	Texture Type
image2D	GL_IMAGE_2D	Texture2D
image3D	GL_IMAGE_3D	Texture3D
imageCube	GL_IMAGE_CUBE	TextureCubeMap
image2DArray	GL_IMAGE_2D_ARRAY	Texture2DArray
iimage2D	GL_INT_IMAGE_2D	Texture2D
iimage3D	GL_INT_IMAGE_3D	Texture3D
iimageCube	GL_INT_IMAGE_CUBE	TextureCubeMap
iimage2DArray	GL_INT_IMAGE_2D_ARRAY	Texture2DArray
uimage2D	GL_UNSIGNED_INT_IMAGE_2D	Texture2D
uimage3D	GL_UNSIGNED_INT_IMAGE_3D	Texture3D
uimageCube	GL_UNSIGNED_INT_IMAGE_CUBE	TextureCubeMap
uimage2DArray	GL_UNSIGNED_INT_IMAGE_2D_ARRAY	Texture2DArray

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	TextureBuffer
imageCubeArray	GL_IMAGE_CUBE_MAP_ARRAY	TextureCubeMapArray
iimageBuffer	GL_IMAGE_BUFFER	TextureBuffer
iimageCubeArray	GL_INT_IMAGE_CUBE_MAP_ARRAY	TextureCubeMapArray
uimageBuffer	GL_UNSIGNED_INT_IMAGE_BUFFER	TextureBuffer
uimageCubeArray	GL_UNSIGNED_INT_IMAGE_CUBE_MAP_ARRAY	TextureCubeMapArray

Expected use would look like:

import Qt3D.Render 2.14

Entity {
...
    Texture2D {
        id: tex2D
        ...
    }

    Material {
        parameters: Parameter {
            name: "imageUniformName"
            value: ShaderImage {
                texture: tex2D
            }
        }
        ...
    }
 ...
}

Property Documentation

access : enumeration

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.

Constant	Description
ShaderImage.ReadOnly	Read-only access.
ShaderImage.WriteOnly	Write-only access.
ShaderImage.ReadWrite	Read-write access.

The default value is ShaderImage.ReadWrite.

format : enumeration

Specifies the image format, which is essentially important when storing values in the ShaderImage 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 ShaderImage.Automatic.

layer : int

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

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

The default value is 0.

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.

mipLevel : int

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

The default value is 0.