En esta página

QRhiResourceUpdateBatch Class

Operaciones de carga y copia de registros. Más...

Encabezado: #include <rhi/qrhi.h>
CMake: find_package(Qt6 REQUIRED COMPONENTS GuiPrivate)
target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate)
qmake: QT += gui-private
Desde: Qt 6.6

Funciones públicas

void copyTexture(QRhiTexture *dst, QRhiTexture *src, const QRhiTextureCopyDescription &desc = QRhiTextureCopyDescription())
void generateMips(QRhiTexture *tex)
bool hasOptimalCapacity() const
void merge(QRhiResourceUpdateBatch *other)
void readBackBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, QRhiReadbackResult *result)
void readBackTexture(const QRhiReadbackDescription &rb, QRhiReadbackResult *result)
void release()
void updateDynamicBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)
(since 6.10) void updateDynamicBuffer(QRhiBuffer *buf, quint32 offset, QByteArray data)
void uploadStaticBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)
(since 6.10) void uploadStaticBuffer(QRhiBuffer *buf, QByteArray data)
void uploadStaticBuffer(QRhiBuffer *buf, const void *data)
(since 6.10) void uploadStaticBuffer(QRhiBuffer *buf, quint32 offset, QByteArray data)
void uploadTexture(QRhiTexture *tex, const QImage &image)
void uploadTexture(QRhiTexture *tex, const QRhiTextureUploadDescription &desc)

Descripción detallada

Con « QRhi », ya no es posible realizar operaciones de tipo «copia» en momentos arbitrarios. En su lugar, todas estas operaciones se registran en lotes que, posteriormente, se pasan, por lo general, a ` QRhiCommandBuffer::beginPass()`. Lo que ocurre entonces «entre bastidores» queda oculto para la aplicación: las implementaciones subyacentes pueden aplazar e implementar estas operaciones de diversas formas.

Un lote de actualización de recursos no posee recursos gráficos y no realiza ninguna operación real por sí mismo. Más bien debe considerarse como un búfer de comandos para comandos de actualización, carga y copia.

Para obtener un lote disponible y vacío del grupo, llama a QRhi::nextResourceUpdateBatch().

Nota: Se trata de una API de RHI con garantías de compatibilidad limitadas; consulta QRhi para obtener más detalles.

Documentación de las funciones miembro

void QRhiResourceUpdateBatch::copyTexture(QRhiTexture *dst, QRhiTexture *src, const QRhiTextureCopyDescription &desc = QRhiTextureCopyDescription())

Pone en cola una operación de copia de textura a textura desde src a dst, tal y como se describe en desc.

Nota: La textura de origen src debe crearse con QRhiTexture::UsedAsTransferSource.

Nota: El formato de las texturas debe coincidir. Con la mayoría de las API gráficas, los datos se copian tal cual, sin conversiones de formato. Si dst y src se crean con formatos diferentes, pueden surgir problemas no especificados.

void QRhiResourceUpdateBatch::generateMips(QRhiTexture *tex)

Pone en cola una operación de generación de mipmaps para la textura especificada tex.

Se admiten texturas 2D y cúbicas. Las texturas 1D y 3D se admiten cuando la función QRhi::OneDimensionalTextureMipmaps o QRhi::ThreeDimensionalTextureMipmaps se indica como compatible, respectivamente.

Nota: La textura debe crearse con las opciones QRhiTexture::MipMapped y QRhiTexture::UsedWithGenerateMips.

Advertencia: « QRhi » no puede garantizar que se puedan generar mipmaps para todos los formatos de textura compatibles. Por ejemplo, « QRhiTexture::RGBA32F » no es un formato « filterable » en OpenGL ES 3.0 y Metal en iOS, por lo que la solicitud de generación de mipmaps podría fallar. RGBA8 y RGBA16F suelen ser filtrables, por lo que se recomienda utilizar estos formatos cuando se desee generar mipmaps.

bool QRhiResourceUpdateBatch::hasOptimalCapacity() const

Devuelve «true» hasta que el número de operaciones de búfer y textura en cola en este lote sea inferior a un límite razonable.

El valor devuelto es «false» cuando el número de operaciones de búfer y/o textura añadidas a este lote ha alcanzado, o está a punto de alcanzar, un límite determinado. El lote sigue siendo totalmente funcional a partir de ese momento, pero es posible que necesite asignar memoria adicional. Por lo tanto, un renderizador que recopile muchas actualizaciones de búferes y texturas en un único lote al preparar un fotograma debería considerar submitting the batch y starting a new one cuando esta función devuelva «false».

void QRhiResourceUpdateBatch::merge(QRhiResourceUpdateBatch *other)

Copia todas las operaciones en cola del lote « other » a este.

