En esta página

Manual de QSB

qsb es una herramienta de línea de comandos proporcionada por el módulo Qt Shader Tools. Integra bibliotecas de terceros, como glslang y SPIRV-Cross; invoca opcionalmente herramientas externas, como fxc o spirv-opt; y genera archivos .qsb. Además, se puede utilizar para inspeccionar el contenido de un paquete .qsb.

Usage: qsb [options] file
Qt Shader Baker (using QShader from Qt 6.10.0)

Options:
  -?, -h, --help               Displays help on commandline options.
  --help-all                   Displays help, including generic Qt options.
  -v, --version                Displays version information.
  -b, --batchable              Also generates rewritten vertex shader for Qt
                               Quick scene graph batching.
  --zorder-loc <location>      The extra vertex input location when rewriting
                               for batching. Defaults to 7.
  --glsl <versions>            Comma separated list of GLSL versions to
                               generate. (for example, "100 es,120,330")
  --hlsl <versions>            Comma separated list of HLSL (Shader Model)
                               versions to generate. F.ex. 50 is 5.0, 51 is 5.1.
  --msl <versions>             Comma separated list of Metal Shading Language
                               versions to generate. F.ex. 12 is 1.2, 20 is 2.0.
  --qt6                        Equivalent to --glsl "100 es,120,150" --hlsl 50
                               --msl 12. This set is commonly used with shaders
                               for Qt Quick materials and effects.
  --msltess                    Indicates that a vertex shader is going to be
                               used in a pipeline with tessellation. Mandatory
                               for vertex shaders planned to be used with
                               tessellation when targeting Metal (--msl).
  --tess-vertex-count <count>  The output vertex count from the tessellation
                               control stage. Mandatory for tessellation
                               evaluation shaders planned to be used with Metal.
                               The default value is 3. If it does not match the
                               tess.control stage, the generated MSL code will
                               not function as expected.
  --tess-mode <mode>           The tessellation mode: triangles or quads.
                               Mandatory for tessellation control shaders
                               planned to be used with Metal. The default value
                               is triangles. Isolines are not supported with
                               Metal. If it does not match the tess.evaluation
                               stage, the generated MSL code will not function
                               as expected.
  --view-count <num_views>     The number of views the shader is used with.
                               num_views must be >= 2. Mandatory when multiview
                               rendering is used (gl_ViewIndex). Set only for
                               vertex shaders that really do rely on multiview
                               (as the resulting asset is tied to num_views).
                               Can be set for fragment shaders too, to get
                               QSHADER_VIEW_COUNT auto-defined. (useful for
                               ensuring uniform buffer layouts)
  -g                           Generate full debug info for SPIR-V and DXBC
  -O                           Invoke spirv-opt (external tool) to optimize
                               SPIR-V for performance.
  -o, --output <filename>      Output file for the shader pack.
  --orig-file <filename>       Filename to be be used for dependency tracking
                               instead of <file>.
  --qsbversion <version>       QSB version to use for the output file. By
                               default the latest version is automatically used,
                               use only to bake compatibility versions. F.ex. 64
                               is Qt 6.4.
  -c, --fxc                    In combination with --hlsl invokes fxc (SM
                               5.0/5.1) or dxc (SM 6.0+) to store DXBC or DXIL
                               instead of HLSL.
  -t, --metallib               In combination with --msl builds a Metal library
                               with xcrun metal(lib) and stores that instead of
                               the source. Suitable only when targeting macOS,
                               not iOS.
  -T, --metallib-ios           In combination with --msl builds a Metal library
                               with xcrun metal(lib) and stores that instead of
                               the source. Suitable only when targeting iOS, not
                               macOS.
  -D, --define <name[=value]>  Define macro. This argument can be specified
                               multiple times.
  -p, --per-target             Enable per-target compilation. (instead of
                               source->SPIRV->targets, do source->SPIRV->target
                               separately for each target)
  -d, --dump                   Switches to dump mode. Input file is expected to
                               be a shader pack.
  -x, --extract <what>         Switches to extract mode. Input file is expected
                               to be a shader pack. Result is written to the
                               output specified by -o. Pass -b to choose the
                               batchable variant.
                               <what>=reflect|spirv,<version>|glsl,<version>|...
  -r, --replace <what>         Switches to replace mode. Replaces the specified
                               shader in the shader pack with the contents of a
                               file. This argument can be specified multiple
                               times. Pass -b to choose the batchable variant.
                               Also supports adding a shader for a
                               target/variant that was not present before.
                               <what>=<target>,<filename> where
                               <target>=spirv,<version>|glsl,<version>|...
  -e, --erase <what>           Switches to erase mode. Removes the specified
                               shader from the shader pack. Pass -b to choose
                               the batchable variant.
                               <what>=spirv,<version>|glsl,<version>|...
  -s, --silent                 Enables silent mode. Only fatal errors will be
                               printed.
  --mediump                    Default to medium precision for floats in
                               fragment shaders instead of high. GLSL ES only;
                               ignored for everything else, including GLSL.
  --depfile <depfile>          Enables generating the depfile for the input
                               shaders, using the #include statements.

