En esta página

QRhiBuffer Class

Recurso de búfer de vértices, de índices o uniforme (constante). Más información...

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
Heredado de: QRhiResource

Tipos públicos

struct NativeBuffer
enum Type { Immutable, Static, Dynamic }
enum UsageFlag { VertexBuffer, IndexBuffer, UniformBuffer, StorageBuffer, IndirectBuffer }
flags UsageFlags

Funciones públicas

virtual char *beginFullDynamicBufferUpdateForCurrentFrame()
virtual bool create() = 0
virtual void endFullDynamicBufferUpdateForCurrentFrame()
virtual QRhiBuffer::NativeBuffer nativeBuffer()
void setSize(quint32 sz)
void setType(QRhiBuffer::Type t)
void setUsage(QRhiBuffer::UsageFlags u)
quint32 size() const
QRhiBuffer::Type type() const
QRhiBuffer::UsageFlags usage() const

Funciones públicas reimplementadas

virtual QRhiResource::Type resourceType() const override

Descripción detallada

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

Un QRhiBuffer encapsula cero, uno o más objetos de búfer nativos (como un VkBuffer o un MTLBuffer). Con algunas API gráficas y backends, es posible que ciertos tipos de búferes no utilicen en absoluto un objeto de búfer nativo (por ejemplo, OpenGL si no se utilizan objetos de búfer uniformes), pero esto resulta transparente para el usuario de la API de QRhiBuffer. Del mismo modo, el hecho de que algunos tipos de búferes puedan utilizar dos o tres búferes nativos en el fondo, con el fin de permitir una actualización eficiente del contenido por fotograma sin bloquear el flujo de trabajo de la GPU, resulta prácticamente invisible para las aplicaciones y las bibliotecas.

Una instancia de QRhiBuffer siempre se crea llamando a ` the QRhi's newBuffer() function`. Esto no crea ningún recurso gráfico nativo. Para ello, hay que llamar a ` create()` tras configurar las opciones adecuadas, como el tipo, los indicadores de uso y el tamaño, aunque en la mayoría de los casos estas ya están configuradas en función de los argumentos pasados a ` newBuffer()`.

Ejemplo de uso

Para crear un búfer de uniformes para un shader en el que el bloque de uniformes GLSL contenga un único miembro ` mat4 `, y actualizar su contenido:

QRhiBuffer *ubuf = rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, 64);
if (!ubuf->create()) { error(); }
QRhiResourceUpdateBatch *batch = rhi->nextResourceUpdateBatch();
QMatrix4x4 mvp;
// ... set up the modelview-projection matrix
batch->updateDynamicBuffer(ubuf, 0, 64, mvp.constData());
// ...
commandBuffer->resourceUpdate(batch); // or, alternatively, pass 'batch' to a beginPass() call

Un ejemplo de creación de un búfer con datos de vértices:

const float vertices[] = { -1.0f, -1.0f, 1.0f, -1.0f, 0.0f, 1.0f };
QRhiBuffer *vbuf = rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertices));
if (!vbuf->create()) { error(); }
QRhiResourceUpdateBatch *batch = rhi->nextResourceUpdateBatch();
batch->uploadStaticBuffer(vbuf, vertices);
// ...
commandBuffer->resourceUpdate(batch); // or, alternatively, pass 'batch' to a beginPass() call

Un búfer de índices:

static const quint16 indices[] = { 0, 1, 2 };
QRhiBuffer *ibuf = rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::IndexBuffer, sizeof(indices));
if (!ibuf->create()) { error(); }
QRhiResourceUpdateBatch *batch = rhi->nextResourceUpdateBatch();
batch->uploadStaticBuffer(ibuf, indices);
// ...
commandBuffer->resourceUpdate(batch); // or, alternatively, pass 'batch' to a beginPass() call

Patrones comunes

Una llamada a ` create()` destruye cualquier recurso nativo existente si previamente se ha llamado con éxito a ` create()`. Si esos recursos nativos siguen siendo utilizados por un fotograma en proceso (es decir, existe la posibilidad de que la GPU aún los esté leyendo), la destrucción de dichos recursos se aplaza automáticamente. Por lo tanto, un patrón muy común y práctico para aumentar de forma segura el tamaño de un búfer ya inicializado es el siguiente. En la práctica, esto elimina y crea un conjunto completamente nuevo de recursos nativos subyacentes, por lo que no es necesariamente una operación económica, pero resulta más conveniente y aún más rápida que las alternativas, ya que al no destruir el propio objeto ` buf `, todas las referencias al mismo siguen siendo válidas en otras estructuras de datos (por ejemplo, en cualquier ` QRhiShaderResourceBinding ` desde el que se haga referencia al `QRhiBuffer`).

