cesium1.105.1以此版本的自定义着色器CustomShader中文文档

CustomShader（自定义着色器） 文档

Constructor（构造函数）

const customShader = new Cesium.CustomShader({
  // 用户想要添加到着色器的任何自定义uniform。
  //Uniform是一种在着色器程序中定义的全局变量，它们可以在着色器程序的任何地方使用，但它们的值在每个渲染周期中都是不变的。
  // 这些可以在运行时通过以下方式 更改 customShader.setUniform()
  uniforms: {
    u_time: {
      value: 0, // 初始值
      type: Cesium.UniformType.FLOAT
    },
    // Textures can be loaded from a URL, a Resource, or a TypedArray.//纹理可以从 URL、资源或类型数组加载
    // 有关更多详细信息，请参阅Uniforms部分
    u_externalTexture: {
      value: new Cesium.TextureUniform({
        url: "http://example.com/image.png"
      }),
      type: Cesium.UniformType.SAMPLER_2D
    }
  }
  // 将出现在自定义顶点和片段着色器文本中的自定义变化。
  varyings: {
    v_customTexCoords: Cesium.VaryingType.VEC2
  },
  // configure where in the fragment shader's materials/lighting pipeline the custom shader goes. More on this below.
  //配置自定义着色器在片段着色器的材质/光照管线中的位置。更多内容见下文。
  mode: Cesium.CustomShaderMode.MODIFY_MATERIAL,
  // either PBR (physically-based rendering) or UNLIT depending on the desired results.
  //PBR（基于物理的渲染）或 UNLIT，具体取决于所需的结果。
  lightingModel: Cesium.LightingModel.PBR,
  // Force the shader to render as transparent, even if the primitive had an opaque material
  //强制着色器渲染为透明，即使基元具有不透明材质
  translucencyMode: Cesium.CustomShaderTranslucencyMode.TRANSLUCENT,
  // Custom vertex shader. This is a function from model space -> model space.VertexInput is documented below
  // 自定义顶点着色器。这是模型空间 ->模型空间的函数.VertexInput输入记录如下
  vertexShaderText: `
    // IMPORTANT: the function signature must use these parameter names. This
    // makes it easier for the runtime to generate the shader and make optimizations.
    //重要说明：函数签名必须使用这些参数名称。这使运行时更容易生成着色器并进行优化。
    void vertexMain(VertexInput vsInput, inout czm_modelVertexOutput vsOutput) {
        // code goes here. An empty body is a no-op.
        //代码在这里……空的内容是无操作的。
    }
  `,
  // Custom fragment shader.
  // FragmentInput will be documented below
  // Regardless of the mode, this always takes in a material and modifies it in place.
  //自定义片元着色器
  //FragmentInput（片元）输入将被记录在下面 
  //无论模式如何，这里需要一个material（材质）并将其modifies（位置）放到位                                           
  fragmentShaderText: `
    // IMPORTANT: the function signature must use these parameter names. This
    // makes it easier for the runtime to generate the shader and make optimizations.
    // 重要提示：函数签名必须使用这些参数名称。这
    // 使运行时更容易生成着色器并进行优化。
    void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) {
        // code goes here. e.g. to set the diffuse color to a translucent red:
        //代码在这里。例如将漫反射颜色设置为半透明的红色：
        material.diffuse = vec3(1.0, 0.0, 0.0);
        material.alpha = 0.5;
    }
  `,
});

Applying A Custom Shader（应用自定义着色器）

自定义着色器可以应用于 3D Tiles 或Model
如下：

const customShader = new Cesium.CustomShader(/* ... */);

// Applying to all tiles in a tileset.
//应用于 tileset 中的所有 tile
const tileset = await Cesium.Cesium3DTileset.fromUrl(
  "http://example.com/tileset.json", {
    customShader: customShader
});
viewer.scene.primitives.add(tileset);

// Applying to a model directly
//直接应用于模型
const model = await Cesium.Model.fromGltfAsync({,
  url: "http://example.com/model.gltf",
  customShader: customShader
});

