QSGRendererInterface Class
Una interfaz que permite acceder a algunos de los mecanismos internos específicos de la API gráfica del grafo de escena. Más información...
| Encabezado: | #include <QSGRendererInterface> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
Tipos públicos
| enum | GraphicsApi { Unknown, Software, OpenVG, OpenGL, Direct3D11, …, Null } |
| enum | RenderMode { RenderMode2D, RenderMode2DNoDepthBuffer, RenderMode3D } |
| enum | Resource { DeviceResource, CommandQueueResource, CommandListResource, PainterResource, RhiResource, …, GraphicsQueueIndexResource } |
| enum | ShaderCompilationType { RuntimeCompilation, OfflineCompilation } |
| flags | ShaderCompilationTypes |
| enum | ShaderSourceType { ShaderSourceString, ShaderSourceFile, ShaderByteCode } |
| flags | ShaderSourceTypes |
| enum | ShaderType { UnknownShadingLanguage, GLSL, HLSL, RhiShader } |
Funciones públicas
| virtual void * | getResource(QQuickWindow *window, QSGRendererInterface::Resource resource) const |
| virtual void * | getResource(QQuickWindow *window, const char *resource) const |
| virtual QSGRendererInterface::GraphicsApi | graphicsApi() const = 0 |
| virtual QSGRendererInterface::ShaderCompilationTypes | shaderCompilationType() const = 0 |
| virtual QSGRendererInterface::ShaderSourceTypes | shaderSourceType() const = 0 |
| virtual QSGRendererInterface::ShaderType | shaderType() const = 0 |
Miembros públicos estáticos
| bool | isApiRhiBased(QSGRendererInterface::GraphicsApi api) |
Descripción detallada
Las interfaces de renderizado permiten acceder a funcionalidades específicas de la API gráfica en el grafo de escena. Por lo general, estos detalles internos no se exponen. Sin embargo, al integrar un renderizado personalizado mediante QSGRenderNode, por ejemplo, puede ser necesario consultar determinados valores, como el dispositivo gráfico (p. ej., el dispositivo Direct3D o Vulkan) que utiliza el grafo de escena.
Las funciones de `QSGRendererInterface` tienen una disponibilidad variable. Las consultas sobre la API y el lenguaje, como ` graphicsApi()` o ` shaderType()`, están siempre disponibles, lo que significa que basta con crear un ` QQuickWindow ` o un ` QQuickView`, y la API gráfica o el lenguaje de sombreado en uso se pueden consultar inmediatamente después mediante ` QQuickWindow::rendererInterface()`. Esto garantiza que utilidades como el tipo QML « GraphicsInfo » puedan informar de los valores correctos lo antes posible, sin que los valores de las propiedades condicionales —que dependen, por ejemplo, de « shaderType()»— den lugar a valores inesperados.
Sin embargo, los accesores específicos del motor, como getResource(), solo están disponibles una vez inicializado el grafo de escena. Además, puede haber limitaciones específicas del backend en cuanto al momento en que se pueden invocar dichas funciones. La única forma de garantizar el éxito es invocarlas cuando la representación de un nodo (es decir, la preparación de la lista de comandos para el siguiente fotograma) está activa. En la práctica, esto suele significar QSGRenderNode::render().
Documentación sobre los tipos de miembro
enum QSGRendererInterface::GraphicsApi
| Constante | Valor | Descripción |
|---|---|---|
QSGRendererInterface::Unknown | 0 | Se está utilizando una API gráfica desconocida |
QSGRendererInterface::Software | 1 | Se está utilizando el renderizador 2D de « Qt Quick » |
QSGRendererInterface::OpenVG | 2 | OpenVG a través de EGL |
QSGRendererInterface::OpenGL (since Qt 5.14) | 3 | OpenGL ES 2.0 o superior a través de una capa de abstracción gráfica. |
QSGRendererInterface::Direct3D11 (since Qt 5.14) | 4 | Direct3D 11 a través de una capa de abstracción gráfica. |
QSGRendererInterface::Direct3D12 (since Qt 6.6) | 8 | Direct3D 12 a través de una capa de abstracción gráfica. |
QSGRendererInterface::Vulkan (since Qt 5.14) | 5 | Vulkan 1.0 a través de una capa de abstracción gráfica. |
QSGRendererInterface::Metal (since Qt 5.14) | 6 | Metal a través de una capa de abstracción gráfica. |
QSGRendererInterface::Null (since Qt 5.14) | 7 | Nulo (sin salida) a través de una capa de abstracción gráfica. |
enum QSGRendererInterface::RenderMode
| Constante | Valor | Descripción |
|---|---|---|
QSGRendererInterface::RenderMode2D | 0 | Renderizado 2D normal |
QSGRendererInterface::RenderMode2DNoDepthBuffer | 1 | Renderizado 2D normal con el búfer de profundidad desactivado |
QSGRendererInterface::RenderMode3D | 2 | La escena se renderiza como parte de un gráfico 3D |
enum QSGRendererInterface::Resource
| Constante | Valor | Descripción |
|---|---|---|
QSGRendererInterface::DeviceResource | 0 | El recurso es un puntero al dispositivo gráfico, cuando proceda. Por ejemplo, un ` VkDevice *`, ` MTLDevice * ` o ` ID3D11Device *`. Ten en cuenta que, con Vulkan, el valor devuelto es un puntero al `VkDevice`, no el propio identificador. Esto se debe a que los identificadores de Vulkan pueden no ser punteros y pueden utilizar un tamaño diferente al de los punteros de la arquitectura, por lo que limitarse a realizar una conversión a o des void * o es incorrecto. |
QSGRendererInterface::CommandQueueResource | 1 | El recurso es un puntero a la cola de comandos gráficos utilizada por el grafo de escena, cuando proceda. Por ejemplo, un ` VkQueue * ` o un ` MTLCommandQueue *`. Ten en cuenta que, con Vulkan, el valor devuelto es un puntero a `VkQueue`, no el identificador en sí. |
QSGRendererInterface::CommandListResource | 2 | El recurso es un puntero a la lista de comandos o al búfer utilizado por el grafo de escena, cuando proceda. Por ejemplo, un ` VkCommandBuffer * ` o un ` MTLCommandBuffer *`. Este objeto tiene una validez limitada y solo es válido mientras el grafo de escena está preparando el siguiente fotograma. Tenga en cuenta que, con Vulkan, el valor devuelto es un puntero a `VkCommandBuffer`, no el identificador en sí. |
QSGRendererInterface::PainterResource | 3 | El recurso es un puntero al ` QPainter ` activo utilizado por el grafo de escena, cuando se ejecuta con el backend de software. |
QSGRendererInterface::RhiResource (since Qt 5.14) | 4 | El recurso es un puntero a la instancia de QRhi utilizada por el grafo de escena, cuando sea aplicable. |
QSGRendererInterface::RhiSwapchainResource (since Qt 6.0) | 5 | El recurso es un puntero a una instancia de QRhiSwapchain asociada a la ventana. El valor es nulo cuando la ventana se utiliza en combinación con QQuickRenderControl. |
QSGRendererInterface::RhiRedirectCommandBuffer (since Qt 6.0) | 6 | El recurso es un puntero a una instancia de ` QRhiCommandBuffer ` asociada a la ventana y a su ` QQuickRenderControl`. El valor es nulo cuando la ventana no está asociada a un ` QQuickRenderControl`. |
QSGRendererInterface::RhiRedirectRenderTarget (since Qt 6.0) | 7 | El recurso es un puntero a una instancia de ` QRhiTextureRenderTarget ` asociada a la ventana y a su ` QQuickRenderControl`. El valor es `null` cuando la ventana no está asociada a un ` QQuickRenderControl`. Tenga en cuenta que el valor siempre refleja el destino de renderizado de textura principal y no depende de la escena ` Qt Quick `, lo que significa que no tiene en cuenta ningún paso de renderizado adicional dirigido a texturas generado por capas de ` ShaderEffect ` o ` QQuickItem `. |
QSGRendererInterface::PhysicalDeviceResource (since Qt 5.14) | 8 | El recurso es un puntero al objeto de dispositivo físico utilizado por el grafo de escena, cuando proceda. Por ejemplo, un VkPhysicalDevice *. Ten en cuenta que, con Vulkan, el valor devuelto es un puntero al VkPhysicalDevice, no el propio identificador. |
QSGRendererInterface::OpenGLContextResource (since Qt 5.14) | 9 | El recurso es un puntero al ` QOpenGLContext ` utilizado por el grafo de escena (en el hilo de renderizado), cuando proceda. |
QSGRendererInterface::DeviceContextResource (since Qt 5.14) | 10 | El recurso es un puntero al contexto de dispositivo utilizado por el grafo de escena, cuando proceda. Por ejemplo, un ` ID3D11DeviceContext *`. |
QSGRendererInterface::CommandEncoderResource (since Qt 5.14) | 11 | El recurso es un puntero al objeto codificador de comandos de renderizado actualmente activo utilizado por el grafo de escena, cuando proceda. Por ejemplo, un ` MTLRenderCommandEncoder *`. Este objeto tiene una validez limitada y solo es válido mientras el grafo de escena está grabando una pasada de renderizado para el siguiente fotograma. |
QSGRendererInterface::VulkanInstanceResource (since Qt 5.14) | 12 | El recurso es un puntero al ` QVulkanInstance ` utilizado por el grafo de escena, cuando proceda. |
QSGRendererInterface::RenderPassResource (since Qt 5.14) | 13 | El recurso es un puntero al paso de renderizado principal utilizado por el grafo de escena, que describe los anexos de color y profundidad/plantilla y cómo se utilizan. Por ejemplo, un ` VkRenderPass *`. Ten en cuenta que el valor siempre refleja el destino de renderizado principal (ya sea la ventana en pantalla o la textura a la que redirige ` QQuickRenderControl `) y no depende de la escena ` Qt Quick `, lo que significa que no tiene en cuenta ningún paso de renderizado adicional dirigido a texturas generado por las capas ` ShaderEffect ` o ` QQuickItem `. |
QSGRendererInterface::RedirectPaintDevice (since Qt 6.4) | 14 | El recurso es un puntero a una instanci QPaintDevice asociada a la ventana y a su QQuickRenderControl. El valor es nulo cuando la ventana no está asociada a un QQuickRenderControl. |
QSGRendererInterface::GraphicsQueueFamilyIndexResource (since Qt 6.6) | 15 | El recurso es un puntero a un índice de familia de colas gráficas utilizado por el grafo de escena, cuando procede. Con Vulkan, se trata de un puntero a un uint32_t valor de índice. |
QSGRendererInterface::GraphicsQueueIndexResource (since Qt 6.6) | 16 | El recurso es un puntero al índice de la cola gráfica (uint32_t) utilizado por el grafo de escena, cuando procede. Con Vulkan, se trata de un puntero a un valor de índice de uint32_t, que en la práctica es el índice de la VkQueue indicado para CommandQueueResource. |
enum QSGRendererInterface::ShaderCompilationType
flags QSGRendererInterface::ShaderCompilationTypes
| Constante | Valor | Descripción |
|---|---|---|
QSGRendererInterface::RuntimeCompilation | 0x01 | Se admite la compilación en tiempo de ejecución del código fuente del shader |
QSGRendererInterface::OfflineCompilation | 0x02 | Se admite el código byte precompilado |
El tipo ShaderCompilationTypes es una definición de tipo para QFlags<ShaderCompilationType>. Almacena una combinación OR de valores de ShaderCompilationType.
enum QSGRendererInterface::ShaderSourceType
flags QSGRendererInterface::ShaderSourceTypes
| Constante | Valor | Descripción |
|---|---|---|
QSGRendererInterface::ShaderSourceString | 0x01 | El código fuente del sombreador se puede proporcionar como una cadena en las propiedades correspondientes de ShaderEffect |
QSGRendererInterface::ShaderSourceFile | 0x02 | Se admiten archivos locales o de recursos que contengan código fuente del shader |
QSGRendererInterface::ShaderByteCode | 0x04 | Se admiten archivos locales o de recursos que contengan código de bytes de sombreador |
El tipo ShaderSourceTypes es un typedef para QFlags<ShaderSourceType>. Almacena una combinación OR de valores de ShaderSourceType.
enum QSGRendererInterface::ShaderType
| Constante | Valor | Descripción |
|---|---|---|
QSGRendererInterface::UnknownShadingLanguage | 0 | Aún se desconoce, ya que no hay ninguna ventana ni grafo de escena asociados |
QSGRendererInterface::GLSL | 1 | GLSL o GLSL ES |
QSGRendererInterface::HLSL | 2 | HLSL |
QSGRendererInterface::RhiShader (since Qt 5.14) | 3 | Consume instancias de « QShader » que contienen variantes de shader para múltiples lenguajes de destino y formatos intermedios. |
Documentación de las funciones de miembro
[virtual] void *QSGRendererInterface::getResource(QQuickWindow *window, QSGRendererInterface::Resource resource) const
Consulta un recurso gráfico resource en window. Devuelve «null» cuando el recurso en cuestión no es compatible o no está disponible.
Si la operación se realiza correctamente, el puntero devuelto es o bien un puntero directo a una interfaz, o bien un puntero a un identificador opaco que debe desreferenciarse primero (por ejemplo, VkDevice dev = *static_cast<VkDevice *>(result)). Esto último es necesario, ya que dichos identificadores pueden tener tamaños diferentes a los de un puntero.
Nota: La propiedad del puntero devuelto nunca se transfiere al llamante.
Nota: Esta función solo debe llamarse en el hilo de renderizado.
[virtual] void *QSGRendererInterface::getResource(QQuickWindow *window, const char *resource) const
Consulta un recurso gráfico. « resource » es una clave específica del backend. Esto permite admitir cualquier recurso futuro que no figure en la enumeración «Resource».
Nota: La propiedad del puntero devuelto nunca se transfiere al llamante.
Nota: Esta función solo debe invocarse en el hilo de renderizado.
[pure virtual] QSGRendererInterface::GraphicsApi QSGRendererInterface::graphicsApi() const
Devuelve la API gráfica que está utilizando el grafo de escena « Qt Quick ».
Nota: Esta función se puede invocar desde cualquier hilo.
[static] bool QSGRendererInterface::isApiRhiBased(QSGRendererInterface::GraphicsApi api)
Devuelve «true» si « api » se basa en una capa de abstracción gráfica (QRhi) en lugar de llamar directamente a la API gráfica nativa.
Nota: Esta función se puede invocar desde cualquier hilo.
[pure virtual] QSGRendererInterface::ShaderCompilationTypes QSGRendererInterface::shaderCompilationType() const
Devuelve una máscara de bits con los métodos de compilación de shaders compatibles con el backend « Qt Quick » que utiliza la aplicación.
Nota: Esta función se puede invocar desde cualquier hilo.
Véase también « QtQuick::GraphicsInfo ».
[pure virtual] QSGRendererInterface::ShaderSourceTypes QSGRendererInterface::shaderSourceType() const
Devuelve una máscara de bits con las formas compatibles de proporcionar fuentes de shaders en los elementos de « ShaderEffect ».
Nota: Esta función se puede invocar en cualquier hilo.
Véase también QtQuick::GraphicsInfo.
[pure virtual] QSGRendererInterface::ShaderType QSGRendererInterface::shaderType() const
Devuelve el lenguaje de sombreado compatible con el backend Qt Quick que utiliza la aplicación.
Nota: Esta función se puede invocar en cualquier hilo.
Véase también QtQuick::GraphicsInfo.
© 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.