QRhi Class

成员函数文档

[noexcept] QRhi::~QRhi()

析构函数。销毁后端并释放资源。

void QRhi::addCleanupCallback(const QRhi::CleanupCallback &callback)

注册一个callback ，该回调函数将在QRhi 被销毁时被调用。

回调函数执行时图形资源仍可用，因此这为应用程序提供了一个机会，可以干净地释放属于QRhi 的QRhiResource 实例。这对于管理存储在cache 类型对象中的资源的生命周期特别有用，其中缓存中包含QRhiResources或包含QRhiResources的对象。

另请参阅 ~QRhi()。

void QRhi::addCleanupCallback(const void *key, const QRhi::CleanupCallback &callback)

注册回调函数callback ，以便在QRhi 被销毁时调用该函数。此重载接受一个不透明指针key ，用于确保给定的回调函数仅被注册（并因此被调用）一次。

另请参阅 removeCleanupCallback()。

QRhi::Implementation QRhi::backend() const

返回此QRhi 的后端类型。

const char *QRhi::backendName() const

返回此QRhi 的后端类型（字符串形式）。

[static] const char *QRhi::backendName(QRhi::Implementation impl)

返回后端impl 的友好名称，通常为所用3D API的名称。

QRhi::FrameOpResult QRhi::beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags = {})

启动一个新帧，目标为swapChain 中的下一个可用缓冲区。

一个帧由资源更新以及一个或多个渲染和计算过程组成。

flags 可能表示某些特殊情况。

使用交换链将内容渲染到QWindow 中的高级模式如下：

• 创建一个交换链。
• 每当表面大小与之前不同时，调用 `QRhiSwapChain::createOrResize()`。
• 在 `QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed` 上调用 `QRhiSwapChain::destroy()`。
• 然后在每一帧中：

  beginFrame(sc);
  updates = nextResourceUpdateBatch();
  updates->...
  QRhiCommandBuffer *cb = sc->currentFrameCommandBuffer();
  cb->beginPass(sc->currentFrameRenderTarget(), colorClear, dsClear, updates);
  ...
  cb->endPass();
  ... // more passes as necessary
  endFrame(sc);

成功时返回QRhi::FrameOpSuccess ，失败时返回另一个QRhi::FrameOpResult 值。其中某些情况应被视为软错误，即“稍后重试”类型的错误：当返回QRhi::FrameOpSwapChainOutOfDate 时，应通过调用QRhiSwapChain::createOrResize()来调整交换链的大小或更新交换链。 随后，应用程序应尝试生成一个新的帧。QRhi::FrameOpDeviceLost 表示图形设备已丢失，但通过释放所有资源（包括QRhi 本身），然后重新创建所有资源，可能仍可恢复。有关详细讨论，请参阅isDeviceLost()。

另请参阅 endFrame()、beginOffscreenFrame() 以及isDeviceLost()。

QRhi::FrameOpResult QRhi::beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags = {})

启动一个新的离屏帧。提供一个适用于在cb 中记录渲染命令的命令缓冲区。flags 用于指示某些特殊情况，这与beginFrame()的功能类似。

也可以不使用交换链进行渲染。典型的用例是在完全离屏的应用程序中使用，例如通过渲染和回读来生成图像序列，而完全不显示窗口。

在屏幕内应用程序中（即beginFrame 、endFrame 、beginOffscreenFrame、endOffscreenFrame 、beginFrame 等）也可以使用。

当安排了texture 或buffer 的回读操作时，离屏帧可防止CPU在GPU仍在处理上一帧时生成新帧。这带来的附带效果是：如果安排了回读操作，则可以保证endOffscreenFrame()返回时，结果已可用。 针对交换链的帧则并非如此：虽然在此情况下 GPU 的利用率可能更高，但应用程序在处理读回操作时需要更加谨慎，因为endFrame() 与endOffscreenFrame() 不同，它无法保证读回结果在该时刻已可用。

不使用交换链渲染帧并随后读回帧内容的代码框架可能如下所示：

QRhiReadbackResult rbResult;
QRhiCommandBuffer *cb;
rhi->beginOffscreenFrame(&cb);
cb->beginPass(rt, colorClear, dsClear);
// ...
u = nextResourceUpdateBatch();
u->readBackTexture(rb, &rbResult);
cb->endPass(u);
rhi->endOffscreenFrame();
// image data available in rbResult

