Sceneform asset file reference

The Sceneform Asset Definition (*.sfa) file is a human-readable description of the Sceneform Binary asset (*.sfb). It points to the models, material definitions, and textures in your source asset and also provides material parameters for Sceneform’s physically-based materials.

This file is automatically generated on first import by the Sceneform Android Studio plugin, but you can tweak the attributes to change the look of your asset. This reference describes attributes that you can configure to modify the look of your asset. Optional attributes not present in the sfa will have their default value. The syntax of the sfa is jsonnet, an extension of JSON.

Syntax

{
   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>",
      },
      …
   ]
}

Attributes

materials[].parameters

The contents of this block depend on the material definition specified by the source attribute.

For default materials (*.sfm), see the list of supported parameters:

• OBJ assets: obj_material.sfm
• FBX assets: fbx_material.sfm
• glTF assets: gltf_material.sfm

For custom materials (*.mat), the list of supported parameters are specified in the *.mat file:

• See the custom material reference

materials[].source

Specifies the material definition file, either a default material definition (*.sfm) file or a custom material definition (*.mat) file.

model.attributes

Defines the set of exported vertex streams, computed during import of the source model. Possible values are:

Value	Description
"Color"	The vertex COLOR.
"Orientation"	The vertex TANGENT.
"Position"	The vertex POSITION.
"TexCoord"	TEXCOORD0, the first UV coordinate.

model.file

Required attribute, contains a file system path to a source asset file. Currently supported formats are *.fbx, *.obj, *.gltf, *.glb.

model.scale

Optional attribute, defaults to 1.0. Controls the scale of the exported model vs. the source asset contents. A scale of 2.0 will make the asset twice as big.

Sceneform position values are specified in meters. To accommodate differences in standard units, the scale term is automatically computed during initial import to make the largest axis no smaller than 5cm, and the smallest axis no larger than 1m. This is for the sake of the initial import experience; these limits are not enforced.

model.recenter

Optional attribute, defaults to false. Controls the positioning of the exported geometry. Possible values are:

Value	Description
false	The geometry will be exported as authored, with no transformation.
true	The center of the geometry will be placed at the origin.
"root"	The geometry will be exported so it is horizontally centered over the origin, and vertically shifted so its lowest vertices are level with the origin. This can be used to ensure that an exported model positioned on an anchor or plane will be standing above this anchor point.
{x:float, y:float, z:float}	The geometry will be exported such that the origin is placed according to the point indicated. {x:0, y:0, z:0} corresponds to the minimum of the axis-aligned bounding box of the geometry. {x:1, y:1, z:1} corresponds to the maximum of the axis-aligned bounding box of the geometry.}

model.smoothing_angle

Optional attribute specified in degrees, defaults to 45. Source assets without per-vertex normals (e.g. obj) will have per-vertex normals generated using smoothing_angle to limit the set of face normals used in the computation of a vertex normal. Edges in the model that exceed this angle will appear 'hard' or faceted, edges that do not exceed will appear smoothed.

model.flip_texture_coordinates

Optional attribute, defaults to false. If true, the vertical coordinate is inverted ((u, v) -> (u, 1 - v)) during import. This helps accommodate historical differences between OpenGL/Direct3D.

model.fix_infacing_normals

