QRhi Class

Documentación de la Función 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 llamada de retorno se ejecutará con el recurso gráfico aún disponible, por lo que esto proporciona una oportunidad para que la aplicación libere limpiamente las instancias de QRhiResource pertenecientes a QRhi. Esto es particularmente útil para gestionar el tiempo de vida de los recursos almacenados en objetos de tipo cache, donde 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 ser invocado cuando se destruya QRhi. Esta sobrecarga toma un puntero opaco, key, que se utiliza para asegurar que una llamada de retorno dada se registra (y así se llama) sólo una vez.

Véase también removeCleanupCallback().

QRhi::Implementation QRhi::backend() const

Devuelve el tipo de backend para 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 amigable para el backend impl, normalmente el nombre de la API 3D en uso.

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

Inicia un nuevo fotograma en el siguiente búfer disponible de swapChain.

Un fotograma se compone de actualizaciones de recursos y uno o más pases de renderizado y cálculo.

flags puede indicar ciertos casos especiales.

El patrón de alto nivel de renderizado en un QWindow utilizando una swapchain:

• Crear una swapchain.
• Llamar a QRhiSwapChain::createOrResize() siempre que el tamaño de la superficie sea diferente al anterior.
• Llama a QRhiSwapChain::destroy() en QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed.
• Luego en cada frame:

  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 en caso de éxito, u otro valor QRhi::FrameOpResult en caso de fallo. Algunos de estos deben ser tratados como errores suaves, del tipo "inténtelo de nuevo más tarde": Cuando se devuelve QRhi::FrameOpSwapChainOutOfDate, la swapchain debe ser redimensionada o actualizada llamando a QRhiSwapChain::createOrResize(). La aplicación debería entonces intentar generar un nuevo frame. QRhi::FrameOpDeviceLost significa que el dispositivo gráfico se pierde pero esto también puede ser recuperable liberando todos los recursos, incluyendo el propio QRhi, y luego recreando todos los recursos. Véase isDeviceLost() para más información.

Véase 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 grabar comandos de renderizado en cb. flags se utiliza para indicar ciertos casos especiales, al igual que con beginFrame().

También es posible renderizar sin swapchain. El caso de uso típico es usarlo en aplicaciones completamente fuera de pantalla, por ejemplo, para generar secuencias de imágenes renderizando y volviendo a leer sin mostrar nunca una ventana.

El uso en aplicaciones en pantalla ( beginFrame, endFrame, beginOffscreenFrame, endOffscreenFrame, beginFrame, ...) también es posible, pero reduce el paralelismo, por lo que sólo debería hacerse con poca frecuencia.

Los fotogramas fuera de pantalla no permiten a la CPU generar potencialmente otro fotograma mientras la GPU sigue procesando el anterior. Esto tiene el efecto secundario de que si se programan lecturas posteriores, se garantiza que los resultados estarán disponibles una vez que vuelva endOffscreenFrame(). Este no es el caso de los fotogramas dirigidos a una swapchain: ahí la GPU está potencialmente mejor utilizada, pero trabajar con operaciones de readback requiere más cuidado por parte de la aplicación porque endFrame(), a diferencia de endOffscreenFrame(), no garantiza que los resultados del readback estén disponibles en ese momento.

El esqueleto de renderizar un cuadro sin una cadena de intercambio y luego volver a leer el contenido del cuadro podría parecerse a lo 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éase también endOffscreenFrame() y beginFrame().

QMatrix4x4 QRhi::clipSpaceCorrMatrix() const

Devuelve una matriz que se puede utilizar para permitir que las aplicaciones sigan utilizando datos de vértices orientados a OpenGL y matrices de proyección de perspectiva (como, por ejemplo, las generadas por QMatrix4x4::perspective()), independientemente del backend QRhi activo.

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

Véase esta página para una discusión 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 de gráficos especificada por impl con el flags especificado. Devuelve nullptr si la función falla.

params debe apuntar a una instancia de una de las subclases específicas de backend de QRhiInitParams, como, QRhiVulkanInitParams, QRhiMetalInitParams, QRhiD3D11InitParams, QRhiD3D12InitParams, QRhiGles2InitParams. Consulte estas clases para ver ejemplos de creación de un QRhi.

