QShader Class
Contiene varias versiones de un sombreador traducidas a distintos lenguajes de sombreado, junto con metadatos de reflexión. Más...
| Encabezado: | #include <qshader.h> |
| 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, incluidos los heredados
- QShader forma parte de «Renderizado en 3D » y «Clases compartidas implícitamente».
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) |
Elementos 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 de shaders en el mundo Qt, independiente de la API gráfica. En lugar de utilizar fuentes de shaders GLSL, como era habitual en Qt 5.x, los nuevos sistemas gráficos con backends para múltiples API gráficas, como Vulkan, Metal, Direct3D y OpenGL, utilizan QShader como entrada siempre que es necesario especificar un shader.
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/qshader.h>.
Una instancia de QShader está vacía y, por lo tanto, no es válida por defecto. Para obtener una instancia útil, los dos métodos habituales son:
- Generar el contenido sin conexión, durante la compilación o antes, utilizando la herramienta de línea de comandos
qsb. El resultado es un archivo binario que se distribuye junto con la aplicación, se lee mediante QIODevice::readAll() y, a continuación, se deserializa mediante fromSerialized(). Para obtener más información, consulta QShaderBaker. - Generar en tiempo de ejecución mediante ` QShaderBaker`. Se trata de una operación costosa, pero permite a las aplicaciones utilizar cadenas de código fuente de shaders proporcionadas por el usuario o generadas dinámicamente.
Cuando se utiliza junto con la interfaz de hardware de renderizado de Qt y sus clases, como QRhiGraphicsPipeline, no se requiere ninguna acción adicional por parte de la aplicación, ya que estas clases están preparadas para utilizar un QShader siempre que sea necesario especificar un sombreador para una etapa determinada de la cadena de procesamiento de gráficos.
Como alternativa, las aplicaciones pueden acceder
- al código fuente o al código de bytes de cualquiera de las versiones del lenguaje de sombreado incluidas 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 resulta esencial cuando una aplicación o un marco de trabajo necesita descubrir las entradas de un sombreador en tiempo de ejecución, al no disponer de información previa sobre los atributos de vértice o la disposición de los búferes uniformes utilizados por el sombreador.
QShader no hace ninguna suposición sobre el lenguaje de sombreado que se utilizó como fuente para generar las diversas versiones y variantes que incluye.
QShader utiliza el uso compartido implícito de forma similar a muchos tipos básicos de Qt Core, por lo que puede devolverse o pasarse por valor. La desconexión se produce de forma implícita al llamar a un setter.
A modo de referencia, un « QRhi » típico y portátil espera que un QShader adecuado para todos sus backends contenga, como mínimo, lo siguiente. (Esto excluye la compatibilidad con contextos OpenGL de perfil básico; para ello, añade GLSL 150 o una versión posterior).
- Código de bytes SPIR-V 1.0 compatible con Vulkan 1.0 o posterior
- Código fuente GLSL/ES 100 compatible con OpenGL ES 2.0 o posterior
- Código fuente GLSL 120 compatible con OpenGL 2.1 o posterior
- Código fuente HLSL Shader Model 5.0 o el código byte DXBC correspondiente, compatible con Direct3D 11/12
- Código fuente de Metal Shading Language 1.2 o el código byte correspondiente, compatible con Metal 1.2 o posterior
Véase también QShaderBaker.
Documentación sobre tipos de miembros
[alias] QShader::NativeResourceBindingMap
Sinónimo de QMap<int, std::pair<int, int>>.
El modelo de enlace 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 imagen 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 disposición binding en el sombreador GLSL compatible con Vulkan.
Las API gráficas distintas de Vulkan pueden utilizar un modelo de enlace de recursos que no sea totalmente compatible con este. El generador del código de shader traducido desde SPIR-V puede optar por no tener en cuenta los calificadores de enlace de SPIR-V, por diversas razones. Este es el caso, por ejemplo, del backend Metal de SPIRV-Cross. Además, aunque en la mayoría de los casos sea posible una traducción automática e implícita (por ejemplo, utilizando los puntos de enlace de SPIR-V como índices de los registros de recursos HLSL), asignar enlaces de recursos sin estar limitado por los puntos de enlace de SPIR-V puede dar lugar a mejores resultados.
Por lo tanto, un « 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, ya que los muestreadores de imagen combinados pueden asignarse a dos recursos nativos (una textura y un muestreador) en algunos lenguajes de sombreado. En ese caso, el segundo valor hace referencia al muestreador.
Nota: El enlace nativo puede ser -1, en caso de que no haya ningún 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). La asignación siempre está completa, lo que significa que hay una entrada para todos los bloques uniformes, bloques de almacenamiento, objetos de imagen y muestreadores combinados declarados, pero el valor será -1 para aquellos a los que no se haga referencia efectiva 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 el ` QShader`.
El valor por defecto del argumento « version » de la función « serialized()» es « Latest ». Esto es suficiente en la gran mayoría de los casos. Solo es necesario especificar otro valor cuando se pretende generar datos serializados que puedan cargarse en versiones anteriores de Qt. Por ejemplo, la herramienta « qsb » utiliza estos valores de enumeración cuando se proporciona el argumento de línea de comandos « --qsbversion ».
Nota: Si se elige como destino una versión anterior, algunas funciones dejarán de funcionar correctamente con el recurso generado. Esto no supone ningún problema al utilizar el recurso con la versión anterior de Qt especificada, siempre que dicha versión no cuente con las nuevas características de las versiones más recientes de Qt que dependen de datos adicionales generados en el « QShader » y en el flujo de datos serializados; sin embargo, puede convertirse en un problema si el recurso generado se utiliza posteriormente 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 shader contiene una entrada.
| Constante | Valor | Descripción |
|---|---|---|
QShader::SpirvShader | 0 | SPIR-V |
QShader::GlslShader | 1 | GLSL |
QShader::HlslShader | 2 | HLSL |
QShader::DxbcShader | 3 | Código byte de Direct3D (HLSL compilado por fxc) |
QShader::MslShader | 4 | Lenguaje de sombreado Metal |
QShader::DxilShader | 5 | Bytecode de Direct3D (HLSL compilado por dxc) |
QShader::MetalLibShader | 6 | Bytecode de Metal precompilado |
QShader::WgslShader | 7 | WGSL |
enum QShader::Stage
Describe la etapa del proceso de renderizado para la que es adecuado el shader.
| Constante | Valor | Descripción |
|---|---|---|
QShader::VertexStage | 0 | Shader de vértices |
QShader::TessellationControlStage | 1 | Shader 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 shader contiene una entrada.
| Constante | Valor | Descripción |
|---|---|---|
QShader::StandardShader | 0 | La versión normal, sin modificar, del código del sombreador. |
QShader::BatchableVertexShader | 1 | Sombreador de vértices reescrito para que sea compatible con el procesamiento por lotes del grafo de escena de « Qt Quick ». |
QShader::UInt16IndexedVertexAsComputeShader | 2 | Un sombreador de vértices diseñado para utilizarse en un canal de procesamiento Metal con teselación, en combinación con llamadas de dibujo indexadas que obtienen los datos de índice de un búfer de índices uint16. Para dar soporte al pipeline de teselación de Metal, el sombreador de vértices se traduce a un sombreador de cálculo que puede depender del uso del búfer de índices en las llamadas de dibujo (por ejemplo, si el sombreador utiliza gl_VertexIndex); de ahí la necesidad de tres variantes específicas. |
QShader::UInt32IndexedVertexAsComputeShader | 3 | Un sombreador de vértices diseñado para utilizarse en un flujo de trabajo de Metal con teselación, en combinación con llamadas de dibujo indexadas que obtienen los 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 traduce a un sombreador de cálculo que puede depender del uso del búfer de índices en las llamadas de dibujo (por ejemplo, si el sombreador utiliza gl_VertexIndex), de ahí la necesidad de tres variantes específicas. |
QShader::NonIndexedVertexAsComputeShader | 4 | Un sombreador de vértices diseñado para utilizarse en un pipeline de Metal con teselación en combinación con llamadas de dibujo no indexadas. Para admitir el canal de teselación de Metal, el sombreador de vértices se traduce a un sombreador de cálculo que puede depender del uso del búfer de índices en las llamadas de dibujo (por ejemplo, si el sombreador utiliza gl_VertexIndex), de ahí la necesidad de tres variantes específicas. |
QShader::HdrCapableFragmentShader (since Qt 6.10) | 5 | Un sombreador de fragmentos reescrito para admitir el renderizado de alto rango dinámico en un grafo de escena de « Qt Quick ». |
Documentación de las funciones miembro
QShader::QShader()
Crea una nueva instancia de QShader vacía (y, por lo tanto, no válida).
QShader::QShader(const QShader &other)
Crea una copia de other.
[noexcept, since 6.7] QShader::QShader(QShader &&other)
Crea un nuevo QShader a partir de other.
Nota: El objeto del que se ha realizado el movimiento, ` other `, queda 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 shader disponibles
QShaderDescription QShader::description() const
Devuelve los metadatos de reflexión del shader.
Véase también setDescription().
[static] QShader QShader::fromSerialized(const QByteArray &data)
Crea una nueva instancia de ` QShader ` a partir del objeto ` data` proporcionado.
Si no se puede deserializar correctamente data, el resultado es un QShader construido por defecto para el que isValid() devuelve false.
Advertencia: Se considera que los paquetesde shaders , incluidos los archivos .qsb del sistema de archivos, son contenido de confianza. Se recomienda a los desarrolladores de aplicaciones que evalúen cuidadosamente las posibles implicaciones 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 el objeto ` QShader ` contiene al menos una versión de shader.
QShader::NativeResourceBindingMap QShader::nativeResourceBindingMap(const QShaderKey &key) const
Devuelve el mapa de enlace nativo para key. El mapa está vacío si no hay ninguna correspondencia disponible para key (por ejemplo, porque el mapa no es aplicable a la API y al lenguaje de sombreado descritos en key).
QShader::NativeShaderInfo QShader::nativeShaderInfo(const QShaderKey &key) const
Devuelve la estructura de información del shader nativo para key, o un objeto vacío si no hay datos disponibles para key, por ejemplo, porque dicha asignación no es aplicable al lenguaje de sombreado o a la etapa del shader.
Véase también setNativeShaderInfo().
void QShader::removeNativeShaderInfo(const QShaderKey &key)
Elimina la información del shader nativo de « key ».
void QShader::removeResourceBindingMap(const QShaderKey &key)
Elimina el mapa de vinculación de recursos nativos de 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 el código binario del shader correspondiente a un ` key` determinado. No realiza ninguna acción si no lo encuentra.
QShader::SeparateToCombinedImageSamplerMappingList QShader::separateToCombinedImageSamplerMappingList(const QShaderKey &key) const
Devuelve la lista combinada de asignaciones del muestreador de imágenes para key, o una lista vacía si no hay datos disponibles para key, por ejemplo, porque dicha asignación no es aplicable al 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 que contiene el objeto ` QShader`, adecuada para escribir en archivos u otros dispositivos de E/S.
Por defecto, se utiliza el formato de serialización más reciente. Utiliza el parámetro version para serializar para una versión de Qt compatible. Solo cuando se sepa que el flujo de datos generado debe ser compatible con una versión anterior de Qt, aun a costa de que resulte incompatible con las características introducidas desde esa versión de Qt, se debe utilizar 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 a key.
Véase también nativeShaderInfo().
void QShader::setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map)
Almacena el enlace de recurso nativo especificado 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 el código binario shader correspondiente a una versión determinada del shader, especificada mediante key.
Véase también ` shader()`.
void QShader::setStage(QShader::Stage stage)
Establece el canal de datos stage.
Véase también stage().
QShaderCode QShader::shader(const QShaderKey &key) const
Devuelve el código fuente o el código binario de una versión de shader determinada, especificada mediante ` key`.
Véase también setShader().
QShader::Stage QShader::stage() const
Devuelve la etapa del pipeline a la que está destinado el shader.
Véase también setStage().
[noexcept, since 6.7] void QShader::swap(QShader &other)
Sustituye este shader por 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)
La operación «move-assigns» asigna other a esta instancia de QShader.
Nota: El objeto del que se realiza el traslado, other, pasa a 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.
Elementos no miembros relacionados
[noexcept] size_t qHash(const QShader &key, size_t seed = 0)
Devuelve el valor hash de key, utilizando seed como semilla para 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 de tipo « QShader », « lhs » y « rhs », son iguales, lo que significa que corresponden a la misma etapa y tienen conjuntos coincidentes de código fuente o binario de shader.
© 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.