if (buf->size() < newSize) {
    buf->setSize(newSize);
    if (!buf->create()) { error(); }
}
// continue using buf, fill it with new data

Al trabajar con búferes uniformes, a veces será necesario combinar los datos de varias llamadas de dibujo en un único búfer por motivos de eficiencia. Ten en cuenta los requisitos de alineación: con algunas API gráficas, los desplazamientos de un búfer uniforme deben estar alineados a 256 bytes. Esto se aplica tanto a QRhiShaderResourceBinding como a los desplazamientos dinámicos pasados a setShaderResources(). Utiliza las funciones ` ubufAlignment()` y ` ubufAligned()` para crear código portátil. A modo de ejemplo, a continuación se muestra un esquema para emitir múltiples llamadas de dibujo (`N`) con el mismo pipeline y la misma geometría, pero con datos diferentes en los búferes uniformes expuestos en el punto de enlace 0. Esto supone que el búfer se expone mediante ` uniformBufferWithDynamicOffset()`, lo que permite pasar una lista ` QRhiCommandBuffer::DynamicOffset ` a ` setShaderResources()`.

const int N = 2;
const int UB_SIZE = 64 + 4; // assuming a uniform block with { mat4 matrix; float opacity; }
const int ONE_UBUF_SIZE = rhi->ubufAligned(UB_SIZE);
const int TOTAL_UBUF_SIZE = N * ONE_UBUF_SIZE;
QRhiBuffer *ubuf = rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, TOTAL_UBUF_SIZE);
if (!ubuf->create()) { error(); }
QRhiResourceUpdateBatch *batch = rhi->nextResourceUpdateBatch();
for (int i = 0; i < N; ++i) {
    batch->updateDynamicBuffer(ubuf, i * ONE_UBUF_SIZE, 64, matrix.constData());
    batch->updateDynamicBuffer(ubuf, i * ONE_UBUF_SIZE + 64, 4, &opacity);
}
// ...
// beginPass(), set pipeline, etc., and then:
for (int i = 0; i < N; ++i) {
    QRhiCommandBuffer::DynamicOffset dynOfs[] = { { 0, i * ONE_UBUF_SIZE } };
    cb->setShaderResources(srb, 1, dynOfs);
    cb->draw(36);
}

Véase también QRhiResourceUpdateBatch, QRhi y QRhiCommandBuffer.

Documentación sobre los tipos de miembros

enum QRhiBuffer::Type

Especifica el tipo de almacenamiento del recurso de búfer.

ConstanteValorDescripción
QRhiBuffer::Immutable0Indica que no se espera que los datos cambien nunca tras la carga inicial. En realidad, estos recursos de búfer suelen ubicarse en la memoria local del dispositivo (GPU) (en los sistemas en los que sea aplicable). Es posible cargar nuevos datos, pero puede resultar costoso. La carga se realiza normalmente copiando los datos a un búfer intermedio independiente y visible para el host, desde el cual se lleva a cabo una copia de búfer a búfer de la GPU al búfer propio de la GPU.
QRhiBuffer::Static1Indica que se espera que los datos cambien solo de forma esporádica. Normalmente se almacenan en la memoria local del dispositivo (GPU), cuando sea aplicable. En los backends en los que se utilizan búferes intermedios visibles para el host para la carga, estos búferes se mantienen activos para este tipo, a diferencia de lo que ocurre con «Immutable», de modo que las cargas posteriores no se ven afectadas en cuanto al rendimiento. Deben evitarse las actualizaciones frecuentes, especialmente las actualizaciones en fotogramas consecutivos.
QRhiBuffer::Dynamic2Indica que se espera que los datos cambien con frecuencia. No se recomienda para búferes de gran tamaño. Normalmente se respalda con memoria visible para el host en dos copias, con el fin de permitir cambios sin bloquear la canalización de gráficos. El doble búfer se gestiona de forma transparente para las aplicaciones y no se expone en la API aquí de ninguna forma. Este es el tipo recomendado y, con algunos backends, el único posible, para búferes con uso de « UniformBuffer ».

