En esta página

QShaderBaker Class

Compila un shader GLSL/Vulkan en SPIR-V, lo traduce a otros lenguajes de sombreado y recopila metadatos de reflexión. Más...

Encabezado: #include <qshaderbaker.h>
CMake: find_package(Qt6 REQUIRED COMPONENTS ShaderTools)
target_link_libraries(mytarget PRIVATE Qt6::ShaderTools)
Desde: Qt 6.6

Tipos públicos

GeneratedShader
enum class GlslOption { GlslEsFragDefaultFloatPrecisionMedium }
flags GlslOptions
enum class SpirvOption { GenerateFullDebugInfo, StripDebugAndVarInfo }
flags SpirvOptions

Funciones públicas

QShaderBaker()
~QShaderBaker()
QShader bake()
QString errorMessage() const
void setBatchableVertexShaderExtraInputLocation(int location)
void setBreakOnShaderTranslationError(bool enable)
void setGeneratedShaderVariants(const QList<QShader::Variant> &v)
void setGeneratedShaders(const QList<QShaderBaker::GeneratedShader> &v)
(since 6.9) void setGlslOptions(QShaderBaker::GlslOptions options)
(since 6.7) void setMultiViewCount(int count)
void setPerTargetCompilation(bool enable)
void setPreamble(const QByteArray &preamble)
void setSourceDevice(QIODevice *device, QShader::Stage stage, const QString &fileName = QString())
void setSourceFileName(const QString &fileName)
void setSourceFileName(const QString &fileName, QShader::Stage stage)
void setSourceString(const QByteArray &sourceString, QShader::Stage stage, const QString &fileName = QString())
void setSpirvOptions(QShaderBaker::SpirvOptions options)
void setTessellationMode(QShaderDescription::TessellationMode mode)
void setTessellationOutputVertexCount(int count)

Descripción detallada

Advertencia: QShaderBaker , al igual que la familia de clases « QRhi » del módulo Qt GUI, incluidas 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 a nivel de código fuente, y estos solo se realizarán en versiones menores (6.7, 6.8, etc.). Para utilizar esta clase en una aplicación, enlaza con Qt::ShaderToolsPrivate (si utilizas CMake) e incluye los encabezados con el prefijo rhi, por ejemplo, #include <rhi/qshaderbaker.h>.

QShaderBaker toma un shader gráfico (de vértices, de fragmentos, etc.) o de cálculo, y genera múltiples variantes del mismo —ya sean de código fuente o de código byte—, junto con información de reflexión. Los resultados se representan mediante una instancia de QShader, que también proporciona una serialización y deserialización sencillas y rápidas.

Nota: Se recomienda alas aplicaciones y bibliotecas que eviten utilizar esta clase directamente. En su lugar, se anima a todos los usuarios de Qt a recurrir a la compilación fuera de línea ejecutando la herramienta de línea de comandos qsb en el momento de la compilación a través de CMake. La herramienta qsb utiliza QShaderBaker y escribe la versión serializada del QShader generado en un archivo. El uso de esta clase debe limitarse a los casos en los que no se pueda evitar la compilación en tiempo de ejecución, como cuando se trabaja con cadenas de código fuente de shaders proporcionadas por el usuario o generadas dinámicamente.

Por el momento, se da por hecho que el formato de entrada es GLSL al estilo de Vulkan. Consulte la especificación GL_KHR_vulkan_glsl para obtener una visión general, teniendo en cuenta que el módulo Qt Shader Tools está pensado para utilizarse en combinación con las clases QRhi del módulo Qt Rendering Hardware Interface y, por lo tanto, una serie de conceptos y construcciones (constantes push, búferes de almacenamiento, subpasos, etc.) no son aplicables por el momento. Es posible que se introduzcan opciones adicionales en el futuro, por ejemplo, habilitando HLSL como formato de origen, una vez que la compilación de HLSL a SPIR-V se considere adecuada.

Los metadatos de reflexión se pueden recuperar del objeto ` QShader ` resultante llamando a ` QShader::description()`. Esto resulta esencial a la hora de determinar qué conjunto de entradas de vértices y recursos de shader espera un shader, y cuáles son sus disposiciones, ya que muchas API gráficas modernas no ofrecen capacidades integradas de reflexión de shaders.

Flujo de trabajo típico

Supongamos que una aplicación tiene un sombreador de vértices y un sombreador de fragmentos como los siguientes:

Shader 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;
};

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

Shader de fragmentos:

#version 440

layout(location = 0) in vec3 v_color;
layout(location = 0) out vec4 fragColor;

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

void main()
{
    fragColor = vec4(v_color * opacity, opacity);
}

Para obtener instanci QShader s que puedan pasarse tal cual a un ` QRhiGraphicsPipeline`, hay dos opciones: generar el paquete de shaders fuera de línea o en tiempo de ejecución.

La primera implica ejecutar la herramienta qsb:

qsb --glsl "100 es,120" --hlsl 50 --msl 12 color.vert -o color.vert.qsb
qsb --glsl "100 es,120" --hlsl 50 --msl 12 color.frag -o color.frag.qsb

El ejemplo utiliza los destinos de traducción adecuados para QRhi. Esto significa GLSL/ES 100, GLSL 120, HLSL Shader Model 5.0 y Metal Shading Language 1.2.

Obsérvese cómo las opciones de la línea de comandos se corresponden con lo que se puede especificar mediante ` setGeneratedShaders()`. Una vez que los archivos resultantes están disponibles, pueden incluirse con la aplicación (normalmente incrustados en el ejecutable mediante el sistema de recursos de Qt) y pueden cargarse y pasarse a ` QShader::fromSerialized()` en tiempo de ejecución.

Aunque no se muestra aquí, qsb puede hacer más: también es capaz de invocar fxc en Windows o las herramientas adecuadas de XCode en macOS para compilar el código de shader HLSL o Metal generado en bytecode e incluir las versiones compiladas en QShader. Una vez que un paquete de shaders «baked» se ha guardado en un archivo, su contenido puede examinarse ejecutando qsb -d sobre él. Ejecuta qsb con --help para obtener más información.

El método alternativo consiste en realizar lo mismo en tiempo de ejecución. Para ello, hay que crear una instancia de QShaderBaker, llamar a setSourceFileName() y, a continuación, configurar los destinos de traducción mediante setGeneratedShaders():

baker.setGeneratedShaderVariants({ QShader::StandardShader });
QList<QShaderBaker::GeneratedShader> targets;
targets.append({ QShader::SpirvShader, QShaderVersion(100) });
targets.append({ QShader::GlslShader, QShaderVersion(100, QShaderVersion::GlslEs) });
targets.append({ QShader::SpirvShader, QShaderVersion(120) });
targets.append({ QShader::HlslShader, QShaderVersion(50) });
targets.append({ QShader::MslShader, QShaderVersion(12) });
baker.setGeneratedShaders(targets);
QShader shaders = baker.bake();
if (!shaders.isValid())
    qWarning() << baker.errorMessage();

Véase también QShader.

Documentación sobre tipos de miembros

[alias] QShaderBaker::GeneratedShader

Sinónimo de std::pair<QShader::Source, QShaderVersion>.

enum class QShaderBaker::GlslOption
flags QShaderBaker::GlslOptions

ConstanteValorDescripción
QShaderBaker::GlslOption::GlslEsFragDefaultFloatPrecisionMedium0x01Emite « precision mediump float; » en los sombreadores de fragmentos para GLSL ES.

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

enum class QShaderBaker::SpirvOption
flags QShaderBaker::SpirvOptions

ConstanteValorDescripción
QShaderBaker::SpirvOption::GenerateFullDebugInfo0x01Genera y almacena información de depuración adicional en el binario SPIR-V.
QShaderBaker::SpirvOption::StripDebugAndVarInfo0x02Elimina toda la información de depuración y los nombres de variables del binario SPIR-V.

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

Documentación de las funciones de miembro

QShaderBaker::QShaderBaker()

Crea un nuevo objeto QShaderBaker.

[noexcept] QShaderBaker::~QShaderBaker()

Destructor.

QShader QShaderBaker::bake()

Ejecuta el proceso de compilación y traducción.

Devuelve una instancia de ` QShader `. Para comprobar si el proceso se ha realizado correctamente, llama a ` QShader::isValid()`. Cuando este indique ` false`, llama a ` errorMessage()` para recuperar el registro.

Esta es una operación costosa. Al llamarla desde aplicaciones, puede ser recomendable hacerlo en un hilo independiente.

