En esta página

CustomMaterial QML Type

Componente básico para crear materiales personalizados que se utilizan para dar sombra a los modelos. Más...

Import Statement: import QtQuick3D
Inherits:

Material

Propiedades

Descripción detallada

El material personalizado permite utilizar código de sombreador personalizado para un material, lo que facilita la programabilidad a nivel de sombreador gráfico. Se pueden proporcionar sombreadores de vértices, de fragmentos o ambos. Las propiedades « vertexShader » y « fragmentShader » son direcciones URL que hacen referencia a archivos que contienen fragmentos de shader, y funcionan de manera muy similar a ShaderEffect o Image.source. Solo se admiten los esquemas file y qrc con los materiales personalizados. También es posible omitir el esquema file, lo que permite especificar una ruta relativa de forma cómoda. Dicha ruta se resuelve en relación con la ubicación del componente (el archivo .qml ).

Para obtener una guía de introducción a los materiales personalizados, consulta la página «Materiales programables, efectos, geometría y datos de texturas».

Introducción

Considera las siguientes versiones de la misma escena. A la izquierda, el cilindro utiliza un material integrado no programable. Estos materiales se pueden configurar mediante una amplia gama de propiedades, pero no se ofrece ningún control adicional sobre los sombreadores que se generan en segundo plano. A la derecha, el mismo cilindro está ahora asociado a un «CustomMaterial» que hace referencia a fragmentos de código de sombreadores de vértices y de fragmentos proporcionados por la aplicación. Esto permite insertar lógica personalizada y específica de la aplicación en el sombreador de vértices para transformar la geometría, así como determinar ciertas propiedades de color de forma personalizada en el sombreador de fragmentos. Al tratarse de un material personalizado de tipo « shaded », el cilindro sigue participando en la iluminación de la escena con normalidad.

View3D {
    anchors.fill: parent
    PerspectiveCamera {
        id: camera
        position: Qt.vector3d(0, 0, 600)
    }
    camera: camera
    DirectionalLight {
        position: Qt.vector3d(-500, 500, -100)
        color: Qt.rgba(0.2, 0.2, 0.2, 1.0)
        ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
    }
    Model {
        source: "#Cylinder"
        eulerRotation: Qt.vector3d(30, 30, 0)
        scale: Qt.vector3d(1.5, 1.5, 1.5)
        materials: [
            DefaultMaterial {
                diffuseColor: Qt.rgba(0, 1, 0, 1)
            }
        ]
    }
}
View3D {
    anchors.fill: parent
    PerspectiveCamera {
        id: camera
        position: Qt.vector3d(0, 0, 600)
    }
    camera: camera
    DirectionalLight {
        position: Qt.vector3d(-500, 500, -100)
        color: Qt.rgba(0.2, 0.2, 0.2, 1.0)
        ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
    }
    Model {
        source: "#Cylinder"
        eulerRotation: Qt.vector3d(30, 30, 0)
        scale: Qt.vector3d(1.5, 1.5, 1.5)
        materials: [
            CustomMaterial {
                vertexShader: "material.vert"
                fragmentShader: "material.frag"
                property real uTime
                property real uAmplitude: 50
                NumberAnimation on uTime { from: 0; to: 100; duration: 10000; loops: -1 }
            }
        ]
    }
}

Supongamos que los fragmentos de shader en material.vert y material.frag son los siguientes:

void MAIN()
{
    VERTEX.x += sin(uTime + VERTEX.y) * uAmplitude;
}
void MAIN()
{
    BASE_COLOR = vec4(0.0, 1.0, 0.0, 1.0);
}

Fíjate en que uTime y uAmplitude son propiedades del elemento CustomMaterial. Pueden cambiar de valor y animarse con normalidad; los valores se mostrarán automáticamente a los shaders sin que el desarrollador tenga que hacer nada más.

El resultado es un cilindro cuyos vértices se animan:

Cilindro curvado con sombreador de vértices personalizado

Dos tipos de materiales personalizados

Existen dos tipos principales de materiales personalizados. Esto se especifica mediante la propiedad « shadingMode ». En los materiales « unshaded », el sombreador de fragmentos genera un único color « vec4 », ignorando las luces, las sondas de luz y las sombras de la escena. En los materiales « shaded », se espera que el sombreador implemente ciertas funciones y trabaje con variables integradas para tener en cuenta la contribución de la iluminación y las sombras.

La opción predeterminada suele ser un material sombreado, lo que se refleja en el valor por defecto de la propiedad shadingMode. Esto se adapta a los materiales que necesitan transformar vértices u otros datos procedentes de la geometría, o determinar valores como BASE_COLOR o EMISSIVE_COLOR de forma personalizada, quizá mediante el muestreo de SCREEN_TEXTURE o DEPTH_TEXTURE, sin dejar de recibir las contribuciones de luz y sombra de la escena. Además, dichos materiales también pueden anular y reimplementar las ecuaciones utilizadas para calcular las contribuciones de las luces direccionales, puntuales y de otro tipo. Los fragmentos de sombreador proporcionados por la aplicación son modificados en gran medida por el motor 3D de Qt Quick en segundo plano, con el fin de proporcionar las características, como la iluminación, que tienen los materiales estándar.

Los materiales sin sombreado resultan útiles cuando el aspecto del objeto viene determinado por completo por el código del sombreador personalizado. Los motores de sombreado de estos materiales reciben modificaciones mínimas por parte del motor, por lo que depende totalmente del motor de sombreado determinar el color final del fragmento. Esto ofrece más libertad, pero también limita las posibilidades de integración con otros elementos de la escena, como las luces.

Nota: El códigodel sombreador siempre se proporciona utilizando GLSL al estilo de Vulkan, independientemente de la API gráfica que utilice Qt en tiempo de ejecución.

Nota: El código de los sombreadores de vértices y de fragmentos proporcionado por el material no constituye, por sí solo, un sombreador GLSL completo. Más bien, proporciona un conjunto de funciones que el motor complementa posteriormente con código de sombreador adicional.

Exposición de datos a los shaders

Las propiedades dinámicas del CustomMaterial se pueden modificar y animar utilizando QML y las funciones de « Qt Quick », y los valores se exponen a los sombreadores de forma automática. En la práctica, esto es muy similar a lo que se describe en ShaderEffect. La siguiente lista muestra cómo se asignan las propiedades:

  • bool, int, real -> bool, int, float
  • QColor, color -> vec4, y el color se convierte a lineal, suponiendo un espacio sRGB para el valor de color especificado en QML. Los colores integrados de Qt, como "green", también se encuentran en el espacio de color sRGB, y se realiza la misma conversión para todas las propiedades de color de DefaultMaterial y PrincipledMaterial, por lo que este comportamiento de CustomMaterial coincide con los anteriores. A diferencia de Qt Quick, en el caso de Qt Quick la linealización 3D es esencial, ya que normalmente se aplica un mapeo de tonos a la escena 3D.
  • QRect, QRectF, rect -> vec4
  • QPoint, QPointF, point, QSize, QSizeF, size -> vec2
  • QVector2D, vector2d -> vec2
  • QVector3D, vector3d -> vec3
  • QVector4D, vector4d -> vec4
  • QMatrix4x4, matrix4x4 -> mat4
  • QQuaternion, quaternion -> vec4, el valor escalar es w
  • TextureInput -> sampler2D o samplerCube, dependiendo de si se utiliza Texture o CubeMapTexture en la propiedad de textura del TextureInput. Establecer la propiedad enabled en false hace que se exponga una textura ficticia al sombreador, lo que significa que los sombreadores siguen siendo funcionales, pero muestrearán una textura con contenido de imagen negro opaco. Ten en cuenta que las propiedades de los muestreadores siempre deben hacer referencia a un objeto ` TextureInput `, y no directamente a un ` Texture `. En cuanto a las propiedades de Texture, las relacionadas con la fuente, el mosaico y el filtrado son las únicas que se tienen en cuenta de forma implícita con los materiales personalizados, ya que el resto (como las transformaciones UV) depende de que los sombreadores personalizados las implementen como consideren oportuno.

Nota: Cuando un uniforme al que se hace referencia en el código del sombreador no tiene una propiedad correspondiente, se producirá un error de compilación del sombreador al procesar el material en tiempo de ejecución. Hay algunas excepciones a esto, como los uniformes de muestreador, a los que se les asigna una textura ficticia cuando no existe una propiedad QML correspondiente; pero, por regla general, todos los uniformes y muestreadores deben tener una propiedad correspondiente declarada en el objeto `CustomMaterial`.