另请参阅 endOffscreenFrame() 和beginFrame()。

QMatrix4x4 QRhi::clipSpaceCorrMatrix() const

返回一个矩阵，应用程序可利用该矩阵继续使用针对 OpenGL 的顶点数据和透视投影矩阵（例如由QMatrix4x4::perspective() 生成的那些），而无论当前活动的QRhi 后端为何。

在典型的渲染器中，一旦使用this_matrix * mvp 代替单纯的mvp ，即可使用 Y 轴向上且深度范围为 0 - 1 的视口，而无需考虑运行时将使用何种后端（以及相应的图形 API）。 这样可以避免基于isYUpInNDC() 和isClipDepthZeroToOne() 的条件分支（尽管在实现某些高级图形技术时，此类逻辑可能仍然不可或缺）。

有关从 Vulkan 角度对该主题的讨论，请参阅此页面。

[static] QRhi *QRhi::create(QRhi::Implementation impl, QRhiInitParams *params, QRhi::Flags flags, QRhiNativeHandles *importDevice, QRhiAdapter *adapter)

返回一个新的QRhi 实例，其后端为由impl 指定的图形API，并使用指定的flags 。如果函数执行失败，则返回nullptr 。

params 必须指向QRhiInitParams 的某个后端特定子类的实例，例如：QRhiVulkanInitParams 、QRhiMetalInitParams 、QRhiD3D11InitParams 、QRhiD3D12InitParams 、QRhiGles2InitParams 。有关创建QRhi 的示例，请参阅这些类。

QRhi 按设计不实现任何备用逻辑：如果无法初始化指定的 API，create() 将失败，后端会在调试输出中打印警告。不过，QRhi 的客户端（例如Qt Quick ）可能会根据平台提供额外的逻辑，允许回退到与请求不同的 API。 如果仅是为了测试在稍后调用 `create()` 时初始化是否会成功，建议使用 `probe()` 代替 `create()`，因为对于某些后端，探测功能可以以比 `create()` 更轻量的方式实现；而 `create()` 会对基础架构进行完整初始化，如果随后立即丢弃该 `QRhi ` 实例，则会造成资源浪费。

importDevice 允许使用已存在的图形设备，而无需由QRhi 自行创建。当该参数不为空时，必须指向QRhiNativeHandles 的某个子类的实例：QRhiVulkanNativeHandles 、QRhiD3D11NativeHandles 、QRhiD3D12NativeHandles 、QRhiMetalNativeHandles 、QRhiGles2NativeHandles 。具体细节和语义取决于后端以及底层的图形 API。

在adapter 中指定QRhiAdapter ，提供了一种透明的、跨API的替代方案，可替代通过QRhiVulkanNativeHandles 传入VkPhysicalDevice ，或通过QRhiD3D12NativeHandles 传入适配器LUID。不会获取adapter 的所有权。有关此方法的更多信息，请参阅enumerateAdapters()。

另请参阅 probe()。

[static] QRhi *QRhi::create(QRhi::Implementation impl, QRhiInitParams *params, QRhi::Flags flags = {}, QRhiNativeHandles *importDevice = nullptr)

相当于 create(impl,params,flags,importDevice,nullptr)。

int QRhi::currentFrameSlot() const

在录制帧时返回当前帧槽索引。若在非活动帧外调用（即当isRecordingFrame()为false 时），则未指定该索引。

对于 Vulkan 或 Metal 等后端，当开始一个新帧时，若发现 CPU 已FramesInFlight - 1 帧领先于 GPU（因为在帧号current -FramesInFlight 提交的命令缓冲区尚未完成），则由QRhi 后端负责进行阻塞。

那些在帧与帧之间容易发生变化的资源（例如，作为类型为QRhiBuffer::Dynamic 的QRhiBuffer 的后端原生缓冲区对象）会存在多个版本，这样，当上一帧仍在处理中时提交的每一帧都可以使用自己的副本，从而避免了在准备帧时需要让管道停滞。 （不应触及可能仍在 GPU 中被使用的资源内容，但如果总是等待上一帧处理完毕，将会降低 GPU 利用率，并最终影响性能和效率。）

从概念上讲，这与某些 C++ 容器及其他类型所采用的“写时复制”（copy-on-write）机制有些相似。它可能也类似于 OpenGL 或 Direct 3D 11 实现中针对特定类型对象所执行的内部操作。