Nota: Las instanciasde ` QShaderBaker ` son reutilizables: tras llamar a `bake()`, la misma instancia puede volver a utilizarse con diferentes entradas. Sin embargo, una instancia de ` QShaderBaker ` solo debe utilizarse en un único hilo durante su ciclo de vida.

QString QShaderBaker::errorMessage() const

Devuelve el mensaje de error de la última ejecución de ` bake()`, o una cadena vacía si no se produjo ningún error.

Nota: Los errores incluyen errores de lectura de archivos, de compilación y de traducción. No solicitar ningún objetivo ni variante no se considera un error, aunque el resultado de ` QShader ` no sea válido.

void QShaderBaker::setBatchableVertexShaderExtraInputLocation(int location)

Al generar una variante « QShader::BatchableVertexShader », la opción « location » especifica la ubicación de entrada para la entrada del vértice insertado. El valor predeterminado es 7 y solo es necesario modificarlo si el sombreador de vértices ya utiliza la ubicación de entrada 7.

void QShaderBaker::setBreakOnShaderTranslationError(bool enable)

Controla el comportamiento cuando falla la conversión del shader (de SPIR-V a GLSL/HLSL/MSL). Por defecto, este parámetro está establecido en «true», lo que hará que ` bake()` devuelva un error si no se puede generar el shader solicitado. Si no se desea que esto ocurra y la intención es generar lo que sea posible y omitir el resto de forma silenciosa, hay que establecer ` enable ` en «false».

Dirigirse a varias versiones de GLSL puede provocar errores cuando una característica no es traducible a una versión determinada. Por ejemplo, intentar traducir un shader que utilice textureSize() a GLSL ES 100 haría que fallara toda la llamada a bake() con el mensaje de error «textureSize no es compatible con ESSL 100». Si resulta aceptable no obtener un sombreador GLSL ES 100 en el resultado, aunque se haya solicitado, al establecer este indicador en «false» se garantiza que la llamada a ` bake()` se ejecute correctamente.

void QShaderBaker::setGeneratedShaderVariants(const QList<QShader::Variant> &v)

Especifica qué variantes de shader se generan. Cada versión de shader puede tener varias variantes en el archivo resultante QShader.

En la mayoría de los casos, el archivo « v » contiene una única entrada: « QShader::StandardShader ».

Nota: cuando no se definen variantes, el archivo « QShader » resultante estará vacío y, por lo tanto, no será válido.

void QShaderBaker::setGeneratedShaders(const QList<QShaderBaker::GeneratedShader> &v)

Especifica qué tipo de shaders se deben compilar o a cuáles se deben traducir. Por defecto no se genera nada, por lo que es obligatorio llamar a esta función antes de bake()

Nota: si no se llama a esta función, osi ` v ` está vacío o contiene solo entradas no válidas, el archivo ` QShader ` resultante estará vacío y, por lo tanto, no será válido.

Por ejemplo, el destino de «baking» mínimo posible es SPIR-V, sin traducciones adicionales a otros lenguajes. Para solicitarlo, haz lo siguiente:

baker.setGeneratedShaders({ QShader::SpirvShader, QShaderVersion(100) });

Nota: QShaderBaker solo admite los destinos SPIR-V y de código fuente legible para humanos. La compilación posterior a formatos intermedios específicos de la API, como QShader::DxbcShader o QShader::MetalLibShader, se lleva a cabo mediante la herramienta de línea de comandos qsb y no forma parte de la API de tiempo de ejecución QShaderBaker.

[since 6.9] void QShaderBaker::setGlslOptions(QShaderBaker::GlslOptions options)

Establece indicadores adicionales de « options » para los códigos fuente GLSL y GLSL ES generados. Por defecto, no se establece ningún indicador.

Esta función se introdujo en Qt 6.9.

[since 6.7] void QShaderBaker::setMultiViewCount(int count)

Al transpilar shaders utilizando multiview (por ejemplo, un shader de vértices que utilice `gl_ViewIndex` para un renderizador que se base en `GL_OVR_multiview2`, `VK_KHR_multiview`, etc.), para algunos de los destinos es necesario declarar el número de vistas en el shader. Esto no se hace en el código GLSL al estilo Vulkan, y no es relevante para destinos como SPIR-V o HLSL, pero sí es obligatorio para OpenGL y GLSL, por lo que el valor debe proporcionarse como metadatos adicionales.

