En esta página

QRhi Class

Abstracción acelerada de la API de gráficos 2D/3D. Más...

Encabezado: #include <rhi/qrhi.h>
CMake: find_package(Qt6 REQUIRED COMPONENTS GuiPrivate)
target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate)
qmake: QT += gui-private
Desde: Qt 6.6

Tipos públicos

(since 6.10) AdapterList
enum BeginFrameFlag { }
flags BeginFrameFlags
enum EndFrameFlag { SkipPresent }
flags EndFrameFlags
enum Feature { MultisampleTexture, MultisampleRenderBuffer, DebugMarkers, Timestamps, Instancing, …, ShaderDrawParameters }
enum Flag { EnableDebugMarkers, EnableTimestamps, PreferSoftwareRenderer, EnablePipelineCacheDataSave, SuppressSmokeTestWarnings }
flags Flags
enum FrameOpResult { FrameOpSuccess, FrameOpError, FrameOpSwapChainOutOfDate, FrameOpDeviceLost }
enum Implementation { Null, Vulkan, OpenGLES2, D3D11, D3D12, Metal }
enum ResourceLimit { TextureSizeMin, TextureSizeMax, MaxColorAttachments, FramesInFlight, MaxAsyncReadbackFrames, …, ShadingRateImageTileSize }

Funciones públicas

~QRhi()
void addCleanupCallback(const QRhi::CleanupCallback &callback)
void addCleanupCallback(const void *key, const QRhi::CleanupCallback &callback)
QRhi::Implementation backend() const
const char *backendName() const
QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags = {})
QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags = {})
QMatrix4x4 clipSpaceCorrMatrix() const
int currentFrameSlot() const
QRhiDriverInfo driverInfo() const
QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags = {})
QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags = {})
QRhi::FrameOpResult finish()
bool isClipDepthZeroToOne() const
bool isDeviceLost() const
bool isFeatureSupported(QRhi::Feature feature) const
bool isRecordingFrame() const
bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags = {}) const
bool isYUpInFramebuffer() const
bool isYUpInNDC() const
bool makeThreadLocalNativeContextCurrent()
const QRhiNativeHandles *nativeHandles()
QRhiBuffer *newBuffer(QRhiBuffer::Type type, QRhiBuffer::UsageFlags usage, quint32 size)
QRhiComputePipeline *newComputePipeline()
QRhiGraphicsPipeline *newGraphicsPipeline()
QRhiRenderBuffer *newRenderBuffer(QRhiRenderBuffer::Type type, const QSize &pixelSize, int sampleCount = 1, QRhiRenderBuffer::Flags flags = {}, QRhiTexture::Format backingFormatHint = QRhiTexture::UnknownFormat)
QRhiSampler *newSampler(QRhiSampler::Filter magFilter, QRhiSampler::Filter minFilter, QRhiSampler::Filter mipmapMode, QRhiSampler::AddressMode addressU, QRhiSampler::AddressMode addressV, QRhiSampler::AddressMode addressW = QRhiSampler::Repeat)
QRhiShaderResourceBindings *newShaderResourceBindings()
(since 6.9) QRhiShadingRateMap *newShadingRateMap()
QRhiSwapChain *newSwapChain()
QRhiTexture *newTexture(QRhiTexture::Format format, const QSize &pixelSize, int sampleCount = 1, QRhiTexture::Flags flags = {})
QRhiTexture *newTexture(QRhiTexture::Format format, int width, int height, int depth, int sampleCount = 1, QRhiTexture::Flags flags = {})
QRhiTexture *newTextureArray(QRhiTexture::Format format, int arraySize, const QSize &pixelSize, int sampleCount = 1, QRhiTexture::Flags flags = {})
QRhiTextureRenderTarget *newTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc, QRhiTextureRenderTarget::Flags flags = {})
QRhiResourceUpdateBatch *nextResourceUpdateBatch()
QByteArray pipelineCacheData()
void releaseCachedResources()
void removeCleanupCallback(const void *key)
int resourceLimit(QRhi::ResourceLimit limit) const
void setPipelineCacheData(const QByteArray &data)
(since 6.9) void setQueueSubmitParams(QRhiNativeHandles *params)
QRhiStats statistics() const
QList<int> supportedSampleCounts() const
(since 6.9) QList<QSize> supportedShadingRates(int sampleCount) const
QThread *thread() const
int ubufAligned(int v) const
int ubufAlignment() const

Miembros públicos estáticos

const char *backendName(QRhi::Implementation impl)
QRhi *create(QRhi::Implementation impl, QRhiInitParams *params, QRhi::Flags flags, QRhiNativeHandles *importDevice, QRhiAdapter *adapter)
QRhi *create(QRhi::Implementation impl, QRhiInitParams *params, QRhi::Flags flags = {}, QRhiNativeHandles *importDevice = nullptr)
(since 6.10) QRhi::AdapterList enumerateAdapters(QRhi::Implementation impl, QRhiInitParams *params, QRhiNativeHandles *nativeHandles = nullptr)
int mipLevelsForSize(const QSize &size)
bool probe(QRhi::Implementation impl, QRhiInitParams *params)
QSize sizeForMipLevel(int mipLevel, const QSize &baseLevelSize)
QRhiSwapChainProxyData updateSwapChainProxyData(QRhi::Implementation impl, QWindow *window)

Descripción detallada

La interfaz de hardware de renderizado de Qt es una abstracción para las API gráficas con aceleración por hardware, como OpenGL, OpenGL ES, Direct3D, Metal y Vulkan.

Advertencia: La familia de clases QRhi del módulo Qt GUI, que incluye QShader y QShaderDescription, ofrece garantías de compatibilidad limitadas. No hay garantías de compatibilidad ni a nivel de código fuente ni de binarios 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 en el código fuente, y estos solo se realizarán en versiones menores (6.7, 6.8, etc.). Para utilizar estas clases en una aplicación, enlaza con Qt::GuiPrivate (si utilizas CMake) e incluye los encabezados con el prefijo rhi, por ejemplo, #include <rhi/qrhi.h>.

Cada instancia de QRhi está respaldada por un backend para una API gráfica específica. La selección del backend se realiza en tiempo de ejecución y depende de la aplicación o biblioteca que cree la instancia de QRhi. Algunos backends están disponibles en varias plataformas (OpenGL, Vulkan, Null), mientras que las API específicas de una plataforma determinada solo están disponibles cuando se ejecutan en dicha plataforma (Metal en macOS/iOS, Direct3D en Windows).

Los backends disponibles actualmente son:

  • OpenGL 2.1 / OpenGL ES 2.0 o versiones posteriores. Se utilizan algunas extensiones y características más recientes de la especificación básica cuando están presentes, por ejemplo, para habilitar framebuffers multimuestra o shaders de cálculo. También se admite el funcionamiento en contextos de perfil básico. Si es necesario, las aplicaciones pueden consultar el ` feature flags ` en tiempo de ejecución para comprobar qué características no son compatibles con el contexto OpenGL que respalda el QRhi. El backend de OpenGL se basa en QOpenGLContext, QOpenGLFunctions y la infraestructura multiplataforma relacionada del módulo Qt GUI.
  • Direct3D 11.2 y versiones posteriores (con DXGI 1.3 y versiones posteriores), utilizando Shader Model 5.0 o posterior. Cuando el entorno de ejecución de D3D no sea compatible con las características de la versión 11.2 ni con el Shader Model 5.0, la inicialización mediante un dispositivo gráfico acelerado fallará, pero seguirá siendo posible utilizar el adaptador de software.
  • Direct3D 12 en Windows 10 versión 1703 y posteriores, con Shader Model 5.0 o posterior. Qt requiere que esté presente ID3D12Device2, de ahí que se exija como mínimo la versión 1703 de Windows 10. El dispositivo D3D12 se crea por defecto especificando un nivel mínimo de características de D3D_FEATURE_LEVEL_11_0.
  • Metal 1.2 o posterior.
  • Vulkan 1.0 o posterior, utilizando opcionalmente algunas características del nivel de Vulkan 1.1.
  • Null, un backend «ficticio» que no emite ninguna llamada gráfica.

Para permitir que el código de los shaders se escriba una sola vez en las aplicaciones y bibliotecas de Qt, se espera que todos los shaders se escriban en un único lenguaje que, posteriormente, se compila en SPIR-V. A partir de ahí se generan versiones para diversos lenguajes de sombreado, junto con información de reflexión (entradas, salidas y recursos de shader). A continuación, todo ello se empaqueta en instancias de ` QShader ` fácilmente y eficientemente serializables. Los compiladores y herramientas para generar dichos sombreadores no forman parte de QRhi ni del módulo ` Qt GUI `, pero sí lo hacen las clases principales para utilizar dichos sombreadores: ` QShader ` y ` QShaderDescription`. Las API y herramientas para realizar la compilación y la traducción forman parte del módulo ` Shader Tools ` de Qt.

Consulta el ejemplo «RHI Window Example» para ver un ejemplo introductorio sobre cómo crear una aplicación portátil y multiplataforma que realice un renderizado 3D acelerado en un QWindow utilizando QRhi.

Una visión general de la API

Para ofrecer una visión rápida de la API con un ejemplo breve pero completo que no implique ninguna configuración relacionada con ventanas, a continuación se presenta una aplicación multiplataforma completa y ejecutable que renderiza 20 fotogramas fuera de pantalla y, a continuación, guarda las imágenes generadas en archivos tras leer de nuevo el contenido de las texturas desde la GPU. Para ver un ejemplo que realiza el renderizado en pantalla, lo que implica configurar un « QWindow » y una «swapchain», consulta el ejemplo «RHI Window Example».

En aras de la brevedad, la inicialización de QRhi se realiza en función de la plataforma: el código de ejemplo aquí elegido utiliza Direct 3D 12 en Windows, Metal en macOS e iOS, y Vulkan en los demás casos. Esta aplicación nunca utiliza OpenGL ni Direct 3D 11, pero se podría añadir compatibilidad con ellos con unas pocas líneas de código adicionales.

#include <QGuiApplication>
#include <QImage>
#include <QFile>
#include <rhi/qrhi.h>

int main(int argc, char**argv)
{
    QGuiApplication app(argc, argv);

#if QT_CONFIG(vulkan)
    QVulkanInstance inst;
#endif
    std::unique_ptr<QRhi> rhi;
#if defined(Q_OS_WIN)
    QRhiD3D12InitParams params;
    rhi.reset(QRhi::create(QRhi::D3D12, &params));
#elif QT_CONFIG(metal)
    QRhiMetalInitParams params;
    rhi.reset(QRhi::create(QRhi::Metal, &params));
#elif QT_CONFIG(vulkan)
    inst.setExtensions(QRhiVulkanInitParams::preferredInstanceExtensions());
    if (inst.create()) {
        QRhiVulkanInitParams params;
        params.inst = &inst;
        rhi.reset(QRhi::create(QRhi::Vulkan, &params));
    } else {
        qFatal("Failed to create Vulkan instance");
    }
#endif
    if (rhi)
        qDebug() << rhi->backendName() << rhi->driverInfo();
   sino
        qFatal("Failed to initialize RHI");

   float rotación = 0.0f;
    float opacidad = 1.0f;
    int direcciónOpacidad = 1;

    std::unique_ptr<QRhiTexture> tex(rhi->newTexture(QRhiTexture::RGBA8,
                                                     QSize(1280, 720),
                                                     1,
                                                     QRhiTexture::RenderTarget | QRhiTexture::UsedAsTransferSource));
    tex->create();
    std::unique_ptr<QRhiTextureRenderTarget> rt(rhi->newTextureRenderTarget({ tex.get() }));
    std::unique_ptr<QRhiRenderPassDescriptor> rp(rt->newCompatibleRenderPassDescriptor());
    rt->setRenderPassDescriptor(rp.get());
    rt->create();

    QMatrix4x4 viewProjection = rhi->clipSpaceCorrMatrix();
    viewProjection.perspective(45.0f, 1280 / 720.f, 0.01f, 1000.0f);
    viewProjection.translate(0, 0,-4);

    static float vertexData[] = { // Y hacia arriba, en sentido antihorario
        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,
    };

    std::unique_ptr<QRhiBuffer> vbuf(rhi->newBuffer(QRhiBuffer::Immutable,
                                                    QRhiBuffer::VertexBuffer,
                                                    sizeof(vertexData)));
    vbuf->create();

    std::unique_ptr<QRhiBuffer> ubuf(rhi->newBuffer(QRhiBuffer::Dynamic,
                                                    QRhiBuffer::UniformBuffer,
                                                    64 + 4));
    ubuf->create();

    std::unique_ptr<QRhiShaderResourceBindings> srb(rhi->newShaderResourceBindings());
    srb->setBindings({
        QRhiShaderResourceBinding::uniformBuffer(0,
                                                 QRhiShaderResourceBinding::VertexStage | QRhiShaderResourceBinding::FragmentStage,
                                                 ubuf.get())
    });
    srb->create();

    std::unique_trp<QRhiGraphicsPipeline> ps(rhi->newGraphicsPipeline());
    QRhiGraphicsPipeline::TargetBlendpremulAlphaBlend;
    premulAlphaBlend.enable = true;
    ps->setTargetBlends({ premulAlphaBlend });
    static auto getShader = [](const QString&name) {
        QFile f(name);
        return f.open(QIODevice::ReadOnly) ? QShader::fromSerialized(f.readAll()) : QShader();
    };
    ps->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) }
    });
    ps->setVertexInputLayout(inputLayout);
    ps->setShaderResourceBindings(srb.get());
    ps->setRenderPassDescriptor(rp.get());
    ps->create();

    QRhiCommandBuffer*cb;
    for (int frame = 0; frame < 20;++frame) {
        rhi->beginOffscreenFrame(&cb);

        QRhiResourceUpdateBatch*u = rhi->nextResourceUpdateBatch();
        if (frame== 0)
            u->uploadStaticBuffer(vbuf.get(), vertexData);

        QMatrix4x4 mvp = viewProjection;
        mvp.rotate(rotation, 0, 1, 0);
        u->updateDynamicBuffer(ubuf.get(), 0, 64, mvp.constData());
        rotation+= 5.0f;

        u->updateDynamicBuffer(ubuf.get(), 64, 4, &opacity);
        opacity+= opacityDir * 0.2f;
        if (opacity < 0.0f|| opacity > 1.0f) {
            opacityDir*=-1;
            opacity = qBound(0.0f, opacity, 1.0f);
        }

        cb->beginPass(rt.get(), Qt::green, { 1.0f, 0 }, u);
        cb->setGraphicsPipeline(ps.get());
        cb->setViewport({ 0, 0, 1280, 720 });
        cb->setShaderResources();
        const QRhiCommandBuffer::VertexInput vbufBinding(vbuf.get(), 0);
        cb->setVertexInput(0, 1, &vbufBinding);
        cb->draw(3);
        QRhiReadbackResult readbackResult;
        u = rhi->nextResourceUpdateBatch();
        u->readBackTexture({ tex.get() }, &readbackResult);
        cb->endPass(u);

        rhi->endOffscreenFrame();

        QImage image(reinterpret_cast<const uchar*>(readbackResult.data.constData()),
                     readbackResult.pixelSize.width(),
                     readbackResult.pixelSize.height(),
                     QImage::Format_RGBA8888_Premultiplied);
        if (rhi->isYUpInFramebuffer())
            image.flip();
        image.save(QString::asprintf("frame%d.png", frame));
    }

    return 0;
}

El resultado de la aplicación son 20 imágenes de PNG (frame0.png - frame19.png). Estas contienen un triángulo giratorio con opacidad variable sobre un fondo verde.

Se espera que los sombreadores de vértices y de fragmentos se procesen y se empaqueten en archivos .qsb. El código fuente GLSL compatible con Vulkan es 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;
    float opacity;
};

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;

layout(std140, binding = 0) uniform buf {
    mat4 mvp;
    float opacity;
};

void main()
{
    fragColor = vec4(v_color * opacity, opacity);
}

Para compilar y transpilar manualmente estos shaders a varios formatos de destino (SPIR-V, HLSL, MSL, GLSL) y generar los archivos « .qsb » que la aplicación carga en tiempo de ejecución, ejecuta qsb --qt6 color.vert -o color.vert.qsb y qsb --qt6 color.frag -o color.frag.qsb. Como alternativa, el módulo Qt « Shader Tools » ofrece integración con el sistema de compilación de CMake, la función de CMake « qt_add_shaders() », que permite conseguir lo mismo en tiempo de compilación.

