Referencia del archivo de elementos de Sceneform

El archivo de definición de elementos de Sceneform (*.sfa) es una descripción legible del elemento binario de Sceneform (*.sfb). Apunta a los modelos, las definiciones de materiales y las texturas de tu elemento de origen, y también proporciona parámetros de material para los materiales basados en la física.

Este archivo se genera automáticamente en la primera importación con el complemento de Sceneform para Android Studio, pero puedes ajustar los atributos para cambiar el aspecto de tu elemento. En esta referencia, se describen los atributos que puedes configurar para modificar el aspecto del elemento. Los atributos opcionales que no están presentes en sfa tendrán su valor predeterminado. La sintaxis de sfa es jsonnet, una extensión de JSON.

Sintaxis

{
   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

El contenido de este bloque depende de la definición del material especificada por el atributo source.

Para ver los materiales predeterminados (*.sfm), consulta la lista de parámetros admitidos:

• Elementos de OBJ: obj_material.sfm
• Elementos de FBX: fbx_material.sfm
• Elementos de glTF: gltf_material.sfm

Para los materiales personalizados (*.mat), la lista de parámetros compatibles se especifica en el archivo *.mat:

• Consulta la referencia de material personalizado.

materials[].source

Especifica el archivo de definición de material, ya sea un archivo de definición de material predeterminado (*.sfm) o de material personalizado (*.mat).

model.attributes

Define el conjunto de transmisiones de vértices exportados, que se calcula durante la importación del modelo de origen. Los valores posibles son:

Valor	Descripción
"Color"	El vértice COLOR.
"Orientation"	El vértice TANGENT.
"Position"	El vértice POSITION.
"TexCoord"	TEXCOORD0, la primera coordenada UV.

model.file

El atributo obligatorio contiene una ruta del sistema de archivos a un archivo de elementos de origen. Actualmente, se admiten los formatos *.fbx, *.obj, *.gltf y *.glb.

model.scale

El atributo opcional es 1.0 de forma predeterminada. Controla la escala del modelo exportado en comparación con el contenido del elemento de origen. Una escala de 2.0 hará que el elemento se duplique.

Los valores de posición de la escena se especifican en metros. Para adaptarse a las diferencias en unidades estándar, el término de escala se calcula automáticamente durante la importación inicial a fin de que el eje más grande no supere los 5 cm y el eje más pequeño no supere 1 m. Esto se hace a los fines de la experiencia de importación inicial; estos límites no se aplican.

model.recenter

El atributo opcional es false de forma predeterminada. Controla el posicionamiento de la geometría exportada. Los valores posibles son:

Valor	Descripción
false	La geometría se exportará como creada, sin transformación.
true	El centro de la geometría se colocará en el origen.
"root"	La geometría se exportará para que quede centrada horizontalmente sobre el origen y se desplace verticalmente a fin de que sus vértices más bajos estén al mismo nivel que el origen. Esto se puede usar para garantizar que un modelo exportado ubicado en un ancla o un plano permanezca de pie sobre este punto de anclaje.
{x:float, y:float, z:float}	La geometría se exportará de manera que el origen se coloque según el punto indicado. {x:0, y:0, z:0} corresponde al mínimo del cuadro de límite alineado con los ejes de la geometría. {x:1, y:1, z:1} corresponde al máximo del cuadro alineado de ejes de la geometría.}

model.smoothing_angle

El atributo opcional especificado en grados es 45 de forma predeterminada. Los elementos de origen sin normales por vértice (p.ej., obj) tendrán normales por vértices generados mediante smoothing_angle para limitar el conjunto de normales de rostro que se usan en el cálculo de una normalidad de vértice. Las aristas del modelo que superan este ángulo aparecerán como "duro" o tallada, o las que no superen esta cifra.

model.flip_texture_coordinates

El atributo predeterminado es false. Si es verdadero, la coordenada vertical se invierte ((u, v) -> (u, 1 - v)) durante la importación. Esto ayuda a adaptarse a las diferencias históricas entre OpenGL y Direct3D.

model.fix_infacing_normals

El atributo predeterminado es false. Si es verdadero, la importación intentará encontrar y corregir las normales internas (las normales que apuntan a la superficie, en lugar de "fuera de" de la superficie).

samplers[].params.usage_type

Define cómo el entorno de ejecución interpreta los datos de imagen codificados. Usa "Color" para las texturas de imágenes sRGB. Usa "Data" o "Normal" para tratar el contenido de la imagen como si estuviera en un espacio lineal. El valor predeterminado es "Color".

