CustomMaterial QML Type

用于创建自定义材质的基底组件，这些材质用于为模型着色。更多...

• 所有成员的列表，包括继承的成员

属性

• alwaysDirty : bool
• destinationAlphaBlend : enumeration (since 6.7)
• destinationBlend : enumeration
• fragmentShader : url
• lineWidth : real
• shadingMode : enumeration
• sourceAlphaBlend : enumeration (since 6.7)
• sourceBlend : enumeration
• vertexShader : url

详细说明

自定义材质允许为材质使用自定义着色器代码，从而在图形着色器层面上实现可编程性。可以提供顶点着色器、片段着色器，或两者兼有。vertexShader 和fragmentShader 属性是 URL，用于引用包含着色器代码片段的文件，其工作原理与ShaderEffect 或Image.source 非常相似。自定义材质仅支持file 和qrc 方案。此外，还可以省略file 方案，以便以更便捷的方式指定相对路径。此类路径将相对于组件（即.qml 文件）的位置进行解析。

有关自定义材质的入门指南，请参阅“可编程材质、效果、几何体和纹理数据”页面。

简介

请看同一场景的以下两种版本。左侧的圆柱体使用的是内置的、不可编程的材质。此类材质可通过多种属性进行配置，但无法进一步控制其底层生成的着色器。 右侧，同一圆柱体现在关联了一个“CustomMaterial”，该材质引用了应用程序提供的顶点着色器和片段着色器代码片段。 这使得开发者能够将自定义的、特定于应用程序的逻辑插入顶点着色器中以变换几何体，并在片段着色器中以自定义的方式确定某些颜色属性。由于这是shaded 的自定义材质，该圆柱体仍能像往常一样参与场景的照明。

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 }
            }
        ]
    }
}

假设material.vert 和material.frag 中的着色器代码片段如下：

void MAIN()
{
    VERTEX.x += sin(uTime + VERTEX.y) * uAmplitude;
}

void MAIN()
{
    BASE_COLOR = vec4(0.0, 1.0, 0.0, 1.0);
}

请注意，uTime 和uAmplitude 是 CustomMaterial 元素的属性。它们可以像往常一样更改值并进行动画处理，这些值会自动暴露给着色器，无需开发者进行任何额外操作。

最终效果是一个顶点会进行动画效果的圆柱体：

两种自定义材质类型

自定义材质主要有两种类型。这由shadingMode 属性指定。在unshaded 自定义材质中，片段着色器会输出单一的vec4 颜色，忽略场景中的光源、光探针和阴影。在shaded 材质中，着色器需要实现某些函数，并利用内置变量来考虑光照和阴影的影响。

默认选择通常是带着色（shaded）材质，这体现在shadingMode 属性的默认值上。这适用于需要对顶点或其他来自几何体的输入数据进行变换，或以自定义方式（例如通过采样SCREEN_TEXTURE 或DEPTH_TEXTURE ）确定BASE_COLOR 或EMISSIVE_COLOR 等值的材质，同时仍能接收来自场景的光照和阴影贡献。 此外，此类材质还可以覆盖并重新实现用于计算定向光、点光源及其他光源贡献的计算公式。应用程序提供的着色器代码片段会在后台由Qt Quick 3D 引擎进行大幅修改，以便提供标准材质所具备的功能，例如光照效果。

当物体的外观完全由自定义着色器代码决定时，无着色材质便十分有用。 此类材质的着色器仅会受到引擎的极少干预，因此最终的片段颜色完全由着色器决定。这虽然提供了更大的自由度，但也限制了与场景中其他元素（如光源）的集成可能性。

向着色器暴露数据

CustomMaterial 的动态属性可通过 QML 和Qt Quick 功能进行修改和动画处理，其值会自动提供给着色器。实际上，这与ShaderEffect 的实现非常相似。以下列表展示了属性的映射关系：

• bool、int、real → bool、int、float
• QColor、color → vec4，且颜色会转换为线性模式——假设 QML 中指定的颜色值采用 sRGB 色彩空间。Qt 的内置颜色（如"green" ）同样位于 sRGB 色彩空间中，而 DefaultMaterial 和PrincipledMaterial 的所有颜色属性也会进行相同的转换，因此 CustomMaterial 的这种行为与它们保持一致。 与Qt Quick 不同，对于Qt Quick 3D 而言，线性化处理至关重要，因为通常会对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，标量值为w
• TextureInput -> sampler2D 或 samplerCube，具体取决于TextureInput 的texture属性中使用的是Texture 还是CubeMapTexture 。将enabled 属性设置为false会导致向着色器暴露一个虚拟纹理，这意味着着色器仍可正常运行，但将采样一张内容为不透明黑色图像的纹理。 请注意，采样器的属性必须始终引用TextureInput 对象，而不能直接引用Texture 。 关于Texture 的属性，在使用自定义材质时，仅源、平铺和过滤相关的属性会被隐式考虑在内，其余属性（例如UV变换）则由自定义着色器根据需要自行实现。

无着色自定义材质

以下是一个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"
}

根据上述示例，unshaded 的顶点着色器和片段着色器代码片段可能如下所示。请注意，这些着色器不会也不应声明uniform变量或顶点输入，因为Qt在组装最终着色器代码时会自动处理这些内容。

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