Consideraciones de seguridad

Todos los datos utilizados por QRhi y las clases relacionadas, como QShader, se consideran contenido de confianza.

Advertencia: Se recomienda a los desarrolladoresde aplicaciones que evalúen cuidadosamente las posibles implicaciones antes de permitir la incorporación de contenido proporcionado por el usuario que no forme parte de la aplicación y que no esté bajo el control de los desarrolladores. (Esto incluye todos los datos de vértices e índices, los sombreadores, los parámetros del pipeline y de las llamadas de dibujo, etc.)

Fundamentos de diseño

Un QRhi no se puede instanciar directamente. En su lugar, utilice la función create(). Elimine la instancia de QRhi de la forma habitual para liberar el dispositivo gráfico.

Recursos

Las instancias de clases derivadas de QRhiResource, como QRhiBuffer, QRhiTexture, etc., encapsulan cero, uno o más recursos gráficos nativos. Las instancias de dichas clases siempre se crean mediante las funciones new del QRhi, como newBuffer(), newTexture(), newTextureRenderTarget() y newSwapChain().

QRhiBuffer *vbuf = rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertexData));
if (!vbuf->create()) { error(); }
// ...
delete vbuf;
  • El valor devuelto por funciones como newBuffer() siempre es propiedad del llamante.
  • El mero hecho de crear una instancia de una subclase de ` QRhiResource ` nunca asigna ni inicializa ningún recurso nativo. Esto solo se hace al llamar a la función ` create() ` de una subclase, por ejemplo, ` QRhiBuffer::create()` o ` QRhiTexture::create()`.
  • Las excepciones son QRhiTextureRenderTarget::newCompatibleRenderPassDescriptor(), QRhiSwapChain::newCompatibleRenderPassDescriptor() y QRhiRenderPassDescriptor::newCompatibleRenderPassDescriptor(). Para estos no existe la operación create() y el objeto devuelto queda activo de inmediato.
  • Los propios objetos de recurso se tratan como inmutables: una vez que se ha llamado a create() en un recurso, cambiar cualquier parámetro mediante los setters, como QRhiTexture::setPixelSize(), no tiene ningún efecto, a menos que se libere el recurso nativo subyacente y se vuelva a llamar a create(). Consulta más información sobre la reutilización de recursos en las secciones siguientes.
  • La liberación de los recursos nativos subyacentes se programa mediante el destructor de QRhiResource o llamando a QRhiResource::destroy(). Los backends suelen poner en cola las solicitudes de liberación y aplazar su ejecución hasta un momento no especificado, lo cual queda oculto a las aplicaciones. De este modo, las aplicaciones no tienen que preocuparse por liberar recursos nativos que aún puedan estar en uso por un marco en ejecución.
  • Tenga en cuenta que esto no significa que un ` QRhiResource ` pueda ser liberado mediante `destroy()` o eliminado libremente dentro de un fotograma (es decir, en un tramo comprendido entre ` beginFrame()` y ` endFrame()`). Como norma general, todos los objetos ` QRhiResource ` a los que se haga referencia deben permanecer inalterados hasta que el fotograma se envíe llamando a ` endFrame()`. Para facilitar esto, se proporciona ` QRhiResource::deleteLater()` como medida de comodidad.

Búferes de comandos y ejecución diferida de comandos

Independientemente del diseño y las capacidades de la API gráfica subyacente, todos los backends de QRhi implementan algún nivel de búferes de comandos. Ninguna función de « QRhiCommandBuffer » emite directamente ningún comando nativo de enlace o dibujo (como, por ejemplo, ` glDrawElements`). Los comandos siempre se registran en una cola, ya sea nativa o proporcionada por el backend de QRhi. El búfer de comandos se envía, por lo que la ejecución solo comienza tras llamar a ` QRhi::endFrame()` o ` QRhi::finish()`.

Esta naturaleza diferida tiene consecuencias para algunos tipos de objetos. Por ejemplo, escribir en un búfer dinámico varias veces dentro de un fotograma, en caso de que dichos búferes estén respaldados por memoria visible para el host, hará que los resultados de todas las escrituras sean visibles para todas las llamadas de dibujo del búfer de comandos del fotograma, independientemente de cuándo se haya registrado la actualización del búfer dinámico en relación con una llamada de dibujo.

Además, las instancias de las subclases de ` QRhiResource ` deben tratarse como inmutables dentro de un fotograma en el que se haga referencia a ellas de cualquier forma. Crea todos los recursos por adelantado, antes de empezar a registrar comandos para el siguiente fotograma. Debe evitarse reutilizar una instancia de ` QRhiResource ` dentro de un fotograma (llamando a ` create() ` y luego haciendo referencia a ella de nuevo en la misma sección ` beginFrame - endFrame `), ya que puede dar lugar a resultados inesperados, dependiendo del backend.

Como regla general, todos los objetos QRhiResource a los que se haga referencia deben permanecer válidos y sin modificar hasta que el fotograma se envíe llamando a endFrame(). Por otro lado, llamar a destroy() o eliminar el QRhiResource siempre es seguro una vez enviado el fotograma, independientemente del estado de los recursos nativos subyacentes (que pueden seguir siendo utilizados por la GPU, pero eso se gestiona internamente).

A diferencia de API como OpenGL, los comandos de tipo «upload» y «copy» no se pueden mezclar con los comandos de dibujo. Un renderizador típico seguirá una secuencia similar a la siguiente:

  • (re)crear recursos
  • iniciar fotograma
  • grabar/emitir cargas y copias
  • iniciar la grabación de una pasada de renderizado
  • grabar llamadas de dibujo
  • finalizar la pasada de renderizado
  • fin del fotograma

El registro de operaciones de tipo «copia» se realiza mediante QRhiResourceUpdateBatch. Estas operaciones suelen confirmarse en beginPass().

Al trabajar con motores de renderizado heredados diseñados para OpenGL, la migración a QRhi suele implicar un rediseño que pasa de tener un único paso de « render » (que realiza copias y cargas, borra los búferes y emite llamadas de dibujo, todo ello mezclado) a una configuración claramente separada, configuración de dos fases prepare - render, en la que el paso render solo inicia un renderpass y registra las llamadas de dibujo, mientras que toda la creación de recursos y la puesta en cola de actualizaciones, cargas y copias se realiza previamente, en el paso prepare.

QRhi no permite, por el momento, crear y enviar libremente búferes de comandos. Es posible que esta restricción se levante en cierta medida en el futuro, especialmente si se introduce soporte para computación, pero el modelo de puntos bien definidos frame-start y frame-end, combinado con un búfer de comandos dedicado al «fotograma», en el que frame-end implica la presentación, seguirá siendo la forma principal de funcionamiento, ya que es lo que mejor se adapta a las diversas tecnologías de interfaz de usuario de Qt XML.

Multihilo

Una instancia de QRhi y los recursos asociados pueden crearse y utilizarse en cualquier hilo, pero todo uso debe limitarse a ese único hilo. Al renderizar en varias QWindows dentro de una aplicación, suele ser recomendable disponer de un hilo y una instancia de QRhi específicos para cada ventana, ya que esto puede eliminar problemas de limitación inesperada causados por la presentación en varias ventanas. Conceptualmente, esto equivale al funcionamiento del bucle de renderizado multihilo de un gráfico de escena de « Qt Quick » cuando se trabaja directamente con OpenGL: un hilo para cada ventana, un « QOpenGLContext » para cada hilo. Al pasar a QRhi, « QOpenGLContext » se sustituye por QRhi, lo que facilita la migración.

En lo que respecta a los objetos nativos creados externamente, como los contextos de OpenGL pasados a través de ` QRhiGles2NativeHandles`, corresponde a la aplicación asegurarse de que otros subprocesos no los utilicen de forma incorrecta.

Los recursos no se pueden compartir entre instancias de QRhi. Se trata de una decisión intencionada, ya que QRhi oculta la mayoría de las tareas relacionadas con las colas, los búferes de comandos y la sincronización de recursos, y no proporciona ninguna API para ellas. Sin embargo, el uso concurrente seguro y eficiente de los recursos gráficos desde múltiples subprocesos está vinculado a esos conceptos y, por lo tanto, es un tema que actualmente queda fuera del alcance, aunque podría introducirse en el futuro.

Nota: El backend de Metal requiere que haya un autorelease pool disponible en el hilo de renderizado, idealmente envolviendo cada iteración del bucle de renderizado. Esto no requiere ninguna acción por parte de los usuarios de QRhi cuando se renderiza en el hilo principal (GUI), pero cobra importancia cuando se utiliza un hilo de renderizado independiente y dedicado.

Sincronización de recursos

QRhi no expone API para barreras de recursos ni transiciones de diseño de imágenes. Dicha sincronización la realizan implícitamente los backends, cuando procede (por ejemplo, Vulkan), mediante el seguimiento del uso de recursos según sea necesario. Las barreras de búfer e imagen se insertan antes de las pasadas de renderizado o cálculo de forma transparente para la aplicación.

Nota: Se espera quelos recursos dentro de una pasada de renderizado o de cálculo estén vinculados a un único uso durante dicha pasada. Por ejemplo, un búfer puede utilizarse como búfer de vértices, de índices, uniforme o de almacenamiento, pero no como una combinación de todos ellos dentro de una misma pasada. Sin embargo, no hay ningún problema en utilizar un búfer como búfer de almacenamiento en una pasada de cálculo y, a continuación, como búfer de vértices en una pasada de renderizado, por ejemplo, siempre que el búfer haya declarado ambos usos en el momento de su creación.

Nota: En el caso de las texturas , esta regla se flexibiliza en determinados casos, ya que se admite el uso de dos subrecursos (normalmente dos niveles mip diferentes) de la misma textura para accesos distintos (uno para la lectura y otro para la escritura) incluso dentro de la misma pasada.

Reutilización de recursos

Desde el punto de vista del usuario, un objeto ` QRhiResource ` es reutilizable inmediatamente después de llamar a ` QRhiResource::destroy()`. Con la excepción de las cadenas de intercambio (swapchains), llamar a ` create() ` sobre un objeto ya creado realiza implícitamente ` destroy()`. Esto proporciona un atajo muy útil para reutilizar una instancia de ` QRhiResource ` con parámetros diferentes, con un nuevo objeto gráfico nativo subyacente.

La importancia de reutilizar el mismo objeto radica en que algunos objetos hacen referencia a otros: por ejemplo, un ` QRhiShaderResourceBindings ` puede hacer referencia a instancias de ` QRhiBuffer`, ` QRhiTexture` y ` QRhiSampler `. Si en un fotograma posterior fuera necesario redimensionar uno de estos buffers o modificar un parámetro del sampler, destruir y crear un ` QRhiBuffer ` o un ` QRhiSampler ` completamente nuevo invalidaría todas las referencias a la instancia anterior. Con solo modificar los parámetros adecuados mediante QRhiBuffer::setSize() o similar y, a continuación, llamar a QRhiBuffer::create(), todo funciona como se espera y no hay necesidad alguna de tocar el QRhiShaderResourceBindings, aunque es muy probable que, en el fondo, el QRhiBuffer esté ahora respaldado por un búfer nativo completamente nuevo.

QRhiBuffer *ubuf = rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, 256);
ubuf->create();

QRhiShaderResourceBindings *srb = rhi->newShaderResourceBindings()
srb->setBindings({
    QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage | QRhiShaderResourceBinding::FragmentStage, ubuf)
});
srb->create();

// ...

// now in a later frame we need to grow the buffer to a larger size
ubuf->setSize(512);
ubuf->create(); // same as ubuf->destroy(); ubuf->create();

// srb needs no changes whatsoever, any references in it to ubuf
// stay valid. When it comes to internal details, such as that
// ubuf may now be backed by a completely different native buffer
// resource, that is is recognized and handled automatically by the
// next setShaderResources().

QRhiTextureRenderTarget ofrece el mismo comportamiento: llamar a ` QRhiCommandBuffer::beginPass()` es seguro incluso cuando una de las texturas o búferes de renderizado asociados al objetivo de renderizado se ha reconstruido (mediante la llamada a ` create() `) desde la creación del objeto de objetivo de renderizado. Esto permite a la aplicación cambiar el tamaño de una textura estableciendo un nuevo tamaño de píxel en el objeto « QRhiTexture » y llamando a ` create()`, creando así un recurso de textura nativo completamente nuevo en el fondo, sin tener que actualizar el objeto « QRhiTextureRenderTarget », ya que esto se hará de forma implícita en `beginPass()`.

Objetos agrupados

Además de los recursos, también existen objetos en el pool, como, por ejemplo, QRhiResourceUpdateBatch. Una instancia se recupera mediante una función next, como, por ejemplo, nextResourceUpdateBatch(). En este caso, quien realiza la llamada no es propietario de la instancia devuelta. La única forma válida de proceder aquí es llamar a funciones sobre el QRhiResourceUpdateBatch y, a continuación, pasarlo a QRhiCommandBuffer::beginPass() o QRhiCommandBuffer::endPass(). Estas funciones se encargan de devolver el lote al grupo. Como alternativa, un lote puede «cancelarse» y devolverse al grupo sin procesar llamando a QRhiResourceUpdateBatch::release().

Un patrón típico es, por tanto:

QRhiResourceUpdateBatch *resUpdates = rhi->nextResourceUpdateBatch();
// ...
resUpdates->updateDynamicBuffer(ubuf, 0, 64, mvp.constData());
if (!image.isNull()) {
    resUpdates->uploadTexture(texture, image);
    image = QImage();
}
// ...
QRhiCommandBuffer *cb = m_sc->currentFrameCommandBuffer();
// note the last argument
cb->beginPass(swapchain->currentFrameRenderTarget(), clearCol, clearDs, resUpdates);

Características específicas de las cadenas de intercambio

QRhiSwapChain presenta una semántica especial debido a la naturaleza peculiar de las swapchains.

  • No dispone de ` create() `, sino de ` QRhiSwapChain::createOrResize()`. Llamar repetidamente a esta función no es lo mismo que llamar a ` QRhiSwapChain::destroy()` seguido de ` QRhiSwapChain::createOrResize()`. Esto se debe a que las swapchains suelen disponer de mecanismos para gestionar los casos en los que es necesario redimensionar los búferes de una manera más eficiente que la de destruir y volver a crear desde cero por la fuerza bruta.
  • Una ` QRhiSwapChain ` activa debe liberarse llamando a ` destroy()` o destruyendo el objeto, antes de que se destruya la `QPlatformWindow` subyacente de ` QWindow` y, por lo tanto, el objeto de ventana nativo asociado. No debe posponerse, ya que liberar la cadena de intercambio puede resultar problemático (y, con algunas API, como Vulkan, está explícitamente prohibido) cuando la ventana nativa ya no existe, por ejemplo, porque el `QPlatformWindow` se destruyó al recibir un evento ` QWindow::close()`. Por lo tanto, la liberación de la cadena de intercambio debe producirse siempre que la ventana de destino ` QWindow ` envíe el evento ` QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed `. Si el evento no llega antes de la destrucción de ` QWindow ` —lo cual puede ocurrir al utilizar ` QCoreApplication::quit()`—, comprueba `QWindow::handle()` tras salir del bucle de eventos e invoca la liberación de la cadena de intercambio si el valor no es nulo (lo que significa que la ventana nativa subyacente sigue existiendo).

Propiedad

La regla general es que no hay transferencia de propiedad. Crear un QRhi con un dispositivo gráfico ya existente no significa que el QRhi asuma la propiedad del objeto dispositivo. Del mismo modo, la propiedad no se cede cuando un objeto dispositivo o de textura se «exporta» mediante QRhi::nativeHandles() o QRhiTexture::nativeTexture(). Y lo más importante: pasar punteros en estructuras y a través de setters no transfiere la propiedad.

Resolución de problemas y análisis de rendimiento

Notificación de errores

Funciones como QRhi::create() y las funciones miembro create() de las clases de recursos (p. ej., QRhiBuffer::create()) indican un fallo mediante el valor de retorno (nullptr o false, respectivamente). Al trabajar con QShader, QShader::fromSerialized() devuelve un QShader no válido (para el que isValid() devuelve false) cuando los datos pasados a la función no se pueden deserializar correctamente. Algunas funciones, en particular beginFrame(), también pueden informar en ocasiones de «fallos leves», como FrameOpSwapChainOutOfDate, que no indican un error irrecuperable, sino que deben considerarse más bien como una respuesta del tipo «inténtalo de nuevo más tarde».