Uniforms

自定义着色器目前支持以下统一类型：

UniformType（统一类型）	GLSL type（GLSL类型）	JS type（JS型）
FLOAT	float	Number
VEC2	vec2	Cartesian2
VEC3	vec3	Cartesian3
VEC4	vec4	Cartesian4
INT	int	Number
INT_VEC2	ivec2	Cartesian2
INT_VEC3	ivec3	Cartesian3
INT_VEC4	ivec4	Cartesian4
BOOL	bool	Boolean
BOOL_VEC2	bvec2	Cartesian2
BOOL_VEC3	bvec3	Cartesian3
BOOL_VEC4	bvec4	Cartesian4
MAT2	mat2	Matrix2
MAT3	mat3	Matrix3
MAT4	mat4	Matrix4
SAMPLER_2D	sampler2D	TextureUniform

Texture Uniforms（纹理Uniforms）

Texture uniforms have more options, which have been encapsulated in the
TextureUniform class. Textures can be loaded from a URL, a Resource or a
typed array. Here are some examples:

Texture uniforms有更多的选项，已经封装在 TextureUniform class.可以从a URL、aResource或 a typed array加载纹理。这里有些例子：

const textureFromUrl = new Cesium.TextureUniform({
  url: "https://example.com/image.png",
});

const textureFromTypedArray = new Cesium.TextureUniform({
  typedArray: new Uint8Array([255, 0, 0, 255]),
  width: 1,
  height: 1,
  pixelFormat: Cesium.PixelFormat.RGBA,
  pixelDatatype: Cesium.PixelDatatype.UNSIGNED_BYTE,
});

// TextureUniform还提供了用于控制采样器的选项
const textureWithSampler = new Cesium.TextureUniform({
  url: "https://example.com/image.png",
  repeat: false,
  minificationFilter: Cesium.TextureMinificationFilter.NEAREST,
  magnificationFilter: Cesium.TextureMagnificationFilter.NEAREST,
});

Varyings（变换）

Varyings 在构造函数中声明CustomShader。这会自动将诸如out float v_userDefinedVarying;和in float v_userDefinedVarying;之类的行分别添加到 GLSL 顶点和片段着色器的顶部。

用户负责为这个 varying in 赋值 vertexShaderText并在 中使用它fragmentShaderText。例如：

const customShader = new Cesium.CustomShader({
  // 在这里声明了varyings
  varyings: {
    v_selectedColor: Cesium.VaryingType.VEC4,
  },
  //用户在顶点着色器中分配varyings
  vertexShaderText: `
    void vertexMain(VertexInput vsInput, inout czm_modelVertexOutput vsOutput) {
        float positiveX = step(0.0, vsOutput.positionMC.x);
        v_selectedColor = mix(
            vsInput.attributes.color_0,
            vsInput.attributes.color_1,
            vsOutput.positionMC.x
        );
    }
  `,
  // 用户在片段着色器中使用 varying
  fragmentShaderText: `
    void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) {
        material.diffuse = v_selectedColor.rgb;
    }
  `,
});

自定义着色器支持以下不同类型：

VaryingType（Varying类型）	GLSL type（GLSL类型）
FLOAT	float
VEC2	vec2
VEC3	vec3
VEC4	vec4
MAT2	mat2
MAT3	mat3
MAT4	mat4

Custom Shader Modes(自定义着色器模式)

自定义片段着色器是可配置的，因此它可以在材质或光照之前/之后使用。以下是内容的摘要 模式可用。
模式可用

Mode（模式）	Fragment shader pipeline（片元着色器管道）	Description（描述）
MODIFY_MATERIAL (default)（默认）	material -> custom shader -> lighting（材质 -> 自定义着色器 ->照明）	The custom shader modifies the results of the material stage（自定义着色器修改材质流程）
REPLACE_MATERIAL	custom shader -> lighting（自定义着色器 - >照明）	Don’t run the material stage at all, but procedurally generate it in the custom shader（根本不运行材质阶段，而是在自定义着色器中按程序生成它）

