QRhiCommandBuffer Class
Recurso del búfer de comandos. 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 |
| Heredan de: | QRhiResource |
Tipos públicos
| enum | BeginPassFlag { ExternalContent, DoNotTrackResourcesForCompute } |
| flags | BeginPassFlags |
| DynamicOffset | |
| enum | IndexFormat { IndexUInt16, IndexUInt32 } |
| VertexInput |
Funciones públicas
| void | beginComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr, QRhiCommandBuffer::BeginPassFlags flags = {}) |
| void | beginExternal() |
| void | beginPass(QRhiRenderTarget *rt, const QColor &colorClearValue, const QRhiDepthStencilClearValue &depthStencilClearValue, QRhiResourceUpdateBatch *resourceUpdates = nullptr, QRhiCommandBuffer::BeginPassFlags flags = {}) |
| void | debugMarkBegin(const QByteArray &name) |
| void | debugMarkEnd() |
| void | debugMarkMsg(const QByteArray &msg) |
| void | dispatch(int x, int y, int z) |
| void | draw(quint32 vertexCount, quint32 instanceCount = 1, quint32 firstVertex = 0, quint32 firstInstance = 0) |
| void | drawIndexed(quint32 indexCount, quint32 instanceCount = 1, quint32 firstIndex = 0, qint32 vertexOffset = 0, quint32 firstInstance = 0) |
(since 6.12) void | drawIndexedIndirect(QRhiBuffer *indirectBuffer, quint32 indirectBufferOffset, quint32 drawCount, quint32 stride = sizeof(QRhiIndexedIndirectDrawCommand)) |
(since 6.12) void | drawIndirect(QRhiBuffer *indirectBuffer, quint32 indirectBufferOffset, quint32 drawCount, quint32 stride = sizeof(QRhiIndirectDrawCommand)) |
| void | endComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr) |
| void | endExternal() |
| void | endPass(QRhiResourceUpdateBatch *resourceUpdates = nullptr) |
| double | lastCompletedGpuTime() |
| const QRhiNativeHandles * | nativeHandles() |
| void | resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates) |
| void | setBlendConstants(const QColor &c) |
| void | setComputePipeline(QRhiComputePipeline *ps) |
| void | setGraphicsPipeline(QRhiGraphicsPipeline *ps) |
| void | setScissor(const QRhiScissor &scissor) |
| void | setShaderResources(QRhiShaderResourceBindings *srb = nullptr, int dynamicOffsetCount = 0, const QRhiCommandBuffer::DynamicOffset *dynamicOffsets = nullptr) |
(since 6.9) void | setShadingRate(const QSize &coarsePixelSize) |
| void | setStencilRef(quint32 refValue) |
| void | setVertexInput(int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings, QRhiBuffer *indexBuf = nullptr, quint32 indexOffset = 0, QRhiCommandBuffer::IndexFormat indexFormat = IndexUInt16) |
| void | setViewport(const QRhiViewport &viewport) |
Funciones públicas reimplementadas
| virtual QRhiResource::Type | resourceType() const override |
Descripción detallada
Por el momento, las aplicaciones no pueden crearlo. Las únicas formas de obtener un QRhiCommandBuffer válido son obtenerlo de la cadena de intercambio de destino mediante QRhiSwapChain::currentFrameCommandBuffer() o, en caso de renderizado completamente fuera de pantalla, inicializar uno mediante QRhi::beginOffscreenFrame().
Nota: Se trata de una API RHI con garantías de compatibilidad limitadas; consulta QRhi para obtener más detalles.
Documentación sobre los tipos de miembros
enum QRhiCommandBuffer::BeginPassFlag
flags QRhiCommandBuffer::BeginPassFlags
Valores de los indicadores para QRhi::beginPass()
| Constante | Valor | Descripción |
|---|---|---|
QRhiCommandBuffer::ExternalContent | 0x01 | Especifica que se realizará una llamada a ` QRhiCommandBuffer::beginExternal()` en esta pasada. Algunos backends, en particular Vulkan, fallarán si no se establece este indicador y aún así se llama a ` beginExternal()`. |
QRhiCommandBuffer::DoNotTrackResourcesForCompute | 0x02 | Especifica que no es necesario realizar un seguimiento de los recursos utilizados en esta pasada si el único propósito de dicho seguimiento es generar barreras para el cálculo. Implica que no hay pasadas de cálculo en el fotograma. Se trata de una sugerencia de optimización que pueden tener en cuenta ciertos backends, en particular OpenGL, lo que les permite omitir determinadas operaciones. Cuando se activa este indicador para una pasada de renderizado en un fotograma, llamar a beginComputePass() en ese fotograma puede provocar un comportamiento inesperado, dependiendo de las dependencias de recursos entre las pasadas de renderizado y de cálculo. |
El tipo `BeginPassFlags` es un `typedef` para ` QFlags<BeginPassFlag>`. Almacena una combinación OR de valores de `BeginPassFlag`.
[alias] QRhiCommandBuffer::DynamicOffset
Sinónimo de std::pair<int, quint32>. La primera entrada es la vinculación y la segunda, el desplazamiento en el búfer.
enum QRhiCommandBuffer::IndexFormat
Especifica el tipo de datos del índice
| Constante | Valor | Descripción |
|---|---|---|
QRhiCommandBuffer::IndexUInt16 | 0 | 16 bits sin signo (quint16) |
QRhiCommandBuffer::IndexUInt32 | 1 | 32 bits sin signo (quint32) |
[alias] QRhiCommandBuffer::VertexInput
Sinónimo de std::pair<QRhiBuffer *, quint32>. La segunda entrada es una posición en el búfer especificado por la primera.
Documentación de las funciones miembro
void QRhiCommandBuffer::beginComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr, QRhiCommandBuffer::BeginPassFlags flags = {})
Registra el inicio de una nueva pasada de cálculo.
resourceUpdates, cuando no es nulo, especifica un lote de actualizaciones de recursos que se va a confirmar y, a continuación, liberar.
Nota: Nose debe dar por sentado que el estado o los enlaces a recursos persistan entre pasadas.
Nota: Una pasada de cálculo puede registrar llamadas a setComputePipeline(), setShaderResources() y dispatch(), pero no llamadas gráficas. La funcionalidad general, como los marcadores de depuración y beginExternal(), está disponible tanto en las pasadas de renderizado como en las de cálculo.
Nota: La computación solo está disponible cuando se indica que la función Compute es compatible.
flags Actualmente no se utiliza.
void QRhiCommandBuffer::beginExternal()
Se invoca cuando la aplicación anterior a la actual está a punto de poner en cola comandos en el búfer de comandos de la pasada actual mediante la llamada directa a funciones de la API gráfica.
Nota: Esto solo está disponible cuando la intención se ha declarado previamente en ` beginPass()` o ` beginComputePass()`. Por lo tanto, esta función solo debe llamarse cuando la grabación de la pasada se haya iniciado especificando ` QRhiCommandBuffer::ExternalContent`.
Con Vulkan, Metal o Direct3D 12, se puede consultar el búfer de comandos nativo o los objetos codificadores mediante ` nativeHandles()` y poner comandos en cola en ellos. Con OpenGL o Direct3D 11, el contexto (del dispositivo) se puede recuperar mediante ` QRhi::nativeHandles()`. Sin embargo, esto nunca debe hacerse sin asegurarse de que el estado de QRhiCommandBuffer se mantenga actualizado. De ahí la necesidad de envolver cualquier grabación de comandos añadida externamente entre beginExternal() y endExternal(). Conceptualmente, esto es lo mismo que las funciones beginNativePainting() y endNativePainting() de QPainter.
En el caso concreto de OpenGL, esta función tiene una tarea adicional: se asegura de que el contexto se establezca como actual en el hilo actual.
Nota: Una vez llamada beginExternal(), no se deben llamar otras funciones específicas de la pasada de renderizado (set* o draw*) en el QRhiCommandBuffer hasta que se llame a endExternal().
Advertencia: Algunos backends pueden devolver un objeto de búfer de comandos nativo desde ` QRhiCommandBuffer::nativeHandles()` que sea diferente del principal cuando se encuentre dentro de un bloque `beginExternal()` - ` endExternal()`. Por lo tanto, es importante volver a consultar el objeto de búfer de comandos nativo tras llamar a `beginExternal()`. En la práctica, esto significa que, con Vulkan por ejemplo, los comandos de Vulkan grabados externamente se colocan en un búfer de comandos secundario (con VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT). La función ` nativeHandles()` devuelve este búfer de comandos secundario cuando se invoca entre `begin` y `endExternal`.
Véanse también endExternal() y nativeHandles().
void QRhiCommandBuffer::beginPass(QRhiRenderTarget *rt, const QColor &colorClearValue, const QRhiDepthStencilClearValue &depthStencilClearValue, QRhiResourceUpdateBatch *resourceUpdates = nullptr, QRhiCommandBuffer::BeginPassFlags flags = {})
Registra el inicio de una nueva pasada de renderizado dirigida al destino de renderizado rt.
resourceUpdates, cuando no es nulo, especifica un lote de actualización de recursos que se va a confirmar y, a continuación, liberar.
Normalmente, los búferes de color y de profundidad/plantilla del destino de renderizado se borran. Los valores de borrado se especifican en colorClearValue y depthStencilClearValue. La excepción se da cuando el destino de renderizado se ha creado con QRhiTextureRenderTarget::PreserveColorContents y/o QRhiTextureRenderTarget::PreserveDepthStencilContents. En ese caso, los valores de borrado se ignoran.
Nota: Habilitar la conservación del contenido de color o profundidad reduce el rendimiento en función del hardware subyacente. Las GPU móviles con arquitectura en mosaico se benefician de no tener que volver a cargar el contenido anterior en el búfer de mosaicos. Del mismo modo, un « QRhiTextureRenderTarget » con un « QRhiTexture » como búfer de profundidad es menos eficiente que un « QRhiRenderBuffer », ya que el uso de una textura de profundidad obliga a escribir los datos en ella, mientras que con los «renderbuffers» esto no es necesario (pues la API no permite el muestreo ni la lectura desde un «renderbuffer»).
Nota: Nose debe dar por sentado que los enlaces de estado o de recursos persistan entre pasadas.
Nota: Las funciones ` set ` y ` draw ` de ` QRhiCommandBuffer` solo pueden invocarse dentro de un paso. Además, a excepción de ` setGraphicsPipeline()`, esperan que ya haya un pipeline configurado en el búfer de comandos. De lo contrario, pueden surgir problemas no especificados, dependiendo del backend.
Si rt es un QRhiTextureRenderTarget, beginPass() comprueba si los objetos de textura y renderbuffer a los que hace referencia el destino de renderizado están actualizados. Esto es similar a lo que hace setShaderResources() con QRhiShaderResourceBindings. Si alguno de los archivos adjuntos se ha reconstruido desde QRhiTextureRenderTarget::create(), se realiza una llamada implícita a create() en rt. Por lo tanto, si rt tiene un archivo adjunto de color QRhiTexture texture y es necesario cambiar el tamaño de la textura, lo siguiente es válido:
QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ { texture } });
rt->create();
// ...
texture->setPixelSize(new_size);
texture->create();
cb->beginPass(rt, colorClear, dsClear); // this is ok, no explicit rt->create() is required beforeflags permite controlar ciertas funcionalidades avanzadas. Un indicador de uso común es ExternalContents. Este debe especificarse siempre que se vaya a llamar a beginExternal() dentro de la pasada iniciada por esta función.
Véase también endPass() y BeginPassFlags.
void QRhiCommandBuffer::debugMarkBegin(const QByteArray &name)
Registra un grupo de depuración con nombre en el búfer de comandos con el « name » especificado. Esto se muestra en herramientas gráficas de depuración como RenderDoc y XCode. El final de la agrupación se indica mediante « debugMarkEnd()».
Nota: Se ignora cuando no se admiten los « QRhi::DebugMarkers » o cuando no se ha definido « QRhi::EnableDebugMarkers ».
Nota: Se puede invocar en cualquier punto del fotograma, tanto dentro como fuera de las pasadas.
void QRhiCommandBuffer::debugMarkEnd()
Marca el final de un grupo de depuración.
Nota: Se ignora cuando no se admiten las opciones « QRhi::DebugMarkers » o no se ha establecido « QRhi::EnableDebugMarkers ».
Nota: Se puede llamar desde cualquier punto del marco, tanto dentro como fuera de las pasadas.
void QRhiCommandBuffer::debugMarkMsg(const QByteArray &msg)
Inserta un mensaje de depuración « msg » en el flujo de comandos.
Nota: Se ignora cuando no se admiten los mensajes de depuración QRhi::DebugMarkers o cuando no está activada la opción QRhi::EnableDebugMarkers.
Nota: En algunos backends, debugMarkMsg() solo es compatible dentro de una pasada y se ignora cuando se invoca fuera de ella. En otros, se registra en cualquier punto del fotograma.
void QRhiCommandBuffer::dispatch(int x, int y, int z)
Registra el envío de elementos de trabajo de cálculo, utilizando x, y y z para especificar el número de grupos de trabajo locales en la dimensión correspondiente.
Nota: Esta función solo se puede invocar dentro de una pasada de cálculo, es decir, entre una llamada a beginComputePass() y otra a endComputePass().
Nota: x, y y z deben ajustarse a los límites de la implementación de la API gráfica subyacente en tiempo de ejecución. Los valores máximos suelen ser 65535.
Nota: Ten en cuenta también los posibles límites en el tamaño del grupo de trabajo local. Esto se especifica en el shader, por ejemplo: layout(local_size_x = 16, local_size_y = 16) in;. Por ejemplo, con OpenGL, el valor mínimo exigido por la especificación para el número de invocaciones en un único grupo de trabajo local (el producto de local_size_x, local_size_y y local_size_z) es 1024, mientras que con OpenGL ES (3.1) el valor puede ser tan bajo como 128. Esto significa que el ejemplo anterior podría ser rechazado por algunas implementaciones de OpenGL ES, ya que el número de invocaciones es de 256.
void QRhiCommandBuffer::draw(quint32 vertexCount, quint32 instanceCount = 1, quint32 firstVertex = 0, quint32 firstInstance = 0)
Registra un dibujo no indexado.
El número de vértices se especifica en vertexCount. Para el dibujo instanciado, establezca instanceCount en un valor distinto de 1. firstVertex es el índice del primer vértice que se va a dibujar. Al dibujar varias instancias, el ID de la primera instancia se especifica mediante firstInstance.
Nota: Es posible quefirstInstance no sea compatible y se ignore cuando se indique que la función QRhi::BaseInstance no es compatible. En ese caso, el ID de la primera instancia es siempre 0. Por el momento, QRhi::BaseInstance nunca es compatible con OpenGL, debido principalmente a las limitaciones de OpenGL ES; por lo tanto, las aplicaciones portátiles no deben diseñarse basándose en este argumento.
Nota: Los shaders que necesiten acceder al índice del vértice o la instancia actual deben utilizar gl_VertexIndex y gl_InstanceIndex, es decir, las variables integradas compatibles con Vulkan, en lugar de gl_VertexID y gl_InstanceID.
Nota: Cuando firstInstance es distinto de cero, gl_InstanceIndex no incluirá el valor base con algunas de las API 3D subyacentes. Esto viene indicado por la característica QRhi::InstanceIndexIncludesBaseInstance. Si no se puede evitar depender de un valor de instancia base, se recomienda a las aplicaciones que pasen el valor como un «uniform» de forma condicional en función de lo que indique dicha característica, y que lo sumen a gl_InstanceIndex en el shader.
Nota: Esta función solo se puede invocar dentro de un paso de renderizado, es decir, entre una llamada a ` beginPass()` y una a ` endPass()`.
void QRhiCommandBuffer::drawIndexed(quint32 indexCount, quint32 instanceCount = 1, quint32 firstIndex = 0, qint32 vertexOffset = 0, quint32 firstInstance = 0)
Registra un sorteo indexado.
El número de vértices se especifica en indexCount. firstIndex es el índice base. El desplazamiento efectivo en el búfer de índices viene dado por indexOffset + firstIndex * n, donde n es 2 o 4, dependiendo del tipo de elemento del índice. indexOffset se especifica en setVertexInput().
Nota: El desplazamiento efectivo en el búfer de índices debe estar alineado a 4 bytes con algunos backends (por ejemplo, Metal). Con estos backends, la característica « NonFourAlignedEffectiveIndexBufferOffset » se indicará como no compatible.
vertexOffset (también denominado « base vertex ») es un valor con signo que se suma al índice del elemento antes de indexarlo en el búfer de vértices. La compatibilidad con esta característica no siempre está disponible, y el valor se ignora cuando la característica « QRhi::BaseVertex » se indica como no compatible.
Para el dibujo instanciado, establezca « instanceCount » en un valor distinto de 1. Al dibujar varias instancias, el ID de la primera instancia se especifica mediante « firstInstance ».
Nota: Es posible quefirstInstance no sea compatible y se ignore cuando la función QRhi::BaseInstance se indique como no compatible. En ese caso, el ID de la primera instancia es siempre 0. QRhi::BaseInstance no es compatible con OpenGL por el momento, debido principalmente a las limitaciones de OpenGL ES; por lo tanto, las aplicaciones portátiles no deben diseñarse para depender de este argumento.
Nota: Los shaders que necesiten acceder al índice del vértice o la instancia actual deben utilizar gl_VertexIndex y gl_InstanceIndex, es decir, las variables integradas compatibles con Vulkan, en lugar de gl_VertexID y gl_InstanceID.
Nota: Cuando firstInstance es distinto de cero, gl_InstanceIndex no incluirá el valor base con algunas de las API 3D subyacentes. Esto viene indicado por la característica QRhi::InstanceIndexIncludesBaseInstance. Si no se puede evitar depender de un valor de instancia base, se recomienda a las aplicaciones que pasen el valor como un «uniform» de forma condicional en función de lo que indique dicha característica, y que lo sumen a gl_InstanceIndex en el shader.
Nota: Esta función solo se puede invocar dentro de un paso de renderizado, es decir, entre una llamada a ` beginPass()` y una a ` endPass()`.
[since 6.12] void QRhiCommandBuffer::drawIndexedIndirect(QRhiBuffer *indirectBuffer, quint32 indirectBufferOffset, quint32 drawCount, quint32 stride = sizeof(QRhiIndexedIndirectDrawCommand))
Registra un dibujo indirecto e indexado.
Los parámetros de lectura son proporcionados por el búfer especificado en indirectBuffer, que debe contener una matriz de elementos de tipo QRhiIndexedIndirectDrawCommand. Los parámetros de QRhiIndexedIndirectDrawCommand tienen el mismo significado que en drawIndexed().
El desplazamiento, en bytes, desde el que se leen los parámetros en el búfer se especifica mediante indirectBufferOffset.
drawCount especifica el número de dichos comandos de dibujo que se van a emitir.
stride indica el tamaño en bytes de cada estructura de comando de dibujo individual en el búfer. Esto permite intercalar datos personalizados entre comandos si es necesario. El valor debe ser un múltiplo de 4 y mayor o igual que sizeof(QRhiIndexedIndirectDrawCommand).
Nota: Un valor de ` drawCount ` mayor que 1 solo es compatible de forma nativa si la característica ` QRhi::DrawIndirectMulti ` se indica como compatible y `stride` es el valor por defecto. De lo contrario, esta función emula el dibujo múltiple registrando varias llamadas de dibujo, sin ofrecer ninguna ventaja de rendimiento respecto a las llamadas repetidas a ` drawIndexed()`.
Nota: Esta función solo se puede invocar dentro de una pasada de renderizado, es decir, entre una llamada a ` beginPass()` y una a ` endPass()`.
Esta función se introdujo en Qt 6.12.
[since 6.12] void QRhiCommandBuffer::drawIndirect(QRhiBuffer *indirectBuffer, quint32 indirectBufferOffset, quint32 drawCount, quint32 stride = sizeof(QRhiIndirectDrawCommand))
Registra un dibujo indirecto no indexado.
Los parámetros de lectura los proporciona el búfer especificado en indirectBuffer, que debe contener una matriz de elementos de tipo QRhiIndirectDrawCommand. Los parámetros de QRhiIndirectDrawCommand tienen el mismo significado que en draw().
El desplazamiento, en bytes, a partir del cual se leen los parámetros en el búfer se especifica mediante indirectBufferOffset.
drawCount especifica el número de comandos de dibujo de este tipo que se van a emitir.
stride indica el tamaño en bytes de cada estructura de comando de dibujo individual en el búfer. Esto permite intercalar datos personalizados entre comandos si es necesario. El valor debe ser un múltiplo de 4 y mayor o igual que sizeof(QRhiIndirectDrawCommand).
Nota: Un valor de ` drawCount ` superior a 1 solo es compatible de forma nativa si la función ` QRhi::DrawIndirectMulti ` se indica como compatible y `stride` es el valor predeterminado. De lo contrario, esta función emula el dibujo múltiple registrando múltiples llamadas de dibujo, sin ofrecer ninguna ventaja de rendimiento frente a llamadas repetidas a ` draw()`.
Nota: Esta función solo se puede invocar dentro de un paso de renderizado, es decir, entre una llamada a ` beginPass()` y otra a ` endPass()`.
Esta función se introdujo en Qt 6.12.
void QRhiCommandBuffer::endComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr)
Registros que ponen fin a la pasada de cálculo actual.
resourceUpdates, cuando no es nulo, especifica un lote de actualización de recursos que debe confirmarse y, a continuación, liberarse.
void QRhiCommandBuffer::endExternal()
Se invocará una vez que los comandos añadidos externamente se hayan registrado en el búfer de comandos o en el contexto.
Nota: Se debe considerar quetodo el estado de QRhiCommandBuffer ha dejado de ser válido tras llamar a esta función. Las tuberías, los búferes de vértices e índices, y cualquier otro estado deben volver a configurarse si se registran más llamadas de dibujo tras los comandos externos.
Véase también beginExternal() y nativeHandles().
void QRhiCommandBuffer::endPass(QRhiResourceUpdateBatch *resourceUpdates = nullptr)
Registros que ponen fin a la pasada de renderizado actual.
resourceUpdates, cuando no es nulo, especifica un lote de actualizaciones de recursos que se va a confirmar y, a continuación, liberar.
Véase también beginPass().
double QRhiCommandBuffer::lastCompletedGpuTime()
Devuelve la última marca de tiempo disponible, en segundos, cuando se activó la función « QRhi::EnableTimestamps » al crear el objeto ` QRhi`. El valor indica el tiempo transcurrido en la GPU durante el último fotograma completado.
Nota: Nose deben esperar resultados distintos de 0 cuando la función « QRhi::Timestamps » no figure como compatible, o cuando no se haya pasado QRhi::EnableTimestamps a QRhi::create(). Existen excepciones a esto, ya que con algunas API gráficas (Metal) los tiempos están disponibles sin necesidad de realizar operaciones adicionales (consultas de marcas de tiempo), pero las aplicaciones portables siempre deben optar conscientemente por la recopilación de marcas de tiempo cuando sepan que es necesaria, y llamar a esta función en consecuencia.
Hay que tener cuidado con la interpretación del valor, ya que su precisión y granularidad a menudo no están controladas por Qt, y dependen de la API gráfica subyacente y de su implementación. En particular, no se recomienda comparar los valores entre diferentes API gráficas y hardware, ya que puede carecer de sentido.
Es probable que los valores de tiempo estén disponibles de forma asíncrona. Por lo tanto, el valor devuelto puede ser 0 (por ejemplo, durante los primeros 1-2 fotogramas) o el último valor conocido correspondiente a algún fotograma anterior. El valor también puede volver a ser 0 en determinadas condiciones, como al cambiar el tamaño de la ventana. Cabe esperar que el valor más actualizado disponible se recupere en `beginFrame()` y pueda consultarse mediante esta función una vez que `beginFrame()` devuelva un resultado.
Nota: Nose debe dar por sentado que el valor se refiere al fotograma anterior (currently_recorded - 1). También puede referirse a currently_recorded - 2 o currently_recorded - 3. El comportamiento exacto puede depender de la API gráfica y de su implementación.
Ten en cuenta las consecuencias del escalado de frecuencia de la GPU y los cambios en la frecuencia de reloj de la GPU, dependiendo de la plataforma. Por ejemplo, en Windows, el tiempo devuelto puede variar en un rango bastante amplio entre fotogramas con tarjetas gráficas modernas, incluso al enviar fotogramas con una carga de trabajo similar o idéntica. En términos generales, esto queda fuera del alcance de Qt para controlarlo y resolverlo. Sin embargo, el backend D3D12 llama automáticamente a `ID3D12Device::SetStablePowerState() ` siempre que la variable de entorno ` QT_D3D_STABLE_POWER_STATE ` se establezca en un valor distinto de cero. Esto puede estabilizar en gran medida el resultado. También puede tener un efecto nada desdeñable en los tiempos medidos en el lado de la CPU a través de QElapsedTimer, por ejemplo, especialmente cuando hay fotogramas fuera de pantalla.
Nota: Nose deben lanzar nunca aplicaciones a producción con la variable QT_D3D_STABLE_POWER_STATE activada. Consulte la documentación de la API de Windows para obtener más detalles.
Véase también QRhi::Timestamps y QRhi::EnableTimestamps.
const QRhiNativeHandles *QRhiCommandBuffer::nativeHandles()
Devuelve un puntero a una subclase de ` QRhiNativeHandles ` específica del backend, como ` QRhiVulkanCommandBufferNativeHandles`. El valor devuelto es ` nullptr ` cuando el backend no admite la exposición de los recursos nativos subyacentes o esta no es aplicable.
Véase también QRhiVulkanCommandBufferNativeHandles, QRhiMetalCommandBufferNativeHandles, beginExternal() y endExternal().
[override virtual] QRhiResource::Type QRhiCommandBuffer::resourceType() const
Reimplementa: ` QRhiResource::resourceType()` const.
Devuelve el tipo de recurso.
void QRhiCommandBuffer::resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates)
A veces es necesario, o simplemente más práctico, aplicar actualizaciones de recursos sin iniciar una pasada de renderizado. Llamar a esta función con ` resourceUpdates ` es una alternativa a pasar ` resourceUpdates ` a una llamada a ` beginPass()` (o ` endPass()`, lo cual sería habitual en el caso de las lecturas posteriores).
Nota: No se puede llamar dentro de una pasada.
void QRhiCommandBuffer::setBlendConstants(const QColor &c)
Registros que establecen las constantes de mezcla activas en c.
Esto solo se puede invocar cuando el pipeline vinculado tiene QRhiGraphicsPipeline::UsesBlendConstants establecido.
Nota: Esta función solo se puede invocar dentro de un paso de renderizado, es decir, entre una llamada a ` beginPass()` y otra a ` endPass()`.
void QRhiCommandBuffer::setComputePipeline(QRhiComputePipeline *ps)
Registra la configuración de una nueva canalización de cálculo ps.
Nota: Esta función debe llamarse antes de registrar los comandos setShaderResources() o dispatch() en el búfer de comandos.
Nota: ` QRhi ` optimizará las invocaciones innecesarias dentro de una pasada, por lo que no es necesario que las aplicaciones optimicen en exceso para evitar llamadas a esta función.
Nota: Esta función solo se puede invocar dentro de una pasada de cálculo, es decir, entre una llamada a beginComputePass() y otra a endComputePass().
void QRhiCommandBuffer::setGraphicsPipeline(QRhiGraphicsPipeline *ps)
Registra la configuración de una nueva canalización gráfica ps.
Nota: Esta función debe llamarse antes de registrar otros comandos set o draw en el búfer de comandos.
Nota: ` QRhi ` optimizará las invocaciones innecesarias dentro de un paso, por lo que no es necesario que las aplicaciones optimicen en exceso para evitar llamadas a esta función.
Nota: Esta función solo se puede invocar dentro de una pasada de renderizado, es decir, entre una llamada a ` beginPass()` y otra a ` endPass()`.
Nota: El nuevo canal gráfico ps debe ser un puntero válido.
Al establecer un canal de procesamiento gráfico que no tenga el indicador UsesScissor, se desactivará el recorte —en las API gráficas en las que sea aplicable— o se configurará el rectángulo de recorte para que coincida con la ventana de visualización establecida en último lugar (en las API gráficas en las que el recorte está, a efectos prácticos, siempre activo), con el fin de garantizar un comportamiento uniforme en todos los backends de QRhi.
void QRhiCommandBuffer::setScissor(const QRhiScissor &scissor)
Función que establece el rectángulo de tijera activo especificado en ` scissor`.
Solo se puede invocar esta función cuando el pipeline vinculado tiene activado el indicador « UsesScissor ». Cuando se activa este indicador en el pipeline activo, es obligatorio invocar esta función, ya que se habilitará la prueba de tijera y, por lo tanto, se debe proporcionar un rectángulo de tijera.
Nota: QRhi asume coordenadas de ventana de visualización al estilo OpenGL, lo que significa que x e y se sitúan en la esquina inferior izquierda.
Nota: Esta función solo se puede invocar dentro de un paso de renderizado, es decir, entre una llamada a ` beginPass()` y una a ` endPass()`.
void QRhiCommandBuffer::setShaderResources(QRhiShaderResourceBindings *srb = nullptr, int dynamicOffsetCount = 0, const QRhiCommandBuffer::DynamicOffset *dynamicOffsets = nullptr)
Registros que vinculan un conjunto de recursos de shader, como búferes uniformes o texturas, que se hacen visibles para una o más etapas de shader.
srb Puede ser nulo; en ese caso, se utiliza el ` QRhiShaderResourceBindings ` asociado a la canalización gráfica o de cálculo actual. Cuando ` srb ` no es nulo, debe ser ` layout-compatible`, lo que significa que la disposición (número de enlaces, tipo y número de enlace de cada uno) debe coincidir totalmente con el ` QRhiShaderResourceBindings ` que estaba asociado a la canalización en el momento de llamar a `create()` de la misma.
Hay casos en los que una llamada a `setShaderResources()` aparentemente innecesaria resulta obligatoria: al reconstruir un recurso al que se hace referencia desde ` srb`, por ejemplo, al cambiar el tamaño de un ` QRhiBuffer ` seguido de un ` QRhiBuffer::create()`, este es el momento en el que los objetos nativos asociados (como los conjuntos de descriptores en el caso de Vulkan) se actualizan para hacer referencia a los recursos nativos actuales que respaldan los objetos ` QRhiBuffer`, ` QRhiTexture` y ` QRhiSampler ` a los que se hace referencia desde ` srb`. En este caso, se debe llamar a `setShaderResources()` incluso si ` srb ` es el mismo que en la última llamada.
Cuando srb no es nulo, se garantiza que no se accederá de ninguna forma al objeto QRhiShaderResourceBindings con el que se construyó el pipeline en create(). De hecho, ni siquiera es necesario que sea válido en este momento: es válido destruir el srb asociado al pipeline tras create() y, en su lugar, especificar explícitamente otro, layout compatible, en cada llamada a setShaderResources().
dynamicOffsets Permite especificar desplazamientos de búfer para los búferes uniformes que se asociaron a srb mediante QRhiShaderResourceBinding::uniformBufferWithDynamicOffset(). Esto difiere de proporcionar el desplazamiento en el propio srb: los desplazamientos dinámicos no requieren crear un nuevo QRhiShaderResourceBindings para cada desplazamiento diferente, pueden evitar la escritura de los descriptores subyacentes (con backends donde sea aplicable) y, por lo tanto, pueden resultar más eficientes. Cada elemento de dynamicOffsets es un par formado por binding y offset. dynamicOffsetCount especifica el número de elementos de dynamicOffsets.
Nota: Todos los desplazamientos de dynamicOffsets deben estar alineados por bytes con el valor devuelto por QRhi::ubufAlignment().
Nota: Algunos backends pueden limitar el número de desplazamientos dinámicos admitidos. Evita utilizar un dynamicOffsetCount mayor que 8.
Nota: QRhi optimizará las invocaciones innecesarias dentro de una pasada (teniendo en cuenta las condiciones descritas anteriormente), por lo que no es necesario que las aplicaciones optimicen en exceso para evitar llamadas a esta función.
Nota: Esta función solo se puede invocar dentro de una pasada de renderizado o de cálculo, es decir, entre un ` beginPass()` y un ` endPass()`, o entre un ` beginComputePass()` y un ` endComputePass()`.
[since 6.9] void QRhiCommandBuffer::setShadingRate(const QSize &coarsePixelSize)
Establece la tasa de sombreado para las siguientes llamadas de dibujo en ` coarsePixelSize`.
El valor predeterminado es 1x1.
Solo funciona cuando se indica que la función « QRhi::VariableRateShading » es compatible y las uniones de « QRhiGraphicsPipeline » del búfer de comandos declaraban « QRhiGraphicsPipeline::UsesShadingRate » al crearlas.
Llama a QRhi::supportedShadingRates() para comprobar qué tasas de sombreado son compatibles con un número determinado de muestras.
Cuando se utilizan tanto ` QRhiShadingRateMap ` como esta función, se aplica la tasa de sombreado más alta de las dos para cada mosaico. Actualmente no se ofrece ningún control sobre el comportamiento del combinador.
Esta función se introdujo en Qt 6.9.
void QRhiCommandBuffer::setStencilRef(quint32 refValue)
Registra el valor de referencia de la plantilla activa como refValue.
Solo se puede invocar esta función cuando el pipeline vinculado tiene QRhiGraphicsPipeline::UsesStencilRef establecido.
Nota: Esta función solo se puede invocar dentro de un paso de renderizado, es decir, entre una llamada a ` beginPass()` y otra a ` endPass()`.
void QRhiCommandBuffer::setVertexInput(int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings, QRhiBuffer *indexBuf = nullptr, quint32 indexOffset = 0, QRhiCommandBuffer::IndexFormat indexFormat = IndexUInt16)
Registra las vinculaciones de entrada de vértices.
El búfer de índice utilizado por los comandos drawIndexed() posteriores se especifica mediante indexBuf, indexOffset y indexFormat. indexBuf se puede establecer en nulo cuando no se necesita el dibujo indexado.
Los enlaces del búfer de vértices se agrupan por lotes. startBinding especifica el número del primer enlace. A continuación, el comando grabado vincula cada búfer desde bindings al punto de enlace startBinding + i, donde i es el índice en bindings. Cada elemento de bindings especifica un QRhiBuffer y un desplazamiento.
Nota: Algunos backends pueden limitar el número de enlaces de búferes de vértices. Evita utilizar un bindingCount mayor que 8.
Los cambios superfluos en las entradas de vértices y en el índice dentro de la misma pasada se ignoran automáticamente en la mayoría de los backends, por lo que las aplicaciones no necesitan optimizar en exceso para evitar llamadas a esta función.
Nota: Esta función solo se puede invocar dentro de una pasada de renderizado, es decir, entre una llamada a ` beginPass()` y otra a ` endPass()`.
A modo de ejemplo sencillo, tomemos un sombreador de vértices con dos entradas:
layout(location = 0) in vec4 position;
layout(location = 1) in vec3 color;y supongamos que disponemos de los datos en formato intercalado, utilizando solo 2 flotantes para la posición (es decir, 5 flotantes por vértice: x, y, r, g, b). A continuación, se puede crear un ` QRhiGraphicsPipeline ` para este sombreador utilizando la disposición de entradas:
QRhiVertexInputLayout inputLayout;
inputLayout.setBindings({
{ 5 * sizeof(float) }
});
inputLayout.setAttributes({
{ 0, 0, QRhiVertexInputAttribute::Float2, 0 },
{ 0, 1, QRhiVertexInputAttribute::Float3, 2 * sizeof(float) }
});Aquí hay un enlace de búfer (número de enlace 0), al que hacen referencia dos entradas. Al grabar la pasada, una vez configurada la canalización, los enlaces de vértices pueden especificarse simplemente como se indica a continuación, suponiendo que `vbuf` sea el ` QRhiBuffer ` con todos los datos entrelazados de posición y color:
const QRhiCommandBuffer::VertexInput vbufBinding(vbuf, 0);
cb->setVertexInput(0, 1, &vbufBinding);void QRhiCommandBuffer::setViewport(const QRhiViewport &viewport)
Establece el rectángulo de la ventana de visualización activa especificado en viewport.
En los backends en los que la API gráfica subyacente tiene el recorte (scissoring) siempre activado, esta función también ajusta el recorte para que coincida con la ventana de visualización siempre que el QRhiGraphicsPipeline activo no tenga establecido UsesScissor.
Nota: ` QRhi ` asume coordenadas de ventana de visualización al estilo OpenGL, lo que significa que x e y se sitúan en la esquina inferior izquierda.
© 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.