实际上，在Vulkan、Metal以及类似的QRhi 后端中，此类双缓冲（或三缓冲）资源是通过在QRhiResource 背后配置固定数量的原生资源（如VkBuffer）slots 来实现的。 随后可通过帧槽索引（范围从 0、1、…、FramesInFlight-1，并循环往复）对这些资源进行索引。

对于QRhi 的用户而言，这一切都是透明管理的。然而，直接集成图形 API 渲染功能的应用程序可能希望对其自身的图形资源执行类似的双缓冲或三缓冲操作。 要实现这一点，最简单的方法是了解待处理帧的最大数量（可通过resourceLimit() 获取）以及当前帧（槽）索引（由该函数返回）。

另请参阅 isRecordingFrame()、beginFrame() 以及endFrame()。

QRhiDriverInfo QRhi::driverInfo() const

返回此已成功初始化的QRhi 实例所使用的图形设备的元数据。

QRhi::FrameOpResult QRhi::endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags = {})

结束、提交并呈现一个在swapChain 上通过上一次beginFrame()方法启动的帧。

双缓冲（或三缓冲）由QRhiSwapChain 和QRhi 在内部进行管理。

flags 可选地，可使用该方法以特定方式更改行为。传递 `QRhi::SkipPresent ` 会跳过将 `Present` 命令加入队列或调用 `swapBuffers`。

成功时返回QRhi::FrameOpSuccess ，失败时返回另一个QRhi::FrameOpResult 值。其中某些情况应被视为软错误，即“稍后重试”类型的错误：当返回QRhi::FrameOpSwapChainOutOfDate 时，应通过调用QRhiSwapChain::createOrResize()来调整交换链的大小或更新交换链。 随后，应用程序应尝试生成一个新帧。QRhi::FrameOpDeviceLost 表示图形设备已丢失，但通过释放所有资源（包括QRhi 本身），然后重新创建所有资源，可能仍可恢复。有关详细讨论，请参阅isDeviceLost()。

另请参阅 beginFrame() 和isDeviceLost()。

QRhi::FrameOpResult QRhi::endOffscreenFrame(QRhi::EndFrameFlags flags = {})

结束、提交，并可能等待该帧的离屏渲染完成。

与endFrame()不同，当存在活跃的缓冲区或纹理回读时，此函数将阻塞并等待 GPU 端工作完成。

flags 目前未被使用。

另请参阅 beginOffscreenFrame()。

[static, since 6.10] QRhi::AdapterList QRhi::enumerateAdapters(QRhi::Implementation impl, QRhiInitParams *params, QRhiNativeHandles *nativeHandles = nullptr)

返回现有适配器（物理设备）的列表；如果给定的图形 API 不支持此功能，则返回空列表。

对于不支持此级别控制的后端，返回的列表始终为空。因此，空列表并不表示系统中没有图形设备，而是表示无法对选择使用哪个设备进行精细控制。

Direct 3D 11、Direct 3D 12 和 Vulkan 的后端通常完全支持适配器的枚举。其他后端可能不支持。 后端由impl 指定。该函数返回的QRhiAdapter 仅可用于带有相同impl 的create()调用。某些底层API可能会存在进一步的限制，特别是Vulkan中，QRhiAdapter 被指定为QVulkanInstance （VkInstance ）。

调用方应销毁列表中的QRhiAdapter 对象。除了调用info()之外，这些对象的唯一用途就是传递给create()，或者传递给更高层级的相应函数，例如Qt Quick 。

以下代码片段专为 Vulkan 编写，演示了如何枚举可用的物理设备，并请求为选定的设备创建一个QRhi 。实际上，这相当于通过QRhiVulkanNativeHandles 将VkPhysicalDevice 传递给create()，但在应用程序侧涉及的 API 特定代码更少：

QRhiVulkanInitParams initParams;
initParams.inst= &vulkanInstance;
QRhi::AdapterList adapters=QRhi::enumerateAdapters(QRhi::Vulkan, &initParams);
QRhiAdapter*chosenAdapter =nullptr;
for(QRhiAdapter*adapter: adapters) {
    if(looksGood(adapter->info())) {
        chosenAdapter=adapter;
        break;
    }
}
QRhi*rhi =QRhi::create(QRhi::Vulkan, &initParams,{},nullptr,chosenAdapter);
qDeleteAll(adapters);