在上面的内容中，“material”对纹理进行预处理，从而生成“czm_modelMaterial”。这主要与PBR相关，但即使对于UNLIT，也会处理基本颜色纹理。

VertexInput struct（VertexInput 结构）

自动生成（cesium内置）的包含属性的 GLSL 结构。

struct VertexInput {
    // Processed attributes. See the Attributes Struct section below.
    //已处理的attributes。请参见下面的“Struct”部分。
    Attributes attributes;
    // Feature IDs/Batch IDs. See the FeatureIds Struct section below.
    //Feature ID/Batch ID。请参阅下面的 FeatureIds Struct部分。
    FeatureIds featureIds;
    // Metadata properties. See the Metadata Struct section below.
    //Metadata属性。请参阅下面的Metadata Struct部分
    Metadata metadata;
    // Metadata class properties. See the MetadataClass Struct section below.
    //Metadata类属性。请参阅下面的MetadataClass Struct部分
    MetadataClass metadataClass;
    // Metadata statistics. See the Metadata Statistics Struct section below
    //Metadata统计。请参阅下面的Metadata统计结构部分
    MetadataStatistics metadataStatistics;
};

FragmentInput struct(FragmentInput结构)

这个结构类似于“VertexInput”，但还有一些自动的
各种坐标空间中位置的变量。

struct FragmentInput {
    // Processed attribute values. See the Attributes Struct section below.
    //已处理过的attribute值。请参阅下面的Attributes Struct部分。
    Attributes attributes;
    // Feature IDs/Batch IDs. See the FeatureIds Struct section below.
    Feature ID/Batch ID。请参阅下面的 FeatureIds Struct部分。
    FeatureIds featureIds;
    // Metadata properties. See the Metadata Struct section below.
    // Metadata类属性。请参阅下面的MetadataClass Struct部分
    Metadata metadata;
    // Metadata class properties. See the MetadataClass Struct section below.
    //Metadata类属性。请参阅下面的MetadataClass Struct部分
    MetadataClass metadataClass;
    // Metadata statistics. See the Metadata Statistics Struct section below
    //Metadata统计。请参阅下面的Metadata统计结构部分
    MetadataStatistics metadataStatistics;
};

Attributes Struct

Attributes 结构体根据自定义着色器中使用的变量和要渲染的基元中的属性动态生成。例如,如果用户在着色器中使用 fsInput.attributes.texCoord_0,运行时将生成从模型中的属性 TEXCOORD_0
提供此值所需的代码(如果可用)。如果一个基元没有满足自定义着色器所需的属性,则在可能的情况下会推断出默认值,以便着色器仍然可以编译。否则,将禁用该基元的 custom vertex/fragment shader(定制顶点/片段着色器)部分。内置属性的完整列表如下。某些属性有一个固定的索引,即0、1、2,…(例如texCoord_0),这些属性用N表示。

