En esta página

QShaderDescription Class

Describe la interfaz de un sombreador. Más...

Cabecera: #include <QShaderDescription>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
Desde: Qt 6.6

Tipos Públicos

(since 6.6) struct BlockVariable
(since 6.6) struct BuiltinVariable
(since 6.6) struct InOutVariable
(since 6.6) struct PushConstantBlock
(since 6.6) struct StorageBlock
(since 6.6) struct UniformBlock
enum BuiltinType { PositionBuiltin, PointSizeBuiltin, ClipDistanceBuiltin, CullDistanceBuiltin, VertexIdBuiltin, …, ViewIndexBuiltin }
enum ImageFlag { ReadOnlyImage, WriteOnlyImage }
flags ImageFlags
enum ImageFormat { ImageFormatUnknown, ImageFormatRgba32f, ImageFormatRgba16f, ImageFormatR32f, ImageFormatRgba8, …, ImageFormatR8ui }
enum QualifierFlag { QualifierReadOnly, QualifierWriteOnly, QualifierCoherent, QualifierVolatile, QualifierRestrict }
flags QualifierFlags
enum TessellationMode { UnknownTessellationMode, TrianglesTessellationMode, QuadTessellationMode, IsolineTessellationMode }
enum TessellationPartitioning { UnknownTessellationPartitioning, EqualTessellationPartitioning, FractionalEvenTessellationPartitioning, FractionalOddTessellationPartitioning }
enum TessellationWindingOrder { UnknownTessellationWindingOrder, CwTessellationWindingOrder, CcwTessellationWindingOrder }
enum VariableType { Unknown, Float, Vec2, Vec3, Vec4, …, Half4 }

Funciones Públicas

QShaderDescription()
QShaderDescription(const QShaderDescription &other)
~QShaderDescription()
QList<QShaderDescription::InOutVariable> combinedImageSamplers() const
std::array<uint, 3> computeShaderLocalSize() const
QList<QShaderDescription::BuiltinVariable> inputBuiltinVariables() const
QList<QShaderDescription::InOutVariable> inputVariables() const
bool isValid() const
QList<QShaderDescription::BuiltinVariable> outputBuiltinVariables() const
QList<QShaderDescription::InOutVariable> outputVariables() const
QList<QShaderDescription::PushConstantBlock> pushConstantBlocks() const
void serialize(QDataStream *stream, int version) const
QList<QShaderDescription::StorageBlock> storageBlocks() const
QList<QShaderDescription::InOutVariable> storageImages() const
QShaderDescription::TessellationMode tessellationMode() const
uint tessellationOutputVertexCount() const
QShaderDescription::TessellationPartitioning tessellationPartitioning() const
QShaderDescription::TessellationWindingOrder tessellationWindingOrder() const
QByteArray toJson() const
QList<QShaderDescription::UniformBlock> uniformBlocks() const
QShaderDescription &operator=(const QShaderDescription &other)

Miembros Públicos Estáticos

QShaderDescription deserialize(QDataStream *stream, int version)
bool operator==(const QShaderDescription &lhs, const QShaderDescription &rhs)

Descripción Detallada

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/qshaderdescription.h>.

Un sombreador suele tener un conjunto de entradas y salidas. Un sombreador de vértices, por ejemplo, tiene una serie de variables de entrada y puede utilizar uno o más buffers uniformes para acceder a los datos (por ejemplo, una matriz modelview) proporcionados por la aplicación. El sombreador de la etapa de fragmentos recibe datos de la etapa de vértices (en una configuración sencilla) y también puede basarse en datos de memorias intermedias uniformes, imágenes y muestreadores.

En lo que respecta a las entradas de vértices y la disposición de las memorias intermedias uniformes (¿cuáles son los nombres de los miembros?, ¿cuál es su tamaño, desplazamiento, etc.?), es posible que las aplicaciones y los frameworks necesiten descubrir esto dinámicamente en tiempo de ejecución. Esto es típico cuando el sombreador no está incorporado, sino que lo proporciona una entidad externa, como el usuario.

Es posible que las API de gráficos modernas y simplificadas ya no ofrezcan una forma de consultar la información de reflexión del sombreador en tiempo de ejecución. Por lo tanto, estos datos son ahora generados automáticamente por QShaderBaker y se proporcionan como un objeto QShaderDescription para todos y cada uno de los QShader.

Ejemplo

Tomemos el siguiente sombreador de vértices:

#version 440

layout(location = 0) in vec4 position;
layout(location = 1) in vec3 color;
layout(location = 0) out vec3 v_color;

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

void main()
{
    v_color = color;
    gl_Position = ubuf.mvp * position;
}