Las advertencias y los errores pueden mostrarse en cualquier momento en la salida de depuración mediante qWarning(). Por lo tanto, siempre es recomendable revisar la salida de la aplicación.

Se pueden habilitar mensajes de depuración adicionales a través de las siguientes categorías de registro. Los mensajes de estas categorías no se muestran de forma predeterminada a menos que se habiliten explícitamente mediante QLoggingCategory o la variable de entorno QT_LOGGING_RULES. Para una mejor interoperabilidad con Qt Quick, la variable de entorno QSG_INFO también habilita estas salidas de depuración.

  • qt.rhi.general

Además, las aplicaciones pueden consultar los valores de QRhi backend name y graphics device information a partir de un QRhi inicializado correctamente. Esta información puede mostrarse al usuario o almacenarse en los registros de la aplicación, incluso en entornos de producción, si así se desea.

Investigación de problemas de renderizado

Cuando los resultados de renderizado no sean los esperados, o la aplicación experimente problemas, considera siempre comprobarlo con las herramientas de depuración y validación de las API 3D nativas. El propio QRhi cuenta con una comprobación de errores limitada, ya que no resulta razonable replicar la enorme cantidad de funcionalidades ya existentes en las capas subyacentes.

  • En el caso de Vulkan, el control de las capas de validación de Vulkan no entra dentro del ámbito de QRhi, sino que se puede lograr configurando el objeto ` QVulkanInstance ` con las capas adecuadas. Por ejemplo, llame a ` instance.setLayers({ "VK_LAYER_KHRONOS_validation" }); ` antes de invocar ` create()` en ` QVulkanInstance`. (Tenga en cuenta que esto supone que las capas de validación están realmente instaladas y disponibles, p. ej., desde el SDK de Vulkan). Por defecto, ` QVulkanInstance ` redirige convenientemente los mensajes de depuración de Vulkan a ` qDebug`, lo que significa que los mensajes de validación se muestran igual que otras advertencias de Qt XML.
  • Con Direct 3D 11 y 12, se puede solicitar un dispositivo gráfico con la capa de depuración habilitada activando el indicador « enableDebugLayer » en el archivo correspondiente init params struct. Con Direct 3D 12, los mensajes se muestran a través de qDebug, al igual que los mensajes de validación de Vulkan, siempre que la capa de depuración admita devoluciones de llamada de mensajes. De lo contrario, y siempre con Direct 3D 11, los mensajes aparecen en la salida de depuración, que se puede ver en el panel de mensajes de Qt Creator o mediante una herramienta como DebugView.
  • En el caso de Metal, el control de la validación de Metal queda fuera del ámbito de QRhi. Para habilitar la validación, ejecuta la aplicación con la variable de entorno METAL_DEVICE_WRAPPER_TYPE=1 establecida, o ejecuta la aplicación desde XCode. Es posible que haya más ajustes y variables de entorno en las versiones recientes de XCode y macOS. Consulta, por ejemplo, esta página.

Capturas de fotogramas y análisis de rendimiento

Una aplicación Qt que realiza el renderizado con QRhi en una ventana, al tiempo que utiliza una API 3D en segundo plano, no difiere, al menos desde el punto de vista de la gestión de ventanas y el proceso gráfico, de cualquier otra aplicación (no Qt) que utilice la misma API 3D. Esto significa que las herramientas y prácticas para la depuración y el análisis de rendimiento de aplicaciones que incluyen gráficos 3D, como los videojuegos, también son aplicables a este tipo de aplicaciones Qt.

Algunos ejemplos de herramientas que pueden proporcionar información sobre el funcionamiento interno del renderizado de las aplicaciones Qt que utilizan QRhi, lo que incluye también proyectos basados en 3D de Qt Quick y Qt Quick:

  • RenderDoc permite realizar capturas de fotogramas y analizar los comandos grabados y el estado del proceso de renderizado en Windows y Linux para aplicaciones que utilizan OpenGL, Vulkan, D3D11 o D3D12. Cuando se intenta averiguar por qué algunas partes de la escena 3D no se muestran como se esperaba, RenderDoc suele ser una forma rápida y eficaz de comprobar las etapas del proceso y el estado relacionado, y descubrir el valor que falta o que es incorrecto. También es una herramienta que se utiliza activamente en el desarrollo del propio Qt.
  • Para los sistemas basados en NVIDIA, Nsight Graphics ofrece una herramienta de depuración gráfica en Windows y Linux. Además de investigar los comandos del fotograma y del canal de procesamiento, las herramientas específicas del fabricante permiten examinar los tiempos y la información sobre el rendimiento del hardware, algo que las simples capturas de fotogramas no pueden proporcionar.
  • Para los sistemas basados en AMD, se puede utilizar el Radeon GPU Profiler para obtener una visión más detallada del renderizado de la aplicación y de su rendimiento.
  • Las superposiciones que muestran información de rendimiento en tiempo real también pueden resultar muy útiles y, a menudo, son preferibles a la implementación de simples contadores de fotogramas por segundo dentro de la propia aplicación, ya que son más fiables y muestran más información. Un ejemplo es PresentMon, que es compatible con hardware gráfico de múltiples fabricantes.
  • Dado que QRhi es compatible con Direct 3D 12, también es una opción utilizar PIX, una herramienta de optimización del rendimiento y depuración para juegos de DirectX 12 en Windows.
  • En macOS, se puede utilizar el depurador de Metal de XCode para capturar y analizar fotogramas, investigar detalles de rendimiento y depurar shaders. En macOS 13 también es posible habilitar una superposición que muestre la tasa de fotogramas y otra información para cualquier ventana basada en Metal configurando la variable de entorno MTL_HUD_ENABLED=1.

En plataformas móviles e integradas, puede haber herramientas específicas del fabricante y de la plataforma, proporcionadas por el fabricante de la GPU o del SoC, disponibles para realizar perfiles de rendimiento de aplicaciones que utilicen OpenGL ES o Vulkan.

Al capturar fotogramas, recuerda que se puede asignar un nombre a los objetos y grupos de comandos mediante marcadores de depuración, siempre que debug markers were enabled para el QRhi y la API gráfica utilizada lo admitan. Para anotar el flujo de comandos, llama a debugMarkBegin(), debugMarkEnd() y/o debugMarkMsg(). Esto puede resultar especialmente útil en fotogramas más grandes con múltiples pasadas de renderizado. Los recursos se nombran llamando a setName() antes de create().

Para realizar mediciones básicas de tiempo en la CPU y la GPU dentro de la aplicación, se pueden utilizar QElapsedTimer y QRhiCommandBuffer::lastCompletedGpuTime(). Esta última solo está disponible con determinadas API gráficas por el momento y requiere activarla mediante el indicador QRhi::EnableTimestamps.

Comprobación de fugas de recursos

Al destruir un objeto QRhi sin destruir adecuadamente todos los búferes, texturas y demás recursos creados a partir de él, se muestran advertencias al respecto en la salida de depuración siempre que la aplicación sea una compilación de depuración o cuando la variable de entorno ` QT_RHI_LEAK_CHECK ` esté establecida en un valor distinto de cero. Esta es una forma sencilla de detectar problemas de diseño relacionados con la gestión de recursos dentro de la lógica de renderizado de la aplicación. Sin embargo, hay que tener en cuenta que algunas plataformas y API gráficas subyacentes también pueden realizar su propia detección de asignaciones y fugas de recursos, sobre las que Qt no tendrá control directo. Por ejemplo, al utilizar Vulkan, el asignador de memoria puede generar aserciones fallidas en compilaciones de depuración cuando los recursos que poseen asignaciones de memoria gráfica no se destruyen antes que el QRhi. Además, la capa de validación de Vulkan, cuando está habilitada, emitirá advertencias sobre recursos gráficos nativos que no se hayan liberado. Del mismo modo, con Direct 3D pueden aparecer advertencias sobre objetos COM no liberados cuando la aplicación no destruya el QRhi y sus recursos en el orden correcto.

Véase también el ejemplo de ventana RHI, QRhiCommandBuffer, QRhiResourceUpdateBatch, QRhiShaderResourceBindings, QShader, QRhiBuffer, QRhiTexture, QRhiRenderBuffer, QRhiSampler, QRhiTextureRenderTarget, QRhiGraphicsPipeline, QRhiComputePipeline y QRhiSwapChain.

Documentación sobre tipos de miembros

[alias, since 6.10] QRhi::AdapterList

Sinónimo de « QVector » <QRhiAdapter *>.

Esta definición de tipo se introdujo en Qt 6.10.

enum QRhi::BeginFrameFlag
flags QRhi::BeginFrameFlags

Valores de los indicadores para ` QRhi::beginFrame()`

El tipo `BeginFrameFlags` es una definición de tipo (`typedef`) para ` QFlags<BeginFrameFlag>`. Almacena una combinación OR de valores de `BeginFrameFlag`.

enum QRhi::EndFrameFlag
flags QRhi::EndFrameFlags

Valores de los indicadores para QRhi::endFrame()

ConstanteValorDescripción
QRhi::SkipPresent1 << 0Especifica que no se debe poner en cola ningún comando de presentación ni realizar ninguna llamada a swapBuffers. De este modo, no se muestra ninguna imagen. No se recomienda generar varios fotogramas con esta bandera activada en todos ellos (excepto, por ejemplo, con fines de evaluación de rendimiento; pero hay que tener en cuenta que los backends pueden comportarse de forma diferente a la hora de esperar a que se complete el comando sin mostrar nada, por lo que los resultados no son comparables entre ellos)

El tipo EndFrameFlags es una definición de tipo (typedef) para QFlags<EndFrameFlag>. Almacena una combinación OR de valores de EndFrameFlag.

enum QRhi::Feature

Valores de indicador que señalan qué funciones son compatibles con el backend que se está utilizando actualmente.

