Sceneform asset 文件参考

Sceneform Asset 定义 (*.sfa) 文件是 Sceneform 二进制 asset (*.sfb) 的人类可读说明。 它指向您的源 asset 中的模型、材料定义和纹理，还为 Sceneform 的基于物理材料提供了材料参数。

此文件会在首次导入时由 Sceneform Android Studio 插件自动生成，但您可以调整属性来更改 asset 的外观。 本参考描述您可以配置用于修改 asset 外观的属性。 sfa 中未出现的可选属性有自己的默认值。 sfa 的语法为 jsonnet，是对 JSON 的扩展。

语法

{
   materials: [
      {
         name: "<name>",
         parameters: [
            {
               <parameterName>: <parameterDefaultValue>,
            },
            …
         ],
         source: "path/to/source_material.sfm",
      },
      …
   ],
   model: {
      attributes: [
         "Position",
         "TexCoord",
         "Orientation",
      ],
      file: "path/to/source_asset.ext",
      name: "<Name>",
      scale: 1.0,
      recenter: false,
      smoothing_angle: 45.0,
      flip_texture_coordinates: false,
      fix_infacing_normals: false,
   },
   samplers: [
      {
         file: "path/to/source_texture.ext",
         name: "<name>",
         params: {
            usage_type: "Color",
            mag_filter: "Linear",
            min_filter: "NearestMipmapLinear",
            wrap_s: "Repeat",
            wrap_t: "Repeat",
         },
         pipeline_name: "<pipeline_name>",
      },
      …
   ]
}

属性

materials[].parameters

此区块的内容取决于由 source 属性指定的材料定义。

对于默认材料 (*.sfm)，请参阅受支持的参数的列表：

• OBJ asset：obj_material.sfm
• FBX asset：fbx_material.sfm
• glTF asset：gltf_material.sfm

对于自定义材料 (*.mat)，*.mat 文件中指定了受支持的参数的列表：

• 请参阅自定义材料参考

materials[].source

指定材料定义文件 - 默认材料定义 (*.sfm) 文件或自定义材料 定义 (*.mat) 文件。

model.attributes

定义在源模型导入期间计算的一组已导出顶点流。 可能的值为：

值	说明
"Color"	顶点 COLOR。
"Orientation"	顶点 TANGENT。
"Position"	顶点 POSITION。
"TexCoord"	TEXCOORD0，第一个 UV 坐标。

model.file

必需的属性，包含源 asset 文件的文件系统路径。 当前受支持的格式为 *.fbx、*.obj、*.gltf、*.glb。

model.scale

可选属性，默认值为 1.0。 控制导出的模型与 源 asset 内容的比例。 比例为 2.0 将使 asset 达到原来的两倍。

：Sceneform 位置值以米为单位。 要以标准单位考虑差异，在初始导入时将自动计算比例，使最大轴不小于 5cm，最小轴不大于 1m。 这是为了保证初始导入体验；这些限制不会强制。

model.recenter

可选属性，默认值为 false。 控制导出的几何形状的定位。 可能的值为：

值	说明
false	几何形状将按创建时的原样导出，不进行转换。
true	几何形状的中心将置于原点处。
"root"	几何形状导出时水平中心将位于原点，并进行垂直偏移，使最低的顶点与原点持平。 这可用于确保锚点或平面上的导出模型将立在此锚点上方。
{x:float, y:float, z:float}	几何形状导出时，原点将根据指示的点放置。 {x:0, y:0, z:0} 对应于几何形状与轴对齐的边界框的最小值。 {x:1, y:1, z:1} 对应于几何形状与轴对齐的边界框的最大值。}

model.smoothing_angle

以度为单位指定的可选属性，默认值为 45。 没有逐顶点法线的源 asset（例如， obj）将使用平滑角度生成逐顶点法线，以限制顶点法线计算中使用的面法线集合。

