QRhiCommandBuffer Class

Documentación de las funciones miembro

void QRhiCommandBuffer::beginComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr, QRhiCommandBuffer::BeginPassFlags flags = {})

Registra el inicio de un nuevo paso de cálculo.

resourceUpdatescuando no es nulo, especifica un lote de actualización de recursos que debe confirmarse y luego liberarse.

flags no se utiliza actualmente.

void QRhiCommandBuffer::beginExternal()

Se invoca cuando la aplicación está a punto de poner en cola comandos en el búfer de comandos del pase actual llamando directamente a funciones de la API gráfica.

Con Vulkan, Metal o Direct3D 12 se puede consultar el buffer de comandos nativo o los objetos codificadores a través de nativeHandles() y poner en cola comandos para ellos. Con OpenGL o Direct3D 11 el contexto (dispositivo) puede ser recuperado desde QRhi::nativeHandles(). Sin embargo, esto nunca debe hacerse sin asegurarse de que el estado de QRhiCommandBuffer se mantiene actualizado. De ahí el requisito de envolver cualquier grabación de comando añadido externamente entre beginExternal() y endExternal(). Conceptualmente es lo mismo que las funciones beginNativePainting() y endNativePainting() de QPainter.

Para OpenGL en particular, esta función tiene una tarea adicional: se asegura de que el contexto se hace actual en el hilo actual.

Véase 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 un nuevo pase de renderizado dirigido al objetivo de renderizado rt.

resourceUpdatescuando no es nulo, especifica un lote de actualización de recursos que debe ser consignado y luego liberado.

Los buffers de color y profundidad/esténcil del objetivo de renderizado se borran normalmente. Los valores de borrado se especifican en colorClearValue y depthStencilClearValue. La excepción es cuando el objetivo de render se creó con QRhiTextureRenderTarget::PreserveColorContents y/o QRhiTextureRenderTarget::PreserveDepthStencilContents. En este caso, los valores de borrado se ignoran.

Si rt es un QRhiTextureRenderTarget, beginPass() realiza una comprobación para ver si la textura y los objetos renderbuffer referenciados desde el objetivo de renderizado están actualizados. Esto es similar a lo que setShaderResources() hace para QRhiShaderResourceBindings. Si alguno de los anexos ha sido reconstruido desde QRhiTextureRenderTarget::create(), se realiza una llamada implícita a create() en rt. Por lo tanto, si rt tiene un adjunto de color QRhiTexture texture , y uno necesita hacer la textura de un tamaño diferente, lo siguiente es entonces 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 before

flags permiten controlar ciertas funcionalidades avanzadas. Una bandera de uso común es ExternalContents. Debe especificarse siempre que se vaya a llamar a beginExternal() dentro del pase iniciado por esta función.

Véase también endPass() y BeginPassFlags.

void QRhiCommandBuffer::debugMarkBegin(const QByteArray &name)

Registra un grupo de depuración nombrado en el búfer de comandos con la dirección name especificada. Esto se muestra en herramientas de depuración de gráficos como RenderDoc y XCode. El final de la agrupación se indica mediante debugMarkEnd().

void QRhiCommandBuffer::debugMarkEnd()

Registra el final de un grupo de depuración.

void QRhiCommandBuffer::debugMarkMsg(const QByteArray &msg)

Inserta un mensaje de depuración msg en el flujo de comandos.

void QRhiCommandBuffer::dispatch(int x, int y, int z)

Registra el envío de elementos de trabajo de cálculo, con x, y, y z especificando el número de grupos de trabajo locales en la dimensión correspondiente.

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 dibujar instancias establece instanceCount a un valor distinto de 1. firstVertex es el índice del primer vértice a dibujar. Cuando se dibujan múltiples instancias, el ID de la primera instancia se especifica en firstInstance.

void QRhiCommandBuffer::drawIndexed(quint32 indexCount, quint32 instanceCount = 1, quint32 firstIndex = 0, qint32 vertexOffset = 0, quint32 firstInstance = 0)

Registra un dibujo indexado.

El número de vértices se especifica en indexCount. firstIndex es el índice base. El desplazamiento efectivo en el búfer de índice viene dado por indexOffset + firstIndex * n donde n es 2 o 4 dependiendo del tipo de elemento de índice. indexOffset se especifica en setVertexInput().

vertexOffset (también llamado base vertex) es un valor con signo que se añade al índice del elemento antes de indexarlo en el búfer de vértices. El soporte para esto no está siempre disponible, y el valor es ignorado cuando la característica QRhi::BaseVertex es reportada como no soportada.

Para dibujar instancias, configure instanceCount con un valor distinto de 1. Cuando se dibujan varias instancias, el ID de la primera instancia se especifica mediante firstInstance.

void QRhiCommandBuffer::endComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr)

