1// Copyright (C) 2022 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only
3
4#include "qquick3dcubemaptexture_p.h"
5#include "qquick3dobject_p.h"
6
7QT_BEGIN_NAMESPACE
8
9/*!
10 \qmltype CubeMapTexture
11 \inherits Texture
12 \inqmlmodule QtQuick3D
13 \brief Defines a cube map texture for use in 3D scenes.
14
15 CubeMapTexture is a Texture that represents a cube map texture. A cube map
16 texture has 6 faces (X+, X-, Y+, Y-, Z+, Z-), where each face is an
17 individual 2D image. CubeMapTexture allows \l{CustomMaterial}{custom
18 materials} and \l{Effect}{post-processing effects} to work with cube map
19 textures in their shaders. A cube map can also be used to define the scene
20 environment's \l{SceneEnvironment::skyBoxCubeMap}{skybox}.
21
22 \qml
23 CustomMaterial {
24 property TextureInput customTexture: TextureInput {
25 texture: CubeMapTexture {
26 source: "cubemap.ktx"
27 }
28 }
29 fragmentShader: "shader.frag"
30 }
31 \endqml
32
33 Here shader.frag can be implemented assuming \c customTexture is sampler
34 uniform with the GLSL type a \c samplerCube. This means that the
35 \c{texture()} GLSL function takes a \c vec3 as the texture coordinate for
36 that sampler. If we used \l Texture, the type would have been \c sampler2D.
37
38 \badcode
39 void MAIN()
40 {
41 vec4 c = texture(customTexture, NORMAL);
42 BASE_COLOR = vec4(c.rgb, 1.0);
43 }
44 \endcode
45
46 Sourcing a Texture from a container with a cubemap only loads face 0 (X+)
47 and results in a 2D texture. Whereas sourcing a CubeMapTexture from the
48 same asset loads all 6 faces and results in a cubemap texture.
49
50 CubeMapTexture inherits all its properties from Texture. The important
51 difference is that \l {Texture::}{source} must refer to a image file
52 containing a cubemap, or to a list of image files. In practice a single
53 file means a \l{https://www.khronos.org/ktx/}{KTX} container containing 6
54 face images.
55
56 Sourcing a CubeMapTexture from 6 individual images can be done in two
57 different ways. Either as a semicolon-separated list of file names in
58 X+, X-, Y+, Y-, Z+, Z- order:
59 \qml
60 CubeMapTexture {
61 source: "maps/right.jpg;maps/left.jpg;maps/top.jpg;maps/bottom.jpg;maps/front.jpg;maps/back.jpg"
62 }
63 \endqml
64 or as a string containing a "%p" placeholder, where "%p" will be replaced by the strings
65 "posx", "negx", "posy", "negy", "posz", and "negz" to generate the six filenames:
66 \qml
67 CubeMapTexture {
68 source: "maps/sky_%p.png"
69 // equivalent to:
70 // 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"
71 }
72 \endqml
73
74 \note Sourcing image data via other means, such as \l {Texture::}{sourceItem}
75 or \l {Texture::}{textureData} is not supported for CubeMapTexture at the
76 moment.
77
78 \sa Texture, CustomMaterial, Effect
79*/
80
81QQuick3DCubeMapTexture::QQuick3DCubeMapTexture(QQuick3DObject *parent)
82 : QQuick3DTexture(*(new QQuick3DObjectPrivate(QQuick3DObjectPrivate::Type::ImageCube)), parent)
83{
84}
85
86QQuick3DCubeMapTexture::~QQuick3DCubeMapTexture()
87{
88}
89
90QT_END_NAMESPACE
91

source code of qtquick3d/src/quick3d/qquick3dcubemaptexture.cpp