Arguments:
  file                         Vulkan GLSL source file to compile. The file
                               extension determines the shader stage, and can be
                               one of .vert, .tesc, .tese, .geom, .frag, .comp.
                               Note: Tessellation control/evaluation is not
                               supported with HLSL, instead use -r to inject
                               handcrafted hull/domain shaders. Some targets may
                               need special arguments to be set, e.g. MSL
                               tessellation will likely need --msltess,
                               --tess-vertex-count, --tess-mode, depending on
                               the stage. Geometry shaders are not supported
                               with Metal.

Modos de funcionamiento

Existen cinco modos principales de funcionamiento:

  • .qsb generación de archivos.
  • .qsb Inspección de archivos. Por ejemplo, qsb -d myshader.frag.qsb mostrará los metadatos de reflexión (en formato JSON) y los shaders incluidos.
  • Modo de extracción. Permite escribir un shader determinado de un archivo « .qsb » existente en un archivo independiente. Por ejemplo, « qsb -x spirv,100 -o myshader.spv myshader.frag.qsb » escribe el binario SPIR-V en « myshader.spv ».
  • Modo «Reemplazar». Permite sustituir el contenido de uno o varios shaders del archivo .qsb por el contenido leído de los archivos especificados. De esta forma, se puede inyectar código de shader creado manualmente en el paquete .qsb.
  • Modo «Borrar». Elimina la variante de shader especificada del archivo .qsb.

Ejemplo

Tomemos el siguiente shader de fragmentos:

#version 440

layout(location = 0) in vec2 v_texcoord;
layout(location = 0) out vec4 fragColor;
layout(binding = 1) uniform sampler2D tex;

layout(std140, binding = 0) uniform buf {
    float uAlpha;
};

void main()
{
    vec4 c = texture(tex, v_texcoord);
    fragColor = vec4(c.rgb, uAlpha);
}

Al ejecutar « qsb -o shader.frag.qsb shader.frag » se genera « shader.frag.qsb ». Al examinar este archivo con « qsb -d shader.frag.qsb », obtenemos:

Stage: Fragment
QSB_VERSION: 5
Has 1 shaders:
  Shader 0: SPIR-V 100 [Standard]

Reflection info: {
    "combinedImageSamplers": [
        {
            "binding": 1,
            "name": "tex",
            "set": 0,
            "type": "sampler2D"
        }
    ],
    "inputs": [
        {
            "location": 0,
            "name": "v_texcoord",
            "type": "vec2"
        }
    ],
    "localSize": [
        0,
        0,
        0
    ],
    "outputs": [
        {
            "location": 0,
            "name": "fragColor",
            "type": "vec4"
        }
    ],
    "uniformBlocks": [
        {
            "binding": 0,
            "blockName": "buf",
            "members": [
                {
                    "name": "uAlpha",
                    "offset": 0,
                    "size": 4,
                    "type": "float"
                }
            ],
            "set": 0,
            "size": 4,
            "structName": "_27"
        }
    ]
}


Shader 0: SPIR-V 100 [Standard]
Entry point: main
Contents:
Binary of 864 bytes

Por defecto, solo se genera SPIR-V, por lo que una aplicación que utilice este paquete de sombreadores solo funcionaría con Vulkan. Hagámoslo más útil:

qsb --glsl "100 es,120,150" --hlsl 50 --msl 12 -o shader.frag.qsb shader.frag