Materiales personalizados sin sombreado

A continuación se muestra un ejemplo de un material personalizado « unshaded ».

CustomMaterial {
    // These properties are automatically exposed to the shaders
    property real time: 0.0
    property real amplitude: 5.0
    property real alpha: 1.0
    property TextureInput tex: TextureInput {
        enabled: true
        texture: Texture { source: "image.png" }
    }

    shadingMode: CustomMaterial.Unshaded
    sourceBlend: alpha < 1.0 ? CustomMaterial.SrcAlpha : CustomMaterial.NoBlend
    destinationBlend: alpha < 1.0 ? CustomMaterial.OneMinusSrcAlpha : CustomMaterial.NoBlend
    cullMode: CustomMaterial.BackFaceCulling

    vertexShader: "customshader.vert"
    fragmentShader: "customshader.frag"
}

Con el ejemplo anterior, los fragmentos de código de los shaders de vértices y fragmentos de unshaded podrían tener el siguiente aspecto. Fíjate en que los shaders no declaran, ni deben declarar, uniformes ni entradas de vértices, ya que Qt se encarga de ello al compilar el código final del shader.

VARYING vec3 pos;
VARYING vec2 texcoord;

void MAIN()
{
    pos = VERTEX;
    pos.x += sin(time * 4.0 + pos.y) * amplitude;
    texcoord = UV0;
    POSITION = MODELVIEWPROJECTION_MATRIX * vec4(pos, 1.0);
}
VARYING vec3 pos;
VARYING vec2 texcoord;

void MAIN()
{
    vec4 c = texture(tex, texcoord);
    FRAGCOLOR = vec4(pos.x * 0.02, pos.y * 0.02, pos.z * 0.02, alpha) * c;
}

Se dispone de las siguientes palabras clave especiales, en mayúsculas:

  • MAIN -> el nombre del punto de entrada en el fragmento de código del sombreador de vértices o de fragmentos debe ser siempre MAIN. Es obligatorio incluir esta función en los fragmentos de código de sombreadores para materiales personalizados sin sombreado.
  • VARYING -> declara una salida del sombreador de vértices o una entrada al sombreador de fragmentos
  • POSITION -> vec4, la salida del sombreador de vértices
  • FRAGCOLOR -> vec4, la salida del sombreador de fragmentos. Disponible únicamente para materiales personalizados sin sombreado.
  • VERTEX -> vec3, la posición del vértice en el sombreador de vértices.
  • NORMAL -> vec3, la normal del vértice en el sombreador de vértices. Cuando la malla del modelo asociado no proporciona normales, el valor es vec3(0,0).
  • UV0 -> vec2, el primer conjunto de coordenadas de textura en el sombreador de vértices. Cuando la malla del modelo asociado no proporciona coordenadas de textura, el valor es vec2(0,0).
  • UV1 -> vec2: el segundo conjunto de coordenadas de textura en el sombreador de vértices. Cuando la malla del modelo asociado no proporciona un segundo conjunto de coordenadas de textura, el valor es vec2(0,0).
  • COLOR -> vec4: el color del vértice en el sombreador de vértices. Cuando la malla del modelo asociado no proporciona colores por vértice, el valor es vec4(1,0).
  • TANGENT -> vec3: tangente en el sombreador de vértices. Cuando la malla del modelo asociado no proporciona datos de tangente, el valor es vec3(0,0).
  • BINORMAL -> vec3, binormal en el sombreador de vértices. Cuando la malla del modelo asociado no proporciona datos de binormal, el valor es vec3(0,0).
  • ARTICULACIONES -> ivec4, índices de articulación en el sombreador de vértices. Cuando la malla del modelo asociado no proporciona datos de índices de articulación, el valor es ivec4(0).
  • WEIGHTS -> vec4, pesos de las articulaciones en el sombreador de vértices. Cuando la malla del modelo asociado no proporciona datos de pesos de las articulaciones, el valor es vec4(0,0).
  • MORPH_POSITION(n) -> vec3, la posición del n+1.ºobjetivo de morfo en el sombreador de vértices. El modelo asociado debe proporcionar los datos adecuados.
  • MORPH_NORMAL(n) -> vec3, la normal del n+1.ºobjetivo de morfo en el sombreador de vértices. El modelo asociado debe proporcionar los datos adecuados.
  • MORPH_TANGENT(n) -> vec3, la tangente del n+1.ºobjetivo de morfo en el sombreador de vértices. El modelo asociado debe proporcionar los datos adecuados.
  • MORPH_BINORMAL(n) -> vec3, la binormal del objetivo de morfo n+1en el sombreador de vértices. El modelo asociado debe proporcionar los datos adecuados.
  • MODELVIEWPROJECTION_MATRIX -> mat4, la matriz de modelo-vista-proyección. Las matrices de proyección siempre siguen las convenciones de OpenGL, con una transformación integrada para la dirección del eje Y y la profundidad de recorte, dependiendo de la API gráfica utilizada en tiempo de ejecución.
  • VIEWPROJECTION_MATRIX -> mat4, la matriz de vista-proyección
  • PROJECTION_MATRIX -> mat4, la matriz de proyección
  • INVERSE_PROJECTION_MATRIX -> mat4, la matriz de proyección inversa
  • VIEW_MATRIX -> mat4, la matriz de vista (cámara)
  • MODEL_MATRIX -> mat4, la matriz del modelo (mundo)
  • NORMAL_MATRIX -> mat3, la matriz de normales (la transpuesta de la inversa de la parte superior izquierda de 3x3 de la matriz del modelo)
  • BONE_TRANSFORMS -> mat4[], la matriz de las matrices de huesos del modelo
  • BONE_NORMAL_TRANSFORMS -> mat3[], la matriz de matrices normales de los huesos del modelo (la transpuesta de la inversa de la parte superior izquierda de 3x3 de cada matriz de hueso)
  • MORPH_WEIGHTS -> float[], la matriz de los pesos de morfo. El modelo asociado debe proporcionar los datos adecuados. Por seguridad, QT_MORPH_MAX_COUNT se define con el tamaño de esta matriz.
  • CAMERA_POSITION -> vec3, la posición de la cámara en el espacio mundial
  • CAMERA_DIRECTION -> vec3, el vector de dirección de la cámara
  • CAMERA_PROPERTIES -> vec2, los valores de recorte cercano y lejano de la cámara
  • POINT_SIZE -> float, modificable únicamente en el sombreador de vértices. Al renderizar geometría con una topología de puntos, el sombreador de vértices personalizado debe establecer este valor en 1,0 o en otro valor, tanto en materiales personalizados sombreados como no sombreados. Consulte PrincipledMaterial::pointSize para obtener más información sobre la compatibilidad con tamaños distintos de 1.

Materiales personalizados con sombreado

Un material shaded augments el código de sombreador que generaría un PrincipledMaterial. A diferencia de los materiales sin sombreado, que proporcionan por sí mismos casi toda la lógica para las funciones principales de los sombreadores de vértices y de fragmentos —lo que impide añadir código generado para la iluminación, las sombras, la iluminación global, etc.—, los materiales con sombreado permiten que la generación de sombreadores se produzca con normalidad, como si el CustomMaterial fuera un PrincipledMaterial. Se espera que los fragmentos de código de los shaders de vértices y de fragmentos proporcionen funciones opcionales que luego se invocan en determinados puntos, lo que les da la posibilidad de personalizar los colores y otros valores que posteriormente se utilizan para calcular la iluminación y el color final del fragmento.

En lugar de implementar únicamente una función ` MAIN `, el sombreador de fragmentos de un material personalizado sombreado puede implementar varias funciones. Todas las funciones, incluida ` MAIN`, son opcionales en los materiales personalizados sombreados. Un fragmento de código de sombreador vacío, o incluso no especificar en absoluto las propiedades ` vertexShader ` o ` fragmentShader `, también es perfectamente válido.

Fragmentos de sombreador de vértices en un material personalizado con sombreado