可使用以下特殊的大写关键字：

• MAIN -> 顶点着色器或片元着色器代码片段中的入口点名称必须始终为MAIN 。在未着色的自定义材质着色器代码片段中，必须提供此函数。
• VARYING -> 声明顶点着色器的输出或片段着色器的输入
• POSITION -> vec4，顶点着色器的输出
• FRAGCOLOR -> vec4，顶点着色器的输出。仅适用于未着色的自定义材质。
• VERTEX -> vec3，顶点着色器中的顶点位置。
• NORMAL -> vec3，顶点着色器中的顶点法线。当关联模型的网格未提供法线时，该值为 vec3(0.0)。
• UV0 -> vec2，顶点着色器中的第一组纹理坐标。当关联模型的网格未提供纹理坐标时，该值为 vec2(0.0)。
• UV1 -> vec2，顶点着色器中的第二组纹理坐标。当相关模型的网格未提供第二组纹理坐标时，该值为 vec2(0.0)。
• COLOR -> vec4，顶点着色器中的顶点颜色。当相关模型的网格未提供顶点颜色时，该值为 vec4(1.0)。
• TANGENT -> vec3，顶点着色器中的切向量。当相关模型的网格未提供切向数据时，该值为 vec3(0.0)。
• BINORMAL -> vec3，顶点着色器中的副法线。当关联模型的网格未提供副法线数据时，该值为 vec3(0.0)。
• JOINTS -> ivec4，顶点着色器中的关节索引。如果相关模型的网格未提供关节索引数据，则该值为 ivec4(0)。
• WEIGHTS -> vec4，顶点着色器中的关节权重。当关联模型的网格未提供关节权重数据时，该值为 vec4(0.0)。
• MORPH_POSITION(n) -> vec3，顶点着色器中的第 n+1 个变形目标位置。关联模型应提供相应数据。
• MORPH_NORMAL(n) -> vec3，顶点着色器中第 n+1 个变形目标的法线。相关模型应提供正确的数据。
• MORPH_TANGENT(n) -> vec3，顶点着色器中第 n+1 个形态目标的切向量。关联模型应提供正确的数据。
• MORPH_BINORMAL(n) -> vec3，顶点着色器中的第 n+1 个变形目标副法向量。相关模型应提供正确的数据。
• MODELVIEWPROJECTION_MATRIX -> mat4，模型-视图-投影矩阵。投影矩阵始终遵循 OpenGL 规范，其中包含针对 Y 轴方向和裁剪深度的内置变换，具体取决于运行时使用的图形 API。
• VIEWPROJECTION_MATRIX -> mat4，视图-投影矩阵
• PROJECTION_MATRIX -> mat4，投影矩阵
• INVERSE_PROJECTION_MATRIX -> mat4，逆投影矩阵
• VIEW_MATRIX -> mat4，视图（摄像机）矩阵
• MODEL_MATRIX -> mat4，模型（世界）矩阵
• NORMAL_MATRIX -> mat3，法线矩阵（即模型矩阵左上角 3x3 部分逆矩阵的转置）
• BONE_TRANSFORMS -> mat4[], 模型骨骼矩阵数组
• BONE_NORMAL_TRANSFORMS -> mat3[], 模型骨骼法线矩阵数组（即每个骨骼矩阵左上角 3x3 部分逆矩阵的转置）
• MORPH_WEIGHTS -> float[], 形态权重数组。相关模型应提供正确的数据。出于安全考虑，QT_MORPH_MAX_COUNT被定义为该数组的大小。
• CAMERA_POSITION -> vec3，世界坐标系中的摄像机位置
• CAMERA_DIRECTION -> vec3，摄像机在世界坐标系中的方向向量
• CAMERA_PROPERTIES -> vec2，摄像机的近裁剪值和远裁剪值
• POINT_SIZE -> float，仅可在顶点着色器中写入。渲染具有点拓扑结构的几何体时，自定义顶点着色器必须将其设置为 1.0 或另一个值，无论是在带着色还是不带着色的自定义材质中均需如此。有关对 1 以外大小的支持的更多说明，请参阅PrincipledMaterial::pointSize 。

带着色效果的自定义材质

一个shaded 材质augments 包含由PrincipledMaterial 生成的着色器代码。与无着色材质不同，后者几乎完全自行提供顶点和片段着色器主函数的逻辑，从而阻止添加用于照明、阴影、全局光照等的生成的代码；而着色材质则允许着色器生成正常进行，就好像该 CustomMaterial 是一个PrincipledMaterial 一样。 这些顶点着色器和片段着色器代码片段应提供可选函数，这些函数将在特定点被调用，从而允许自定义颜色及其他值，这些值随后将用于计算光照和最终的片段颜色。

带着色效果的自定义材质所对应的片段着色器，不必仅实现MAIN 函数，而是可以实现多个函数。在带着色效果的自定义材质中，所有函数（包括MAIN ）的实现均为可选。一个空的着色器代码片段，甚至完全不指定vertexShader 或fragmentShader 属性，也是完全有效的。

带着色效果的自定义材质中的顶点着色器代码片段

可以在顶点着色器片段中实现以下函数：

