Référence du fichier d'élément Sceneform

Le fichier Sceneform Asset Definition (*.sfa) est une description lisible de l'élément binaire Sceneform (*.sfb). Il indique les modèles, les définitions et les textures de l'élément source, et fournit également des paramètres matériels pour les matériaux physiques de Sceneform.

Ce fichier est généré automatiquement lors de la première importation par le plug-in Sceneform Android Studio, mais vous pouvez modifier les attributs pour modifier l'apparence de votre élément. Ce document de référence décrit les attributs que vous pouvez configurer pour modifier l'apparence de votre élément. Les attributs facultatifs qui ne figurent pas dans sfa auront leur valeur par défaut. La syntaxe de sfa est jsonnet, une extension de JSON.

Syntaxe

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

Attributs

materials[].parameters

Le contenu de ce bloc dépend de la définition matérielle spécifiée par l'attribut source.

Pour les supports par défaut (*.sfm), consultez la liste des paramètres acceptés:

Pour les supports personnalisés (*.mat), la liste des paramètres acceptés est spécifiée dans le fichier *.mat:

materials[].source
Spécifie le fichier de définition de Material, un fichier de définition Material par défaut (*.sfm) ou un fichier de définition de matière personnalisée (*.mat).
model.attributes

Définit l'ensemble des flux de sommets exportés, calculés lors de l'importation du modèle source. Les valeurs possibles sont les suivantes :

Value Description
"Color" Le sommet COLOR.
"Orientation" Le sommet TANGENT.
"Position" Le sommet POSITION.
"TexCoord" TEXCOORD0, la première coordonnée UV.
model.file
Attribut obligatoire, contenant le chemin d'accès à un fichier d'élément source. Les formats actuellement acceptés sont *.fbx, *.obj, *.gltf et *.glb.
model.scale

Attribut facultatif, défini par défaut sur 1.0. Contrôle l'échelle du modèle exporté par rapport au contenu de l'élément source. Une échelle de 2.0 double l'élément.

Les valeurs de position des scènes sont indiquées en mètres. Pour prendre en compte les différences au niveau des unités standards, le terme de l'échelle est calculé automatiquement lors de l'importation initiale. L'axe le plus grand est inférieur à 5 cm et l'axe le plus petit ne dépasse pas 1 m. Cela est nécessaire dans le cadre de l'expérience d'importation initiale. Ces limites ne sont pas appliquées.

model.recenter

Attribut facultatif, défini par défaut sur false. Permet de contrôler le positionnement de la géométrie exportée. Les valeurs possibles sont les suivantes :

Value Description
false La géométrie sera exportée comme étant créée, sans transformation.
true Le centre de la géométrie sera placé à l'origine.
"root" La géométrie sera exportée afin qu'elle soit centrée horizontalement sur l'origine, et déplacée verticalement afin que ses sommets les plus bas soient à la hauteur de l'origine. Cela permet de s'assurer qu'un modèle exporté placé sur une ancre ou un plan sera au-dessus de ce point d'ancrage.
{x:float, y:float, z:float} La géométrie sera exportée de sorte que l'origine soit placée conformément au point indiqué.
{x:0, y:0, z:0} correspond au minimum du cadre de délimitation aligné sur l'axe de la géométrie.
{x:1, y:1, z:1} correspond au maximum du cadre englobant aligné sur l'axe de la géométrie.}
model.smoothing_angle
Attribut facultatif spécifié en degrés. Valeur par défaut : 45. Pour les éléments sources sans normalité par vertex (par exemple, obj), des valeurs normales de vertex sont générées à l'aide de smoothing_angle afin de limiter l'ensemble des valeurs normales de visage utilisées dans le calcul d'un normal de sommet. Les arêtes du modèle qui dépassent cet angle apparaîtront en tant qu'arêtes dures ou tranchées, et les arêtes qui ne dépassent pas apparaîtront lissées.
model.flip_texture_coordinates
Attribut facultatif. Valeur par défaut : false. Si la valeur est"true", les coordonnées verticales sont inversées ((u, v) -> (u, 1 - v)) lors de l'importation. Cela permet de prendre en compte les différences historiques entre OpenGL/Direct3D.
model.fix_infacing_normals
Attribut facultatif. Valeur par défaut : false. Si la valeur est définie sur "true", l'importation tente de trouver et de corriger les valeurs normales (normalement pointant vers la surface, par opposition à la surface).
samplers[].params.usage_type
Définit l'interprétation des données d'images encodées par l'environnement d'exécution. Utilisez "Color" pour les textures d'image RVB. Utilisez "Data" ou "Normal" pour traiter le contenu de l'image comme s'il se trouvait dans un espace linéaire. La valeur par défaut est "Color".
samplers[].params.mag_filter

Définit le filtre de minimisation utilisé lorsque la carte mipmap échantillonnée est supérieure à la taille en pixels de la géométrie d'échantillonnage. La valeur par défaut est "Linear". Les valeurs possibles sont les suivantes :