Esto da lugar a la generación de un paquete de sombreadores que también resulta adecuado para OpenGL, Direct 3D y Metal. Las características utilizadas en este sombreador son básicas, por lo que incluso GLSL ES 100 (el lenguaje de sombreado de OpenGL ES 2.0) resulta adecuado.

Al examinar el resultado, vemos que:

Stage: Fragment
QSB_VERSION: 5
Has 6 shaders:
  Shader 0: GLSL 120 [Standard]
  Shader 1: HLSL 50 [Standard]
  Shader 2: GLSL 100 es [Standard]
  Shader 3: MSL 12 [Standard]
  Shader 4: SPIR-V 100 [Standard]
  Shader 5: GLSL 150 [Standard]

Reflection info: {
    ... <same as above>
}


Shader 0: GLSL 120 [Standard]
Entry point: main
Contents:
#version 120

struct buf
{
    float uAlpha;
};

uniform buf _27;

uniform sampler2D tex;

varying vec2 v_texcoord;

void main()
{
    vec4 c = texture2D(tex, v_texcoord);
    gl_FragData[0] = vec4(c.xyz, _27.uAlpha);
}

************************************

Shader 1: HLSL 50 [Standard]
Entry point: main
Native resource binding map:
0 -> [0, -1]
1 -> [0, 0]
Contents:
cbuffer buf : register(b0)
{
    float _27_uAlpha : packoffset(c0);
};

Texture2D<float4> tex : register(t0);
SamplerState _tex_sampler : register(s0);

static float2 v_texcoord;
static float4 fragColor;

struct SPIRV_Cross_Input
{
    float2 v_texcoord : TEXCOORD0;
};

struct SPIRV_Cross_Output
{
    float4 fragColor : SV_Target0;
};

void frag_main()
{
    float4 c = tex.Sample(_tex_sampler, v_texcoord);
    fragColor = float4(c.xyz, _27_uAlpha);
}

SPIRV_Cross_Output main(SPIRV_Cross_Input stage_input)
{
    v_texcoord = stage_input.v_texcoord;
    frag_main();
    SPIRV_Cross_Output stage_output;
    stage_output.fragColor = fragColor;
    return stage_output;
}

************************************

...

Shader 3: MSL 12 [Standard]
Entry point: main0
Native resource binding map:
0 -> [0, -1]
1 -> [0, 0]
Contents:
#include <metal_stdlib>
#include <simd/simd.h>

using namespace metal;

struct buf
{
    float uAlpha;
};

struct main0_out
{
    float4 fragColor [[color(0)]];
};

struct main0_in
{
    float2 v_texcoord [[user(locn0)]];
};

fragment main0_out main0(main0_in in [[stage_in]], constant buf& _27 [[buffer(0)]], texture2d<float> tex [[texture(0)]], sampler texSmplr [[sampler(0)]])
{
    main0_out out = {};
    float4 c = tex.sample(texSmplr, in.v_texcoord);
    out.fragColor = float4(c.xyz, _27.uAlpha);
    return out;
}

************************************

...

Ahora, Qt Quick puede utilizar este paquete con todas las API gráficas compatibles: Vulkan, Direct 3D, Metal, OpenGL y OpenGL ES. En tiempo de ejecución, la interfaz de hardware de renderizado de Qt, que se encuentra bajo Qt Quick y Qt Quick 3D, selecciona automáticamente el sombreador adecuado.

Además de traducir el bytecode SPIR-V de nuevo a código fuente de nivel superior, el sistema se encarga de resolver problemas adicionales, como garantizar la asignación correcta de los números de enlace SPIR-V a los recursos nativos. Por ejemplo, con HLSL veíamos una sección como esta anteriormente:

Native resource binding map:
 0 -> [0, -1]
 1 -> [0, 0]

A nivel interno, esto permite asignar un punto de enlace de estilo SPIR-V 0 al registro HLSL b0 y vincular 1 a t0 y s0. Esto contribuye a que las diferencias en los enlaces de recursos entre los distintos lenguajes de sombreado resulten transparentes para los usuarios de la interfaz de hardware de renderizado, y permite que todo en Qt funcione con puntos de enlace al estilo de Vulkan/SPIR-V, tal y como se especifican en el código fuente original de GLSL al estilo de Vulkan.

