En esta página

Ejemplo de ventana RHI

Este ejemplo muestra cómo crear una aplicación mínima basada en « QWindow » utilizando « QRhi ».

Captura de pantalla de un ejemplo

Qt 6.6 comienza a ofrecer su API 3D acelerada y su capa de abstracción de shaders también para su uso en aplicaciones. Las aplicaciones pueden ahora utilizar las mismas clases de gráficos 3D que utiliza el propio Qt para implementar el grafo de escena de Qt Quick o el motor 3D de Qt Quick. En versiones anteriores de Qt, QRhi y las clases relacionadas eran todas API privadas. A partir de la versión 6.6, estas clases se encuentran en una categoría similar a la de la familia de clases QPA: ni totalmente públicas ni privadas, sino algo intermedio, con una garantía de compatibilidad más limitada en comparación con las API públicas. Por otro lado, QRhi y las clases relacionadas cuentan ahora con documentación completa, de forma similar a las API públicas.

Existen varias formas de utilizar QRhi; el ejemplo que se muestra aquí ilustra el enfoque de más bajo nivel: orientarse a un QWindow, sin utilizar Qt Quick, Qt Quick 3D ni Widgets de ningún tipo, y configurar toda la infraestructura de renderizado y gestión de ventanas en la aplicación.

Por el contrario, al escribir una aplicación QML con Qt Quick o Qt Quick 3D y querer añadirle renderizado basado en QRhi, dicha aplicación se basará en la infraestructura de ventanas y renderizado que Qt Quick ya haya inicializado, y es probable que consulte una instancia existente de QRhi a través de QQuickWindow. Allí, el manejo de QRhi::create(), los aspectos específicos de la plataforma o la API, como Vulkan instances, o la gestión correcta de expose y los eventos de cambio de tamaño de la ventana, todo ello se gestiona mediante Qt Quick. En cambio, en este ejemplo, todo eso lo gestiona y se encarga de ello la propia aplicación.

Nota: En el caso concretode las aplicaciones basadas en QWidget, cabe señalar que QWidget::createWindowContainer() permite incrustar un QWindow (respaldado por una ventana nativa) en la interfaz de usuario basada en widgets. Por lo tanto, la clase HelloWindow de este ejemplo es reutilizable en aplicaciones basadas en QWidget, siempre que también se haya realizado la inicialización necesaria desde main().

Compatibilidad con la API 3D

La aplicación es compatible con todas las QRhi backends actuales. Cuando no se especifican argumentos de línea de comandos, se utilizan los valores predeterminados específicos de cada plataforma: Direct 3D 11 en Windows, OpenGL en Linux y Metal en macOS/iOS.

Al ejecutar la aplicación con el comando « --help », se muestran las opciones de línea de comandos disponibles:

  • -d o –d3d11 para Direct 3D 11
  • -D o –d3d12 para Direct 3D 12
  • -m o –metal para Metal
  • -v o –vulkan para Vulkan
  • -g o –opengl para OpenGL u OpenGL ES
  • -n o –null para el Null backend

Notas sobre el sistema de compilación

Esta aplicación se basa exclusivamente en el módulo Qt GUI. No utiliza Qt Widgets ni Qt Quick.

Para acceder a las API de RHI, que están disponibles para todas las aplicaciones Qt pero que tienen una compatibilidad limitada, el comando CMake « target_link_libraries » incluye « Qt6::GuiPrivate ». Esto es lo que permite que la instrucción de inclusión « #include <rhi/qrhi.h> » se compile correctamente.

Características

La aplicación incluye las siguientes características:

  • Un « QWindow » redimensionable,
  • una cadena de intercambio y un búfer de profundidad-estencil que se adaptan correctamente al tamaño de la ventana,
  • lógica para inicializar, renderizar y desmontar en el momento adecuado en función de eventos como « QExposeEvent » y « QPlatformSurfaceEvent »,
  • el renderizado de un cuadrilátero con textura a pantalla completa, utilizando una textura cuyo contenido se genera en un « QImage » mediante « QPainter » (utilizando el motor de pintura rasterizada, es decir, la generación de los datos de píxeles de la imagen se realiza íntegramente en la CPU, y dichos datos se cargan posteriormente en una textura de la GPU),
  • renderizar un triángulo con la mezcla y la comprobación de profundidad activadas, utilizando una proyección en perspectiva, al tiempo que se aplica una transformación del modelo que cambia en cada fotograma,
  • un bucle de renderizado eficiente y multiplataforma utilizando requestUpdate().