由于某些底层图形 API 的设计原因，必须在params 中传递参数。特别是对于 Vulkan，必须提供QVulkanInstance ，因为没有它就无法进行枚举。后端特有的params 中的其他字段实际上不会被此函数使用。

nativeHandles 是可选的。若指定，它必须是有效的QRhiD3D11NativeHandles 、QRhiD3D12NativeHandles 或QRhiVulkanNativeHandles ，与create() 类似。但与create() 不同，此处仅使用物理设备（Vulkan 情况下）或适配器 LUID（D3D 情况下）字段，所有其他字段均被忽略。这可用于将结果限制在指定的适配器上。 在此情况下，返回的列表将包含 1 个或 0 个元素。

请注意，在之前的代码片段中，looksGood() 函数的实现无法基于真正的适配器/物理设备标识（例如 Windows 上的适配器 LUID 或 Vulkan 中的 VkPhysicalDevice）进行任何平台特定的过滤。这是因为QRhiDriverInfo 不包含平台特定数据。 取而代之，请使用 `nativeHandles ` 来获取已在 `enumerateAdapters()` 内部经过过滤的结果。

以下两个代码片段以 Direct 3D 12 为例，实际上效果等同：

// 自 Qt 6.10 起基于 enumerateAdapters 的方法
QRhiD3D12InitParams initParams;
QRhiD3D12NativeHandles nativeHandles;
nativeHandles.adapterLuidLow=luid.LowPart;// 从某处获取了 LUID，现在将其传递给 Qt
nativeHandles.adapterLuidHigh=luid.HighPart;
QRhi::AdapterList adapters=QRhi::enumerateAdapters(QRhi::D3D12, &initParams, &nativeHandles);
if(adapters.isEmpty()) {qWarning("未找到请求的适配器");}
QRhi*rhi =QRhi::create(QRhi::D3D12, &initParams,{},nullptr,adapters[0]);
qDeleteAll(adapters);

// traditional approach, more lightweight
QRhiD3D12InitParams initParams;
QRhiD3D12NativeHandles nativeHandles;
nativeHandles.adapterLuidLow = luid.LowPart; // retrieved a LUID from somewhere, now pass it on to Qt
nativeHandles.adapterLuidHigh = luid.HighPart;
QRhi *rhi = QRhi::create(QRhi::D3D12, &initParams, {}, &nativeHandles, nullptr);

该函数在 Qt 6.10 中引入。

另请参阅 create()。

QRhi::FrameOpResult QRhi::finish()

等待图形队列（如适用）中的任何任务完成，然后执行所有延迟操作，例如完成读回和资源释放。该函数可在帧内和帧外调用，但不能在渲染通道内调用。在帧内调用时，这意味着会提交命令缓冲区中的任何任务。

bool QRhi::isClipDepthZeroToOne() const

如果底层图形 API 在裁剪空间中使用深度范围 [0, 1]，则返回true 。

实际上，这仅对 OpenGL 而言是false ，因为 OpenGL 使用投影后的深度范围 [-1, 1]。（请勿与由 glDepthRange() 控制的 NDC 到窗口映射混淆，后者使用范围 [0, 1]，除非被QRhiViewport 覆盖） 在某些 OpenGL 版本中，可以使用 glClipControl() 来更改此设置，但QRhi 的 OpenGL 后端并未使用该函数，因为该函数在 OpenGL ES 或低于 4.5 版本的 OpenGL 中不可用。

bool QRhi::isDeviceLost() const

如果图形设备丢失，则返回 true。

通常在beginFrame()、endFrame()或QRhiSwapChain::createOrResize()中检测到设备丢失，具体取决于后端和底层原生API。最常见的是endFrame()，因为呈现操作正是在此处进行的。对于某些后端，QRhiSwapChain::createOrResize()也可能因设备丢失而失败。 因此，提供此函数作为一种通用方法，用于检查先前操作是否检测到设备丢失。

当设备丢失时，不应再通过QRhi 执行任何操作。相反，应释放所有QRhi 资源，随后销毁QRhi 。然后可以尝试创建一个新的QRhi 。如果成功，必须重新初始化所有图形资源。如果不成功，请稍后重试，并反复尝试。

