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

CubeMapTexture

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

• 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"
}

See also Texture, CustomMaterial, and Effect.