Referência do arquivo de recurso do Sceneform

O arquivo Definição de recurso do Sceneform (*.sfa) é uma descrição legível do recurso binário do Sceneform (*.sfb). Ele aponta para os modelos, definições do Material Design e texturas no recurso de origem e também fornece parâmetros do Material Design com base física do Sceneform.

Esse arquivo é gerado automaticamente na primeira importação pelo plug-in do Sceneform no Android Studio, mas você pode ajustar os atributos para mudar a aparência do seu recurso. Esta referência descreve os atributos que você pode configurar para modificar a aparência do recurso. Os atributos opcionais que não estão presentes no sfa terão o valor padrão. A sintaxe de sfa é jsonnet, uma extensão de JSON.

Sintaxe

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

Atributos

materials[].parameters

O conteúdo desse bloco depende da definição do material especificada pelo atributo source.

Para ver materiais padrão (*.sfm), consulte a lista de parâmetros compatíveis:

• Recursos do OBJ: obj_material.sfm
• Recursos do AppSheet: fbx_material.sfm
• Recursos do glTF: gltf_material.sfm

Para materiais personalizados (*.mat), a lista de parâmetros compatíveis é especificada no arquivo *.mat:

• Consulte a referência de material personalizado.

materials[].source

Especifica o arquivo de definição de material, que pode ser um arquivo de definição de material padrão (*.sfm) ou um arquivo de definição de material personalizado (*.mat).

model.attributes

Define o conjunto de fluxos de vértices exportados, calculado durante a importação do modelo de origem. Os valores possíveis são:

Valor	Descrição
"Color"	O vértice COLOR.
"Orientation"	O vértice TANGENT.
"Position"	O vértice POSITION.
"TexCoord"	TEXCOORD0, a primeira coordenada UV.

model.file

Atributo obrigatório que contém um caminho do sistema de arquivos para um arquivo de recursos de origem. Os formatos atualmente compatíveis são *.fbx, *.obj, *.gltf e *.glb.

model.scale

Atributo opcional, o padrão é 1.0. Controla a escala do modelo exportado em comparação ao conteúdo do recurso de origem. Uma escala de 2.0 tornará o recurso duas vezes maior.

Os valores de posição do cenário da cena são especificados em metros. Para acomodar diferenças em unidades padrão, o termo de escala é calculado automaticamente durante a importação inicial para tornar o maior eixo não inferior a 5 cm e o menor eixo de até 1 m. Isso é feito por uma experiência de importação inicial. Esses limites não são aplicados.

model.recenter

Atributo opcional, o padrão é false. Controla o posicionamento da geometria exportada. Os valores possíveis são:

Valor	Descrição
false	A geometria será exportada como autora, sem transformação.
true	O centro da geometria será colocado na origem.
"root"	A geometria será exportada para que fique centralizada horizontalmente sobre a origem. Além disso, ela será deslocada verticalmente para que os vértices mais baixos fiquem alinhados com a origem. Isso pode ser usado para garantir que um modelo exportado posicionado em uma âncora ou em um plano ficará acima desse ponto de âncora.
{x:float, y:float, z:float}	A geometria será exportada de modo que a origem seja colocada de acordo com o ponto indicado. {x:0, y:0, z:0} corresponde ao mínimo da caixa delimitadora alinhada ao eixo da geometria. {x:1, y:1, z:1} corresponde ao máximo da caixa delimitadora alinhada por eixo da geometria.}

model.smoothing_angle

Atributo opcional especificado em graus. O padrão é 45. Os recursos de origem sem normal por vértice (por exemplo, obj) terão valores normais gerados usando smoothing_angle para limitar o conjunto de normais de rosto usados na computação de um normal de vértice. As bordas do modelo que excederem esse ângulo aparecerão 'hard' ou das facetas que não excederem serão exibidas suavizadas.

model.flip_texture_coordinates

Atributo opcional, o padrão é false. Se for verdadeiro, a coordenada vertical será invertida ((u, v) -> (u, 1 - v)) durante a importação. Isso ajuda a acomodar as diferenças históricas entre o OpenGL/Direct3D.

model.fix_infacing_normals

Atributo opcional, o padrão é false. Se for verdadeiro, a importação tentará encontrar e corrigir a normalidade (normales que apontam para a superfície, ao contrário de 'da' da superfície).

samplers[].params.usage_type

Define como o ambiente de execução interpreta os dados de imagem codificados. Use "Color" para texturas de imagens sRGB. Use "Data" ou "Normal" para tratar o conteúdo da imagem como se estivessem em um espaço linear. O valor padrão é "Color".

samplers[].params.mag_filter

Define o filtro de minificação usado quando o mipmap de amostragem é maior do que o tamanho de pixel da geometria de amostragem. O valor padrão é "Linear". Os valores possíveis são:

Valor	Descrição
"Nearest"	Corresponde a GL_NEAREST. Retorna o valor do elemento de textura que está mais próximo (na distância de Manhattan) do centro do pixel que está sendo texturizado.
"Linear"	Corresponde a GL_LINEAR. Retorna a média ponderada dos quatro elementos de textura que estão mais próximos do centro do pixel que está sendo texturado. Elas podem incluir elementos de textura de borda, dependendo dos valores da textura wrap_s e da textura wrap_t, e do mapeamento exato.

samplers[].params.min_filter

Define o filtro de minificação usado quando o mipmap de amostragem é maior do que o tamanho de pixel da geometria de amostragem. O valor padrão é "NearestMipmapLinear". Os valores possíveis são:

Valor	Descrição
"Nearest"	Corresponde a GL_NEAREST. Retorna o valor do elemento de textura que está mais próximo (na distância de Manhattan) do centro do pixel que está sendo texturado.
"Linear"	Corresponde a GL_LINEAR. Retorna a média ponderada dos quatro elementos de textura mais próximos do centro do pixel que está sendo texturizado. Eles podem incluir elementos de textura de borda, dependendo dos valores da textura wrap_s e da textura wrap_t e do mapeamento exato.
"NearestMipmapNearest"	Corresponde a GL_NEAREST_MIPMAP_NEAREST. Escolha o mipmap que melhor corresponde ao tamanho do pixel que está sendo texturado e usa o critério "Nearest" (o elemento de textura mais próximo do centro do pixel) para produzir um valor de textura.
"LinearMipmapNearest"	Corresponde a GL_NEAREST_MIPMAP_LINEAR. Escolha os dois mipmaps que mais se aproximam do tamanho do pixel que está sendo texturado e usa o critério "Nearest" (o elemento de textura mais próximo do centro do pixel) para produzir um valor de textura de cada mipmap. O valor final da textura é uma média ponderada desses dois valores.
"LinearMipmapLinear"	Corresponde a GL_LINEAR_MIPMAP_LINEAR. Escolha os dois mipmaps que mais se aproximam do tamanho do pixel que está sendo texturizado e usa o critério "Linear" (uma média ponderada dos quatro elementos de textura mais próximos ao centro do pixel) para produzir um valor de textura de cada mipmap. O valor final da textura é uma média ponderada desses dois valores.

samplers[].params.wrap_s

Atributo opcional, o padrão é "Repeat". Controla o comportamento do wrapper horizontal.

Valor	Descrição
"ClampToBorder"	Corresponde a GL_CLAMP_TO_BORDER.
"ClampToEdge"	Corresponde a GL_CLAMP_TO_BORDER.
"MirroredRepeat"	Corresponde a GL_MIRRORED_REPEAT.
"MirrorClampToEdge"	Corresponde a GL_MIRROR_CLAMP_TO_EDGE.
"Repeat"	Corresponde a GL_REPEAT.

samplers[].params.wrap_t

Atributo opcional, o padrão é "Repeat". Controla o comportamento do wrapper vertical.

Valor	Descrição
"ClampToBorder"	Corresponde a GL_CLAMP_TO_BORDER.
"ClampToEdge"	Corresponde a GL_CLAMP_TO_BORDER.
"MirroredRepeat"	Corresponde a GL_MIRRORED_REPEAT.
"MirrorClampToEdge"	Corresponde a GL_MIRROR_CLAMP_TO_EDGE.
"Repeat"	Corresponde a GL_REPEAT.

Parâmetros para materiais padrão

O Sceneform fornece três definições de material padrão: uma para recursos OBJ, uma para recursos do AppSheet e uma para recursos glTF.

Esta seção lista os parâmetros do Material Design compatíveis com cada definição padrão do Material.

obj_material.sfm

Parâmetro	Valor	Descrição
baseColor	<sampler_name>	Calcule baseColor como o valor do sampler multiplicando a cor interpolada.
	null	Calcule baseColor como a cor interpolada ou branco se não houver nenhuma cor interpolada.
baseColorTint	<vec4>	Aplica uma tonalidade ao valor baseColor calculado, especificado como [r, b, g, a].
metallic	<float_value>	Controla a metalicidade do material. Use 0.0 para materiais não metálicos. Use 1.0 para materiais metálicos.
roughness	<float_value>	Controla a aspereza do material. Use valores baixos para materiais brilhos (0.0 representa um espelho perfeito). Use valores altos para materiais difíceis (1.0 representa um material sem brilho).
opacity	null	Totalmente opaco.
	<float_value>	Transparência ativada. 1.0 é totalmente opaca. 0.0 é totalmente transparente.

fbx_material.sfm

