QShader Class
Contiene varias versiones de un sombreador traducidas a varios lenguajes de sombreado, junto con metadatos de reflexión. Más...
| Cabecera: | #include <QShader> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui)target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Desde: | Qt 6.6 |
- Lista de todos los miembros, incluyendo los heredados
- QShader es parte de Renderizado en 3D.
Tipos Públicos
| struct | NativeShaderInfo |
| struct | SeparateToCombinedImageSamplerMapping |
| NativeResourceBindingMap | |
| SeparateToCombinedImageSamplerMappingList | |
| enum class | SerializedFormatVersion { Latest, Qt_6_5, Qt_6_4 } |
| enum | Source { SpirvShader, GlslShader, HlslShader, DxbcShader, MslShader, …, WgslShader } |
| enum | Stage { VertexStage, TessellationControlStage, TessellationEvaluationStage, GeometryStage, FragmentStage, ComputeStage } |
| enum | Variant { StandardShader, BatchableVertexShader, UInt16IndexedVertexAsComputeShader, UInt32IndexedVertexAsComputeShader, NonIndexedVertexAsComputeShader, HdrCapableFragmentShader } |
Funciones Públicas
| QShader() | |
| QShader(const QShader &other) | |
(since 6.7) | QShader(QShader &&other) |
| ~QShader() | |
| QList<QShaderKey> | availableShaders() const |
| QShaderDescription | description() const |
| bool | isValid() const |
| QShader::NativeResourceBindingMap | nativeResourceBindingMap(const QShaderKey &key) const |
| QShader::NativeShaderInfo | nativeShaderInfo(const QShaderKey &key) const |
| void | removeNativeShaderInfo(const QShaderKey &key) |
| void | removeResourceBindingMap(const QShaderKey &key) |
| void | removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key) |
| void | removeShader(const QShaderKey &key) |
| QShader::SeparateToCombinedImageSamplerMappingList | separateToCombinedImageSamplerMappingList(const QShaderKey &key) const |
| QByteArray | serialized(QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const |
| void | setDescription(const QShaderDescription &desc) |
| void | setNativeShaderInfo(const QShaderKey &key, const QShader::NativeShaderInfo &info) |
| void | setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map) |
| void | setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key, const QShader::SeparateToCombinedImageSamplerMappingList &list) |
| void | setShader(const QShaderKey &key, const QShaderCode &shader) |
| void | setStage(QShader::Stage stage) |
| QShaderCode | shader(const QShaderKey &key) const |
| QShader::Stage | stage() const |
(since 6.7) void | swap(QShader &other) |
(since 6.7) QShader & | operator=(QShader &&other) |
| QShader & | operator=(const QShader &other) |
Miembros Públicos Estáticos
| QShader | fromSerialized(const QByteArray &data) |
No Miembros Relacionados
| size_t | qHash(const QShader &key, size_t seed = 0) |
| bool | operator!=(const QShader &lhs, const QShader &rhs) |
| bool | operator==(const QShader &lhs, const QShader &rhs) |
Descripción Detallada
QShader es el punto de entrada al código shader en el mundo Qt agnóstico a la API gráfica. En lugar de usar fuentes de shaders GLSL, como era habitual en Qt 5.x, los nuevos sistemas gráficos con backends para múltiples APIs gráficas, como Vulkan, Metal, Direct3D y OpenGL, toman QShader como entrada siempre que se necesite especificar un shader.
Advertencia: La familia de clases QRhi en el módulo Qt Gui, incluyendo QShader y QShaderDescription, ofrecen garantías de compatibilidad limitadas. No existen garantías de compatibilidad binaria o de código fuente para estas clases, lo que significa que sólo se garantiza que la API funcione con la versión de Qt con la que se desarrolló la aplicación. Sin embargo, los cambios incompatibles con el código fuente se mantendrán al mínimo y sólo se realizarán en versiones menores (6.7, 6.8, etc.). Para utilizar estas clases en una aplicación, enlace a Qt::GuiPrivate (si utiliza CMake), e incluya las cabeceras con el prefijo rhi, por ejemplo #include <rhi/qshader.h>.
Una instancia de QShader está vacía y, por tanto, no es válida por defecto. Para obtener una instancia útil, los dos métodos típicos son:
- Generar el contenido fuera de línea, durante el tiempo de compilación o antes, utilizando la herramienta de línea de comandos
qsb. El resultado es un archivo binario que se envía con la aplicación, leído a través de QIODevice::readAll(), y luego deserializado a través de fromSerialized(). Para más información, consulte QShaderBaker. - Generar en tiempo de ejecución mediante QShaderBaker. Se trata de una operación costosa, pero permite a las aplicaciones utilizar cadenas fuente de sombreado proporcionadas por el usuario o generadas dinámicamente.
Cuando se utiliza junto con el Qt Rendering Hardware Interface y sus clases, como QRhiGraphicsPipeline, no es necesaria ninguna acción adicional por parte de la aplicación ya que estas clases están preparadas para consumir un QShader siempre que se necesite especificar un shader para una determinada etapa del pipeline gráfico.
Alternativamente, las aplicaciones pueden acceder
- el código fuente o byte de cualquiera de las versiones del lenguaje de sombreado que se incluyen en el QShader,
- el nombre del punto de entrada del sombreador,
- los metadatos de reflexión que contienen una descripción de las entradas, salidas y recursos del sombreador, como los bloques uniformes. Esto es esencial cuando una aplicación o framework necesita descubrir las entradas de un shader en tiempo de ejecución debido a que no tiene conocimiento previo de los atributos de vértice o la disposición de los buffers uniformes utilizados por el shader.
QShader no hace ninguna suposición sobre el lenguaje de sombreado que se utilizó como fuente para generar las distintas versiones y variantes que se incluyen en él.
QShader utiliza la compartición implícita de forma similar a muchos tipos del núcleo de Qt, por lo que puede ser devuelto o pasado por valor. Detach ocurre implícitamente cuando se llama a un setter.
Como referencia, un típico, portable QRhi espera que un QShader adecuado para todos sus backends contenga al menos lo siguiente. (esto excluye el soporte para contextos OpenGL de perfil básico, para eso añade GLSL 150 o más reciente)
- SPIR-V 1.0 bytecode adecuado para Vulkan 1.0 o más reciente
- Código fuente GLSL/ES 100 apto para OpenGL ES 2.0 o posterior.
- Código fuente GLSL 120 adecuado para OpenGL 2.1 o posterior
- Código fuente de HLSL Shader Model 5.0 o el bytecode DXBC correspondiente apto para Direct3D 11/12
- Código fuente de Metal Shading Language 1.2 o el bytecode correspondiente apto para Metal 1.2 o posterior.
Véase también QShaderBaker.
Documentación de tipos de miembros
[alias] QShader::NativeResourceBindingMap
Sinónimo de QMap<int, std::pair<int, int>>.
El modelo de vinculación de recursos que asume QRhi se basa en SPIR-V. Esto significa que los búferes uniformes, los búferes de almacenamiento, los muestreadores de imágenes combinados y las imágenes de almacenamiento comparten un espacio de puntos de enlace común. Se espera que los números de enlace en QShaderDescription y QRhiShaderResourceBinding coincidan con el calificador de diseño binding en el sombreador GLSL compatible con Vulkan.
Las API de gráficos distintas de Vulkan pueden utilizar un modelo de vinculación de recursos que no sea totalmente compatible con este. El generador del código del sombreador traducido desde SPIR-V puede optar por no tener en cuenta los calificadores de vinculación de SPIR-V, por diversas razones. Este es el caso, por ejemplo, del backend Metal de SPIRV-Cross. Además, incluso cuando una traducción automática e implícita es posible en la mayoría de los casos (por ejemplo, mediante el uso de puntos de enlace SPIR-V como índices de registro de recursos HLSL), la asignación de enlaces de recursos sin estar limitado por los puntos de enlace SPIR-V puede conducir a mejores resultados.
Por lo tanto, QShader puede exponer un mapa adicional que describa cuál es el punto de enlace nativo para un enlace SPIR-V determinado. Se espera que los backends de QRhi, para los que esto es relevante, utilicen este mapa automáticamente, según corresponda. El valor es un par, porque los muestreadores de imágenes combinados pueden corresponder a dos recursos nativos (una textura y un muestreador) en algunos lenguajes de sombreado. En ese caso, el segundo valor se refiere al muestreador.
Nota: El enlace nativo puede ser -1, en caso de que no haya un enlace activo para el recurso en el sombreador. (por ejemplo, hay un bloque uniforme declarado, pero no se utiliza en el código del sombreador) El mapa siempre está completo, lo que significa que hay una entrada para todos los bloques uniformes declarados, bloques de almacenamiento, objetos de imagen y muestreadores combinados, pero el valor será -1 para los que no se hace referencia en las funciones del sombreador.
[alias] QShader::SeparateToCombinedImageSamplerMappingList
Sinónimo de QList<QShader::SeparateToCombinedImageSamplerMapping>.
enum class QShader::SerializedFormatVersion
Describe el formato de salida deseado al serializar QShader.
El valor por defecto para el argumento version de serialized() es Latest. Esto es suficiente en la gran mayoría de los casos. Especificar otro valor sólo es necesario cuando la intención es generar datos serializados que puedan ser cargados por versiones anteriores de Qt. Por ejemplo, la herramienta qsb utiliza estos valores enum cuando se proporciona el argumento de línea de comandos --qsbversion.
Nota: La selección de versiones anteriores hará que ciertas características no funcionen con el activo generado. Esto no es un problema cuando se utiliza el activo con la versión antigua de Qt especificada, dado que esa versión de Qt no tiene las nuevas características de las versiones más recientes de Qt que dependen de los datos adicionales generados en QShader y el flujo de datos serializados, pero puede convertirse en un problema si el activo generado se utiliza con una versión más reciente de Qt.
| Constante | Valor | Descripción |
|---|---|---|
QShader::SerializedFormatVersion::Latest | 0 | La versión actual de Qt |
QShader::SerializedFormatVersion::Qt_6_5 | 1 | Qt 6.5 |
QShader::SerializedFormatVersion::Qt_6_4 | 2 | Qt 6.4 |
enum QShader::Source
Describe qué tipo de código de sombreado contiene una entrada.
| Constante | Valor | Descripción |
|---|---|---|
QShader::SpirvShader | 0 | SPIR-V |
QShader::GlslShader | 1 | GLSL |
QShader::HlslShader | 2 | HLSL |
QShader::DxbcShader | 3 | Direct3D bytecode (HLSL compilado por fxc) |
QShader::MslShader | 4 | Lenguaje de sombreado Metal |
QShader::DxilShader | 5 | Código de bytes Direct3D (HLSL compilado por dxc) |
QShader::MetalLibShader | 6 | Código de bytes Metal precompilado |
QShader::WgslShader | 7 | WGSL |
enum QShader::Stage
Describe la etapa de la canalización gráfica para la que es adecuado el sombreador.
| Constante | Valor | Descripción |
|---|---|---|
QShader::VertexStage | 0 | Sombreador de vértices |
QShader::TessellationControlStage | 1 | Sombreador de control de teselación (casco) |
QShader::TessellationEvaluationStage | 2 | Sombreador de evaluación de teselación (dominio) |
QShader::GeometryStage | 3 | Sombreador de geometría |
QShader::FragmentStage | 4 | Sombreador de fragmentos (píxeles) |
QShader::ComputeStage | 5 | Sombreador de cálculo |
enum QShader::Variant
Describe qué tipo de código de sombreado contiene una entrada.
| Constante | Valor | Descripción |
|---|---|---|
QShader::StandardShader | 0 | La versión normal, no modificada, del código del shader. |
QShader::BatchableVertexShader | 1 | Sombreador de vértices reescrito para ser adecuado para Qt Quick scenegraph batching. |
QShader::UInt16IndexedVertexAsComputeShader | 2 | Un sombreador de vértices destinado a ser utilizado en un canal de Metal con teselación en combinación con llamadas de dibujo indexadas que obtienen datos de índice de un búfer de índice uint16. Para soportar el canal de teselación Metal, el sombreador de vértices se convierte en un sombreador de cálculo que puede depender del uso del búfer de índice en las llamadas de dibujo (por ejemplo, si el sombreador utiliza gl_VertexIndex), de ahí la necesidad de tres variantes dedicadas. |
QShader::UInt32IndexedVertexAsComputeShader | 3 | Un sombreador de vértices destinado a ser utilizado en un canal de Metal con teselación en combinación con llamadas de dibujo indexadas que obtienen datos de índice de un búfer de índice uint32. Para admitir el canal de teselación de Metal, el sombreador de vértices se convierte en un sombreador de cálculo que puede depender del uso del búfer de índice en las llamadas de dibujo (por ejemplo, si el sombreador utiliza gl_VertexIndex), de ahí la necesidad de tres variantes dedicadas. |
QShader::NonIndexedVertexAsComputeShader | 4 | Un sombreador de vértices destinado a ser utilizado en un canal Metal con teselación en combinación con llamadas a dibujo no indexadas. Para soportar el canal de teselación de Metal, el sombreador de vértices se convierte en un sombreador de cálculo que puede depender del uso del búfer de índice en las llamadas de dibujo (por ejemplo, si el sombreador utiliza gl_VertexIndex), de ahí la necesidad de tres variantes dedicadas. |
QShader::HdrCapableFragmentShader (since Qt 6.10) | 5 | Un fragment shader reescrito para soportar el renderizado de alto rango dinámico en un scenegraph Qt Quick. |
Documentación de las funciones miembro
QShader::QShader()
Construye una nueva instancia de QShader vacía (y por tanto inválida).
QShader::QShader(const QShader &other)
Construye una copia de other.
[noexcept, since 6.7] QShader::QShader(QShader &&other)
Mover-construye un nuevo QShader a partir de other.
Nota: El objeto movido-desde other se coloca en un estado parcialmente formado, en el que las únicas operaciones válidas son la destrucción y la asignación de un nuevo valor.
Esta función se introdujo en Qt 6.7.
[noexcept] QShader::~QShader()
Destructor.
QList<QShaderKey> QShader::availableShaders() const
Devuelve la lista de versiones de sombreadores disponibles
QShaderDescription QShader::description() const
Devuelve los metadatos de reflexión del sombreador.
Véase también setDescription().
[static] QShader QShader::fromSerialized(const QByteArray &data)
Crea una nueva instancia QShader a partir de data.
Si data no puede ser deserializado con éxito, el resultado es un QShader construido por defecto para el cual isValid() devuelve false.
Advertencia: Los paquetes de sombreado, incluidos los archivos .qsb del sistema de archivos, se consideran contenido de confianza. Se recomienda a los desarrolladores de aplicaciones que consideren cuidadosamente las implicaciones potenciales antes de permitir la carga de contenido proporcionado por el usuario que no forme parte de la aplicación.
Véase también serialized().
bool QShader::isValid() const
Devuelve true si QShader contiene al menos una versión de shader.
QShader::NativeResourceBindingMap QShader::nativeResourceBindingMap(const QShaderKey &key) const
Devuelve el mapa de vinculación nativo para key. El mapa está vacío si no hay ningún mapa disponible para key (por ejemplo, porque el mapa no es aplicable para la API y el lenguaje de sombreado descritos por key).
QShader::NativeShaderInfo QShader::nativeShaderInfo(const QShaderKey &key) const
Devuelve la estructura nativa de información de sombreado para key, o un objeto vacío si no hay datos disponibles para key, por ejemplo porque dicha asignación no es aplicable para el lenguaje de sombreado o la etapa de sombreado.
Véase también setNativeShaderInfo().
void QShader::removeNativeShaderInfo(const QShaderKey &key)
Elimina la información del shader nativo para key.
void QShader::removeResourceBindingMap(const QShaderKey &key)
Elimina el mapa de vinculación de recursos nativos para key.
void QShader::removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key)
Elimina la lista de asignación del muestreador de imágenes combinadas para key.
void QShader::removeShader(const QShaderKey &key)
Elimina el código fuente o binario del shader para un determinado key. No hace nada si no se encuentra.
QShader::SeparateToCombinedImageSamplerMappingList QShader::separateToCombinedImageSamplerMappingList(const QShaderKey &key) const
Devuelve la lista de mapeado del muestreador de imágenes combinado para key, o una lista vacía si no hay datos disponibles para key, por ejemplo porque dicho mapeado no es aplicable para el lenguaje de sombreado.
Véase también setSeparateToCombinedImageSamplerMappingList().
QByteArray QShader::serialized(QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const
Devuelve una versión binaria serializada de todos los datos contenidos en QShader, adecuada para escribir en archivos u otros dispositivos de E/S.
Por defecto se utiliza el último formato de serialización. Utilice el parámetro version para serializar para una versión Qt de compatibilidad. Sólo cuando se sepa que el flujo de datos generado debe hacerse compatible con una versión antigua de Qt a costa de hacerlo incompatible con características introducidas desde esa versión de Qt, debería usarse otro valor (por ejemplo, Qt_6_5 para Qt 6.5).
Véase también fromSerialized().
void QShader::setDescription(const QShaderDescription &desc)
Establece los metadatos de reflexión en desc.
Véase también description().
void QShader::setNativeShaderInfo(const QShaderKey &key, const QShader::NativeShaderInfo &info)
Almacena el shader nativo info asociado con key.
Véase también nativeShaderInfo().
void QShader::setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map)
Almacena el enlace de recurso nativo map asociado a key.
Véase también nativeResourceBindingMap().
void QShader::setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key, const QShader::SeparateToCombinedImageSamplerMappingList &list)
Almacena la asignación del muestreador de imágenes combinadas list asociada a key.
Véase también separateToCombinedImageSamplerMappingList().
void QShader::setShader(const QShaderKey &key, const QShaderCode &shader)
Almacena el código fuente o binario shader para una determinada versión de shader especificada por key.
Véase también shader().
void QShader::setStage(QShader::Stage stage)
Establece el canal stage.
Véase también stage().
QShaderCode QShader::shader(const QShaderKey &key) const
Devuelve el código fuente o binario de una determinada versión de shader especificada por key.
Véase también setShader().
QShader::Stage QShader::stage() const
Devuelve la etapa del pipeline para la que está destinado el shader.
Véase también setStage().
[noexcept, since 6.7] void QShader::swap(QShader &other)
Intercambia este sombreador con other. Esta operación es muy rápida y nunca falla.
Esta función se introdujo en Qt 6.7.
[noexcept, since 6.7] QShader &QShader::operator=(QShader &&other)
Mover-asigna other a esta instancia QShader.
Nota: El objeto movido-desde other se coloca en un estado parcialmente formado, en el que las únicas operaciones válidas son la destrucción y la asignación de un nuevo valor.
Esta función se introdujo en Qt 6.7.
QShader &QShader::operator=(const QShader &other)
Asigna other a este objeto.
No miembros relacionados
[noexcept] size_t qHash(const QShader &key, size_t seed = 0)
Devuelve el valor hash para key, utilizando seed para sembrar el cálculo.
[noexcept] bool operator!=(const QShader &lhs, const QShader &rhs)
Devuelve false si los valores de los dos objetos QShader lhs y rhs son iguales; en caso contrario devuelve true.
[noexcept] bool operator==(const QShader &lhs, const QShader &rhs)
Devuelve true si los dos objetos QShader lhs y rhs son iguales, lo que significa que son para la misma etapa con conjuntos coincidentes de código fuente shader o código binario.
© 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.
