CubeMapTexture QML Type

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

Import Statement: import QtQuick3D


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.

© 2024 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.