Value Description
"Nearest" Correspond à GL_NEAREST. Renvoie la valeur de l'élément de texture le plus proche (à la distance de Manhattan) du centre du pixel texturé.
"Linear" Correspond à GL_LINEAR. Renvoie la moyenne pondérée des quatre éléments de texture les plus proches du centre du pixel texturé. Ils peuvent inclure des éléments de texture de bordure, en fonction des valeurs de la texture wrap_s et de la texture wrap_t, ainsi que du mappage exact.
samplers[].params.min_filter

Définit le filtre de minimisation utilisé lorsque la carte mipmap échantillonnée est supérieure à la taille en pixels de la géométrie d'échantillonnage. La valeur par défaut est "NearestMipmapLinear". Les valeurs possibles sont les suivantes :

Value Description
"Nearest" Correspond à GL_NEAREST. Renvoie la valeur de l'élément de texture le plus proche (à la distance de Manhattan) du centre du pixel texturé.
"Linear" Correspond à GL_LINEAR. Renvoie la moyenne pondérée des quatre éléments de texture les plus proches du centre du pixel texturé. Ils peuvent inclure des éléments de texture de bordure, en fonction des valeurs de la texture wrap_s et de la texture wrap_t, ainsi que du mappage exact.
"NearestMipmapNearest" Correspond à GL_NEAREST_MIPMAP_NEAREST. Sélectionne le mipmap qui correspond le mieux à la taille du pixel texturé et utilise le critère "Nearest" (l'élément de texture le plus proche du centre du pixel) pour générer une valeur de texture.
"LinearMipmapNearest" Correspond à GL_NEAREST_MIPMAP_LINEAR. Choisit les deux mipmaps qui correspondent le mieux à la taille du pixel avec texture, et utilise le critère "Nearest" (l'élément de texture le plus proche du centre du pixel) pour générer une valeur de texture pour chaque plan. La valeur de texture finale est une moyenne pondérée de ces deux valeurs.
"LinearMipmapLinear" Correspond à GL_LINEAR_MIPMAP_LINEAR. Choisit les deux mipmaps qui correspondent le plus à la taille du pixel avec texture et utilise le critère "Linear" (une moyenne pondérée des quatre éléments de texture les plus proches du centre du pixel) pour produire une valeur de texture de chaque mipmap. La valeur de texture finale est une moyenne pondérée de ces deux valeurs.
samplers[].params.wrap_s

Attribut facultatif, défini par défaut sur "Repeat". Contrôle le comportement de l'enveloppement horizontal.

Value Description
"ClampToBorder" Correspond à GL_CLAMP_TO_BORDER.
"ClampToEdge" Correspond à GL_CLAMP_TO_BORDER.
"MirroredRepeat" Correspond à GL_MIRRORED_REPEAT.
"MirrorClampToEdge" Correspond à GL_MIRROR_CLAMP_TO_EDGE.
"Repeat" Correspond à GL_REPEAT.
samplers[].params.wrap_t

Attribut facultatif, défini par défaut sur "Repeat". Contrôle le comportement de l'enveloppement vertical.

Value Description
"ClampToBorder" Correspond à GL_CLAMP_TO_BORDER.
"ClampToEdge" Correspond à GL_CLAMP_TO_BORDER.
"MirroredRepeat" Correspond à GL_MIRRORED_REPEAT.
"MirrorClampToEdge" Correspond à GL_MIRROR_CLAMP_TO_EDGE.
"Repeat" Correspond à GL_REPEAT.

Paramètres des matériaux par défaut

Sceneform fournit trois définitions Material par défaut: une pour les éléments OBJ, une pour les éléments TCF et une pour les éléments glTF.

Cette section répertorie les paramètres Material compatibles avec chaque définition Material par défaut.

obj_material.sfm

Paramètre Value Description
baseColor <sampler_name> Calculez la valeur baseColor comme valeur de l'échantillonneur multipliée par la couleur interpolée.
null Calculez baseColor comme couleur interpolée ou blanche s'il n'y a pas de couleur interpolée.
baseColorTint <vec4> Applique une teinte à la valeur baseColor calculée, spécifiée sous la forme [r, b, g, a].
metallic <float_value> Contrôle la métallicité du matériau.
Utilisez 0.0 pour les matériaux non métalliques.
Utilisez 1.0 pour les matériaux métalliques.
roughness <float_value> Permet de contrôler la rugosité du matériau.
Utilisez des valeurs faibles pour les matériaux brillants (0.0 représente un miroir parfait).
Utilisez des valeurs élevées pour les matières diffuses (1.0 représente un matériau sans reflets).
opacity null Complètement opaque.
<float_value> Transparence activée.
1.0 est totalement opaque.
0.0 est complètement transparent.

fbx_material.sfm

Paramètre Value Description
baseColor <vec4> Facteur de teinte sur le résultat de baseColorMap, spécifié en tant que [r, g, b, a].
baseColorMap <sampler_name> Le résultat est la valeur de l'échantillonneur baseColorMap.
null Renvoie en blanc.
normalMap <sampler_name> Interprète l'exemple de résultat comme une normale d'espace tangente, utilisée dans les calculs d'éclairage.
null Utilisez une constante [0, 0, 1] comme normal d'espace tangente.
metallic <float_value> Ajuste metallicMap pour contrôler la métallurité du matériau.
Utilisez 0.0 pour les matériaux non métalliques.
Utilisez 1.0 pour les matériaux métalliques.
metallicMap <sampler_name> Utilisez la valeur du canal rouge de l'échantillon comme valeur metallicMap.
null Utilisez une valeur 1.0 constante à mettre à l'échelle par metallic.
roughness <float_value> Ajuste roughnessMap pour contrôler la rugosité du matériau.
Utilisez une rugosité faible pour les matériaux brillants.
Utilisez la rugosité élevée pour les matériaux diffus.
roughnessMap <sampler_name> Utilisez la valeur du canal rouge de l'échantillon comme valeur roughnessMap.
null Utilisez une valeur 1.0 constante à mettre à l'échelle par roughness.
reflectance <float_value> Permet de contrôler la réflectance d'un matériau.
La valeur par défaut de 0.5 couvre presque tous les matériaux possibles.
opacity null Aucun contrôle explicite d'opacité.
Si une carte d'opacité a été spécifiée dans les données sources, le matériau est rendu avec une combinaison transparente.

gltf_material.sfm

Paramètre Value Description
baseColorFactor <vec4> Facteur de teinte sur le résultat de baseColor, spécifié en tant que [r, g, b, a].
normal <sampler_name> Interpréte l'exemple de résultat comme une normale d'espace tangente et est utilisée dans les calculs d'éclairage.
null Utilisez une constante [0, 0, 1] comme normal d'espace tangente.
metallicFactor <float_value> Scaling metallicRoughness pour contrôler la métallicité du matériau.
Utilisez 0.0 pour les matériaux non métalliques.
Utilisez 1.0 pour les matériaux métalliques.
roughnessFactor <float_value> Agrandit metallicRoughness pour contrôler la rugosité du matériau.
Utilisez une rugosité faible pour les matériaux brillants.
Utilisez la rugosité élevée pour les matériaux diffus.
metallicRoughness <sampler_name> Utilisez le canal vert de l'échantillonneur pour la rugosité (mise à l'échelle par roughnessFactor).
Utilisez le canal bleu de l'échantillonneur pour le métal (mise à l'échelle par metallicFactor).
null Utilisez metallicFactor et roughnessFactor.
occlusion <sampler_name> Utilisez le canal rouge de l'échantillonneur pour l'occlusion ambiante.
null Si la texture metallicRoughness est présente, utilisez le canal rouge pour générer une occlusion ambiante.
emissiveFactor <float_value> Ajuste emissive pour contrôler l'émission du matériau.
Utilisez 0.0 pour les matériaux qui ne génèrent pas leur propre lumière.
emissive <sampler_name> Utilisez la couleur de l'échantillon comme valeur émissive.
null Aucune émission.
reflectance <float_value> Permet de contrôler la réflectance d'un matériau.
La valeur par défaut de 0.5 couvre presque tous les matières possibles.