ConstanteValorDescripción
QRhi::MultisampleTexture1Indica que se admiten texturas con un número de muestras superior a 1. En la práctica, esta característica no será compatible con versiones de OpenGL ES anteriores a la 3.1 ni con versiones de OpenGL anteriores a la 3.0.
QRhi::MultisampleRenderBuffer2Indica que se admiten buffers de renderizado con un número de muestras superior a 1. En la práctica, esta característica no será compatible con OpenGL ES 2.0, y es posible que tampoco lo sea con OpenGL 2.x, a menos que se disponga de las extensiones pertinentes.
QRhi::DebugMarkers3Indica que se admiten los grupos de marcadores de depuración (y, por lo tanto, ` QRhiCommandBuffer::debugMarkBegin()`).
QRhi::Timestamps4Indica que se admiten marcas de tiempo en los búferes de comandos. Relevante para QRhiCommandBuffer::lastCompletedGpuTime(). Cabe esperar que sea compatible con Metal, Vulkan, Direct 3D 11 y 12, y con contextos de OpenGL de la versión 3.3 o posterior. Sin embargo, en algunas de estas API, la compatibilidad con las consultas de marcas de tiempo es técnicamente opcional, por lo que no se puede garantizar que esta característica sea siempre compatible con todas sus implementaciones.
QRhi::Instancing5Indica que se admite el dibujo instanciado. En la práctica, esta característica no será compatible con OpenGL ES 2.0 ni con OpenGL 3.2 o versiones anteriores.
QRhi::CustomInstanceStepRate6Indica que se admiten velocidades de paso de instancias distintas de 1. En la práctica, esta característica nunca será compatible con OpenGL. Además, ejecutarla con Vulkan 1.0 sin VK_EXT_vertex_attribute_divisor también dará lugar a que se informe de «false» para esta característica.
QRhi::PrimitiveRestart7Indica que está habilitado el reinicio del ensamblaje de primitivas cuando se encuentra un valor de índice de 0xFFFF (IndexUInt16) o 0xFFFFFFFF (IndexUInt32), al menos para determinadas topologías de primitivas. QRhi intentará habilitar esto con todos los backends, pero en algunos casos no será compatible. No es posible controlar dinámicamente el reinicio primitivo, ya que en algunas API el reinicio primitivo con un índice fijo está siempre activado. Las aplicaciones deben dar por hecho que, siempre que se indique que esta característica es compatible, los valores de índice mencionados anteriormente may deben tratarse de forma especial, dependiendo de la topología. Las únicas dos topologías en las que se garantiza que el reinicio de primitivas se comporte de forma idéntica en todos los backends, siempre que se indique que esta característica es compatible, son LineStrip y TriangleStrip.
QRhi::NonDynamicUniformBuffers8Indica que se admite la creación de búferes con el uso UniformBuffer y los tipos Immutable o Static. Cuando se indica que no es compatible, los búferes uniformes (constantes) deben crearse como Dynamic. (lo cual se recomienda en cualquier caso)
QRhi::NonFourAlignedEffectiveIndexBufferOffset9Indica que se admiten desplazamientos efectivos del búfer de índices (indexOffset + firstIndex * indexComponentSize) que no estén alineados a 4 bytes. Cuando no se admiten, intentar ejecutar una llamada a drawIndexed() con un desplazamiento efectivo no alineado puede dar lugar a un comportamiento no especificado. Es relevante, en particular, para Metal, donde esto se indicará como no compatible.
QRhi::NPOTTextureRepeat10Indica que se admiten el modo de envoltura « Repeat » y los modos de filtrado mipmap para texturas con un tamaño que no sea una potencia de dos. En la práctica, esto solo puede ser «false» en implementaciones de OpenGL ES 2.0 que no dispongan de « GL_OES_texture_npot ».
QRhi::RedOrAlpha8IsRed11Indica que el formato « RED_OR_ALPHA8 » se asigna a un formato « red » de un componente y 8 bits. Este es el caso de todos los backends, excepto OpenGL, cuando se utiliza OpenGL ES o un contexto de perfil no básico. En su lugar, se utiliza GL_ALPHA, un formato de alpha de un componente y 8 bits. El uso de este formato de textura especial permite disponer de una única ruta de código para crear texturas, dejando que sea el backend el que decida el formato real, mientras que el indicador de características se puede utilizar para seleccionar la variante de shader adecuada para el muestreo de la textura.
QRhi::ElementIndexUint12Indica que se admiten elementos enteros sin signo de 32 bits en el búfer de índices. En la práctica, esto es así en todos los casos, salvo cuando se ejecuta en implementaciones básicas de OpenGL ES 2.0 que carecen de la extensión necesaria. Cuando el valor es falso, solo se admiten elementos sin signo de 16 bits en el búfer de índices.
QRhi::Compute13Indica que se admiten shaders de cálculo, carga/almacenamiento de imágenes y búferes de almacenamiento. Las versiones de OpenGL anteriores a la 4.3 y las de OpenGL ES anteriores a la 3.1 no admiten el cálculo.
QRhi::WideLines14Indica que se admiten líneas con un ancho distinto de 1. Cuando se indica que no se admite, se ignora el ancho de línea establecido en el estado del canal gráfico. Esto siempre puede ser «false» con algunos backends (D3D11, D3D12, Metal). Con Vulkan, el valor depende de la implementación. Con OpenGL, las líneas anchas no son compatibles en contextos de perfil básico.
QRhi::VertexShaderPointSize15Indica que se tiene en cuenta el tamaño de los puntos rasterizados establecido mediante ` gl_PointSize ` en el sombreador de vértices. Cuando se indica que no es compatible, no se admite el dibujo de puntos con un tamaño distinto de 1. En ese caso, la configuración de ` gl_PointSize ` en el sombreador sigue siendo válida, pero se ignora. (por ejemplo, al generar HLSL, la asignación se omite silenciosamente del código generado). Ten en cuenta que algunas API (Metal, Vulkan) requieren que el tamaño del punto se establezca explícitamente en el sombreador siempre que se dibujen puntos, incluso cuando el tamaño sea 1, ya que no se establecen automáticamente en 1 por defecto.
QRhi::BaseVertex16Indica que drawIndexed() admite el argumento vertexOffset. Cuando se indica que no es compatible, se ignora el valor de vertexOffset en un dibujo indexado. En la práctica, esta característica no será compatible con las versiones de OpenGL y OpenGL ES anteriores a la 3.2, ni con Metal en dispositivos iOS más antiguos, incluido el simulador de iOS.
QRhi::BaseInstance17Indica que los comandos de dibujo instanciados admiten el argumento ` firstInstance `. Cuando se indica que no es compatible, se ignora el valor de `firstInstance` y el identificador de instancia comienza en 0. En la práctica, esta característica no será compatible con Metal en dispositivos iOS más antiguos, incluido el simulador de iOS, ni con ninguna versión de OpenGL. Esto último se debe a que OpenGL ES no admite en absoluto las llamadas de dibujo con una instancia base. Actualmente, el backend de OpenGL de QRhi tampoco implementa esta funcionalidad para OpenGL (no ES), ya que, en la práctica, las aplicaciones portátiles no pueden basarse en una instancia base distinta de cero debido a GLES. Si la aplicación decide hacerlo de todos modos, también debe tener en cuenta la característica InstanceIndexIncludesBaseInstance.
QRhi::TriangleFanTopology18Indica que ` QRhiGraphicsPipeline::setTopology()` es compatible con ` QRhiGraphicsPipeline::TriangleFan`. En la práctica, esta característica no será compatible con Metal ni con Direct 3D 11/12.
QRhi::ReadBackNonUniformBuffer19Indica que reading buffer contents es compatible con instancias de QRhiBuffer cuyo uso difiere del de UniformBuffer. En la práctica, esta característica no será compatible con OpenGL ES 2.0.
QRhi::ReadBackNonBaseMipLevel20Indica que se admite la especificación de un nivel de mip distinto de 0 al leer de nuevo el contenido de la textura. Cuando no se admite, especificar un nivel distinto de cero en ` QRhiReadbackDescription ` da como resultado una imagen con todos los píxeles a cero. En la práctica, esta característica no será compatible con OpenGL ES 2.0.
QRhi::TexelFetch21Indica que texelFetch() y textureLod() están disponibles en los shaders. En la práctica, se indicará que no es compatible con los contextos de OpenGL ES 2.0 y OpenGL 2.x, ya que GLSL 100 es y las versiones anteriores a la 130 no admiten estas funciones.
QRhi::RenderToNonBaseMipLevel22Indica que se admite la especificación de un nivel de mip distinto de 0 al crear un ` QRhiTextureRenderTarget ` con un ` QRhiTexture ` como adjunto de color. Cuando no se admite, ` create()` fallará siempre que el nivel de mip de destino no sea cero. En la práctica, esta característica no será compatible con OpenGL ES 2.0.
QRhi::IntAttributes23Indica que se admite la especificación de atributos de entrada con tipos de enteros con y sin signo para una canalización de sombreadores. Cuando no se admite, la función ` QRhiGraphicsPipeline::create()` se ejecutará con éxito, pero mostrará un mensaje de advertencia y los valores de los atributos de destino serán erróneos. En la práctica, esta característica no será compatible con OpenGL ES 2.0 ni con OpenGL 2.x.
QRhi::ScreenSpaceDerivatives24Indica que funciones como dFdx(), dFdy() y fwidth() son compatibles con los sombreadores. En la práctica, esta característica no será compatible con OpenGL ES 2.0 sin la extensión GL_OES_standard_derivatives.
QRhi::ReadBackAnyTextureFormat25Indica que cabe esperar que la lectura del contenido de las texturas funcione para cualquier QRhiTexture::Format. Es de esperar que los backends distintos de OpenGL devuelvan «true» para esta característica. Cuando se devuelve «false» —lo que suele ocurrir con OpenGL—, solo se garantiza la compatibilidad con los formatos QRhiTexture::RGBA8 y QRhiTexture::BGRA8 para la lectura del contenido. Además, con OpenGL —pero no con OpenGL ES—, también se admite la lectura de los formatos de 1 byte por componente QRhiTexture::R8 y QRhiTexture::RED_OR_ALPHA8. La lectura de los formatos de punto flotante QRhiTexture::RGBA16F y RGBA32F también puede funcionar con OpenGL, siempre que la implementación los admita, pero QRhi no puede ofrecer garantías al respecto, tal y como indica este indicador.
QRhi::PipelineCacheDataLoadSave26Indica que las funciones pipelineCacheData() y setPipelineCacheData() están operativas. Cuando no son compatibles, las funciones no realizarán ninguna acción, el blob recuperado estará siempre vacío y, por lo tanto, no cabe esperar ningún beneficio al recuperarlo ni al recargar el contenido de la caché del pipeline durante una ejecución posterior de la aplicación.
QRhi::ImageDataStride27Indica que se admite la especificación de un paso (longitud de fila) personalizado para los datos de imagen sin procesar en las cargas de texturas. Cuando no se admite (lo que puede ocurrir si la API subyacente es OpenGL ES 2.0 sin soporte para GL_UNPACK_ROW_LENGTH), no debe utilizarse QRhiTextureSubresourceUploadDescription::setDataStride().
QRhi::RenderBufferImport28Indica que se admite ` QRhiRenderBuffer::createFrom()`. Para la mayoría de las API gráficas, esto no tiene sentido, ya que ` QRhiRenderBuffer ` encapsula los objetos de textura internamente, al igual que ` QRhiTexture`. Sin embargo, con OpenGL, los objetos de búfer de renderizado existen como un tipo de objeto independiente en la API, y en determinados entornos (por ejemplo, cuando se desee asociar un objeto de búfer de renderizado con un objeto EGLImage) es importante permitir envolver un objeto de búfer de renderizado de OpenGL existente con un ` QRhiRenderBuffer`.
QRhi::ThreeDimensionalTextures29Indica que se admiten texturas 3D. En la práctica, esta característica no será compatible con las versiones de OpenGL y OpenGL ES anteriores a la 3.0.
QRhi::RenderTo3DTextureSlice30Indica que se admite el renderizado en una porción de una textura 3D. Es posible que esta característica no sea compatible con Vulkan 1.0, ya que depende de VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, que es una característica de Vulkan 1.1.
QRhi::TextureArrays31Indica que se admiten las matrices de texturas y que QRhi::newTextureArray() funciona. Ten en cuenta que, incluso cuando no se admiten las matrices de texturas, las matrices de texturas siguen estando disponibles, ya que se trata de dos características independientes.
QRhi::Tessellation32Indica que se admiten las etapas de control y evaluación de la teselación. Cuando se indica que son compatibles, la topología de una « QRhiGraphicsPipeline » puede establecerse en « Patches », el número de puntos de control puede configurarse mediante « setPatchControlPointCount()» y los shaders para el control y la evaluación de la teselación pueden especificarse en la lista « QRhiShaderStage ». Los sombreadores de teselación presentan problemas de portabilidad entre las API (por ejemplo, la conversión de GLSL/SPIR-V a HLSL resulta problemática debido a la forma en que están estructurados los sombreadores de casco, mientras que Metal utiliza un proceso de teselación algo diferente al de otros); por lo tanto, pueden seguir surgiendo problemas inesperados, aunque la funcionalidad básica esté implementada en todas las API subyacentes. En el caso concreto de Direct 3D, es necesario inyectar sombreadores de casco y de dominio HLSL escritos manualmente en cada « QShader » para las etapas de control y evaluación de la teselación, respectivamente, ya que qsb no puede generarlos a partir de SPIR-V. Ten en cuenta que debe evitarse la teselación de isolíneas, ya que no será compatible con todos los backends. El número máximo de puntos de control de parches transferibles entre backends es 32.
QRhi::GeometryShader33Indica que la etapa de shader de geometría es compatible. Cuando sea compatible, se podrá especificar un shader de geometría en la lista « QRhiShaderStage ». Los sombreadores de geometría se consideran una característica experimental en QRhi y solo cabe esperar que sean compatibles con Vulkan, Direct 3D 11 y 12, OpenGL (3.2+) y OpenGL ES (3.2+), siempre que la implementación lo indique como compatible en tiempo de ejecución. A partir de Qt 6.11, los sombreadores de geometría se traducen automáticamente a HLSL, por lo que ya no es necesario inyectar sombreadores de geometría HLSL escritos manualmente (pero ten en cuenta que gl_in y expresiones como gl_in[0].gl_Position no son compatibles; en su lugar, se debe pasar la posición como variable de salida desde el sombreador de vértices). Los sombreadores geométricos no son compatibles con Metal.
QRhi::TextureArrayRange34Indica que, para texture arrays, es posible especificar un rango que se exponga a los sombreadores. Normalmente, se exponen todas las capas de la matriz y corresponde al sombreador seleccionar la capa (mediante la tercera coordenada pasada a `texture()` al muestrear el ` sampler2DArray`). Cuando se admite, llamar a QRhiTexture::setArrayRangeStart() y QRhiTexture::setArrayRangeLength() antes de building o importing la textura nativa tiene efecto y hace que solo se seleccione el rango especificado de la matriz. Esto será necesario en casos especiales, como al trabajar con decodificación de vídeo acelerada y Direct 3D 11, ya que una matriz de texturas que contenga tanto D3D11_BIND_DECODER como D3D11_BIND_SHADER_RESOURCE solo se puede utilizar como recurso de shader si se selecciona una única capa de la matriz. Ten en cuenta que todo esto solo es aplicable cuando la textura se utiliza como recurso de sombreador de tipo « QRhiShaderResourceBinding::SampledTexture » o « QRhiShaderResourceBinding::Texture », y no es compatible con la carga/almacenamiento de imágenes. Esta característica solo está disponible con algunos backends, ya que no se adapta bien a todas las API gráficas, y, en cualquier caso, solo está pensada para ofrecer soporte en casos especiales. En la práctica, cabe esperar que esta característica sea compatible con Direct3D 11/12 y Vulkan.
QRhi::NonFillPolygonMode35Indica que se admite la configuración de un PolygonMode distinto del valor predeterminado «Fill» para « QRhiGraphicsPipeline ». Un caso de uso habitual para cambiar el modo a «Line» es obtener un renderizado de estructura alámbrica. Sin embargo, esto no está disponible como característica básica de OpenGL ES, y es opcional en Vulkan, además de que es posible que algunas GPU móviles no ofrezcan esta característica.
QRhi::OneDimensionalTextures36Indica que se admiten texturas 1D. En la práctica, esta característica no será compatible con OpenGL ES.
QRhi::OneDimensionalTextureMipmaps37Indica que se admite la generación de mipmaps de texturas 1D. En la práctica, esta característica no será compatible en los backends que no indiquen compatibilidad con OneDimensionalTextures, Metal y Direct 3D 12.
QRhi::HalfAttributes38Indica que se admite la especificación de atributos de entrada con tipos de punto flotante de media precisión (16 bits) para una canalización de sombreadores. Cuando no sea compatible, la llamada a ` QRhiGraphicsPipeline::create()` se ejecutará con éxito, pero mostrará un mensaje de advertencia y los valores de los atributos de destino serán erróneos. En la práctica, esta característica no será compatible con algunas implementaciones de OpenGL ES 2.0 y OpenGL 2.x. Tenga en cuenta que, aunque Direct3D 11/12 admite atributos de entrada de media precisión, no admite el tipo half3. Los backends de D3D pasan los atributos half3 como half4. Para garantizar la compatibilidad entre plataformas, las entradas half3 deben rellenarse hasta 8 bytes.
QRhi::RenderToOneDimensionalTexture39Indica que se admiten destinos de renderizado de texturas 1D. En la práctica, esta característica no será compatible con los backends que no indiquen compatibilidad con OneDimensionalTextures, ni con Metal.
QRhi::ThreeDimensionalTextureMipmaps40Indica que se admite la generación de mipmaps de texturas 3D. Normalmente, esto es compatible con todos los backends a partir de Qt 6.10.
QRhi::MultiView41Indica que se admite la vista múltiple; véase, por ejemplo, VK_KHR_multiview. Con las implementaciones de OpenGL ES 2.0, Direct 3D 11 y OpenGL (ES) que no incluyan « GL_OVR_multiview2 », esta característica no será compatible. Con Vulkan 1.1 y versiones posteriores, así como con Direct 3D 12, la función multivista suele ser compatible. Cuando se indica que es compatible, la creación de un « QRhiTextureRenderTarget » con un « QRhiColorAttachment » que haga referencia a una matriz de texturas y tenga « multiViewCount » activado permite grabar una pasada de renderizado que utilice renderizado multivista. Además, cualquier ` QRhiGraphicsPipeline ` utilizado en ese paso de renderizado debe tener ` the same view count set`. Ten en cuenta que la multivista solo está disponible en combinación con matrices de texturas 2D. No se puede utilizar para optimizar el renderizado en texturas individuales (por ejemplo, dos, para el ojo izquierdo y el derecho). Más bien, el destino de una pasada de renderizado multivista es siempre una matriz de texturas, que se renderiza automáticamente en la capa (elemento de la matriz) correspondiente a cada vista. Por lo tanto, esta característica implica también el uso de matrices de texturas. El renderizado multivista no es compatible con la teselación ni con los shaders de geometría. Consulte QRhiColorAttachment::setMultiViewCount() para obtener más detalles sobre el renderizado multivista. Este valor de enumeración se ha introducido en Qt 6.7.
QRhi::TextureViewFormat42Indica que la configuración de un formato de visualización ( view format ) en un objeto de textura ( QRhiTexture ) es efectiva. Cuando se indica que es compatible, al establecer el modo de visualización de lectura (muestreo) o de escritura (destino de renderizado / carga-almacenamiento de imágenes) se modifica el formato de visualización de la textura. Cuando no es compatible, la configuración de un formato de visualización no tiene ningún efecto. Tenga en cuenta que Qt no tiene conocimiento ni control sobre la compatibilidad de formatos ni sobre las reglas de visualización de recursos en la API 3D subyacente y su implementación. Pasar formatos inadecuados o incompatibles puede provocar errores y un comportamiento no especificado. Esto se proporciona principalmente para permitir la «conversión» del renderizado en una textura creada con un formato sRGB a un formato distinto de sRGB, con el fin de evitar la conversión no deseada de lineal a sRGB en las escrituras del shader. Otros tipos de conversión pueden funcionar o no, dependiendo de la API subyacente. Actualmente está implementado para Vulkan y Direct 3D 12. Con D3D12, la función solo está disponible si se admite « CastingFullyTypedFormatSupported »; véase https://microsoft.github.io/DirectX-Specs/d3d/RelaxedCasting.html (y ten en cuenta que QRhi siempre utiliza formatos totalmente tipados para las texturas). Este valor de enumeración se ha introducido en Qt 6.8.
QRhi::ResolveDepthStencil43Indica que se admite la resolución de una textura de profundidad multimuestra o de profundidad-estencil. De lo contrario, setting a depth resolve texture no funciona y debe evitarse. Direct 3D 11 y 12 no admiten la resolución de formatos de profundidad/profundidad-estencil, por lo que esta característica nunca será compatible con ellos. Vulkan 1.0 no dispone de ninguna API para solicitar la resolución de un anexo de profundidad-plantilla. Por lo tanto, con Vulkan esta característica solo será compatible a partir de la versión 1.2 y, en implementaciones de la versión 1.1, si se dispone de las extensiones adecuadas. Esta característica se proporciona para los casos excepcionales en los que sea necesario resolver en una textura de profundidad no multimuestreada, por ejemplo, al renderizar en una textura de profundidad proporcionada por OpenXR (XR_KHR_composition_layer_depth). Este valor de enumeración se ha introducido en Qt 6.8.
QRhi::VariableRateShading44Indica que se admite el sombreado de tasa variable por dibujo (por canal). Cuando se indica que está admitido, la función ` QRhiCommandBuffer::setShadingRate()` es operativa y tiene efecto para los objetos ` QRhiGraphicsPipeline ` que hayan declarado ` QRhiGraphicsPipeline::UsesShadingRate ` en sus indicadores. Llama a QRhi::supportedShadingRates() para comprobar qué tasas son compatibles. (1x1 siempre es compatible; otros valores habituales son 2x2, 1x2, 2x1, 2x4, 4x2 y 4x4). Cabe esperar que esta característica sea compatible con Direct 3D 12 y Vulkan, siempre que la implementación y la GPU utilizadas en tiempo de ejecución admitan VRS. Este valor de enumeración se ha introducido en Qt 6.9.
QRhi::VariableRateShadingMap45Indica que es posible especificar la tasa de sombreado mediante una imagen. La «imagen» no tiene por qué ser necesariamente una textura, sino que puede ser un objeto nativo de la API 3D, dependiendo del backend subyacente y de la API gráfica en tiempo de ejecución. En la práctica, cabe esperar que esta característica sea compatible con Direct 3D 12, Vulkan y Metal, siempre que la GPU sea lo suficientemente moderna como para admitir VRS. Para comprobar si se admite el VRS basado en imágenes al estilo de D3D12/Vulkan, utiliza en su lugar `VariableRateShadingMapWithTexture`. Cuando se indica que esta función es compatible, existen dos posibilidades: si `VariableRateShadingMapWithTexture` también es `true`, entonces ` QRhiShadingRateMap ` consume objetos ` QRhiTexture ` a través de la sobrecarga de `createFrom()` que toma un argumento ` QRhiTexture `. Cuando `VariableRateShadingMapWithTexture` es `false`, entonces ` QRhiShadingRateMap ` consume algún otro tipo de objetos nativos, por ejemplo, un `MTLRasterizationRateMap` en el caso de Metal. En este caso, utilice la sobrecarga de `createFrom()` que toma un `NativeShadingRateMap`. Este valor de enumeración se ha introducido en Qt 6.9.
QRhi::VariableRateShadingMapWithTexture46Indica que se admite la especificación basada en imágenes de la tasa de sombreado mediante texturas normales. En la práctica, esto puede ser compatible con Direct 3D 12 y Vulkan. Este valor de enumeración se ha introducido en Qt 6.9.
QRhi::PerRenderTargetBlending47Indica que se admite la mezcla por objetivo de renderizado; es decir, que los distintos objetivos de renderizado del framebuffer MRT pueden tener diferentes modos de mezcla. En la práctica, cabe esperar que esto sea compatible en todas partes excepto en OpenGL ES, donde solo está disponible con implementaciones de GLES 3.2. Este valor de enumeración se ha introducido en Qt 6.9.
QRhi::SampleVariables48Indica que las variables gl_SampleID, gl_SamplePosition, gl_SampleMaskIn y gl_SampleMask están disponibles en los sombreadores de fragmentos. En la práctica, cabe esperar que esto sea compatible en todas partes excepto en OpenGL ES, donde solo está disponible con implementaciones de GLES 3.2. Este valor de enumeración se ha introducido en Qt 6.9.
QRhi::InstanceIndexIncludesBaseInstance49Indica que ` gl_InstanceIndex ` incluye la instancia base (el argumento ` firstInstance ` en las llamadas de dibujo) en su valor. Cuando esta característica no es compatible, pero sí lo es `BaseInstance`, esto indica que ` gl_InstanceIndex ` siempre comienza en 0, y no en el valor base. En la práctica, este será el caso actualmente para Direct 3D 11 y 12. Con Vulkan y Metal, se espera que esta característica se indique siempre como compatible. Este valor de enumeración se ha introducido en Qt 6.11.
QRhi::DepthClamp (since Qt 6.11)50Indica que se admite la activación del «depth clamping». Cuando se indica que no es compatible —lo cual ocurrirá con OpenGL ES, las versiones de OpenGL anteriores a la 3.2 que no cuenten con la extensión correspondiente y Metal en el simulador de iOS—, llamar a QRhiGraphicsPipeline::setDepthClamp() con el argumento true no tiene ningún efecto.
QRhi::DrawIndirect (since Qt 6.12)51Indica que las funciones ` drawIndirect()` y ` drawIndexedIndirect()` están disponibles. En la práctica, cabe esperar que esto sea compatible en todas partes, excepto en OpenGL ES < 3.1.
QRhi::DrawIndirectMulti (since Qt 6.12)52Indica que el backend admite de forma nativa un drawCount > 1 en drawIndirect() y drawIndexedIndirect(). De lo contrario, el RHI emite múltiples llamadas de dibujo en la CPU. En la práctica, cabe esperar que esto sea compatible con Vulkan 1.1+, OpenGL 4.3+ y D3D12.
QRhi::ShaderDrawParameters (since Qt 6.12)53Indica que las variables integradas ` gl_BaseInstance`, ` gl_BaseVertex ` y ` gl_DrawID ` están disponibles en los shaders. En la práctica, cabe esperar que esto sea compatible con Vulkan 1.1+ y con OpenGL 4.6 para ordenadores de sobremesa o GL_ARB_shader_draw_parameters.