• void MAIN() 若存在此函数，系统将调用它来设置POSITION 的值（即顶点着色器的vec4输出），并可选地修改VERTEX 、COLOR 、NORMAL 、UV0 、UV1 、TANGENT,BINORMAL,JOINTS, 以及WEIGHTS 。与无着色材质不同，向这些变量写入数据是有意义的，因为修改后的值会在后续生成的着色器代码中被考虑进去（而对于无着色材质，则不会生成额外的着色器代码）。 例如，如果自定义顶点着色器对顶点或法线进行了位移，则需要将修改后的值存储到VERTEX 或NORMAL 中，以便后续进行正确的照明计算。 此外，该函数还可以写入使用 `VARYING ` 定义的变量，以便将插值后的数据传递给片段着色器。当不存在该函数或 `POSITION ` 的重定义时，POSITION 将基于 `VERTEX ` 和 `MODELVIEWPROJECTION_MATRIX` 进行计算，就像 `PrincipledMaterial ` 所做的那样。

  示例：既依赖作为uniform暴露的QML属性，同时也向片段着色器传递数据：

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

  注意：在 上述示例中 ，为POSITION 赋值是可选的，因为此处的使用方式与默认行为完全一致。

带着色效果的自定义材质中的片段着色器代码片段

以下函数可在片段着色器片段中实现：

• void MAIN() 若存在该函数，则会调用它来设置以下特殊可写变量的值：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 以及OCCLUSION_AMOUNT 。

  一种常见的用法是根据对纹理的采样来设置BASE_COLOR 的值，无论是基础颜色贴图、SCREEN_TEXTURE ，还是其他类型的源。这在未实现自定义光照处理函数时尤为相关且方便。 将BASE_COLOR.a 设置为默认值1.0以外的数值，可以影响片段的最终透明度值。（请注意，这通常还需要在sourceBlend 和destinationBlend 中启用透明度混合）

  另一种情况是，当未提供自定义的SPECULAR_LIGHT 函数，或者在SceneEnvironment 中设置了光探针时。金属度、粗糙度以及其他影响镜面反射贡献计算的值，均可通过MAIN 设置为所需的自定义值。

  该函数可写入以下特殊变量。写入这些变量的值通常为硬编码值，或基于映射到uniforms的QML属性计算得出。其语义与PrincipledMaterial 完全一致。

  • vec4BASE_COLOR - 基础颜色和材质透明度值。对应于built-in materials' color property 。当未实现光照处理器函数时，在MAIN 中设置自定义基础颜色会比较方便，因为默认光照计算会将该值纳入考量。 默认值为vec4(1.0) ，表示不透明度为1.0的白色。不透明度值会影响片段的最终不透明度。最终不透明度是对象（模型）的不透明度乘以基础颜色不透明度的结果。 当直接在着色器代码中指定该值（而非依赖 QML 中颜色属性暴露的 uniform 值）时，请注意：如有必要，着色器需自行执行 sRGB 到线性空间的转换。例如，假设vec3 color 和float alpha ，可通过以下方式实现：

    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);

  • vec3EMISSIVE_COLOR - 自发光颜色。 对应于内置材质的发光颜色，该颜色由built-in materials's emissiveFactor property 和built-in materials's emissiveMap property 组合而成。默认值为vec3(0.0) 。当在着色器代码中直接指定该值（而非依赖 QML 中颜色属性暴露的 uniform 值）时，请注意：如有必要，sRGB 到线性空间的转换应由着色器自行完成。
  • floatIOR 指定材质的折射率。典型值（也是默认值）为1.5 ，因为这是PrincipledMaterial 所使用的值。
  • floatTRANSMISSION_FACTOR 指定半透明程度。典型值（也是默认值）为1.0 ，即0.0 所采用的值，因为PrincipledMaterial 也会使用该值。
  • floatTHICKNESS_FACTOR 指定半透明材质的厚度。典型值通常为10.0 ，默认值为0.0 ，因为这是PrincipledMaterial 所使用的值。
  • vec3ATTENUATION_COLOR 指定半透明材质随距离产生的颜色偏移。典型值为vec3(1.0, 0.0, 0.0) ，默认值为vec3(1.0) ，因为这是PrincipledMaterial 所使用的值。
  • floatATTENUATION_DISTANCE 指定半透明材质颜色偏移的距离衰减。典型值为100.0 ，默认值为0.0 ，因为这是PrincipledMaterial 所使用的值。
  • floatMETALNESS 金属度值，范围为 0.0 - 1.0。默认值为 0。必须设置为非零值才能生效。
  • floatROUGHNESS 粗糙度值，范围为 0.0 至 1.0。默认值为 0。
  • floatCLEARCOAT_FRESNEL_POWER 指定清漆层的菲涅尔指数。典型值（也是默认值）为5.0 ，因为这是PrincipledMaterial 所使用的数值。
  • floatCLEARCOAT_FRESNEL_SCALE 指定清漆层的菲涅尔缩放因子。典型值（也是默认值）为1.0 ，因为这是PrincipledMaterial 所使用的值。
  • floatCLEARCOAT_FRESNEL_BIAS 指定清漆层的菲涅尔偏移量。典型值（也是默认值）为0.0 ，因为这是PrincipledMaterial 所使用的数值。
  • floatCLEARCOAT_AMOUNT 指定清漆层在材质上的覆盖量。典型值（也是默认值）为1.0 ，即0.0 ，因为这是PrincipledMaterial 所使用的值。
  • floatCLEARCOAT_ROUGHNESS 指定清漆层的粗糙度。典型值为1.0 （表示完全模糊的清漆层），默认值为0.0 ，因为这是PrincipledMaterial 所使用的值。
  • vec3CLEARCOAT_NORMAL - 来自顶点着色器的、位于世界坐标系中的清漆层法线。虽然该属性的初始值与VAR_WORLD_NORMAL 相同，但只有修改CLEARCOAT_NORMAL 的值才会影响清漆层法线。
  • floatFRESNEL_POWER 指定菲涅尔强度。典型值（也是默认值）为5.0 ，因为这是PrincipledMaterial 所使用的值。
  • floatFRESNEL_SCALE 指定菲涅尔系数。典型值（也是默认值）为1.0 ，因为这是PrincipledMaterial 所使用的值。
  • floatFRESNEL_BIAS 指定菲涅尔偏移量。典型值（也是默认值）为0.0 ，因为这是PrincipledMaterial 所使用的值。
  • floatSPECULAR_AMOUNT 镜面反射量，取值范围为 0.0 - 1.0。默认值为0.5 ，与PrincipledMaterial::specularAmount 一致。必须设置为非零值才能生效。
  • floatOCCLUSION_AMOUNT 指定AO因子。典型值（也是默认值）为1.0 ，因为这是PrincipledMaterial 所使用的值。
  • vec3NORMAL - 来自顶点着色器的世界坐标系法向量。虽然该属性的初始值与VAR_WORLD_NORMAL 相同，但只有修改NORMAL 的值才会对光照产生影响。
  • vec3TANGENT - 来自顶点着色器的世界坐标系切向量。该值可能会根据双面性进行调整。
  • vec3BINORMAL - 来自顶点着色器的世界坐标系中的切向量。该值可能会因双面性而进行调整。
  • vec2UV0 - 来自顶点着色器的第一组纹理坐标。该属性在片段着色器中为只读。
  • vec2UV1 - 来自顶点着色器的第二组纹理坐标。该属性在片段着色器中为只读。

  注意：与 无着色材质不同， 着色材质的片段MAIN 无法直接控制FRAGCOLOR 。相反，最终的片段颜色由在光照处理器函数中写入的DIFFUSE 和SPECULAR 值决定。当未实现光照处理器函数时，系统会像处理PrincipledMaterial 一样执行相关的默认着色计算，并考虑BASE_COLOR 以及上述列表中的其他值。

  以下是一个简单的金属质感自定义材质着色器的示例：

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

  另一个示例，其中通过采样纹理来设置基础颜色和透明度：

  VARYING vec2 texcoord;
  void MAIN()
  {
      BASE_COLOR = texture(uColorMap, texcoord);
  }

