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 文件）的位置进行解析。

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

简介

请看同一场景的以下版本。左边的圆柱体使用的是内置的非可编程材质。这种材质可通过多种属性进行配置，但无法进一步控制在引擎盖下生成的着色器。在右侧，同一圆柱体现在与引用应用程序提供的顶点和片段着色器片段的自定义材质相关联。这样就可以在顶点着色器中插入自定义的特定应用逻辑来转换几何图形，并在片段着色器中以自定义方式确定某些颜色属性。由于这是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 材质中，着色器需要实现某些功能，并与内置变量配合使用，以将灯光和阴影的影响考虑在内。

默认选择通常是阴影材质，这反映在shadingMode 属性的默认值中。这适合那些需要转换顶点或来自几何体的其他传入数据，或以自定义方式确定BASE_COLOR 或EMISSIVE_COLOR 等值（可能是通过采样SCREEN_TEXTURE 或DEPTH_TEXTURE ）的材质，同时仍从场景中获取光影贡献。此外，此类材质还可以覆盖和重新实现用于计算定向光、点光源和其他光源贡献的方程。Qt Quick 3D 引擎对应用程序提供的着色器片段进行了大量修改，以提供标准材质所具有的照明等功能。

当物体的外观完全由自定义着色器代码决定时，无着色器材质就非常有用。引擎对此类材质的着色器的添加很少，因此完全由着色器决定最终的片段颜色。这样可以获得更大的自由度，但也限制了与场景中其他元素（如灯光）集成的可能性。

向着色器公开数据

自定义材质的动态属性可以使用 QML 和Qt Quick 工具进行更改和动画，其值会自动显示给着色器。这在实践中与ShaderEffect 非常相似。以下列表显示了属性的映射方式：

• bool, int, real -> bool, int, float
• QColor color -> vec4，颜色被转换为线性，假设 QML 中指定的颜色值为 sRGB 空间。内置的 Qt 颜色（如 ）也采用 sRGB 色彩空间，DefaultMaterial 和 的所有颜色属性都执行了相同的转换，因此 CustomMaterial 的这种行为与这些颜色相匹配。与 不同，对于 而言，三维线性化是必不可少的，因为三维场景通常会执行色调映射。"green" PrincipledMaterial Qt Quick Qt Quick
• 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，具体取决于 的纹理属性中使用的是 还是 。将 属性设置为 false 会导致着色器暴露出一个虚假纹理，这意味着着色器仍能正常工作，但会对含有不透明黑色图像内容的纹理进行采样。请注意，采样器的属性必须始终引用 对象，而不是直接引用 。说到 属性，与源、平铺和过滤相关的属性是自定义材质中唯一隐式考虑的属性，其余属性（如 UV 变换）则由自定义着色器根据自己的需要来实现。TextureInput Texture CubeMapTexture enabled TextureInput Texture Texture

无阴影自定义材质

以下是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 顶点和片段着色器片段可如下所示。请注意，着色器不声明也不得声明制服或顶点输入，因为 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 轴方向和剪辑深度进行内置变换。
• 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 生成的着色器代码。与无着色器材质不同，有着色器材质可自行提供顶点和片段着色器主要功能的几乎所有逻辑，从而避免为光照、阴影、全局光照等添加生成的代码、有阴影的材质可正常生成着色器，就像自定义材质是一个PrincipledMaterial 。顶点和片段着色器片段应提供可选函数，然后在某些点上调用这些函数，使它们有可能自定义颜色和其他值，然后用于计算光照和最终片段颜色。

着色自定义材质的片段着色器可以实现多个函数，而不是只实现一个MAIN 函数。包括MAIN 在内的所有函数都可在着色自定义材质中选择执行。空着色器片段，甚至完全不指定vertexShader 或fragmentShader 属性也是完全有效的。

着色自定义材质中的顶点着色器片段

顶点着色器片段中可以实现以下功能：

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

  示例，既依赖 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 以外的值，可以影响片段的最终 alpha 值。(注意，这通常还需要在sourceBlend 和destinationBlend 中启用阿尔法混合）。

  另一种情况是没有提供自定义SPECULAR_LIGHT 函数，或者在SceneEnvironment 中设置了光探针。可以在MAIN 中将金属度、粗糙度和其他影响镜面反射计算的值设置为所需的自定义值。

  该函数可以写入以下特殊变量。写入这些变量的值通常要么是硬编码，要么是根据映射到制服的 QML 属性计算出来的。其语义与PrincipledMaterial 相同。

  • vec4BASE_COLOR - 基本颜色和材料 alpha 值。对应于built-in materials' color property 。当未实现光照处理器功能时，在MAIN 中设置自定义基色会很方便，因为默认光照计算会考虑该基色。默认值为vec4(1.0) ，即白色，alpha 值为 1.0。alpha 值会影响片段的最终 alpha 值。最终的 alpha 值是对象（模型）的不透明度乘以基色 alpha。在着色器代码中直接指定值，而不是依赖 QML 中颜色属性的统一值时，请注意，如果需要，应由着色器执行 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 中颜色属性的统一值时，请注意，如果需要，应由着色器执行 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;
  }

  另一个例子是通过对纹理采样来设置基色和 alpha：

  VARYING vec2 texcoord;
  void MAIN()
  {
      BASE_COLOR = texture(uColorMap, texcoord);
  }
