Qt3DRender::QShaderImage Class
class Qt3DRender::QShaderImage提供对着色器程序的图像访问。更多
| 头文件： | #include <QShaderImage> |
| 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 类型枚举 | 纹理类型 |
|---|---|---|
| 图像 1D | GL_IMAGE_1D | QTexture1D |
| 图像2D | GL_IMAGE_2D | QTexture2D |
| 图像 3D | GL_IMAGE_3D | QTexture3D |
| image2DRect | gl_image_2d_rect | QTextureRectangle |
| 图像立方体 | 图像立方体 | QTextureCubeMap |
| 图像缓冲区 | gl_image_buffer | QTextureBuffer |
| image1DArray | gl_image_1d_array | QTexture1DArray |
| 图像 2DArray | gl_image_2d_array | QTexture2DArray |
| 图像立方数组 | gl_image_cube_map_array | QTextureCubeMapArray |
| 图像2DMS | gl_image_2d_multisample | QTexture2DMultisample |
| 图像 2DMSArray | 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 类型枚举 | 纹理类型 |
|---|---|---|
| 图像 2D | GL_IMAGE_2D | QTexture2D |
| 图像 3D | GL_IMAGE_3D | QTexture3D |
| 图像立方体 | 图像立方体 | QTextureCubeMap |
| image2DArray | gl_image_2d_array | QTexture2DArray |
| iimage2D | gl_int_image_2d | QTexture2D |
| iimage3D | gl_int_image_3d | QTexture3D |
| 图像立方体 | 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 类型枚举 | 纹理类型 |
|---|---|---|
| 图像缓冲区 | gl_image_buffer | QTextureBuffer |
| 图像立方数组 | 图像立方图数组 | QTextureCubeMapArray |
| iimageBuffer | gl_image_buffer | QTextureBuffer |
| 图像立方数组 | 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) |
Notifier 信号：
| void | accessChanged(Qt3DRender::QShaderImage::Access access) |
format : ImageFormat
指定图像格式，这对于从着色器中将值存储到图像中非常重要。
格式不一定要与引用纹理的格式相同。但必须兼容（大小匹配，但不一定是类类型匹配）。例如，格式为 R32F（大小为 32 位，类别为 1x32）的纹理可以与格式为 RGBA8I（大小为 32 位，类别为 4x8）的图像一起使用。OpenGL 规范的表 8.27 显示了所有支持的图像格式的大小和类别。
默认情况下，Qt3D 将尝试设置图像格式，使其与引用纹理的格式相匹配。
默认值是QShaderImage::Automatic 。
访问函数：
| Qt3DRender::QShaderImage::ImageFormat | format() const |
| void | setFormat(Qt3DRender::QShaderImage::ImageFormat format) |
Notifier 信号：
| void | formatChanged(Qt3DRender::QShaderImage::ImageFormat format) |
layer : int
表示QShaderImage 应使用引用纹理中的哪个图层。如果layered 设置为 true 或引用纹理的类型与图层不兼容，则此属性不起任何作用。
注： 当引用的纹理类型为立方体贴图或立方体贴图数组，且ĺ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
表示QShaderImage 应使用引用纹理中的哪个 mipLevel。
默认值为 0。
访问功能：
| int | mipLevel() const |
| void | setMipLevel(int mipLevel) |
Notifier 信号：
| void | mipLevelChanged(int mipLevel) |
© 2025 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.