Las siguientes funciones se pueden implementar en un fragmento de sombreador de vértices:

  • void MAIN() Cuando está presente, esta función se invoca para establecer el valor de POSITION, la salida vec4 del sombreador de vértices, y, opcionalmente, para modificar los valores de VERTEX, COLOR, NORMAL, UV0, UV1, TANGENT, BINORMAL, JOINTS y WEIGHTS. A diferencia de lo que ocurre con los materiales sin sombreado, tiene sentido escribir en ellos porque los valores modificados se tienen en cuenta posteriormente en el resto del código de sombreador generado (mientras que, en el caso de los materiales sin sombreado, no se genera código de sombreador adicional). Por ejemplo, si el sombreador de vértices personalizado desplaza los vértices o las normales, querrá almacenar los valores modificados en VERTEX o NORMAL, para lograr posteriormente unos cálculos de iluminación correctos. Además, la función puede escribir en variables definidas con VARYING para pasar datos interpolados al sombreador de fragmentos. Cuando esta función o una redefinición de POSITION no está presente, POSITION se calcula basándose en VERTEX y MODELVIEWPROJECTION_MATRIX, tal y como lo haría un sombreador de vértices ( PrincipledMaterial ).

    Ejemplo, en el que se recurre tanto a las propiedades QML expuestas como uniformes como al envío de datos al sombreador de fragmentos:

    VARYING vec3 vNormal;
    VARYING vec3 vViewVec;
    
    void MAIN()
    {
        VERTEX.x += sin(uTime * 4.0 + VERTEX.y) * uAmplitude;
        vNormal = normalize(NORMAL_MATRIX * NORMAL);
        vViewVec = CAMERA_POSITION - (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz;
        POSITION = MODELVIEWPROJECTION_MATRIX * vec4(VERTEX, 1.0);
    }

    Nota: En el ejemplo anterior, asignar un valor a POSITION es opcional, ya que el uso en este caso es idéntico al comportamiento por defecto.

Nota: Para pasar datos sin interpolación desde la etapa de vértices a la de fragmentos, añade la palabra clave « flat » antes del tipo en las declaraciones « VARYING ».

Fragmentos de código del sombreador de fragmentos en un material personalizado con sombreado

Las siguientes funciones se pueden implementar en un fragmento de sombreador de fragmentos:

  • void MAIN() Cuando está presente, esta función se invoca para establecer los valores de las variables especiales modificables BASE_COLOR, METALNESS, ROUGHNESS, SPECULAR_AMOUNT, NORMAL, CLEARCOAT_FRESNEL_POWER, CLEARCOAT_FRESNEL_SCALE, CLEARCOAT_FRESNEL_BIAS, CLEARCOAT_AMOUNT, CLEARCOAT_ROUGHNESS, CLEARCOAT_NORMAL, FRESNEL_BIAS, FRESNEL_SCALE, FRESNEL_POWER, IOR, TRANSMISSION_FACTOR, THICKNESS_FACTOR, ATTENUATION_COLOR, ATTENUATION_DISTANCE y OCCLUSION_AMOUNT.

    Un caso de uso habitual es establecer el valor de « BASE_COLOR » basándose en el muestreo de una textura, ya sea un mapa de color base, « SCREEN_TEXTURE » o cualquier otro tipo de fuente. Esto puede resultar relevante y práctico, especialmente cuando no se han implementado funciones personalizadas del procesador de luz. Establecer « BASE_COLOR.a » en un valor distinto del predeterminado 1,0 permite modificar el valor alfa final del fragmento. (Ten en cuenta que esto a menudo requerirá también habilitar la mezcla alfa en sourceBlend y destinationBlend).

    Otro caso es cuando no se ha proporcionado una función personalizada de « SPECULAR_LIGHT », o cuando hay una sonda de luz configurada en SceneEnvironment. La metalicidad, la rugosidad y otros valores que afectan al cálculo de la contribución especular se pueden establecer en MAIN con los valores personalizados deseados.

    La función puede escribir en las siguientes variables especiales. Los valores que se escriben en ellas suelen estar codificados de forma fija o calcularse a partir de propiedades QML asignadas a variables uniformes. La semántica es idéntica a la de PrincipledMaterial.

    • vec4 BASE_COLOR: el color base y el valor alfa del material. Se corresponde con built-in materials' color property. Cuando no se han implementado funciones del procesador de luz, puede resultar conveniente establecer un color base personalizado en MAIN, ya que así se tendrá en cuenta en los cálculos de iluminación predeterminados. El valor por defecto es vec4(1.0), lo que significa blanco con un alfa de 1,0. El valor alfa afecta al alfa final del fragmento. El valor alfa final es la opacidad del objeto (modelo) multiplicada por el alfa del color base. Al especificar el valor directamente en el código del shader, sin basarse en los valores uniformes expuestos desde las propiedades de color en QML, hay que tener en cuenta que es el shader el que debe realizar la conversión de sRGB a lineal, si es necesario. Por ejemplo, suponiendo que vec3 color y float alpha, esto se puede lograr de la siguiente manera:
      float C1 = 0.305306011;
      vec3 C2 = vec3(0.682171111, 0.682171111, 0.682171111);
      vec3 C3 = vec3(0.012522878, 0.012522878, 0.012522878);
      BASE_COLOR = vec4(rgb * (rgb * (rgb * C1 + C2) + C3), alpha);
    • vec3 EMISSIVE_COLOR: el color de la autoiluminación. Corresponde al color emisivo de los materiales integrados, que se combina mediante built-in materials's emissiveFactor property y built-in materials's emissiveMap property. El valor por defecto es vec3(0.0). Al especificar el valor directamente en el código del sombreador, sin basarse en los valores uniformes expuestos a partir de las propiedades de color en QML, hay que tener en cuenta que es el sombreador el que debe realizar la conversión de sRGB a lineal, si es necesario.
    • float IOR Especifica el índice de refracción del material. Un valor típico, y también el predeterminado, es 1.5, ya que es el que utilizaría un PrincipledMaterial.
    • float TRANSMISSION_FACTOR Especifica el grado de translucidez. Un valor típico —y también el predeterminado— sería 1.0, ya que es el que utilizaría un 0.0, tal y como lo haría un PrincipledMaterial.
    • 0.0 float THICKNESS_FACTOR Especifica el grosor del material translúcido. Un valor típico, que también es el predeterminado, sería 10.0, ya que es el que utilizaría un PrincipledMaterial.
    • vec3 ATTENUATION_COLOR Especifica el cambio de color del material translúcido en función de la distancia. Un valor típico sería vec3(1.0, 0.0, 0.0) y, además, el valor por defecto es vec3(1.0), ya que es el que utilizaría un PrincipledMaterial.
    • float ATTENUATION_DISTANCE Especifica la atenuación por distancia del cambio de color del material translúcido. Un valor típico —y también el predeterminado— sería 100.0, y 0.0, ya que es el que utilizaría un PrincipledMaterial.
    • float METALNESS Nivel de metalicidad en el rango de 0,0 a 1,0. El valor por defecto es 0. Debe establecerse en un valor distinto de cero para que surta efecto.
    • float ROUGHNESS Valor de rugosidad en el rango de 0,0 a 1,0. El valor por defecto es 0.
    • float CLEARCOAT_FRESNEL_POWER Especifica la potencia de Fresnel de la capa de barniz transparente. Un valor típico, y también el predeterminado, es 5.0, ya que es el que utilizaría un PrincipledMaterial.
    • float CLEARCOAT_FRESNEL_SCALE Especifica la escala de Fresnel de la capa de barniz transparente. Un valor típico, y también el predeterminado, es 1.0, ya que es el que utilizaría un PrincipledMaterial.
    • float CLEARCOAT_FRESNEL_BIAS Especifica el sesgo de Fresnel de la capa de barniz transparente. Un valor típico, y también el predeterminado, es 0.0, ya que es el que utilizaría un « PrincipledMaterial ».
    • float CLEARCOAT_AMOUNT Especifica la cantidad de capa de barniz transparente sobre el material. Un valor típico, y también el predeterminado, sería 1.0 y 0.0, ya que es lo que utilizaría un PrincipledMaterial.
    • float CLEARCOAT_ROUGHNESS Especifica la rugosidad de la capa de barniz transparente. Un valor típico sería 1.0 para una capa de barniz totalmente difuminada; el valor por defecto es 0.0, ya que es el que utilizaría un PrincipledMaterial.
    • vec3 CLEARCOAT_NORMAL: la normal de la capa de barniz que proviene del sombreador de vértices en el espacio mundial. Aunque esta propiedad tiene el mismo valor inicial que VAR_WORLD_NORMAL, solo el cambio del valor de CLEARCOAT_NORMAL tendrá efecto sobre la normal de la capa de barniz.
    • float FRESNEL_POWER Especifica la potencia de Fresnel. Un valor típico, y también el predeterminado, es 5.0, ya que es el que utilizaría un PrincipledMaterial.
    • float FRESNEL_SCALE Especifica la escala de Fresnel. Un valor típico, y también el predeterminado, es 1.0, ya que es el que utilizaría un PrincipledMaterial.
    • float FRESNEL_BIAS Especifica el sesgo de Fresnel. Un valor típico, y también el predeterminado, es 0.0, ya que es el que utilizaría un PrincipledMaterial.
    • float SPECULAR_AMOUNT Cantidad especular en el rango de 0,0 a 1,0. El valor por defecto es 0.5, que coincide con PrincipledMaterial::specularAmount. Debe establecerse en un valor distinto de cero para que surta efecto.
    • float OCCLUSION_AMOUNT Especifica el factor AO. Un valor típico, y también el predeterminado, es 1.0, ya que es el que utilizaría un PrincipledMaterial.
    • vec3 NORMAL: la normal procedente del sombreador de vértices en el espacio mundial. Aunque esta propiedad tiene el mismo valor inicial que VAR_WORLD_NORMAL, solo el cambio del valor de NORMAL tendrá efecto sobre la iluminación.
    • vec3 TANGENT: la tangente procedente del sombreador de vértices en el espacio del mundo. Este valor puede ajustarse en función de si la superficie es de doble cara.
    • vec3 BINORMAL: la binormal procedente del sombreador de vértices en el espacio mundial. Este valor puede ajustarse para tener en cuenta la doble cara.
    • vec2 UV0: el primer conjunto de coordenadas de textura procedente del sombreador de vértices. Esta propiedad es de solo lectura en el sombreador de fragmentos.
    • vec2 UV1: el segundo conjunto de coordenadas de textura procedente del sombreador de vértices. Esta propiedad es de solo lectura en el sombreador de fragmentos.

    Nota: A diferencia de lo que ocurre con los materiales sin sombreado, el «fragment MAIN » de un material sombreado no tiene control directo sobre « FRAGCOLOR ». En su lugar, son los valores « DIFFUSE » y « SPECULAR » escritos en las funciones del procesador de luz los que determinan cuál es el color final del fragmento. Cuando no se implementa una función del procesador de luz, se realizan los cálculos de sombreado predeterminados pertinentes, al igual que con un « PrincipledMaterial », teniendo en cuenta « BASE_COLOR » y otros valores de la lista anterior.

    Un ejemplo de un shader sencillo y personalizado con un material metálico podría ser el siguiente:

    void MAIN()
    {
        METALNESS = 1.0;
        ROUGHNESS = 0.5;
        FRESNEL_POWER = 5.0;
    }

    Otro ejemplo, en el que el color base y el alfa se establecen mediante el muestreo de una textura:

    VARYING vec2 texcoord;
    void MAIN()
    {
        BASE_COLOR = texture(uColorMap, texcoord);
    }
  • void AMBIENT_LIGHT() Cuando está presente, esta función se invoca una vez por cada fragmento. La tarea de la función es sumar la contribución ambiental total a una variable especial modificable, ` DIFFUSE`. Por supuesto, puede optar por calcular un valor diferente o no modificar en absoluto ` DIFFUSE ` (para ignorar por completo la iluminación ambiental). Cuando esta función no está presente en absoluto, la contribución ambiental se calcula normalmente, tal y como lo haría una función « PrincipledMaterial ».

    La función puede escribir en las siguientes variables especiales:

    • vec3 DIFFUSE Acumula las contribuciones de luz difusa, por fragmento. Las funciones del procesador de luz suelen sumarle (+=), ya que sobrescribir el valor haría que se perdiera la contribución de otras luces.

    La función puede leer las siguientes variables especiales, además de las variables uniformes de matriz (como MODEL_MATRIX) y de vector (como CAMERA_POSITION) de la tabla anterior:

    • vec3 TOTAL_AMBIENT_COLOR La contribución ambiental total en la escena.

    Ejemplo:

    void AMBIENT_LIGHT()
    {
        DIFFUSE += TOTAL_AMBIENT_COLOR;
    }
  • void DIRECTIONAL_LIGHT() Cuando está presente, esta función se invoca para cada luz direccional activa en la escena por cada fragmento. La tarea de la función es sumar la contribución difusa a una variable especial modificable DIFFUSE. La función también puede optar por no hacer nada, en cuyo caso se ignoran las contribuciones difusas de las luces direccionales. Cuando la función no está presente en absoluto, las contribuciones difusas de las luces direccionales se acumulan normalmente, tal y como lo haría un « PrincipledMaterial ».

    La función puede escribir en las siguientes variables especiales:

    • vec3 DIFFUSE Acumula las contribuciones de luz difusa, por fragmento. Las funciones del procesador de luz suelen sumarle (+=), ya que sobrescribir el valor supondría perder la contribución de otras luces.

    La función puede leer las siguientes variables especiales, además de las uniformes de matriz (como MODEL_MATRIX) y de vector (como CAMERA_POSITION) de la tabla anterior:

    • vec3 LIGHT_COLOR Color de la luz difusa.
    • float SHADOW_CONTRIB Contribución de la sombra, o 1,0 si no hay sombra alguna o si no recibe sombras.
    • vec3 TO_LIGHT_DIR Vector que apunta hacia la fuente de luz.
    • vec3 NORMAL El vector normal en el espacio mundial.
    • vec4 BASE_COLOR El color base y el valor alfa del material.
    • float METALNESS La cantidad de metalicidad.
    • float ROUGHNESS La cantidad de rugosidad.

    Ejemplo:

    void DIRECTIONAL_LIGHT()
    {
        DIFFUSE += LIGHT_COLOR * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
    }
  • void POINT_LIGHT() Cuando está presente, esta función se invoca para cada luz puntual activa de la escena y para cada fragmento. La tarea de la función es añadir la contribución difusa a una variable especial modificable DIFFUSE. La función también puede optar por no hacer nada, en cuyo caso se ignoran las contribuciones difusas de las luces puntuales. Cuando la función no está presente en absoluto, las contribuciones difusas de las luces puntuales se acumulan normalmente, tal y como lo haría una función « PrincipledMaterial ».

    La función puede escribir en las siguientes variables especiales:

    • vec3 DIFFUSE Acumula las contribuciones de luz difusa, por fragmento.

    La función puede leer las siguientes variables especiales, además de los uniformes de matriz (como MODEL_MATRIX) y de vector (como CAMERA_POSITION) de la tabla anterior:

    • vec3 LIGHT_COLOR Color de la luz difusa.
    • float LIGHT_ATTENUATION Atenuación de la luz.
    • float SHADOW_CONTRIB Contribución de la sombra, o 1,0 si no hay sombra alguna o si no recibe sombras.
    • vec3 TO_LIGHT_DIR Vector que apunta hacia la fuente de luz.
    • vec3 NORMAL El vector normal en el espacio mundial.
    • vec4 BASE_COLOR El color base y el valor alfa del material.
    • float METALNESS La cantidad de metalicidad.
    • float ROUGHNESS La cantidad de rugosidad.

    Ejemplo:

    void POINT_LIGHT()
    {
        DIFFUSE += LIGHT_COLOR * LIGHT_ATTENUATION * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
    }
  • void SPOT_LIGHT() Cuando está presente, esta función se invoca para cada luz puntual activa de la escena y para cada fragmento. La tarea de la función es añadir la contribución difusa a una variable especial modificable DIFFUSE. La función también puede optar por no hacer nada, en cuyo caso se ignoran las contribuciones difusas de las luces puntuales. Cuando la función no está presente en absoluto, las contribuciones difusas de los focos puntuales se acumulan normalmente, tal y como lo haría un « PrincipledMaterial ».

    La función puede escribir en las siguientes variables especiales:

    • vec3 DIFFUSE Acumula las contribuciones de luz difusa, por fragmento.

    La función puede leer las siguientes variables especiales, además de los uniformes de matriz (como MODEL_MATRIX) y de vector (como CAMERA_POSITION) de la tabla anterior:

    • vec3 LIGHT_COLOR Color de la luz difusa.
    • float LIGHT_ATTENUATION Atenuación de la luz.
    • float SHADOW_CONTRIB Contribución de la sombra, o 1,0 si no hay sombra alguna o si no se reciben sombras.
    • vec3 TO_LIGHT_DIR Vector que apunta hacia la fuente de luz.
    • float SPOT_FACTOR Factor de luz puntual.
    • vec3 NORMAL El vector normal en el espacio mundial.
    • vec4 BASE_COLOR El color base y el valor alfa del material.
    • float METALNESS La cantidad de metalicidad.
    • float ROUGHNESS La cantidad de rugosidad.

    Ejemplo:

    void SPOT_LIGHT()
    {
        DIFFUSE += LIGHT_COLOR * LIGHT_ATTENUATION * SPOT_FACTOR * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
    }
  • void SPECULAR_LIGHT() Cuando está presente, esta función se invoca para cada luz activa de la escena y para cada fragmento. La tarea de la función es añadir la contribución especular a una variable especial modificable SPECULAR. La función también puede optar por no hacer nada, en cuyo caso se ignoran las contribuciones especulares de las luces. Cuando la función no está presente en absoluto, las contribuciones especulares de las luces se acumulan normalmente, tal y como lo haría un « PrincipledMaterial ».

    La función puede escribir en las siguientes variables especiales:

    • vec3 SPECULAR Acumula las contribuciones especulares de la luz, por fragmento. Las funciones del procesador de luz suelen sumarle (+=), ya que sobrescribir el valor haría que se perdiera la contribución de otras luces.

    La función puede leer las siguientes variables especiales, además de los uniformes de matriz (como MODEL_MATRIX) y de vector (como CAMERA_POSITION) de la tabla anterior:

    • vec3 LIGHT_COLOR Color de la luz especular.
    • float LIGHT_ATTENUATION Atenuación de la luz. Para luces direccionales, el valor es 1,0. Para luces puntuales, el valor es el mismo que « LIGHT_ATTENUATION * SPOT_FACTOR » de « void SPOT_LIGHT() ».
    • float SHADOW_CONTRIB Contribución de la sombra, o 1,0 si no hay sombra alguna o si no se reciben sombras.
    • vec3 FRESNEL_CONTRIB Contribución de Fresnel procedente del cálculo de Fresnel integrado.
    • vec3 TO_LIGHT_DIR Vector que apunta hacia la fuente de luz.
    • vec3 NORMAL El vector normal en el espacio mundial.
    • vec4 BASE_COLOR El color base y el valor alfa del material.
    • float METALNESS La cantidad de metalicidad.
    • float ROUGHNESS La cantidad de rugosidad.
    • float SPECULAR_AMOUNT El valor de «specular». Este valor estará entre 0,0 y 1,0 y será el mismo que el establecido en la función personalizada MAIN. Este valor resultará útil para calcular las contribuciones de Fresnel cuando no se utilice la contribución de Fresnel integrada que proporciona FRESNEL_CONTRIB.
    void SPECULAR_LIGHT()
    {
        vec3 H = normalize(VIEW_VECTOR + TO_LIGHT_DIR);
        float cosAlpha = max(0.0, dot(H, normalize(NORMAL)));
        float shine = pow(cosAlpha, exp2(15.0 * (1.0 - ROUGHNESS) + 1.0) * 0.25);
        SPECULAR += shine * LIGHT_COLOR * FRESNEL_CONTRIB * SHADOW_CONTRIB * LIGHT_ATTENUATION;
    }
  • void POST_PROCESS() Cuando está presente, esta función se invoca al final del proceso de fragmentos. La tarea de la función es finalizar COLOR_SUM con los términos difusos, especulares y emisivos finales. A diferencia de FRAGCOLOR para un material sin sombreado, COLOR_SUM se someterá automáticamente a un mapeo de tonos antes de escribirse en el búfer de fotogramas. A efectos de depuración, a veces resulta útil generar un valor que no deba tratarse como un color. Para evitar que el mapeo de tonos distorsione este valor, se puede desactivar estableciendo la propiedad « tonemapMode » en

    «

    TonemapModeNone

    ». La función puede escribir en las siguientes variables especiales:

    • vec4 COLOR_SUM: la salida del sombreador de fragmentos. El valor por defecto es vec4(DIFFUSE.rgb + SPECULAR + EMISSIVE, DIFFUSE.a)

    La función puede leer las siguientes variables especiales.

    • vec4 DIFFUSE: el término difuso final del proceso de fragmentos.
    • vec3 SPECULAR: el término especular final del proceso de fragmentos.
    • vec3 EMISSIVE: el término emisivo final del proceso de fragmentos.
    • vec2 UV0: el primer conjunto de coordenadas de textura del sombreador de vértices.
    • vec2 UV1 - El segundo conjunto de coordenadas de textura del sombreador de vértices.
    void POST_PROCESS()
    {
        float center_x = textureSize(SCREEN_TEXTURE, 0).x * 0.5;
        if (gl_FragCoord.x > center_x)
            COLOR_SUM = DIFFUSE;
        else
            COLOR_SUM = vec4(EMISSIVE, DIFFUSE.a);
    }
  • void IBL_PROBE() Cuando está presente, esta función se invoca para la iluminación basada en imágenes (IBL). La tarea de la función es sumar las contribuciones tanto difusas como especulares de la IBL a las variables especiales modificables DIFFUSE y SPECULAR.

    La función puede escribir en las siguientes variables especiales:

    • vec3 DIFFUSE Acumula las contribuciones de luz difusa, por fragmento.
    • vec3 SPECULAR Acumula las contribuciones de luz especular, por fragmento.

    La función puede leer las siguientes variables especiales.

    • vec4 BASE_COLOR El color base y el valor alfa del material.
    • float AO_FACTOR El factor de oclusión en el espacio de pantalla.
    • float SPECULAR_AMOUNT La cantidad especular.
    • float ROUGHNESS El término emisivo final del proceso de fragmentos.
    • vec3 NORMAL El vector normal en el espacio mundial.
    • vec3 VIEW_VECTOR Apunta hacia la cámara.
    • mat3 IBL_ORIENTATION La orientación de la sonda de luz. Proviene de SceneEnvironment::probeOrientation.
    void IBL_PROBE()
    {
        vec3 smpDir = IBL_ORIENTATION * NORMAL;
        DIFFUSE += AO_FACTOR * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, smpDir, IBL_MAXMIPMAP).rgb;
    }
  • Variables personalizadas entre funciones

    Se pueden pasar variables adicionales desde la función MAIN a las demás. La palabra clave SHARED_VARS se puede utilizar para definir nuevas variables personalizadas. Se puede acceder a estas variables definidas por el usuario mediante SHARED.<nombre de la variable>.

    Por ejemplo, un material personalizado con sombreado puede obtener un valor compartido en la función MAIN y utilizarlo en otras funciones.

    SHARED_VARS {
        vec3 colorThreshold;
    };
    void MAIN()
    {
        BASE_COLOR = texture(baseColorMap, UV0);
        SHARED.colorThreshold = texture(thresholdMap, UV0).rgb;
    }
    void DIRECTIONAL_LIGHT()
    {
        if (DIFFUSE >= SHARED.colorThreshold) {
            DIFFUSE = SHARED.colorThreshold;
            return;
        }
        DIFFUSE += LIGHT_COLOR * SHADOW_CONTRIB;
    }

    Nota: Se puede escribir«SHARED» en todas las funciones que no contengan «POST_PROCESS», pero lo más seguro es escribirlo en «MAIN» y leerlo en las demás funciones.

    Nota: Un caso de uso recomendado para escribir SHARED en las funciones LIGHT es restablecerlo primero en MAIN y, a continuación, acumularlo en cada una de las funciones LIGHT.

    SHARED_VARS {
        float sheenIntensity;
        float sheenRoughness;
        vec3 sheenColor;
        vec3 outSheenColor;
    };
    void MAIN()
    {
        ...
        vec4 tex = texture(uSheenMap, UV0);
        SHARED.sheenColor = tex.rgb;
        SHARED.sheenIntensity = tex.a;
        SHARED.sheenRoughness = uSheenRoughness;
        SHARED.outSheenColor = vec3(0.0);
    }
    void SPECULAR_LIGHT()
    {
        SHARED.outSheenColor += ...;
    }
    void POST_PROCESS()
    {
        COLOR_SUM = DIFFUSE + SPECULAR + EMISSIVE + SHARED.outSheenColor;
    }

    Nota: MAIN se invoca antes que las demás, y POST_PROCESS después de todas las demás, pero no hay garantía de que se mantenga ningún otro orden para los procesadores LIGHT.

    Palabras clave especiales adicionales

    El código del sombreador de fragmentos personalizado puede acceder libremente a los uniformes (como CAMERA_DIRECTION o CAMERA_POSITION) y a los «varyings» pasados desde el sombreador de vértices personalizado. Además, hay una serie de «varyings» integrados disponibles como palabras clave especiales. Algunas de ellas son opcionales, en el sentido de que un «vertex MAIN » podría calcularlas y pasarlas por sí mismo, pero, para reducir la duplicación de datos, los «fragment shaders» también pueden recurrir a estas variables integradas. Estas variables integradas están disponibles en las funciones de los procesadores ligeros y en la función MAIN del fragmento.

    • vec3 VAR_WORLD_NORMAL: normal interpolada transformada mediante NORMAL_MATRIX.
    • vec3 VAR_WORLD_TANGENT: tangente interpolada transformada mediante MODEL_MATRIX.
    • vec3 VAR_WORLD_BINORMAL - Binormal interpolada transformada por MODEL_MATRIX
    • vec3 NORMAL - A diferencia de VAR_WORLD_NORMAL, que es la normal interpolada tal cual, este valor puede ajustarse para tener en cuenta la doble cara: al renderizar con el culling desactivado, la normal se invertirá según sea necesario. Por lo tanto, se recomienda utilizar NORMAL en lugar de VAR_WORLD_NORMAL en los cálculos de iluminación y de otro tipo, para que funcionen correctamente con todos los modos de culling.
    • vec3 TANGENT - Al igual que NORMAL, este valor puede ajustarse para tener en cuenta la doble cara: al renderizar con el culling desactivado, la tangente se invertirá según sea necesario.
    • vec3 BINORMAL: al igual que NORMAL, este valor puede ajustarse para tener en cuenta la doble cara: al renderizar con el culling desactivado, la binormal se invertirá según sea necesario.
    • vec3 VAR_WORLD_POSITION - Posición interpolada del vértice en el espacio mundial ((MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz)
    • vec4 VAR_COLOR - El color del vértice interpolado cuando se proporcionan colores en la malla. De lo contrario, vec4(1.0).
    • vec3 VIEW_VECTOR: apunta hacia la cámara. Se trata, en la práctica, del vector CAMERA_POSITION - VAR_WORLD_POSITION normalizado.
    • vec4 FRAGCOORD: contiene las coordenadas relativas a la ventana del fragmento actual.
    • float FRAMEBUFFER_Y_UP: el valor es 1 cuando el eje Y apunta hacia arriba en el sistema de coordenadas de los framebuffers (texturas), lo que significa que (0, 0) es la esquina inferior izquierda. El valor es -1 cuando el eje Y apunta hacia abajo, siendo (0, 0) la esquina superior izquierda. Estas diferencias en las API gráficas subyacentes no afectan a la mayoría de los materiales personalizados. Una excepción notable es el muestreo de SCREEN_TEXTURE con coordenadas de textura que no se basan en FRAGCOORD. Dado que la orientación de SCREEN_TEXTURE está vinculada por naturaleza a la API gráfica subyacente, el uso de coordenadas de textura de una malla puede requerir ajustes adecuados en la coordenada Y.

      Por ejemplo, el siguiente sombreador de fragmentos, adecuado para mallas de tipo «Rectangle» o «Cube», mostrará los objetos opacos de la escena sobre el modelo:

      VARYING vec2 texcoord;
      void MAIN()
      {
          vec2 screencoord = texcoord;
          if (FRAMEBUFFER_Y_UP < 0.0) // effectively: if not OpenGL
              screencoord.y = 1.0 - screencoord.y;
          BASE_COLOR = texture(SCREEN_TEXTURE, screencoord);
      }

      Al muestrear texturas distintas de SCREEN_TEXTURE y DEPTH_TEXTURE, o cuando se utiliza FRAGCOORD para calcular la coordenada de textura (lo que sería el caso de uso típico para acceder a las texturas de pantalla y de profundidad), dicho ajuste no es necesario.

    • float NDC_Y_UP: el valor es 1 cuando el eje Y apunta hacia arriba en el espacio de coordenadas normalizadas del dispositivo, y -1 cuando el eje Y apunta hacia abajo. El eje Y apunta hacia abajo cuando el renderizado se realiza con Vulkan. La mayoría de los materiales no tienen por qué preocuparse por esto, pero poder realizar una ramificación en función de ello puede resultar útil en determinados casos de uso avanzados.
    • float NEAR_CLIP_VALUE - El valor es -1 cuando el rango del plano de recorte comienza en -1 y llega hasta 1. Esto es así cuando se utiliza OpenGL para el renderizado. Para otros backends de renderizado, el valor de esta propiedad será 0, lo que significa que el rango del plano de recorte va de 0 a 1. Este valor resulta útil con ciertas técnicas que implican el DEPTH_TEXTURE

      Por ejemplo, el siguiente sombreador de fragmentos muestra una técnica para reconstruir la posición de un valor a partir del búfer de profundidad con el fin de determinar la distancia desde la posición actual que se está renderizando. Cuando se utiliza en combinación con INVERSE_PROJECTION_MATRIX, el valor de profundidad debe estar en coordenadas normalizadas del dispositivo, por lo que es importante asegurarse de que el rango del valor de profundidad refleje esto. Cuando el valor « NEAR_CLIP_VALUE » es « -1 », el valor de profundidad se escala para que esté comprendido entre « -1 » y « 1 ».

      void MAIN() {
          vec2 screen_uv = FRAGCOORD.xy / vec2(textureSize(SCREEN_TEXTURE, 0));
          float depth = texture(DEPTH_TEXTURE, screen_uv).r;
      
          if (NEAR_CLIP_VALUE < 0.0) // effectively: if opengl
              depth = depth * 2.0 - 1.0;
      
          vec4 unproject = INVERSE_PROJECTION_MATRIX * vec4(screen_uv, depth, 1.0);
          depth = (unproject.xyz / unproject.w).z;
          float viewVectorZ = (VIEW_MATRIX * vec4(VAR_WORLD_POSITION, 1.0)).z;
          depth = viewVectorZ - depth;
      
          BASE_COLOR = vec4(depth, depth, depth, 1.0);
      }
    • float IBL_EXPOSE: la cantidad de luz emitida por la sonda de luz. Se obtiene de SceneEnvironment::probeExposure.
      DIFFUSE += AO_FACTOR * IBL_EXPOSE * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, NORMAL, IBL_MAXMIPMAP).rgb;
    • float IBL_HORIZON: el valor de corte horizontal de los reflejos procedentes de la mitad inferior del entorno. Se obtiene de Horizon Cut-Off, pero se reasigna al intervalo [-1, 0).
      vec3 diffuse += AO_FACTOR * IBL_EXPOSE * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, NORMAL, IBL_MAXMIPMAP).rgb;
      if (IBL_HORIZON > -1.0) {
          float ctr = 0.5 + 0.5 * IBL_HORIZON;
          float vertWt = smoothstep(ctr * 0.25, ctr + 0.25, NORMAL.y);
          float wtScaled = mix(1.0, vertWt, IBL_HORIZON + 1.0);
          diffuse *= wtScaled;
      }
    • float IBL_MAXMIPMAP: el nivel máximo de mipmap de IBL_TEXTURE.

    Instanciación

    Al realizar un renderizado instanciado, algunas de las palabras clave anteriores no son aplicables. Las siguientes palabras clave solo están disponibles con la instanciación:

    • INSTANCE_MODEL_MATRIX -> mat4, sustituto de « MODEL_MATRIX », que incluye la transformación de instanciación.
    • INSTANCE_MODELVIEWPROJECTION_MATRIX -> mat4, sustituye a « MODELVIEWPROJECTION_MATRIX », e incluye la transformación de instanciación.
    • INSTANCE_COLOR -> vec4, el color de la instancia: se debe combinar con ` COLOR`.
    • INSTANCE_DATA -> vec4, datos personalizados de la instancia.
    • INSTANCE_INDEX -> int: el número de instancia y el índice en la tabla de instanciación.

    Texturas de pantalla, profundidad y otras texturas

    El proceso de renderizado puede proporcionar una serie de texturas a los sombreadores de materiales personalizados con contenido procedente de pasadas de renderizado especiales. Esto se aplica tanto a los materiales personalizados con sombreado como a los que carecen de él.

    Por ejemplo, un sombreador puede necesitar acceder a una textura de profundidad que contenga el contenido del búfer de profundidad de los objetos opacos de la escena. Esto se consigue muestreando DEPTH_TEXTURE. Normalmente, este tipo de textura no se genera, a menos que exista una necesidad real de ella. Por lo tanto, la presencia de las siguientes palabras clave en el sombreador de vértices o de fragmentos también actúa como un conmutador para activar las pasadas —potencialmente costosas— destinadas a generar la textura en cuestión. (Por supuesto, es posible que algunas de ellas ya estén habilitadas debido a otros ajustes, como los parámetros de oclusión ambiental en SceneEnvironment o debido a un efecto de posprocesamiento que se base en la textura de profundidad; en tal caso, las texturas en cuestión se generan independientemente del material personalizado, por lo que el muestreo de estas texturas especiales en el material no supone ningún coste adicional, aparte del propio acceso a la textura)

    • SCREEN_TEXTURE - Cuando está presente, se expone al sombreador, bajo este nombre, una textura (sampler2D o sampler2DArray) con el búfer de color de un paso de renderizado que contiene el contenido de la escena, excluyendo cualquier material transparente o cualquier material que también utilice la SCREEN_TEXTURE. La textura se puede utilizar para técnicas que requieran el contenido del búfer de fotogramas en el que se están renderizando. La textura SCREEN_TEXTURE utiliza el mismo modo de borrado que View3D. El tamaño de estas texturas coincide con el tamaño de View3D en píxeles. Por ejemplo, un sombreador de fragmentos podría contener lo siguiente:
      vec2 uv = FRAGCOORD.xy / vec2(textureSize(SCREEN_TEXTURE, 0));
      vec2 displace = vec2(0.1);
      vec4 c = texture(SCREEN_TEXTURE, uv + displace);

      Ten en cuenta que el uso de SCREEN_TEXTURE requiere un diseño adecuado y consciente de la escena. Los objetos que utilicen dichos materiales deben colocarse con cuidado, normalmente por encima de todos los demás objetos que se espera que sean visibles en la textura. Los objetos que emplean semitransparencia de algún tipo nunca forman parte de la « SCREEN_TEXTURE ». A menudo, « SCREEN_TEXTURE » se utilizará en combinación con « BASE_COLOR » en « MAIN ». Por ejemplo, el siguiente sombreador de fragmentos personalizado aplica un efecto de relieve, al tiempo que mantiene transparentes los fragmentos que no son tocados por objetos opacos. Esto supone que el objeto con el material está situado en primer plano y que tiene habilitada la mezcla.

      void MAIN()
      {
          vec2 size = vec2(textureSize(SCREEN_TEXTURE, 0));
          vec2 uv = FRAGCOORD.xy / size;
      
          // basic emboss effect
          vec2 d = vec2(1.0 / size.x, 1.0 / size.y);
          vec4 diff = texture(SCREEN_TEXTURE, uv + d) - texture(SCREEN_TEXTURE, uv - d);
          float c = (diff.x + diff.y + diff.z) + 0.5;
      
          float alpha = texture(SCREEN_TEXTURE, uv).a;
          BASE_COLOR = vec4(vec3(c), alpha);
      }

      Con el renderizado multivista, ` SCREEN_TEXTURE ` es un ` sampler2DArray`. Utiliza ` VIEW_INDEX ` para seleccionar la capa que se va a utilizar. Para aplicaciones de RV/RA que deseen admitir ambos tipos de renderizado, el enfoque portátil es el siguiente:

      #if QSHADER_VIEW_COUNT >= 2
          vec4 c = texture(SCREEN_TEXTURE, vec3(uv, VIEW_INDEX));
      #else
          vec4 c = texture(SCREEN_TEXTURE, uv);
      #endif
    • SCREEN_MIP_TEXTURE - Idéntico a ` SCREEN_TEXTURE ` en la mayoría de los aspectos, con la diferencia de que esta textura tiene mipmaps generados. Esta característica puede suponer un coste elevado en términos de rendimiento, dependiendo del tamaño de la pantalla, y debido a que hay que generar los mipmaps cada vez que se renderiza la escena. Por lo tanto, es preferible utilizar siempre SCREEN_TEXTURE, a menos que el material personalizado implemente una técnica que dependa de los niveles de mip de la textura (por ejemplo, utilizando textureLod en el shader).
    • DEPTH_TEXTURE - Cuando está presente, se expone al sombreador, bajo este nombre, una textura (sampler2D o sampler2DArray) con el contenido (no linealizado) del búfer de profundidad. Solo se incluyen los objetos opacos. Por ejemplo, un sombreador de fragmentos podría contener lo siguiente:
      ivec2 dtSize = textureSize(DEPTH_TEXTURE, 0);
      vec2 dtUV = (FRAGCOORD.xy) / vec2(dtSize);
      vec4 depthSample = texture(DEPTH_TEXTURE, dtUV);
      float zNear = CAMERA_PROPERTIES.x;
      float zFar = CAMERA_PROPERTIES.y;
      float zRange = zFar - zNear;
      float z_n = 2.0 * depthSample.r - 1.0;
      float d = 2.0 * zNear * zFar / (zFar + zNear - z_n * zRange);
      d /= zFar;

      Con el renderizado multivista, DEPTH_TEXTURE es un sampler2DArray. Utiliza VIEW_INDEX para seleccionar la capa que se va a utilizar. Para aplicaciones de RV/RA que deseen admitir ambos tipos de renderizado, el enfoque portátil es el siguiente:

      #if QSHADER_VIEW_COUNT >= 2
          vec4 depthSample = texture(DEPTH_TEXTURE, vec3(uv, VIEW_INDEX));
      #else
          vec4 depthSample = texture(DEPTH_TEXTURE, uv);
      #endif
    • NORMAL_ROUGHNESS_TEXTURE: cuando está presente, se expone al sombreador, bajo este nombre, una textura (sampler2D) con las normales en el espacio mundial y la rugosidad del material. Solo se incluyen los objetos opacos. La rugosidad se almacena en el canal alfa. Por ejemplo, un sombreador de fragmentos podría contener lo siguiente:
      vec3 N = normalize(texture(NORMAL_ROUGHNESS_TEXTURE, uv).rgb);
    • AO_TEXTURE - Cuando está presente y la oclusión ambiental en el espacio de pantalla está habilitada (es decir, cuando tanto la intensidad como la distancia de la AO son distintas de cero) en SceneEnvironment, la textura SSAO (sampler2D o sampler2DArray) se expone al sombreador con este nombre. Muestrear esta textura puede resultar útil en materiales sin sombreado. Los materiales sombreados incorporan de serie la compatibilidad con la oclusión ambiental. Esto significa que el factor de oclusión ambiental se tiene en cuenta automáticamente. En cambio, en un sombreador de fragmentos para un material sin sombreado, se podría escribir lo siguiente para conseguir lo mismo:
      ivec2 aoSize = textureSize(AO_TEXTURE, 0);
      vec2 aoUV = (FRAGCOORD.xy) / vec2(aoSize);
      float aoFactor = texture(AO_TEXTURE, aoUV).x;

      Con el renderizado multivista, ` AO_TEXTURE ` es un ` sampler2DArray`. Utiliza ` VIEW_INDEX ` para seleccionar la capa que se va a utilizar. Para aplicaciones de RV/RA que deseen admitir ambos tipos de renderizado, el enfoque portátil es el siguiente:

      #if QSHADER_VIEW_COUNT >= 2
          ivec2 aoSize = textureSize(AO_TEXTURE, 0).xy;
          vec2 aoUV = (FRAGCOORD.xy) / vec2(aoSize);
          float aoFactor = texture(AO_TEXTURE, vec3(aoUV, VIEW_INDEX)).x;
      #else
          ivec2 aoSize = textureSize(AO_TEXTURE, 0);
          vec2 aoUV = (FRAGCOORD.xy) / vec2(aoSize);
          float aoFactor = texture(AO_TEXTURE, aoUV).x;
      #endif
    • IBL_TEXTURE - No habilitará ninguna pasada de renderizado especial, pero se puede utilizar cuando el material tenga « Material::lightProbe » o el modelo se encuentre dentro del ámbito de « SceneEnvironment::lightProbe ».
      void IBL_PROBE()
      {
          DIFFUSE += AO_FACTOR * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, NORMAL, IBL_MAXMIPMAP).rgb;
      }
    • MOTION_VECTOR_TEXTURE — Habilita una pasada de renderizado dedicada que calcula los vectores de movimiento por objeto para la escena. El resultado es una textura de cuatro canales: los componentes R y G contienen los vectores de movimiento escalados de los modelos, mientras que los componentes B y A almacenan los vectores de movimiento sin escalar.
    • VIEW_INDEX - Cuando se utiliza en el código del sombreador personalizado, se trata de una variable uint (no interpolada). Cuando no se utiliza el renderizado multivista, el valor es siempre 0. Con el renderizado multivista, el valor es el índice de vista actual (p. ej., gl_ViewIndex). Resulta especialmente útil en combinación con DEPTH_TEXTURE y similares cuando se habilita el renderizado multivista.

    Véase también SceneEnvironment::tonemapMode, Uso de la iluminación basada en imágenes, Qt Quick 3D - Ejemplo de sombreadores personalizados, Qt Quick 3D - Ejemplo de materiales personalizados y Datos programables de materiales, efectos, geometría y texturas.

    Documentación de propiedades

    alwaysDirty : bool

    Especifica que el estado del material es siempre «sucio», lo que indica que el material debe actualizarse cada vez que lo utiliza el QtQuick3D.

    destinationAlphaBlend : enumeration [since 6.7]

    Especifica el factor de mezcla alfa de destino. El valor por defecto es « CustomMaterial.NoBlend ». Este valor solo se utiliza de forma efectiva si « sourceBlend » y « destinationBlend » se establecen en un valor distinto del predeterminado.

    ConstanteDescripción
    CustomMaterial.NoBlend 
    CustomMaterial.Zero 
    CustomMaterial.One 
    CustomMaterial.SrcColor 
    CustomMaterial.OneMinusSrcColor 
    CustomMaterial.DstColor 
    CustomMaterial.OneMinusDstColor 
    CustomMaterial.SrcAlpha 
    CustomMaterial.OneMinusSrcAlpha 
    CustomMaterial.DstAlpha 
    CustomMaterial.OneMinusDstAlpha 
    CustomMaterial.ConstantColor 
    CustomMaterial.OneMinusConstantColor 
    CustomMaterial.ConstantAlpha 
    CustomMaterial.OneMinusConstantAlpha 
    CustomMaterial.SrcAlphaSaturate

    Nota: Por motivos de compatibilidad con versiones anteriores, si se deja en su valor por defecto, se le asignará el mismo valor que a « destinationBlend » cuando « sourceBlend » y « destinationBlend » estén configurados con valores distintos de los predeterminados.

    Esta propiedad se introdujo en Qt 6.7.

    Véase también destinationBlend.

    destinationBlend : enumeration

    Especifica el factor de mezcla de destino. El valor por defecto es ` CustomMaterial.NoBlend`.

    ConstanteDescripción
    CustomMaterial.NoBlend 
    CustomMaterial.Zero 
    CustomMaterial.One 
    CustomMaterial.SrcColor 
    CustomMaterial.OneMinusSrcColor 
    CustomMaterial.DstColor 
    CustomMaterial.OneMinusDstColor 
    CustomMaterial.SrcAlpha 
    CustomMaterial.OneMinusSrcAlpha 
    CustomMaterial.DstAlpha 
    CustomMaterial.OneMinusDstAlpha 
    CustomMaterial.ConstantColor 
    CustomMaterial.OneMinusConstantColor 
    CustomMaterial.ConstantAlpha 
    CustomMaterial.OneMinusConstantAlpha 
    CustomMaterial.SrcAlphaSaturate

    Nota: Tanto « sourceBlend » como «destinationBlend» deben configurarse con un valor distinto del predeterminado antes de habilitar la fusión.

    Véase también « sourceBlend ».

    fragmentShader : url

    Especifica el archivo que contiene el fragmento de código del sombreador de fragmentos personalizado.

    El valor es una URL y debe ser un archivo local o utilizar el esquema qrc para acceder a archivos incrustados a través del sistema de recursos de Qt. También se aceptan rutas de archivo relativas (sin esquema); en ese caso, el archivo se considera relativo al componente (el archivo .qml ).

    Advertencia: Se da por hecho que los fragmentosde sombreador son contenido de confianza. Se recomienda a los desarrolladores de aplicaciones que valoren cuidadosamente las posibles implicaciones antes de permitir la carga de contenido proporcionado por el usuario que no forme parte de la aplicación.

    Véase también vertexShader.

    lineWidth : real

    Esta propiedad determina el ancho de las líneas representadas, cuando la geometría utiliza un tipo primitivo de líneas o tiras de líneas. El valor por defecto es 1,0. Esta propiedad no es relevante al representar otros tipos de geometría, como, por ejemplo, mallas triangulares.

    Advertencia: Es posible que los anchosde línea distintos de 1 no sean compatibles en tiempo de ejecución, dependiendo de la API gráfica subyacente. En tal caso, se ignora la solicitud de cambiar el ancho. Por ejemplo, no cabe esperar que ninguna de las siguientes API admita líneas anchas: Direct3D, Metal, OpenGL con contextos de perfil básico.

    Nota: A diferencia del ancho de línea, cuyo valor forma parte del objeto de la canalización gráfica, el tamaño de los puntos para geometrías con una topología de puntos lo controla el sombreador de vértices (cuando se admite) y, por lo tanto, no tiene una propiedad QML correspondiente.

    shadingMode : enumeration

    Especifica el tipo de material. El valor por defecto es «Sombreado».

    ConstanteValor
    CustomMaterial.Unshaded
    CustomMaterial.Shaded

    sourceAlphaBlend : enumeration [since 6.7]

    Especifica el factor de mezcla alfa de la fuente. El valor por defecto es CustomMaterial.NoBlend. Este valor solo se utiliza de forma efectiva si sourceBlend y destinationBlend se establecen en un valor distinto del predeterminado.

    ConstanteDescripción
    CustomMaterial.NoBlend 
    CustomMaterial.Zero 
    CustomMaterial.One 
    CustomMaterial.SrcColor 
    CustomMaterial.OneMinusSrcColor 
    CustomMaterial.DstColor 
    CustomMaterial.OneMinusDstColor 
    CustomMaterial.SrcAlpha 
    CustomMaterial.OneMinusSrcAlpha 
    CustomMaterial.DstAlpha 
    CustomMaterial.OneMinusDstAlpha 
    CustomMaterial.ConstantColor 
    CustomMaterial.OneMinusConstantColor 
    CustomMaterial.ConstantAlpha 
    CustomMaterial.OneMinusConstantAlpha 
    CustomMaterial.SrcAlphaSaturate

    Nota: Por motivos de compatibilidad con versiones anteriores, si se deja en su valor por defecto, se le asignará el mismo valor que a « sourceBlend » cuando « sourceBlend » y « destinationBlend » estén configurados con valores distintos de los predeterminados.

    Esta propiedad se introdujo en Qt 6.7.

    Véase también sourceBlend.

    sourceBlend : enumeration

    Especifica el factor de mezcla de origen. El valor por defecto es « CustomMaterial.NoBlend ».

    ConstanteDescripción
    CustomMaterial.NoBlend 
    CustomMaterial.Zero 
    CustomMaterial.One 
    CustomMaterial.SrcColor 
    CustomMaterial.OneMinusSrcColor 
    CustomMaterial.DstColor 
    CustomMaterial.OneMinusDstColor 
    CustomMaterial.SrcAlpha 
    CustomMaterial.OneMinusSrcAlpha 
    CustomMaterial.DstAlpha 
    CustomMaterial.OneMinusDstAlpha 
    CustomMaterial.ConstantColor 
    CustomMaterial.OneMinusConstantColor 
    CustomMaterial.ConstantAlpha 
    CustomMaterial.OneMinusConstantAlpha 
    CustomMaterial.SrcAlphaSaturate

    Nota: Tanto sourceBlend como destinationBlend deben configurarse con un valor distinto del predeterminado antes de habilitar la fusión.

    Véase también « destinationBlend ».

    vertexShader : url

    Especifica el archivo que contiene el fragmento de código del sombreador de vértices personalizado.

    El valor es una URL y debe corresponder a un archivo local o utilizar el esquema qrc para acceder a archivos incrustados a través del sistema de recursos de Qt. También se aceptan rutas de archivo relativas (sin esquema); en ese caso, el archivo se considera relativo al componente (el archivo .qml ).

    Advertencia: Se da por hecho que los fragmentosde sombreador son contenido de confianza. Se recomienda a los desarrolladores de aplicaciones que sopesen cuidadosamente las posibles implicaciones antes de permitir la carga de contenido proporcionado por el usuario que no forme parte de la aplicación.

    Véase también fragmentShader.

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