模型中超过此角度的边将显示为“硬边”或分面边，未超过此角度的边将显示为平滑边。

model.flip_texture_coordinates

可选属性，默认值为 false。 如果为 true，纵坐标将在导入期间反转 ((u, v) -> (u, 1 - v))。 这有助于考虑 OpenGL/Direct3D 之间的历史差异。

model.fix_infacing_normals

可选属性，默认值为 false。 如果为 true，导入将尝试查找和纠正内向法线（指向表面的法线，与背离表面的法线相对）。

samplers[].params.usage_type

定义运行时如何解读编码图像数据。 将 "Color" 用于 sRGB 图像纹理。 使用 "Data" 或 "Normal" 将图像内容视为线性空间内容进行处理。

samplers[].params.mag_filter

定义当采样的 mipmap 大于对其采样的几何形状的像素尺寸时使用的源码压缩过滤器。 可能的值为：

值	说明
"Nearest"	对应于 GL_NEAREST。 返回最接近（按曼哈顿距离计算）带纹理像素中心的纹理元素的值。
"Linear"	对应于 GL_LINEAR。 返回最接近带纹理像素中心的四个纹理元素的加权平均值。 这些元素可能包括边界纹理元素，具体取决于纹理 wrap_s 和纹理 wrap_t 的值以及精确映射。

samplers[].params.min_filter

定义当采样的 mipmap 大于对其采样的几何形状的像素尺寸时使用的源码压缩过滤器。 可能的值为：

值	说明
"Nearest"	对应于 GL_NEAREST。 返回最接近（按曼哈顿距离计算）带纹理像素中心的纹理元素的值。
"Linear"	对应于 GL_LINEAR。 返回最接近带纹理像素中心的四个纹理元素的加权平均值。 这些元素可能包括边界纹理元素，具体取决于纹理 wrap_s 和纹理 wrap_t 的值以及精确映射。
"NearestMipmapNearest"	对应于 GL_NEAREST_MIPMAP_NEAREST。 选择与带纹理像素大小匹配度最高的 mipmap，并按照 "Nearest" 标准（最接近像素中心的纹理元素）来生成纹理值。
"LinearMipmapNearest"	对应于 GL_NEAREST_MIPMAP_LINEAR。 选择与带纹理像素大小匹配度最高的两个 mipmap，并按照 "Nearest" 标准（最接近像素中心的纹理元素）从每个 mipmap 生成一个纹理值。 最终纹理值是这两个值的加权平均值。
"LinearMipmapLinear"	对应于 GL_LINEAR_MIPMAP_LINEAR。 选择与带纹理像素大小匹配度最高的两个 mipmap，并按照 "Linear" 标准（最接近像素中心的四个纹理元素的加权平均值）从每个 mipmap 生成一个纹理值。 最终纹理值是这两个值的加权平均值。

samplers[].params.wraps

可选属性，默认值为 "Repeat"。 控制水平包裹行为。

值	说明
"ClampToBorder"	对应于 GL_CLAMP_TO_BORDER。
"ClampToEdge"	对应于 GL_CLAMP_TO_BORDER。
"MirroredRepeat"	对应于 GL_MIRRORED_REPEAT。
"MirrorClampToEdge"	对应于 GL_MIRROR_CLAMP_TO_EDGE。
"Repeat"	对应于 GL_REPEAT。

samplers[].params.wrapt

可选属性，默认值为 "Repeat"。 控制垂直包裹行为。

值	说明
"ClampToBorder"	对应于 GL_CLAMP_TO_BORDER。
"ClampToEdge"	对应于 GL_CLAMP_TO_BORDER。
"MirroredRepeat"	对应于 GL_MIRRORED_REPEAT。
"MirrorClampToEdge"	对应于 GL_MIRROR_CLAMP_TO_EDGE。
"Repeat"	对应于 GL_REPEAT。

默认材料的参数

Sceneform 提供了三个默认的材料定义：一个用于 OBJ asset，一个用于 FBX asset，一个用于 glTF asset。