enum QRhi::Flag
flags QRhi::Flags

Describe qué funciones especiales hay que activar.

ConstanteValorDescripción
QRhi::EnableDebugMarkers1 << 0Activa los grupos de marcadores de depuración. Sin esta opción, no estarán disponibles las funciones de depuración de fotogramas, como hacer visibles los grupos de depuración y los nombres de recursos personalizados en herramientas externas de depuración de la GPU, y funciones como ` QRhiCommandBuffer::debugMarkBegin()` dejarán de tener efecto. Evita activarla en compilaciones de producción, ya que puede suponer un ligero impacto en el rendimiento. No tiene ningún efecto cuando la función « QRhi::DebugMarkers » no se indica como compatible.
QRhi::EnableTimestamps1 << 3Habilita la recopilación de marcas de tiempo de la GPU. Cuando no está activada, QRhiCommandBuffer::lastCompletedGpuTime() siempre devuelve 0. Habilítala solo cuando sea necesario, ya que puede suponer una pequeña cantidad de trabajo adicional (por ejemplo, consultas de marcas de tiempo), dependiendo de la API gráfica subyacente. No tiene ningún efecto cuando la función QRhi::Timestamps no se indica como compatible.
QRhi::PreferSoftwareRenderer1 << 1Indica que los backends deben dar preferencia a la elección de un adaptador o dispositivo físico que realice el renderizado por software en la CPU. Por ejemplo, con Direct3D suele haber un adaptador «Basic Render Driver» disponible con DXGI_ADAPTER_FLAG_SOFTWARE. Al activar este indicador, se solicita al backend que elija ese adaptador frente a cualquier otro, siempre que no se haya impuesto un adaptador específico mediante otros medios propios del backend. Con Vulkan, esto se traduce en dar preferencia a los dispositivos físicos con VK_PHYSICAL_DEVICE_TYPE_CPU. Cuando no esté disponible, o cuando no sea posible determinar si un adaptador o dispositivo es de tipo software, se ignorará este indicador. También puede ignorarse con API gráficas que no cuenten con el concepto ni los medios para enumerar adaptadores o dispositivos.
QRhi::EnablePipelineCacheDataSave1 << 2Habilita la recuperación del contenido de la caché de la canalización, cuando sea aplicable. Cuando no está activada, ` pipelineCacheData()` devolverá siempre un blob vacío. Con backends en los que no se admite la recuperación y restauración del contenido de la caché de la canalización, el indicador no tiene ningún efecto y los datos serializados de la caché estarán siempre vacíos. El indicador proporciona un mecanismo de activación opcional, ya que el coste de mantener las estructuras de datos relacionadas no es insignificante en algunos backends. Con Vulkan, esta característica se corresponde directamente con VkPipelineCache, vkGetPipelineCacheData y VkPipelineCacheCreateInfo::pInitialData. Con Direct3D 11 no existe una caché de pipeline propiamente dicha, pero los resultados de las compilaciones de HLSL a DXBC se almacenan y pueden serializarse y deserializarse mediante este mecanismo. Esto permite omitir la función D3DCompile(), que consume mucho tiempo, en futuras ejecuciones de las aplicaciones para los shaders que vienen con código fuente HLSL en lugar de bytecode precompilado fuera de línea. Esto puede suponer una mejora considerable en los tiempos de inicio y carga, si se realizan muchas compilaciones de código fuente HLSL. Con OpenGL, la «caché de pipeline» se simula recuperando y cargando los binarios de los programas de shader (si el controlador lo admite). En OpenGL, Qt proporciona mecanismos adicionales de almacenamiento en caché basados en disco para los binarios de shaders y programas. La escritura en dichos mecanismos puede desactivarse siempre que se active este indicador, ya que no tiene sentido almacenar binarios de programas en múltiples cachés.
QRhi::SuppressSmokeTestWarnings1 << 4Indica que, en los backends en los que esto sea relevante, ciertos errores no fatales de ` QRhi::create()` no deben generar llamadas a ` qWarning()`. Por ejemplo, con D3D11, al pasar este indicador, varios mensajes de advertencia (que aparecen debido a que falla ` QRhi::create()`) pasan a clasificarse como mensajes de depuración dentro de la categoría de registro de uso común ` qt.rhi.general `. Esto puede ser utilizado por motores, como Qt Quick, que cuentan con lógica de recambio, es decir, que vuelven a intentar llamar a create() con un conjunto diferente de indicadores (como, por ejemplo, PreferSoftwareRenderer), con el fin de ocultar de la salida las advertencias incondicionales que se imprimirían si el primer intento de create() hubiera fallado.

El tipo Flags es un typedef de QFlags<Flag>. Almacena una combinación OR de valores de Flag.

enum QRhi::FrameOpResult

Describe el resultado de operaciones que pueden dar lugar a un fallo leve.

ConstanteValorDescripción
QRhi::FrameOpSuccess0Éxito
QRhi::FrameOpError1Error no especificado
QRhi::FrameOpSwapChainOutOfDate2La cadena de intercambio se encuentra en un estado incoherente internamente. Esto puede solucionarse intentando repetir la operación (por ejemplo, beginFrame()) más tarde.
QRhi::FrameOpDeviceLost3Se ha perdido el dispositivo gráfico. Esto se puede solucionar intentando repetir la operación (por ejemplo, beginFrame()) tras liberar y reinicializar todos los objetos respaldados por recursos gráficos nativos. Véase isDeviceLost().

enum QRhi::Implementation

Describe qué backend específico de la API gráfica utiliza una instancia de ` QRhi `.

ConstanteValor
QRhi::Null0
QRhi::Vulkan1
QRhi::OpenGLES22
QRhi::D3D113
QRhi::D3D125
QRhi::Metal4

enum QRhi::ResourceLimit

Describe el límite de recursos para la consulta.

ConstanteValorDescripción
QRhi::TextureSizeMin1Ancho y alto mínimos de la textura. Normalmente es 1. El tamaño mínimo de la textura se gestiona de forma flexible, lo que significa que, si se intenta crear una textura con un tamaño vacío, se creará en su lugar una textura con el tamaño mínimo.
QRhi::TextureSizeMax2Ancho y altura máximos de la textura. Dependen de la API gráfica y, en ocasiones, también de la plataforma o la implementación. Normalmente, el valor se encuentra en el rango de 4096 a 16384. Se espera que falle cualquier intento de crear texturas de mayor tamaño.
QRhi::MaxColorAttachments3El número máximo de adjuntos de color para un ` QRhiTextureRenderTarget`, en caso de que se admitan múltiples destinos de renderizado (MRT). Cuando no se admite MRT, el valor es 1. En caso contrario, suele ser 8, pero hay que tener en cuenta que OpenGL solo exige 4 como mínimo, y eso es lo que ofrecen algunas implementaciones de OpenGL ES.
QRhi::FramesInFlight4El número de fotogramas que el backend puede mantener «en vuelo»: con backends como Vulkan o Metal, es responsabilidad de QRhi bloquearse cada vez que se inicie un nuevo fotograma y se detecte que la CPU ya se ha adelantado a la GPU en N - 1 s de fotogramas (porque el búfer de comandos enviado en el fotograma n.º current - N aún no se ha completado). El valor N es el que se devuelve desde aquí, y suele ser 2. Esto puede ser relevante para aplicaciones que integran el renderizado realizado directamente con la API gráfica, ya que dicho código de renderizado podría querer realizar un doble almacenamiento en búfer (si el valor es 2) para recursos, como los búferes, de forma similar a los propios backends de QRhi. El índice de ranura del fotograma actual (un valor que va de 0, 1, …, N-1, y luego vuelve a empezar) se puede obtener mediante ` QRhi::currentFrameSlot()`. El valor es 1 para los backends en los que la API gráfica no ofrece ese control de bajo nivel sobre el proceso de envío de comandos. Tenga en cuenta que el procesamiento en pipeline puede seguir produciéndose incluso cuando este valor sea 1 (algunos backends, como D3D11, están diseñados para intentar habilitarlo, por ejemplo, utilizando una estrategia de actualización para los búferes uniformes que no bloquea el pipeline), pero en ese caso no lo controla QRhi y, por lo tanto, no se refleja aquí en la API.
QRhi::MaxAsyncReadbackFrames5El número de fotogramas de « submitted » (incluido el que contiene la lectura posterior) tras el cual se garantiza que una lectura asíncrona de textura o búfer se completará al llamar a ` starting a new frame`.
QRhi::MaxThreadGroupsPerDimension6El número máximo de grupos de trabajo de cálculo o de subprocesos que se pueden enviar. En la práctica, es el valor máximo para los argumentos de ` QRhiCommandBuffer::dispatch()`. Normalmente es 65535.
QRhi::MaxThreadsPerThreadGroup7El número máximo de invocaciones en un único grupo de trabajo local o, dicho de otro modo, el número máximo de subprocesos en un grupo de subprocesos. En la práctica, es el valor máximo del producto de local_size_x, local_size_y y local_size_z en el shader de cálculo. Los valores habituales son 128, 256, 512, 1024 o 1536. Hay que tener en cuenta que tanto OpenGL ES como Vulkan especifican únicamente 128 como límite mínimo requerido para las implementaciones. Aunque es poco habitual en Vulkan, algunas implementaciones de OpenGL ES 3.1 para dispositivos móviles o integrados solo admiten el valor mínimo exigido por la especificación.
QRhi::MaxThreadGroupX8El tamaño máximo de un grupo de trabajo/hilo en la dimensión X. En la práctica, es el valor máximo de ` local_size_x ` en el shader de cálculo. Normalmente es 256 o 1024.
QRhi::MaxThreadGroupY9El tamaño máximo de un grupo de trabajo o de subprocesos en la dimensión Y. En la práctica, es el valor máximo de ` local_size_y ` en el shader de cálculo. Normalmente es 256 o 1024.
QRhi::MaxThreadGroupZ10El tamaño máximo de un grupo de trabajo/hilo en la dimensión Z. En la práctica, es el valor máximo de ` local_size_z ` en el shader de cálculo. Normalmente es 64 o 256.
QRhi::TextureArraySizeMax11Tamaño máximo de la matriz de texturas. Normalmente oscila entre 256 y 2048. Si se intenta utilizar ` create a texture array ` con más elementos, es probable que la operación falle.
QRhi::MaxUniformBufferRange12El número de bytes que se pueden exponer desde un búfer uniforme a los sombreadores de una sola vez. En las implementaciones de OpenGL ES 2.0 y 3.0, este valor puede ser tan bajo como 3584 bytes (224 vectores de cuatro componentes, con 32 bits por componente). En otros casos, el valor suele ser 16 384 (1 024 vec4) o 65 536 (4 096 vec4).
QRhi::MaxVertexInputs13El número de atributos de entrada al sombreador de vértices. La ubicación en un « QRhiVertexInputAttribute » debe estar comprendida en el intervalo [0, MaxVertexInputs-1]. El valor puede ser tan bajo como 8 en OpenGL ES 2.0. En otros casos, los valores habituales son 16, 31 o 32.
QRhi::MaxVertexOutputs14El número máximo de salidas (variables de « out » de vectores de 4 componentes) del sombreador de vértices. El valor puede ser tan bajo como 8 con OpenGL ES 2.0, y de 15 con OpenGL ES 3.0 y algunos dispositivos Metal. En otros casos, un valor típico es 32.
QRhi::ShadingRateImageTileSize15El tamaño de mosaico para las texturas de tasa de sombreado. 0 si no se admite la función « QRhi::VariableRateShadingMapWithTexture ». En caso contrario, un valor como 16, que indica, por ejemplo, un tamaño de mosaico de 16x16. Cada byte de la textura de tasa de sombreado (R8UI) define entonces la tasa de sombreado para un mosaico de 16x16 píxeles. Consulte QRhiShadingRateMap para obtener más detalles.

Documentación de las funciones miembro

[noexcept] QRhi::~QRhi()

Destructor. Destruye el backend y libera recursos.

void QRhi::addCleanupCallback(const QRhi::CleanupCallback &callback)

Registra un ` callback ` que se invoca cuando se destruye el ` QRhi `.

La función de devolución de llamada se ejecutará mientras el recurso gráfico siga estando disponible, lo que brinda a la aplicación la oportunidad de liberar de forma ordenada las instancias de ` QRhiResource ` pertenecientes al ` QRhi`. Esto resulta especialmente útil para gestionar el ciclo de vida de los recursos almacenados en objetos de tipo ` cache `, en los que la caché contiene `QRhiResources` u objetos que contienen `QRhiResources`.