Shaders

La aplicación utiliza dos conjuntos de pares de sombreadores de vértices y de fragmentos:

  • uno para el cuadrilátero a pantalla completa, que no utiliza entradas de vértices y en el que el sombreador de fragmentos muestrea una textura (quad.vert, quad.frag),
  • y otro par para el triángulo, en el que las posiciones y los colores de los vértices se proporcionan en un búfer de vértices y la matriz de proyección modelview se proporciona en un búfer de uniformes (color.vert, color.frag).

Los shaders están escritos como código fuente GLSL compatible con Vulkan.

Al tratarse de un ejemplo del módulo Qt GUI, este ejemplo no puede tener ninguna dependencia del módulo Qt Shader Tools. Esto significa que no se pueden utilizar funciones auxiliares de CMake como qt_add_shaders(). Por lo tanto, el ejemplo incluye los archivos « .qsb » preprocesados en la carpeta « shaders/prebuilt », y estos se incorporan al ejecutable mediante « qt_add_resources ». Este enfoque no se recomienda generalmente para aplicaciones; se aconseja utilizar «qt_add_shaders()», lo que evita tener que generar y gestionar manualmente los archivos « .qsb ».

Para generar los archivos .qsb de este ejemplo, se utilizó el comando qsb --qt6 color.vert -o prebuilt/color.vert.qsb etc. Esto da lugar a una compilación a SPIR-V y, a continuación, a una transpilación a GLSL (100 es y 120), HLSL (5.0) y MSL (1.2). A continuación, todas las versiones de los shaders se empaquetan juntas en un archivo QShader y se serializan en el disco.

Inicialización específica de la API

En algunas de las API 3D, la función `main()` debe realizar la inicialización específica de la API correspondiente; por ejemplo, crear un ` QVulkanInstance ` cuando se utiliza Vulkan. En el caso de OpenGL, debemos asegurarnos de que haya un búfer de profundidad disponible, lo cual se realiza mediante QSurfaceFormat. Estos pasos no entran dentro del ámbito de QRhi, ya que los backends de QRhi para OpenGL o Vulkan se basan en las funciones existentes de Qt, como QOpenGLContext o QVulkanInstance.

   // Para OpenGL, para garantizar que haya un búfer de profundidad/estencil para la ventana.
    // Con otras API, esto queda bajo el control de la aplicación (QRhiRenderBuffer, etc.)
    // por lo que no se necesita ninguna configuración especial para ellas.
    QSurfaceFormat fmt;
    fmt.setDepthBufferSize(24);
    fmt.setStencilBufferSize(8);
   // Caso especial de macOS para permitir el uso de OpenGL en este sistema.
    // (aunque se recomienda utilizar Metal por defecto)
    // gl_VertexID es una característica de GLSL 130, por lo que el contexto predeterminado de OpenGL 2.1 
    // que obtenemos en macOS no es suficiente.
#ifdef Q_OS_MACOS
    fmt.setVersion(4, 1);
    fmt.setProfile(QSurfaceFormat::CoreProfile);
#endif
    QSurfaceFormat::setDefaultFormat(fmt);

    // Para Vulkan.
#if QT_CONFIG(vulkan)
    QVulkanInstance inst;
    if (graphicsApi== QRhi::Vulkan) {
        // Solicitar validación, si está disponible. Esto es totalmente opcional
        // y afecta al rendimiento, por lo que debe evitarse en entornos de producción.
        inst.setLayers({ "VK_LAYER_KHRONOS_validation" });
        // Funciona bien con QRhi.
        inst.setExtensions(QRhiVulkanInitParams::preferredInstanceExtensions());
        if (!inst.create()) {
            qWarning("Failed to create Vulkan instance, switching to OpenGL");
            graphicsApi = QRhi::OpenGLES2;
        }
    }