Nota: Es posible que« other » ya no contenga datos válidos tras la operación de fusión, por lo que no debe enviarse; no obstante, seguirá siendo necesario liberarlo llamando a « release()».

Esto permite un patrón práctico en el que las actualizaciones de recursos que ya se conocen durante la fase de inicialización se recopilan en un lote que, posteriormente, se fusiona con otro al iniciar la primera pasada de renderizado:

void init()
{
    initialUpdates = rhi->nextResourceUpdateBatch();
    initialUpdates->uploadStaticBuffer(vbuf, vertexData);
    initialUpdates->uploadStaticBuffer(ibuf, indexData);
    // ...
}

void render()
{
    QRhiResourceUpdateBatch *resUpdates = rhi->nextResourceUpdateBatch();
    if (initialUpdates) {
        resUpdates->merge(initialUpdates);
        initialUpdates->release();
        initialUpdates = nullptr;
    }
    // resUpdates->updateDynamicBuffer(...);
    cb->beginPass(rt, clearCol, clearDs, resUpdates);
}

void QRhiResourceUpdateBatch::readBackBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, QRhiReadbackResult *result)

Pone en cola la lectura de una región de QRhiBuffer buf . El tamaño de la región se especifica mediante size en bytes, mientras que offset es el desplazamiento en bytes desde el que se iniciará la lectura.

La relectura es asíncrona. result contiene una función de devolución de llamada que se invoca cuando la operación ha finalizado. Los datos se proporcionan en QRhiReadbackResult::data. Si la operación se completa con éxito, QByteArray tendrá un tamaño igual a size. En caso de fallo, QByteArray estará vacío.

Nota: La lectura de búferes con un uso distinto al de QRhiBuffer::UniformBuffer solo se admite cuando la función QRhi::ReadBackNonUniformBuffer se indica como compatible.

Nota: Se garantiza quela relectura asíncrona se ha completado cuando se cumple una de las siguientes condiciones: se ha llamado a finish(); o se han submitted al menos N tramas, incluida la trama que inició la operación de relectura, y se ha iniciado el recording of a new frame, donde N es el resource limit value devuelto por QRhi::MaxAsyncReadbackFrames.

Véase también readBackTexture(), QRhi::isFeatureSupported() y QRhi::resourceLimit().

void QRhiResourceUpdateBatch::readBackTexture(const QRhiReadbackDescription &rb, QRhiReadbackResult *result)

Pone en cola una operación de copia de textura al host tal y como se describe en rb.

Normalmente, rb especificará un ` QRhiTexture ` como origen. Sin embargo, cuando la cadena de intercambio (swapchain) del fotograma actual se haya creado con QRhiSwapChain::UsedAsTransferSource, también puede ser el origen de la lectura posterior. Para ello, deja la textura establecida en `null` en rb.

A diferencia de otras operaciones, aquí los resultados deben ser procesados por la aplicación. Por lo tanto, ` result ` no solo proporciona los datos, sino también una llamada de retorno, ya que las operaciones sobre el lote son asíncronas por naturaleza:

rhi->beginFrame(swapchain);
cb->beginPass(swapchain->currentFrameRenderTarget(), colorClear, dsClear);
// ...
QRhiReadbackResult *rbResult = new QRhiReadbackResult;
rbResult->completed = [rbResult] {
    {
        const QImage::Format fmt = QImage::Format_RGBA8888_Premultiplied; // fits QRhiTexture::RGBA8
        const uchar *p = reinterpret_cast<const uchar *>(rbResult->data.constData());
        QImage image(p, rbResult->pixelSize.width(), rbResult->pixelSize.height(), fmt);
        image.save("result.png");
    }
    delete rbResult;
};
QRhiResourceUpdateBatch *u = nextResourceUpdateBatch();
QRhiReadbackDescription rb; // no texture -> uses the current backbuffer of sc
u->readBackTexture(rb, rbResult);
cb->endPass(u);
rhi->endFrame(swapchain);

Nota: La textura debe crearse con QRhiTexture::UsedAsTransferSource.

Nota: Las texturasmultisample no se pueden volver a leer.

Nota: La lectura devuelve datos en bytes sin procesar, para que las aplicaciones puedan interpretarlos como mejor les parezca. Ten en cuenta la configuración de mezcla del código de renderizado: si la mezcla está configurada para basarse en alfa premultiplicado, los resultados de la lectura también deben interpretarse como premultiplicados.

Nota: Al interpretar los datos sin procesar resultantes, ten en cuenta que la lectura se realiza con un formato de orden de bytes. Por lo tanto, una textura « RGBA8 » se corresponde con formatos de orden de bytes QImage, como, por ejemplo, QImage::Format_RGBA8888.

Nota: Se garantiza quela lectura asíncrona habrá finalizado cuando se cumpla una de las siguientes condiciones: se haya llamado a finish(); o se hayan submitted al menos N fotogramas, incluido el fotograma que inició la operación de lectura, y se haya iniciado el recording of a new frame, donde N es el resource limit value devuelto por QRhi::MaxAsyncReadbackFrames.

