- Qt 6.8
- Qt Quick 3D
- C++ Classes
- QQuick3DTextureData
- Qt Quick 3D | Commercial or GPLv3

# QQuick3DTextureData Class

Base class for defining custom texture data. More...

Header: | #include <QQuick3DTextureData>
Since: | Qt 6.0
Instantiated By: | TextureData
Inherits: | QQuick3DObject

- List of all members, including inherited members

## Public Types

enum | Format { None, RGBA8, RGBA16F, RGBA32F, RGBE8, …, ASTC_12x12 }

## Public Functions

int | depth() const
QQuick3DTextureData::Format | format() const
bool | hasTransparency() const
void | setDepth(int depth)
void | setFormat(QQuick3DTextureData::Format format)
void | setHasTransparency(bool hasTransparency)
void | setSize(const QSize &size)
void | setTextureData(const QByteArray &data)
QSize | size() const
const QByteArray | textureData() const

## Detailed Description

The QQuick3DTextureData class can be used to specify custom texture data for a Texture in a Qt Quick 3D scene.

While not strictly required, the typical usage is to inherit from this class. The subclass is then exposed to QML by registering it to the type system. The textureData property of a Texture can then be set to reference an instance of the registered type.

Example implementation:

     class CustomTextureData : public QQuick3DTextureData
     {
         Q_OBJECT
         ... properties ...

     public:
         CustomTextureData() { regenerateTextureData(); }

         void setProperty(...)
         {
             // Change relevant internal data.
             // ...

             // Update the texture data
             regenerateTextureData();

             // Finally, trigger an update. This is relevant in case nothing else
             // is changed in the scene; this way we make sure a new frame will
             // be rendered
             update();
         }
     private:
         void regenerateTextureData()
         {
             QByteArray textureData;
             textureData = generateTextureData();
             setTextureData(textureData);
             setSize(QSize(256, 256));
             setFormat(QQuick3DTextureData::Format::RGBA8)
             setHasTransparency(true);
         }
     };

This class can then be registered as a QML type and used with Texture.

In Qt 5 type registration happened with qmlRegisterType:

     qmlRegisterType<MyCustomTextureData>("Example", 1, 0, "MyCustomTextureData");

In Qt 6 the default approach is to use automatic registration with the help of the build system. Instead of calling qmlRegisterType, the `.pro` file can now contain:

     CONFIG += qmltypes
     QML_IMPORT_NAME = Example
     QML_IMPORT_MAJOR_VERSION = 1

With CMake, automatic registration is the default behavior, so no special settings are needed beyond basic QML module setup:

     qt_add_qml_module(application
         URI Example
         VERSION 1.0
     )

The class implementation should add QML_NAMED_ELEMENT:

     class CustomTextureData : public QQuick3DTextureData
     {
         Q_OBJECT
         QML_NAMED_ELEMENT(MyCustomTextureData)
         ...
     };

The QML code can then use the custom type:

     import Example 1.0

     Model {
         source: "#Cube"
         materials: [
             DefaultMaterial {
                 diffuseMap: diffuseMapCustomTexture
             }
         ]
         Texture {
             id: diffuseMapCustomTexture
             textureData: MyCustomTextureData { }
         }
     }

## Member Type Documentation

### enum QQuick3DTextureData::Format

Returns the color format of the texture data assigned in textureData property.

