- Qt 6.4
- Qt 3D
- QML Types
- Qt3D.Render
- ShaderImage
- Qt 6.4.3 Reference Documentation

# ShaderImage QML Type

Provides Image access to shader programs. More...

Import Statement: | import Qt3D.Render 2.4
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.

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.

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.