Corresponding Attribute in Model(模型中的对应属性)	variable in shader(着色器中的变量)	Type(类型)	Available in Vertex Shader?(在顶点着色器中可用？)	Available in Fragment Shader?(在片段着色器中可用？)	Description(描述)
POSITION	positionMC	vec3	Yes	Yes	Position in model coordinates(模型坐标中的位置)
POSITION	positionWC	vec3	No	Yes	Position in world coordinates (WGS84 ECEF (x, y, z)). Low precision.(世界坐标中的位置 （WGS84 ECEF ）。精度低。(x, y, z))
POSITION	positionEC	vec3	No	Yes	Position in eye coordinates.(眼睛坐标中的位置)
NORMAL	normalMC	vec3	Yes	No	Unit-length normal vector in model coordinates. Only available in the vertex shader(模型坐标中的单位长度法线向量。仅在顶点着色器中可用)
NORMAL	normalEC	vec3	No	Yes	Unit-length normal vector in eye coordinates. Only available in the fragment shader(眼睛坐标中的单位长度法线向量。仅在片段着色器中可用)
TANGENT	tangentMC	vec3	Yes	No	Unit-length tangent vector in model coordinates. This is always a vec3. For models that provide a w component, that is removed after computing the bitangent vector.(模型坐标中的单位切向量。这始终是一个vec3。对于提供w分量的模型,在计算副切向量后会删除w分量。)
TANGENT	tangentEC	vec3	No	Yes	Unit-length tangent vector in eye coordinates. This is always a vec3. For models that provide a w component, that is removed after computing the bitangent vector.(眼坐标中的单位切向矢量。这始终是一个vec3。对于提供w分量的模型,计算副切线矢量后会删除它。)
NORMAL & TANGENT	bitangentMC	vec3	Yes	No	Unit-length bitangent vector in model coordinates. Only available when both normal and tangent vectors are available.
NORMAL & TANGENT	bitangentEC	vec3	No	Yes	Unit-length bitangent vector in eye coordinates. Only available when both normal and tangent vectors are available.
TEXCOORD_N	texCoord_N	vec2	Yes	Yes	N-th set of texture coordinates.
COLOR_N	color_N	vec4	Yes	Yes	N-th set of vertex colors. This is always a vec4; if the model does not specify an alpha value, it is assumed to be 1.
JOINTS_N	joints_N	ivec4	Yes	Yes	N-th set of joint indices
WEIGHTS_N	weights_N	vec4

自定义属性也是可用的,虽然它们被重命名为使用小写字母和下划线。例如,模型中名为 _SURFACE_TEMPERATURE 的属性在着色器中会变为 fsInput.attributes.surface_temperature

FeatureIds struct

• 此结构体动态生成,用于将各种特征ID收集到一个集合中,无论该值来自属性、纹理还是变化。
  特征ID表示为GLSL int类型,尽管在WebGL 1中有几个限制:
  • 超过2^24,值可能会损失精度,因为WebGL 1实现highp int作为浮点值。
  • 理想情况下,类型应为uint,但直到WebGL 2才可用。

3D Tiles 1.0 Batch IDs

• 在3D Tiles 1.0中,在基元内识别特征的同一个概念被称为“BATCH_ID”或旧的“_BATCHID”。这些批处理ID被重命名为单个特征ID,索引总是为0:
  • vsInput.featureIds.featureId_0(顶点着色器)
  • fsInput.featureIds.featureId_0(片元着色器)

EXT_mesh_features/EXT_instance_features Feature IDs

当使用glTF扩展EXT_mesh_features或EXT_instance_features时，feature ID出现在两个位置：

• 任何glTF基元都可以有一个featureIds数组。 featureIds数组可能包含feature ID属性，隐式feature ID属性和/或feature ID纹理。 无论feature ID的类型如何，它们都会出现在自定义着色器中作为（vsInput | fsInput）。featureIds.featureId_N，其中N是featureIds数组中的feature IDs的索引。
• 具有EXT_mesh_gpu_instancing和EXT_instance_features的任何glTF节点都可以定义feature IDs。 这些可能是feature ID属性或隐式feature ID属性，但不是feature ID纹理。 这些将出现在自定义着色器中作为（vsInput | fsInput）。featureIds.instanceFeatureId_N，其中N是featureIds数组中的功能ID的索引。此外，仅支持在片段着色器中使用feature ID纹理。

如果一组feature IDs包括标签属性（在EXT_mesh_features中新增），则该标签将作为别名可用。 例如，如果标签：“alias”，则（vsInput | fsInput）。featureIds.alias将与featureId_N一起在着色器中可用。
例如，假设我们有一个具有以下feature IDs的glTF基元：