Parâmetro	Valor	Descrição
baseColor	<vec4>	Um fator de tonalidade no resultado de baseColorMap, especificado como [r, g, b, a].
baseColorMap	<sampler_name>	O resultado é o valor do sampler baseColorMap.
	null	Resolve como branco.
normalMap	<sampler_name>	Interpreta o resultado da amostra como um espaço tangente normal, usado em computações de iluminação.
	null	Use uma [0, 0, 1] constante como espaço tangente no espaço tangente.
metallic	<float_value>	Escalona metallicMap para controlar a metalidade do material. Use 0.0 para materiais não metálicos. Use 1.0 para materiais metálicos.
metallicMap	<sampler_name>	Use o valor do canal vermelho do amostrador como nosso valor de metallicMap.
	null	Use um 1.0 constante para ser escalonado por metallic.
roughness	<float_value>	Escalona roughnessMap para controlar a áspera do material. Use a baixa ásperidade para materiais brilhantes. Use a aspereza para materiais difusas.
roughnessMap	<sampler_name>	Use o valor do canal vermelho do amostrador como nosso valor de roughnessMap.
	null	Use um 1.0 constante para ser escalonado por roughness.
reflectance	<float_value>	Controla a reflexão de um material. O padrão de 0.5 abrange quase todos os materiais possíveis.
opacity	null	Sem controle de opacidade explícito. Se um mapa de opacidade for especificado nos dados de origem, o material será renderizado com mesclagem transparente.

gltf_material.sfm

Parâmetro	Valor	Descrição
baseColorFactor	<vec4>	Um fator de tonalidade no resultado de baseColor, especificado como [r, g, b, a].
normal	<sampler_name>	Interpreta o resultado da amostra como um normal de espaço tangente, usado em computações de iluminação.
	null	Use um [0, 0, 1] constante como normal no espaço tangente.
metallicFactor	<float_value>	Escalona metallicRoughness para controlar a metalidade do material. Use 0.0 para materiais não metálicos. Use 1.0 para materiais metálicos.
roughnessFactor	<float_value>	Escalona metallicRoughness para controlar a aspereza do material. Use a aspereza baixa para materiais brilhos. Use a alta ásperidade para materiais difíceis.
metallicRoughness	<sampler_name>	Use o canal verde do amostrador para aspereza (escalonado por roughnessFactor). Use o canal azul do amostrador para metálica (escalonada por metallicFactor).
	null	Use metallicFactor e roughnessFactor.
occlusion	<sampler_name>	Use o canal vermelho do amostrador para a oclusão do ambiente.
	null	Se a textura metallicRoughness estiver presente, use o canal vermelho para impulsionar a oclusão de ambiente.
emissiveFactor	<float_value>	Escalona emissive para controlar a emissão do material. Use 0.0 para materiais que não geram a própria luz.
emissive	<sampler_name>	Use a cor do exemplo como nosso valor emissivo.
	null	Sem emissão.
reflectance	<float_value>	Controla a reflexão de um material. O padrão de 0.5 abrange quase todos os materiais possíveis.

Se um corte Alfa foi especificado nos dados de origem, o material será renderizado com mesclagem mascarado. Se a combinação tiver sido ativada no conteúdo de origem, a transparência será ativada.

Como substituir ou adicionar texturas

O bloco samplers define quais texturas estão disponíveis para os materiais. Os registros de amostra do recurso de origem declaram pipeline_name e, com isso, identificam-os exclusivamente pelo caminho de imagem original no recurso de origem. O campo file pode ser alterado para conter um caminho de arquivo relativo app/. Por exemplo, o código:

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

substitui a textura de origem, chamada de andy.png nos recursos de origem, pelo conteúdo do arquivo ./sampledata/models/textures/dandy_andy.png.

Texturas total ou parcialmente declaradas no recurso de origem podem não ser importadas automaticamente para o recurso. Nesse caso, elas podem ser adicionadas ao SFA. É possível adicionar texturas a qualquer modelo que tenha TexCoord na lista de atributos. Em vez de um pipeline_name, que se aplica somente a amostras importadas automaticamente, o usuário especifica um bloco injections.

Considere um exemplo de um OnHub que tenha atributos TexCoord, mas não texturas. É possível adicionar um arquivo de imagem à pasta do projeto e vinculá-lo a um novo bloco de amostrar. Em seguida, nas injeções, declare o uso dele como "Normal", como no código a seguir:

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

Neste ponto, a textura está disponível para seus materiais. Para exibi-lo, verifique se o material solicita o exemplo ao parâmetro normalMap. Caso contrário, o exemplo parecerá não utilizado e será selecionado. Considerando o nome bumps no bloco de amostragem, o bloco do Material Design precisa ter o seguinte código:

    {
      normalMap: 'bumps',
    },

Os usos disponíveis para o bloco de injeção são BaseColor, Metallic,Normal, Emissive, Roughness e Occlusion.