QQuickRhiItem Class

Descripción detallada

QQuickRhiItem es efectivamente la contrapartida de QRhiWidget en el mundo de Qt Quick. Ambos están pensados para ser subclasificados, y ambos permiten la grabación de renderizado basado en QRhi que se dirige a un buffer de color fuera de la pantalla. La imagen 2D resultante se compone con el resto de la escena Qt Quick.

QQuickRhiItem sustituye a la clase heredada QQuickFramebufferObject. Esta última está inherentemente ligada a OpenGL / OpenGL ES, mientras que QQuickRhiItem trabaja con las clases QRhi, permitiendo ejecutar el mismo código de renderizado con Vulkan, Metal, Direct 3D 11/12, y OpenGL / OpenGL ES. Conceptual y funcionalmente están muy cerca, y migrar de QQuickFramebufferObject a QQuickRhiItem es sencillo. QQuickFramebufferObject sigue estando disponible para asegurar la compatibilidad del código de aplicación existente que trabaja directamente con la API OpenGL.

En la mayoría de las plataformas, el renderizado del gráfico de escena, y por tanto el renderizado realizado por QQuickRhiItem ocurrirá en un hilo dedicado. Por esta razón, la clase QQuickRhiItem impone una separación estricta entre la implementación del elemento (la subclase QQuickItem ) y la lógica de renderizado real. Toda la lógica del elemento, como las propiedades y las funciones de ayuda relacionadas con la interfaz de usuario expuestas a QML deben estar ubicadas en la subclase QQuickRhiItem. Todo lo relacionado con el renderizado debe ubicarse en la clase QQuickRhiItemRenderer. Para evitar race conditions y problemas de lectura/escritura desde dos hilos es importante que el renderizador y el item nunca lean o escriban variables compartidas. La comunicación entre el item y el renderizador debe realizarse principalmente a través de la función QQuickRhiItem::synchronize(). Esta función será llamada en el hilo de renderizado mientras el hilo GUI está bloqueado. También es posible utilizar conexiones en cola o eventos para la comunicación entre el ítem y el renderizador.

Las aplicaciones deben subclasificar tanto QQuickRhiItem como QQuickRhiItemRenderer. La función virtual pura createRenderer() debe reimplementarse para devolver una nueva instancia de la subclase QQuickRhiItemRenderer.

Al igual que con QRhiWidget, QQuickRhiItem gestiona automáticamente el buffer de color, que es una textura 2D (QRhiTexture) normalmente, o un QRhiRenderBuffer cuando se utiliza multimuestreo. (algunas APIs 3D diferencian entre texturas y renderbuffers, mientras que con algunas otras el recurso nativo subyacente es el mismo; los renderbuffers se usan principalmente para permitir el multimuestreo con OpenGL ES 3.0)

El tamaño de la textura se adaptará por defecto al tamaño del elemento (teniendo en cuenta device pixel ratio ). Si el tamaño del objeto cambia, la textura se recreará con el tamaño correcto. Si se prefiere un tamaño fijo, establezca fixedColorBufferWidth y fixedColorBufferHeight en valores distintos de cero.

QQuickRhiItem es un texture provider y puede ser utilizado directamente en ShaderEffects y otras clases que consumen proveedores de textura.

Aunque no es un caso de uso primario, QQuickRhiItem también permite incorporar código de renderizado que utilice directamente una API de gráficos 3D como Vulkan, Metal, Direct 3D u OpenGL. Ver QRhiCommandBuffer::beginExternal() para más detalles sobre la grabación de comandos nativos dentro de un pase de render QRhi, así como QRhiTexture::createFrom() para una forma de envolver una textura nativa existente y luego usarla con QRhi en un pase de render posterior. Ver también QQuickGraphicsConfiguration con respecto a la configuración del entorno nativo de la API 3D (por ejemplo, extensiones de dispositivo) y tenga en cuenta que el QQuickWindow se puede asociar con un QVulkanInstance personalizado llamando a QWindow::setVulkanInstance() con suficiente antelación.

Un ejemplo sencillo

Tomemos la siguiente subclase de QQuickRhiItem. Se muestra aquí en forma completa. Renderiza un triángulo simple con una proyección en perspectiva, donde el triángulo es rotado basado en la propiedad angle del item personalizado. (lo que significa que puede ser manejado por ejemplo con animaciones como NumberAnimation desde QML)

class ExampleRhiItemRenderer : public QQuickRhiItemRenderer
{
public:
    void initialize(QRhiCommandBuffer *cb) override;
    void synchronize(QQuickRhiItem *item) 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_angle = 0.0f;
};

class ExampleRhiItem : public QQuickRhiItem
{
    Q_OBJECT
    QML_NAMED_ELEMENT(ExampleRhiItem)
    Q_PROPERTY(float angle READ angle WRITE setAngle NOTIFY angleChanged)

public:
    QQuickRhiItemRenderer *createRenderer() override;

    float angle() const { return m_angle; }
    void setAngle(float a);

signals:
    void angleChanged();

private:
    float m_angle = 0.0f;
};

QQuickRhiItemRenderer *ExampleRhiItem::createRenderer()
{
    return new ExampleRhiItemRenderer;
}

void ExampleRhiItem::setAngle(float a)
{
    if (m_angle == a)
        return;

    m_angle = a;
    emit angleChanged();
    update();
}

void ExampleRhiItemRenderer::synchronize(QQuickRhiItem *rhiItem)
{
    ExampleRhiItem *item = static_cast<ExampleRhiItem *>(rhiItem);
    if (item->angle() != m_angle)
        m_angle = item->angle();
}

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

static 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,
};

void ExampleRhiItemRenderer::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(":/shaders/color.vert.qsb")) },
            { QRhiShaderStage::Fragment, getShader(QLatin1String(":/shaders/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 = renderTarget()->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 ExampleRhiItemRenderer::render(QRhiCommandBuffer *cb)
{
    QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();
    QMatrix4x4 modelViewProjection = m_viewProjection;
    modelViewProjection.rotate(m_angle, 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 = renderTarget()->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();
}

Es notable que esta simple clase es casi exactamente igual al código mostrado en la introducción de QRhiWidget. Los sombreadores de vértices y fragmentos son los mismos también. Estos se proporcionan como código fuente GLSL al estilo Vulkan y deben ser procesados primero por la infraestructura de shaders 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. El QQuickRhiItem carga estos archivos pre-procesados .qsb que se envían con la aplicación. Ver Qt Shader Tools para más información sobre la infraestructura de traducción de shaders de Qt.

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);
}

Una vez expuesto a QML (nótese el QML_NAMED_ELEMENT), nuestro elemento personalizado puede ser instanciado en cualquier escena. (después de importar el URI apropiado especificado para qt_add_qml_module en el proyecto CMake)

ExampleRhiItem {
    anchors.fill: parent
    anchors.margins: 10
    NumberAnimation on angle { from: 0; to: 360; duration: 5000; loops: Animation.Infinite }
}

Véase Scene Graph - RHI Texture Item para un ejemplo más complejo.