"nodes": [
  {
    "mesh": 0
    "extensions": {
      "EXT_mesh_gpu_instancing": {
        "attributes": {
          "TRANSLATION": 3,
          "_FEATURE_ID_0": 4
        }
      },
      "EXT_instance_features": {
        "featureIds": [
          {
            // Default feature IDs (instance ID)
            //
            // Vertex Shader:
            //   vsInput.featureIds.instanceFeatureId_0 OR
            //   vsInput.featureIds.perInstance
            // Fragment Shader:
            //   fsInput.featureIds.instanceFeatureId_0 OR
            //   fsInput.featureIds.perInstance
            "label": "perInstance",
            "propertyTable": 0
          },
          {
            // Feature ID attribute. This corresponds to _FEATURE_ID_0 from the
            // instancing extension above. Note that this is
            // labeled as instanceFeatureId_1 since it is the second feature ID
            // set in the featureIds array
            //
            // Vertex Shader: vsInput.featureIds.instanceFeatureId_1
            // Fragment Shader: fsInput.featureIds.instanceFeatureId_1
            //
            // Since there is no label field, instanceFeatureId_1 must be used.
            "propertyTable": 1,
            "attribute": 0
          },
        ]
      }
    }
  }
],
"meshes": [
  {
    "primitives": [
      {
        "attributes": {
          "POSITION": 0,
          "_FEATURE_ID_0": 1,
          "_FEATURE_ID_1": 2
        },
        "extensions": {
          "EXT_mesh_features": {
            "featureIds": [
              {
                // Feature ID Texture
                //
                // Vertex Shader: (Not supported)
                // Fragment Shader:
                //   fsInput.featureIds.featureId_0 OR
                //   fsInput.featureIds.texture
                "label": "texture",
                "propertyTable": 2,
                "index": 0,
                "texCoord": 0,
                "channel": 0
              },
              {
                // Default Feature IDs (vertex ID)
                //
                // Vertex Shader:
                //   vsInput.featureIds.featureId_1 OR
                //   vsInput.featureIds.perVertex
                // Fragment Shader:
                //   fsInput.featureIds.featureId_1 OR
                //   fsInput.featureIds.perVertex
                "label": "perVertex",
                "propertyTable": 3,
              },
              {
                // Feature ID Attribute (_FEATURE_ID_0). Note that this
                // is labeled featureId_2 for its index in the featureIds
                // array
                //
                // Vertex Shader: vsInput.featureIds.featureId_2
                // Fragment Shader: fsInput.featureIds.featureId_2
                //
                // Since there is no label, featureId_2 must be used.
                "propertyTable": 4,
                "attribute": 0
              },
              {
                // Feature ID Attribute (_FEATURE_ID_1). Note that this
                // is labeled featureId_3 for its index in the featureIds
                // array
                //
                // Vertex Shader: vsInput.featureIds.featureId_3
                // Fragment Shader: fsInput.featureIds.featureId_3
                "propertyTable": 5,
                "attribute": 1
              }
            ]
          }
        }
      },
    ]
  }
]

Legacy EXT_feature_metadata Feature IDs

EXT_feature_metadata是EXT_mesh_features的早期草案。尽管feature ID的概念没有太大变化，但JSON结构略有不同。在旧版扩展中，featureIdAttributes和featureIdTextures被单独存储。在此CesiumJS实现中，将特征属性和特征纹理连接成一个列表，即featureIds = featureIdAttributes.concat（featureIdTextures）。除了扩展JSON中的这种差异之外，feature ID集的标签方式与EXT_mesh_features相同，即
•（vsInput | fsInput）。featureIds.featureId_N对应于每个基元的组合featureIds数组中的第N个功能ID集。
•（vsInput | fsInput）。featureIds.instanceFeatureId_N对应于具有EXT_mesh_gpu_instancing扩展的节点的featureIds数组中的第N个功能ID集。
为了比较，这里是与上一节相同的示例，转换为EXT_feature_metadata扩展：

