QShaderBaker Class

Documentación de Funciones Miembro

QShaderBaker::QShaderBaker()

Construye un nuevo 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, llame a QShader::isValid(). Cuando indique false, llama a errorMessage() para recuperar el registro.

Se trata de una operación costosa. Cuando se llama a esto desde aplicaciones, puede ser aconsejable hacerlo en un hilo separado.

QString QShaderBaker::errorMessage() const

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

void QShaderBaker::setBatchableVertexShaderExtraInputLocation(int location)

Al generar una variante de QShader::BatchableVertexShader, location especifica la ubicación de entrada para la entrada de vértices insertada. El valor predeterminado es 7 y sólo debe modificarse 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 traducción del sombreador (de SPIR-V a GLSL/HLSL/MSL). Por defecto este ajuste es true, lo que hará que bake() devuelva un error si no se puede generar el shader solicitado. Si no se desea esto, y la intención es generar lo que podamos pero omitir silenciosamente el resto, entonces establezca enable a false.

Tener como objetivo múltiples versiones de GLSL puede llevar a errores cuando una característica no es traducible a una versión dada. Por ejemplo, intentar traducir un shader usando textureSize() a GLSL ES 100 fallaría toda la llamada a bake() con el mensaje de error "textureSize no está soportado en ESSL 100". Si es aceptable no tener un shader GLSL ES 100 en el resultado, a pesar de que fue solicitado, entonces establecer esta bandera a false hace que bake() tenga éxito.

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

Especifica qué variantes de sombreado se generan. Cada versión de shader puede tener múltiples variantes en el resultado QShader.

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

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

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

Por ejemplo, el mínimo objetivo de cocción posible es SPIR-V, sin traducciones adicionales a otros idiomas. Para solicitarlo, haga lo siguiente:

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

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

Establece options adicional para las fuentes GLSL y GLSL ES generadas. Por defecto no se establece ninguna bandera.

Esta función se introdujo en Qt 6.9.

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

Cuando se transpilan shaders que utilizan multiview (por ejemplo, un vertex shader que utiliza gl_ViewIndex para un renderizador que confía en GL_OVR_multiview2, VK_KHR_multiview, etc.), para algunos de los objetivos es necesario declarar el número de vistas en el shader. Esto no se hace en el código GLSL estilo Vulkan, y no es relevante para objetivos como SPIR-V o HLSL, pero es necesario para OpenGL y GLSL, por lo que el valor tiene que ser proporcionado como metadatos adicionales.

Por defecto, el valor es 0, que desactiva la inyección de la sentencia num_views. Establecer 1 no es útil ya que ese es el valor por defecto de num_views independientemente. Por lo tanto, count debe ser >= 2 para que tenga efecto. Cuando se establece a, por ejemplo, 2, el shader GLSL generado contendrá una declaración layout(num_views = 2) in;.

Establecer un count de 2 o mayor también inyecta algunas sentencias 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 count apropiado puede ser relevante con otros tipos de shaders también, por ejemplo, cuando se comparte un buffer uniforme entre el vertex y fragment shader y ambos shaders tienen que ser capaces de 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. Por defecto está desactivada, lo que significa que el código fuente Vulkan/GLSL se compila en SPIR-V una vez por variante. (así que una vez por defecto, dos veces si es un vertex shader y la variante Batchable si se solicita también). El SPIR-V resultante se traduce a los distintos lenguajes de destino (GLSL, HLSL, MSL).

En el modo de compilación por objetivo, hay un paso de compilación GLSL a SPIR-V separado para cada objetivo, es decir, para cada versión GLSL/HLSL/MSL solicitada a través de setGeneratedShaders(). La fuente de entrada es la misma, pero con las definiciones de preprocesador específicas del objetivo insertadas. Esto consume bastante más tiempo, pero permite a las aplicaciones proporcionar un único shader 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 sombreado, procesar cada una por separado, enviar archivos {.qsb} para cada una y elegir el archivo correcto basándose en la lógica de tiempo de ejecución.

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

• QSHADER_SPIRV - definidas cuando se apunta a SPIR-V (para ser consumidas, típicamente, por Vulkan).
• QSHADER_SPIRV_VERSION - el número de versión de SPIR-V de destino, como 100.
• QSHADER_GLSL - definido cuando se utiliza 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 - definido sólo para GLSL ES
• QSHADER_HLSL - definido cuando se utiliza HLSL (para ser consumido, normalmente, por Direct 3D)
• QSHADER_HLSL_VERSION - la versión del modelo de sombreado HLSL de destino, por ejemplo 50
• QSHADER_MSL - definido cuando se utiliza Metal Shading Language (para ser utilizado, normalmente, por Metal)
• QSHADER_MSL_VERSION - la versión MSL de destino, como 12 o 20.

Esto permite escribir código de sombreado 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

void QShaderBaker::setPreamble(const QByteArray &preamble)

Especifica un preamble personalizado que se procesa antes que el código normal del shader.

Esto es más que simplemente añadirlo a la cadena fuente: la validez de la directiva de versión GLSL, que debe colocarse antes que todo lo demás, no se ve afectada. Los números de línea en los mensajes de error también permanecen sin cambios, ignorando el contenido dado en preamble.

Un caso de uso de los preámbulos es la inserción transparente de 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 sólo archivos. stage especifica la etapa del shader, mientras que el opcional fileName contiene un nombre de archivo que se utiliza en los mensajes de error.

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 bake(). La etapa del sombreador se deduce automáticamente de la extensión del archivo. Si no se desea o no es posible, utilice la sobrecarga con el argumento stage.

Las extensiones de archivo soportadas son:

• .vert - vertex shader
• .frag - sombreador de fragmentos (píxeles)
• .tesc - tessellation control (hull) shader
• .tese - sombreador de evaluación de teselación (dominio)
• .geom - sombreador de geometría
• .comp - sombreador de cálculo

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 sombreador se especifica en stage.

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 opcional fileName contiene un nombre de archivo que se utiliza en los mensajes de error.

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

Establece options adicional para el binario SPIR-V generado. Por defecto no se establece ninguna bandera.

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

Al generar el código del sombreador MSL para un sombreador de control de teselado, debe conocerse de antemano el teselado mode (triángulos o cuadrángulos). En GLSL esto se declara normalmente en el shader de evaluación de teselación, pero para Metal debe conocerse también al generar el shader de cálculo a partir del shader de control de teselación.

Si no se establece, el valor predeterminado es triángulos.

void QShaderBaker::setTessellationOutputVertexCount(int count)

Cuando se genera código de sombreado MSL para un sombreador de evaluación de teselación, el vértice de salida count del sombreador de control de teselación debe conocerse por adelantado. en GLSL esto se declararía en el sombreador de control de teselación típicamente, pero para Metal debe conocerse también al generar el sombreador de vértices desde el sombreador de evaluación de teselación.

Cuando no se establece, el valor por defecto es 3.