Tipos de sombreadores

El tipo de sombreador se deduce a partir de la extensión del archivo de entrada. Por lo tanto, la extensión debe ser una de las siguientes:

  • .vert - para sombreadores de vértices
  • .tesc - para sombreadores de control de teselación
  • .tese - para sombreadores de evaluación de teselación
  • .geom - para sombreadores de geometría
  • .frag - para sombreadores de fragmentos (píxeles)
  • .comp - para sombreadores de cálculo

Nota: Actualmente, los shaders de control y evaluaciónde teselación no son compatibles con Direct 3D (HLSL).

Lenguajes de sombreado y versiones

Siempre se genera SPIR-V 1.0. Lo que se genere adicionalmente depende de los argumentos de línea de comandos --glsl, --hlsl y --msl.

Todos estos parámetros van seguidos de una lista separada por comas. La lista debe incluir números de versión al estilo GLSL, con un sufijo opcional (es, que indica GLSL ES). El espacio entre el sufijo y la versión es opcional (no incluirlo puede ayudar a evitar la necesidad de entrecomillas).

Por ejemplo, los materiales integrados de Qt Quick(los sombreadores que respaldan elementos como Image, Text y Rectangle) preparan todos sus sombreadores con --glsl "100 es,120,150" --hlsl 50 --msl 12. Esto los hace compatibles con OpenGL ES 2.0 y superior, OpenGL 2.1 y superior, y los contextos de perfil básico de OpenGL de la versión 3.2 y superior.

Si el shader utiliza funciones o construcciones que no tienen equivalente en los destinos especificados, ` qsb ` dará error. En ese caso, habrá que ajustar los destinos, lo que también implica que los requisitos mínimos del sistema de la aplicación se ajustarán de forma implícita. Tomemos como ejemplo la función GLSL « textureLod », que solo está disponible con OpenGL ES 3.0 y versiones posteriores (es decir, GLSL ES 300 o superior). Al solicitar GLSL 300 es en lugar de 100 es, qsb se ejecutará correctamente, pero la aplicación que utilice ese archivo .qsb requerirá ahora OpenGL ES 3.0 o superior y no será compatible con sistemas basados en OpenGL ES 2.0.

Otro ejemplo evidente de esto son los shaders de cálculo: los shaders de .comp deberán especificar --glsl 310es,430, ya que los shaders de cálculo solo están disponibles con OpenGL ES 3.1 o posterior y con OpenGL 4.3 o posterior.

Se prevé que rara vez sea necesario ajustar la versión del modelo de sombreador para HLSL o la versión de Metal Shading Language. Normalmente bastará con el modelo de sombreador 5.0 (--hlsl 50) y MSL 1.2 (--msl 12).

Qt Quick Agrupación en el grafo de escena

El renderizador del grafo de escena de Qt Quick admite el agrupamiento de geometría para reducir el número de llamadas de dibujo. Consulta las páginas del grafo de escena para obtener más detalles. Esto se basa en la inserción de código en la función main() del sombreador de vértices. En Qt 5.x esto se realizaba en tiempo de ejecución, modificando el código del sombreador de vértices GLSL proporcionado. En Qt 6, esa opción ya no está disponible. En su lugar, se pueden generar variantes agrupables de los sombreadores de vértices mediante la herramienta qsb. Esto se solicita mediante el argumento -b. Cuando la entrada no es un sombreador de vértices con la extensión « .vert », no tiene ningún efecto. Sin embargo, en el caso de los sombreadores de vértices, esto dará lugar a la generación de dos versiones para cada destino. A continuación, Qt Quick seleccionará automáticamente la variante adecuada (estándar o agrupable) en tiempo de ejecución.

Nota: Las aplicaciones no tienen que preocuparse por los detalles del procesamiento por lotes. Simplemente deben asegurarse de que se especifique -b (o la palabra clave equivalente BATCHABLE si se utiliza la integración con CMake) al procesar los sombreadores de vértices. Esto solo es relevante para los sombreadores Qt Quick utilizados con ShaderEffect o QSGMaterialShader.

Tomemos el siguiente ejemplo de sombreador de vértices:

#version 440
layout(location = 0) in vec4 position;
layout(location = 1) in vec2 texcoord;
layout(location = 0) out vec2 v_texcoord;
layout(std140, binding = 0) uniform buf {
    mat4 mvp;
} ubuf;