Este sombreador tiene dos entradas: position en la posición 0 con un tipo de vec4, y color en la posición 1 con un tipo de vec3. Tiene una salida: v_color, aunque esto no suele ser interesante para las aplicaciones. Lo que es más importante, hay un bloque uniforme en la posición 0 con un tamaño de 68 bytes y dos miembros, una matriz 4x4 llamada mvp en la posición 0, y un float opacity en la posición 64. Todo esto está descrito por un QShift.

Todo esto es descrito por un objeto QShaderDescription. QShaderDescription puede ser serializado a JSON y a un formato binario a través de QDataStream, y puede ser deserializado desde este formato binario. En la práctica esto es raramente necesario ya que QShader se encarga del QShaderDescription asociado automáticamente, pero si el QShaderDescription del shader anterior se escribiera como JSON (como se hace mediante la opción -d de la herramienta qsb ), tendría el siguiente aspecto:

{
    "inputs": [
        {
            "location": 1,
            "name": "color",
            "type": "vec3"
        },
        {
            "location": 0,
            "name": "position",
            "type": "vec4"
        }
    ],
    "outputs": [
        {
            "location": 0,
            "name": "v_color",
            "type": "vec3"
        }
    ],
    "uniformBlocks": [
        {
            "binding": 0,
            "blockName": "buf",
            "members": [
                {
                    "matrixStride": 16,
                    "name": "mvp",
                    "offset": 0,
                    "size": 64,
                    "type": "mat4"
                },
                {
                    "name": "opacity",
                    "offset": 64,
                    "size": 4,
                    "type": "float"
                }
            ],
            "set": 0,
            "size": 68,
            "structName": "ubuf"
        }
    ]
}

La API de C++ permite acceder a una estructura de datos como la anterior. Para simplificar, los structs internos sólo contienen miembros de datos públicos, considerando también que es poco probable que su disposición cambie en el futuro.

Véase también QShaderBaker y QShader.

Documentación de tipos de miembros

enum QShaderDescription::BuiltinType

Tipo de variable incorporada.

ConstanteValor
QShaderDescription::PositionBuiltin0
QShaderDescription::PointSizeBuiltin1
QShaderDescription::ClipDistanceBuiltin3
QShaderDescription::CullDistanceBuiltin4
QShaderDescription::VertexIdBuiltin5
QShaderDescription::InstanceIdBuiltin6
QShaderDescription::PrimitiveIdBuiltin7
QShaderDescription::InvocationIdBuiltin8
QShaderDescription::LayerBuiltin9
QShaderDescription::ViewportIndexBuiltin10
QShaderDescription::TessLevelOuterBuiltin11
QShaderDescription::TessLevelInnerBuiltin12
QShaderDescription::TessCoordBuiltin13
QShaderDescription::PatchVerticesBuiltin14
QShaderDescription::FragCoordBuiltin15
QShaderDescription::PointCoordBuiltin16
QShaderDescription::FrontFacingBuiltin17
QShaderDescription::SampleIdBuiltin18
QShaderDescription::SamplePositionBuiltin19
QShaderDescription::SampleMaskBuiltin20
QShaderDescription::FragDepthBuiltin22
QShaderDescription::NumWorkGroupsBuiltin24
QShaderDescription::WorkgroupSizeBuiltin25
QShaderDescription::WorkgroupIdBuiltin26
QShaderDescription::LocalInvocationIdBuiltin27
QShaderDescription::GlobalInvocationIdBuiltin28
QShaderDescription::LocalInvocationIndexBuiltin29
QShaderDescription::VertexIndexBuiltin42
QShaderDescription::InstanceIndexBuiltin43
QShaderDescription::ViewIndexBuiltin4440

enum QShaderDescription::ImageFlag
flags QShaderDescription::ImageFlags

Banderas de imagen.

ConstanteValor
QShaderDescription::ReadOnlyImage1 << 0
QShaderDescription::WriteOnlyImage1 << 1

El tipo ImageFlags es un typedef para QFlags<ImageFlag>. Almacena una combinación OR de valores ImageFlag.

enum QShaderDescription::ImageFormat

Formato de imagen.

