CubeMapTexture QML Type | Qt Quick 3D 6.4.3

- Qt 6.4
- Qt Quick 3D
- QML Types
- CubeMapTexture
- Qt Quick 3D | Commercial or GPLv3

# CubeMapTexture QML Type

Defines a cube map texture for use in 3D scenes. More...

Import Statement: | import QtQuick3D
Inherits: | Texture

- List of all members, including inherited members

## Detailed Description

CubeMapTexture is a Texture that represents a cube map texture. A cube map texture has 6 faces (X+, X-, Y+, Y-, Z+, Z-), where each face is an individual 2D image. CubeMapTexture allows custom materials and post-processing effects to work with cube map textures in their shaders. A cube map can also be used to define the scene environment's skybox.

     CustomMaterial {
         property TextureInput customTexture: TextureInput {
             texture: CubeMapTexture {
                 source: "cubemap.ktx"
             }
         }
         fragmentShader: "shader.frag"
     }

Here shader.frag can be implemented assuming `customTexture` is sampler uniform with the GLSL type a `samplerCube`. This means that the `texture()` GLSL function takes a `vec3` as the texture coordinate for that sampler. If we used Texture, the type would have been `sampler2D`.

     void MAIN()
     {
         vec4 c = texture(customTexture, NORMAL);
         BASE_COLOR = vec4(c.rgb, 1.0);
     }

Sourcing a Texture from a container with a cubemap only loads face 0 (X+) and results in a 2D texture. Whereas sourcing a CubeMapTexture from the same asset loads all 6 faces and results in a cubemap texture.

CubeMapTexture inherits all its properties from Texture. The important difference is that source must refer to a image file containing a cubemap, or to a list of image files. In practice a single file means a KTX container containing 6 face images.

Sourcing a CubeMapTexture from 6 individual images can be done in two different ways. Either as a semicolon-separated list of file names in X+, X-, Y+, Y-, Z+, Z- order:

     CubeMapTexture {
         source: "maps/right.jpg;maps/left.jpg;maps/top.jpg;maps/bottom.jpg;maps/front.jpg;maps/back.jpg"
     }

or as a string containing a "%p" placeholder, where "%p" will be replaced by the strings "posx", "negx", "posy", "negy", "posz", and "negz" to generate the six filenames:

     CubeMapTexture {
         source: "maps/sky_%p.png"
         // equivalent to:
         // source: "maps/sky_posx.png;maps/sky_negx.png;maps/sky_posy.png;maps/sky_negy.png;maps/sky_posz.png;maps/sky_negz.png"
     }

Note: Sourcing image data via other means, such as sourceItem or textureData is not supported for CubeMapTexture at the moment.

See also Texture, CustomMaterial, and Effect.