• 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 Diffuse light color.
  • floatSHADOW_CONTRIB Shadow contribution（阴影贡献值），或 1。
  • vc3TO_LIGHT_DIR 指向光源的矢量。 vc
  • 3NORMAL 世界空间中的法线矢量。
  • vc4BASE_COLOR 基准色和材质 alpha 值。
  • 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 基准色和材质 alpha 值。
  • 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 ）制服外，函数还可以读取以下特殊变量：

  • vec3LIGHT_COLOR 漫反射光颜色。
  • floatLIGHT_ATTENUATION 光衰减。
  • floatSHADOW_CONTRIB 阴影贡献度，如果完全没有阴影或不接收阴影，则为 1.0。
  • vec3TO_LIGHT_DIR 指向光源的矢量。
  • floatSPOT_FACTOR 聚光因子。
  • vec3NORMAL 世界空间中的法线矢量。
  • vec4BASE_COLOR 基色和材质 alpha 值。
  • 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。对于
  • 点光源
  • ，该值与LIGHT_ATTENUATION * SPOT_FACTOR ofvoid SPOT_LIGHT() 相同
  。
  • floatSHADOW_CONTRIB 阴影贡献，如果完全没有阴影或不接收阴影，则为 1.0。
  • vec3FRESNEL_CONTRIB 内建菲涅尔计算的菲涅尔贡献。
  • vec3TO_LIGHT_DIR 指向光源的矢量。
  • vec3NORMAL 世界空间中的法线矢量。
  • vec4BASE_COLOR 基本颜色和材质 alpha 值。
  • floatMETALNESS 金属度量。float
ROUGHNESS
• • 粗糙度
  • 量。float
SPECULAR_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)

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

  • vec4DIFFUSE 片段流水线的最终漫反射项。
  • 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 基色和材质 alpha 值。
  • floatAO_FACTOR 屏幕空间遮挡系数。
  • floatSPECULAR_AMOUNT 镜面光量。
  • floatROUGHNESS 片段管道的最终发射项。
  • vec3NORMAL 世界空间中的法线向量。 vec3
VIEW_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.<variable name> 访问这些用户定义的变量。

例如，阴影自定义材料可以获取 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;
}

其他特殊关键字

自定义片段着色器代码可自由访问制服（如CAMERA_DIRECTION 或CAMERA_POSITION ）以及从自定义顶点着色器传递的变化。此外，还有一些内置变化作为特殊关键字可用。其中一些是可选的，顶点着色器MAIN 可以自行计算并传递这些变化，但为了减少重复数据，片段着色器也可以依赖这些内置变化。这些内置项可在光处理器函数和片段 MAIN 中使用。

• vec3VAR_WORLD_NORMAL - 由NORMAL_MATRIX 进行插值法线变换。
• vec3VAR_WORLD_TANGENT - 经MODEL_MATRIX 变换的切线插值。
• 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) 为左上角。底层图形应用程序接口的这种差异与大多数自定义材质无关。一个值得注意的例外是采样SCREEN_TEXTURE 的纹理坐标不是基于FRAGCOORD 。由于SCREEN_TEXTURE 的方向本质上与底层图形 API 相关联，因此使用网格中的纹理坐标可能需要对 Y 坐标进行适当调整。

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

  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 的一部分。通常情况下，SCREEN_TEXTURE 与BASE_COLOR 结合使用，在MAIN 中使用。例如，以下自定义片段着色器应用了浮雕效果，同时使不透明对象未接触到的片段保持透明。假定带有材质的对象位于前方，并启用了混合功能。

  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 相同，不同之处在于这种纹理会生成 mipmaps。从性能上来说，这可能是一个昂贵的功能，这取决于屏幕尺寸，而且每次渲染场景时都要生成 mipmaps。因此，除非自定义材质实现了依赖纹理 mip 层的技术（例如在着色器中使用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
• 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;
  }
• VIEW_INDEX - 在自定义着色器代码中使用时，这是一个（非插值）uint 变量。不使用多视图渲染时，该值始终为 0。使用多视图渲染时，其值为当前视图索引（例如 gl_ViewIndex）。当启用多视图渲染时，与 及类似功能结合使用时尤其有用。DEPTH_TEXTURE

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

属性文档