ConstanteValor
QShaderDescription::ImageFormatUnknown0
QShaderDescription::ImageFormatRgba32f1
QShaderDescription::ImageFormatRgba16f2
QShaderDescription::ImageFormatR32f3
QShaderDescription::ImageFormatRgba84
QShaderDescription::ImageFormatRgba8Snorm5
QShaderDescription::ImageFormatRg32f6
QShaderDescription::ImageFormatRg16f7
QShaderDescription::ImageFormatR11fG11fB10f8
QShaderDescription::ImageFormatR16f9
QShaderDescription::ImageFormatRgba1610
QShaderDescription::ImageFormatRgb10A211
QShaderDescription::ImageFormatRg1612
QShaderDescription::ImageFormatRg813
QShaderDescription::ImageFormatR1614
QShaderDescription::ImageFormatR815
QShaderDescription::ImageFormatRgba16Snorm16
QShaderDescription::ImageFormatRg16Snorm17
QShaderDescription::ImageFormatRg8Snorm18
QShaderDescription::ImageFormatR16Snorm19
QShaderDescription::ImageFormatR8Snorm20
QShaderDescription::ImageFormatRgba32i21
QShaderDescription::ImageFormatRgba16i22
QShaderDescription::ImageFormatRgba8i23
QShaderDescription::ImageFormatR32i24
QShaderDescription::ImageFormatRg32i25
QShaderDescription::ImageFormatRg16i26
QShaderDescription::ImageFormatRg8i27
QShaderDescription::ImageFormatR16i28
QShaderDescription::ImageFormatR8i29
QShaderDescription::ImageFormatRgba32ui30
QShaderDescription::ImageFormatRgba16ui31
QShaderDescription::ImageFormatRgba8ui32
QShaderDescription::ImageFormatR32ui33
QShaderDescription::ImageFormatRgb10a2ui34
QShaderDescription::ImageFormatRg32ui35
QShaderDescription::ImageFormatRg16ui36
QShaderDescription::ImageFormatRg8ui37
QShaderDescription::ImageFormatR16ui38
QShaderDescription::ImageFormatR8ui39

enum QShaderDescription::QualifierFlag
flags QShaderDescription::QualifierFlags

Banderas de los calificadores.

ConstanteValor
QShaderDescription::QualifierReadOnly1 << 0
QShaderDescription::QualifierWriteOnly1 << 1
QShaderDescription::QualifierCoherent1 << 2
QShaderDescription::QualifierVolatile1 << 3
QShaderDescription::QualifierRestrict1 << 4

El tipo QualifierFlags es un typedef para QFlags<QualifierFlag>. Almacena una combinación OR de valores QualifierFlag.

enum QShaderDescription::TessellationMode

ConstanteValor
QShaderDescription::UnknownTessellationMode0
QShaderDescription::TrianglesTessellationMode1
QShaderDescription::QuadTessellationMode2
QShaderDescription::IsolineTessellationMode3

enum QShaderDescription::TessellationPartitioning

ConstanteValor
QShaderDescription::UnknownTessellationPartitioning0
QShaderDescription::EqualTessellationPartitioning1
QShaderDescription::FractionalEvenTessellationPartitioning2
QShaderDescription::FractionalOddTessellationPartitioning3

enum QShaderDescription::TessellationWindingOrder

ConstanteValor
QShaderDescription::UnknownTessellationWindingOrder0
QShaderDescription::CwTessellationWindingOrder1
QShaderDescription::CcwTessellationWindingOrder2

enum QShaderDescription::VariableType

Representa el tipo de una variable o miembro de bloque.

ConstanteValorDescripción
QShaderDescription::Unknown0
QShaderDescription::Float1
QShaderDescription::Vec22
QShaderDescription::Vec33
QShaderDescription::Vec44
QShaderDescription::Mat25
QShaderDescription::Mat2x36
QShaderDescription::Mat2x47
QShaderDescription::Mat38
QShaderDescription::Mat3x29
QShaderDescription::Mat3x410
QShaderDescription::Mat411
QShaderDescription::Mat4x212
QShaderDescription::Mat4x313
QShaderDescription::Int14
QShaderDescription::Int215
QShaderDescription::Int316
QShaderDescription::Int417
QShaderDescription::Uint18
QShaderDescription::Uint219
QShaderDescription::Uint320
QShaderDescription::Uint421
QShaderDescription::Bool22
QShaderDescription::Bool223
QShaderDescription::Bool324
QShaderDescription::Bool425
QShaderDescription::Double26
QShaderDescription::Double227
QShaderDescription::Double328
QShaderDescription::Double429
QShaderDescription::DMat230
QShaderDescription::DMat2x331
QShaderDescription::DMat2x432
QShaderDescription::DMat333
QShaderDescription::DMat3x234
QShaderDescription::DMat3x435
QShaderDescription::DMat436
QShaderDescription::DMat4x237
QShaderDescription::DMat4x338
QShaderDescription::Sampler1D39
QShaderDescription::Sampler2D40
QShaderDescription::Sampler2DMS41
QShaderDescription::Sampler3D42
QShaderDescription::SamplerCube43
QShaderDescription::Sampler1DArray44
QShaderDescription::Sampler2DArray45
QShaderDescription::Sampler2DMSArray46
QShaderDescription::Sampler3DArray47
QShaderDescription::SamplerCubeArray48
QShaderDescription::SamplerRect49
QShaderDescription::SamplerBuffer50
QShaderDescription::SamplerExternalOES51
QShaderDescription::Sampler52Para muestreadores separados.
QShaderDescription::Image1D53
QShaderDescription::Image2D54
QShaderDescription::Image2DMS55
QShaderDescription::Image3D56
QShaderDescription::ImageCube57
QShaderDescription::Image1DArray58
QShaderDescription::Image2DArray59
QShaderDescription::Image2DMSArray60
QShaderDescription::Image3DArray61
QShaderDescription::ImageCubeArray62
QShaderDescription::ImageRect63
QShaderDescription::ImageBuffer64
QShaderDescription::Struct65
QShaderDescription::Half66
QShaderDescription::Half267
QShaderDescription::Half368
QShaderDescription::Half469