samplers[].params.mag_filter

Define el filtro de reducción que se usa cuando el mapa mip de muestra supera el tamaño de píxeles de la geometría de muestreo. El valor predeterminado es "Linear". Los valores posibles son:

Valor	Descripción
"Nearest"	Corresponde a GL_NEAREST. Muestra el valor del elemento de textura más cercano (en distancia de Manhattan) al centro del píxel con textura.
"Linear"	Corresponde a GL_LINEAR. Muestra el promedio ponderado de los cuatro elementos de textura más cercanos al centro del píxel con textura. Pueden incluir elementos de textura de borde, según los valores de textura wrap_s y wrap_t, y la asignación exacta.

samplers[].params.min_filter

Define el filtro de reducción que se usa cuando el mapa mip de muestra supera el tamaño de píxeles de la geometría de muestreo. El valor predeterminado es "NearestMipmapLinear" Los valores posibles son:

Valor	Descripción
"Nearest"	Corresponde a GL_NEAREST. Muestra el valor del elemento de textura más cercano (en distancia de Manhattan) al centro del píxel con textura.
"Linear"	Corresponde a GL_LINEAR. Muestra el promedio ponderado de los cuatro elementos de textura más cercanos al centro del píxel con textura. Pueden incluir elementos de textura de borde, según los valores de la textura wrap_s y la textura wrap_t, y en la asignación exacta.
"NearestMipmapNearest"	Corresponde a GL_NEAREST_MIPMAP_NEAREST. Selecciona el mipmap que más coincida con el tamaño del píxel con textura y usa el criterio "Nearest" (el elemento de textura más cercano al centro del píxel) para producir un valor de textura.
"LinearMipmapNearest"	Corresponde a GL_NEAREST_MIPMAP_LINEAR. Selecciona los dos mipmaps que más coincidan con el tamaño del píxel con textura y usa el criterio "Nearest" (el elemento de textura más cercano al centro del píxel) para producir un valor de textura a partir de cada mipmap. El valor de textura final es un promedio ponderado de esos dos valores.
"LinearMipmapLinear"	Corresponde a GL_LINEAR_MIPMAP_LINEAR. Elige los dos mipmaps que más coincidan con el tamaño del píxel con textura y usa el criterio "Linear" (un promedio ponderado de los cuatro elementos de textura que están más cerca del centro del píxel) para producir un valor de textura de cada mipmap. El valor de textura final es un promedio ponderado de esos dos valores.

samplers[].params.wrap_s

El atributo opcional es "Repeat" de forma predeterminada. Controla el comportamiento de ajuste horizontal.

Valor	Descripción
"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

El atributo opcional es "Repeat" de forma predeterminada. Controla el comportamiento de ajuste vertical.

Valor	Descripción
"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 materiales predeterminados

Sceneform proporciona tres definiciones de materiales predeterminadas: una para los elementos OBJ, otra para los elementos de FBX y otra para los de glTF.

En esta sección, se enumeran los parámetros de material admitidos por cada definición de material predeterminada.

obj_material.sfm

Parámetro	Valor	Descripción
baseColor	<sampler_name>	Calcula baseColor como el valor de la muestra multiplicado por el color interpolado.
	null	Calcula baseColor como el color interpolado o blanco si no hay ningún color interpolado.
baseColorTint	<vec4>	Aplica un tono al valor baseColor calculado, especificado como [r, b, g, a].
metallic	<float_value>	Controla la metalicidad del material. Usa 0.0 para los materiales no metálicos. Usa 1.0 para los materiales metálicos.
roughness	<float_value>	Controla la aspereza del material. Usa valores bajos para los materiales brillantes (0.0 representa un espejo perfecto). Usa valores altos para los materiales difusos (1.0 representa un material sin brillo).
opacity	null	Completamente opaco.
	<float_value>	La transparencia está habilitada. 1.0 es completamente opaca. 0.0 es completamente transparente.

fbx_material.sfm

Parámetro	Valor	Descripción
baseColor	<vec4>	Un factor de tono en el resultado de baseColorMap, especificado como [r, g, b, a]
baseColorMap	<sampler_name>	El resultado es el valor de la muestra baseColorMap.
	null	Se resuelve en blanco.
normalMap	<sampler_name>	Interpreta el resultado de muestra como una normal de espacio tangencial, que se usa en los cálculos de iluminación.
	null	Usa una constante [0, 0, 1] como nuestra normal de espacio tangencial.