本部分列出了每个默认材料定义支持的材料参数。

obj_material.sfm

参数	值	说明
baseColor	<sampler_name>	将 baseColor 计算为采样器值与插值颜色的乘积。
	null	将 baseColor 计算为插值颜色（不存在插值颜色时计算为白色）。
baseColorTint	<vec4>	对计算的 baseColor 值应用着色，以 [r, b, g, a] 形式指定。
metallic	<float_value>	控制材料的金属性。 使用 0.0 代表非金属材料。 使用 1.0 代表金属材料。
roughness	<float_value>	控制材料的粗糙度。 为有光泽材料使用低粗糙度（0.0 表示完美镜面）。 为漫射材料使用高粗糙度（1.0 表示不发光的材料）。
opacity	null	完全不透明。
	<float_value>	启用透明度。 1.0 为完全不透明。 0.0 为完全透明。

fbx_material.sfm

参数	值	说明
baseColor	<vec4>	baseColorMap 结果着色因子，以 [r, g, b, a] 形式指定。
baseColorMap	<sampler_name>	结果是 baseColorMap 采样器的值。
	null	解析为白色。
normalMap	<sampler_name>	将样本结果解读为一条切线空间法线，在照明计算中使用。
	null	使用 [0, 0, 1] 常量作为我们的切线空间法线。
metallic	<float_value>	缩放 metallicMap 来控制材料的金属性。 使用 0.0 代表非金属材料。 使用 1.0 代表金属材料。
metallicMap	<sampler_name>	使用采样器的红色通道值作为我们的 metallicMap 值。
	null	使用 1.0 常量，由 metallic 缩放。
roughness	<float_value>	缩放 roughnessMap 来控制材料的粗糙度。 为有光泽材料使用低粗糙度。 为漫射材料使用高粗糙度。
roughnessMap	<sampler_name>	使用采样器的红色通道值作为我们的 roughnessMap 值。
	null	使用 1.0 常量，由 roughness 缩放。
reflectance	<float_value>	控制材料的反射率。 默认值 0.5 涵盖了几乎所有可能存在的材料。
opacity	null	无显式不透明度控制。 如果源数据中指定了不透明贴图，将通过透明混合渲染材料。

gltf_material.sfm

参数	值	说明
baseColorFactor	<vec4>	baseColor 结果着色因子，以 [r, g, b, a] 形式指定。
normal	<sampler_name>	将样本结果解读为一条切线空间法线，在照明计算中使用。
	null	使用 [0, 0, 1] 常量作为我们的切线空间法线。
metallicFactor	<float_value>	缩放 metallicRoughness 来控制材料的金属性。 使用 0.0 代表非金属材料。 使用 1.0 代表金属材料。
roughnessFactor	<float_value>	缩放 metallicRoughness 来控制材料的粗糙度。 为有光泽材料使用低粗糙度。 为漫射材料使用高粗糙度。
metallicRoughness	<sampler_name>	使用采样器的绿色通道代表粗糙度（由 roughnessFactor 缩放）。 使用采样器的蓝色通道代表金属性（由 metallicFactor 缩放）。
	null	使用 metallicFactor 和 roughnessFactor。
occlusion	<sampler_name>	使用采样器的红色通道代表环境光遮蔽。
	null	如果存在 metallicRoughness 纹理，则使用红色通道来推动环境光遮蔽。
emissiveFactor	<float_value>	缩放 emissive 来控制材料的发光。 使用 0.0 代表自身不发光的材料。
emissive	<sampler_name>	使用采样器的颜色作为我们的发光值。
	null	不发光。
reflectance	<float_value>	控制材料的反射率。 默认值 0.5 涵盖了几乎所有可能存在的材料。

如果源数据中指定了 alpha 截止，将通过遮罩混合渲染材料。 如果在源内容上启用了混合，将启用透明度。