QRhi by design no implementa ninguna lógica fallback: si la API especificada no puede ser inicializada, create() fallará, con advertencias impresas en la salida debug por los backends. Los clientes de QRhi, por ejemplo Qt Quick, pueden sin embargo proporcionar una lógica adicional que permita volver a una API diferente de la solicitada, dependiendo de la plataforma. Si la intención es sólo probar si la inicialización tendría éxito al llamar a create() en un momento posterior, es preferible utilizar probe() en lugar de create(), porque con algunos backends el sondeo puede ser implementado de una manera más ligera en oposición a create(), que realiza la inicialización completa de la infraestructura y es un desperdicio si esa instancia QRhi es luego desechada inmediatamente.

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 backand y de la API gráfica subyacente.

Especificar un QRhiAdapter en adapter ofrece una alternativa transparente y multiAPI a pasar un VkPhysicalDevice a través de QRhiVulkanNativeHandles, o un LUID de adaptador a través de QRhiD3D12NativeHandles. No se toma la propiedad de adapter. Véase enumerateAdapters() para más información sobre este enfoque.

Véase también probe().

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

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

int QRhi::currentFrameSlot() const

Devuelve el índice de la ranura de fotograma actual mientras se graba un fotograma. No se especifica cuando se llama fuera de un fotograma activo (es decir, cuando isRecordingFrame() es false).