Registros que finalizan el pase de cálculo actual.

resourceUpdatescuando no es nulo, especifica un lote de actualización de recursos que debe confirmarse y luego liberarse.

void QRhiCommandBuffer::endExternal()

Para ser llamada una vez que los comandos añadidos externamente son registrados en el buffer de comandos o contexto.

Véase también beginExternal() y nativeHandles().

void QRhiCommandBuffer::endPass(QRhiResourceUpdateBatch *resourceUpdates = nullptr)

Registros que finalizan el pase de renderizado actual.

resourceUpdatescuando no es nulo, especifica un lote de actualización de recursos que debe confirmarse y luego liberarse.

Véase también beginPass().

double QRhiCommandBuffer::lastCompletedGpuTime()

Devuelve la última marca de tiempo disponible, en segundos, cuando QRhi::EnableTimestamps estaba habilitada al crear el QRhi. El valor indica el tiempo transcurrido en la GPU durante el último fotograma completado.

Hay que tener cuidado con la interpretación del valor, ya que su precisión y granularidad a menudo no está controlada por Qt, y depende de la API gráfica subyacente y su implementación. En particular, se desaconseja comparar los valores entre diferentes APIs gráficas y hardware, ya que puede carecer de sentido.

Cuando el fotograma se grabó con beginFrame() y endFrame(), es decir, con una cadena de intercambio, es probable que los valores de temporización estén disponibles de forma asíncrona. Por lo tanto, el valor devuelto puede ser 0 (por ejemplo, para los primeros 1-2 fotogramas) o el último valor conocido referido 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. Se puede esperar que el valor disponible más actualizado se recupere en beginFrame() y se pueda consultar a través de esta función una vez que retorne beginFrame().

Por otro lado, con los fotogramas fuera de pantalla el valor devuelto está actualizado una vez que endOffscreenFrame() vuelve, porque los fotogramas fuera de pantalla reducen el pipelining de la GPU y esperan a que los comandos se completen.

Ten cuidado con las consecuencias del escalado de frecuencia de la GPU y los cambios 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 cuando se envían fotogramas con una carga de trabajo similar, o la misma. Esto está fuera del alcance de Qt para controlar y resolver, en términos generales. Sin embargo, el backend D3D12 llama automáticamente a ID3D12Device::SetStablePowerState() siempre que la variable de entorno QT_D3D_STABLE_POWER_STATE se establece en un valor distinto de cero. Esto puede estabilizar mucho el resultado. También puede tener un efecto no insignificante en los tiempos del lado de la CPU medidos a través de QElapsedTimer por ejemplo, especialmente cuando se trata de fotogramas fuera de pantalla.

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 la exposición de los recursos nativos subyacentes no está soportada por, o no es aplicable a, el backend.

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 más conveniente actualizar los recursos sin iniciar un pase de renderizado. Llamar a esta función con resourceUpdates es una alternativa a pasar resourceUpdates a una llamada a beginPass() (o endPass(), que sería lo típico en caso de readbacks).

void QRhiCommandBuffer::setBlendConstants(const QColor &c)

Registra las constantes de mezcla activas en c.

Esto sólo puede ser llamado cuando la tubería de enlace tiene QRhiGraphicsPipeline::UsesBlendConstants establecido.

void QRhiCommandBuffer::setComputePipeline(QRhiComputePipeline *ps)

Registra la configuración de un nuevo canal de cálculo ps.

void QRhiCommandBuffer::setGraphicsPipeline(QRhiGraphicsPipeline *ps)

Registra la configuración de un nuevo conducto de gráficos ps.

void QRhiCommandBuffer::setScissor(const QRhiScissor &scissor)

Registra el ajuste del rectángulo de tijera activo especificado en scissor.

Esto sólo puede ser llamado cuando la tubería vinculada tiene UsesScissor establecido. Cuando la bandera se establece en la tubería activa, esta función debe ser llamada porque la prueba de tijera se activará y por lo tanto un rectángulo de tijera debe ser proporcionado.

void QRhiCommandBuffer::setShaderResources(QRhiShaderResourceBindings *srb = nullptr, int dynamicOffsetCount = 0, const QRhiCommandBuffer::DynamicOffset *dynamicOffsets = nullptr)

Registra un conjunto de recursos de sombreado, como memorias intermedias uniformes o texturas, que se hacen visibles para una o más etapas de sombreado.

srb puede ser nulo, en cuyo caso se utilizará el canal gráfico o de cálculo actual asociado a QRhiShaderResourceBindings. Cuando srb no es nulo, debe ser layout-compatible, lo que significa que el diseño (número de vinculaciones, el tipo y el número de vinculación de cada vinculación) debe coincidir totalmente con el QRhiShaderResourceBindings que se asoció con la canalización en el momento de llamar a create() de la canalización.