Optional attribute, defaults to false. If true, import will attempt to find and correct for infacing normals (normals pointing 'into' the surface, as opposed to 'out of' the surface.

samplers[].params.usage_type

Defines how the runtime interprets the encoded image data. Use "Color" for sRGB image textures. Use "Data" or "Normal" to treat the contents of the image as if they are in linear space. The default value is "Color".

samplers[].params.mag_filter

Defines the minification filter used when the sampled mipmap is larger than the pixel size of the geometry sampling it. The default value is "Linear". Possible values are:

Value	Description
"Nearest"	Corresponds to GL_NEAREST. Returns the value of the texture element that is nearest (in Manhattan distance) to the center of the pixel being textured.
"Linear"	Corresponds to GL_LINEAR. Returns the weighted average of the four texture elements that are closest to the center of the pixel being textured. These can include border texture elements, depending on the values of texture wrap_s and texture wrap_t, and on the exact mapping.

samplers[].params.min_filter

Defines the minification filter used when the sampled mipmap is larger than the pixel size of the geometry sampling it. The default value is "NearestMipmapLinear". Possible values are:

Value	Description
"Nearest"	Corresponds to GL_NEAREST. Returns the value of the texture element that is nearest (in Manhattan distance) to the center of the pixel being textured.
"Linear"	Corresponds to GL_LINEAR. Returns the weighted average of the four texture elements that are closest to the center of the pixel being textured. These can include border texture elements, depending on the values of texture wrap_s and texture wrap_t, and on the exact mapping.
"NearestMipmapNearest"	Corresponds to GL_NEAREST_MIPMAP_NEAREST. Chooses the mipmap that most closely matches the size of the pixel being textured and uses the "Nearest" criterion (the texture element nearest to the center of the pixel) to produce a texture value.
"LinearMipmapNearest"	Corresponds to GL_NEAREST_MIPMAP_LINEAR. Chooses the two mipmaps that most closely match the size of the pixel being textured and uses the "Nearest" criterion (the texture element nearest to the center of the pixel) to produce a texture value from each mipmap. The final texture value is a weighted average of those two values.
"LinearMipmapLinear"	Corresponds to GL_LINEAR_MIPMAP_LINEAR. Chooses the two mipmaps that most closely match the size of the pixel being textured and uses the "Linear" criterion (a weighted average of the four texture elements that are closest to the center of the pixel) to produce a texture value from each mipmap. The final texture value is a weighted average of those two values.

samplers[].params.wrap_s

Optional attribute, defaults to "Repeat". Controls the horizontal wrapping behavior.

Value	Description
"ClampToBorder"	Corresponds to GL_CLAMP_TO_BORDER.
"ClampToEdge"	Corresponds to GL_CLAMP_TO_BORDER.
"MirroredRepeat"	Corresponds to GL_MIRRORED_REPEAT.
"MirrorClampToEdge"	Corresponds to GL_MIRROR_CLAMP_TO_EDGE.
"Repeat"	Corresponds to GL_REPEAT.

samplers[].params.wrap_t

Optional attribute, defaults to "Repeat". Controls the vertical wrapping behavior.

Value	Description
"ClampToBorder"	Corresponds to GL_CLAMP_TO_BORDER.
"ClampToEdge"	Corresponds to GL_CLAMP_TO_BORDER.
"MirroredRepeat"	Corresponds to GL_MIRRORED_REPEAT.
"MirrorClampToEdge"	Corresponds to GL_MIRROR_CLAMP_TO_EDGE.
"Repeat"	Corresponds to GL_REPEAT.

Parameters for default materials

Sceneform provides three default material definitions: one for OBJ assets, one for FBX assets, and one for glTF assets.

This section lists the material parameters supported by each default material definition.

obj_material.sfm

Parameter	Value	Description
baseColor	<sampler_name>	Compute baseColor as the value from the sampler times the interpolated color.
	null	Compute baseColor as the interpolated color, or white if no interpolated color is present.
baseColorTint	<vec4>	Applies a tint to the computed baseColor value, specified as [r, b, g, a].
metallic	<float_value>	Controls the metallicity of the material. Use 0.0 for non-metallic materials. Use 1.0 for metallic materials.
roughness	<float_value>	Controls the roughness of the material. Use low values for shiny materials (0.0 represents a perfect mirror). Use high values for diffuse materials (1.0 represents a material with no shininess).
opacity	null	Fully opaque.
	<float_value>	Transparency enabled. 1.0 is fully opaque. 0.0 is fully transparent.

fbx_material.sfm

Parameter	Value	Description
baseColor	<vec4>	A tint factor on the result of baseColorMap, specified as [r, g, b, a].
baseColorMap	<sampler_name>	Result is the value of the baseColorMap sampler.
	null	Resolves to white.
normalMap	<sampler_name>	Interprets the sample result as a tangent-space normal, used in lighting computations.
	null	Use a constant [0, 0, 1] as our tangent-space normal.
metallic	<float_value>	Scales metallicMap to control the metallicity of the material. Use 0.0 for non-metallic materials Use 1.0 for metallic materials.
metallicMap	<sampler_name>	Use the red channel value from the sampler as our metallicMap value.
	null	Use a constant 1.0, to be scaled by metallic.
roughness	<float_value>	Scales roughnessMap to control the roughness of the material. Use low roughness for shiny materials. Use high roughness for diffuse materials.
roughnessMap	<sampler_name>	Use the red channel value from the sampler as our roughnessMap value.
	null	Use a constant 1.0, to be scaled by roughness.
reflectance	<float_value>	Controls the reflectance of a material. The default of 0.5 covers almost all possible materials.
opacity	null	No explicit opacity control. If an opacity map was specified in the source data, the material will be rendered with transparent blending.

gltf_material.sfm

Parameter	Value	Description
baseColorFactor	<vec4>	A tint factor on the result of baseColor, specified as [r, g, b, a].
normal	<sampler_name>	Interprets the sample result as a tangent-space normal, uses in lighting computations.
	null	Use a constant [0, 0, 1] as our tangent-space normal.
metallicFactor	<float_value>	Scales metallicRoughness to control the metallicity of the material. Use 0.0 for non-metallic materials. Use 1.0 for metallic materials.
roughnessFactor	<float_value>	Scales metallicRoughness to control the roughness of the material. Use low roughness for shiny materials. Use high roughness for diffuse materials.
metallicRoughness	<sampler_name>	Use the green channel from the sampler for roughness (scaled by roughnessFactor). Use the blue channel from the sampler for metallic (scaled by metallicFactor).
	null	Use metallicFactor and roughnessFactor.
occlusion	<sampler_name>	Use the red channel from the sampler for ambient occlusion.
	null	If the metallicRoughness texture is present, use the red channel to drive ambient occlusion.
emissiveFactor	<float_value>	Scales emissive to controls the emission of the material. Use 0.0 for materials which do not generate their own light.
emissive	<sampler_name>	Use the color from the sampler as our emissive value.
	null	No emission.
reflectance	<float_value>	Controls the reflectance of a material. The default of 0.5 covers almost all possible materials.

If alpha cutoff was specified in the source data, the material will be rendered with masked blending. If blending was enabled on the source content, transparency will be enabled.

Replacing or adding textures

The samplers block defines which textures are available to your materials. Sampler records originating from the source asset declare pipeline_name, thereby uniquely identifying them by the original image path in the source asset. The field file is changeable to contain an app/ relative file path. For example, the code:

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

replaces the source texture, referred to as andy.png in the source assets, with the contents of the file ./sampledata/models/textures/dandy_andy.png.

Textures that are fully or partially declared in the source asset may not be automatically imported into the asset, in which case they can be added to the SFA. It's possible to add textures to any model that has TexCoord in the attribute list. Instead of a pipeline_name, which only apply to automatically imported samplers, the user specifies an injections block.

Consider an example of an FBX that has TexCoord attributes but no textures. You can add a image file in your project folder and link it in a new sampler block, then in the injections declare its usage as "Normal" as in the following code:

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

At this point, the texture is available to your materials. To display it, ensure the material requests that sampler for its normalMap parameter (otherwise the sampler will appear unused and will be culled). Given the name bumps in our sampler block, that means our material block should have the following code:

    {
      normalMap: 'bumps',
    },

Available usages for the injection block are BaseColor, Metallic,Normal,Emissive, Roughness, and Occlusion.