Sceneform SDK for Android 是开源的 (github.com/google-ar/sceneform-android-sdk)，版本为 1.16.0。
此网站 (developers.google.com/sceneform) 是旧版 Sceneform SDK for Android 1.15.0 的文档归档。
请勿使用 Sceneform Maven 工件 1.17.0 版。
可以使用 1.17.1 Maven 工件。但是，1.17.1 工件与 1.15.0 工件相同，但不包括版本。

此页面由 Cloud Translation API 翻译。

Sceneform 资源文件参考

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

此文件由 Sceneform Android Studio 插件首次导入时自动生成，但您可以调整属性来更改资源的外观。本参考介绍了可用于配置素材资源外观的属性。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 素材资源：obj_material.sfm
CocoaPods 资源：fbx_material.sfm
glTF 素材资源：gltf_material.sfm

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

请参阅自定义资料参考文档

materials[].source: 指定 Material 定义文件，可以是默认 Material 定义 (*.sfm) 文件，也可以是自定义 Material 定义 (*.mat) 文件。

model.attributes

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

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

model.file: 必需属性，包含来源素材资源文件的文件系统路径。目前支持的格式为 *.fbx、*.obj、*.gltf、*.glb。

model.scale: 可选属性，默认为 1.0。控制导出的模型与源资产内容的缩放比例。2.0 的缩放比例将使资源增加两倍。; 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。没有顶点法线的源资源（例如 obj）将使用 smoothing_angle 生成每个顶点法线，以限制顶点法线计算中使用的面法线集。模型中超过此角度的边缘会变得很“硬”，分面的边缘看起来很平滑。

model.flip_texture_coordinates: 可选属性，默认为 false。如果为 true，则系统会在导入期间垂直坐标反转 ((u, v) -> (u, 1 - v))。这有助于适应 OpenGL/Direct3D 之间的历史差异。

model.fix_infacing_normals: 可选属性，默认为 false。如果为 true，导入将尝试查找和纠正内向法线（指向 Surface 的法线，而不是指向 Surface 的法线）。

samplers[].params.usage_type: 定义运行时如何解读编码后的图片数据。对于 sRGB 图片纹理，请使用 "Color"。使用 "Data" 或 "Normal" 将图片内容视为线性空间内容。默认值为 "Color"。

samplers[].params.mag_filter

定义当采样的 mipmap 大于对其采样的几何图形的像素大小时使用的压缩过滤器。默认值为 "Linear"。可能的值包括：

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

samplers[].params.min_filter

定义当采样的 mipmap 大于对其采样的几何图形的像素大小时使用的压缩过滤器。默认值为 "NearestMipmapLinear"。可能的值包括：

值	说明
`"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.wrap_s

可选属性，默认为 "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.wrap_t

可选属性，默认为 "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 提供三种默认 Material 定义：一个用于 OBJ 资源，一个用于 CocoaPods 资源，一个用于 glTF 资源。

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

`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 截止值，材料将进行遮罩混合渲染。如果源内容已启用混合模式，则系统将启用透明度。

替换或添加纹理

samplers 代码块定义了可用于您的材质的纹理。源自源资产的采样器记录声明 pipeline_name，从而通过源资产中的原始映像路径对其进行唯一标识。字段 file 可更改以包含 app/ 相对文件路径。例如，以下代码：

  {
     file: "sampledata/models/textures/dandy_andy.png",
     name: "andy",
     pipeline_name: "andy.png",
  },

将源资源（在来源资源中称为 andy.png）替换为文件 ./sampledata/models/textures/dandy_andy.png 的内容。

源资源中完全或部分声明的纹理可能无法自动导入到资源中，在这种情况下，可以将其添加到 SFA 中。您可以向属性列表中具有 TexCoord 的任何模型添加纹理。用户指定 injections 代码块，而不是 pipeline_name（仅适用于自动导入的采样器）。

请参考具有 TexCoord 属性但没有纹理的 CocoaPods 示例。您可以在项目文件夹中添加一个图片文件并将其链接到新的采样器块中，然后在注入中将其使用情况声明为 "Normal"，如以下代码所示：

  {
     file: "sampledata/models/cragly_normal.png",
     name: "bumps",
     injections: [
       {usage: "Normal",},
     ],
  },

此时，纹理可以用于您的材料了。如需显示该采样器，请确保 Material 请求其 normalMap 参数的采样器（否则，采样器将处于未使用状态并被剔除）。鉴于采样器块中的名称 bumps，这意味着我们的 Material 块应该包含以下代码：

    {
      normalMap: 'bumps',
    },

注入块的可用用法为 BaseColor、Metallic、Normal、Emissive、Roughness 和 Occlusion。