Hay casos en los que una llamada aparentemente innecesaria a setShaderResources() es obligatoria: cuando se reconstruye un recurso referenciado desde srb, por ejemplo cambiando el tamaño de un QRhiBuffer seguido de un QRhiBuffer::create(), este es el lugar donde los objetos nativos asociados (como los conjuntos de descriptores en el caso de Vulkan) se actualizan para referirse a los recursos nativos actuales que respaldan los objetos QRhiBuffer, QRhiTexture, QRhiSampler referenciados 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 null, se garantiza que no se accede de ninguna forma al objeto QRhiShaderResourceBindings con el que se construyó el pipeline en create(). De hecho, no necesita ser válido incluso en este punto: destruir el srb asociado a la canalización después de create() y en su lugar especificar explícitamente otro, layout compatible en cada llamada a setShaderResources() es válido.

dynamicOffsets permite especificar desplazamientos de búfer para búferes uniformes que estaban asociados a srb a través de QRhiShaderResourceBinding::uniformBufferWithDynamicOffset(). Esto es diferente de proporcionar el offset en el propio srb: los offsets dinámicos no requieren construir un nuevo QRhiShaderResourceBindings para cada offset diferente, pueden evitar escribir los descriptores subyacentes (con backends donde sea aplicable), y por lo tanto pueden ser más eficientes. Cada elemento de dynamicOffsets es un par binding - offset. dynamicOffsetCount especifica el número de elementos en dynamicOffsets.

[since 6.9] void QRhiCommandBuffer::setShadingRate(const QSize &coarsePixelSize)

Establece la tasa de sombreado para las siguientes llamadas a coarsePixelSize.

El valor por defecto es 1x1.

Funcional sólo cuando la característica QRhi::VariableRateShading es reportada como soportada y los QRhiGraphicsPipeline(s) ligados en el buffer de comandos declaraban QRhiGraphicsPipeline::UsesShadingRate al crearlos.

Llame a QRhi::supportedShadingRates() para comprobar qué tasas de sombreado se admiten para un recuento de muestras determinado.

Cuando se utilizan tanto QRhiShadingRateMap como esta función, se utiliza la mayor de las dos tasas de sombreado 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 del esténcil activo en refValue.

Esta función sólo puede invocarse cuando el canal de renderización vinculado tiene QRhiGraphicsPipeline::UsesStencilRef establecido.

void QRhiCommandBuffer::setVertexInput(int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings, QRhiBuffer *indexBuf = nullptr, quint32 indexOffset = 0, QRhiCommandBuffer::IndexFormat indexFormat = IndexUInt16)

Registra los enlaces de entrada de vértices.

El búfer de índice utilizado por los comandos drawIndexed() subsiguientes se especifica mediante indexBuf, indexOffset, y indexFormat. indexBuf puede establecerse como nulo cuando no se necesita el dibujo indexado.

Las vinculaciones de búferes de vértices se realizan por lotes. startBinding especifica el primer número de vinculación. El comando grabado enlaza 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.

Las entradas de vértices superfluas y los cambios de índice en la misma pasada se ignoran automáticamente con la mayoría de los backends y, por lo tanto, las aplicaciones no necesitan sobreoptimizar para evitar llamadas a esta función.

Como ejemplo simple, tomemos un vertex shader con dos entradas:

layout(location = 0) in vec4 position;
layout(location = 1) in vec3 color;

y supongamos que tenemos los datos disponibles en formato intercalado, usando sólo 2 floats para la posición (así que 5 floats por vértice: x, y, r, g, b). Un QRhiGraphicsPipeline para este shader puede ser creado usando el layout de entrada:

QRhiVertexInputLayout inputLayout;
inputLayout.setBindings({
    { 5 * sizeof(float) }
});
inputLayout.setAttributes({
    { 0, 0, QRhiVertexInputAttribute::Float2, 0 },
    { 0, 1, QRhiVertexInputAttribute::Float3, 2 * sizeof(float) }
});

Aquí hay un buffer binding (binding número 0), con dos inputs referenciándolo. Cuando se graba el pase, una vez que el pipeline está configurado, los vertex bindings se pueden especificar simplemente como sigue, asumiendo que vbuf es el QRhiBuffer con todos los datos de posición+color intercalados:

const QRhiCommandBuffer::VertexInput vbufBinding(vbuf, 0);
cb->setVertexInput(0, 1, &vbufBinding);

void QRhiCommandBuffer::setViewport(const QRhiViewport &viewport)

Registra el rectángulo activo de la ventana gráfica especificado en viewport.

Con backends donde la API gráfica subyacente tiene la tijera siempre activada, esta función también establece la tijera para que coincida con la ventana gráfica siempre que la QRhiGraphicsPipeline activa no tenga UsesScissor establecido.