虽然简单的应用程序可能选择忽略设备丢失的情况，但在常用的桌面平台上，设备丢失可能由多种原因引起，包括物理断开图形适配器、禁用设备或驱动程序、卸载或升级图形驱动程序，或者因导致图形设备重置的错误所致。 其中一些情况甚至可能在完全正常的环境下发生，例如将图形驱动程序升级到新版本是一项常见操作，可能在 Qt 应用程序运行的任何时候发生。用户完全有理由期望应用程序能够在此情况下继续正常运行，即使该应用程序正在积极使用 OpenGL 或 Direct3D 等 API 也是如此。

基于QRhi 构建的Qt自有框架（例如Qt Quick ）在发生设备丢失时，通常能够进行处理并采取适当措施。 如果图形资源（如纹理和缓冲区）的数据在CPU端仍然可用，则此类事件在应用程序层面上可能完全不会被察觉，因为图形资源可以无缝地重新初始化。然而，直接使用QRhi 的应用程序和库应做好准备，自行检查并处理设备丢失的情况。

bool QRhi::isFeatureSupported(QRhi::Feature feature) const

如果指定的feature 被支持，则返回true

bool QRhi::isRecordingFrame() const

当存在活动帧时返回 true，这意味着已调用beginFrame()（或beginOffscreenFrame()），但尚未有对应的endFrame()（或endOffscreenFrame()）。

另请参阅 currentFrameSlot()、beginFrame() 和endFrame()。

bool QRhi::isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags = {}) const

如果由flags 修改的指定纹理format 受支持，则返回true 。

该查询同时支持未压缩和压缩格式。

bool QRhi::isYUpInFramebuffer() const

如果底层图形 API 在帧缓冲区和图像中将 Y 轴设置为向上，则返回true 。

实际上，仅在 OpenGL 中，此函数返回值为true 。

bool QRhi::isYUpInNDC() const

如果底层图形 API 的归一化设备坐标系中 Y 轴向上，则返回true 。

实际上，仅在 Vulkan 中，该函数返回值为 `false `。

bool QRhi::makeThreadLocalNativeContextCurrent()

在 OpenGL 中，这会将该 OpenGL 上下文设为当前线程的活动上下文。在其他后端中，该函数无效。

通常在 Qt 框架代码中调用此函数，目的是确保应用程序提供的外部 OpenGL 代码，只要QRhi 仍在使用 OpenGL 后端，就能像以前直接使用 OpenGL 时那样正常运行。

失败时返回 false，与 `QOpenGLContext::makeCurrent()` 类似。当操作失败时，可调用 `isDeviceLost()` 来确定是否发生了上下文丢失的情况。此类检查等同于通过 `QOpenGLContext::isValid()` 进行检查。

另请参阅 QOpenGLContext::makeCurrent() 和QOpenGLContext::isValid()。

[static] int QRhi::mipLevelsForSize(const QSize &size)

返回给定size 的MIP级别数量。

const QRhiNativeHandles *QRhi::nativeHandles()

返回指向后端特定本机对象集合的指针，该集合包含后端所使用的设备、上下文及类似概念。

请根据需要将其强制转换为QRhiVulkanNativeHandles 、QRhiD3D11NativeHandles 、QRhiD3D12NativeHandles 、QRhiGles2NativeHandles 或QRhiMetalNativeHandles 。

QRhiBuffer *QRhi::newBuffer(QRhiBuffer::Type type, QRhiBuffer::UsageFlags usage, quint32 size)

返回一个新的缓冲区，其中包含指定的type 、usage 和size 。

另请参见 QRhiResource::destroy()。

QRhiComputePipeline *QRhi::newComputePipeline()

返回一个新的计算管道资源。

另请参阅 QRhiResource::destroy()。

QRhiGraphicsPipeline *QRhi::newGraphicsPipeline()

返回一个新的图形管道资源。

另请参阅 QRhiResource::destroy()。

QRhiRenderBuffer *QRhi::newRenderBuffer(QRhiRenderBuffer::Type type, const QSize &pixelSize, int sampleCount = 1, QRhiRenderBuffer::Flags flags = {}, QRhiTexture::Format backingFormatHint = QRhiTexture::UnknownFormat)

返回一个新的渲染缓冲区，其type 、pixelSize 、sampleCount 和flags 均按指定值设置。