Documentación de la función miembro

QShaderDescription::QShaderDescription()

Construye un nuevo QShaderDescription vacío.

Nota: Estar vacío implica que isValid() devuelve false para la instancia recién construida.

QShaderDescription::QShaderDescription(const QShaderDescription &other)

Construye una copia de other.

[noexcept] QShaderDescription::~QShaderDescription()

Destructor.

QList<QShaderDescription::InOutVariable> QShaderDescription::combinedImageSamplers() const

Devuelve la lista de muestreadores de imagen combinados

Con shaders GLSL/Vulkan como fuente un uniforme layout(binding = 1) uniform sampler2D tex; genera lo siguiente: (mostrado como JSON textual aquí)

"combinedImageSamplers": [
     {
         "binding": 1,
         "name": "tex",
         "set": 0,
         "type": "sampler2D"
     }
 ]

Esto no significa que las versiones de otros lenguajes del shader deban utilizar también un muestreador de imágenes combinado, sobre todo teniendo en cuenta que el concepto puede no existir en todas partes. Por ejemplo, una versión HLSL probablemente sólo utilizará un objeto Texture2D y SamplerState con los registros t1 y s1, respectivamente.

std::array<uint, 3> QShaderDescription::computeShaderLocalSize() const

Devuelve el tamaño local de un sombreador de cálculo.

Por ejemplo, para un sombreador de cálculo con la siguiente declaración, la función devuelve { 256, 16, 1}.

layout(local_size_x = 256, local_size_y = 16, local_size_z = 1) in;

[static] QShaderDescription QShaderDescription::deserialize(QDataStream *stream, int version)

Devuelve un nuevo QShaderDescription cargado desde stream. version especifica la versión qsb.

Véase también serialize().

QList<QShaderDescription::BuiltinVariable> QShaderDescription::inputBuiltinVariables() const

Devuelve la lista de builtins activos utilizados como entrada. Por ejemplo, un shader de evaluación de teselación que lea el valor de gl_TessCoord y gl_Position tendrá TessCoordBuiltin y PositionBuiltin listados aquí.

QList<QShaderDescription::InOutVariable> QShaderDescription::inputVariables() const

Devuelve la lista de variables de entrada. Esto incluye entradas de vértice (a veces llamadas atributos) para la etapa de vértice, y entradas para otras etapas (a veces llamadas variantes).

bool QShaderDescription::isValid() const

Devuelve true si QShaderDescription contiene al menos una entrada en una de las listas de variables y bloques.

QList<QShaderDescription::BuiltinVariable> QShaderDescription::outputBuiltinVariables() const

Devuelve la lista de variables incorporadas activas utilizadas como entrada. Por ejemplo, un sombreador de vértices tendrá muy a menudo PositionBuiltin como salida incorporada.

QList<QShaderDescription::InOutVariable> QShaderDescription::outputVariables() const

Devuelve la lista de variables de salida.

QList<QShaderDescription::PushConstantBlock> QShaderDescription::pushConstantBlocks() const

Devuelve la lista de bloques de constantes push.

Nota: Evite depender de bloques constantes de empuje para shaders que se van a utilizar en combinación con la Interfaz de Hardware de Renderizado de Qt, ya que actualmente no tiene soporte para ellos.

void QShaderDescription::serialize(QDataStream *stream, int version) const

Serializa este QShaderDescription a stream. version especifica la versión qsb.

Véase también deserialize() y toJson().

QList<QShaderDescription::StorageBlock> QShaderDescription::storageBlocks() const