Por defecto, el valor es 0, lo que deshabilita la inserción de la instrucción ` num_views `. Establecer el valor en 1 no sirve de nada, ya que ese es el valor por defecto de ` num_views ` en cualquier caso. Por lo tanto, ` count ` debe ser ≥ 2 para que surta efecto. Cuando se establece, por ejemplo, en 2, el sombreador GLSL generado contendrá una instrucción ` layout(num_views = 2) in; `.

Establecer un valor de « count » de 2 o superior también inserta algunas instrucciones del preprocesador: « QSHADER_VIEW_COUNT » se establece en « count », mientras que la extensión « GL_EXT_multiview » se habilita automáticamente. Por lo tanto, establecer el valor adecuado de « count » puede ser relevante también con otros tipos de sombreadores, por ejemplo, cuando se comparte un búfer uniforme entre el sombreador de vértices y el de fragmentos y ambos sombreadores deben poder escribir algo como « #if QSHADER_VIEW_COUNT >= 2 ».

Esta función se introdujo en Qt 6.7.

void QShaderBaker::setPerTargetCompilation(bool enable)

Establece la compilación por objetivo en « enable ». De forma predeterminada, esta opción está desactivada, lo que significa que el código fuente de Vulkan/GLSL se compila a SPIR-V una vez por variante. (Es decir, una vez de forma predeterminada, y dos veces si se trata de un sombreador de vértices y también se ha solicitado la variante «Batchable»). A continuación, el SPIR-V resultante se traduce a los distintos lenguajes de destino (GLSL, HLSL, MSL).

En el modo de compilación por destino, hay un paso de compilación independiente de GLSL a SPIR-V para cada destino, es decir, para cada versión de GLSL/HLSL/MSL solicitada mediante ` setGeneratedShaders()`. El código fuente de entrada es el mismo, pero se insertan definiciones de preprocesador específicas para cada destino. Esto requiere mucho más tiempo, pero permite a las aplicaciones proporcionar un único sombreador y utilizar bloques « #ifdef » para diferenciarlos. Cuando este modo está desactivado, la única forma de conseguir lo mismo es proporcionar varias versiones del archivo de sombreador, procesar cada una por separado, distribuir archivos {.qsb} para cada una y elegir el archivo adecuado en función de la lógica en tiempo de ejecución.

Las siguientes macros se definirán automáticamente en este modo. Ten en cuenta que las macros siempre están vinculadas a los lenguajes de sombreado, no a las API gráficas.

  • QSHADER_SPIRV - Se define cuando se utiliza SPIR-V como destino (para ser utilizado, normalmente, por Vulkan).
  • QSHADER_SPIRV_VERSION - el número de versión de SPIR-V al que se dirige, como 100.
  • QSHADER_GLSL - Se define cuando el destino es GLSL o GLSL ES (para ser utilizado, normalmente, por OpenGL u OpenGL ES).
  • QSHADER_GLSL_VERSION - El número de versión de GLSL o GLSL ES de destino, como 100, 300 o 330.
  • QSHADER_GLSL_ES - Se define únicamente cuando el objetivo es GLSL ES
  • QSHADER_HLSL - Se define cuando se utiliza HLSL (normalmente para su uso con Direct 3D).
  • QSHADER_HLSL_VERSION - La versión del modelo de sombreador HLSL a la que se dirige, como 50
  • QSHADER_MSL - Se define cuando se utiliza Metal Shading Language (normalmente para su uso en Metal).
  • QSHADER_MSL_VERSION - la versión de MSL a la que se dirige, como 12 o 20.

Esto permite escribir código de sombreador como el siguiente.

#if QSHADER_HLSL || QSHADER_MSL
vec2 uv = vec2(uv_coord.x, 1.0 - uv_coord.y);
#else
vec2 uv = uv_coord;
#endif

Nota: Los númerosde versión siguen la sintaxis QShaderVersion, inspirada en GLSL, y, por lo tanto, son siempre un único número entero.

Nota: Solohay un QShaderDescription por cada QShader, independientemente del número de destinos individuales que haya. Por lo tanto, los miembros de los bloques uniformes, las entradas de vértices, etc., no deben hacerse condicionales utilizando las macros descritas anteriormente.