当backingFormatHint 设置为QRhiTexture::UnknownFormat 以外的纹理格式时，后端可能会根据该设置来决定渲染缓冲区的存储底层应采用何种格式。

另请参阅 QRhiResource::destroy()。

QRhiSampler *QRhi::newSampler(QRhiSampler::Filter magFilter, QRhiSampler::Filter minFilter, QRhiSampler::Filter mipmapMode, QRhiSampler::AddressMode addressU, QRhiSampler::AddressMode addressV, QRhiSampler::AddressMode addressW = QRhiSampler::Repeat)

返回一个新的采样器，其放大滤波器为magFilter ，缩小滤波器为minFilter ，MIP映射模式为mipmapMode ，以及寻址（环绕）模式为addressU 、addressV 和addressW 。

另请参阅 QRhiResource::destroy()。

QRhiShaderResourceBindings *QRhi::newShaderResourceBindings()

返回一个新的着色器资源绑定集合资源。

另请参阅 QRhiResource::destroy()。

[since 6.9] QRhiShadingRateMap *QRhi::newShadingRateMap()

返回一个新的着色率映射对象。

该函数在 Qt 6.9 中引入。

QRhiSwapChain *QRhi::newSwapChain()

返回一个新的交换链。

另请参阅 QRhiResource::destroy() 和QRhiSwapChain::createOrResize()。

QRhiTexture *QRhi::newTexture(QRhiTexture::Format format, const QSize &pixelSize, int sampleCount = 1, QRhiTexture::Flags flags = {})

返回一个新的 1D 或 2D 纹理，其format 、pixelSize 、sampleCount 和flags 均按指定值设置。

一维纹理必须在flags 中设置QRhiTexture::OneDimensional 。如果pixelSize 的高度为0，则该函数会隐式设置此标志。

另请参阅 QRhiResource::destroy()。

QRhiTexture *QRhi::newTexture(QRhiTexture::Format format, int width, int height, int depth, int sampleCount = 1, QRhiTexture::Flags flags = {})

返回一个新的 1D、2D 或 3D 纹理，其format 、width 、height 、depth 、sampleCount 和flags 均按指定值设置。

此重载适用于 3D 纹理，因为它允许指定depth 。3D 纹理必须在flags 中设置QRhiTexture::ThreeDimensional ，但使用此重载时可以省略该设置，因为只要depth 大于 0，该标志就会被隐式设置。对于 1D、2D 和立方体纹理，depth 应设置为 0。

一维纹理必须在flags 中设置QRhiTexture::OneDimensional 。如果height 和depth 均为0，此重载会隐式设置该标志。

QRhiTexture *QRhi::newTextureArray(QRhiTexture::Format format, int arraySize, const QSize &pixelSize, int sampleCount = 1, QRhiTexture::Flags flags = {})

返回一个新的 1D 或 2D 纹理数组，其format 、arraySize 、pixelSize 、sampleCount 和flags 均按指定值设置。

该函数会在flags 中隐式设置QRhiTexture::TextureArray 。

一维纹理数组必须在flags 中设置QRhiTexture::OneDimensional 。如果pixelSize 的高度为0，该函数将隐式设置此标志。

另请参阅 newTexture()。

QRhiTextureRenderTarget *QRhi::newTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc, QRhiTextureRenderTarget::Flags flags = {})

返回一个新的纹理渲染目标，其颜色和深度/模板附件由desc 中指定，并具有指定的flags 。

另请参阅 QRhiResource::destroy()。

QRhiResourceUpdateBatch *QRhi::nextResourceUpdateBatch()

返回一个可用的、空的批处理，可将各种操作记录到其中。

由于不与正在录制的帧绑定，因此例如以下代码序列是有效的：

rhi->beginFrame(swapchain);
QRhiResourceUpdateBatch *u = rhi->nextResourceUpdateBatch();
u->uploadStaticBuffer(buf, data);
// ... do not commit the batch
rhi->endFrame();
// u stays valid (assuming buf stays valid as well)
rhi->beginFrame(swapchain);
swapchain->currentFrameCommandBuffer()->resourceUpdate(u);
// ... draw with buf
rhi->endFrame();

QByteArray QRhi::pipelineCacheData()

返回一个二进制数据块，其中包含从QRhiGraphicsPipeline 和QRhiComputePipeline 收集的数据，这些缓存是在此QRhi 生命周期内成功创建的。