enum QRhiBuffer::UsageFlag
flags QRhiBuffer::UsageFlags

Valores de indicador para especificar cómo se va a utilizar el búfer.

ConstanteValorDescripción
QRhiBuffer::VertexBuffer1 << 0Búfer de vértices. Esto permite utilizar el QRhiBuffer en setVertexInput().
QRhiBuffer::IndexBuffer1 << 1Búfer de índices. Permite utilizar el « QRhiBuffer » en la función ` setVertexInput()`.
QRhiBuffer::UniformBuffer1 << 2Búfer uniforme (también denominado búfer constante). Permite utilizar la función « QRhiBuffer » en combinación con « UniformBuffer ». Cuando se indica que « NonDynamicUniformBuffers » no es compatible, este uso solo puede combinarse con el tipo «Dynamic».
QRhiBuffer::StorageBuffer1 << 3Búfer de almacenamiento. Permite utilizar el ` QRhiBuffer ` en combinación con ` BufferLoad`, ` BufferStore` o ` BufferLoadStore`. Este uso solo puede combinarse con los tipos `Immutable` o `Static`, y solo está disponible cuando se indica que el ` Compute feature ` es compatible.
QRhiBuffer::IndirectBuffer (since Qt 6.12)1 << 4Búfer de dibujo indirecto. Esto permite utilizar el ` QRhiBuffer ` en ` drawIndirect()` y ` drawIndexedIndirect()`. Este uso puede combinarse con los tipos «Immutable» o «Static». No se admite su combinación con «Dynamic» en D3D11, donde ` create()` dará error. Este uso también puede combinarse con `StorageBuffer` en backends que admitan ` compute shaders`, lo que permite que los shaders de cálculo generen comandos de dibujo indirecto y que estos sean utilizados por llamadas de dibujo indirectas.

El tipo «UsageFlags» es un «typedef» para «QFlags<UsageFlag>». Almacena una combinación OR de valores de «UsageFlag».

Documentación de las funciones miembro

[virtual] char *QRhiBuffer::beginFullDynamicBufferUpdateForCurrentFrame()

Devuelve un puntero a un bloque de memoria con los datos del búfer visible del host.

Se trata de un atajo para búferes uniformes dinámicos de tamaño medio a grande cuyo contenido completo (o al menos todas las regiones leídas por los sombreadores en el fotograma actual) cambia en cada fotograma y en los que el mecanismo de actualización basado en ` QRhiResourceUpdateBatch` resulta demasiado pesado debido a la cantidad de datos que hay que copiar.

La llamada a esta función debe ir seguida, en última instancia, de una llamada a `endFullDynamicUniformBufferUpdateForCurrentFrame()`, antes de registrar cualquier pasada de renderizado o cálculo que dependa de este búfer.

Advertencia: La actualización de datos mediante este método no es compatible con las actualizaciones y lecturas posteriores basadas en ` QRhiResourceUpdateBatch`. Pueden producirse comportamientos inesperados al intentar combinar los dos modelos de actualización para el mismo búfer. Del mismo modo, es posible que los datos actualizados de esta forma directa no sean visibles para ` readBackBuffer operations`, dependiendo del backend.

Advertencia: Al actualizar los datos del búfer mediante este método, la actualización debe realizarse en cada fotograma; de lo contrario, los backends que realizan un búfer doble o triple de los recursos pueden presentar un comportamiento inesperado.

Advertencia: Con este enfoque no es posible realizar actualizacionesparciales , ya que algunos backends pueden optar por una estrategia en la que el contenido anterior del búfer se pierda al llamar a esta función. Los datos deben escribirse en todas las regiones que lean los shaders en el fotograma que se está preparando actualmente.

Advertencia: Esta función solo se puede llamar al grabar un fotograma, es decir, entre QRhi::beginFrame() y QRhi::endFrame().

Advertencia: Esta función solo se puede invocar en búferes dinámicos.

[pure virtual] bool QRhiBuffer::create()

Crea los recursos gráficos nativos correspondientes. Si ya existen recursos debido a una llamada anterior a `create()` sin el correspondiente ` destroy()`, entonces se llama primero de forma implícita a ` destroy()`.

Devuelve ` true ` si se realiza correctamente, y ` false ` si falla alguna operación gráfica. Independientemente del valor devuelto, llamar a ` destroy()` siempre es seguro.

