QQuickRenderTarget Class
QQuickRenderTarget 类提供了一个用于存储本机图形资源的不透明容器，该容器指定了一个渲染目标及其相关元数据。更多内容...
| 头文件： | #include <QQuickRenderTarget> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake： | QT += quick |
| 自： | Qt 6.0 |
公共类型
公共函数
| QQuickRenderTarget() | |
| ~QQuickRenderTarget() | |
(since 6.8) QRhiTexture * | depthTexture() const |
(since 6.3) qreal | devicePixelRatio() const |
| bool | isNull() const |
(since 6.4) bool | mirrorVertically() const |
(since 6.8) void | setDepthTexture(QRhiTexture *texture) |
(since 6.3) void | setDevicePixelRatio(qreal ratio) |
(since 6.4) void | setMirrorVertically(bool enable) |
静态公共成员
(since 6.4) QQuickRenderTarget | fromD3D11Texture(void *texture, uint format, const QSize &pixelSize, int sampleCount = 1) |
| QQuickRenderTarget | fromD3D11Texture(void *texture, const QSize &pixelSize, int sampleCount = 1) |
(since 6.8) QQuickRenderTarget | fromD3D11Texture(void *texture, uint format, QSize pixelSize, int sampleCount, QQuickRenderTarget::Flags flags) |
(since 6.6) QQuickRenderTarget | fromD3D12Texture(void *texture, int resourceState, uint format, const QSize &pixelSize, int sampleCount = 1) |
(since 6.8) QQuickRenderTarget | fromD3D12Texture(void *texture, int resourceState, uint format, uint viewFormat, QSize pixelSize, int sampleCount, int arraySize, QQuickRenderTarget::Flags flags) |
(since 6.4) QQuickRenderTarget | fromMetalTexture(MTLTexture *texture, uint format, const QSize &pixelSize, int sampleCount = 1) |
| QQuickRenderTarget | fromMetalTexture(MTLTexture *texture, const QSize &pixelSize, int sampleCount = 1) |
(since 6.8) QQuickRenderTarget | fromMetalTexture(MTLTexture *texture, uint format, uint viewFormat, QSize pixelSize, int sampleCount, int arraySize, QQuickRenderTarget::Flags flags) |
(since 6.2) QQuickRenderTarget | fromOpenGLRenderBuffer(uint renderbufferId, const QSize &pixelSize, int sampleCount = 1) |
(since 6.4) QQuickRenderTarget | fromOpenGLTexture(uint textureId, uint format, const QSize &pixelSize, int sampleCount = 1) |
| QQuickRenderTarget | fromOpenGLTexture(uint textureId, const QSize &pixelSize, int sampleCount = 1) |
(since 6.8) QQuickRenderTarget | fromOpenGLTexture(uint textureId, uint format, QSize pixelSize, int sampleCount, int arraySize, QQuickRenderTarget::Flags flags) |
(since 6.4) QQuickRenderTarget | fromPaintDevice(QPaintDevice *device) |
(since 6.6) QQuickRenderTarget | fromRhiRenderTarget(QRhiRenderTarget *renderTarget) |
(since 6.4) QQuickRenderTarget | fromVulkanImage(VkImage image, VkImageLayout layout, VkFormat format, const QSize &pixelSize, int sampleCount = 1) |
| QQuickRenderTarget | fromVulkanImage(VkImage image, VkImageLayout layout, const QSize &pixelSize, int sampleCount = 1) |
(since 6.8) QQuickRenderTarget | fromVulkanImage(VkImage image, VkImageLayout layout, VkFormat format, VkFormat viewFormat, QSize pixelSize, int sampleCount, int arraySize, QQuickRenderTarget::Flags flags) |
相关的非成员
| bool | operator!=(const QQuickRenderTarget &a, const QQuickRenderTarget &b) |
| bool | operator==(const QQuickRenderTarget &a, const QQuickRenderTarget &b) |
另请参阅 QQuickWindow::setRenderTarget() 和QQuickGraphicsDevice 。
成员类型文档
[since 6.8] enum class QQuickRenderTarget::Flag
flags QQuickRenderTarget::Flags
静态QQuickRenderTarget 构造函数的标志。
| 常量 | 值 | 描述 |
|---|---|---|
QQuickRenderTarget::Flag::MultisampleResolve | 0x01 | 表示sampleCount 参数并非所提供纹理的采样数（且该纹理仍为非多采样纹理），而是多采样抗锯齿所需的采样数。这将自动创建并管理一个用作颜色缓冲区的中间多采样纹理（或纹理数组），对应用程序而言是透明的。 渲染过程结束时，这些采样会自动解析到提供的纹理中。当未设置此标志且sampleCount 参数大于1时，表示所提供的纹理为多采样纹理。若sampleCount 为1（表示不涉及多采样），则该标志无效。 |
该枚举类型在 Qt 6.8 中引入。
Flags 类型是QFlags<Flag> 的 typedef。它存储 Flag 值的按“或”运算组合。
成员函数文档
QQuickRenderTarget::QQuickRenderTarget()
构建一个默认的 QQuickRenderTarget，该对象不引用任何本机对象。
[noexcept] QQuickRenderTarget::~QQuickRenderTarget()
析构函数。
[since 6.8] QRhiTexture *QQuickRenderTarget::depthTexture() const
返回当前设置的深度纹理，或者在大多数情况下返回nullptr 。
仅当调用了setDepthTexture() 时，该值才不为空。
该函数在 Qt 6.8 中引入。
另请参阅 setDepthTexture()。
[since 6.3] qreal QQuickRenderTarget::devicePixelRatio() const
返回渲染目标的设备像素比。这是设备像素与设备独立像素之间的比例。
默认的设备像素比为 1.0。
该函数在 Qt 6.3 中引入。
另请参阅 setDevicePixelRatio()。
[static, since 6.4] QQuickRenderTarget QQuickRenderTarget::fromD3D11Texture(void *texture, uint format, const QSize &pixelSize, int sampleCount = 1)
返回一个新的QQuickRenderTarget ，该对象引用由texture 指定的D3D11纹理对象。
format 指定纹理的 DXGI_FORMAT。应仅使用 Qt 渲染基础设施支持的纹理格式。
pixelSize 指定图像的大小（以像素为单位）。目前仅支持 2D 纹理。
sampleCount 指定采样次数。0 或 1 表示不进行多重采样，而 4 或 8 等值则表示原生对象为多重采样纹理。
该纹理将作为Qt Quick 场景图所用渲染目标的第一个颜色附件。若适用，系统会自动创建并使用深度-模板缓冲区。
注意：生成的 QQuickRenderTarget 并不拥有任何原生资源，它仅包含引用以及大小和采样次数的相关元数据。确保原生资源在必要时一直存在是调用方的责任。
该函数于 Qt 6.4 中引入。
另请参阅 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
[static] QQuickRenderTarget QQuickRenderTarget::fromD3D11Texture(void *texture, const QSize &pixelSize, int sampleCount = 1)
返回一个新的QQuickRenderTarget ，该对象引用由texture 指定的D3D11纹理对象。该纹理的格式默认为DXGI_FORMAT_R8G8B8A8_UNORM。
pixelSize 指定图像的大小（以像素为单位）。目前仅支持 2D 纹理。
sampleCount 指定采样数。0 或 1 表示不进行多采样，而 4 或 8 等值则表示原生对象是多采样纹理。
该纹理将作为Qt Quick 场景图所用渲染目标的第一个颜色附件。如有必要，系统会自动创建并使用深度-模板缓冲区。
注意：生成的 QQuickRenderTarget 并不拥有任何原生资源，它仅包含引用以及大小和采样次数的相关元数据。确保原生资源在必要时一直存在是调用方的责任。
这是一个重载函数。
另请参阅 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
[static, since 6.8] QQuickRenderTarget QQuickRenderTarget::fromD3D11Texture(void *texture, uint format, QSize pixelSize, int sampleCount, QQuickRenderTarget::Flags flags)
返回一个新的QQuickRenderTarget ，该对象引用由texture 指定的D3D11纹理对象。
format 指定纹理的 DXGI_FORMAT。应仅使用 Qt 渲染基础设施支持的纹理格式。
pixelSize 指定图像的大小（以像素为单位）。目前仅支持 2D 纹理。
sampleCount 指定采样数。0 或 1 表示不进行多采样，而 4 或 8 等值则表示原生对象为多采样纹理，除非flags 包含MultisampleResolve 。在这种情况下，将假定texture 是一个非多采样的 2D 纹理，且sampleCount 定义了所需采样数。 生成的QQuickRenderTarget 将使用一个自动创建的中间多采样纹理作为其颜色附件，并将采样解析为texture 。当原生纹理本身并非多采样时，这是执行MSAA的推荐方法。
该纹理将作为Qt Quick 场景图所用渲染目标的第一个颜色附件。如果适用，系统会自动创建并使用深度-模板缓冲区。当颜色缓冲区为多采样时，深度-模板缓冲区也会自动成为多采样。
注意：生成的 QQuickRenderTarget 不拥有任何原生资源，它仅包含引用以及相关的大小和采样数元数据。确保原生资源在必要时一直存在是调用方的责任。
这是一个重载函数。
该函数在 Qt 6.8 中引入。
另请参阅 QQuickWindow::setRenderTarget()、QQuickRenderControl 以及fromD3D11Texture()。
[static, since 6.6] QQuickRenderTarget QQuickRenderTarget::fromD3D12Texture(void *texture, int resourceState, uint format, const QSize &pixelSize, int sampleCount = 1)
返回一个新的QQuickRenderTarget ，该对象引用由texture 指定的D3D12纹理对象。
resourceState xml-ph-0001@deepl.internal 必须是一个有效的位掩码，其位取自 D3D12_RESOURCE_STATES，用于指定资源的当前状态。
format 指定纹理的 DXGI_FORMAT。仅应使用 Qt 渲染基础设施支持的纹理格式。
pixelSize 指定图像的大小（以像素为单位）。目前仅支持 2D 纹理。
sampleCount 指定采样数。0 或 1 表示不进行多重采样，而 4 或 8 等值则表示原生对象为多重采样纹理。
该纹理将作为Qt Quick 场景图所用渲染目标的第一个颜色附件。如有需要，系统会自动创建并使用深度-模板缓冲区。
注意：生成的 QQuickRenderTarget 不拥有任何原生资源，它仅包含引用以及大小和采样次数的相关元数据。确保原生资源在必要时一直存在是调用方的责任。
该函数在 Qt 6.6 中引入。
另请参阅 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
[static, since 6.8] QQuickRenderTarget QQuickRenderTarget::fromD3D12Texture(void *texture, int resourceState, uint format, uint viewFormat, QSize pixelSize, int sampleCount, int arraySize, QQuickRenderTarget::Flags flags)
返回一个新的QQuickRenderTarget ，该对象引用由texture 指定的D3D12 2D纹理或2D纹理数组对象。
resourceState 必须是一个有效的位掩码，其中包含来自 D3D12_RESOURCE_STATES 的位，用于指定资源的当前状态。
format 指定纹理的 DXGI_FORMAT。应仅使用 Qt 渲染基础设施支持的纹理格式。
viewFormat 是渲染目标视图（RTV）所使用的 DXGI_FORMAT。通常与 `format` 相同。仅当驱动程序支持宽松的格式转换时才有效，否则该参数将被忽略。实际上，预计在 Windows 10 1703 及更高版本上始终支持此功能。
pixelSize 指定图像的大小（以像素为单位）。目前仅支持 2D 纹理和 2D 纹理数组。
sampleCount 指定采样数。0 或 1 表示不进行多采样，而 4 或 8 等值则表示原生对象是多采样纹理，除非flags 包含MultisampleResolve 。 在这种情况下，texture 将被视为非多采样的2D纹理或2D纹理数组，而sampleCount 则定义所需采样数。 生成的QQuickRenderTarget 将使用一个自动创建的中间多采样纹理（或纹理数组）作为其颜色附件，并将采样解析为texture 。当原生 D3D12 纹理本身还不是多采样时，这是执行 MSAA 的推荐方法。
数组元素（层）的数量由arraySize 指定。当该值大于1时，表示多视图渲染（视图实例化），这在VR/AR场景中尤为重要。arraySize 表示视图数量，通常为2 。有关在Qt Quick 场景图中启用多视图渲染的详细信息，请参阅QSGMaterial::viewCount()。
该纹理将作为Qt Quick 场景图所用渲染目标的第一个颜色附件。如果适用，系统会自动创建并使用深度-模板缓冲区。当颜色缓冲区为多采样时，深度-模板缓冲区也会自动变为多采样。 对于多视图渲染，深度-模板纹理将自动转换为与之匹配的arraySize 的数组。
注意：生成的 QQuickRenderTarget 不拥有任何本机资源，它仅包含引用以及相关的大小和采样数元数据。确保本机资源在必要时一直存在是调用方的责任。
这是一个重载函数。
该函数于 Qt 6.8 中引入。
另请参阅 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
[static, since 6.4] QQuickRenderTarget QQuickRenderTarget::fromMetalTexture(MTLTexture *texture, uint format, const QSize &pixelSize, int sampleCount = 1)
返回一个新的QQuickRenderTarget ，该对象引用由texture 指定的Metal纹理对象。
format 指定纹理的 MTLPixelFormat。应仅使用 Qt 渲染基础设施支持的纹理格式。
pixelSize 指定图像的大小（单位为像素）。目前仅支持 2D 纹理。
sampleCount 指定采样数。0 或 1 表示不进行多采样，而 4 或 8 等值则表示原生对象是一个多采样纹理。
该纹理将作为Qt Quick 场景图所用渲染目标的第一个颜色附件。如有需要，系统会自动创建并使用深度-模板缓冲区。
注意：生成的 QQuickRenderTarget 不拥有任何原生资源，它仅包含引用以及大小和采样数的相关元数据。确保原生资源在必要时始终存在是调用方的责任。
该函数在 Qt 6.4 中引入。
另请参阅 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
[static] QQuickRenderTarget QQuickRenderTarget::fromMetalTexture(MTLTexture *texture, const QSize &pixelSize, int sampleCount = 1)
返回一个新的QQuickRenderTarget ，该对象引用由texture 指定的Metal纹理对象。该纹理的格式默认为MTLPixelFormatRGBA8Unorm。
pixelSize 指定图像的大小（以像素为单位）。目前仅支持 2D 纹理。
sampleCount 指定采样数。0 或 1 表示不进行多重采样，而 4 或 8 等值则表示原生对象是多重采样纹理。
该纹理将作为Qt Quick 场景图所用渲染目标的第一个颜色附件。如果适用，系统会自动创建并使用深度-模板缓冲区。
注意：生成的 QQuickRenderTarget 不拥有任何原生资源，它仅包含引用以及大小和采样次数的相关元数据。确保原生资源在必要时一直存在是调用方的责任。
这是一个重载函数。
另请参阅 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
[static, since 6.8] QQuickRenderTarget QQuickRenderTarget::fromMetalTexture(MTLTexture *texture, uint format, uint viewFormat, QSize pixelSize, int sampleCount, int arraySize, QQuickRenderTarget::Flags flags)
返回一个新的QQuickRenderTarget ，该对象引用了texture 中指定的Metal 2D纹理或2D纹理数组。
format 指定纹理的 MTLPixelFormat。仅应使用 Qt 渲染基础设施支持的纹理格式。
viewFormat 通常设置为与format 相同的值。在某些情况下，例如将内容渲染到_SRGB 格式的纹理中，且不希望在着色器写入时进行隐式的线性→sRGB转换时，该值可以不同。但请注意，当运行时QRhi 报告QRhi::TextureViewFormat 功能不受支持时，Qt可能会忽略该值。
pixelSize 指定图像的大小（以像素为单位）。目前仅支持 2D 纹理和 2D 纹理数组。
sampleCount 指定采样数。0 或 1 表示不进行多采样，而 4 或 8 等值则表示原生对象为多采样纹理，除非flags 包含MultisampleResolve 。 在这种情况下，texture 将被视为非多采样的2D纹理或2D纹理数组，而sampleCount 则定义所需采样数。 生成的QQuickRenderTarget 将使用一个自动创建的中间多采样纹理（或纹理数组）作为其颜色附件，并将采样解析为texture 。当原生 Metal 纹理尚未是多采样时，这是执行 MSAA 的推荐方法。
数组元素（层）的数量由arraySize 指定。当该值大于1时，表示多视图渲染，这在VR/AR场景中尤为相关。arraySize 表示视图数量，通常为2 。有关在Qt Quick 场景图中启用多视图渲染的详细信息，请参阅QSGMaterial::viewCount()。
该纹理将作为Qt Quick 场景图所用渲染目标的第一个颜色附件。如果适用，系统会自动创建并使用深度-模板缓冲区。当颜色缓冲区为多采样时，深度-模板缓冲区也会自动变为多采样。 对于多视图渲染，深度-模板纹理将自动转换为一个数组，并配有相应的arraySize 。
注意：生成的 QQuickRenderTarget 不拥有任何本机资源，它仅包含引用以及相关的大小和采样数元数据。确保本机资源在必要时一直存在是调用方的责任。
这是一个重载函数。
该函数在 Qt 6.8 中引入。
另请参阅 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
[static, since 6.2] QQuickRenderTarget QQuickRenderTarget::fromOpenGLRenderBuffer(uint renderbufferId, const QSize &pixelSize, int sampleCount = 1)
返回一个新的QQuickRenderTarget ，该对象引用由renderbufferId 指定的OpenGL渲染缓冲区对象。
该渲染缓冲区将作为内部帧缓冲区对象的颜色附件使用。 提供此函数是为了支持将应用程序创建的、底层带有外部缓冲区的渲染缓冲区（例如 EGLImageKHR）作为目标。一旦应用程序调用了glEGLImageTargetRenderbufferStorageOES，该渲染缓冲区即可传递给此函数。
pixelSize 指定图像的大小（以像素为单位）。
sampleCount 指定采样数。0 或 1 表示不进行多采样，而 4 或 8 等值则表示本机对象是一个多采样渲染缓冲区。
注意：生成的 ` QQuickRenderTarget ` 并不拥有任何本机资源，它仅包含引用以及与大小和采样数相关的元数据。确保本机资源在必要时一直存在是调用方的责任。
该函数在 Qt 6.2 中引入。
另请参阅 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
[static, since 6.4] QQuickRenderTarget QQuickRenderTarget::fromOpenGLTexture(uint textureId, uint format, const QSize &pixelSize, int sampleCount = 1)
返回一个新的QQuickRenderTarget ，该对象引用由textureId 指定的OpenGL纹理对象。
format 指定纹理的原生内部格式。应仅使用 Qt 渲染基础设施支持的纹理格式。
pixelSize 指定图像的大小（以像素为单位）。目前仅支持 2D 纹理。
sampleCount 指定采样数。0 或 1 表示不进行多采样，而 4 或 8 等值则表示原生对象为多采样纹理。
该纹理将作为Qt Quick 场景图所用渲染目标的第一个颜色附件。如有需要，深度-模板缓冲区将自动创建并使用。
OpenGL 对象名称textureId 必须是Qt Quick 场景图所用渲染上下文中的有效名称。
注意：生成的 QQuickRenderTarget 不拥有任何本机资源，它仅包含引用以及相关的大小和采样数元数据。确保本机资源在必要时始终存在是调用方的责任。
该函数在 Qt 6.4 中引入。
另请参阅 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
[static] QQuickRenderTarget QQuickRenderTarget::fromOpenGLTexture(uint textureId, const QSize &pixelSize, int sampleCount = 1)
返回一个新的QQuickRenderTarget ，该对象引用由textureId 指定的OpenGL纹理对象。该纹理默认采用GL_RGBA（GL_RGBA8）格式。
pixelSize 指定图像的大小，单位为像素。目前仅支持 2D 纹理。
sampleCount 指定采样数。0 或 1 表示不进行多重采样，而 4 或 8 等值则表示原生对象为多重采样纹理。
该纹理将作为Qt Quick 场景图所用渲染目标的第一个颜色附件。如果适用，系统会自动创建并使用深度-模板缓冲区。
OpenGL 对象名称textureId 必须是Qt Quick 场景图所用渲染上下文中的有效名称。
注意：生成的 QQuickRenderTarget 不拥有任何本机资源，它仅包含引用以及大小和采样数的相关元数据。确保本机资源在必要时始终存在是调用方的责任。
这是一个重载函数。
另请参阅 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
[static, since 6.8] QQuickRenderTarget QQuickRenderTarget::fromOpenGLTexture(uint textureId, uint format, QSize pixelSize, int sampleCount, int arraySize, QQuickRenderTarget::Flags flags)
返回一个新的QQuickRenderTarget ，该对象引用由textureId 指定的OpenGL 2D纹理或纹理数组对象。
format 指定纹理的原生内部格式。应仅使用 Qt 渲染基础设施支持的纹理格式。
pixelSize 指定图像的大小（以像素为单位）。目前仅支持 2D 纹理和 2D 纹理数组。
sampleCount 指定采样数。0 或 1 表示不进行多采样，而 4 或 8 等值则表示原生对象是多采样纹理，除非flags 包含MultisampleResolve 。 在这种情况下，textureId 将被视为非多采样的2D纹理或2D纹理数组，而sampleCount 则定义所需的采样数量。 生成的QQuickRenderTarget 将使用一个自动创建的中间多采样纹理（或纹理数组）作为其颜色附件，并将采样解析为textureId 。当原生OpenGL纹理尚未是多采样时，这是执行MSAA的推荐方法。
当arraySize 大于1时，表示多视图渲染（GL_OVR_multiview， QRhiColorAttachment::setMultiViewCount()），这尤其与VR/AR相关。在此情况下，arraySize 表示视图数量，通常为2 。有关在Qt Quick 场景图中启用多视图渲染的详细信息，请参阅QSGMaterial::viewCount()。
如果适用，系统会自动创建并使用深度-模板缓冲区。当颜色缓冲区为多采样时，深度-模板缓冲区也会自动成为多采样。对于多视图渲染，深度-模板纹理将自动转换为一个数组，并具有匹配的arraySize 。
OpenGL 对象名称textureId 必须是Qt Quick 场景图所用渲染上下文中有效的 2D 纹理名称。当arraySize 大于 1 时，textureId 必须是有效的 2D 纹理数组名称。
注意：生成的 QQuickRenderTarget 不拥有任何本机资源，它仅包含引用以及大小和采样数的相关元数据。确保本机资源在必要时一直存在是调用者的责任。
注意： 此重载的实现 与 OpenGL ES 2.0 或 3.0 不兼容，至少需要 OpenGL ES 3.1。（或在桌面端使用 OpenGL 3.0）
这是一个重载函数。
该函数于 Qt 6.8 中引入。
另请参阅 QQuickWindow::setRenderTarget()、QQuickRenderControl 以及fromOpenGLTexture()。
[static, since 6.4] QQuickRenderTarget QQuickRenderTarget::fromPaintDevice(QPaintDevice *device)
返回一个新的QQuickRenderTarget ，该对象引用由device 指定的绘制设备对象。
仅当使用Qt Quick 的software 后端运行时，才可使用此将渲染重定向至QPaintDevice 的选项。
注意： QQuickRenderTarget 不会接管device 的所有权，确保该对象在必要期间内持续存在是调用方的责任。
该函数于 Qt 6.4 中引入。
另请参阅 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
[static, since 6.6] QQuickRenderTarget QQuickRenderTarget::fromRhiRenderTarget(QRhiRenderTarget *renderTarget)
返回一个引用现有 `renderTarget` 的新 `QQuickRenderTarget `。
renderTarget 在大多数情况下，该对象将是一个 `QRhiTextureRenderTarget`，它允许将 `Qt Quick ` 场景的渲染结果导出到 `QRhiTexture` 中。
注意：生成的 QQuickRenderTarget 并不拥有renderTarget 及其底层原生资源，它仅包含引用以及相关的大小和采样数元数据。确保被引用的资源在必要时始终存在是调用方的责任。
该函数在 Qt 6.6 中引入。
另请参阅 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
[static, since 6.4] QQuickRenderTarget QQuickRenderTarget::fromVulkanImage(VkImage image, VkImageLayout layout, VkFormat format, const QSize &pixelSize, int sampleCount = 1)
返回一个新的QQuickRenderTarget ，该对象引用由image 指定的Vulkan图像对象。还必须提供该图像的当前layout 。
format 指定图像的 VkFormat。应仅使用 Qt 渲染基础设施支持的图像格式。
pixelSize 指定图像的大小（以像素为单位）。目前仅支持 2D 纹理。
sampleCount 指定采样数。0 或 1 表示不进行多采样，而 4 或 8 这样的值则表示原生对象是多采样纹理。
该图像将作为Qt Quick 场景图所用渲染目标的第一个颜色附件。如有需要，系统会自动创建并使用深度-模板缓冲区。
注意：生成的 QQuickRenderTarget 不拥有任何原生资源，它仅包含引用以及大小和采样次数的相关元数据。确保原生资源在必要时一直存在是调用方的责任。
该函数在 Qt 6.4 中引入。
另请参阅 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
[static] QQuickRenderTarget QQuickRenderTarget::fromVulkanImage(VkImage image, VkImageLayout layout, const QSize &pixelSize, int sampleCount = 1)
返回一个新的QQuickRenderTarget ，该对象引用由image 指定的Vulkan图像对象。该图像默认采用VK_FORMAT_R8G8B8A8_UNORM格式。
pixelSize 指定图像的大小（以像素为单位）。目前仅支持 2D 纹理。
sampleCount 指定采样数。0 或 1 表示不进行多采样，而 4 或 8 等值则表示原生对象为多采样纹理。
该纹理将作为Qt Quick 场景图所用渲染目标的第一个颜色附件。如有需要，系统会自动创建并使用深度-模板缓冲区。
注意：生成的 QQuickRenderTarget 并不拥有任何原生资源，它仅包含引用以及相关的大小和采样次数元数据。确保原生资源在必要期间内始终存在是调用方的责任。
这是一个重载函数。
另请参阅 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
[static, since 6.8] QQuickRenderTarget QQuickRenderTarget::fromVulkanImage(VkImage image, VkImageLayout layout, VkFormat format, VkFormat viewFormat, QSize pixelSize, int sampleCount, int arraySize, QQuickRenderTarget::Flags flags)
返回一个新的QQuickRenderTarget ，该对象引用由image 指定的Vulkan图像对象。还必须提供该图像的当前layout 。该图像必须是2D纹理或2D纹理数组。
format 指定图像的 VkFormat。应仅使用 Qt 渲染基础设施支持的图像格式。
viewFormat 通常设置为与format 相同的值。在某些情况下，例如将图像渲染到_SRGB 格式的纹理中，且不希望在着色器写入时进行隐式线性→sRGB转换时，该值可以不同。（例如，format 为VK_FORMAT_R8G8B8A8_SRGB ，viewFormat 为VK_FORMAT_R8G8B8A8_UNORM ）。
pixelSize 指定图像的大小，单位为像素。目前仅支持 2D 纹理。
sampleCount 指定采样次数。0 或 1 表示不进行多采样，而 4 或 8 等值则表示原生对象为多采样纹理，除非flags 包含MultisampleResolve 。 在这种情况下，image 将被视为非多采样的2D纹理或2D纹理数组，而sampleCount 则定义了所需采样数。 生成的QQuickRenderTarget 将使用一个自动创建的中间多采样纹理（或纹理数组）作为其颜色附件，并将采样解析为image 。当原生Vulkan图像本身尚未采用多采样时，这是执行MSAA的推荐方法。
数组元素（层）的数量由arraySize 指定。当该值大于1时，表示多视图渲染（VK_KHR_multiview），这在VR/AR场景中尤为重要。arraySize 表示视图数量，通常为2 。有关在Qt Quick 场景图中启用多视图渲染的详细信息，请参阅QSGMaterial::viewCount()。
该纹理将作为Qt Quick 场景图所用渲染目标的第一个颜色附件。如果适用，系统会自动创建并使用深度-模板缓冲区。当颜色缓冲区为多采样时，深度-模板缓冲区也将自动变为多采样。 对于多视图渲染，深度-模板纹理将自动转换为与之匹配的arraySize 数组。
注意：生成的 QQuickRenderTarget 不拥有任何本机资源，它仅包含引用以及相关的大小和采样数元数据。确保本机资源在必要时一直存在是调用方的责任。
这是一个重载函数。
该函数在 Qt 6.8 中引入。
另请参见 QQuickWindow::setRenderTarget() 和QQuickRenderControl 。
bool QQuickRenderTarget::isNull() const
如果该QQuickRenderTarget 是通过默认构造函数初始化的，且未引用任何本机对象，则返回true。
[since 6.4] bool QQuickRenderTarget::mirrorVertically() const
返回值 返回渲染目标是否进行了垂直镜像。
默认值为false 。
该函数自 Qt 6.4 起引入。
另请参见 setMirrorVertically()。
[since 6.8] void QQuickRenderTarget::setDepthTexture(QRhiTexture *texture)
将给定的texture 用作深度或深度-模板缓冲区的请求。不会获取texture 的所有权。
该请求仅在相关情况下才会被考虑。例如，在调用fromRhiRenderTarget()、fromPaintDevice() 或fromOpenGLRenderBuffer() 时，调用此函数不会产生任何效果。
通常，深度-模板缓冲区会自动创建，对QQuickRenderTarget 的用户而言是透明的。 因此，在使用QQuickRenderTarget 时，大多数情况下无需调用此函数。但在特殊情况下，可能必须提供一个纹理来渲染深度（或深度和模板）数据，而不是让Qt Quick 创建自己的中间纹理或缓冲区。 一个典型的例子是OpenXR及其扩展，例如XR_KHR_composition_layer_depth。 为了将“深度缓冲区”提交给 XR 合成器，实际上必须从 OpenXR（通过 XrSwapchain）中获取一个已创建的深度（深度-模板）纹理，并将该纹理用作深度数据的渲染目标。如果没有此函数，这将无法实现。
注意： texture 预期 始终为非多采样 2D 纹理或纹理数组（用于多视图）。如果涉及 MSAA，无论是否设置了MultisampleResolve 标志，采样都会在渲染通道结束时解析为texture 。 只有当底层 3D API 支持时，深度（深度-模板）纹理才支持 MSAA，且该支持并非普遍可用。详情请参阅the relevant QRhi feature flag 。当不支持此功能且请求结合自定义深度纹理使用多采样时，渲染过程中将不会对texture 进行处理，并会输出警告信息。
注意：对于 OpenGL 和 OpenGL ES，深度纹理在 OpenGL ES 2.0 上无法正常工作，需要至少 OpenGL ES 3.0 版本。若未达到 OpenGL ES 3.1 版本（或桌面端的 OpenGL 3.0 版本），则不支持多采样（MSAA）。
该函数在 Qt 6.8 中引入。
另请参阅 depthTexture()。
[since 6.3] void QQuickRenderTarget::setDevicePixelRatio(qreal ratio)
将此渲染目标的设备像素比设置为ratio 。这是设备像素与设备独立像素之间的比例。
请注意，如果重新实现了 `QQuickRenderControl::renderWindow()` 函数并使其返回一个有效的 `QWindow`，则指定的设备像素比值将被忽略。
该函数于 Qt 6.3 中引入。
另请参阅 devicePixelRatio()。
[since 6.4] void QQuickRenderTarget::setMirrorVertically(bool enable)
设置渲染目标的大小，以便在绘制时将内容沿垂直方向镜像到enable 上。这使得集成不符合标准预期的第三方渲染代码变得更加容易。
注意： 在使用software 后端时，不应使用此 函数。
该函数于 Qt 6.4 中引入。
另请参阅 mirrorVertically()。
相关的非成员
[noexcept] bool operator!=(const QQuickRenderTarget &a, const QQuickRenderTarget &b)
如果a 和b 指向不同的本机对象集，或者相关数据（大小、样本数）不匹配，则返回 true。
[noexcept] bool operator==(const QQuickRenderTarget &a, const QQuickRenderTarget &b)
如果a 和b 指向同一组本机对象，且其关联数据（大小、样本数）相匹配，则返回 true。
© 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.