通过保存缓存数据，并在后续运行同一应用程序时重新加载，可能缩短管道和着色器的创建时间。缓存及其序列化版本的具体内容未作明确规定，始终取决于所使用的后端，在某些情况下还取决于图形 API 的具体实现。

当报告PipelineCacheDataLoadSave 不被支持时，返回的QByteArray 为空。

如果在调用create() 时未指定EnablePipelineCacheDataSave 标志，则返回的QByteArray 可能为空，即使支持PipelineCacheDataLoadSave 功能也是如此。

当返回的数据不为空时，它总是与 Qt 版本和QRhi 后端相关。 此外，在某些情况下，它还与图形设备以及所使用的确切驱动程序版本有着很强的依赖关系。QRhi 负责添加适当的头文件和保护措施，以确保数据总能安全地传递给setPipelineCacheData()，因此，尝试从其他版本的驱动程序运行中加载数据将得到安全且优雅的处理。

有关此功能的更多详细信息，请参阅EnablePipelineCacheDataSave 。

另请参阅 setPipelineCacheData()、create() 以及isFeatureSupported()。

[static] bool QRhi::probe(QRhi::Implementation impl, QRhiInitParams *params)

如果调用create() 时，预期在给定的impl 和params 下能够成功，则返回 true。

对于某些后端，这等同于调用create()，检查其返回值，然后销毁生成的QRhi 。

对于其他后端，特别是 Metal，可能会有特定的探测实现，这允许以更轻量级的方式进行测试，同时避免在失败时用警告污染调试输出。

另请参阅 create()。

void QRhi::releaseCachedResources()

尝试释放后端缓存中的资源。这可能包括 CPU 和 GPU 资源。 仅适用于可自动重建的内存和资源。例如，如果后端的QRhiGraphicsPipeline 实现维护了一个着色器编译结果缓存，调用此函数将清空该缓存，从而可能释放内存和图形资源。

在资源受限的环境中调用此函数是合理的，在这些环境中，有时需要以牺牲性能为代价来确保资源使用量降至最低。

void QRhi::removeCleanupCallback(const void *key)

使用 `key` 注销回调。如果未通过 `key` 注册清理回调，则该函数不执行任何操作。未使用键注册的回调无法被移除。

另请参阅 addCleanupCallback()。

int QRhi::resourceLimit(QRhi::ResourceLimit limit) const

返回指定资源limit 的值。

这些值通常会在后端初始化时被查询，因此调用此函数是一项轻量级操作。

void QRhi::setPipelineCacheData(const QByteArray &data)

在适用时，将data 加载到管道缓存中。

当PipelineCacheDataLoadSave 被报告为不受支持时，该函数仍可安全调用，但不会产生任何效果。

pipelineCacheData() 返回的 blob 总是与 Qt 版本、QRhi 后端以及（在某些情况下）图形设备和特定版本的图形驱动程序相关。QRhi 负责添加适当的头文件和保护措施，以确保数据总能安全地传递给此函数。 如果出现不匹配的情况（例如，由于驱动程序已升级到新版本，或者数据是由不同的QRhi 后端生成的），则会输出一个警告，并且可以安全地忽略data 。

在 Vulkan 中，这直接映射到 VkPipelineCache。调用此函数会创建一个新的 Vulkan 管道缓存对象，其初始数据来自data 。随后创建的所有QRhiGraphicsPipeline 和QRhiComputePipeline 对象都会使用该管道缓存对象，从而可能加速管道的创建。

其他 API 虽然没有真正的管道缓存，但可能会提供包含着色器编译生成的字节码（D3D）或程序二进制文件（OpenGL）的缓存。 在运行时需要大量从源代码进行着色器编译的应用程序中，如果通过此函数将“管道缓存”从之前的运行中预先填充，则可以在后续运行中显著提升性能。

有关此功能的更多详细信息，请参阅EnablePipelineCacheDataSave 。

另请参阅 pipelineCacheData() 和isFeatureSupported()。

[since 6.9] void QRhi::setQueueSubmitParams(QRhiNativeHandles *params)

结合后端和相应的图形 API，此函数允许在下次向图形命令队列提交命令时提供额外参数。