• • LIGHT_COLOR
DIFFUSE
• void AMBIENT_LIGHT() 如果存在该函数，则每个片段都会调用它一次。该函数的任务是将环境光的总贡献值添加到可写特殊变量DIFFUSE 中。当然，它也可以选择计算一个不同的值，或者完全不修改DIFFUSE （以完全忽略环境光）。 如果完全不存在该函数，则环境光的贡献将按常规方式计算，就像PrincipledMaterial 所做的那样。

  该函数可以写入以下特殊变量：

  • vec3DIFFUSE 累积每个片段的漫反射光贡献。光照处理器函数通常会向其添加 (+=)，因为覆盖该值会导致丢失其他光源的贡献。

  除了上表中的矩阵（例如MODEL_MATRIX ）和向量（例如CAMERA_POSITION ）统一变量外，该函数还可以读取以下特殊变量：

  • vec3TOTAL_AMBIENT_COLOR 场景中的总环境光贡献
• 。
• 示例：

  void AMBIENT_LIGHT()
  {
      DIFFUSE += TOTAL_AMBIENT_COLOR;
  }

• void DIRECTIONAL_LIGHT() 若存在，则该函数会针对场景中的每个活动定向光源和每个片元被调用。 该函数的任务是将漫反射贡献加到可写特殊变量DIFFUSE 中。该函数也可以选择不执行任何操作，在这种情况下，来自定向光源的漫反射贡献将被忽略。如果该函数完全不存在，则来自定向光源的漫反射贡献将像PrincipledMaterial 那样正常累加。

  该函数可以写入以下特殊变量：

  • vec3DIFFUSE 累加每个片段的漫反射光贡献。光照处理器函数通常会向其添加 (+=)，因为覆盖该值会导致丢失其他光源的贡献。

  除了上表中列出的矩阵（例如MODEL_MATRIX ）和向量（例如CAMERA_POSITION ）统一变量外，该函数还可以读取以下特殊变量：

  • vec3LIGHT_COLOR 漫反射光颜色。
  • floatSHADOW_CONTRIB 阴影贡献值；若完全无阴影或未接收阴影，则值为 1.0。
  • vec3TO_LIGHT_DIR 指向光源的方向向量。
  • vec3NORMAL 世界坐标系中的法线向量。
  • vec4BASE_COLOR 基色和材质透明度值。
  • floatMETALNESS 金属度值。
  • floatROUGHNESS 粗糙度值。

  示例：

  void DIRECTIONAL_LIGHT()
  {
      DIFFUSE += LIGHT_COLOR * SHADOW_CONTRIB * vec3(max(0.0, dot(normalize(VAR_WORLD_NORMAL), TO_LIGHT_DIR)));
  }