#endif

Nota: En el caso de Vulkan, fíjate en cómo se tiene en cuenta QRhiVulkanInitParams::preferredInstanceExtensions() para garantizar que se habiliten las extensiones adecuadas.

HelloWindow es una subclase de ` RhiWindow`, que a su vez es una subclase de ` QWindow`. ` RhiWindow ` contiene todo lo necesario para gestionar una ventana redimensionable con una cadena de intercambio (y un búfer de profundidad-estencil), y también es potencialmente reutilizable en otras aplicaciones. ` HelloWindow ` contiene la lógica de renderizado específica de esta aplicación de ejemplo en particular.

En el constructor de la subclase ` QWindow `, el tipo de superficie se establece en función de la API 3D seleccionada.

RhiWindow::RhiWindow(QRhi::Implementation graphicsApi)
    : m_graphicsApi(graphicsApi)
{
    switch (graphicsApi) {
    case QRhi::OpenGLES2:
        setSurfaceType(OpenGLSurface);
        break;
    case QRhi::Vulkan:
        setSurfaceType(VulkanSurface);
        break;
    case QRhi::D3D11:
    case QRhi::D3D12:
        setSurfaceType(Direct3DSurface);
        break;
    case QRhi::Metal:
        setSurfaceType(MetalSurface);
        break;
    case QRhi::Null:
        break; // RasterSurface
    }
}

La creación e inicialización de un objeto ` QRhi ` se implementa en `RhiWindow::init()`. Ten en cuenta que esto solo se invoca cuando la ventana está en modo « renderable », lo cual se indica mediante un ` expose event`.

Dependiendo de la API 3D que utilicemos, es necesario pasar la estructura `InitParams` adecuada a ` QRhi::create()`. Con OpenGL, por ejemplo, la aplicación debe crear una ` QOffscreenSurface ` (u otra ` QSurface`) y proporcionarla para su uso a ` QRhi`. Con Vulkan, se requiere un ` QVulkanInstance ` inicializado correctamente. Otros, como Direct 3D o Metal, no necesitan información adicional para poder inicializarse.

