# 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](http://jsonnet.org/learning/tutorial.html), an extension of
[JSON](https://json.org/).

## 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`](https://developers.google.com/sceneform/develop/sfa#source) attribute.

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

    - OBJ assets: [`obj_material.sfm`](https://developers.google.com/sceneform/develop/sfa#obj_material)
    - FBX assets: [`fbx_material.sfm`](https://developers.google.com/sceneform/develop/sfa#fbx_material)
    - glTF assets: [`gltf_material.sfm`](https://developers.google.com/sceneform/develop/sfa#gltf_material)

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

    - See the [custom material](https://developers.google.com/sceneform/develop/custom-material) reference

`materials[].source`
:   Specifies the material definition file, either a default material definition
    (`*.sfm`) file or a [custom material](https://developers.google.com/sceneform/develop/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](https://developers.google.com/sceneform/develop/sfa#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. |

<br />

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:

<br />

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

<br />

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:

<br />

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

<br />

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:

<br />

```
    {
      normalMap: 'bumps',
    },
```

<br />

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