Véase también ~QRhi().

void QRhi::addCleanupCallback(const void *key, const QRhi::CleanupCallback &callback)

Registra callback para que se invoque cuando se destruya QRhi. Esta sobrecarga toma un puntero opaco, key, que se utiliza para garantizar que una determinada función de devolución de llamada se registre (y, por tanto, se invoque) solo una vez.

Se trata de una función sobrecargada.

Véase también removeCleanupCallback().

QRhi::Implementation QRhi::backend() const

Devuelve el tipo de backend correspondiente a este QRhi.

const char *QRhi::backendName() const

Devuelve el tipo de backend como cadena para este QRhi.

[static] const char *QRhi::backendName(QRhi::Implementation impl)

Devuelve un nombre descriptivo para el backend impl, que suele ser el nombre de la API 3D que se está utilizando.

QRhi::FrameOpResult QRhi::beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags = {})

Inicia un nuevo fotograma dirigido al siguiente búfer disponible de swapChain.

Un fotograma consta de actualizaciones de recursos y una o más pasadas de renderizado y cálculo.

flags puede indicar ciertos casos especiales.

El patrón general para renderizar en una cadena de intercambio ( QWindow ) utilizando una cadena de intercambio (swapchain):

  • Crea una cadena de intercambio.
  • Llamar a ` QRhiSwapChain::createOrResize()` siempre que el tamaño de la superficie sea diferente al anterior.
  • Llamar a ` QRhiSwapChain::destroy()` en ` QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed`.
  • A continuación, en cada fotograma:
    beginFrame(sc);
    updates = nextResourceUpdateBatch();
    updates->...
    QRhiCommandBuffer *cb = sc->currentFrameCommandBuffer();
    cb->beginPass(sc->currentFrameRenderTarget(), colorClear, dsClear, updates);
    ...
    cb->endPass();
    ... // more passes as necessary
    endFrame(sc);

Devuelve ` QRhi::FrameOpSuccess ` si se realiza correctamente, u otro valor de ` QRhi::FrameOpResult ` en caso de fallo. Algunos de estos errores deben tratarse como errores leves, del tipo «inténtalo más tarde»: cuando se devuelve ` QRhi::FrameOpSwapChainOutOfDate `, hay que redimensionar o actualizar la cadena de intercambio llamando a ` QRhiSwapChain::createOrResize()`. A continuación, la aplicación debe intentar generar un nuevo fotograma. « QRhi::FrameOpDeviceLost » significa que se ha perdido el dispositivo gráfico, pero esto también puede recuperarse liberando todos los recursos, incluido el propio QRhi, y volviendo a crear todos los recursos. Véase isDeviceLost() para más información.

Véanse también endFrame(), beginOffscreenFrame() y isDeviceLost().

QRhi::FrameOpResult QRhi::beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags = {})

Inicia un nuevo fotograma fuera de pantalla. Proporciona un búfer de comandos adecuado para registrar comandos de renderizado en cb. Se utiliza flags para indicar ciertos casos especiales, al igual que con beginFrame().

Nota: El QRhiCommandBuffer almacenado en *cb no es propiedad de quien realiza la llamada.

También es posible realizar el renderizado sin una cadena de intercambio. El caso de uso típico es utilizarlo en aplicaciones completamente fuera de pantalla, por ejemplo, para generar secuencias de imágenes mediante el renderizado y la lectura posterior sin mostrar nunca una ventana.

También es posible su uso en aplicaciones en pantalla (es decir, beginFrame, endFrame, beginOffscreenFrame, endOffscreenFrame, beginFrame, etc.).

Cuando se programa una lectura de texture o buffer, los fotogramas fuera de pantalla evitan que la CPU genere potencialmente otro fotograma mientras la GPU sigue procesando el anterior. Esto tiene el efecto secundario de que, si se programan lecturas, se garantiza que los resultados estarán disponibles una vez que endOffscreenFrame() devuelva un valor. No ocurre lo mismo con los fotogramas destinados a una cadena de intercambio (swapchain): en ese caso, la GPU se aprovecha potencialmente mejor, pero trabajar con operaciones de lectura posterior requiere mayor precaución por parte de la aplicación, ya que endFrame(), a diferencia de endOffscreenFrame(), no garantiza que los resultados de la lectura posterior estén disponibles en ese momento.

El esquema básico para renderizar un fotograma sin una cadena de intercambio y, a continuación, volver a leer el contenido del fotograma podría ser el siguiente:

QRhiReadbackResult rbResult;
QRhiCommandBuffer *cb;
rhi->beginOffscreenFrame(&cb);
cb->beginPass(rt, colorClear, dsClear);
// ...
u = nextResourceUpdateBatch();
u->readBackTexture(rb, &rbResult);
cb->endPass(u);
rhi->endOffscreenFrame();
// image data available in rbResult

Véanse también endOffscreenFrame() y beginFrame().

QMatrix4x4 QRhi::clipSpaceCorrMatrix() const

Devuelve una matriz que permite a las aplicaciones seguir utilizando datos de vértices y matrices de proyección en perspectiva orientados a OpenGL (como, por ejemplo, los generados por QMatrix4x4::perspective()), independientemente del backend de QRhi activo.

En un renderizador típico, una vez que se utiliza ` this_matrix * mvp ` en lugar de simplemente ` mvp`, se pueden utilizar datos de vértices con el eje Y hacia arriba y ventanas de visualización con un rango de profundidad de 0 a 1 sin tener en cuenta qué backend (y, por tanto, qué API gráfica) se va a utilizar en tiempo de ejecución. De esta forma, se puede evitar la ramificación basada en ` isYUpInNDC()` y ` isClipDepthZeroToOne()` (aunque dicha lógica puede seguir siendo necesaria al implementar ciertas técnicas gráficas avanzadas).

Consulta esta página para ver un análisis del tema desde la perspectiva de Vulkan.

[static] QRhi *QRhi::create(QRhi::Implementation impl, QRhiInitParams *params, QRhi::Flags flags, QRhiNativeHandles *importDevice, QRhiAdapter *adapter)

Devuelve una nueva instancia de ` QRhi ` con un backend para la API gráfica especificada por ` impl ` y con el ` flags` indicado. Devuelve ` nullptr ` si la función falla.

params debe apuntar a una instancia de una de las subclases específicas del backend de QRhiInitParams, tales como QRhiVulkanInitParams, QRhiMetalInitParams, QRhiD3D11InitParams, QRhiD3D12InitParams o QRhiGles2InitParams. Consulte estas clases para ver ejemplos sobre cómo crear un QRhi.

QRhi Por diseño, no implementa ninguna lógica de recambio: si no se puede inicializar la API especificada, create() fallará y los backends mostrarán advertencias en la salida de depuración. Sin embargo, los clientes de QRhi, por ejemplo Qt Quick, pueden proporcionar lógica adicional que permita recurrir a una API diferente a la solicitada, dependiendo de la plataforma. Si la intención es simplemente comprobar si la inicialización se realizaría con éxito al llamar a `create()` en un momento posterior, es preferible utilizar ` probe()` en lugar de `create()`, ya que con algunos backends la comprobación puede implementarse de forma más ligera que con `create()`, que lleva a cabo una inicialización completa de la infraestructura y resulta un desperdicio si esa instancia de ` QRhi ` se desecha inmediatamente después.

importDevice permite utilizar un dispositivo gráfico ya existente, sin que QRhi cree uno propio. Cuando no es nulo, este parámetro debe apuntar a una instancia de una de las subclases de QRhiNativeHandles: QRhiVulkanNativeHandles, QRhiD3D11NativeHandles, QRhiD3D12NativeHandles, QRhiMetalNativeHandles, QRhiGles2NativeHandles. Los detalles exactos y la semántica dependen del backend y de la API gráfica subyacente.

Especificar un « QRhiAdapter » en ` adapter ` ofrece una alternativa transparente e independiente de la API a pasar un « VkPhysicalDevice » mediante ` QRhiVulkanNativeHandles` o un «adapter LUID» mediante ` QRhiD3D12NativeHandles`. No se adquiere la propiedad de ` adapter `. Consulta ` enumerateAdapters()` para obtener más información sobre este enfoque.

Nota: No se pueden especificar a la vezimportDevice y adapter.

Véase también probe().

[static] QRhi *QRhi::create(QRhi::Implementation impl, QRhiInitParams *params, QRhi::Flags flags = {}, QRhiNativeHandles *importDevice = nullptr)

Equivalente a create(impl, params, flags, importDevice, nullptr).

Se trata de una función sobrecargada.

int QRhi::currentFrameSlot() const

Devuelve el índice de la ranura del fotograma actual mientras se graba un fotograma. Sin especificar cuando se invoca fuera de un fotograma activo (es decir, cuando isRecordingFrame() se encuentra en false).

Con backends como Vulkan o Metal, es responsabilidad del backend QRhi bloquearse cada vez que se inicie un nuevo fotograma y se detecte que la CPU ya se ha FramesInFlight - 1 fotogramas por delante de la GPU (porque el búfer de comandos enviado en el fotograma n.º current - FramesInFlight aún no se ha completado).

Los recursos que tienden a cambiar entre fotogramas (como, por ejemplo, el objeto de búfer nativo que respalda un QRhiBuffer de tipo QRhiBuffer::Dynamic) existen en múltiples versiones, de modo que cada fotograma —que puede enviarse mientras aún se está procesando el anterior— funciona con su propia copia, evitando así la necesidad de detener el proceso al preparar el fotograma. (No se debe modificar el contenido de un recurso que aún pueda estar en uso en la GPU, pero limitarse a esperar siempre a que finalice el fotograma anterior reduciría la utilización de la GPU y, en última instancia, el rendimiento y la eficiencia).

Conceptualmente, esto es algo similar a los esquemas de «copia al escribir» (copy-on-write) que utilizan algunos contenedores de C++ y otros tipos. También puede ser similar a lo que una implementación de OpenGL o Direct 3D 11 realiza internamente para ciertos tipos de objetos.

En la práctica, este doble (o triple) almacenamiento en búfer de recursos se lleva a cabo en los backends de Vulkan, Metal y otros similares QRhi mediante un número fijo de recursos nativos (como, por ejemplo, VkBuffer) slots detrás de un QRhiResource. A continuación, se puede indexar mediante un índice de ranura de fotograma que va de 0, 1, …, FramesInFlight-1, y luego vuelve a empezar.

Todo esto se gestiona de forma transparente para los usuarios de QRhi. Sin embargo, es posible que las aplicaciones que integran el renderizado realizado directamente con la API gráfica deseen llevar a cabo un doble o triple búfer similar de sus propios recursos gráficos. La forma más sencilla de lograrlo es conocer los valores del número máximo de fotogramas en proceso (que se puede obtener mediante resourceLimit()) y el índice del fotograma (ranura) actual (que devuelve esta función).

Véanse también isRecordingFrame(), beginFrame() y endFrame().

QRhiDriverInfo QRhi::driverInfo() const

Devuelve los metadatos del dispositivo gráfico utilizado por esta instancia de ` QRhi ` inicializada correctamente.

QRhi::FrameOpResult QRhi::endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags = {})

Finaliza, confirma y presenta un fotograma que se inició en la última llamada a beginFrame() en swapChain.

El almacenamiento en búfer doble (o triple) se gestiona internamente mediante QRhiSwapChain y QRhi.

flags Opcionalmente, se puede utilizar para modificar el comportamiento de determinadas formas. Al pasar QRhi::SkipPresent, se omite la puesta en cola del comando Present o la llamada a swapBuffers.

Devuelve ` QRhi::FrameOpSuccess ` en caso de éxito, u otro valor de ` QRhi::FrameOpResult ` en caso de fallo. Algunos de estos deben tratarse como errores leves, del tipo «inténtalo más tarde»: cuando se devuelve ` QRhi::FrameOpSwapChainOutOfDate `, la cadena de intercambio debe redimensionarse o actualizarse llamando a ` QRhiSwapChain::createOrResize()`. A continuación, la aplicación debe intentar generar un nuevo fotograma. « QRhi::FrameOpDeviceLost » significa que se ha perdido el dispositivo gráfico, pero esto también puede recuperarse liberando todos los recursos, incluido el propio QRhi, y volviendo a crear todos los recursos. Véase isDeviceLost() para más información.

Véanse también beginFrame() y isDeviceLost().

QRhi::FrameOpResult QRhi::endOffscreenFrame(QRhi::EndFrameFlags flags = {})

Finaliza, envía y, posiblemente, espera a que se complete el fotograma fuera de pantalla.

A diferencia de ` endFrame()`, esta función se bloqueará y esperará a que finalice el trabajo en la GPU cuando haya lecturas activas de búferes o texturas.

flags Actualmente no se utiliza.

Véase también beginOffscreenFrame().

[static, since 6.10] QRhi::AdapterList QRhi::enumerateAdapters(QRhi::Implementation impl, QRhiInitParams *params, QRhiNativeHandles *nativeHandles = nullptr)

Devuelve la lista de adaptadores (dispositivos físicos) presentes, o una lista vacía cuando dicha función no está disponible en una API gráfica determinada.

En los backends en los que no se dispone de ese nivel de control, la lista devuelta siempre está vacía. Por lo tanto, una lista vacía no indica que no haya dispositivos gráficos en el sistema, sino que no se dispone de un control detallado para seleccionar cuál utilizar.

Cabe esperar que los backends para Direct 3D 11, Direct 3D 12 y Vulkan admitan plenamente la enumeración de adaptadores. Es posible que otros no lo hagan. El backend se especifica mediante ` impl`. Un objeto ` QRhiAdapter ` devuelto por esta función solo debe utilizarse en una llamada a ` create()` con el mismo ` impl`. Algunas API subyacentes pueden presentar limitaciones adicionales; en el caso concreto de Vulkan, el ` QRhiAdapter ` se especifica en el ` QVulkanInstance ` (`VkInstance`).

Se espera que el llamante destruya los objetos QRhiAdapter de la lista. Aparte de consultar info(), el único propósito de estos objetos es ser pasados a create() o a las funciones correspondientes en capas superiores, como Qt Quick.

El siguiente fragmento de código, escrito específicamente para Vulkan, muestra cómo enumerar los dispositivos físicos disponibles y solicitar la creación de un ` QRhi ` para el dispositivo elegido. En la práctica, esto equivale a pasar un ` VkPhysicalDevice ` a través de un ` QRhiVulkanNativeHandles ` a ` create()`, pero implica menos código específico de la API por parte de la aplicación:

QRhiVulkanInitParams initParams;
initParams.inst = &vulkanInstance;
QRhi::AdapterList adapters = QRhi::enumerateAdapters(QRhi::Vulkan, &initParams);
QRhiAdapter*chosenAdapter = nullptr;
for (QRhiAdapter*adaptador: adaptadores) {
    if (looksGood(adaptador->info())) {
        adaptadorElegido = adaptador;
        break;
    }
}
QRhi*rhi = QRhi::create(QRhi::Vulkan, &initParams, {}, nullptr, chosenAdapter);
qDeleteAll(adapters);

Es necesario pasar un objeto ` params ` debido al diseño de algunas de las API gráficas subyacentes. En el caso concreto de Vulkan, se debe proporcionar el ` QVulkanInstance `, ya que sin él no es posible realizar la enumeración. El resto de campos del objeto ` params `, específico del backend, no serán utilizados realmente por esta función.

nativeHandles es opcional. Cuando se especifica, debe ser un ` QRhiD3D11NativeHandles`, ` QRhiD3D12NativeHandles` o ` QRhiVulkanNativeHandles` válido, de forma similar a ` create()`. Sin embargo, a diferencia de ` create()`, solo se utilizan los campos del dispositivo físico (en el caso de Vulkan) o del LUID del adaptador (en el caso de D3D); el resto de campos se ignoran. Esto puede utilizarse para restringir los resultados a un adaptador determinado. En este caso, la lista devuelta contendrá 1 o 0 elementos.

Obsérvese cómo, en el fragmento de código anterior, la implementación de la función looksGood() no puede realizar ningún filtrado específico de la plataforma basado en la identidad real del adaptador o del dispositivo físico, como el LUID del adaptador en Windows o el VkPhysicalDevice con Vulkan. Esto se debe a que QRhiDriverInfo no contiene datos específicos de la plataforma. En su lugar, utiliza nativeHandles para obtener los resultados ya filtrados dentro de `enumerateAdapters()`.

