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.