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
文件中指定了受支持的参数的列表:- 请参阅自定义材料参考
- OBJ asset:
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 截止,将通过遮罩混合渲染材料。 如果在源内容上启用了混合,将启用透明度。