Una única operación de lectura copia un nivel mip de una capa (cara de cubemap, sección 3D o elemento de matriz de texturas) cada vez. El nivel y la capa se especifican mediante los campos correspondientes en rb.

Véanse también readBackBuffer() y QRhi::resourceLimit().

void QRhiResourceUpdateBatch::release()

Devuelve el lote al grupo. Esto solo debe utilizarse cuando el lote no se pase a una de las funciones QRhiCommandBuffer::beginPass(), QRhiCommandBuffer::endPass() o QRhiCommandBuffer::resourceUpdate(), ya que estas llaman implícitamente a destroy().

Nota: Las aplicaciones nunca deben deleted las instancias deQRhiResourceUpdateBatch.

void QRhiResourceUpdateBatch::updateDynamicBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)

Pone en cola la actualización de una región de un QRhiBuffer buf creado con el tipo QRhiBuffer::Dynamic.

La región se especifica mediante offset y size. Los bytes reales que se van a escribir se especifican mediante data, que debe tener al menos size bytes disponibles.

data se copia y puede destruirse o modificarse de forma segura una vez que esta función devuelva un resultado.

Nota: Si hay escrituras del host implicadas —lo cual suele ocurrir con updateDynamicBuffer(), ya que, en la mayoría de los backends, dichos búferes están respaldados por memoria visible para el host—, estas pueden acumularse dentro de un fotograma. Por lo tanto, una pasada 1 que lea una región modificada por un lote pasado a la pasada 2 puede ver los cambios especificados en el lote de actualización de la pasada 2.

Nota: QRhi gestiona de forma transparente el doble búfer para evitar el bloqueo de la canalización gráfica. El hecho de que un objeto « QRhiBuffer » pueda tener varios objetos de búfer nativos subyacentes puede ignorarse con total seguridad al utilizar QRhi y QRhiResourceUpdateBatch.

[since 6.10] void QRhiResourceUpdateBatch::updateDynamicBuffer(QRhiBuffer *buf, quint32 offset, QByteArray data)

Pone en cola la actualización de una región de un objeto ` QRhiBuffer ` buf creado con el tipo ` QRhiBuffer::Dynamic`.

data se traslada al lote en lugar de copiarse con esta sobrecarga.

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.10.

void QRhiResourceUpdateBatch::uploadStaticBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)

Pone en cola la actualización de una región de un QRhiBuffer buf creado con el tipo QRhiBuffer::Immutable o QRhiBuffer::Static.

La región se especifica mediante offset y size. Los bytes reales que se van a escribir se especifican mediante data, que debe tener al menos size bytes disponibles.

data se copia y puede eliminarse o modificarse sin problema una vez que esta función devuelva un resultado.

[since 6.10] void QRhiResourceUpdateBatch::uploadStaticBuffer(QRhiBuffer *buf, QByteArray data)

Con esta sobrecarga, la actualización de todo el objeto ` QRhiBuffer ` buf creado con el tipo ` QRhiBuffer::Immutable ` o ` QRhiBuffer::Static` se añade a la cola

data Con esta sobrecarga, se traslada al lote en lugar de copiarse.

data size debe ser igual al tamaño de buf.

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.10.

void QRhiResourceUpdateBatch::uploadStaticBuffer(QRhiBuffer *buf, const void *data)

Pone en cola la actualización de todo el QRhiBuffer buf creado con el tipo QRhiBuffer::Immutable o QRhiBuffer::Static.

Esta es una función sobrecargada.

[since 6.10] void QRhiResourceUpdateBatch::uploadStaticBuffer(QRhiBuffer *buf, quint32 offset, QByteArray data)

Pone en cola la actualización de una región de un objeto ` QRhiBuffer ` buf creado con el tipo ` QRhiBuffer::Immutable ` o ` QRhiBuffer::Static`.

data Se traslada al lote en lugar de copiarse con esta sobrecarga.

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.10.

void QRhiResourceUpdateBatch::uploadTexture(QRhiTexture *tex, const QImage &image)

Pone en cola la carga de los datos de imagen para el nivel mip 0 de la capa 0 de la textura tex.

tex Debe tener un formato sin comprimir. Su formato también debe ser compatible con la función QImage::format() de image. Los datos de origen se proporcionan en image.

void QRhiResourceUpdateBatch::uploadTexture(QRhiTexture *tex, const QRhiTextureUploadDescription &desc)

Pone en cola la carga de los datos de imagen para uno o más niveles MIP en una o más capas de la textura tex.

Los detalles de la copia ( QImage de origen o datos de textura comprimidos, regiones, capas de destino y niveles) se describen en desc.

© 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.