void main()
{
    v_texcoord = texcoord;
    gl_Position = ubuf.mvp * position;
}

Al ejecutar « qsb -b --glsl 330 -o example.vert.qsb example.vert » se obtiene:

Stage: Vertex
QSB_VERSION: 5
Has 4 shaders:
  Shader 0: GLSL 330 [Standard]
  Shader 1: GLSL 330 [Batchable]
  Shader 2: SPIR-V 100 [Standard]
  Shader 3: SPIR-V 100 [Batchable]

Reflection info: {
  ...

Obsérvese cómo todos los lenguajes y versiones de destino existen ahora en dos variantes: «Standard» y una versión ligeramente modificada denominada «Batchable».

Invocación de herramientas externas

qsb puede invocar ciertas herramientas externas. Estas se dividen en dos categorías: herramientas para realizar optimizaciones en el código byte del sombreador (SPIR-V) y herramientas específicas de la plataforma para llevar a cabo la primera fase de la compilación del sombreador, desde el código fuente hasta algún formato de código byte intermedio.

Se activan mediante las siguientes opciones de línea de comandos:

  • -O - invoca spirv-opt como paso de posprocesamiento sobre el binario SPIR-V. El archivo .qsb incluirá la versión optimizada. Esto supone que spirv-opt está disponible en el sistema (por ejemplo, desde el SDK de Vulkan) y listo para ser invocado.
  • -c o --fxc: invoca fxc.exe, el compilador de shaders de Direct 3D. Los datos resultantes de DXBC (código de bytes de DirectX) son los que se almacenan en el archivo .qsb en lugar del código fuente HLSL. Qt los detectará automáticamente en tiempo de ejecución, por lo que corresponde al creador del archivo .qsb decidir qué incluir: el código fuente HLSL o el formato intermedio. Siempre que sea posible, es preferible optar por esta última opción, ya que elimina la necesidad de analizar el código fuente HLSL en tiempo de ejecución, lo que puede suponer una mejora significativa del rendimiento durante la creación del pipeline gráfico. La desventaja es que este argumento solo se puede utilizar cuando qsb se ejecuta en Windows.
  • -t o --metallib: invoca las herramientas Metal de XCode adecuadas para generar un archivo .metallib y lo incluye en el paquete .qsb en lugar del código fuente MSL. Esta opción solo está disponible cuando qsb se ejecuta en macOS.

Otras opciones

  • -D - Define una macro. Esto permite utilizar #ifdef y similares en el código fuente GLSL.
  • -g - habilita la generación de información de depuración completa para SPIR-V, lo que permite que herramientas como RenderDoc muestren el código fuente completo al inspeccionar un pipeline o al realizar la depuración de vértices o fragmentos. También tiene efecto en Direct 3D cuando se especifica -c, ya que entonces se indica a fxc que incluya información de depuración en el bytecode intermedio generado.
  • --mediump - Solicita que se utilice por defecto una precisión media para los valores flotantes en los sombreadores de fragmento GLSL ES. Se ignora para cualquier otro destino, incluido GLSL (no ES), y para los sombreadores que no sean de fragmento.
  • --orig-file - Especifica el nombre de archivo que se utiliza en lugar del archivo fuente de entrada al generar archivos de dependencias para CMake (–depfiles). Esto resulta útil cuando el archivo pasado a qsb es un archivo fuente de shader intermedio generado. Sin embargo, a efectos del seguimiento de dependencias, a menudo es necesario utilizar el archivo original.

Tesselación

  • --msltess - Indica que el sombreador de vértices se utiliza en un proceso que incluye etapas de teselación. No tiene ningún efecto en otros tipos de sombreadores, ni cuando la generación de sombreadores MSL no está habilitada. Si no se especifica, el sombreador de vértices no funcionará en Metal en combinación con la teselación.
  • --tess-vertex-count <count> - Especifica el recuento de vértices de salida de la etapa de control de teselación. Es obligatorio especificar este valor para los sombreadores de evaluación de teselación utilizados con Metal. El valor por defecto es 3. Si no coincide con la etapa de control de teselación, el código MSL generado no funcionará como se espera.
  • --tess-mode <mode> - Esta opción especifica el modo de teselación. Puede adoptar uno de estos dos valores: « triangles » o « quads ». El valor por defecto es « triangles ». Es obligatorio especificarla para los sombreadores de control de teselación utilizados con Metal. El valor debe coincidir con la etapa de evaluación de la teselación; de lo contrario, el código MSL generado no funcionará como se espera.

Multivista

Consideremos el siguiente sombreador de vértices. Está escrito en GLSL compatible con Vulkan, habilitando la extensión GL_EXT_multiview para que el uso de gl_ViewIndex sea válido.

#version 440
#extension GL_EXT_multiview : require

layout(location = 0) in vec4 pos;
layout(std140, binding = 0) uniform buf
{
    mat4 mvp[2];
};

void main()
{
    gl_Position = mvp[gl_ViewIndex] * pos;
}

Nota: En la práctica, la línea #extension GL_EXT_multiview no será necesaria en el código fuente pasado a qsb, ya que al pasar el argumento --view-count que se describe a continuación, dicha línea se inserta automáticamente en el código fuente del sombreador antes de compilarlo a SPIR-V.

En el caso de Vulkan, esto funciona tal cual, siempre que se admita Vulkan 1.1 en tiempo de ejecución. Consulta VK_KHR_multiview para obtener más detalles.

Para generar un sombreador de vértices HLSL a partir de lo anterior para Direct 3D 12 (véase «instanciación de vistas» para más detalles), la versión mínima del modelo de sombreador es la 6.1, lo que significa que qsb fallará al especificar, por ejemplo, --hlsl 50. Utilice al menos --hlsl 61 al procesar un sombreador de vértices multivista. Multiview no es compatible con Direct 3D 11.

Para OpenGL, se necesitan metadatos adicionales:

  • --view-count - Al transpilar el shader anterior (tras compilarlo a SPIR-V) a código fuente GLSL compatible con OpenGL, no basta con asignar gl_ViewIndex a gl_ViewID_OVR, sino que también es necesario declarar el número de vistas en el shader. Al pasar un valor de 2 al argumento « --view-count », se inserta una instrucción « layout(num_views = 2) in; » en el código fuente GLSL generado, lo que lo convierte en un shader GLSL válido (para OpenGL). Consulte GL_OVR_multiview para obtener más detalles y tenga en cuenta que los shaders GLSL generados también requieren que GL_OVR_multiview2 sea compatible en tiempo de ejecución, ya que eso es lo que exigirá la directiva #extension en el código fuente del shader generado.

Al compilar para OpenGL (ES) con un sombreador de vértices de este tipo, la versión de GLSL generada (--glsl) debe ser, como mínimo, 330 o 300 es. La primera no es una restricción impuesta por qsb o QShaderBaker, pero en la práctica se sabe que las implementaciones de OpenGL rechazan dichos sombreadores si la versión de GLSL es 150 o inferior. Por lo tanto, se recomienda pasar --glsl 330,300es al condicionar los sombreadores de vértices que habilitan GL_EXT_multiview.

Al especificar « --view-count », se genera e inserta automáticamente una definición de preprocesador: « #define QSHADER_VIEW_COUNT n », donde « n » es el número de vistas. Cuando no se proporciona el número de vistas, la definición no se establece en absoluto. Esto permite escribir código como el siguiente y utilizar el mismo archivo fuente para todas las variantes del sombreador específicas del número de vistas.

layout(std140, binding = 0) uniform buf {
#if QSHADER_VIEW_COUNT >= 2
    mat4 matrix[QSHADER_VIEW_COUNT];
#else
    mat4 matrix;
#endif
    float opacity;
};

Además, la línea « #extension GL_EXT_multiview : require » se genera automáticamente en los sombreadores de vértices siempre que se establezca un recuento de vistas igual o superior a 2. Esto reduce el número de líneas adicionales que hay que añadir para que un sombreador de vértices admita múltiples vistas.

Establecer el número de vistas también puede ser relevante en otros tipos de sombreadores. Por ejemplo, al compartir un búfer uniforme entre el sombreador de vértices y el de fragmentos, y ambos sombreadores deban garantizar la misma estructura del búfer, puede resultar útil poder escribir « #if QSHADER_VIEW_COUNT >= 2 » en ambos archivos fuente. Esto se puede garantizar especificando « --view-count » para ambos al invocar « qsb ».

Nota: Recurrirdirectamente a la palabra clave « gl_ViewIndex » en una etapa que no sea la de vértices, por ejemplo, en un sombreador de fragmentos, no es portátil por el momento y debe evitarse.

Trabajo con características de GLSL específicas de OpenGL

En ocasiones puede ser necesario utilizar construcciones del lenguaje de sombreado que son específicas de OpenGL y GLSL, y que no son aplicables a otros lenguajes de sombreado, formatos intermedios ni API gráficas.

Los principales ejemplos de ello son las texturas externas y los muestreadores de OpenGL ES. La implementación de la reproducción de vídeo o la visualización del visor de una cámara puede implicar, dependiendo de la plataforma, trabajar con objetos de textura de OpenGL que no están pensados para utilizarse como texturas 2D normales, sino que, con un conjunto de características limitado, pueden utilizarse a través del punto de enlace GL_TEXTURE_EXTERNAL_OES de la API de OpenGL y del tipo de muestreador « samplerExternalOES » en los sombreadores. Este último supone un posible obstáculo al utilizar el canal de sombreado basado en SPIR-V de Qt: ejecutar un sombreador de este tipo a través de qsb dará lugar a un error, ya que samplerExternalOES no se acepta como tipo válido al no ser asignable a SPIR-V ni a otros lenguajes de sombreado de destino.

Para solucionar esto, qsb ofrece la opción de sustituir el contenido de cualquier variante de shader de un archivo .qsb por datos proporcionados por el usuario que se leen de un archivo, sustituyendo por completo el código fuente o el código de bytes del shader generado originalmente por qsb.

Tomemos como ejemplo el siguiente shader de fragmentos. Fíjate en el tipo de ` tex`. ¿Qué ocurre si el tipo tiene que ser ` samplerExternalOES ` al ejecutarlo con OpenGL ES?

#version 440

layout(location = 0) in vec2 texCoord;
layout(location = 0) out vec4 fragColor;

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

layout(binding = 1) uniform sampler2D tex;

void main()
{
    fragColor = texture(tex, texCoord).rgba * ubuf.opacity;
}

No basta con cambiar el tipo de `samplerExternalOES`. Eso provoca errores de compilación de inmediato.

Sin embargo, hay una solución sencilla: escribir una versión independiente del sombreador, destinada exclusivamente a OpenGL ES, e insertarla en el archivo .qsb. El siguiente sombreador solo es compatible con GLSL ES y no se puede ejecutar a través de qsb. No obstante, sabemos que OpenGL ES puede procesarlo en tiempo de ejecución.

precision highp float;
#extension GL_OES_EGL_image_external : require
varying vec2 texCoord;

struct buf
{
    float opacity;
};

uniform buf ubuf;
uniform samplerExternalOES tex;

void main()
{
    gl_FragColor = texture2D(tex, texCoord).rgba * ubuf.opacity;
}

Llamemos a esto « shader_gles.frag ». Una vez que se complete « qsb --glsl 100es -o shader.frag.qsb shader.frag », lo que nos dará un archivo .qsb (a medio preparar), podemos ejecutar « qsb -r glsl,100es,shader_gles.frag shader.frag.qsb » para actualizar « shader.frag.qsb », sustituyendo el sombreador para GLSL 100 es por el contenido del archivo especificado (shader_gles.frag). Ahora « shader.frag.qsb » está listo para utilizarse en tiempo de ejecución con OpenGL ES.

Nota: Presta atención a mantener sin cambios la interfaz entre el shader y la aplicación. Comprueba siempre primero el código GLSL generado por qsb, ya sea imprimiendo el contenido del archivo .qsb mediante la opción « -d », o extrayendo el shader GLSL ES 100 ejecutando « qsb -x glsl,100es -o gles_shader.frag shader.frag.qsb ». Los nombres de las estructuras, los miembros de las estructuras y los uniformes tampoco deben diferir en la versión inyectada manualmente.

Nota: La capacidad de incluir datos de archivos arbitrarios en el paquete .qsb también puede utilizarse para inyectar shaders HLSL de hull y domain creados a mano, con el fin de que los flujos de trabajo gráficos basados en teselación también funcionen con Direct 3D.

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