Con backends como Vulkan o Metal, es responsabilidad del backend QRhi bloquearse cada vez que se inicia un nuevo frame y se encuentra que la CPU ya está FramesInFlight - 1 frames por delante de la GPU (porque el buffer de comandos enviado en el frame no. 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 con tipo QRhiBuffer::Dynamic) existen en múltiples versiones, de modo que cada fotograma, que puede ser enviado mientras uno anterior todavía está siendo procesado, funciona con su propia copia, evitando así la necesidad de detener el pipeline al preparar el fotograma. (El contenido de un recurso que aún pueda estar en uso en la GPU no debe tocarse, pero esperar siempre a que termine 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 copy-on-write utilizados por algunos contenedores C++ y otros tipos. También puede ser similar a lo que una implementación de OpenGL o Direct 3D 11 realiza internamente para cierto tipo de objetos.

En la práctica, estos recursos de doble (o triple) buffering se realizan en los backends Vulkan, Metal, y similares QRhi teniendo un número fijo de recursos nativos (como, VkBuffer) slots detrás de un QRhiResource. Que luego pueden ser indexados por un índice de ranura de fotograma que corre 0, 1, .., FramesInFlight-1, y luego se envuelve alrededor.

Todo esto se gestiona de forma transparente para los usuarios de QRhi. Sin embargo, las aplicaciones que integran el renderizado realizado directamente con la API gráfica pueden querer realizar un doble o triple buffering similar de sus propios recursos gráficos. Esto se consigue más fácilmente conociendo los valores del número máximo de fotogramas en vuelo (recuperable a través de resourceLimit()) y el índice del fotograma (slot) actual (devuelto por esta función).

Véase 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 una trama iniciada en el último beginFrame() en swapChain.

El doble (o triple) almacenamiento en búfer es gestionado internamente por QRhiSwapChain y QRhi.

flags se puede utilizar opcionalmente para cambiar el comportamiento de ciertas maneras. Pasando QRhi::SkipPresent se omite poner en cola el comando Presentar o llamar a swapBuffers.

Devuelve QRhi::FrameOpSuccess en caso de éxito, u otro valor QRhi::FrameOpResult en caso de fallo. Algunos de estos deben tratarse como errores suaves del tipo "inténtelo de nuevo más tarde": Cuando se devuelve QRhi::FrameOpSwapChainOutOfDate, la swapchain debe ser redimensionada o actualizada llamando a QRhiSwapChain::createOrResize(). La aplicación debería entonces intentar generar un nuevo frame. QRhi::FrameOpDeviceLost significa que el dispositivo gráfico se pierde pero esto también puede ser recuperable liberando todos los recursos, incluyendo el propio QRhi, y luego recreando todos los recursos. Véase isDeviceLost() para más información.

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

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

Finaliza, envía y espera el fotograma fuera de pantalla.

flags no se utiliza actualmente.

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 dicho control no está disponible con una API gráfica determinada.

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

Es de esperar que los backends para Direct 3D 11, Direct 3D 12 y Vulkan soporten completamente la enumeración de adaptadores. Es posible que otros no. El backend se especifica en impl. Un QRhiAdapter devuelto por esta función sólo debe utilizarse en una llamada a create() con el mismo impl. Algunas APIs subyacentes pueden presentar limitaciones adicionales, con Vulkan en particular el QRhiAdapter se especifica al 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 pasarlos a create(), o a las funciones correspondientes en capas superiores como Qt Quick.

El siguiente fragmento, escrito específicamente para Vulkan, muestra cómo enumerar los dispositivos físicos disponibles y solicitar la creación de un QRhi para el 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 en el lado de la aplicación:

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

Es necesario pasar params debido al diseño de algunas de las API de gráficos subyacentes. Con Vulkan en particular, se debe proporcionar QVulkanInstance, ya que la enumeración no es posible sin él. Otros campos del backend específico params no serán utilizados 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(), sólo se utilizan los campos del dispositivo físico (en el caso de Vulkan) o el LUID del adaptador (en el caso de D3D), todos los demás campos se ignoran. Esto puede utilizarse para restringir los resultados a un adaptador determinado. La lista devuelta contendrá 1 o 0 elementos en este caso.

Observe 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 plataforma basado en la verdadera identidad del adaptador / 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 filtrados ya dentro de enumerateAdapters().

Los dos fragmentos siguientes, utilizando Direct 3D 12 como ejemplo, son equivalentes en la práctica:

// Enfoque basado en enumerateAdapters desde Qt 6.10 enQRhiD3D12InitParams initParams; QRhiD3D12NativeHandles nativeHandles; nativeHandles.adapterLuidLow = luid.LowPart; // recuperado un LUID de algún sitio, ahora pásalo a QtnativeHandles.adapterLuidHigh = luid.HighPart;QRhi::AdapterList adaptadores = QRhi::enumerateAdapters(QRhi::D3D12, &initParams, &nativeHandles);if (adapters.isEmpty()) { qWarning("No se encontró 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 se complete cualquier trabajo en la cola de gráficos (cuando corresponda) y, a continuación, ejecuta todas las operaciones diferidas, como completar las devoluciones de lectura y las liberaciones de recursos. Puede invocarse dentro y fuera de un cuadro, pero no dentro de un pase. Dentro de un frame implica enviar cualquier trabajo en el buffer de comandos.

bool QRhi::isClipDepthZeroToOne() const

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

En la práctica esto es false sólo para OpenGL, porque OpenGL utiliza un rango de profundidad post-proyección de [-1, 1]. (no confundir con el mapeo NDC-a-ventana controlado por glDepthRange(), que usa un rango de [0, 1], a menos que sea sobreescrito por QRhiViewport) En algunas versiones de OpenGL glClipControl() podría usarse para cambiar esto, pero el backend OpenGL de QRhi no usa esa función ya que no está disponible en OpenGL ES o versiones de OpenGL inferiores a 4.5.

bool QRhi::isDeviceLost() const

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

La pérdida del dispositivo se detecta normalmente en beginFrame(), endFrame() o QRhiSwapChain::createOrResize(), dependiendo del backend y de las API nativas subyacentes. La más común es endFrame() porque es donde ocurre la presentación. Con algunos backends QRhiSwapChain::createOrResize() también puede fallar debido a una pérdida de dispositivo. Por lo tanto, esta función se proporciona como una forma genérica de comprobar si una pérdida de dispositivo fue detectada por una operación anterior.

Cuando se pierde el dispositivo, no se deben realizar más operaciones a través de QRhi. En su lugar, se deben liberar todos los recursos de QRhi, seguido de la destrucción de QRhi. A continuación, se puede intentar crear un nuevo QRhi. Si tiene éxito, todos los recursos gráficos deben ser reinicializados. Si no, hay que volver a intentarlo más tarde, repetidamente.

Mientras que las aplicaciones simples pueden decidir no preocuparse por la pérdida del dispositivo, en las plataformas de escritorio de uso común una pérdida del dispositivo puede ocurrir debido a una variedad de razones, incluyendo la desconexión física del adaptador gráfico, la desactivación del dispositivo o controlador, la desinstalación o actualización del controlador gráfico, o debido a errores que conducen a un reinicio del dispositivo gráfico. Algunos de estos pueden ocurrir en circunstancias perfectamente normales también, por ejemplo, la actualización del controlador de gráficos a una versión más reciente es una tarea común que puede ocurrir en cualquier momento mientras se ejecuta una aplicación Qt. Los usuarios pueden muy bien esperar que las aplicaciones sean capaces de sobrevivir a esto, incluso cuando la aplicación está utilizando activamente una API como OpenGL o Direct3D.

Se puede esperar que los propios frameworks de Qt construidos sobre QRhi, como, Qt Quick, manejen y tomen las medidas apropiadas cuando se produce una pérdida de dispositivo. Si los datos para los recursos gráficos, tales como texturas y buffers, están todavía disponibles en la CPU, tal evento puede no ser perceptible en el nivel de aplicación ya que los recursos gráficos pueden ser reinicializados sin problemas. 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 dispositivos.

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

Devuelve true si el feature especificado es compatible

bool QRhi::isRecordingFrame() const

Devuelve true cuando hay un marco activo, lo que significa que hubo un beginFrame() (o beginOffscreenFrame()) sin el correspondiente endFrame() (o endOffscreenFrame()) todavía.

Véase 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 para formatos sin comprimir como comprimidos.

bool QRhi::isYUpInFramebuffer() const

Devuelve true si la API gráfica subyacente tiene el eje Y apuntando hacia arriba en framebuffers e imágenes.

En la práctica esto es true sólo para OpenGL.

bool QRhi::isYUpInNDC() const

Devuelve true si la API gráfica subyacente tiene el eje Y apuntando hacia arriba en su sistema de coordenadas de dispositivo normalizado.

En la práctica esto es false sólo para Vulkan.

bool QRhi::makeThreadLocalNativeContextCurrent()

Con OpenGL, esto hace que el contexto OpenGL se actualice en el subproceso actual. La función no tiene efecto con otros backends.

Llamar a esta función es relevante típicamente en el código del framework Qt, cuando uno tiene que asegurarse de que el código OpenGL externo proporcionado por la aplicación puede seguir ejecutándose como lo hacía antes con el uso directo de OpenGL, siempre y cuando QRhi esté usando el backend OpenGL.

Devuelve false cuando falla, de forma similar a QOpenGLContext::makeCurrent(). Cuando la operación falla, se puede llamar a isDeviceLost() para determinar si hubo una situación de pérdida de contexto. Esta comprobación es equivalente a la realizada mediante QOpenGLContext::isValid().

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

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

Devuelve el número de niveles mip para un determinado size.

const QRhiNativeHandles *QRhi::nativeHandles()

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

Cast to QRhiVulkanNativeHandles, QRhiD3D11NativeHandles, QRhiD3D12NativeHandles, QRhiGles2NativeHandles, or QRhiMetalNativeHandles as appropriate.

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

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

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

QRhiComputePipeline *QRhi::newComputePipeline()

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

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 formatos type, pixelSize, sampleCount, y flags especificados.

Cuando backingFormatHint se establece en un formato de textura distinto de QRhiTexture::UnknownFormat, puede ser utilizado por el backend para decidir qué formato utilizar para el almacenamiento que respalda el renderbuffer.

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 minimización minFilter, el modo mipmapping mipmapMode, y los modos de direccionamiento (wrap) addressU, addressV, y addressW.

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

QRhiShaderResourceBindings *QRhi::newShaderResourceBindings()

Devuelve un nuevo recurso de colección de vinculación de recursos de sombreado.

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

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

Devuelve un nuevo objeto de mapa de sombreado.

Esta función se introdujo en Qt 6.9.

QRhiSwapChain *QRhi::newSwapChain()

Devuelve una nueva swapchain.

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 format, pixelSize, sampleCount, y flags.

Una matriz de textura 1D debe tener QRhiTexture::OneDimensional establecido en flags. Esta función establecerá implícitamente esta bandera si la altura de pixelSize es 0.

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 format, width, height, depth, sampleCount, y flags.

Esta sobrecarga es adecuada para texturas 3D porque permite especificar depth. Una textura 3D debe tener QRhiTexture::ThreeDimensional establecido en flags, pero usando esta sobrecarga eso puede omitirse porque la bandera se establece implícitamente siempre que depth sea mayor que 0. Para texturas 1D, 2D y cubos depth debe establecerse en 0.

Una textura 1D debe tener QRhiTexture::OneDimensional fijado en flags. Esta sobrecarga fijará implícitamente esta bandera si tanto height como depth son 0.

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

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

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

Una matriz de texturas 1D debe tener QRhiTexture::OneDimensional en flags. Esta función fijará implícitamente esta bandera si la altura de pixelSize es 0.

Véase también newTexture().

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

Devuelve un nuevo objetivo de renderizado de textura con los anexos de color y profundidad/esténcil dados 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.

Al no estar ligada 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();

QByteArray QRhi::pipelineCacheData()

Devuelve un blob de datos binarios con los datos recogidos de QRhiGraphicsPipeline y QRhiComputePipeline creados con éxito durante la vida de este QRhi.

Al guardar y luego, en posteriores ejecuciones de la misma aplicación, recargar los datos de la caché, se pueden reducir potencialmente los tiempos de creación de pipelines y shaders. Lo que incluye exactamente la caché y su versión serializada no está especificado, es siempre específico del backend utilizado, y en algunos casos también depende de la implementación particular de la API gráfica.

Cuando el PipelineCacheDataLoadSave es reportado como no soportado, el QByteArray devuelto está vacío.

Cuando no se ha especificado el indicador EnablePipelineCacheDataSave al llamar a create(), el archivo QByteArray devuelto puede estar vacío, incluso si la función PipelineCacheDataLoadSave está soportada.

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 con el dispositivo gráfico y la versión exacta del driver utilizado. QRhi se encarga de añadir la cabecera apropiada y las salvaguardas que aseguran que los datos siempre pueden ser pasados de forma segura a setPipelineCacheData(), por lo tanto, intentar cargar datos desde una ejecución en otra versión de un driver será manejado de forma segura y con gracia.

Véase EnablePipelineCacheDataSave para más detalles sobre esta función.

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

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

Devuelve true si se puede esperar que create() tenga éxito cuando se llama a los dados impl y params.

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 sondeo específica, que permite realizar pruebas de una manera más ligera sin contaminar la salida de depuración con advertencias en caso de fallo.

Véase también create().

void QRhi::releaseCachedResources()

Intenta liberar recursos en las cachés del backend. Esto puede incluir tanto recursos de CPU como de GPU. Sólo la memoria y los recursos que pueden ser recreados automáticamente están dentro del alcance. Por ejemplo, si la implementación de QRhiGraphicsPipeline del backend mantiene una caché de resultados de compilación de sombreadores, la llamada a esta función lleva a vaciar esa caché, liberando así potencialmente memoria y recursos gráficos.

Llamar a esta función tiene sentido en entornos con recursos limitados, donde en un momento dado es necesario garantizar un uso mínimo de recursos, a expensas del rendimiento.

void QRhi::removeCleanupCallback(const void *key)

Cancela el registro de la llamada de retorno con key. Si no se registró ninguna llamada de retorno de limpieza con key, la función no hace nada. Las retrollamadas registradas sin clave no pueden ser eliminadas.

Véase también addCleanupCallback().

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

Devuelve el valor del recurso especificado limit.

Se espera que los valores sean consultados por los backends en el momento de la inicialización, lo que significa que llamar a esta función es una operación ligera.

void QRhi::setPipelineCacheData(const QByteArray &data)

Carga data en la caché de canalización, si procede.

Cuando el PipelineCacheDataLoadSave es reportado como no soportado, la función es segura de llamar, pero no tiene ningún efecto.

El blob devuelto por pipelineCacheData() es siempre específico para la versión de Qt, el backend QRhi, y, en algunos casos, también para el dispositivo gráfico, y una versión dada del controlador gráfico. QRhi se encarga de añadir la cabecera apropiada y las salvaguardas que aseguran que los datos siempre pueden ser pasados de forma segura a esta función. Si hay un desajuste, por ejemplo, porque el controlador se ha actualizado a una versión más reciente, o porque los datos se generaron a partir de un backend QRhi diferente, se imprime una advertencia y data se ignora de forma segura.

Con Vulkan, esto se asigna directamente a VkPipelineCache. Al llamar a esta función se crea un nuevo objeto de caché de canalización Vulkan, con sus datos iniciales procedentes de data. El objeto de caché de canalización es utilizado entonces por todos los objetos QRhiGraphicsPipeline y QRhiComputePipeline creados posteriormente, acelerando así, potencialmente, la creación de canalizaciones.

Con otras APIs no existe una caché de pipeline real, pero pueden proporcionar una caché con bytecode de compilaciones de shaders (D3D) o binarios de programa (OpenGL). En aplicaciones que realizan muchas compilaciones de sombreadores desde el código fuente en tiempo de ejecución, esto puede proporcionar un aumento significativo en las ejecuciones posteriores si la "caché de canalización" se preconfigura desde una ejecución anterior utilizando esta función.

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

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

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

Con backends y APIs gráficas donde sea aplicable, esta función permite proporcionar argumentos adicionales al siguiente envío de comandos a la cola de comandos gráficos.

En particular, con Vulkan esto permite pasar una lista de objetos semáforo Vulkan para que vkQueueSubmit() señale y espere. params debe ser entonces un QRhiVulkanQueueSubmitParams. Esto se vuelve esencial en ciertos casos de uso avanzado, como cuando se realizan llamadas Vulkan nativas que implican tener que esperar y señalar VkSemaphores que el código de renderizado o computación Vulkan personalizado de la aplicación gestiona. Además, esto también permite especificar semáforos adicionales en los que esperar en la siguiente vkQueuePresentKHR().

Con muchos otros backends la implementación de esta función es un no-op.

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 determinado mipLevel, calculado a partir del tamaño del nivel 0 dado 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 sólo están disponibles con algunos backends, donde tales operaciones están bajo el control de Qt. Con APIs gráficas donde no hay control de nivel inferior sobre las asignaciones de memoria de recursos, esto nunca será soportado y todos los campos relevantes en los resultados son 0.

Con Vulkan en particular, los valores son válidos siempre, y se consultan desde la biblioteca de asignación de memoria subyacente. Esto permite conocer los requisitos de memoria de los búferes activos y las texturas.

Lo mismo ocurre con Direct 3D 12. Además de las estadísticas de la biblioteca asignadora de memoria, aquí el resultado también incluye un campo totalUsageBytes que informa del tamaño total incluyendo los recursos adicionales que no están bajo el control de la biblioteca asignadora de memoria (buffers swapchain, heaps de descriptores, etc.), tal y como informa 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 empleado en la creación de canalizaciones gráficas y de cálculo (que suele implicar la compilación de shaders o búsquedas en caché, y un procesamiento potencialmente costoso).

QList<int> QRhi::supportedSampleCounts() const

Devuelve la lista de recuentos de muestras admitidos.

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

Con algunos backend esta lista de valores soportados está fijada de antemano, mientras que con otros las propiedades (físicas) del dispositivo indican lo que está soportado en tiempo de ejecución.

Véase 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 admitidas para la dirección sampleCount especificada.

Siempre se admite 1x1.

Esta función se introdujo en Qt 6.9.

QThread *QRhi::thread() const

Devuelve el hilo en el que se QRhi initialized .

int QRhi::ubufAligned(int v) const

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

int QRhi::ubufAlignment() const

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

Intentar enlazar una región de búfer uniforme con un desplazamiento no alineado con este valor provocará fallos 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 de la API de backend y gráficos especificada por impl. window es la QWindow a la que se dirige una swapchain.

La estructura devuelta puede pasarse a QRhiSwapChain::setProxyData(). Esto tiene sentido en sistemas de renderizado con hilos: se espera que esta función estática sea llamada en el hilo principal (gui), a diferencia de todas las operaciones QRhi, luego transferida al hilo que trabaja con QRhi y QRhiSwapChain y pasada a la swapchain. Esto permite hacer consultas nativas de la plataforma que sólo son seguras para ser llamadas en el hilo principal, por ejemplo para consultar la CAMetalLayer desde una NSView, y luego pasar los datos a la QRhiSwapChain que vive en el hilo de renderizado. Con el ejemplo de Metal, hacer el acceso a view.layer en un hilo de renderizado dedicado causa una advertencia en el Thread Checker de Xcode. Con el mecanismo de proxy de datos, esto se evita.

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