Constant | Value | Description
--- | --- | ---
`QQuick3DTextureData::None` | `0` | The color format is not defined
`QQuick3DTextureData::RGBA8` | `1` | The color format is considered as 8-bit integer in R, G, B and alpha channels.
`QQuick3DTextureData::RGBA16F` | `2` | The color format is considered as 16-bit float in R,G,B and alpha channels.
`QQuick3DTextureData::RGBA32F` | `3` | The color format is considered as 32-bit float in R, G, B and alpha channels.
`QQuick3DTextureData::RGBE8` | `4` | The color format is considered as 8-bit mantissa in the R, G, and B channels and 8-bit shared exponent.
`QQuick3DTextureData::R8` | `5` | The color format is considered as 8-bit integer in R channel.
`QQuick3DTextureData::R16` | `6` | The color format is considered as 16-bit integer in R channel.
`QQuick3DTextureData::R16F` | `7` | The color format is considered as 16-bit float in R channel.
`QQuick3DTextureData::R32F` | `8` | The color format is considered as 32-bit float R channel.
`QQuick3DTextureData::BC1` | `9` | The color format is considred as BC1 compressed format with R, G, B, and alpha channels.
`QQuick3DTextureData::BC2` | `10` | The color format is considred as BC2 compressed format with R, G, B, and alpha channels.
`QQuick3DTextureData::BC3` | `11` | The color format is considred as BC3 compressed format with R, G, B, and alpha channels.
`QQuick3DTextureData::BC4` | `12` | The color format is considred as BC4 compressed format with one color channel.
`QQuick3DTextureData::BC5` | `13` | The color format is considred as BC5 compressed format with two color channels.
`QQuick3DTextureData::BC6H` | `14` | The color format is considred as BC6H compressed format with three high dynamic range color channels.
`QQuick3DTextureData::BC7` | `15` | The color format is considred as BC7 compressed format with R, G, B, and alpha channels.
`QQuick3DTextureData::DXT1_RGBA` | `16` | The color format is considered as DXT1 compressed format with R, G, B and alpha channels.
`QQuick3DTextureData::DXT1_RGB` | `17` | The color format is considered as DXT1 compressed format with R, G and B channels.
`QQuick3DTextureData::DXT3_RGBA` | `18` | The color format is considered as DXT3 compressed format with R, G, B and alpha channels.
`QQuick3DTextureData::DXT5_RGBA` | `19` | The color format is considered as DXT5 compressed format with R, G, B and alpha channels.
`QQuick3DTextureData::ETC2_RGB8` | `20` | The color format is considered as ETC2 compressed format for RGB888 data
`QQuick3DTextureData::ETC2_RGB8A1` | `21` | The color format is considered as ETC2 compressed format for RGBA data where alpha is 1-bit.
`QQuick3DTextureData::ETC2_RGBA8` | `22` | The color format is considered as ETC2 compressed format with RGBA8888 data.
`QQuick3DTextureData::ASTC_4x4` | `23` | The color format is considered as ASTC compressed format with 4x4 block footprint.
`QQuick3DTextureData::ASTC_5x4` | `24` | The color format is considered as ASTC compressed format with 5x4 block footprint.
`QQuick3DTextureData::ASTC_5x5` | `25` | The color format is considered as ASTC compressed format with 5x5 block footprint.
`QQuick3DTextureData::ASTC_6x5` | `26` | The color format is considered as ASTC compressed format with 6x5 block footprint.
`QQuick3DTextureData::ASTC_6x6` | `27` | The color format is considered as ASTC compressed format with 6x6 block footprint.
`QQuick3DTextureData::ASTC_8x5` | `28` | The color format is considered as ASTC compressed format with 8x5 block footprint.
`QQuick3DTextureData::ASTC_8x6` | `29` | The color format is considered as ASTC compressed format with 8x6 block footprint.
`QQuick3DTextureData::ASTC_8x8` | `30` | The color format is considered as ASTC compressed format with 8x8 block footprint.
`QQuick3DTextureData::ASTC_10x5` | `31` | The color format is considered as ASTC compressed format with 10x5 block footprint.
`QQuick3DTextureData::ASTC_10x6` | `32` | The color format is considered as ASTC compressed format with 10x6 block footprint.
`QQuick3DTextureData::ASTC_10x8` | `33` | The color format is considered as ASTC compressed format with 10x8 block footprint.
`QQuick3DTextureData::ASTC_10x10` | `34` | The color format is considered as ASTC compressed format with 10x10 block footprint.
`QQuick3DTextureData::ASTC_12x10` | `35` | The color format is considered as ASTC compressed format with 12x10 block footprint.
`QQuick3DTextureData::ASTC_12x12` | `36` | The color format is considered as ASTC compressed format with 12x12 block footprint.

Note: With the exception of `RGBA8`, not every format is supported at runtime as this depends on which backend is being used as well which hardware is being used.

Note: `RGBE` is internally represented as an `RGBA8` but is intepreted as described when used as a lightProbe or skybox texture.

Note: Using the value `None` will assume the default value of `RGBA8`

## Member Function Documentation

### int QQuick3DTextureData::depth() const

Returns the depth of the texture data in pixels.

See also setDepth().

### QQuick3DTextureData::Format QQuick3DTextureData::format() const

Returns the format of the texture data.

See also setFormat().

### bool QQuick3DTextureData::hasTransparency() const

Returns `true` if the texture data has transparency.

The default value is `false`.

See also setHasTransparency().

### void QQuick3DTextureData::setDepth(int depth)

Sets the depth of the texture data in pixels. Setting the depth above 0 means that the texture is handled as a 3D texture.

See also depth().

### void QQuick3DTextureData::setFormat(QQuick3DTextureData::Format format)

Sets the format of the texture data.

The default format is /c RGBA8

See also format().

### void QQuick3DTextureData::setHasTransparency(bool hasTransparency)

Set hasTransparency to true if the texture data has an active alpha channel with non-opaque values.

This is used as an optimization by the engine so that for formats that do support an alpha channel do not need to have each value checked for non-opaque values.

See also hasTransparency().

### void QQuick3DTextureData::setSize(const QSize &size)

Sets the size of the texture data in pixels.

See also size().

### void QQuick3DTextureData::setTextureData(const QByteArray &data)

Sets the texture data. The contents of data must respect the size and format properties as the backend will try and upload and use the data as if it were a texture of size and format, and if there is any deviation the result will be somewhere between incorrect rendering of the texture, or potentially a crash.

See also textureData().

### QSize QQuick3DTextureData::size() const

Returns the size of the texture data in pixels.

See also setSize().

### const QByteArray QQuick3DTextureData::textureData() const

Returns the current texture data defined by this item.

See also setTextureData().