"nodes": [
  {
    "mesh": 0,
    "extensions": {
      "EXT_mesh_gpu_instancing": {
        "attributes": {
          "TRANSLATION": 3,
          "_FEATURE_ID_0": 4
        },
        "extensions": {
          "EXT_feature_metadata": {
            "featureIdAttributes": [
              {
                // Feature ID attribute from implicit range
                //
                // Vertex Shader: vsInput.featureIds.instanceFeatureId_0
                // Fragment Shader: fsInput.featureIds.instanceFeatureId_0
                "featureTable": "perInstanceTable",
                "featureIds": {
                  "constant": 0,
                  "divisor": 1
                }
              },
              {
                // Feature ID attribute. This corresponds to _FEATURE_ID_0 from the
                // instancing extension above. Note that this is
                // labeled as instanceFeatureId_1 since it is the second feature ID
                // set in the featureIds array
                //
                // Vertex Shader: vsInput.featureIds.instanceFeatureId_1
                // Fragment Shader: fsInput.featureIds.instanceFeatureId_1
                "featureTable": "perInstanceGroupTable",
                "featureIds": {
                  "attribute": "_FEATURE_ID_0"
                }
              }
            ],
          }
        }
      }
    }
  }
],
"meshes": [
  {
    "primitives": [
      {
        "attributes": {
          "POSITION": 0,
          "_FEATURE_ID_0": 1,
          "_FEATURE_ID_1": 2
        },
        "extensions": {
          "EXT_feature_metadata": {
            "featureIdAttributes": [
              {
                // Implicit Feature ID attribute
                //
                // Vertex Shader: vsInput.featureIds.featureId_0
                // Fragment Shader: fsInput.featureIds.featureId_0
                "featureTable": "perFaceTable",
                "featureIds": {
                  "constant": 0,
                  "divisor": 3
                }
              },
              {
                // Feature ID Attribute (_FEATURE_ID_0). Note that this
                // is labeled featureId_1 for its index in the featureIds
                // array
                //
                // Vertex Shader: vsInput.featureIds.featureId_1
                // Fragment Shader: fsInput.featureIds.featureId_1
                "featureTable": "perFeatureTable",
                "featureIds": {
                  "attribute": "_FEATURE_ID_0"
                }
              },
              {
                // Feature ID Attribute (_FEATURE_ID_1). Note that this
                // is labeled featureId_2 for its index in the featureIds
                // array
                //
                // Vertex Shader: vsInput.featureIds.featureId_2
                // Fragment Shader: fsInput.featureIds.featureId_2
                "featureTable": "otherFeatureTable",
                "featureIds": {
                  "attribute": "_FEATURE_ID_1"
                }
              }
            ],
            "featureIdTextures": [
              {
                // Feature ID Texture. Note that this is labeled featureId_3
                // since the list of feature ID textures is concatenated to the
                // list of feature ID attributes
                //
                // Vertex Shader: (Not supported)
                // Fragment Shader: fsInput.featureIds.featureId_3
                "featureTable": "perTexelTable",
                "featureIds": {
                  "texture": {
                    "texCoord": 0,
                    "index": 0
                  },
                  "channels": "r"
                }
              }
            ]
          }
        }
      },
    ]
  }
]

Metadata struct

此结构包含从EXT_structural_metadata glTF扩展（或旧的EXT_feature_metadata扩展）访问模型的相关元数据属性。
当前支持以下类型的元数据：
• 来自EXT_structural_metadata glTF扩展的属性属性。
• 来自EXT_structural_metadata glTF扩展的属性纹理。
目前仅支持componentType：UINT8类型。无论元数据的来源如何，属性都按property ID收集到单个结构中。考虑以下元数据类：

"schema": {
  "classes": {
    "wall": {
      "properties": {
        "temperature": {
          "name": "Surface Temperature",
          "type": "SCALAR",
          "componentType": "FLOAT32"
        }
      }
    }
  }
}

这将显示在着色器中，如下所示：

struct Metadata {
  float temperature;
}

现在可以访问temperature

vsInput.metadata.temperature 或
fsInput.metadata.temperature.

