En esta página

QShaderDescription Class

Describe la interfaz de un shader. Más información...

Encabezado: #include <qshaderdescription.h>
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 » 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 que los cambios que impliquen incompatibilidad a nivel de código fuente se reduzcan al mínimo y 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/qshaderdescription.h>.

Un shader suele tener un conjunto de entradas y salidas. Un shader de vértices, por ejemplo, tiene varias variables de entrada y puede utilizar uno o más búferes 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 procedentes de búferes uniformes, imágenes y muestreadores.

En lo que respecta a las entradas de vértices y a la estructura de los búferes uniformes (¿cuáles son los nombres de los miembros? ¿cuál es su tamaño, desplazamiento, etc.?), es posible que las aplicaciones y los marcos de trabajo tengan que descubrir esta información de forma dinámica en tiempo de ejecución. Esto suele ocurrir cuando el sombreador no está integrado, sino que lo proporciona una entidad externa, como el usuario.

Es posible que las API gráficas modernas y optimizadas ya no ofrezcan una forma de consultar la información de reflexión del sombreador en tiempo de ejecución. Por lo tanto, dichos datos ahora los genera automáticamente QShaderBaker y se proporcionan como un objeto `QShaderDescription` para cada uno de los ` QShader`.

Ejemplo

Consideremos 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, de tipo « vec4 », y « color » en la posición 1, de tipo « vec3 ». Tiene una salida: « v_color », aunque esto no suele ser relevante para las aplicaciones. Lo que es más importante, hay un bloque uniforme en el enlace 0 con un tamaño de 68 bytes y dos miembros: una matriz de 4x4 denominada mvp en el desplazamiento 0, y un valor de tipo float opacity en el desplazamiento 64.

Todo esto se describe mediante un objeto `QShaderDescription`. `QShaderDescription` se puede serializar a JSON y a un formato binario mediante QDataStream, y se puede deserializar a partir de este formato binario. En la práctica, esto rara vez es necesario, ya que QShader se encarga automáticamente del QShaderDescription asociado, pero si el QShaderDescription del shader anterior se escribiera como JSON (tal y como lo hace 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, las estructuras internas solo contienen miembros de datos públicos, teniendo en cuenta además que es poco probable que su disposición cambie en el futuro.

Véase también QShaderBaker y QShader.

Documentación sobre los tipos de los 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

Indicadores de imagen.

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

El tipo ImageFlags es una definición de tipo (typedef) para QFlags<ImageFlag>. Almacena una combinación OR de valores de 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

Indicadores de calificación.

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

El tipo QualifierFlags es una definición de tipo (typedef) para QFlags<QualifierFlag>. Almacena una combinación OR de valores de 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 de un 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 independientes.
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 las funciones de miembro

QShaderDescription::QShaderDescription()

Crea un nuevo objeto QShaderDescription vacío.

Nota: El hecho de que esté vacío implica que la función « isValid()» devuelve « false » para la instancia recién creada.

QShaderDescription::QShaderDescription(const QShaderDescription &other)

Crea una copia de other.

[noexcept] QShaderDescription::~QShaderDescription()

Destructor.

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

Devuelve la lista de muestreadores de imagen combinados

Con los shaders GLSL/Vulkan como fuente, un uniforme « layout(binding = 1) uniform sampler2D tex; » genera lo siguiente: (se muestra aquí como texto JSON)

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

Esto no significa que las versiones del sombreador en otros lenguajes también deban utilizar un muestreador de imagen combinado, sobre todo teniendo en cuenta que es posible que este concepto no exista en todos ellos. Por ejemplo, es probable que una versión en HLSL utilice simplemente un objeto `Texture2D` y un objeto `SamplerState` con los registros `t1` y `s1`, respectivamente.

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

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

Por ejemplo, para un shader 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 objeto ` QShaderDescription ` cargado desde stream. ` version ` especifica la versión de qsb.

Véase también serialize().

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

Devuelve la lista de funciones integradas activas utilizadas como entrada. Por ejemplo, un shader de evaluación de teselación que lea los valores de gl_TessCoord y gl_Position mostrará aquí las entradas « TessCoordBuiltin » y « PositionBuiltin ».

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

Devuelve la lista de variables de entrada. Esta incluye las entradas de vértices (a veces denominadas «atributos») para la etapa de vértices, así como las entradas para otras etapas (a veces denominadas «variables»).

bool QShaderDescription::isValid() const

Devuelve «true» si el objeto ` QShaderDescription ` contiene al menos una entrada en una de las listas de variables o de bloques.

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

Devuelve la lista de variables integradas activas que se utilizan como entrada. Por ejemplo, un sombreador de vértices suele tener la variabl PositionBuiltin como variable integrada de salida.

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: Evita recurrir a bloques de constantes «push» en los shaders que se vayan a utilizar junto con la interfaz de renderizado por hardware de Qt, ya que actualmente esta no los admite.

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

Serializa este QShaderDescription a stream. version especifica la versión de 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: (aquí se muestra como texto JSON)

"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 no está definido. Esto se muestra como un « size » de 0 y una dimensión de matriz de « [0] ». El « knownSize » del bloque de almacenamiento excluye el tamaño del último miembro, ya que este solo se conocerá en tiempo de ejecución. El paso en bytes entre los elementos de la matriz para un último miembro con un tamaño de matriz indefinido es runtimeArrayStride. Este valor se determina según las reglas especificadas en las normas de disposición de la memoria del búfer (std140, std430).

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

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

Devuelve la lista de variables de imagen.

Es probable que estas aparezcan en los shaders de cálculo. Por ejemplo, layout (binding = 0, rgba8) uniform readonly image2D inputImage; genera lo siguiente: (aquí se muestra como texto JSON)

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

Nota: Los objetos de imagenindependientes no son compatibles con algunas API gráficas, como OpenGL 2.x u OpenGL ES anterior a la versión 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 shader de evaluación.

Si no se especifica, el valor devuelto es ` UnknownTessellationMode`.

Por ejemplo, para un shader 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 sombreador 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 shader de evaluación.

Si no se especifica, 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 enrollamiento de la teselación para un control de teselación o un shader de evaluación.

Si no se especifica, el valor devuelto es UnknownTessellationWindingOrder.

Por ejemplo, para un shader 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: Nose 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.

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