void RhiWindow::init()
{
    if (m_graphicsApi== QRhi::Null) {
        QRhiNullInitParams params;
        m_rhi.reset(QRhi::create(QRhi::Null, &params));
    }

#if QT_CONFIG(opengl)
    if (m_graphicsApi== QRhi::OpenGLES2) {
        m_fallbackSurface.reset(QRhiGles2InitParams::newFallbackSurface());
        QRhiGles2InitParams params;
        params.fallbackSurface = m_fallbackSurface.get();
        params.window = this;
        m_rhi.reset(QRhi::create(QRhi::OpenGLES2, &params));
    }
#endif

#if QT_CONFIG(vulkan)
    if (m_graphicsApi== QRhi::Vulkan) {
        QRhiVulkanInitParams params;
        params.inst = vulkanInstance();
        params.window = this;
        m_rhi.reset(QRhi::create(QRhi::Vulkan, &params));
    }
#endif

#ifdef Q_OS_WIN
    if (m_graphicsApi== QRhi::D3D11) {
        QRhiD3D11InitParams params;
        // Habilita la capa de depuración, si está disponible. Esto es opcional
        // y debe evitarse en las compilaciones de producción.
        params.enableDebugLayer = true;
        m_rhi.reset(QRhi::create(QRhi::D3D11, &params));
    } else if (m_graphicsApi== QRhi::D3D12) {
        QRhiD3D12InitParams params;
        // Habilita la capa de depuración, si está disponible. Esto es opcional
        // y debe evitarse en las compilaciones de producción.
        params.enableDebugLayer = true;
        m_rhi.reset(QRhi::create(QRhi::D3D12, &params));
    }
#endif

#if QT_CONFIG(metal)
    if (m_graphicsApi== QRhi::Metal) {
        QRhiMetalInitParams params;
        m_rhi.reset(QRhi::create(QRhi::Metal, &params));
    }
#endif

    if (!m_rhi)
        qFatal("Failed to create RHI backend");

Aparte de esto, todo lo demás —todo el código de renderizado— es totalmente multiplataforma y no contiene ramificaciones ni condiciones específicas de ninguna de las API 3D.

Exponer eventos

Lo que significa exactamente « renderable » depende de la plataforma. Por ejemplo, en macOS, una ventana que está totalmente oculta (completamente detrás de otra ventana) no se puede renderizar, mientras que en Windows el hecho de que esté oculta no tiene ninguna importancia. Afortunadamente, la aplicación no necesita ningún conocimiento especial al respecto: los complementos de plataforma de Qt abstraen las diferencias tras el evento «expose». Sin embargo, la reimplementación de ` exposeEvent()` también debe tener en cuenta que un tamaño de salida vacío (por ejemplo, anchura y altura iguales a 0) es algo que debe tratarse como una situación en la que no se puede renderizar. En Windows, por ejemplo, esto es lo que ocurre al minimizar la ventana. De ahí la comprobación basada en ` QRhiSwapChain::surfacePixelSize()`.

Esta implementación del manejo de eventos «expose» pretende ser robusta, segura y portátil. El propio Qt Quick también implementa una lógica muy similar en sus bucles de renderizado.

void RhiWindow::exposeEvent(QExposeEvent *)
{
    // initialize and start rendering when the window becomes usable for graphics purposes
    if (isExposed() && !m_initialized) {
        init();
        resizeSwapChain();
        m_initialized = true;
    }

    const QSize surfaceSize = m_hasSwapChain ? m_sc->surfacePixelSize() : QSize();

    // stop pushing frames when not exposed (or size is 0)
    if ((!isExposed() || (m_hasSwapChain && surfaceSize.isEmpty())) && m_initialized && !m_notExposed)
        m_notExposed = true;

    // Continue when exposed again and the surface has a valid size. Note that
    // surfaceSize can be (0, 0) even though size() reports a valid one, hence
    // trusting surfacePixelSize() and not QWindow.
    if (isExposed() && m_initialized && m_notExposed && !surfaceSize.isEmpty()) {
        m_notExposed = false;
        m_newlyExposed = true;
    }

    // always render a frame on exposeEvent() (when exposed) in order to update
    // immediately on window resize.
    if (isExposed() && !surfaceSize.isEmpty())
        render();
}

En RhiWindow::render(), que se invoca en respuesta al evento « UpdateRequest » generado por requestUpdate(), se lleva a cabo la siguiente comprobación para evitar que se intente renderizar cuando la inicialización de la cadena de intercambio haya fallado o cuando la ventana haya dejado de ser renderizable.

void RhiWindow::render()
{
    if (!m_hasSwapChain || m_notExposed)
        return;

Cadena de intercambio, búfer de profundidad-estencil y redimensionamiento

Para renderizar en el ` QWindow`, se necesita un ` QRhiSwapChain `. Además, también se crea un ` QRhiRenderBuffer ` que actúa como búfer de profundidad-estencil, ya que la aplicación muestra cómo se puede habilitar la comprobación de profundidad en una canalización gráfica. En algunas API 3D heredadas, la gestión del búfer de profundidad/estencil de una ventana forma parte de la API de interfaz del sistema de ventanas correspondiente (EGL, WGL, GLX, etc., lo que significa que el búfer de profundidad/plantilla se gestiona implícitamente junto con el window surface), mientras que con las API modernas la gestión del búfer de profundidad y plantilla para un destino de renderizado basado en ventanas no difiere de la de los destinos de renderizado fuera de pantalla. QRhi abstrae esto, pero para obtener el mejor rendimiento sigue siendo necesario indicar que el QRhiRenderBuffer es used with together with a QRhiSwapChain.

El « QRhiSwapChain » está asociado al « QWindow » y al búfer de profundidad/plantilla.

    std::unique_ptr<QRhiSwapChain> m_sc;
    std::unique_ptr<QRhiRenderBuffer> m_ds;
    std::unique_ptr<QRhiRenderPassDescriptor> m_rp;

    m_sc.reset(m_rhi->newSwapChain());
    m_ds.reset(m_rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil,
                                      QSize(), // no need to set the size here, due to UsedWithSwapChainOnly
                                      1,
                                      QRhiRenderBuffer::UsedWithSwapChainOnly));
    m_sc->setWindow(this);
    m_sc->setDepthStencil(m_ds.get());
    m_rp.reset(m_sc->newCompatibleRenderPassDescriptor());
    m_sc->setRenderPassDescriptor(m_rp.get());

Cuando cambia el tamaño de la ventana, también hay que redimensionar la cadena de intercambio. Esto se implementa en resizeSwapChain().

void RhiWindow::resizeSwapChain()
{
    m_hasSwapChain = m_sc->createOrResize(); // also handles m_ds

    const QSize outputSize = m_sc->currentPixelSize();
    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);
}