Devuelve la lista de bloques de almacenamiento de shaders.

Por ejemplo, con shaders GLSL/Vulkan como fuente, la declaración

struct Stuff {
    vec2 a;
    vec2 b;
};
layout(std140, binding = 0) buffer StuffSsbo {
    vec4 whatever;
    Stuff stuff[];
} buf;

genera lo siguiente: (mostrado como JSON textual aquí)

"storageBlocks": [ {
    "binding": 0,
    "blockName": "StuffSsbo",
    "instanceName": "buf",
    "knownSize": 16,
    "runtimeArrayStride": 16
    "members": [
        {
            "name": "whatever",
            "offset": 0,
            "size": 16,
            "type": "vec4"
        },
        {
            "arrayDims": [
                0
            ],
            "name": "stuff",
            "offset": 16,
            "size": 0,
            "structMembers": [
                {
                    "name": "a",
                    "offset": 0,
                    "size": 8,
                    "type": "vec2"
                },
                {
                    "name": "b",
                    "offset": 8,
                    "size": 8,
                    "type": "vec2"
                }
            ],
            "type": "struct"
        }
    ],
    "set": 0
} ]

Nota: El tamaño del último miembro del bloque de almacenamiento es indefinido. Esto se muestra como size 0 y una dimensión de array de [0]. El bloque de almacenamiento knownSize excluye el tamaño del último miembro ya que sólo se conocerá en tiempo de ejecución. El intervalo en bytes entre los elementos del array para un último miembro con un tamaño de array indefinido es runtimeArrayStride. Este valor se determina según las reglas del estándar de disposición de memoria intermedia (std140, std430).

Nota: Los SSBO no están disponibles con algunas API gráficas, como OpenGL 2.x u OpenGL ES anteriores a 3.1.

QList<QShaderDescription::InOutVariable> QShaderDescription::storageImages() const

Devuelve la lista de variables de imagen.

Éstas aparecerán probablemente en los sombreadores de cálculo. Por ejemplo, layout (binding = 0, rgba8) uniform readonly image2D inputImage; genera lo siguiente: (mostrado como JSON textual aquí)

"storageImages": [
     {
         "binding": 0,
         "imageFormat": "rgba8",
         "name": "inputImage",
         "set": 0,
         "type": "image2D"
     }
 ]

Nota: Los objetos de imagen separados no son compatibles con algunas API gráficas, como OpenGL 2.x u OpenGL ES anteriores a 3.1.

QShaderDescription::TessellationMode QShaderDescription::tessellationMode() const

Devuelve el modo de ejecución de la teselación para un control de teselación o un sombreador de evaluación.

Si no se establece, el valor devuelto es UnknownTessellationMode.

Por ejemplo, para un sombreador de evaluación de teselación con la siguiente declaración, la función devuelve TrianglesTessellationMode.

layout(triangles) in;

uint QShaderDescription::tessellationOutputVertexCount() const

Devuelve el número de vértices de salida.

Por ejemplo, para un shader de control de teselación con la siguiente declaración, la función devuelve 3.

layout(vertices = 3) out;

QShaderDescription::TessellationPartitioning QShaderDescription::tessellationPartitioning() const

Devuelve el modo de partición de teselación para un control de teselación o un sombreador de evaluación.

Si no se establece, el valor devuelto es UnknownTessellationPartitioning.

Por ejemplo, para un sombreador de evaluación de teselación con la siguiente declaración, la función devuelve FractionalOddTessellationPartitioning.

layout(triangles, fractional_odd_spacing, ccw) in;

QShaderDescription::TessellationWindingOrder QShaderDescription::tessellationWindingOrder() const

Devuelve el orden de teselación para un control de teselación o un sombreador de evaluación.

Si no se establece, el valor devuelto es UnknownTessellationWindingOrder.

Por ejemplo, para un sombreador de evaluación de teselación con la siguiente declaración, la función devuelve CcwTessellationWindingOrder.

layout(triangles, fractional_odd_spacing, ccw) in;

QByteArray QShaderDescription::toJson() const

Devuelve una versión de texto JSON serializada de los datos.

Nota: No se proporciona ningún método de deserialización para el texto JSON.

Véase también serialize().

QList<QShaderDescription::UniformBlock> QShaderDescription::uniformBlocks() const

Devuelve la lista de bloques uniformes.

QShaderDescription &QShaderDescription::operator=(const QShaderDescription &other)

Asigna other a este objeto.

No miembros relacionados

[noexcept] bool operator==(const QShaderDescription &lhs, const QShaderDescription &rhs)

Devuelve true si los dos objetos QShaderDescription lhs y rhs son iguales.

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