• void POINT_LIGHT() 若存在该函数，则针对场景中每个活跃的点光源及每个片段都会调用此函数。 该函数的任务是将漫反射贡献添加到可写特殊变量DIFFUSE 中。该函数也可以选择不执行任何操作，在这种情况下，点光源的漫反射贡献将被忽略。如果该函数完全不存在，则点光源的漫反射贡献将像PrincipledMaterial 那样正常累加。

  该函数可以写入以下特殊变量：

  • vec3DIFFUSE 累积每个片段的漫反射光贡献。

  除了上表中的矩阵（例如，MODEL_MATRIX ）和向量（例如，CAMERA_POSITION ）统一变量外，该函数还可以读取以下特殊变量

  ：
  • vec3LIGHT_COLOR 漫反射光颜色。
  • floatLIGHT_ATTENUATION 光线衰减。
  • floatSHADOW_CONTRIB 阴影贡献度；若完全无阴影或不接收阴影，则设为 1.0。
  • vec3TO_LIGHT_DIR 指向光源的方向向量。
  • vec3NORMAL 世界坐标系中的法线向量。
  • vec4BASE_COLOR 基色和材质透明度值。
  • floatMETALNESS 金属度值。
  • floatROUGHNESS 粗糙度值。

  示例：

  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() 若存在该函数，则针对场景中每个活动聚光灯的每个片段都会调用此函数。该函数的任务是将漫反射贡献添加到可写特殊变量DIFFUSE 中。该函数也可以选择不执行任何操作，在这种情况下，来自聚光灯的漫反射贡献将被忽略。 如果该函数完全不存在，则聚光灯的漫反射贡献将像PrincipledMaterial 那样正常累加。

  该函数可以写入以下特殊变量：

  • vec3DIFFUSE 累加每个片段的漫反射光贡献。

  除了上表中列出的矩阵（例如MODEL_MATRIX ）和向量（例如CAMERA_POSITION ）统一变量外，该函数还可以读取以下特殊变量：

  • vec3 漫反射光颜色。
  • floatLIGHT_ATTENUATION 光线衰减。
  • floatSHADOW_CONTRIB 阴影贡献值；若完全无阴影或未接收阴影，则值为 1.0。
  • vec3TO_LIGHT_DIR 指向光源的方向向量。
  • floatSPOT_FACTOR 聚光灯系数。
  • vec3NORMAL 世界坐标系中的法线向量。
  • vec4BASE_COLOR 基础颜色和材质透明度值。
  • floatMETALNESS 金属度值。
  • floatROUGHNESS 粗糙度值。

  示例：

  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() 若存在该函数，则针对场景中的每个有效光源及每个片段都会调用它。该函数的任务是将镜面反射贡献加到可写特殊变量SPECULAR 中。该函数也可以选择不执行任何操作，在这种情况下，来自光源的镜面反射贡献将被忽略。 如果该函数完全不存在，则光源的镜面反射贡献将像PrincipledMaterial 那样正常累加。

  该函数可以写入以下特殊变量：

  • vec3SPECULAR 累加每个片段的光源镜面反射贡献。 光照处理器函数通常会向其添加 (+=)，因为覆盖该值会导致丢失来自其他光源的贡献。

  除上表中的矩阵（例如MODEL_MATRIX ）和向量（例如CAMERA_POSITION ）统一变量外，该函数还可以读取以下特殊变量：

  • vec3LIGHT_COLOR 镜面光颜色。
  • floatLIGHT_ATTENUATION 光线衰减。对于方向光，该值为 1.0。对于聚光灯，该值与void SPOT_LIGHT() 中的LIGHT_ATTENUATION * SPOT_FACTOR 相同。
  • floatSHADOW_CONTRIB 阴影贡献度，若完全无阴影或未接收阴影，则该值为 1.0。
  • vec3FRESNEL_CONTRIB 来自内置菲涅尔计算的菲涅尔贡献。
  • vec3TO_LIGHT_DIR 指向光源的方向向量。
  • vec3NORMAL 世界坐标系中的法线向量。
  • vec4BASE_COLOR 基础颜色和材质透明度值。
  • floatMETALNESS 金属度值。
  • floatROUGHNESS 粗糙度值。
  • floatSPECULAR_AMOUNT 镜面反射强度。该值介于 0.0 到 1.0 之间，将与在自定义函数MAIN 中设置的值相同。当不使用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() 若存在，该函数将在片段管道结束时被调用。 该函数的任务是使用最终的漫反射、镜面反射和自发光项来完成COLOR_SUM 的计算。与未着色的材质对应的FRAGCOLOR 不同，COLOR_SUM 在写入帧缓冲区之前会自动进行色调映射。出于调试目的，有时输出一个不应被视为颜色的值会很有帮助。 为避免色调映射扭曲该值，可通过将tonemapMode 属性设置为TonemapModeNone
  来禁用色调映射
  • 。

  该函数可写入以下特殊变量：

  • vec4COLOR_SUM 片段着色器的输出。默认值为 vec4(DIFFUSE.rgb + SPECULAR + EMISSIVE, DIFFUSE.a)

  该函数可以读取以下特殊变量：

  • vec4 片段渲染管线中的最终漫反射项。
  • vec3SPECULAR 片段渲染管线中的最终镜面反射项。
  • vec3EMISSIVE 片段渲染管线中的最终自发光项。
  • vec2UV0 - 来自顶点着色器的第一组纹理坐标。
  • vec2UV1 - 来自顶点着色器的第二组纹理坐标。

  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() 若存在，此函数将在基于图像的照明（IBL）中被调用。该函数的任务是将 IBL 的漫反射和镜面反射贡献分别添加到可写特殊变量DIFFUSE 和SPECULAR 中。

  该函数可向以下特殊变量写入数据：

  • vec3DIFFUSE 累加每个片段的漫反射光贡献。
  • vec3SPECULAR 累加每个片段的镜面反射光贡献。

  该函数可读取以下特殊变量

  ：
  • vec4BASE_COLOR 基础颜色和材质透明度值。
  • floatAO_FACTOR 屏幕空间遮挡因子。
  • floatSPECULAR_AMOUNT 镜面反射强度。
  • floatROUGHNESS 片段管线中的最终发光项。
  • vec3NORMAL 世界空间中的法线向量。
  • vec3VIEW_VECTOR 指向摄像机的方向。
  • mat3IBL_ORIENTATION 光探针的朝向。该值来自SceneEnvironment::probeOrientation 。

  void IBL_PROBE()
  {
      vec3 smpDir = IBL_ORIENTATION * NORMAL;
      DIFFUSE += AO_FACTOR * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, smpDir, IBL_MAXMIPMAP).rgb;
  }