A diferencia de otras subclases de ` QRhiResource `, ` QRhiSwapChain ` presenta una semántica ligeramente diferente en lo que respecta a su función de creación. Tal y como sugiere su nombre, ` createOrResize()`, esta función debe llamarse siempre que se sepa que el tamaño de la ventana de salida puede estar desincronizado con respecto a la última inicialización de la cadena de intercambio. El ` QRhiRenderBuffer ` asociado para profundidad-estencil tiene su ` size ` establecido automáticamente, y ` create()` se invoca en él de forma implícita desde `createOrResize()` de la cadena de intercambio.

Este es también un buen momento para (re)calcular las matrices de proyección y de vista, ya que la proyección en perspectiva que hemos configurado depende de la relación de aspecto de la salida.

Nota: Para eliminar las diferencias entre sistemas de coordenadas, se consulta el « a backend/API-specific "correction" matrix » en QRhi y se integra en la matriz de proyección. Esto es lo que permite a la aplicación trabajar con datos de vértices al estilo de OpenGL, suponiendo un sistema de coordenadas con el origen en la esquina inferior izquierda.

La función resizeSwapChain() se invoca desde RhiWindow::render() cuando se detecta que el tamaño indicado actualmente ya no coincide con el utilizado en la última inicialización de la cadena de intercambio.

Consulte QRhiSwapChain::currentPixelSize() y QRhiSwapChain::surfacePixelSize() para obtener más detalles.

La compatibilidad con alta resolución (DPI) está integrada: los tamaños, tal y como indica su nombre, siempre se expresan en píxeles, teniendo en cuenta la resolución de la ventana ( scale factor ). A nivel de QRhi (y de la API 3D) no existe el concepto de escalado de alta resolución (DPI), todo se expresa siempre en píxeles. Esto significa que un « QWindow » con una « size() » de 1280x720 y un «devicePixelRatio()» de 2 es un «render target» (swapchain) con un tamaño (en píxeles) de 2560x1440.

    // If the window got resized or newly exposed, resize the swapchain. (the
    // newly-exposed case is not actually required by some platforms, but is
    // here for robustness and portability)
    //
    // This (exposeEvent + the logic here) is the only safe way to perform
    // resize handling. Note the usage of the RHI's surfacePixelSize(), and
    // never QWindow::size(). (the two may or may not be the same under the hood,
    // depending on the backend and platform)
    //
    if (m_sc->currentPixelSize() != m_sc->surfacePixelSize() || m_newlyExposed) {
        resizeSwapChain();
        if (!m_hasSwapChain)
            return;
        m_newlyExposed = false;
    }

Bucle de renderizado

La aplicación realiza el renderizado de forma continua, limitada por la frecuencia de presentación (vsync). Esto se garantiza llamando a ` requestUpdate()` desde `RhiWindow::render()` cuando se ha enviado el fotograma registrado actualmente.

    m_rhi->endFrame(m_sc.get());

    // Always request the next frame via requestUpdate(). On some platforms this is backed
    // by a platform-specific solution, e.g. CVDisplayLink on macOS, which is potentially
    // more efficient than a timer, queued metacalls, etc.
    requestUpdate();
}