Advertencia: Ten en cuenta las diferencias entre los conceptos de las API gráficas y los lenguajes de sombreado. QShaderBaker y las herramientas relacionadas funcionan estrictamente con el concepto de los lenguajes de sombreado, sin tener en cuenta cómo se consumen los resultados posteriormente. Por lo tanto, si algún día las capas superiores de la pila gráfica de Qt empiezan a utilizar SPIR-V también para una API distinta de Vulkan, la suposición de que QSHADER_SPIRV implica Vulkan dejará de ser válida.

void QShaderBaker::setPreamble(const QByteArray &preamble)

Especifica una instrucción « preamble » personalizada que se procesa antes que el código normal del shader.

Esto va más allá de simplemente anteponerlo a la cadena de código fuente: la validez de la directiva de versión GLSL, que debe colocarse antes que cualquier otra cosa, no se ve afectada. Los números de línea en los mensajes de error mostrados tampoco cambian, ya que se ignora el contenido proporcionado en el preamble.

Un caso de uso de los preámbulos es insertar de forma transparente sentencias « #define » generadas dinámicamente.

void QShaderBaker::setSourceDevice(QIODevice *device, QShader::Stage stage, const QString &fileName = QString())

Establece la fuente device. Esto permite utilizar cualquier QIODevice en lugar de limitarse únicamente a archivos. stage especifica la etapa del shader, mientras que el parámetro opcional fileName contiene un nombre de archivo que se utiliza en los mensajes de error.

Advertencia: se espera quedevice contenga contenido fiable. Se recomienda a los desarrolladores de aplicaciones que sopesen cuidadosamente las posibles implicaciones antes de pasar datos proporcionados por el usuario procedentes de fuentes que no estén bajo el control de la aplicación.

void QShaderBaker::setSourceFileName(const QString &fileName)

Establece el nombre del archivo fuente del shader en « fileName ». Este es el archivo que se leerá al llamar a la función « bake()». La etapa del shader se deduce automáticamente a partir de la extensión del archivo. Cuando esto no sea deseable o no sea posible, utilice en su lugar la sobrecarga con el argumento «stage».

Las extensiones de archivo admitidas son:

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

Advertencia: se espera que« fileName » contenga contenido fiable. Se recomienda a los desarrolladores de aplicaciones que sopesen cuidadosamente las posibles implicaciones antes de pasar archivos fuente proporcionados por el usuario que no formen parte de la aplicación.

void QShaderBaker::setSourceFileName(const QString &fileName, QShader::Stage stage)

Establece el nombre del archivo fuente del shader en fileName. Este es el archivo que se leerá al llamar a bake(). La etapa del shader se especifica mediante stage.

Advertencia: se espera quefileName contenga contenido fiable. Se recomienda a los desarrolladores de aplicaciones que valoren cuidadosamente las posibles implicaciones antes de pasar archivos fuente proporcionados por el usuario que no formen parte de la aplicación.

void QShaderBaker::setSourceString(const QByteArray &sourceString, QShader::Stage stage, const QString &fileName = QString())

Establece el shader de entrada sourceString. stage especifica la etapa del shader, mientras que el parámetro opcional fileName contiene un nombre de archivo que se utiliza en los mensajes de error.

Advertencia: se espera quesourceString contenga contenido fiable. Se recomienda a los desarrolladores de aplicaciones que evalúen cuidadosamente las posibles implicaciones antes de pasar datos proporcionados por el usuario procedentes de fuentes que no estén bajo el control de la aplicación.

void QShaderBaker::setSpirvOptions(QShaderBaker::SpirvOptions options)

Establece los indicadores adicionales options para el binario SPIR-V generado. Por defecto, no se establece ningún indicador.

void QShaderBaker::setTessellationMode(QShaderDescription::TessellationMode mode)

Al generar código de shader MSL para un shader de control de teselación, es necesario conocer de antemano el tipo de « mode » de teselación (triángulos o cuadriláteros). En GLSL, esto se suele declarar en el shader de evaluación de teselación, pero en Metal también debe conocerse al generar el shader de cálculo a partir del shader de control de teselación.

Si no se especifica, el valor por defecto son los triángulos.

void QShaderBaker::setTessellationOutputVertexCount(int count)

Al generar código de shader MSL para un shader de evaluación de teselación, es necesario conocer de antemano la salida del vértice count del shader de control de teselación. En GLSL, esto se declararía normalmente en el shader de control de teselación, pero en Metal también debe conocerse al generar el shader de vértices a partir del shader de evaluación de teselación.

Si no se especifica, el valor por defecto es 3.

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