函数间的自定义变量

可以从 MAIN 函数向其他函数传递额外变量。可使用SHARED_VARS 关键字来定义新的自定义变量。这些用户定义的变量可通过 SHARED.<变量名> 进行访问。

例如，一个带着色效果的自定义材质可以在 MAIN 中获取一个共享值，并在其他函数中使用它。

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

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

其他特殊关键字

自定义片段着色器代码可以自由访问由自定义顶点着色器传递过来的uniform变量（例如，CAMERA_DIRECTION 或CAMERA_POSITION ）和varying变量。此外，还有许多内置的varying变量可作为特殊关键字使用。 其中部分参数是可选的，因为顶点MAIN 可以自行计算并传递这些参数，但为了减少数据重复，片段着色器也可以直接使用这些内置参数。这些内置参数可在轻量级处理器函数和片段MAIN中使用。

• vec3VAR_WORLD_NORMAL - 经NORMAL_MATRIX 变换后的插值法线。
• vec3VAR_WORLD_TANGENT — 经MODEL_MATRIX 变换后的插值法线。vec3 — 经 变换后的插值切线。
• vec3VAR_WORLD_BINORMAL - 经 变换后的插值二法线。MODEL_MATRIX
• vec3NORMAL - 与直接作为插值法线输出的VAR_WORLD_NORMAL 不同，该值可能会根据双面性进行调整：当禁用剔除进行渲染时，法线会根据需要进行反转。因此，建议在光照及其他计算中使用NORMAL 代替VAR_WORLD_NORMAL ，以确保在所有剔除模式下均能正确运行。
• vec3TANGENT - 与NORMAL 类似，该值可能会根据双面性进行调整：当禁用剔除进行渲染时，切向量会根据需要进行反转。
• vec3BINORMAL - 与NORMAL 一样，该值可能会根据双面渲染情况进行调整：当禁用剔除进行渲染时，切向量将根据需要进行反转。
• vec3VAR_WORLD_POSITION - 插值后的世界空间顶点位置（(MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz ）
• vec4VAR_COLOR - 当网格中提供了颜色时，插值后的顶点颜色。否则为vec4(1.0) 。
• vec3VIEW_VECTOR - 指向摄像机的方向。这实际上是CAMERA_POSITION - VAR_WORLD_POSITION 向量的归一化形式。
• vec4FRAGCOORD - 包含当前片段相对于窗口的坐标。
• floatFRAMEBUFFER_Y_UP - 当帧缓冲区（纹理）坐标系中 Y 轴朝上时，该值为1 ，即(0, 0) 为左下角；当 Y 轴朝下时，该值为-1 ，(0, 0) 为左上角。底层图形 API 中的此类差异对大多数自定义材质而言并不重要。 一个值得注意的例外是，使用不基于 FRAGCOORD 的纹理坐标采样SCREEN_TEXTURE 。由于SCREEN_TEXTURE 的方向本质上与底层图形 API 相关联，因此使用来自网格的纹理坐标时，可能需要对 Y 坐标进行适当调整。

  例如，以下适用于矩形（Rectangle）或立方体（Cube）网格的片段着色器，将把场景中的不透明物体显示在模型上：

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

  当采样SCREEN_TEXTURE 和DEPTH_TEXTURE 以外的纹理时，或者当使用FRAGCOORD 来计算纹理坐标时（这通常是访问屏幕和深度纹理的典型用例），则无需进行此类调整。

• floatNDC_Y_UP - 当 Y 轴在归一化设备坐标系中向上时，该值为1 ；当 Y 轴向下时，该值为-1 。在使用 Vulkan 进行渲染时，Y 轴通常指向下方。大多数材质无需考虑此参数，但在某些高级用例中，能够根据此参数进行条件分支会非常有用。
• floatNEAR_CLIP_VALUE - 当裁剪平面范围从-1 开始，到1 结束时，该值为-1 。使用 OpenGL 进行渲染时即为这种情况。对于其他渲染后端，该属性的值为0 ，这意味着裁剪平面范围为0 到1 。该值在涉及DEPTH_TEXTURE

  例如，以下片段着色器演示了一种技术：通过深度缓冲区中的某个值来重建其位置，从而确定该点与当前渲染位置之间的距离。当与INVERSE_PROJECTION_MATRIX 结合使用时，深度值必须采用归一化设备坐标，因此必须确保深度值的范围能反映这一点。 当NEAR_CLIP_VALUE 为-1 时，深度值会被缩放至-1 到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);
  }