Esto acaba dando lugar a la recepción de un evento UpdateRequest. Esto se gestiona en la reimplementación de event().

bool RhiWindow::event(QEvent *e)
{
    switch (e->type()) {
    case QEvent::UpdateRequest:
        render();
        break;

    case QEvent::PlatformSurface:
        // this is the proper time to tear down the swapchain (while the native window and surface are still around)
        if (static_cast<QPlatformSurfaceEvent *>(e)->surfaceEventType() == QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed)
            releaseSwapChain();
        break;

    default:
        break;
    }

    return QWindow::event(e);
}

Configuración de recursos y canalizaciones

La aplicación registra una única pasada de renderizado que emite dos llamadas de dibujo, con dos canalizaciones gráficas diferentes. Una es el «fondo», con la textura que contiene la imagen generada por QPainter; a continuación, se renderiza un único triángulo encima con la mezcla activada.

El búfer de vértices y el de uniformes utilizados con el triángulo se crean de esta manera. El tamaño del búfer de uniformes es de 68 bytes, ya que el shader especifica los miembros « mat4 » y « float » en el bloque de uniformes. Presta atención a las reglas de disposición de std140. En este ejemplo no supone ningún problema, ya que el miembro ` float `, que sigue al ` mat4 `, tiene la alineación correcta sin ningún relleno adicional; sin embargo, puede resultar relevante en otras aplicaciones, especialmente al trabajar con tipos como ` vec2 ` o ` vec3`. En caso de duda, plantéate consultar el archivo « QShaderDescription » para ver el « QShader », o, lo que suele resultar más cómodo, ejecuta la herramienta « qsb » sobre el archivo « .qsb » con el argumento « -d » para inspeccionar los metadatos en un formato legible para el usuario. La información mostrada incluye, entre otras cosas, los desplazamientos de los miembros del bloque uniforme, los tamaños y el tamaño total en bytes de cada bloque uniforme.

void HelloWindow::customInit()
{
    m_initialUpdates = m_rhi->nextResourceUpdateBatch();

    m_vbuf.reset(m_rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertexData)));
    m_vbuf->create();
    m_initialUpdates->uploadStaticBuffer(m_vbuf.get(), vertexData);

    static const quint32 UBUF_SIZE = 68;
    m_ubuf.reset(m_rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, UBUF_SIZE));
    m_ubuf->create();

Tanto el shader de vértices como el de fragmentos necesitan un búfer uniforme en el punto de enlace 0. Esto lo garantiza el objeto QRhiShaderResourceBindings. A continuación, se configura el canal de procesamiento gráfico con los shaders y una serie de datos adicionales. El ejemplo también se basa en una serie de valores predeterminados prácticos; por ejemplo, la topología de las primitivas es Triangles, pero ese es el valor predeterminado y, por lo tanto, no se establece explícitamente. Consulte QRhiGraphicsPipeline para obtener más detalles.