Los dos fragmentos de código siguientes, que utilizan Direct 3D 12 como ejemplo, son equivalentes en la práctica:

// Enfoque basado en enumerateAdapters a partir de Qt 6.10
QRhiD3D12InitParams initParams;
QRhiD3D12NativeHandles nativeHandles;
nativeHandles.adapterLuidLow = luid.LowPart; // se ha obtenido un LUID de algún sitio; ahora se pasa a Qt
nativeHandles.adapterLuidHigh = luid.HighPart;
QRhi::AdapterList adapters = QRhi::enumerateAdapters(QRhi::D3D12, &initParams, &nativeHandles);
if (adapters.isEmpty()) { qWarning("No se ha encontrado el adaptador solicitado"); }
QRhi*rhi = QRhi::create(QRhi::D3D12, &initParams, {}, nullptr, adapters[0]);
qDeleteAll(adapters);
// traditional approach, more lightweight
QRhiD3D12InitParams initParams;
QRhiD3D12NativeHandles nativeHandles;
nativeHandles.adapterLuidLow = luid.LowPart; // retrieved a LUID from somewhere, now pass it on to Qt
nativeHandles.adapterLuidHigh = luid.HighPart;
QRhi *rhi = QRhi::create(QRhi::D3D12, &initParams, {}, &nativeHandles, nullptr);

Esta función se introdujo en Qt 6.10.

Véase también create().

QRhi::FrameOpResult QRhi::finish()

Espera a que finalice cualquier tarea de la cola de gráficos (cuando proceda) y, a continuación, ejecuta todas las operaciones aplazadas, como completar las lecturas posteriores y las liberaciones de recursos. Se puede invocar tanto dentro como fuera de un fotograma, pero no dentro de una pasada. Dentro de un fotograma, implica enviar cualquier tarea al búfer de comandos.

Nota: Evita esta función. Un caso en el que podría ser necesaria es cuando se necesitan los resultados de una lectura posterior puesta en cola en un fotograma basado en una cadena de intercambio en un momento fijo determinado y, por lo tanto, se desea esperar a que se obtengan dichos resultados.

bool QRhi::isClipDepthZeroToOne() const

Devuelve ` true ` si la API gráfica subyacente utiliza el rango de profundidad [0, 1] en el espacio de recorte.

En la práctica, esto solo es false para OpenGL, ya que OpenGL utiliza un rango de profundidad tras la proyección de [-1, 1]. (No debe confundirse con la correspondencia entre NDC y ventana controlada por glDepthRange(), que utiliza un rango de [0, 1], a menos que se anule mediante QRhiViewport). En algunas versiones de OpenGL se podía utilizar glClipControl() para cambiar esto, pero el backend de OpenGL de QRhi no utiliza esa función, ya que no está disponible en OpenGL ES ni en versiones de OpenGL anteriores a la 4.5.

Nota: clipSpaceCorrMatrix() incluye el ajuste correspondiente en la matriz que devuelve. Por lo tanto, muchos usuarios de QRhi no necesitan tomar ninguna medida adicional aparte de premultiplicar sus matrices de proyección por clipSpaceCorrMatrix(). Sin embargo, algunas técnicas gráficas, como ciertos tipos de mapeado de sombras, implican trabajar con valores de profundidad y generarlos en los shaders. En estos casos, será necesario consultar esta función y tener en cuenta su valor según corresponda.

bool QRhi::isDeviceLost() const

Devuelve «true» si se ha perdido el dispositivo gráfico.

La pérdida del dispositivo suele detectarse en beginFrame(), endFrame() o QRhiSwapChain::createOrResize(), dependiendo del backend y de las API nativas subyacentes. Lo más habitual es endFrame(), ya que es ahí donde tiene lugar la presentación. Con algunos backends, QRhiSwapChain::createOrResize() también puede fallar debido a la pérdida de un dispositivo. Por lo tanto, esta función se proporciona como una forma genérica de comprobar si una operación anterior ha detectado la pérdida de un dispositivo.

Cuando se pierde el dispositivo, no deben realizarse más operaciones a través de ` QRhi`. En su lugar, deben liberarse todos los recursos de ` QRhi `, y a continuación debe destruirse ` QRhi`. A continuación, puede intentarse crear un nuevo ` QRhi `. Si tiene éxito, deben reinicializarse todos los recursos gráficos. Si no es así, inténtalo de nuevo más tarde, repetidamente.

Aunque las aplicaciones sencillas pueden optar por no tener en cuenta la pérdida del dispositivo, en las plataformas de escritorio más habituales esta pérdida puede producirse por diversas razones, como la desconexión física de la tarjeta gráfica, la desactivación del dispositivo o del controlador, la desinstalación o actualización del controlador gráfico, o debido a errores que provocan un reinicio del dispositivo gráfico. Algunas de estas situaciones también pueden darse en circunstancias perfectamente normales; por ejemplo, la actualización del controlador gráfico a una versión más reciente es una tarea habitual que puede producirse en cualquier momento mientras se ejecuta una aplicación Qt. Es muy probable que los usuarios esperen que las aplicaciones sean capaces de sobrellevar esto, incluso cuando la aplicación esté utilizando activamente una API como OpenGL o Direct3D.

Cabe esperar que los propios marcos de trabajo de Qt, basados en QRhi, como Qt Quick, gestionen la situación y tomen las medidas adecuadas cuando se produzca una pérdida de dispositivo. Si los datos de los recursos gráficos, como texturas y búferes, siguen estando disponibles en la CPU, es posible que dicho evento ni siquiera se note a nivel de la aplicación, ya que los recursos gráficos pueden reinicializarse sin problemas en ese momento. Sin embargo, se espera que las aplicaciones y bibliotecas que trabajan directamente con QRhi estén preparadas para comprobar y gestionar por sí mismas las situaciones de pérdida de dispositivo.

Nota: Con OpenGL, es posible que las aplicaciones tengan que activar las notificaciones de reinicio de contexto estableciendo ` QSurfaceFormat::ResetNotification ` en ` QOpenGLContext`. Esto se suele hacer activando el indicador en ` QRhiGles2InitParams::format`. No obstante, hay que tener en cuenta que algunos sistemas pueden generar situaciones de reinicio de contexto incluso cuando este indicador no está activado.

bool QRhi::isFeatureSupported(QRhi::Feature feature) const

Devuelve « true » si se admite el « feature » especificado.

bool QRhi::isRecordingFrame() const

Devuelve «true» cuando hay un marco activo, lo que significa que se ha llamado a beginFrame() (o beginOffscreenFrame()) sin que haya todavía un endFrame() (o endOffscreenFrame()) correspondiente.

Véanse también currentFrameSlot(), beginFrame() y endFrame().

bool QRhi::isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags = {}) const

Devuelve « true » si la textura especificada format, modificada por flags, es compatible.

La consulta es compatible tanto con formatos sin comprimir como con formatos comprimidos.

bool QRhi::isYUpInFramebuffer() const

Devuelve ` true ` si la API gráfica subyacente tiene el eje Y orientado hacia arriba en los búferes de fotogramas y las imágenes.

En la práctica, esto solo es « true » para OpenGL.

bool QRhi::isYUpInNDC() const

Devuelve « true » si la API gráfica subyacente tiene el eje Y orientado hacia arriba en su sistema de coordenadas normalizadas del dispositivo.

En la práctica, esto solo es « false » para Vulkan.

Nota: clipSpaceCorrMatrix() incluye el ajuste correspondiente (para que el eje Y apunte hacia arriba) en la matriz que devuelve.

bool QRhi::makeThreadLocalNativeContextCurrent()

Con OpenGL, esto establece el contexto de OpenGL como el actual en el hilo actual. La función no tiene ningún efecto con otros backends.

La llamada a esta función suele ser relevante en el código del marco Qt, cuando hay que garantizar que el código OpenGL externo proporcionado por la aplicación pueda seguir ejecutándose como lo hacía antes con el uso directo de OpenGL, siempre y cuando QRhi utilice el backend de OpenGL.

Devuelve «false» en caso de fallo, de forma similar a « QOpenGLContext::makeCurrent()». Cuando la operación falla, se puede llamar a « isDeviceLost()» para determinar si se ha producido una pérdida de contexto. Esta comprobación equivale a la que se realiza mediante « QOpenGLContext::isValid()».

Véanse también QOpenGLContext::makeCurrent() y QOpenGLContext::isValid().

[static] int QRhi::mipLevelsForSize(const QSize &size)

Devuelve el número de niveles mip de un ` size` dado.

const QRhiNativeHandles *QRhi::nativeHandles()

Devuelve un puntero a la colección específica del backend de objetos nativos para el dispositivo, el contexto y conceptos similares utilizados por el backend.

Convierte el valor a ` QRhiVulkanNativeHandles`, ` QRhiD3D11NativeHandles`, ` QRhiD3D12NativeHandles`, ` QRhiGles2NativeHandles` o ` QRhiMetalNativeHandles `, según corresponda.

Nota: No se transfiere la propiedad, ni del puntero devuelto ni de ningún objeto nativo.

QRhiBuffer *QRhi::newBuffer(QRhiBuffer::Type type, QRhiBuffer::UsageFlags usage, quint32 size)

Devuelve un nuevo búfer con los valores especificados para type, usage y size.

Nota: Es posible que no todos los backends admitanalgunas combinaciones de usage y type. Véase UsageFlags y the feature flags.

Nota: Los backends pueden optar por asignar búferes de mayor tamaño que size. Esto se hace de forma transparente para las aplicaciones, por lo que no hay restricciones especiales sobre el valor de size. QRhiBuffer::size() siempre devolverá el valor que se solicitó en size.

Véase también QRhiResource::destroy().

QRhiComputePipeline *QRhi::newComputePipeline()

Devuelve un nuevo recurso de canalización de cálculo.

Nota: La función «Compute» solo está disponible cuando se indica que la función « Compute » es compatible.

Véase también « QRhiResource::destroy » ().

QRhiGraphicsPipeline *QRhi::newGraphicsPipeline()

Devuelve un nuevo recurso de canalización gráfica.

Véase también QRhiResource::destroy().

QRhiRenderBuffer *QRhi::newRenderBuffer(QRhiRenderBuffer::Type type, const QSize &pixelSize, int sampleCount = 1, QRhiRenderBuffer::Flags flags = {}, QRhiTexture::Format backingFormatHint = QRhiTexture::UnknownFormat)

Devuelve un nuevo renderbuffer con los valores especificados para « type », « pixelSize », « sampleCount » y « flags ».

Cuando backingFormatHint se establece en un formato de textura distinto de QRhiTexture::UnknownFormat, el backend puede utilizarlo para decidir qué formato emplear para el almacenamiento subyacente del búfer de renderizado.

Nota: backingFormatHint suele ser relevante cuando intervienen el multimuestreo y los formatos de textura de coma flotante: renderizar en un QRhiRenderBuffer multimuestreado y luego resolverlo en un QRhiTexture que no sea RGBA8 implica (con algunas API gráficas) que el almacenamiento subyacente a QRhiRenderBuffer utilice el formato correspondiente que no sea RGBA8. Esto significa que es importante pasar un formato como QRhiTexture::RGBA32F, ya que los backends suelen optar por QRhiTexture::RGBA8 de forma predeterminada, lo que posteriormente provocaría un error al intentar configurar una resolución multimuestra de RGBA8 a RGBA32F en los anexos de color del QRhiTextureRenderTarget.

Véase también QRhiResource::destroy().

QRhiSampler *QRhi::newSampler(QRhiSampler::Filter magFilter, QRhiSampler::Filter minFilter, QRhiSampler::Filter mipmapMode, QRhiSampler::AddressMode addressU, QRhiSampler::AddressMode addressV, QRhiSampler::AddressMode addressW = QRhiSampler::Repeat)

Devuelve un nuevo muestreador con el filtro de ampliación especificado magFilter, el filtro de reducción minFilter, el modo de mipmapping mipmapMode y los modos de direccionamiento (enrollamiento) addressU, addressV y addressW.

Nota: Establecer mipmapMode en un valor distinto de None implica que las imágenes para todos los niveles mip relevantes se proporcionarán bien a través de texture uploads, bien llamando a generateMips() sobre la textura que se utiliza con este muestreador. Intentar utilizar el muestreador con una textura que no contenga datos para todos los niveles mip relevantes provocará errores de renderizado, y el comportamiento exacto dependerá de la API gráfica subyacente.

Véase también QRhiResource::destroy().

QRhiShaderResourceBindings *QRhi::newShaderResourceBindings()

Devuelve un nuevo recurso de colección de enlaces a recursos de shader.

Véase también QRhiResource::destroy().

[since 6.9] QRhiShadingRateMap *QRhi::newShadingRateMap()

Devuelve un nuevo objeto de mapa de tasa de sombreado.

Esta función se introdujo en Qt 6.9.

QRhiSwapChain *QRhi::newSwapChain()

Devuelve una nueva cadena de intercambio.

Véase también QRhiResource::destroy() y QRhiSwapChain::createOrResize().

QRhiTexture *QRhi::newTexture(QRhiTexture::Format format, const QSize &pixelSize, int sampleCount = 1, QRhiTexture::Flags flags = {})

Devuelve una nueva textura 1D o 2D con los valores especificados para ` format`, ` pixelSize`, ` sampleCount` y ` flags`.

Una textura 1D debe tener el indicador « QRhiTexture::OneDimensional » establecido en « flags ». Esta función establecerá implícitamente este indicador si la altura de « pixelSize » es 0.

Nota: « format » especifica el formato interno y externo solicitado, lo que significa que los datos que se vayan a cargar en la textura deberán estar en un formato compatible, mientras que la textura nativa puede (aunque no está garantizado, al menos en el caso de OpenGL) utilizar este formato internamente.

Nota: Las texturas1D solo funcionan cuando se indica en tiempo de ejecución que la función « OneDimensionalTextures » es compatible. Además, los mipmaps en texturas 1D solo funcionan cuando se indica en tiempo de ejecución que la función « OneDimensionalTextureMipmaps » está disponible.

Véase también QRhiResource::destroy().

QRhiTexture *QRhi::newTexture(QRhiTexture::Format format, int width, int height, int depth, int sampleCount = 1, QRhiTexture::Flags flags = {})

Devuelve una nueva textura 1D, 2D o 3D con los valores especificados para « format », « width », « height », « depth », « sampleCount » y « flags ».

Esta sobrecarga es adecuada para texturas 3D, ya que permite especificar « depth ». Una textura 3D debe tener « QRhiTexture::ThreeDimensional » establecido en « flags », pero al utilizar esta sobrecarga se puede omitir, ya que el indicador se establece implícitamente siempre que « depth » sea mayor que 0. Para texturas 1D, 2D y cúbicas, « depth » debe establecerse en 0.

Una textura 1D debe tener QRhiTexture::OneDimensional establecido en flags. Esta sobrecarga establecerá implícitamente este indicador si tanto height como depth son 0.

Nota: Las texturas3D solo funcionan cuando se indica que la función « ThreeDimensionalTextures » es compatible en tiempo de ejecución.

Nota: Las texturas1D solo funcionan cuando se indica que la característica OneDimensionalTextures es compatible en tiempo de ejecución. Además, los mipmaps en texturas 1D solo funcionan cuando se indica que la característica OneDimensionalTextureMipmaps es compatible en tiempo de ejecución.

Esta es una función sobrecargada.

QRhiTexture *QRhi::newTextureArray(QRhiTexture::Format format, int arraySize, const QSize &pixelSize, int sampleCount = 1, QRhiTexture::Flags flags = {})

Devuelve una nueva matriz de texturas de 1D o 2D con los valores especificados para « format », « arraySize », « pixelSize », « sampleCount » y « flags ».

Esta función establece implícitamente QRhiTexture::TextureArray en flags.

Una matriz de texturas unidimensional debe tener activada la opción « QRhiTexture::OneDimensional » en « flags ». Esta función activará implícitamente esta opción si la altura de « pixelSize » es 0.