• floatIBL_EXPOSE —— 光探针发出的光量。该值源自SceneEnvironment::probeExposure 。

  DIFFUSE += AO_FACTOR * IBL_EXPOSE * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, NORMAL, IBL_MAXMIPMAP).rgb;

• floatIBL_HORIZON - 来自环境下半部分的反射的水平截止值。该值源自Horizon Cut-Off ，但已被重映射到 [-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;
  }

• floatIBL_MAXMIPMAP - IBL_TEXTURE 的最大 Mipmap 级别。

实例化

在进行实例化渲染时，上述部分关键字不适用。以下关键字仅在实例化渲染时可用：

• INSTANCE_MODEL_MATRIX -> mat4，用于替代MODEL_MATRIX ，包含实例化变换。
• INSTANCE_MODELVIEWPROJECTION_MATRIX -> mat4，用于替代MODELVIEWPROJECTION_MATRIX ，包含实例化变换。
• INSTANCE_COLOR -> vec4，实例颜色：需与COLOR 结合使用。
• INSTANCE_DATA -> vec4，实例自定义数据。
• INSTANCE_INDEX -> int，实例编号，也是实例化表中的索引。

屏幕、深度及其他纹理

渲染管线可向自定义材质着色器提供若干纹理，其内容来自特殊的渲染通道。这既适用于带着色效果的自定义材质，也适用于无着色效果的自定义材质。

例如，某个着色器可能需要访问包含场景中不透明对象深度缓冲区内容的深度纹理。这可通过采样 `DEPTH_TEXTURE` 来实现。此类纹理通常不会被生成，除非确实有实际需求。 因此，在顶点着色器或片段着色器中包含以下关键字，也起到了开启（或关闭）相关渲染通道的作用——这些通道用于生成所涉及的纹理，且可能消耗较大资源。（当然， 也可能由于其他设置（例如SceneEnvironment 中的环境光遮蔽参数，或者依赖深度纹理的后处理效果）而使其中某些纹理已被启用；在这种情况下，无论自定义材质如何，相关纹理都会被生成，因此材质中采样这些特殊纹理除了纹理访问本身外不会产生额外开销）

• SCREEN_TEXTURE - 若存在，则会以该名称向着色器暴露一张纹理（sampler2D 或sampler2DArray ），其颜色缓冲区来自一个渲染通道，该通道包含场景内容，但不包含任何透明材质或同样使用 SCREEN_TEXTURE 的材质。 该纹理可用于需要渲染目标帧缓冲区内容的技术。SCREEN_TEXTURE纹理使用与View3D 相同的清除模式。这些纹理的大小以像素为单位，与View3D 的大小一致。 例如，一个片段着色器可能包含以下内容：

  vec2 uv = FRAGCOORD.xy / vec2(textureSize(SCREEN_TEXTURE, 0));
  vec2 displace = vec2(0.1);
  vec4 c = texture(SCREEN_TEXTURE, uv + displace);

  请注意，使用SCREEN_TEXTURE 需要对场景进行适当且周全的设计。使用此类材质的对象必须精心定位，通常应置于预计会在纹理中可见的所有其他对象之上。 采用某种形式半透明效果的物体绝不会成为SCREEN_TEXTURE 的一部分。通常会在MAIN 中将SCREEN_TEXTURE 与BASE_COLOR 结合使用。例如，以下自定义片段着色器应用了浮雕效果，同时保持未被不透明物体遮挡的片段保持透明。这假设使用该材质的物体位于最前端，并且已启用混合功能。

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

  在多视图渲染中， SCREEN_TEXTURE 属于sampler2DArray 类型。使用VIEW_INDEX 来选择要使用的图层。对于希望同时支持这两种渲染类型的 VR/AR 应用程序，可采用以下通用方法：

  #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 - 该纹理在多数方面与SCREEN_TEXTURE 完全相同，区别在于它生成了 Mipmap。 从性能角度来看，这可能是一项开销较大的功能——具体取决于屏幕尺寸，并且由于每次渲染场景时都需要生成米普图。因此，除非自定义材质实现了依赖纹理米普级别的技术（例如在着色器中使用textureLod ），否则应始终优先使用SCREEN_TEXTURE 。