Normalized values

如果类属性指定normalized：true，则属性将显示在着色器中作为适当的浮点类型（例如float或vec3）。 所有组件都将在[0，1]（无符号）或[-1，1]（有符号）范围内。

例如：

"schema": {
  "classes": {
    "wall": {
      "properties": {
        // damage normalized between 0.0 and 1.0 though stored as a UINT8 in
        // the glTF
        "damageAmount": {
          "name": "Wall damage (normalized)",
          "type": "SCALAR",
          "componentType": "UINT32",
          "normalized": true
        }
      }
    }
  }
}

这将显示为从0.0到1.0的浮点值，可通过(vsInput|fsInput).metadata.damageAmount访问

Offset and scale

如果属性提供offset or scale，则在归一化后自动应用此偏移量或比例（如果适用）。 这对于将值预先缩放到方便的范围非常有用。

例如，考虑将temperature and automatically值自动转换为 Celsius or Fahrenheit

"schema": {
  "classes": {
    "wall": {
      "properties": {
        // scaled to the range [0, 100] in °C
        "temperatureCelsius": {
          "name": "Temperature (°C)",
          "type": "SCALAR",
          "componentType": "UINT32",
          "normalized": true,
          // offset defaults to 0, scale defaults to 1
          "scale": 100
        },
        // scaled/shifted to the range [32, 212] in °F
        "temperatureFahrenheit": {
          "name": "Temperature (°C)",
          "type": "SCALAR",
          "componentType": "UINT32",
          "normalized": true,
          "offset": 32,
          "scale": 180
        }
      }
    }
  }
}

在着色器中, (vsInput|fsInput).metadata.temperatureCelsius将是一个浮点数，其值介于0.0和100.0之间，而
(vsInput|fsInput).metadata.temperatureFahrenheit 将是一个浮点数，其范围为[32.0，212.0]。

Property ID Sanitization

GLSL 只支持字母数字标识符，即不以数字开头的标识符。此外，带有连续下划线 ( __) 的标识符，以及带有gl_前缀的标识符，在 GLSL 中是保留的。为了规避这些限制，属性 ID 修改如下：

1. 将所有非字母数字字符序列替换为单个_。
2. 删除保留gl_前缀（如果存在）。
3. 如果标识符以数字 ( [0-9]) 开头，则前缀为_

以下是结构中自定义着色器中属性 ID 和结果变量名称的几个示例(vsInput|fsInput).metadata

• temperature ℃ -> metadata.temperature_
• custom__property -> metadata.custom_property
• gl_customProperty -> metadata.customProperty
• 12345 -> metadata._12345
• gl_12345 -> metadata._12345

如果以上结果导致空字符串或与其他属性 ID 的名称冲突，则行为未定义。例如：

• ✖️✖️✖️映射到空字符串，因此行为未定义。
• temperature ℃具有名称和的两个属性temperature ℉都将映射到metadata.temperature，因此行为未定义

使用点云 ( .pnts) 格式时，每个点的属性被转码为属性属性。这些属性 ID 遵循相同的约定。

MetadataClass struct

此结构包含每个元数据属性的常量，如类架构中所定义。

无论元数据的来源如何，属性都按属性 ID 收集到一个结构中。考虑以下元数据类：

"schema": {
  "classes": {
    "wall": {
      "properties": {
        "temperature": {
          "name": "Surface Temperature",
          "type": "SCALAR",
          "componentType": "FLOAT32",
          "noData": -9999.0,
          "default": 72.0,
          "min": -40.0,
          "max": 500.0,
        }
      }
    }
  }
}

这将显示在结构字段的着色器中，如下所示：

struct floatMetadataClass {
  float noData;
  float defaultValue; // 'default' is a reserved word in GLSL
  float minValue; // 'min' is a reserved word in GLSL
  float maxValue; // 'max' is a reserved word in GLSL
}
struct MetadataClass {
  floatMetadataClass temperature;
}