[virtual] void QRhiBuffer::endFullDynamicBufferUpdateForCurrentFrame()

Se invocará cuando se haya actualizado todo el contenido de los datos del búfer en el bloque de memoria devuelto por la función ` beginFullDynamicBufferUpdateForCurrentFrame()`.

[virtual] QRhiBuffer::NativeBuffer QRhiBuffer::nativeBuffer()

Devuelve los recursos nativos subyacentes de este búfer. El valor devuelto estará vacío si el backend no admite la exposición de los recursos nativos subyacentes.

Un objeto « QRhiBuffer » puede estar respaldado por varios objetos de búfer nativos, dependiendo de las funciones ` type()` y del backend ` QRhi ` que se utilice. Cuando esto ocurre, todos ellos se devuelven en la matriz `objects` de la estructura devuelta, y `slotCount` especifica el número de objetos de búfer nativos. Si bien se puede utilizar ` recording a frame` y ` QRhi::currentFrameSlot()` para determinar cuáles de los búferes nativos está utilizando ` QRhi ` para las operaciones de lectura o escritura en este ` QRhiBuffer ` dentro del fotograma que se está grabando.

En algunos casos, un ` QRhiBuffer ` no estará respaldado por ningún objeto de búfer nativo. En este caso, `slotCount` se establecerá en 0 y no se devolverán objetos nativos válidos. Esto no es un error y es perfectamente válido cuando un backend determinado no utiliza búferes nativos para `QRhiBuffers` con ciertos tipos o usos.

Nota: Ten en cuenta que los backends de QRhi pueden emplear diversas estrategias de actualización de búferes. A diferencia de las texturas, en las que la carga de datos de imagen siempre implica registrar un comando de copia de búfer a imagen (o similar) en el búfer de comandos, los búferes —en particular los de tipo «Dynamic» y « UniformBuffer »— pueden funcionar de muchas maneras diferentes. Por ejemplo, un « QRhiBuffer » con tipo de uso « UniformBuffer » puede que ni siquiera esté respaldado por un objeto de búfer nativo si un backend y una API gráfica determinados no utilizan o no admiten búferes uniformes. También existen diferencias en cuanto a cómo se escriben los datos en el búfer y al tipo de memoria de respaldo utilizada. En el caso de los búferes respaldados por memoria visible para el host, la llamada a esta función garantiza que se ejecuten las escrituras pendientes del host para todos los búferes nativos devueltos.

Véanse también QRhi::currentFrameSlot() y QRhi::FramesInFlight.

[override virtual] QRhiResource::Type QRhiBuffer::resourceType() const

Reimplementa: ` QRhiResource::resourceType()` const.

Devuelve el tipo de recurso.

void QRhiBuffer::setSize(quint32 sz)

Establece el tamaño del búfer en bytes. Normalmente, el tamaño se especifica en ` QRhi::newBuffer()`, por lo que esta función solo se utiliza cuando es necesario modificar el tamaño. Al igual que ocurre con otros métodos de configuración, el tamaño solo surte efecto al llamar a ` create()`, y en el caso de los búferes ya creados, esto implica liberar el recurso nativo anterior y crear otros nuevos de forma interna.

Los backends pueden optar por asignar búferes de mayor tamaño que el especificado en ` sz ` para cumplir los requisitos de alineación. Esto queda oculto a las aplicaciones y ` size()` siempre indicará el tamaño solicitado en ` sz`.

Véase también size().

void QRhiBuffer::setType(QRhiBuffer::Type t)

Establece el tipo del búfer como « t ».

Véase también ` type()`.

void QRhiBuffer::setUsage(QRhiBuffer::UsageFlags u)

Establece los indicadores de uso del búfer en « u ».

Véase también usage().

quint32 QRhiBuffer::size() const

Devuelve el tamaño del búfer en bytes.

Este valor es siempre el que se pasó a setSize() o QRhi::newBuffer(). Internamente, los búferes nativos pueden ser más grandes si así lo requiere la API gráfica subyacente.

Véase también setSize().

QRhiBuffer::Type QRhiBuffer::type() const

Devuelve el tipo de búfer.

Véase también setType().

QRhiBuffer::UsageFlags QRhiBuffer::usage() const

Devuelve los indicadores de uso del búfer.

Véase también setUsage().

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