• DEPTH_TEXTURE - 若存在，则会将包含（非线性化）深度缓冲区内容的纹理（sampler2D 或sampler2DArray ）以该名称暴露给着色器。仅包含不透明物体。例如，片段着色器可能包含以下内容：

  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;

  在多视图渲染中，DEPTH_TEXTURE 是一个sampler2DArray 。使用VIEW_INDEX 来选择要使用的图层。 对于希望同时支持这两种渲染类型的 VR/AR 应用程序，通用做法如下：

  #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 - 若存在，则会以该名称向着色器提供一张包含世界空间法线和材质粗糙度的纹理（sampler2D ）。仅包含不透明物体。 粗糙度存储在Alpha通道中。例如，片段着色器可能包含以下内容：

  vec3 N = normalize(texture(NORMAL_ROUGHNESS_TEXTURE, uv).rgb);

• AO_TEXTURE - 当存在
• 该纹理
，且在SceneEnvironment 中启用了屏幕空间环境光遮蔽（即AO强度和距离均不为零）时，SSAO纹理（sampler2D 或sampler2DArray ）将以此名称提供给着色器。 在无着色材质中采样该贴图可能很有用。着色材质已内置环境光遮蔽支持，这意味着环境光遮蔽因子会被自动考虑在内。而在无着色材质的片段着色器中，可以编写以下代码来实现相同的效果：

ivec2 aoSize = textureSize(AO_TEXTURE, 0);
vec2 aoUV = (FRAGCOORD.xy) / vec2(aoSize);
float aoFactor = texture(AO_TEXTURE, aoUV).x;

在多视图渲染中， AO_TEXTURE 是一个sampler2DArray 。使用VIEW_INDEX 来选择要使用的图层。对于希望同时支持这两种渲染类型的 VR/AR 应用程序，可采用以下通用方法：

#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 - 它不会启用任何特殊的渲染阶段，但在材质具有Material::lightProbe 属性或模型处于SceneEnvironment::lightProbe 作用域内时，可以使用该方法。

  void IBL_PROBE()
  {
      DIFFUSE += AO_FACTOR * BASE_COLOR.rgb * textureLod(IBL_TEXTURE, NORMAL, IBL_MAXMIPMAP).rgb;
  }

• MOTION_VECTOR_TEXTURE — 启用一个专用渲染通道，用于计算场景中每个对象的运动向量。输出结果为一个四通道纹理：R和G通道包含模型的缩放后运动向量，而B和A通道则存储未缩放的运动向量。
• VIEW_INDEX - 在自定义着色器代码中使用时，这是一个（非插值的）uint 变量。当未启用多视图渲染时，该值始终为 0。启用多视图渲染时，该值即为当前视图索引（例如 gl_ViewIndex）。 在启用多视图渲染时，与DEPTH_TEXTURE 及类似功能结合使用尤为有效。

另请参阅 SceneEnvironment::tonemapMode 、使用基于图像的照明（Qt Quick 3D ）、自定义着色器示例（Qt Quick 3D ） 、自定义材质示例（ ）以及可编程材质、特效、几何体和纹理数据。

属性文档

alwaysDirty : bool

指定材质状态始终为“脏”，这表示每当QtQuick3D 使用该材质时，都需要刷新该材质。

destinationAlphaBlend : enumeration [since 6.7]

指定目标透明度混合因子。默认值为CustomMaterial.NoBlend 。只有当sourceBlend 和destinationBlend 设置为非默认值时，该值才会被有效使用。

该属性在 Qt 6.7 中引入。

另请参阅 destinationBlend 。

destinationBlend : enumeration

指定目标混合因子。默认值为CustomMaterial.NoBlend 。

另请参阅 sourceBlend 。

fragmentShader : url

指定包含自定义片段着色器代码片段的文件。

该值是一个 URL，必须为本地文件，或使用 qrc 方案访问通过 Qt 资源系统嵌入的文件。也接受相对文件路径（不带方案），在此情况下，该文件将被视为相对于组件（.qml 文件）的相对路径。

另请参阅 vertexShader 。

lineWidth : real

当几何体使用“线”或“线段”作为基元类型时，该属性用于确定渲染线的宽度。默认值为 1.0。在渲染其他类型的几何体（例如三角网格）时，该属性不适用。

shadingMode : enumeration

指定材质的类型。默认值为“带阴影”。

sourceAlphaBlend : enumeration [since 6.7]

指定源透明度混合系数。默认值为CustomMaterial.NoBlend 。只有当sourceBlend 和destinationBlend 设置为非默认值时，该值才会被有效使用。

该属性在 Qt 6.7 中引入。

另请参阅 sourceBlend 。

sourceBlend : enumeration

指定源混合因子。默认值为CustomMaterial.NoBlend 。

另请参阅 destinationBlend 。

vertexShader : url

指定包含自定义顶点着色器代码片段的文件。

该值是一个 URL，必须是本地文件，或者使用 qrc 方案访问通过 Qt 资源系统嵌入的文件。相对文件路径（不带方案）也被接受，在这种情况下，该文件将被视为相对于组件（.qml 文件）的相对路径。

另请参阅 fragmentShader 。