QRhiWidget Class
La clase QRhiWidget es un widget que permite renderizar gráficos en 3D a través de una API gráfica acelerada, como Vulkan, Metal o Direct 3D. Más información...
| Encabezado: | #include <QRhiWidget> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Desde: | Qt 6.7 |
| Heredado de: | QWidget |
Tipos públicos
| enum class | Api { Null, OpenGL, Metal, Vulkan, Direct3D11, Direct3D12 } |
| enum class | TextureFormat { RGBA8, RGBA16F, RGBA32F, RGB10A2 } |
Propiedades
|
|
Funciones públicas
| QRhiWidget(QWidget *parent = nullptr, Qt::WindowFlags f = {}) | |
| virtual | ~QRhiWidget() override |
| QRhiWidget::Api | api() const |
| QRhiWidget::TextureFormat | colorBufferFormat() const |
| QSize | fixedColorBufferSize() const |
| QImage | grabFramebuffer() const |
| bool | isDebugLayerEnabled() const |
| bool | isMirrorVerticallyEnabled() const |
| int | sampleCount() const |
| void | setApi(QRhiWidget::Api api) |
| void | setColorBufferFormat(QRhiWidget::TextureFormat format) |
| void | setDebugLayerEnabled(bool enable) |
| void | setFixedColorBufferSize(QSize pixelSize) |
| void | setFixedColorBufferSize(int w, int h) |
| void | setMirrorVertically(bool enabled) |
| void | setSampleCount(int samples) |
Señales
| void | colorBufferFormatChanged(QRhiWidget::TextureFormat format) |
| void | fixedColorBufferSizeChanged(const QSize &pixelSize) |
| void | frameSubmitted() |
| void | mirrorVerticallyChanged(bool enabled) |
| void | renderFailed() |
| void | sampleCountChanged(int samples) |
Funciones protegidas
| QRhiTexture * | colorTexture() const |
| QRhiRenderBuffer * | depthStencilBuffer() const |
| virtual void | initialize(QRhiCommandBuffer *cb) |
| QRhiRenderBuffer * | msaaColorBuffer() const |
| virtual void | releaseResources() |
| virtual void | render(QRhiCommandBuffer *cb) |
| QRhiRenderTarget * | renderTarget() const |
| QRhiTexture * | resolveTexture() const |
| QRhi * | rhi() const |
| void | setAutoRenderTarget(bool enabled) |
Funciones protegidas reimplementadas
| virtual bool | event(QEvent *e) override |
| virtual void | paintEvent(QPaintEvent *e) override |
| virtual void | resizeEvent(QResizeEvent *e) override |
Descripción detallada
QRhiWidget ofrece funcionalidad para mostrar contenido 3D renderizado a través de las API de QRhi dentro de una aplicación basada en QWidget. En muchos aspectos, es el equivalente portátil de QOpenGLWidget, que no está vinculado a una única API de gráficos 3D, sino que puede funcionar con todas las API compatibles con QRhi (como Direct 3D 11/12, Vulkan, Metal y OpenGL).
Se espera que QRhiWidget tenga subclases. Para renderizar en la textura 2D que QRhiWidget crea y gestiona de forma implícita, las subclases deben reimplementar las funciones virtuales initialize() y render().
El tamaño de la textura se adaptará, por defecto, al tamaño del widget. Si se prefiere un tamaño fijo, se debe establecer un tamaño fijo especificado en píxeles llamando a setFixedColorBufferSize().
Además de la textura, que actúa como búfer de color, también se mantienen implícitamente un búfer de profundidad/estarcido y un destino de renderizado que los une.
El ` QRhi ` para la ventana de nivel superior del widget está configurado para utilizar, por defecto, un backend y una API gráfica específicos de la plataforma: Metal en macOS e iOS, Direct 3D 11 en Windows y OpenGL en el resto de casos. Llama a ` setApi()` para anular esta configuración.
Nota: Una ventana de widget solo puede utilizar un backend de « QRhi » y, por lo tanto, una única API de gráficos 3D. Si dos widgets «QRhiWidget» o « QQuickWidget » en la jerarquía de widgets de la ventana solicitan API diferentes, solo uno de ellos funcionará correctamente.
Nota: Aunque QRhiWidget es una API pública de Qt, la familia de clases « QRhi » del módulo Qt GUI, que incluye QRhi, QShader y QShaderDescription, ofrece garantías de compatibilidad limitadas. No hay garantías de compatibilidad ni a nivel de código fuente ni a nivel binario para estas clases, lo que significa que solo se garantiza que la API funcione con la versión de Qt con la que se desarrolló la aplicación. No obstante, se pretende reducir al mínimo los cambios que impliquen incompatibilidad a nivel de código fuente, y estos solo se realizarán en versiones menores (6.7, 6.8, etc.). qrhiwidget.h no incluye directamente ningún encabezado relacionado con QRhi. Para utilizar esas clases al implementar una subclase de QRhiWidget, enlaza con Qt::GuiPrivate (si utilizas CMake) e incluye los encabezados adecuados con el prefijo rhi, por ejemplo, #include <rhi/qrhi.h>.
A continuación se muestra un ejemplo de una subclase sencilla de QRhiWidget que dibuja un triángulo:
class ExampleRhiWidget : public QRhiWidget
{
public:
ExampleRhiWidget(QWidget *parent = nullptr) : QRhiWidget(parent) { }
void initialize(QRhiCommandBuffer *cb) override;
void render(QRhiCommandBuffer *cb) override;
private:
QRhi *m_rhi = nullptr;
std::unique_ptr<QRhiBuffer> m_vbuf;
std::unique_ptr<QRhiBuffer> m_ubuf;
std::unique_ptr<QRhiShaderResourceBindings> m_srb;
std::unique_ptr<QRhiGraphicsPipeline> m_pipeline;
QMatrix4x4 m_viewProjection;
float m_rotation = 0.0f;
};
float vertexData[] = {
0.0f, 0.5f, 1.0f, 0.0f, 0.0f,
-0.5f, -0.5f, 0.0f, 1.0f, 0.0f,
0.5f, -0.5f, 0.0f, 0.0f, 1.0f,
};
QShader getShader(const QString &name)
{
QFile f(name);
return f.open(QIODevice::ReadOnly) ? QShader::fromSerialized(f.readAll()) : QShader();
}
void ExampleRhiWidget::initialize(QRhiCommandBuffer *cb)
{
if (m_rhi != rhi()) {
m_pipeline.reset();
m_rhi = rhi();
}
if (!m_pipeline) {
m_vbuf.reset(m_rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertexData)));
m_vbuf->create();
m_ubuf.reset(m_rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, 64));
m_ubuf->create();
m_srb.reset(m_rhi->newShaderResourceBindings());
m_srb->setBindings({
QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage, m_ubuf.get()),
});
m_srb->create();
m_pipeline.reset(m_rhi->newGraphicsPipeline());
m_pipeline->setShaderStages({
{ QRhiShaderStage::Vertex, getShader(QLatin1String(":/shader_assets/color.vert.qsb")) },
{ QRhiShaderStage::Fragment, getShader(QLatin1String(":/shader_assets/color.frag.qsb")) }
});
QRhiVertexInputLayout inputLayout;
inputLayout.setBindings({
{ 5 * sizeof(float) }
});
inputLayout.setAttributes({
{ 0, 0, QRhiVertexInputAttribute::Float2, 0 },
{ 0, 1, QRhiVertexInputAttribute::Float3, 2 * sizeof(float) }
});
m_pipeline->setVertexInputLayout(inputLayout);
m_pipeline->setShaderResourceBindings(m_srb.get());
m_pipeline->setRenderPassDescriptor(renderTarget()->renderPassDescriptor());
m_pipeline->create();
QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();
resourceUpdates->uploadStaticBuffer(m_vbuf.get(), vertexData);
cb->resourceUpdate(resourceUpdates);
}
const QSize outputSize = colorTexture()->pixelSize();
m_viewProjection = m_rhi->clipSpaceCorrMatrix();
m_viewProjection.perspective(45.0f, outputSize.width() / (float) outputSize.height(), 0.01f, 1000.0f);
m_viewProjection.translate(0, 0, -4);
}
void ExampleRhiWidget::render(QRhiCommandBuffer *cb)
{
QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();
m_rotation += 1.0f;
QMatrix4x4 modelViewProjection = m_viewProjection;
modelViewProjection.rotate(m_rotation, 0, 1, 0);
resourceUpdates->updateDynamicBuffer(m_ubuf.get(), 0, 64, modelViewProjection.constData());
const QColor clearColor = QColor::fromRgbF(0.4f, 0.7f, 0.0f, 1.0f);
cb->beginPass(renderTarget(), clearColor, { 1.0f, 0 }, resourceUpdates);
cb->setGraphicsPipeline(m_pipeline.get());
const QSize outputSize = colorTexture()->pixelSize();
cb->setViewport(QRhiViewport(0, 0, outputSize.width(), outputSize.height()));
cb->setShaderResources();
const QRhiCommandBuffer::VertexInput vbufBinding(m_vbuf.get(), 0);
cb->setVertexInput(0, 1, &vbufBinding);
cb->draw(3);
cb->endPass();
update();
}Se trata de un widget que solicita actualizaciones de forma continua, limitadas por la frecuencia de presentación (vsync, que depende de la frecuencia de actualización de la pantalla). Si no se desea que el renderizado sea continuo, se debe eliminar la llamada a ` update()` en ` render()` y, en su lugar, realizarla solo cuando sea necesario actualizar el contenido renderizado. Por ejemplo, si la rotación del cubo debe estar vinculada al valor de un QSlider, basta con conectar la señal de cambio de valor del control deslizante a un slot o una lambda que reenvíe el nuevo valor y llame a update().
Los sombreadores de vértices y de fragmentos se proporcionan en formato GLSL al estilo de Vulkan y deben ser procesados primero por la infraestructura de sombreadores de Qt. Esto se consigue ejecutando manualmente la herramienta de línea de comandos qsb o utilizando la función qt_add_shaders() en CMake. La implementación de QRhiWidget carga estos archivos .qsb preprocesados que se incluyen con la aplicación. Consulte Qt Shader Tools para obtener más información sobre la infraestructura de traducción de shaders de Qt.
El código fuente de estos shaders podría ser el siguiente:
color.vert
#version 440
layout(location = 0) in vec4 position;
layout(location = 1) in vec3 color;
layout(location = 0) out vec3 v_color;
layout(std140, binding = 0) uniform buf {
mat4 mvp;
};
void main()
{
v_color = color;
gl_Position = mvp * position;
}color.frag
#version 440
layout(location = 0) in vec3 v_color;
layout(location = 0) out vec4 fragColor;
void main()
{
fragColor = vec4(v_color, 1.0);
}El resultado es un widget que muestra lo siguiente:

Para ver un ejemplo completo, mínimo e introductorio, consulta el Ejemplo de widget RHI sencillo.
Para ver un ejemplo con más funcionalidades y una demostración de otros conceptos, consulta el «Ejemplo de widget RHI del cubo».
QRhiWidget siempre implica el renderizado en una textura de fondo, no directamente en la ventana (la superficie o capa proporcionada por el sistema de ventanas para la ventana nativa). Esto permite componer correctamente el contenido con el resto de la interfaz de usuario basada en widgets y ofrece una API sencilla y compacta, lo que facilita el inicio. Todo ello conlleva un consumo adicional de recursos y un posible impacto en el rendimiento. En la práctica, esto suele ser perfectamente aceptable, pero los usuarios avanzados deben tener en cuenta las ventajas y desventajas de los distintos enfoques. Consulte el «Ejemplo de ventana RHI» y compárelo con el «Ejemplo de widget RHI sencillo» para obtener más detalles sobre ambos enfoques.
Al reasignar un QRhiWidget a una jerarquía de widgets que pertenece a una ventana diferente (widget de nivel superior), o al convertir el propio QRhiWidget en uno de nivel superior (estableciendo el padre en nullptr), se modifica el QRhi asociado (y, potencialmente, se destruye el anterior), mientras que el QRhiWidget sigue activo y en buen estado. Para permitir esto, se espera que las implementaciones robustas de QRhiWidget reimplementen también la función virtual ` releaseResources()` y liberen sus recursos ` QRhi ` tal y como lo hacen en el destructor. El ejemplo «Cube RHI Widget» lo ilustra en la práctica.
Aunque no se trata de un caso de uso principal, QRhiWidget también permite incorporar código de renderizado que utilice directamente una API de gráficos 3D como Vulkan, Metal, Direct 3D u OpenGL. Consulte QRhiCommandBuffer::beginExternal() para obtener más detalles sobre cómo registrar comandos nativos dentro de una pasada de renderizado de QRhi, así como QRhiTexture::createFrom() para conocer cómo envolver una textura nativa existente y utilizarla posteriormente con QRhi en una pasada de renderizado posterior. Sin embargo, hay que tener en cuenta que la configurabilidad de la API gráfica subyacente (sus características de dispositivo o contexto, capas, extensiones, etc.) será limitada, ya que el objetivo principal de QRhiWidget es proporcionar un entorno adecuado para el código de renderizado basado en QRhi, y no habilitar motores de renderizado externos arbitrarios y potencialmente complejos.
Véase también QRhi, QShader, QOpenGLWidget, Ejemplo sencillo de widget RHI y Ejemplo de widget RHI de cubo.
Documentación sobre tipos de miembros
enum class QRhiWidget::Api
Especifica la API 3D y el backend « QRhi » que se van a utilizar
| Constante | Valor |
|---|---|
QRhiWidget::Api::Null | 0 |
QRhiWidget::Api::OpenGL | 1 |
QRhiWidget::Api::Metal | 2 |
QRhiWidget::Api::Vulkan | 3 |
QRhiWidget::Api::Direct3D11 | 4 |
QRhiWidget::Api::Direct3D12 | 5 |
Véase también QRhi.
enum class QRhiWidget::TextureFormat
Especifica el formato de la textura en la que se representa el « QRhiWidget ».
| Constante | Valor | Descripción |
|---|---|---|
QRhiWidget::TextureFormat::RGBA8 | 0 | Véase QRhiTexture::RGBA8. |
QRhiWidget::TextureFormat::RGBA16F | 1 | Véase « QRhiTexture::RGBA16F ». |
QRhiWidget::TextureFormat::RGBA32F | 2 | Véase QRhiTexture::RGBA32F. |
QRhiWidget::TextureFormat::RGB10A2 | 3 | Véase QRhiTexture::RGB10A2. |
Véase también QRhiTexture.
Documentación de la propiedad
autoRenderTarget : bool
La configuración actual para el mantenimiento automático del búfer de profundidad-estencil y del destino de renderizado.
Por defecto, el valor es « true ».
colorBufferFormat : TextureFormat
Esta propiedad controla el formato de la textura (o buffer de renderizado) utilizada como búfer de color. El valor por defecto es TextureFormat::RGBA8. QRhiWidget admite el renderizado en un subconjunto de los formatos compatibles con QRhiTexture. Solo deben especificarse los formatos que QRhi::isTextureFormatSupported() indique que son compatibles; de lo contrario, el renderizado no funcionará.
Nota: Establecer un nuevo formato cuando el widget ya está inicializado y se ha renderizado implica que todos los objetos QRhiGraphicsPipeline creados por el renderizador pueden quedar inutilizables, si el QRhiRenderPassDescriptor asociado resulta ahora incompatible debido al diferente formato de textura. De forma similar a cambiar sampleCount dinámicamente, esto significa que las implementaciones de initialize() o render() deben encargarse entonces de liberar los pipelines existentes y crear otros nuevos.
Funciones de acceso:
| QRhiWidget::TextureFormat | colorBufferFormat() const |
| void | setColorBufferFormat(QRhiWidget::TextureFormat format) |
Señal del notificador:
| void | colorBufferFormatChanged(QRhiWidget::TextureFormat format) |
fixedColorBufferSize : QSize
El tamaño fijo, en píxeles, de la textura asociada al « QRhiWidget ». Es relevante cuando se desea un tamaño de textura fijo que no dependa del tamaño del widget. Este tamaño no afecta a la geometría del widget (su tamaño y ubicación dentro de la ventana de nivel superior), lo que significa que el contenido de la textura aparecerá estirado (ampliado) o reducido en el área del widget.
Por ejemplo, establecer un tamaño que sea exactamente el doble del tamaño (en píxeles) del widget equivale, en la práctica, a realizar un supermuestreo 2x (renderizar al doble de la resolución y, a continuación, reducir implícitamente la escala al aplicar la textura al cuadrante correspondiente al widget en la ventana). Por otro lado, establecer un tamaño que sea la mitad del del widget equivale, en la práctica, a renderizar a la mitad de la resolución y, a continuación, ampliar los resultados.
Por defecto, el valor es un ` QSize` nulo. Un ` QSize ` nulo o vacío significa que el tamaño de la textura sigue el del ` QRhiWidget`. (texture size = widget size * device pixel ratio).
Nota: La relación de píxeles del dispositivo (el factor de escala del compositor del sistema) puede tener un gran impacto en el rendimiento, ya que un factor de escala de 2 (200 %) implica renderizar al doble de resolución, es decir, al doble de lo que el desarrollador y el diseñador de la interfaz de usuario perciben como el tamaño del widget, y luego reducir efectivamente la escala del contenido, de forma similar a lo que ocurre al establecer esta propiedad al doble del tamaño en píxeles del widget en un sistema donde la relación de píxeles del dispositivo es 1. Por lo tanto, se espera que esta propiedad se utilice en contadas ocasiones con tamaños superiores al tamaño en píxeles del widget, ya que muchos sistemas de escritorio modernos no tienen ni la necesidad ni el margen de rendimiento para ello, cuando el sistema ya utiliza de por sí una relación de píxeles del dispositivo superior a 1. En cambio, el principal caso de uso de esta propiedad es establecer un tamaño menor, con el fin de renderizar a una resolución razonablemente menor en lugar de seguir ciegamente la geometría de la ventana, por muy grande que sea esta.
Funciones de acceso:
| QSize | fixedColorBufferSize() const |
| void | setFixedColorBufferSize(QSize pixelSize) |
| void | setFixedColorBufferSize(int w, int h) |
Señal de notificador:
| void | fixedColorBufferSizeChanged(const QSize &pixelSize) |
mirrorVertically : bool
Cuando está activada, invierte la imagen alrededor del eje X al superponer la textura de fondo de « QRhiWidget » con el resto del contenido del widget en la ventana de nivel superior.
El valor por defecto es false.
Funciones de acceso:
| bool | isMirrorVerticallyEnabled() const |
| void | setMirrorVertically(bool enabled) |
Señal del notificador:
| void | mirrorVerticallyChanged(bool enabled) |
sampleCount : int
Esta propiedad controla el número de muestras para el antialiasing de múltiples muestras (MSAA). Por defecto, el valor es « 1 », lo que significa que el MSAA está desactivado.
Los valores válidos son 1, 4, 8 y, en ocasiones, 16 y 32. Se puede utilizar QRhi::supportedSampleCounts() para consultar los recuentos de muestras admitidos en tiempo de ejecución, pero normalmente las aplicaciones deben solicitar 1 (sin MSAA), 4x (MSAA normal) u 8x (MSAA alto).
Nota: Establecer un nuevo valor implica que todos los objetos ` QRhiGraphicsPipeline ` creados por el renderizador deben utilizar el mismo número de muestras a partir de ese momento. Los objetos ` QRhiGraphicsPipeline ` existentes creados con un número de muestras diferente ya no deben utilizarse. Cuando el valor cambia, todos los búferes de color y de profundidad-plantilla se destruyen y se recrean automáticamente, y se vuelve a invocar ` initialize()`. Sin embargo, cuando ` autoRenderTarget ` es ` false`, corresponderá a la aplicación gestionar esto en lo que respecta al búfer de profundidad-plantilla o a los búferes de color adicionales.
Cambiar el número de muestras del valor predeterminado 1 a un valor superior implica que colorTexture() pasa a ser nullptr y que msaaColorBuffer() comienza a devolver un objeto válido. Volver a 1 (o 0) implica lo contrario: en la siguiente llamada a initialize(), msaaColorBuffer() devolverá nullptr, mientras que colorTexture() volverá a ser válido. Además, resolveTexture() devuelve un QRhiTexture válido (no multimuestra) siempre que el número de muestras sea superior a 1 (es decir, cuando se utilice MSAA).
Funciones de acceso:
| int | sampleCount() const |
| void | setSampleCount(int samples) |
Señal de notificación:
| void | sampleCountChanged(int samples) |
Véase también msaaColorBuffer() y resolveTexture().
Documentación de funciones miembro
[explicit] QRhiWidget::QRhiWidget(QWidget *parent = nullptr, Qt::WindowFlags f = {})
Crea un widget que es un elemento secundario de « parent », con los indicadores del widget establecidos en « f ».
[override virtual noexcept] QRhiWidget::~QRhiWidget()
Destructor.
QRhiWidget::Api QRhiWidget::api() const
Devuelve la API gráfica configurada actualmente (backend «QRhi »).
Véase también setApi().
[protected] QRhiTexture *QRhiWidget::colorTexture() const
Devuelve la textura que actúa como búfer de color para el widget.
Solo debe llamarse desde initialize() y render().
A diferencia del búfer de profundidad-estencil y de ` QRhiRenderTarget`, esta textura está siempre disponible y la gestiona ` QRhiWidget`, independientemente del valor de ` autoRenderTarget`.
Nota: Cuando sampleCount es mayor que 1, y por lo tanto está habilitado el antialiasing multimuestra, el valor devuelto es nullptr. En su lugar, consulta el QRhiRenderBuffer llamando a msaaColorBuffer().
Nota: El tamañode la textura de fondo y el número de muestras también se pueden consultar a través del valor QRhiRenderTarget devuelto por renderTarget(). Esto puede resultar más cómodo y compacto que consultarlo a través de QRhiTexture o QRhiRenderBuffer, ya que funciona independientemente de si se utiliza el multisampling o no.
Véanse también msaaColorBuffer(), depthStencilBuffer(), renderTarget() y resolveTexture().
[protected] QRhiRenderBuffer *QRhiWidget::depthStencilBuffer() const
Devuelve el búfer de profundidad y estencil utilizado por el renderizado del widget.
Solo debe llamarse desde ` initialize()` y ` render()`.
Solo está disponible cuando autoRenderTarget es true. De lo contrario, el valor devuelto es nullptr y corresponde a la reimplementación de initialize() crear y gestionar un búfer de profundidad-estencil y un QRhiTextureRenderTarget.
Véanse también colorTexture() y renderTarget().
[override virtual protected] bool QRhiWidget::event(QEvent *e)
Reimplementa: QWidget::event(QEvent *event).
[signal] void QRhiWidget::frameSubmitted()
Esta señal se emite una vez que la ventana de nivel superior del widget ha finalizado la composición y se encuentra en el estado « submitted a frame ».
QImage QRhiWidget::grabFramebuffer() const
Genera un nuevo fotograma, lee de nuevo el contenido de la textura y lo devuelve como un ` QImage`.
Cuando se produce un error, se devuelve un objeto ` QImage ` nulo.
El ` QImage ` devuelto tendrá un formato de ` QImage::Format_RGBA8888`, ` QImage::Format_RGBA16FPx4`, ` QImage::Format_RGBA32FPx4` o ` QImage::Format_BGR30`, dependiendo de ` colorBufferFormat()`.
QRhiWidget no conoce el enfoque del renderizador respecto a la mezcla y la composición y, por lo tanto, no puede saber si la salida tiene el alfa premultiplicado en los valores de color RGB. Por ello, los formatos _Premultiplied y QImage nunca se utilizan para el QImage devuelto, incluso cuando sería lo adecuado. Corresponde a quien realiza la llamada reinterpretar los datos resultantes como considere oportuno.
Nota: Esta función también se puede invocar cuando el QRhiWidget no está añadido a una jerarquía de widgets perteneciente a una ventana de nivel superior en pantalla. Esto permite generar una imagen a partir de un renderizado 3D fuera de pantalla.
La función se denomina grabFramebuffer() para mantener la coherencia con QOpenGLWidget y QQuickWidget. No es la única forma de obtener datos de imagen del lado de la CPU a partir del contenido de QRhiWidget: llamar a QWidget::grab() sobre un QRhiWidget, o un antepasado del mismo, también funciona (devuelve un QPixmap). Además de trabajar directamente con QImage, otra ventaja de grabFramebuffer() es que puede ofrecer un rendimiento ligeramente superior, simplemente porque no tiene que pasar por el resto de la infraestructura de QWidget, sino que puede activar directamente el renderizado de un nuevo fotograma y, a continuación, realizar la lectura.
Véase también setColorBufferFormat().
[virtual protected] void QRhiWidget::initialize(QRhiCommandBuffer *cb)
Se invoca cuando el widget se inicializa por primera vez, cuando cambia el tamaño, el formato o el número de muestras de la textura asociada, o cuando el objeto « QRhi » y la textura cambian por cualquier motivo. Se espera que la función mantenga (cree si aún no se ha creado, ajuste y vuelva a generar si el tamaño ha cambiado) los recursos gráficos utilizados por el código de renderizado en ` render()`.
Para consultar el objeto « QRhi », « QRhiTexture » y otros objetos relacionados, llame a « rhi()», « colorTexture()», « depthStencilBuffer()» y « renderTarget()».
Cuando cambia el tamaño del widget, el objeto ` QRhi `, la textura del búfer de color y los objetos del búfer de profundidad y del búfer de plantilla son todos las mismas instancias (por lo que los métodos de lectura devuelven los mismos punteros) que antes, pero es probable que los búferes de color y de profundidad/plantilla se hayan reconstruido, lo que significa que ` size ` y el recurso de textura nativo subyacente pueden ser diferentes a los de la última invocación.
Las reimplementaciones también deben estar preparadas para que el objeto ` QRhi ` y la textura del búfer de color puedan cambiar entre las invocaciones de esta función. Un caso especial en el que los objetos serán diferentes es cuando se realiza un ` grabFramebuffer()` con un widget que aún no se muestra y, a continuación, se hace visible el widget en pantalla dentro de un widget de nivel superior. En ese caso, la captura se realizará con un ` QRhi ` específico que, posteriormente, se sustituirá por el ` QRhi ` asociado a la ventana de nivel superior en las siguientes invocaciones de `initialize()` y ` render()`. Otro caso más habitual es cuando se cambia la ventana padre del widget para que pertenezca a una nueva ventana de nivel superior. En este caso, el ` QRhi ` y todos los recursos relacionados gestionados por el ` QRhiWidget ` serán instancias diferentes a las anteriores en la llamada posterior a esta función. Por lo tanto, es importante que todos los recursos ` QRhi ` existentes, creados previamente por la subclase, se destruyan, ya que pertenecen al ` QRhi ` anterior, que el widget ya no debería utilizar.
Cuando ` autoRenderTarget ` es ` true` —que es el valor por defecto—, se crean y gestionan automáticamente un `depth-stencil` QRhiRenderBuffer y un ` QRhiTextureRenderTarget ` asociados a ` colorTexture()` (o ` msaaColorBuffer()`) y al búfer de profundidad-estencil. Las reimplementaciones de `initialize()` y ` render()` pueden consultar esos objetos mediante ` depthStencilBuffer()` y ` renderTarget()`. Cuando ` autoRenderTarget ` se establece en ` false`, estos objetos ya no se crean ni se gestionan automáticamente. En su lugar, corresponderá a la implementación de `initialize()` crear los búferes y configurar el destino de renderizado según considere oportuno. Al gestionar manualmente adjuntos adicionales de color o profundidad-plantilla para el destino de renderizado, su tamaño y número de muestras deben ajustarse siempre al tamaño y número de muestras de ` colorTexture()` / ` msaaColorBuffer()`, ya que, de lo contrario, podrían producirse errores de renderizado o de validación de la API 3D.
Se espera que los recursos gráficos creados por la subclase se liberen en la implementación del destructor de la subclase.
cb es el « QRhiCommandBuffer » del fotograma actual del widget. La función se invoca mientras se graba un fotograma, pero sin un paso de renderizado activo. El búfer de comandos se proporciona principalmente para permitir poner en cola resource updates sin tener que recurrir a render().
Véase también render().
bool QRhiWidget::isDebugLayerEnabled() const
Devuelve «true» si se solicitará una capa de depuración o validación, siempre que sea aplicable a la API gráfica que se esté utilizando.
Véase también setDebugLayerEnabled().
[protected] QRhiRenderBuffer *QRhiWidget::msaaColorBuffer() const
Devuelve el búfer de renderizado que actúa como búfer de color multisample para el widget.
Solo debe invocarse desde ` initialize()` y ` render()`.
Cuando sampleCount es mayor que 1, y por lo tanto el antialiasing multisample está habilitado, el QRhiRenderBuffer devuelto tiene un recuento de muestras coincidente y actúa como búfer de color. Las tuberías gráficas utilizadas para renderizar en este búfer deben crearse con el mismo recuento de muestras, y el recuento de muestras del búfer de profundidad-plantilla también debe coincidir. Se espera que el contenido multimuestra se resuelva en la textura devuelta por ` resolveTexture()`. Cuando ` autoRenderTarget ` es ` true`, ` renderTarget()` se configura automáticamente para ello, estableciendo `msaaColorBuffer()` como ` renderbuffer ` del accesorio de color 0 y ` resolveTexture()` como su ` resolveTexture`.
Cuando no se utiliza MSAA, el valor de retorno es ` nullptr`. En ese caso, utilice ` colorTexture()` en su lugar.
Dependiendo de la API de gráficos 3D subyacente, puede que no haya ninguna diferencia práctica entre las texturas multimuestra y los búferes de renderizado de color con un número de muestras superior a 1 (QRhi puede que simplemente asigne ambos al mismo tipo de recurso nativo). Sin embargo, algunas API más antiguas pueden diferenciar entre texturas y búferes de renderizado. Para ser compatible con OpenGL ES 3.0, donde hay disponibles búferes de renderizado multimuestra, pero no texturas multimuestra, QRhiWidget siempre realiza MSAA utilizando un QRhiRenderBuffer multimuestra como anexo de color (y nunca un QRhiTexture multimuestra).
Nota: El tamañode la textura de fondo y el número de muestras también pueden consultarse a través del objeto ` QRhiRenderTarget ` devuelto por ` renderTarget()`. Esto puede resultar más cómodo y compacto que consultarlo a partir de ` QRhiTexture ` o ` QRhiRenderBuffer`, ya que funciona independientemente de si se utiliza el multimuestreo o no.
Véanse también colorTexture(), depthStencilBuffer(), renderTarget() y resolveTexture().
[override virtual protected] void QRhiWidget::paintEvent(QPaintEvent *e)
Reimplementa: QWidget::paintEvent(QPaintEvent *event).
Gestiona los eventos de pintura.
Al llamar a ` QWidget::update()` se envía un evento de pintura ` e`, lo que a su vez invoca esta función. El envío del evento es asíncrono y tendrá lugar en algún momento después de que se regrese de ` update()`. A continuación, tras algunos preparativos, esta función llamará a la función virtual ` render()` para actualizar el contenido de la textura asociada a ` QRhiWidget`. A continuación, la ventana de nivel superior del widget compondrá la textura con el resto de la ventana.
[virtual protected] void QRhiWidget::releaseResources()
Se invoca cuando surge la necesidad de liberar anticipadamente los recursos gráficos.
Normalmente, esto no ocurre con un « QRhiWidget » que se añade a la jerarquía de hijos de un widget de nivel superior y que, a continuación, permanece allí durante el resto de su vida útil y la del widget de nivel superior. Por lo tanto, en muchos casos no es necesario reimplementar esta función, por ejemplo, porque la aplicación solo tiene un único widget de nivel superior (ventana nativa). Sin embargo, cuando se produce un cambio de padre del widget (o de uno de sus antepasados), será necesario reimplementar esta función en subclases de ` QRhiWidget ` robustas y bien escritas.
Cuando se llama a esta función, se espera que la implementación destruya todos los recursos de QRhi (objetos de tipoQRhiBuffer, QRhiTexture, etc.), de forma similar a como se espera que lo haga en el destructor. También será necesario poner a nulo, utilizar un puntero inteligente o establecer un indicador de « resources-invalid », ya que initialize() acabará llamándose posteriormente. Sin embargo, ten en cuenta que aplazar la liberación de recursos hasta la posterior llamada a initialize() es incorrecto. Si se llama a esta función, el recurso debe liberarse antes de regresar. Ten en cuenta también que la implementación de esta función no sustituye al destructor de la clase (ni a los punteros inteligentes): los recursos gráficos deben liberarse en ambos casos.
Consulta el ejemplo del widget Cube RHI para ver cómo funciona esto en la práctica. Allí, el botón que alterna el QRhiWidget entre ser un widget hijo (por tener un widget padre) y ser un widget de nivel superior (por no tener ningún widget padre) activará la llamada a esta función, ya que el widget de nivel superior asociado, la ventana nativa, y QRhi cambian durante el ciclo de vida de QRhiWidget, con lo que el QRhi utilizado anteriormente se destruye, lo que implica una liberación anticipada de los recursos asociados gestionados por el QRhiWidget, que sigue activo.
Otro caso en el que se llama a esta función es cuando se utiliza ` grabFramebuffer()` con un ` QRhiWidget ` que no se ha añadido a una ventana visible, es decir, cuando la representación se realiza fuera de pantalla. Si posteriormente este QRhiWidget se hace visible o se añade a una jerarquía de widgets visible, el QRhi asociado pasará de ser el temporal utilizado para la representación fuera de pantalla al dedicado a la ventana, lo que también activará esta función.
Véase también initialize().
[virtual protected] void QRhiWidget::render(QRhiCommandBuffer *cb)
Se invoca cuando es necesario actualizar el contenido del widget (es decir, el contenido de la textura).
Siempre se realiza al menos una llamada a ` initialize()` antes de que se llame a esta función.
Para solicitar actualizaciones, llama a ` QWidget::update()`. Llamar a ` update()` desde dentro de `render()` provocará una actualización continua, limitada por la sincronización vertical (vsync).
cb QRhiCommandBuffer es la función de renderizado del fotograma actual del widget. La función se invoca mientras se graba un fotograma, pero sin un paso de renderizado activo.
Véase también initialize().
[signal] void QRhiWidget::renderFailed()
Esta señal se emite cada vez que el widget debe renderizarse en su textura de fondo (ya sea debido a un ` widget update ` o a una llamada a ` grabFramebuffer()`), pero no hay ninguna ` QRhi ` que el widget pueda utilizar, probablemente debido a problemas relacionados con la configuración gráfica.
Esta señal puede emitirse varias veces cuando surge un problema. No se debe dar por sentado que solo se emite una vez. Se debe conectar con ` Qt::SingleShotConnection ` si se desea que el código de gestión de errores reciba la notificación únicamente una vez.
[protected] QRhiRenderTarget *QRhiWidget::renderTarget() const
Devuelve el objeto de destino de renderizado que debe utilizarse con ` QRhiCommandBuffer::beginPass()` en las reimplementaciones de ` render()`.
Solo debe llamarse desde ` initialize()` y ` render()`.
Solo está disponible cuando autoRenderTarget es true. De lo contrario, el valor devuelto es nullptr y corresponde a la reimplementación de initialize() crear y gestionar un búfer de profundidad-estencil y un QRhiTextureRenderTarget.
Al crear un ` graphics pipelines`, se necesita un ` QRhiRenderPassDescriptor `. Este se puede obtener del ` QRhiTextureRenderTarget ` devuelto llamando a ` renderPassDescriptor()`.
Véase también colorTexture() y depthStencilBuffer().
[override virtual protected] void QRhiWidget::resizeEvent(QResizeEvent *e)
Reimplementa: QWidget::resizeEvent(QResizeEvent *event).
Gestiona los eventos de cambio de tamaño que se pasan en el parámetro de evento ` e `. Llama a la función virtual ` initialize()`.
Nota: Evita sobrescribir esta función en clases derivadas. Si eso no es posible, asegúrate de que también se invoque la implementación de QRhiWidget. De lo contrario, el objeto de textura subyacente y los recursos relacionados no se redimensionarán correctamente, lo que provocará un renderizado incorrecto.
[protected] QRhiTexture *QRhiWidget::resolveTexture() const
Devuelve la textura no multisample a la que se resuelve el contenido multisample.
El resultado es ` nullptr ` cuando el antialiasing multimuestra no está habilitado.
Solo debe llamarse desde ` initialize()` y ` render()`.
Con el MSAA activado, esta es la textura que se compone con el resto del contenido de « QWidget » en pantalla. Sin embargo, el renderizado de « QRhiWidget » debe tener como destino el « QRhiRenderBuffer » (multimuestra) devuelto por « msaaColorBuffer()». Cuando « autoRenderTarget » es « true », de esto se encarga el « QRhiRenderTarget » devuelto por « renderTarget()». De lo contrario, corresponde al código de la subclase configurar correctamente un objeto de destino de renderizado con el búfer de color y las texturas de resolución.
Véase también ` colorTexture()`.
[protected] QRhi *QRhiWidget::rhi() const
Devuelve el objeto ` QRhi ` actual.
Solo debe invocarse desde ` initialize()` y ` render()`.
void QRhiWidget::setApi(QRhiWidget::Api api)
Establece la API gráfica y el backend de QRhi que se van a utilizar en api.
Advertencia: Esta función debe llamarse con suficiente antelación, antes de que el widget se añada a una jerarquía de widgets y se muestre en pantalla. Por ejemplo, se recomienda llamar a la función en el constructor de la subclase. Si se llama demasiado tarde, la función no tendrá ningún efecto.
El valor por defecto depende de la plataforma: Metal en macOS e iOS, Direct 3D 11 en Windows y OpenGL en el resto de casos.
El ` api ` solo se puede establecer una vez para el widget y su ventana de nivel superior; una vez hecho esto y surta efecto, la ventana solo podrá utilizar esa API y ese backend ` QRhi ` para renderizar. Intentar establecer otro valor, o añadir otro ` QRhiWidget ` con un ` api ` diferente, no funcionará como se espera.
Véanse también setColorBufferFormat(), setDebugLayerEnabled() y api().
[protected] void QRhiWidget::setAutoRenderTarget(bool enabled)
Determina si el widget crea y mantiene automáticamente un búfer de profundidad-estencil QRhiRenderBuffer y un búfer de QRhiTextureRenderTarget. El valor por defecto es true.
En modo automático, el tamaño y el número de muestras del búfer de profundidad-estencil siguen la configuración de la textura del búfer de color. En modo no automático, las funciones ` renderTarget()` y ` depthStencilBuffer()` siempre devuelven ` nullptr `, por lo que corresponde a la implementación de la aplicación de ` initialize()` encargarse de configurar y gestionar estos objetos.
Llama a esta función con enabled establecido en false desde el principio, por ejemplo, en el constructor de la clase derivada, para desactivar el modo automático.
void QRhiWidget::setDebugLayerEnabled(bool enable)
Solicita la capa de depuración o validación de la API gráfica subyacente cuando ` enable ` es verdadero.
Advertencia: Esta función debe llamarse con suficiente antelación, antes de que el widget se añada a una jerarquía de widgets y se muestre en pantalla. Por ejemplo, se recomienda llamar a la función en el constructor de la subclase. Si se llama demasiado tarde, la función no tendrá ningún efecto.
Aplicable a Vulkan y Direct 3D.
Por defecto, está desactivada.
Véase también setApi() y isDebugLayerEnabled().
© 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.