Además de especificar la topología y diversos estados, el canal también debe estar asociado a:

   m_colorTriSrb.reset(m_rhi->newShaderResourceBindings());
   static const QRhiShaderResourceBinding::StageFlags visibility =
           QRhiShaderResourceBinding::VertexStage | QRhiShaderResourceBinding::FragmentStage;
   m_colorTriSrb->setBindings({
           QRhiShaderResourceBinding::uniformBuffer(0, visibility, m_ubuf.get())
   });
   m_colorTriSrb->create();

   m_colorPipeline.reset(m_rhi->newGraphicsPipeline());
   // Enable depth testing; not quite needed for a simple triangle, but we
   // have a depth-stencil buffer so why not.
   m_colorPipeline->setDepthTest(true);
   m_colorPipeline->setDepthWrite(true);
   // Blend factors default to One, OneOneMinusSrcAlpha, which is convenient.
   QRhiGraphicsPipeline::TargetBlend premulAlphaBlend;
   premulAlphaBlend.enable = true;
   m_colorPipeline->setTargetBlends({ premulAlphaBlend });
   m_colorPipeline->setShaderStages({
       { QRhiShaderStage::Vertex, getShader(QLatin1String(":/color.vert.qsb")) },
       { QRhiShaderStage::Fragment, getShader(QLatin1String(":/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_colorPipeline->setVertexInputLayout(inputLayout);
   m_colorPipeline->setShaderResourceBindings(m_colorTriSrb.get());
   m_colorPipeline->setRenderPassDescriptor(m_rp.get());
   m_colorPipeline->create();

getShader() es una función auxiliar que carga un archivo .qsb y deserializa un QShader a partir de él.

static QShader getShader(const QString &name)
{
    QFile f(name);
    if (f.open(QIODevice::ReadOnly))
        return QShader::fromSerialized(f.readAll());

    return QShader();
}

El shader color.vert especifica lo siguiente como entradas de vértices:

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

Sin embargo, el código en C++ proporciona los datos de vértices como 2 valores flotantes para la posición, intercalados con 3 valores flotantes para el color. (x, y, r, g, b para cada vértice). Por eso el paso es 5 * sizeof(float) y las entradas para las posiciones 0 y 1 se especifican como Float2 y Float3, respectivamente. Esto es válido, y los valores « z » y « w » de la posición « vec4 » se establecerán automáticamente.

Representación

La grabación de un fotograma se inicia llamando a ` QRhi::beginFrame()` y finaliza llamando a ` QRhi::endFrame()`.

    QRhi::FrameOpResult result = m_rhi->beginFrame(m_sc.get());
    if (result== QRhi::FrameOpSwapChainOutOfDate) {
        resizeSwapChain();
        if (!m_hasSwapChain)
            return;
        result = m_rhi->beginFrame(m_sc.get());
    }
    if (result != QRhi::FrameOpSuccess) {
        qWarning("beginFrame failed with %d, will retry", result);
        requestUpdate();
        return;
    }

    customRender();

Algunos de los recursos (búferes, texturas) contienen datos estáticos en la aplicación, lo que significa que su contenido nunca cambia. El contenido del búfer de vértices, por ejemplo, se proporciona en la fase de inicialización y no se modifica posteriormente. Estas operaciones de actualización de datos se registran en m_initialUpdates. Cuando aún no se han ejecutado, los comandos de este lote de actualización de recursos se fusionan con el lote por fotograma.

void HelloWindow::customRender()
{
    QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();

    if (m_initialUpdates) {
        resourceUpdates->merge(m_initialUpdates);
        m_initialUpdates->release();
        m_initialUpdates = nullptr;
    }

Es necesario disponer de un lote de actualización de recursos por fotograma, ya que el contenido del búfer uniforme —con la matriz de modelo-vista-proyección y la opacidad— cambia en cada fotograma.

    m_rotation += 1.0f;
    QMatrix4x4 modelViewProjection = m_viewProjection;
    modelViewProjection.rotate(m_rotation, 0, 1, 0);
    resourceUpdates->updateDynamicBuffer(m_ubuf.get(), 0, 64, modelViewProjection.constData());
    m_opacity += m_opacityDir * 0.005f;
    if (m_opacity < 0.0f || m_opacity > 1.0f) {
        m_opacityDir *= -1;
        m_opacity = qBound(0.0f, m_opacity, 1.0f);
    }
    resourceUpdates->updateDynamicBuffer(m_ubuf.get(), 64, 4, &m_opacity);

Para comenzar a grabar el paso de renderizado, se consulta un ` QRhiCommandBuffer ` y se determina el tamaño de salida, lo que resultará útil para configurar la ventana de visualización y ajustar el tamaño de nuestra textura a pantalla completa, si fuera necesario.

    QRhiCommandBuffer *cb = m_sc->currentFrameCommandBuffer();
    const QSize outputSizeInPixels = m_sc->currentPixelSize();

Iniciar una pasada de renderizado implica borrar los búferes de color y de profundidad-estarcido del destino de renderizado (a menos que los indicadores del destino de renderizado indiquen lo contrario, pero esa es solo una opción para los destinos de renderizado basados en texturas). Aquí especificamos negro para el color, 1,0f para la profundidad y 0 para la plantilla (sin usar). El último argumento, ` resourceUpdates`, es el que garantiza que se apliquen los comandos de actualización de datos registrados en el lote. Como alternativa, podríamos haber utilizado ` QRhiCommandBuffer::resourceUpdate()` en su lugar. La pasada de renderizado tiene como destino una cadena de intercambio (swapchain), por lo que se llama a ` currentFrameRenderTarget()` para obtener un ` QRhiRenderTarget` válido.

    cb->beginPass(m_sc->currentFrameRenderTarget(), Qt::black, { 1.0f, 0 }, resourceUpdates);

Grabar la llamada de dibujo del triángulo es sencillo: se configura el pipeline, se establecen los recursos del shader, se configuran los búferes de vértices e índices y se graba la llamada de dibujo. En este caso utilizamos un dibujo no indexado con solo 3 vértices.

    cb->setGraphicsPipeline(m_colorPipeline.get());
    cb->setShaderResources();
    const QRhiCommandBuffer::VertexInput vbufBinding(m_vbuf.get(), 0);
    cb->setVertexInput(0, 1, &vbufBinding);
    cb->draw(3);

    cb->endPass();

La llamada ` setShaderResources()` no tiene argumentos, lo que implica que se utiliza ` m_colorTriSrb `, ya que estaba asociado al ` QRhiGraphicsPipeline ` activo (m_colorPipeline).

No entraremos en detalles sobre el renderizado de la imagen de fondo a pantalla completa. Para ello, consulta el código fuente del ejemplo. Sin embargo, vale la pena señalar un patrón habitual para «redimensionar» un recurso de textura o búfer. No es posible cambiar el tamaño de un recurso nativo ya existente, por lo que al modificar el tamaño de una textura o un búfer debe seguir una llamada a `create()`, para liberar y volver a crear los recursos nativos subyacentes. Para garantizar que ` QRhiTexture ` tenga siempre el tamaño requerido, la aplicación implementa la siguiente lógica. Ten en cuenta que m_texture permanece válido durante todo el ciclo de vida de la ventana, lo que significa que las referencias a este objeto, por ejemplo, en un QRhiShaderResourceBindings, siguen siendo válidas en todo momento. Solo los recursos nativos subyacentes van y vienen con el paso del tiempo.

Ten en cuenta también que establecemos una relación de píxeles del dispositivo (DPR) en la imagen que coincide con la ventana en la que estamos dibujando. Esto garantiza que el código de dibujo pueda ser independiente de la DPR, produciendo el mismo diseño independientemente de la DPR, al tiempo que se aprovechan los píxeles adicionales para mejorar la fidelidad.

void HelloWindow::ensureFullscreenTexture(const QSize &pixelSize, QRhiResourceUpdateBatch *u)
{
    if (m_texture && m_texture->pixelSize() == pixelSize)
        return;

    if (!m_texture)
        m_texture.reset(m_rhi->newTexture(QRhiTexture::RGBA8, pixelSize));
    else
        m_texture->setPixelSize(pixelSize);

    m_texture->create();

    QImage image(pixelSize, QImage::Format_RGBA8888_Premultiplied);
    image.setDevicePixelRatio(devicePixelRatio());

Una vez generado un ` QImage ` y finalizado el dibujo basado en ` QPainter` en él, utilizamos ` uploadTexture()` para registrar una carga de textura en el lote de actualización de recursos:

    u->uploadTexture(m_texture.get(), image);

Proyecto de ejemplo en code.qt.io

Véase también QRhi, QRhiSwapChain, QWindow, QRhiCommandBuffer, QRhiResourceUpdateBatch, QRhiBuffer y QRhiTexture.

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