metallic	<float_value>	Escala metallicMap para controlar la metalización del material. Usa 0.0 para materiales no metálicos Usa 1.0 para materiales metálicos.
metallicMap	<sampler_name>	Usa el valor de canal rojo de la muestra como nuestro valor metallicMap.
	null	Usa una constante 1.0 para que se escale por metallic.
roughness	<float_value>	Escala roughnessMap para controlar la aspereza del material. Usa una aspereza baja para los materiales brillantes. Usa una aspereza alta para los materiales difusos.
roughnessMap	<sampler_name>	Usa el valor de canal rojo de la muestra como nuestro valor roughnessMap.
	null	Usa una constante 1.0 para que se escale por roughness.
reflectance	<float_value>	Controla la reflectancia de un material. El valor predeterminado de 0.5 abarca casi todos los materiales posibles.
opacity	null	No hay control explícito de opacidad. Si se especificó un mapa de opacidad en los datos de origen, el material se procesará con una combinación transparente.

gltf_material.sfm

Parámetro	Valor	Descripción
baseColorFactor	<vec4>	Un factor de tono en el resultado de baseColor, especificado como [r, g, b, a]
normal	<sampler_name>	Interpreta el resultado de muestra como una normal de espacio tangente y se usa en cálculos de iluminación.
	null	Usa una constante [0, 0, 1] como nuestra normal de tangente-espacio.
metallicFactor	<float_value>	Escala metallicRoughness para controlar la metalicidad del material. Usa 0.0 para los materiales no metálicos. Usa 1.0 para los materiales metálicos.
roughnessFactor	<float_value>	Escala metallicRoughness para controlar la aspereza del material. Usa una aspereza baja para los materiales brillantes. Usa una aspereza alta para los materiales difusos.
metallicRoughness	<sampler_name>	Usa el canal verde de la muestra para la aspereza (escalado por roughnessFactor). Usa el canal azul de la muestra para metalizado (escalado por metallicFactor).
	null	Usa metallicFactor y roughnessFactor.
occlusion	<sampler_name>	Usa el canal rojo de la muestra para la oclusión del ambiente.
	null	Si la textura metallicRoughness está presente, usa el canal rojo para impulsar la oclusión del ambiente.
emissiveFactor	<float_value>	Escala emissive para controlar la emisión del material. Usa 0.0 para los materiales que no generan su propia luz.
emissive	<sampler_name>	Usa el color de la muestra como nuestro valor emisivo.
	null	Sin emisiones.
reflectance	<float_value>	Controla la reflectancia de un material. El valor predeterminado de 0.5 abarca casi todos los materiales posibles.

Si se especificó el corte alfa en los datos de origen, el material se renderizará con una mezcla enmascarada. Si se habilitó la combinación en el contenido fuente, se habilitará la transparencia.

Reemplaza o agrega texturas

El bloque samplers define las texturas disponibles para tus materiales. Los registros de muestra que se originan en el elemento de origen declaran pipeline_name, lo que los identifica de forma única por la ruta de acceso de la imagen original en el elemento de origen. El campo file se puede modificar para contener una ruta de archivo relativa app/. Por ejemplo, el código:

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

reemplaza la textura de origen, conocida como andy.png en los recursos de origen, por el contenido del archivo ./sampledata/models/textures/dandy_andy.png.

Es posible que las texturas que se declaran de forma completa o parcial en el recurso de origen no se importen de forma automática al elemento, en cuyo caso se pueden agregar a la SFA. Es posible agregar texturas a cualquier modelo que tenga TexCoord en la lista de atributos. En lugar de un pipeline_name, que solo se aplica a las muestras importadas automáticamente, el usuario especifica un bloque injections.

Considera un ejemplo de un FBX que tiene atributos TexCoord, pero no texturas. Puedes agregar un archivo de imagen en la carpeta de tu proyecto y vincularlo en un bloque de muestra nuevo. Luego, en las inyecciones, debes declarar su uso como "Normal", como en el siguiente código:

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

En este punto, la textura está disponible para tus materiales. A fin de mostrarlo, asegúrate de que las muestras de material que muestrea la muestra para su parámetro normalMap (de lo contrario, la muestra aparezca sin usar y se seleccionará). Dado el nombre bumps en nuestro bloque de muestra, nuestro bloque material debe tener el siguiente código:

    {
      normalMap: 'bumps',
    },

Los usos disponibles para el bloque de inyección son BaseColor, Metallic, Normal, Emissive, Roughness y Occlusion.