Si la valeur alpha a été spécifiée dans les données sources, le matériau s'affiche avec une combinaison masquée. Si la combinaison est activée sur le contenu source, la transparence est activée.

Remplacement ou ajout de textures

Le bloc samplers définit les textures disponibles pour vos matériaux. Les enregistrements d'échantillons provenant de l'élément source déclarent pipeline_name et les identifient ainsi de manière unique par le chemin de l'image d'origine dans l'élément source. Le champ file peut être modifié pour contenir un chemin de fichier relatif app/. Par exemple:

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

remplace la texture source (appelée andy.png dans les éléments sources) par le contenu du fichier ./sampledata/models/textures/dandy_andy.png.

Les textures qui sont entièrement ou partiellement déclarées dans l'élément source peuvent ne pas être automatiquement importées dans l'élément. Dans ce cas, elles peuvent être ajoutées au SFA. Il est possible d'ajouter des textures à tout modèle dont la liste d'attributs contient TexCoord. Au lieu d'un pipeline_name, qui ne s'applique qu'aux échantillons importés automatiquement, l'utilisateur spécifie un bloc injections.

Prenons l'exemple d'un Looker comportant des attributs TexCoord, mais aucune texture. Vous pouvez ajouter un fichier image dans le dossier de votre projet et l'associer à un nouveau bloc d'échantillonneur, puis déclarer dans les injections son utilisation "Normal", comme dans le code suivant:

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

À ce stade, la texture est disponible pour vos matériaux. Pour l'afficher, assurez-vous que le Material demande que l'échantillonneur obtienne son paramètre normalMap (sinon, il s'affichera inutilisé et sera récolté). Compte tenu du nom bumps dans notre bloc d'échantillonneur, cela signifie que notre bloc Material doit avoir le code suivant:

    {
      normalMap: 'bumps',
    },

Les utilisations disponibles pour le bloc d'injection sont BaseColor, Metallic, Normal, Emissive, Roughness et Occlusion.