将选择每个属性的子结构，以便各个属性（例如noData和defaultValue）与属性的实际值具有相同的类型。

现在可以在顶点着色器中按如下方式访问 noData 和默认值：

float noData = vsInput.metadataClass.temperature.noData;            // == -9999.0
float defaultTemp = vsInput.metadataClass.temperature.defaultValue; // == 72.0
float minTemp = vsInput.metadataClass.temperature.minValue;         // == -40.0
float maxTemp = vsInput.metadataClass.temperature.maxValue;         // == 500.0

或类似地来自fsInput片段着色器中的结构。

MetadataStatistics struct

如果模型是从3D Tiles tilesetstatistics加载的，它可能在tileset.json 的属性中定义了统计信息。这些将在结构的自定义着色器中可用MetadataStatistics.

Organization（组织）

无论元数据的来源如何，属性都通过属性 ID 收集到一个源中。考虑以下元数据类

  "statistics": {
    "classes": {
      "exampleMetadataClass": {
        "count": 29338,
        "properties": {
          "intensity": {
            "min": 0.0,
            "max": 0.6333333849906921,
            "mean": 0.28973701532415364,
            "median": 0.25416669249534607,
            "standardDeviation": 0.18222664489583626,
            "variance": 0.03320655011,
            "sum": 8500.30455558002,
          },
          "classification": {
            "occurrences": {
              "MediumVegetation": 6876,
              "Buildings": 22462
            }
          }
        }
      }
    }
  }

这将显示在结构字段的着色器中，如下所示：

struct floatMetadataStatistics {
  float minValue; // 'min' is a reserved word in GLSL
  float maxValue; // 'max' is a reserved word in GLSL
  float mean;
  float median;
  float standardDeviation;
  float variance;
  float sum;
}
struct MetadataStatistics {
  floatMetadataStatistics intensity;
}

可以从顶点着色器中访问统计值，如下所示：

float minValue = vsInput.metadataStatistics.intensity.minValue;
float mean = vsInput.metadataStatistics.intensity.mean;

或类似地来自fsInput片元着色器中的结构

Types(类型)

对于SCALAR、VECN和MATNtype 属性，统计结构字段minValue、maxValue、median和sum将使用与它们描述的元数据属性相同的类型声明。字段mean、standardDeviation和variance声明为与元数据属性具有相同维度的类型，但具有浮点组件。

对于ENUM类型元数据，该属性的统计结构应该包含一个occurrence字段，但该字段尚未实现

czm_modelVertexOutput struct

• 此结构是内置的，请参阅文档注释。

  该结构包含自定义顶点着色器的输出。这包括：

  • positionMC- 模型空间坐标中的顶点位置。该结构字段可用于扰动或动画顶点。它被初始化为 vsInput.attributes.positionMC。 自定义着色器可以修改它，结果用于计算gl_Position。
  • pointSize- 对应于gl_PointSize。这仅适用于渲染为 的模型gl.POINTS，否则将被忽略。这会覆盖 应用于模型的任何磅值样式Cesium3DTileStyle。

实施注意事项：positionMC不修改图元的边界球体。如果顶点移动到包围球之外，则图元可能会被无意中剔除，具体取决于视锥体。

czm_modelMaterial struct

此结构是内置的，请参阅文档注释。czm_material这与旧的 Fabric 系统类似，但由于支持 PBR 照明，因此字段略有不同。

此结构用作片段着色器管道阶段的基本输入/输出。例如：

• 物质阶段产生物质
• 照明阶段接收材质，计算照明，并将结果存储到material.diffuse
• 自定义着色器（无论它在管线中的哪个位置）接收一种材质（即使它是具有默认值的材质）并对其进行修改

Material color space (材质色彩空间)

材料颜色（例如material.diffuse）始终在线性颜色空间中，即使lightingModel是LightingModel.UNLIT。

当scene.highDynamicRange是 时false，最终计算的颜色（在自定义着色器和光照之后）被转换为sRGB