Qt3DRender::QShaderImage Class
class Qt3DRender::QShaderImage为着色器程序提供对图像的访问。更多内容...
| 标题： | #include <qshaderimage.h> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS 3drender) target_link_libraries(mytarget PRIVATE Qt6::3drender) |
| qmake： | QT += 3drender |
| 在 QML 中： | ShaderImage |
| 继承自： | Qt3DCore::QNode |
| 状态： | 已弃用 |
该类已弃用。我们强烈建议不要在新代码中使用它。
公共类型
| enum | Access { ReadOnly, WriteOnly, ReadWrite } |
| enum | ImageFormat { NoFormat, Automatic, R8_UNorm, RG8_UNorm, RGBA8_UNorm, …, RGB10A2U } |
属性
公共函数
| Qt3DRender::QShaderImage::Access | access() const |
| Qt3DRender::QShaderImage::ImageFormat | format() const |
| int | layer() const |
| bool | layered() const |
| int | mipLevel() const |
| Qt3DRender::QAbstractTexture * | texture() const |
公共槽位
| void | setAccess(Qt3DRender::QShaderImage::Access access) |
| void | setFormat(Qt3DRender::QShaderImage::ImageFormat format) |
| void | setLayer(int layer) |
| void | setLayered(bool layered) |
| void | setMipLevel(int mipLevel) |
| void | setTexture(Qt3DRender::QAbstractTexture *texture) |
信号
| void | accessChanged(Qt3DRender::QShaderImage::Access access) |
| void | formatChanged(Qt3DRender::QShaderImage::ImageFormat format) |
| void | layerChanged(int layer) |
| void | layeredChanged(bool layered) |
| void | mipLevelChanged(int mipLevel) |
| void | textureChanged(Qt3DRender::QAbstractTexture *texture) |
详细说明
为了使着色器中能够对纹理内容进行读写操作，必须将其作为 QShaderImage 暴露出来。纹理可以由多个 Mip 级别、图层和面组成。此外，声明一个 QShaderImage 还可以指定我们要访问纹理内容的哪个级别、图层或面。
QShaderImage必须被赋值为QParameter 的值，并引用一个有效的Qt3DRender::QAbstractTexture ，才能正常工作。
如果引用的纹理是一维数组、二维数组、三维数组、立方体贴图、立方体贴图数组或二维多采样数组纹理，则可以绑定整个纹理级别，也可以绑定该纹理级别的单个图层或面。这可以通过layered 属性进行控制。
QShaderImage 仅在 OpenGL 4 中受支持，在 OpenGL ES 3.1 和 3.2 中仅部分支持。
OpenGL 4 支持以下图像类型：
| GLSL 类型 | OpenGL 类型枚举 | 纹理类型 |
|---|---|---|
| image1D | GL_IMAGE_1D | QTexture1D |
| image2D | GL_IMAGE_2D | QTexture2D |
| image3D | GL_IMAGE_3D | QTexture3D |
| image2DRect | GL_IMAGE_2D_RECT | QTextureRectangle |
| imageCube | GL_IMAGE_CUBE | QTextureCubeMap |
| imageBuffer | GL_IMAGE_BUFFER | QTextureBuffer |
| image1DArray | GL_IMAGE_1D_ARRAY | QTexture1DArray |
| image2DArray | GL_IMAGE_2D_ARRAY | QTexture2DArray |
| imageCubeArray | GL_IMAGE_CUBE_MAP_ARRAY | QTextureCubeMapArray |
| image2DMS | GL_IMAGE_2D_MULTISAMPLE | QTexture2DMultisample |
| image2DMSArray | GL_IMAGE_2D_MULTISAMPLE_ARRAY | QTexture2DMultisampleArray |
| iimage1D | GL_INT_IMAGE_1D | QTexture1D |
| iimage2D | GL_INT_IMAGE_2D | QTexture2D |
| iimage3D | GL_INT_IMAGE_3D | QTexture3D |
| iimage2DRect | GL_INT_IMAGE_2D_RECT | QTextureRectangle |
| iimageCube | GL_INT_IMAGE_CUBE | QTextureCubeMap |
| iimageBuffer | GL_INT_IMAGE_BUFFER | QTextureBuffer |
| iimage1DArray | GL_INT_IMAGE_1D_ARRAY | QTexture1DArray |
| iimage2DArray | GL_INT_IMAGE_2D_ARRAY | QTexture2DArray |
| iimageCubeArray | GL_INT_IMAGE_CUBE_MAP_ARRAY | QTextureCubeMapArray |
| iimage2DMS | GL_INT_IMAGE_2D_MULTISAMPLE | QTexture2DMultisample |
| iimage2DMSArray | GL_INT_IMAGE_2D_MULTISAMPLE_ARRAY | QTexture2DMultisampleArray |
| uimage1D | GL_UNSIGNED_INT_IMAGE_1D | QTexture1D |
| uimage2D | GL_UNSIGNED_INT_IMAGE_2D | QTexture2D |
| uimage3D | GL_UNSIGNED_INT_IMAGE_3D | QTexture3D |
| uimage2DRect | GL_UNSIGNED_INT_IMAGE_2D_RECT | QTextureRectangle |
| uimageCube | GL_UNSIGNED_INT_IMAGE_CUBE | QTextureCubeMap |
| uimageBuffer | GL_UNSIGNED_INT_IMAGE_BUFFER | QTextureBuffer |
| uimage1DArray | GL_UNSIGNED_INT_IMAGE_1D_ARRAY | QTexture1DArray |
| uimage2DArray | GL_UNSIGNED_INT_IMAGE_2D_ARRAY | QTexture2DArray |
| uimageCubeArray | GL_UNSIGNED_INT_IMAGE_CUBE_MAP_ARRAY | QTextureCubeMapArray |
| uimage2DMS | GL_UNSIGNED_INT_IMAGE_2D_MULTISAMPLE | QTexture2DMultisample |
| uimage2DMSArray | GL_UNSIGNED_INT_IMAGE_2D_MULTISAMPLE_ARRAY | QTexture2DMultisampleArray |
OpenGL ES 3.1 支持以下图像类型：
| GLSL 类型 | OpenGL 类型枚举 | 纹理类型 |
|---|---|---|
| image2D | GL_IMAGE_2D | QTexture2D |
| image3D | GL_IMAGE_3D | QTexture3D |
| imageCube | GL_IMAGE_CUBE | QTextureCubeMap |
| image2DArray | GL_IMAGE_2D_ARRAY | QTexture2DArray |
| iimage2D | GL_INT_IMAGE_2D | QTexture2D |
| iimage3D | GL_INT_IMAGE_3D | QTexture3D |
| iimageCube | GL_INT_IMAGE_CUBE | QTextureCubeMap |
| iimage2DArray | GL_INT_IMAGE_2D_ARRAY | QTexture2DArray |
| uimage2D | GL_UNSIGNED_INT_IMAGE_2D | QTexture2D |
| uimage3D | GL_UNSIGNED_INT_IMAGE_3D | QTexture3D |
| uimageCube | GL_UNSIGNED_INT_IMAGE_CUBE | QTextureCubeMap |
| uimage2DArray | GL_UNSIGNED_INT_IMAGE_2D_ARRAY | QTexture2DArray |
OpenGL ES 3.2 支持所有 OpenGL ES 3.1 图像类型，以及以下类型：
| GLSL 类型 | OpenGL 类型枚举 | 纹理类型 |
|---|---|---|
| imageBuffer | GL_IMAGE_BUFFER | QTextureBuffer |
| imageCubeArray | GL_IMAGE_CUBE_MAP_ARRAY | QTextureCubeMapArray |
| iimageBuffer | GL_IMAGE_BUFFER | QTextureBuffer |
| iimageCubeArray | GL_INT_IMAGE_CUBE_MAP_ARRAY | QTextureCubeMapArray |
| uimageBuffer | GL_UNSIGNED_INT_IMAGE_BUFFER | QTextureBuffer |
| uimageCubeArray | GL_UNSIGNED_INT_IMAGE_CUBE_MAP_ARRAY | QTextureCubeMapArray |
预期用法如下：
Qt3DRender::QTexture2D *tex2D = new Qt3DRender::QTexture2D();
...
Qt3DRender::QMaterial *material = new Qt3DRender::QMaterial();
...
Qt3DRender::QParameter *imageParameter = new Qt3DRender::QParameter();
Qt3DRender::QShaderImage *shaderImage = new Qt3DRender::QShaderImage();
shaderImage->setTexture(tex2D);
imageParameter->setName("imageUniformName");
imageParameter->setValue(QVariant::fromValue(shaderImage));
material->addParameter(imageParamenter);成员类型文档
enum QShaderImage::Access
| 常数 | 值 | 描述 |
|---|---|---|
Qt3DRender::QShaderImage::ReadOnly | 0 | 该图像仅在着色器中被读取 |
Qt3DRender::QShaderImage::WriteOnly | 1 | 仅允许从着色器向图像写入数据 |
Qt3DRender::QShaderImage::ReadWrite | 2 | 该图像仅在着色器中进行读写操作 |
enum QShaderImage::ImageFormat
此列表列出了所有可能的图像格式
| 常量 | 值 | 描述 |
|---|---|---|
Qt3DRender::QShaderImage::NoFormat | 0 | GL_NONE |
Qt3DRender::QShaderImage::Automatic | 1 | Qt 3D 将尝试根据引用的纹理自动确定格式。 |
Qt3DRender::QShaderImage::R8_UNorm | 0x8229 | GL_R8（GLSL 类型 r8，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RG8_UNorm | 0x822B | GL_RG8（GLSL 类型 rg8，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RGBA8_UNorm | 0x8058 | GL_RGBA8（GLSL 类型 rgba8，受 OpenGL 4.2 及以上版本、OpenGL ES 3.1 及以上版本支持） |
Qt3DRender::QShaderImage::R16_UNorm | 0x822A | GL_R16（GLSL 类型 r16，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RG16_UNorm | 0x822C | GL_RG16（GLSL 类型 rg16，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RGBA16_UNorm | 0x805B | GL_RGBA16（GLSL 类型 rgba16，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::R8_SNorm | 0x8F94 | GL_R8_SNORM（GLSL 类型 r8_snorm，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RG8_SNorm | 0x8F95 | GL_RG8_SNORM（GLSL 类型 rg8_snorm，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RGBA8_SNorm | 0x8F97 | GL_RGBA8_SNORM（GLSL 类型 rgba8_snorm，受 OpenGL 4.2 及以上版本、OpenGL ES 3.1 及以上版本支持） |
Qt3DRender::QShaderImage::R16_SNorm | 0x8F98 | GL_R16_SNORM（GLSL 类型 r16_snorm，OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RG16_SNorm | 0x8F99 | GL_RG16_SNORM（GLSL 类型 rg16_snorm，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RGBA16_SNorm | 0x8F9B | GL_RGBA16_SNORM（GLSL 类型 rgba16_snorm，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::R8U | 0x8232 | GL_R8UI（GLSL 类型 r8ui，由 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RG8U | 0x8238 | GL_RG8UI（GLSL 类型 rg8ui，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RGBA8U | 0x8D7C | GL_RGBA8UI（GLSL 类型 rgba8ui，受 OpenGL 4.2+、OpenGL ES 3.1+ 支持） |
Qt3DRender::QShaderImage::R16U | 0x8234 | GL_R16UI（GLSL 类型 r16ui，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RG16U | 0x823A | GL_RG16UI（GLSL 类型 rg16ui，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RGBA16U | 0x8D76 | GL_RGBA16UI（GLSL 类型 rgba16ui，受 OpenGL 4.2 及以上版本、OpenGL ES 3.1 及以上版本支持） |
Qt3DRender::QShaderImage::R32U | 0x8236 | GL_R32UI（GLSL 类型 r32ui，受 OpenGL 4.2 及以上版本、OpenGL ES 3.1 支持） |
Qt3DRender::QShaderImage::RG32U | 0x823C | GL_RG32UI（GLSL 类型 rg32ui，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RGBA32U | 0x8D70 | GL_RGBA32UI（GLSL 类型 rgba32ui，受 OpenGL 4.2 及以上版本、OpenGL ES 3.1 及以上版本支持） |
Qt3DRender::QShaderImage::R8I | 0x8231 | GL_R8I（GLSL 类型 r8i，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RG8I | 0x8237 | GL_RG8I（GLSL 类型 rg8i，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RGBA8I | 0x8D8E | GL_RGBA8I（GLSL 类型 rgba8i，受 OpenGL 4.2 及以上版本、OpenGL ES 3.1 及以上版本支持） |
Qt3DRender::QShaderImage::R16I | 0x8233 | GL_R16I（GLSL 类型 r16i，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RG16I | 0x8239 | GL_RG16I（GLSL 类型 rg16i，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RGBA16I | 0x8D88 | GL_RGBA16I（GLSL 类型 rgba16i，受 OpenGL 4.2 及以上版本、OpenGL ES 3.1 及以上版本支持） |
Qt3DRender::QShaderImage::R32I | 0x8235 | GL_R32I（GLSL 类型 r32i，受 OpenGL 4.2+、OpenGL ES 3.1+ 支持） |
Qt3DRender::QShaderImage::RG32I | 0x823B | GL_RG32I（GLSL 类型 rg32i，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RGBA32I | 0x8D82 | GL_RGBA32I（GLSL 类型 rgba32i，受 OpenGL 4.2 及以上版本、OpenGL ES 3.1 及以上版本支持） |
Qt3DRender::QShaderImage::R16F | 0x822D | GL_R16F（GLSL 类型 r16f，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RG16F | 0x822F | GL_RG16F（GLSL 类型 rg16f，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RGBA16F | 0x881A | GL_RGBA16F（GLSL 类型 rgba16f，受 OpenGL 4.2 及以上版本、OpenGL ES 3.1 及以上版本支持） |
Qt3DRender::QShaderImage::R32F | 0x822E | GL_R32F（GLSL 类型 r32f，受 OpenGL 4.2 及以上版本、OpenGL ES 3.1 及以上版本支持） |
Qt3DRender::QShaderImage::RG32F | 0x8230 | GL_RG32F（GLSL 类型 rg32f，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RGBA32F | 0x8814 | GL_RGBA32F（GLSL 类型 rgba32f，受 OpenGL 4.2 及以上版本、OpenGL ES 3.1 及以上版本支持） |
Qt3DRender::QShaderImage::RG11B10F | 0x8C3A | GL_R11F_G11F_B10F（GLSL 类型 r11f_g11f_b10f，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RGB10A2 | 0x8059 | GL_RGB10_A2（GLSL 类型 rgb10_a2，受 OpenGL 4.2 及以上版本支持） |
Qt3DRender::QShaderImage::RGB10A2U | 0x906F | GL_RGB10_A2UI（GLSL 类型 rgb10_a2ui，受 OpenGL 4.2 及以上版本支持） |
属性文档
access : Access
指定我们希望允许着色器实例对图像进行的访问类型。如果着色器试图对访问类型不兼容的图像进行读写操作，则行为未定义。
默认值为QShaderImage::ReadWrite 。
访问函数：
| Qt3DRender::QShaderImage::Access | access() const |
| void | setAccess(Qt3DRender::QShaderImage::Access access) |
通知器信号：
| void | accessChanged(Qt3DRender::QShaderImage::Access access) |
format : ImageFormat
指定图像格式，这在将值从着色器存储到 Image 时至关重要。
该格式不必与所引用的纹理格式完全一致，但必须兼容（尺寸需匹配，但类类型不作硬性要求）。 例如，格式为 R32F（大小为 32 位，类为 1x32）的纹理可以与格式为 RGBA8I（大小为 32 位，类为 4x8）的图像一起使用。OpenGL 规范中的表 8.27 列出了所有受支持的 Image 格式的大小和类。
默认情况下，Qt3D 会尝试将图像格式设置为与被引用的纹理格式一致。
默认值为QShaderImage::Automatic 。
访问函数：
| Qt3DRender::QShaderImage::ImageFormat | format() const |
| void | setFormat(Qt3DRender::QShaderImage::ImageFormat format) |
通知器信号：
| void | formatChanged(Qt3DRender::QShaderImage::ImageFormat format) |
layer : int
指定应使用引用纹理中的哪一层作为QShaderImage 。如果layered 设置为true，或者引用纹理的类型与层不兼容，则此属性无作用。
注意：当 引用纹理的类型为立方体贴图（cube map）或立方体贴图数组（cube map array），且ĺayered 设置为false时，面和图层将按以下方式获取：
cubeMapLayer = layer / 6
cubeMapFace = layer - (cubeMapLayer * 6)默认值为 0。
访问函数：
| int | layer() const |
| void | setLayer(int layer) |
通知器信号：
| void | layerChanged(int layer) |
layered : bool
*
如果设置为 true，且引用的纹理是一维数组、二维数组、三维数组、立方体贴图、立方体贴图数组或二维多采样数组纹理，则整个纹理将绑定到所有图层。如果设置为 false，则仅绑定由layer 属性指定的单个图层。
默认值为false 。
访问函数：
| bool | layered() const |
| void | setLayered(bool layered) |
通知器信号：
| void | layeredChanged(bool layered) |
mipLevel : int
指定应从引用的纹理中使用哪个mipLevel作为QShaderImage 。
默认值为 0。
访问函数：
| int | mipLevel() const |
| void | setMipLevel(int mipLevel) |
通知器信号：
| void | mipLevelChanged(int mipLevel) |
texture : Qt3DRender::QAbstractTexture*
存储着着色器图像将要使用的纹理。
访问函数：
| Qt3DRender::QAbstractTexture * | texture() const |
| void | setTexture(Qt3DRender::QAbstractTexture *texture) |
通知器信号：
| void | textureChanged(Qt3DRender::QAbstractTexture *texture) |
© 2026 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.