特别是在 Vulkan 环境中，这允许将一组 Vulkan 信号量对象作为参数传递给 `vkQueueSubmit() ` 函数，以便对其进行信号发送和等待。此时，`params ` 必须是一个 `QRhiVulkanQueueSubmitParams`。在某些高级用例中，这一点至关重要，例如在执行涉及等待和向 VkSemaphores 发送信号的原生 Vulkan 调用时，这些信号量由应用程序自定义的 Vulkan 渲染或计算代码进行管理。 此外，这还允许指定在下次调用 `vkQueuePresentKHR()` 时需要等待的其他信号量。

对于许多其他后端，此函数的实现为空操作。

该函数于 Qt 6.9 中引入。

[static] QSize QRhi::sizeForMipLevel(int mipLevel, const QSize &baseLevelSize)

返回给定mipLevel 的纹理图像大小，该大小基于baseLevelSize 中给出的第0级大小计算得出。

QRhiStats QRhi::statistics() const

收集并返回有关图形资源使用时长和分配情况的统计数据。

有关内存分配的数据仅在某些后端中可用，在这些后端中，此类操作由 Qt 控制。对于无法对资源内存分配进行底层控制的图形 API，此功能将永远不被支持，且结果中的所有相关字段均为 0。

特别是对于 Vulkan，这些值始终有效，且是从底层内存分配库中查询获得的。这有助于了解活动缓冲区和纹理的内存需求。

Direct 3D 12 也是如此。除了内存分配器库的统计数据外，此处的结果还包含一个 `totalUsageBytes ` 字段，该字段报告了包括 DXGI 报告的非内存分配器库控制的附加资源（如交换链缓冲区、描述符堆等）在内的总大小。

这些数值对应于所有已用内存类型的总和（即，对于独立显卡而言，包括显存和系统内存）。

大多数后端还提供其他数据，例如用于图形和计算管道创建的总时间（以毫秒为单位），该过程通常涉及着色器编译或缓存查找，以及可能较为耗时的处理。

QList<int> QRhi::supportedSampleCounts() const

返回支持的样本计数列表。

一个典型的示例是 (1, 2, 4, 8)。

在某些后端中，该支持值列表是预先确定的，而在另一些后端中，则由（物理）设备属性在运行时决定支持哪些值。

另请参阅 QRhiRenderBuffer::setSampleCount()、QRhiTexture::setSampleCount()、QRhiGraphicsPipeline::setSampleCount() 以及QRhiSwapChain::setSampleCount()。

[since 6.9] QList<QSize> QRhi::supportedShadingRates(int sampleCount) const

返回指定sampleCount 所支持的可变着色速率列表。

1x1始终受支持。

该函数自 Qt 6.9 起引入。

QThread *QRhi::thread() const

返回QRhi 被initialized 的那个线程。

int QRhi::ubufAligned(int v) const

返回值（通常为偏移量）v ，该值已根据ubufAlignment() 函数指定的统一缓冲区对齐方式进行对齐。

int QRhi::ubufAlignment() const

返回统一缓冲区偏移量的最小对齐值（以字节为单位）。该值通常为 256。

如果尝试绑定一个偏移量未对齐到此值的统一缓冲区区域，则根据后端和底层图形 API 的不同，可能会导致绑定失败。

另请参阅 ubufAligned()。

[static] QRhiSwapChainProxyData QRhi::updateSwapChainProxyData(QRhi::Implementation impl, QWindow *window)

生成并返回一个QRhiSwapChainProxyData 结构体，其中包含由impl 指定的后端和图形API特有的不透明数据。window 是swapchain所针对的QWindow 。

返回的结构体可传递给QRhiSwapChain::setProxyData()。这在多线程渲染系统中很有意义：与所有QRhi 操作不同，该静态函数应在线程（GUI）主线程上调用，随后将数据传递给处理QRhi 和QRhiSwapChain 的线程，并最终传递给交换链。 这使得可以执行仅在主线程上调用才安全的原生平台查询，例如从 NSView 查询 CAMetalLayer，然后将数据传递给位于渲染线程上的QRhiSwapChain 。 以 Metal 示例为例，在专用渲染线程上访问 view.layer 会导致 Xcode 线程检查器发出警告。借助数据代理机制，可以避免这种情况。

当不涉及线程时，无需生成和传递QRhiSwapChainProxyData ：后端保证能够自行查询所需的一切，而且如果所有内容都位于主（GUI）线程上，这应该就足够了。