Nota: Nohay que confundir las matrices de texturas con las matrices de texturas. Un ` QRhiTexture ` creado por esta función se puede utilizar con muestreadores de matrices 1D o 2D en el shader, por ejemplo: ` layout(binding = 1) uniform sampler2DArray texArr;`. Las matrices de texturas se refieren a una lista de texturas que se exponen al shader mediante ` QRhiShaderResourceBinding::sampledTextures()` y un recuento > 1, y que se declaran en el shader, por ejemplo, de esta manera: layout(binding = 1) uniform sampler2D textures[4];

Nota: Esto solo funciona cuando la función TextureArrays se indica como compatible en tiempo de ejecución.

Nota: Las texturas1D solo funcionan cuando se indica que la función « OneDimensionalTextures » es compatible en tiempo de ejecución. Además, los mipmaps en texturas 1D solo funcionan cuando se indica que la función « OneDimensionalTextureMipmaps » es compatible en tiempo de ejecución.

Véase también ` newTexture()`.

QRhiTextureRenderTarget *QRhi::newTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc, QRhiTextureRenderTarget::Flags flags = {})

Devuelve un nuevo destino de renderizado de textura con los adjuntos de color y profundidad/plantilla indicados en desc, y con el flags especificado.

Véase también QRhiResource::destroy().

QRhiResourceUpdateBatch *QRhi::nextResourceUpdateBatch()

Devuelve un lote disponible y vacío en el que se pueden registrar operaciones de tipo «copia».

Nota: el valor devuelto no es propiedad de quien realiza la llamada y nunca debe destruirse. En su lugar, el lote se devuelve al grupo para su reutilización pasándolo a QRhiCommandBuffer::beginPass(), QRhiCommandBuffer::endPass() o QRhiCommandBuffer::resourceUpdate(), o bien llamando a QRhiResourceUpdateBatch::release() sobre él.

Nota: También sepuede llamar fuera de beginFrame() - endFrame(), ya que una instancia de lote solo recopila datos por sí misma, no realiza ninguna operación.

Al no estar vinculada a un fotograma que se esté grabando, la siguiente secuencia es válida, por ejemplo:

rhi->beginFrame(swapchain);
QRhiResourceUpdateBatch *u = rhi->nextResourceUpdateBatch();
u->uploadStaticBuffer(buf, data);
// ... do not commit the batch
rhi->endFrame();
// u stays valid (assuming buf stays valid as well)
rhi->beginFrame(swapchain);
swapchain->currentFrameCommandBuffer()->resourceUpdate(u);
// ... draw with buf
rhi->endFrame();

Advertencia: El número máximo de lotes por QRhi es 64. Cuando se alcanza este límite, la función devolverá «null» hasta que se devuelva un lote al grupo.

QByteArray QRhi::pipelineCacheData()

Devuelve un blob de datos binarios con la información recopilada de QRhiGraphicsPipeline y QRhiComputePipeline, creados correctamente durante el ciclo de vida de este QRhi.

Al guardar y, posteriormente, en ejecuciones sucesivas de la misma aplicación, volver a cargar los datos de la caché, es posible reducir los tiempos de creación de los pipelines y los shaders. No se especifica qué incluyen exactamente la caché y su versión serializada; esto siempre depende del backend utilizado y, en algunos casos, también de la implementación concreta de la API gráfica.

Cuando se indica que el ` PipelineCacheDataLoadSave ` no es compatible, el ` QByteArray ` devuelto está vacío.

Si no se ha especificado el indicador « EnablePipelineCacheDataSave » al llamar a create(), el objeto QByteArray devuelto puede estar vacío, incluso cuando se admite la función « PipelineCacheDataLoadSave ».

Cuando los datos devueltos no están vacíos, siempre son específicos de la versión de Qt y del backend QRhi. Además, en algunos casos existe una fuerte dependencia del dispositivo gráfico y de la versión exacta del controlador utilizado. QRhi se encarga de añadir el encabezado adecuado y las medidas de seguridad que garantizan que los datos siempre se puedan pasar de forma segura a setPipelineCacheData(), por lo que cualquier intento de cargar datos de una ejecución en otra versión de un controlador se gestionará de forma segura y sin problemas.

Nota: La llamada a releaseCachedResources() puede, dependiendo del backend, borrar los datos de la canalización recopilados. Por lo tanto, una llamada posterior a esta función podría no devolver ningún dato.

Consulte EnablePipelineCacheDataSave para obtener más detalles sobre esta característica.

Nota: Minimice el número de llamadas a esta función. Recuperar el blob no siempre es una operación económica, por lo que esta función solo debe invocarse con poca frecuencia; lo ideal es hacerlo una sola vez, por ejemplo, al cerrar la aplicación.

Véase también setPipelineCacheData(), create() y isFeatureSupported().

[static] bool QRhi::probe(QRhi::Implementation impl, QRhiInitParams *params)

Devuelve «true» si cabe esperar que la llamada a ` create()` se realice con éxito cuando se invoque a las funciones ` impl ` y ` params` especificadas.

Para algunos backends, esto equivale a llamar a ` create()`, comprobar su valor de retorno y, a continuación, destruir el ` QRhi` resultante.

Para otros, en particular con Metal, puede haber una implementación de comprobación específica, que permite realizar pruebas de forma más ligera sin saturar la salida de depuración con advertencias en caso de fallos.

Véase también create().

void QRhi::releaseCachedResources()

Intenta liberar recursos de las cachés del backend. Esto puede incluir tanto recursos de CPU como de GPU. Solo se tienen en cuenta la memoria y los recursos que se pueden recrear automáticamente. Por ejemplo, si la implementación de ` QRhiGraphicsPipeline ` del backend mantiene una caché con los resultados de la compilación de shaders, llamar a esta función vacía dicha caché, lo que puede liberar memoria y recursos gráficos.

Tiene sentido llamar a esta función en entornos con recursos limitados, en los que, llegado un momento dado, es necesario garantizar un uso mínimo de recursos, a costa del rendimiento.

void QRhi::removeCleanupCallback(const void *key)

Da de baja la función de llamada con ` key`. Si no se ha registrado ninguna función de llamada de limpieza con ` key`, la función no realiza ninguna acción. Las funciones de llamada registradas sin una clave no se pueden eliminar.

Véase también addCleanupCallback().

int QRhi::resourceLimit(QRhi::ResourceLimit limit) const

Devuelve el valor del recurso especificado limit.

Se espera que los backends consulten los valores durante la inicialización, por lo que llamar a esta función es una operación ligera.

void QRhi::setPipelineCacheData(const QByteArray &data)

Carga data en la caché del canal, cuando sea aplicable.

Cuando se indica que PipelineCacheDataLoadSave no es compatible, la función se puede llamar con total seguridad, pero no tiene ningún efecto.

El blob devuelto por pipelineCacheData() siempre es específico de la versión de Qt, del backend QRhi y, en algunos casos, también del dispositivo gráfico y de una versión determinada del controlador gráfico. QRhi se encarga de añadir el encabezado adecuado y las medidas de seguridad que garantizan que los datos siempre se puedan pasar de forma segura a esta función. Si se produce una discrepancia, por ejemplo, porque el controlador se ha actualizado a una versión más reciente o porque los datos se han generado a partir de un backend QRhi diferente, se muestra una advertencia y data se ignora de forma segura.

En el caso de Vulkan, esto se corresponde directamente con `VkPipelineCache`. Al llamar a esta función se crea un nuevo objeto de caché de pipeline de Vulkan, cuyos datos iniciales proceden de ` data`. A continuación, el objeto de caché de pipeline es utilizado por todos los objetos ` QRhiGraphicsPipeline ` y ` QRhiComputePipeline ` creados posteriormente, lo que, potencialmente, acelera la creación del pipeline.

En otras API no existe una caché de pipeline propiamente dicha, pero pueden proporcionar una caché con bytecode procedente de compilaciones de shaders (D3D) o binarios de programas (OpenGL). En aplicaciones que realizan numerosas compilaciones de shaders a partir del código fuente en tiempo de ejecución, esto puede suponer una mejora significativa en ejecuciones posteriores si la «caché del pipeline» se inicializa previamente a partir de una ejecución anterior utilizando esta función.

Nota: QRhi no puede garantizar que data tenga ningún efecto en el rendimiento de la creación de la pipeline y de los shaders. Con API como Vulkan, depende del controlador decidir si data se utiliza para algún fin o si se ignora.

Consulte EnablePipelineCacheDataSave para obtener más detalles sobre esta función.

Nota: Este mecanismo que ofrece QRhi es independiente del propio mecanismo de almacenamiento en caché interno del controlador, si lo hubiera. Esto significa que, dependiendo de la API gráfica y de su implementación, los efectos exactos de recuperar y volver a cargar data no son predecibles. Es posible que la mejora en el rendimiento no se aprecie en absoluto en caso de que ya estén activos otros mecanismos de almacenamiento en caché ajenos al control de Qt.

Nota: Minimiza el número de llamadas a esta función. Cargar el blob no siempre es una operación económica y, por lo tanto, esta función solo debe llamarse con poca frecuencia; lo ideal es que solo se haga una vez, por ejemplo, al iniciar la aplicación.

Advertencia: Se da por hecho que los datosserializados de la caché del canal son contenido fiable. Qt realiza un análisis riguroso del encabezado y los metadatos incluidos en data; no obstante, se recomienda a los desarrolladores de aplicaciones que nunca pasen datos procedentes de fuentes no fiables.

Véanse también pipelineCacheData() y isFeatureSupported().

[since 6.9] void QRhi::setQueueSubmitParams(QRhiNativeHandles *params)

Con los backends y las API gráficas correspondientes, esta función permite proporcionar argumentos adicionales al siguiente envío de comandos a la cola de comandos gráficos.

En concreto, con Vulkan, esto permite pasar una lista de objetos de semáforo de Vulkan para que « vkQueueSubmit() » envíe señales y espere en ellos. « params » debe ser, por tanto, un « QRhiVulkanQueueSubmitParams ». Esto resulta esencial en determinados casos de uso avanzados, como al realizar llamadas nativas a Vulkan que implican tener que esperar y enviar señales a «VkSemaphores» gestionados por el código de renderizado o de cálculo personalizado de Vulkan de la aplicación. Además, esto también permite especificar semáforos adicionales en los que esperar en la siguiente llamada a ` vkQueuePresentKHR()`.

Nota: Esta función afecta únicamente al siguiente envío a la cola, que tendrá lugar en endFrame(), endOffscreenFrame() o finish(). La puesta en cola de «present» se realiza en endFrame().

En muchos otros backends, la implementación de esta función no produce ningún efecto.

Esta función se introdujo en Qt 6.9.

[static] QSize QRhi::sizeForMipLevel(int mipLevel, const QSize &baseLevelSize)

Devuelve el tamaño de la imagen de textura para un ` mipLevel` dado, calculado a partir del tamaño del nivel 0 especificado en ` baseLevelSize`.

QRhiStats QRhi::statistics() const

Recopila y devuelve estadísticas sobre los tiempos y las asignaciones de recursos gráficos.

Los datos sobre las asignaciones de memoria solo están disponibles con algunos backends, en los que dichas operaciones están bajo el control de Qt. En el caso de las API gráficas en las que no existe un control de bajo nivel sobre las asignaciones de memoria de los recursos, esta función nunca será compatible y todos los campos relevantes de los resultados serán 0.

En el caso concreto de Vulkan, los valores son siempre válidos y se obtienen de la biblioteca de asignación de memoria subyacente. Esto permite conocer los requisitos de memoria de los búferes y texturas activos.

Lo mismo ocurre con Direct 3D 12. Además de las estadísticas de la biblioteca del asignador de memoria, aquí el resultado también incluye un campo « totalUsageBytes » que indica el tamaño total, incluidos los recursos adicionales que no están bajo el control de la biblioteca del asignador de memoria (búferes de swapchain, montones de descriptores, etc.), tal y como los comunica DXGI.

Los valores corresponden a todos los tipos de memoria utilizados, combinados (es decir, vídeo + sistema en el caso de una GPU discreta).

En la mayoría de los backends se dispone de datos adicionales, como el tiempo total en milisegundos dedicado a la creación de pipelines gráficos y de cálculo (lo que suele implicar la compilación de shaders o búsquedas en caché, así como un procesamiento potencialmente costoso).

Nota: Los tiempos transcurridos en operaciones como la creación de canalizaciones pueden verse afectados por diversos factores. Los resultados no deben compararse entre diferentes backends, ya que el concepto de «canalizaciones» y lo que ocurre exactamente en segundo plano durante, por ejemplo, una llamada a ` QRhiGraphicsPipeline::create()` difieren enormemente entre las API gráficas y sus implementaciones.

Nota: Además , es probable que muchos controladores empleen diversas estrategias de almacenamiento en caché para sombreadores, programas y canalizaciones (independientemente de las propias funciones similares de Qt, como setPipelineCacheData() o la caché binaria de disco específica de OpenGL para programas). Dado que dicho comportamiento interno es transparente para el cliente de la API, ni Qt ni QRhi tienen conocimiento ni control sobre la estrategia exacta de almacenamiento en caché, la persistencia o la invalidación de los datos almacenados, etc. Al interpretar los tiempos, como el tiempo dedicado a la creación de la canalización, se debe tener en cuenta la posible presencia y el comportamiento no especificado de los mecanismos de almacenamiento en caché a nivel de controlador.

QList<int> QRhi::supportedSampleCounts() const

Devuelve la lista de recuentos de muestras admitidos.

Un ejemplo típico sería (1, 2, 4, 8).

En algunos backends, esta lista de valores admitidos viene fijada de antemano, mientras que en otros son las propiedades (físicas) del dispositivo las que indican qué valores se admiten en tiempo de ejecución.

Véanse también QRhiRenderBuffer::setSampleCount(), QRhiTexture::setSampleCount(), QRhiGraphicsPipeline::setSampleCount() y QRhiSwapChain::setSampleCount().

[since 6.9] QList<QSize> QRhi::supportedShadingRates(int sampleCount) const

Devuelve la lista de tasas de sombreado variables compatibles para el ` sampleCount` especificado.

Siempre se admite 1x1.

Esta función se introdujo en Qt 6.9.

QThread *QRhi::thread() const

Devuelve el hilo en el que se ejecutó la función ` QRhi ` initialized.

int QRhi::ubufAligned(int v) const

Devuelve el valor (normalmente un desplazamiento) v alineado con la alineación uniforme del búfer especificada por ubufAlignment().

int QRhi::ubufAlignment() const

Devuelve la alineación mínima del desplazamiento del búfer uniforme en bytes. Normalmente es 256.

Intentar vincular una región de búfer uniforme con un desplazamiento que no esté alineado con este valor provocará errores, dependiendo del backend y de la API gráfica subyacente.

Véase también ubufAligned().

[static] QRhiSwapChainProxyData QRhi::updateSwapChainProxyData(QRhi::Implementation impl, QWindow *window)

Genera y devuelve una estructura ` QRhiSwapChainProxyData ` que contiene datos opacos específicos del backend y de la API gráfica especificados por ` impl`. ` window ` es el ` QWindow ` al que apunta una cadena de intercambio.

La estructura devuelta se puede pasar a ` QRhiSwapChain::setProxyData()` (). Esto tiene sentido en sistemas de renderizado multihilo: se espera que esta función estática se llame en el hilo principal (GUI), a diferencia de todas las operaciones de ` QRhi `, para luego transferirse al hilo que trabaja con ` QRhi ` y ` QRhiSwapChain ` y pasarse a la cadena de intercambio. Esto permite realizar consultas nativas de la plataforma que solo es seguro llamar en el hilo principal, por ejemplo, para consultar el CAMetalLayer desde un NSView, y luego pasar los datos a la QRhiSwapChain que reside en el hilo de renderizado. En el ejemplo de Metal, acceder a view.layer en un hilo de renderizado dedicado provoca una advertencia en el Thread Checker de Xcode. Con el mecanismo de proxy de datos, esto se evita.

Cuando no intervienen hilos, no es necesario generar ni pasar el ` QRhiSwapChainProxyData `: se garantiza que los backends pueden consultar por sí mismos todo lo que sea necesario, y si todo reside en el hilo principal (GUI), eso debería ser suficiente.

Nota: ` impl ` debe coincidir con el valor con el que se ha creado ` QRhi `. Por ejemplo, llamar a ` QRhi::Metal ` en una plataforma que no sea de Apple no generará ningún dato útil.

Elementos no miembros relacionados

[alias, since 6.7] QRhiShaderResourceBindingSet

Sinónimo de « QRhiShaderResourceBindings ».

Este «typedef» se introdujo en Qt 6.7.

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