Sceneform SDK for Android ist als Open-Source-Version und archiviert (github.com/google-ar/sceneform-android-sdk) mit Version 1.16.0 verfügbar.
Diese Website (developers.google.com/sceneform) dient als Dokumentationsarchiv für die vorherige Version, Sceneform SDK for Android 1.15.0.
Verwenden Sie keine Version 1.17.0 der Sceneform-Maven-Artefakte.
Die Artefakte 1.17.1 Maven können verwendet werden. Abgesehen von der Version sind die 1.17.1-Artefakte jedoch mit den 1.15.0-Artefakten identisch.

Diese Seite wurde von der Cloud Translation API übersetzt.

Verweis auf Sceneform-Asset-Datei

Die Sceneform Asset Definition (*.sfa)-Datei ist eine für Menschen lesbare Beschreibung des Sceneform Binary-Assets (*.sfb). Sie verweist auf die Modelle, Materialdefinitionen und Texturen in Ihrem Quell-Asset und enthält auch Materialparameter für die physisch basierten Materialien von Sceneform.

Diese Datei wird beim ersten Import automatisch über das Android Studio-Plug-in generiert In dieser Referenz werden Attribute beschrieben, die Sie konfigurieren können, um das Aussehen Ihres Assets zu ändern. Optionale Attribute, die nicht in sfa vorhanden sind, haben ihren Standardwert. Die Syntax von sfa ist jsonnet, eine Erweiterung von 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>",
      },
      …
   ]
}

Attribute

materials[].parameters

Der Inhalt dieses Blocks hängt von der mit dem Attribut source angegebenen Materialdefinition ab.

Informationen zu Standardmaterialien (*.sfm) finden Sie in der Liste der unterstützten Parameter:

OBJ-Assets: obj_material.sfm
Bazel-Assets: fbx_material.sfm
glTF-Assets: gltf_material.sfm

Bei benutzerdefinierten Materialien (*.mat) ist die Liste der unterstützten Parameter in der Datei *.mat angegeben:

Siehe Referenzmaterial zu benutzerdefiniertem Material

materials[].source: Gibt die Materialdefinitionsdatei an, entweder eine Standardmaterialdefinitionsdatei (*.sfm) oder eine benutzerdefinierte Materialdefinitionsdatei (*.mat).

model.attributes

Definiert die Gruppe der exportierten Eckpunkte, die beim Import des Quellmodells berechnet werden. Folgende Werte sind möglich:

Wert	Beschreibung
`"Color"`	Eckpunkt `COLOR`.
`"Orientation"`	Eckpunkt `TANGENT`.
`"Position"`	Eckpunkt `POSITION`.
`"TexCoord"`	`TEXCOORD0`, die erste UV-Koordinate.

model.file: Erforderliches Attribut, enthält einen Dateisystempfad zu einer Quell-Asset-Datei. Derzeit werden folgende Formate unterstützt: *.fbx, *.obj, *.gltf, *.glb.

model.scale: Optionales Attribut. Der Standardwert ist 1.0. Steuert den Maßstab des exportierten Modells im Vergleich zum Inhalt des Quell-Assets. Eine Skalierung von 2.0 macht das Asset doppelt so groß.; Positionswerte für Szenen werden in Metern angegeben. Damit Differenzen in Standardeinheiten berücksichtigt werden, wird der Skalierungsbegriff beim ersten Import automatisch so berechnet, dass die größte Achse nicht kleiner als 5 cm und die kleinste Achse nicht größer als 1 m ist. Dies geschieht zu Beginn des Importvorgangs. Diese Limits werden nicht erzwungen.

model.recenter

Optionales Attribut. Der Standardwert ist false. Steuert die Positionierung der exportierten Geometrie. Folgende Werte sind möglich:

Wert	Beschreibung
`false`	Die Geometrie wird unverändert und ohne Autor exportiert.
`true`	Der Mittelpunkt der Geometrie wird am Ursprung positioniert.
`"root"`	Die Geometrie wird so exportiert, dass sie horizontal zentriert über dem Ursprung ist und vertikal verschoben wird, sodass die niedrigsten Eckpunkte mit dem Ursprung eben sind. Dies kann verwendet werden, um sicherzustellen, dass ein exportiertes Modell, das auf einem Anker oder einer Ebene positioniert ist, über diesem Ankerpunkt steht.
`{x:float, y:float, z:float}`	Die Geometrie wird so exportiert, dass der Ursprung gemäß dem angegebenen Punkt platziert wird. `{x:0, y:0, z:0}` entspricht dem Minimum des achsenbezogenen Begrenzungsrahmens der Geometrie. `{x:1, y:1, z:1}` entspricht dem Maximalwert des achsenbezogenen Begrenzungsrahmens der Geometrie.}

model.smoothing_angle: Optionales Attribut in Grad, standardmäßig 45. Für Quell-Assets ohne Normalwerte pro Eckpunkt (z.B. obj) werden mit smoothing_angle generierte Normalwerte pro Eckpunkt generiert, um die Anzahl der Gesichtsnormalen zu begrenzen, die bei der Berechnung einer Vertex-Normalität verwendet werden. Kanten im Modell, die diesen Winkel überschreiten, werden angezeigt oder mit Facetten versehen. Kanten, die diese Grenze nicht überschreiten, werden geglättet.

model.flip_texture_coordinates: Optionales Attribut, standardmäßig false. Wenn der Wert „true“ ist, wird die vertikale Koordinate während des Imports invertiert ((u, v) -> (u, 1 - v)). Dies hilft, historische Unterschiede zwischen OpenGL/Direct3D zu berücksichtigen.

model.fix_infacing_normals: Optionales Attribut, standardmäßig false. Wenn der Wert „true“ ist, versucht der Import, die Normalität zu finden und zu korrigieren (Normalwerte, die auf die Oberfläche zeigen, anstatt auf die Oberfläche).

samplers[].params.usage_type: Gibt an, wie die Laufzeit die codierten Bilddaten interpretiert. Verwende "Color" für Texturen mit RGB-Bild. Verwenden Sie "Data" oder "Normal", um den Inhalt des Bildes so zu behandeln, als befänden sie sich im linearen Bereich. Der Standardwert ist "Color".

samplers[].params.mag_filter

Definiert den Komprimierungsfilter, der verwendet wird, wenn die Stichproben-Mipmap größer ist als die Pixelgröße der geometrischen Stichprobe. Der Standardwert ist "Linear". Folgende Werte sind möglich:

Wert	Beschreibung
`"Nearest"`	Entspricht `GL_NEAREST`. Gibt den Wert des Textelements zurück, das am nächsten an der Mitte des zu strukturierten Pixels liegt (in Manhattan).
`"Linear"`	Entspricht `GL_LINEAR`. Gibt den gewichteten Durchschnitt der vier Texturelemente zurück, die dem Mittelpunkt des zu formatierenden Pixels am nächsten sind. Dazu können Sie Rahmenlinienstrukturelemente gehören, abhängig von den Werten der Textur `wrap_s` und der Textur `wrap_t` sowie von der genauen Zuordnung.

samplers[].params.min_filter

Definiert den Komprimierungsfilter, der verwendet wird, wenn die Stichproben-Mipmap größer ist als die Pixelgröße der geometrischen Stichprobe. Der Standardwert ist "NearestMipmapLinear". Folgende Werte sind möglich:

Wert	Beschreibung
`"Nearest"`	Entspricht `GL_NEAREST`. Gibt den Wert des Texturelements zurück, das dem Mittelpunkt des zu bearbeitenden Pixels am nächsten ist (in Manhattan).
`"Linear"`	Entspricht `GL_LINEAR`. Gibt den gewichteten Durchschnitt der vier Texturelemente zurück, die der Mitte des zu formatierenden Pixels am nächsten sind. Zu diesen Elementen können abhängig von den Werten für die Textur `wrap_s` und der Textur `wrap_t` sowie für die genaue Zuordnung Grenztexturelemente gehören.
`"NearestMipmapNearest"`	Entspricht `GL_NEAREST_MIPMAP_NEAREST`. Wählt die Mipmap aus, die der Größe des strukturierten Pixels am ehesten entspricht, und verwendet das Kriterium `"Nearest"` (das Texturelement, das der Mitte des Pixels am nächsten ist), um einen Texturwert zu erzeugen.
`"LinearMipmapNearest"`	Entspricht `GL_NEAREST_MIPMAP_LINEAR`. Wählt die beiden Mipmaps aus, die am ehesten der Größe des texturierten Pixels entsprechen, und verwendet das Kriterium `"Nearest"` (das Textelement, das dem Mittelpunkt des Pixels am nächsten ist), um einen Texturwert aus jeder Mipmap zu erstellen. Der endgültige Texturwert ist ein gewichteter Durchschnitt dieser beiden Werte.
`"LinearMipmapLinear"`	Entspricht `GL_LINEAR_MIPMAP_LINEAR`. Wählt die beiden Mipmaps aus, die der Größe des zu Texturierenden Pixels am ehesten entsprechen, und verwendet das Kriterium `"Linear"` (ein gewichteter Durchschnitt der vier Texturelemente, die der Mitte des Pixels am nächsten sind), um einen Texturwert aus jeder Mipmap zu erzeugen. Der endgültige Texturwert ist ein gewichteter Durchschnitt dieser beiden Werte.

samplers[].params.wrap_s

Optionales Attribut. Der Standardwert ist "Repeat". Steuert das horizontale Wrapping-Verhalten.

Wert	Beschreibung
`"ClampToBorder"`	Entspricht `GL_CLAMP_TO_BORDER`.
`"ClampToEdge"`	Entspricht `GL_CLAMP_TO_BORDER`.
`"MirroredRepeat"`	Entspricht `GL_MIRRORED_REPEAT`.
`"MirrorClampToEdge"`	Entspricht `GL_MIRROR_CLAMP_TO_EDGE`.
`"Repeat"`	Entspricht `GL_REPEAT`.

samplers[].params.wrap_t

Optionales Attribut. Der Standardwert ist "Repeat". Steuert das vertikale Wrapping-Verhalten.

Wert	Beschreibung
`"ClampToBorder"`	Entspricht `GL_CLAMP_TO_BORDER`.
`"ClampToEdge"`	Entspricht `GL_CLAMP_TO_BORDER`.
`"MirroredRepeat"`	Entspricht `GL_MIRRORED_REPEAT`.
`"MirrorClampToEdge"`	Entspricht `GL_MIRROR_CLAMP_TO_EDGE`.
`"Repeat"`	Entspricht `GL_REPEAT`.

Parameter für Standardmaterialien

Sceneform bietet drei Standard-Materialdefinitionen: eine für OBJ-Assets, eine für reCAPTCHA-Assets und eine für glTF-Assets.

In diesem Abschnitt werden die Materialparameter aufgeführt, die von den einzelnen Standard-Materialdefinitionen unterstützt werden.

`obj_material.sfm`

Parameter	Wert	Beschreibung
`baseColor`	`<sampler_name>`	Berechnet `baseColor` als Wert aus dem Sampler multipliziert mit der interpolierten Farbe.
	`null`	Berechnet `baseColor` als interpolierte Farbe oder weiß, wenn keine interpolierte Farbe vorhanden ist.
`baseColorTint`	`<vec4>`	Wendet eine Färbung auf den berechneten Wert `baseColor` an, der als `[r, b, g, a]` angegeben wird.
`metallic`	`<float_value>`	Steuert die Metallizität des Materials. Verwenden Sie `0.0` für nicht metallische Materialien. Verwenden Sie `1.0` für metallische Materialien.
`roughness`	`<float_value>`	Steuert die Rauheit des Materials. Verwenden Sie niedrige Werte für glänzende Materialien (`0.0` steht für einen perfekten Spiegel). Verwenden Sie hohe Werte für diffuse Materialien (`1.0` steht für ein Material ohne Schimmer).
`opacity`	`null`	Vollständig undurchsichtig.
	`<float_value>`	Transparenz aktiviert. `1.0` ist vollständig undurchsichtig. `0.0` ist vollständig transparent.

`fbx_material.sfm`

Parameter	Wert	Beschreibung
`baseColor`	`<vec4>`	Ein Färbungsfaktor für das Ergebnis von `baseColorMap`, angegeben als `[r, g, b, a]`.
`baseColorMap`	`<sampler_name>`	Ergebnis ist der Wert des Samplers `baseColorMap`.
	`null`	Wird in Weiß aufgelöst.
`normalMap`	`<sampler_name>`	Interpretiert das Beispielergebnis als Tangens für Normalbereiche und wird in Beleuchtungsberechnungen verwendet.
	`null`	Verwende als Konstante für den Tangensraum eine Konstante `[0, 0, 1]`.
`metallic`	`<float_value>`	Skaliert `metallicMap`, um die Metallizität des Materials zu steuern. Verwenden Sie `0.0` für nicht metallische Materialien. Verwenden Sie `1.0` für metallische Materialien.
`metallicMap`	`<sampler_name>`	Verwenden Sie den roten Kanalwert aus dem Sampler als `metallicMap`-Wert.
	`null`	Verwenden Sie eine Konstante `1.0`, die um `metallic` skaliert wird.
`roughness`	`<float_value>`	Skaliert `roughnessMap`, um die Rauheit des Materials zu steuern. Verwenden Sie die niedrige Rauigkeit für glänzende Materialien. Verwenden Sie die hohe Rauigkeit für diffuse Materialien.
`roughnessMap`	`<sampler_name>`	Verwenden Sie den roten Kanalwert aus dem Sampler als `roughnessMap`-Wert.
	`null`	Verwenden Sie eine Konstante `1.0`, die um `roughness` skaliert wird.
`reflectance`	`<float_value>`	Steuert die Reflexion eines Materials. Die Standardeinstellung von `0.5` deckt fast alle möglichen Materialien ab.
`opacity`	`null`	Keine explizite Deckkraftkontrolle. Wenn in den Quelldaten eine Deckkraftkarte angegeben wurde, wird das Material mit transparenter Zusammenführung gerendert.

`gltf_material.sfm`

Parameter	Wert	Beschreibung
`baseColorFactor`	`<vec4>`	Ein Färbungsfaktor für das Ergebnis von `baseColor`, angegeben als `[r, g, b, a]`.
`normal`	`<sampler_name>`	Interpretiert das Beispielergebnis als Tangens eines normalen Raums, der in Beleuchtungsberechnungen verwendet wird.
	`null`	Verwenden Sie die Konstante `[0, 0, 1]` als Tangens für normale Bereiche.
`metallicFactor`	`<float_value>`	Skaliert `metallicRoughness`, um die Metallizität des Materials zu steuern. Verwenden Sie `0.0` für nicht metallische Materialien. Verwenden Sie `1.0` für metallische Materialien.
`roughnessFactor`	`<float_value>`	Skaliert `metallicRoughness`, um die Rauheit des Materials zu steuern. Verwenden Sie die niedrige Rauheit der glänzenden Materialien. Verwenden Sie die hohe Rauheit für diffuse Materialien.
`metallicRoughness`	`<sampler_name>`	Verwenden Sie für die Rauheit die Verwendung des grünen Kanals aus dem Sampler (skaliert nach `roughnessFactor`). Verwenden Sie den blauen Kanal aus dem Sampler für metallisch (skaliert nach `metallicFactor`).
	`null`	Verwende `metallicFactor` und `roughnessFactor`.
`occlusion`	`<sampler_name>`	Verwenden Sie den roten Kanal aus dem Sampler für die Umgebungsverdeckung.
	`null`	Wenn die `metallicRoughness`-Textur vorhanden ist, verwenden Sie den roten Kanal, um eine Ambient-Verdeckung zu fördern.
`emissiveFactor`	`<float_value>`	Skaliert `emissive`, um die Emissionen des Materials zu steuern. Verwenden Sie `0.0` für Materialien, die kein eigenes Licht erzeugen.
`emissive`	`<sampler_name>`	Verwenden Sie die Farbe des Samplers als entsprechenden Wert.
	`null`	Keine Emissionen.
`reflectance`	`<float_value>`	Steuert die Reflexion eines Materials. Die Standardeinstellung von `0.5` deckt fast alle möglichen Materialien ab.

Wenn in den Quelldaten ein Alpha-Grenzwert angegeben wurde, wird das Material mit maskierter Zusammenführung gerendert. Wenn das Zusammenführen für den Quellinhalt aktiviert wurde, wird die Transparenz aktiviert.

Texturen ersetzen oder hinzufügen

Der Block samplers definiert, welche Texturen für Ihre Materialien verfügbar sind. Sampler-Einträge aus dem Quell-Asset deklarieren pipeline_name und identifizieren sie dadurch eindeutig anhand des ursprünglichen Bildpfads im Quell-Asset. Das Feld file kann so geändert werden, dass es einen relativen Dateipfad von app/ enthält. Der Code zum Beispiel:

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

ersetzt die Quelltextur, die in den Quell-Assets als andy.png bezeichnet wird, durch den Inhalt der Datei ./sampledata/models/textures/dandy_andy.png.

Texturen, die im Quell-Asset vollständig oder teilweise deklariert sind, werden möglicherweise nicht automatisch in das Asset importiert. In diesem Fall können sie dem SFA hinzugefügt werden. Es ist möglich, jedem Modell, dessen Attributliste TexCoord enthält, Texturen hinzuzufügen. Statt einer pipeline_name, die nur für automatisch importierte Sampler gilt, gibt der Nutzer einen injections-Block an.

Hier ein Beispiel für ein Chromebook mit TexCoord-Attributen, aber ohne Texturen. Sie können in Ihrem Projektordner eine Bilddatei hinzufügen und in einem neuen Sampler-Block verknüpfen. Anschließend geben Sie in den Injektionen die Verwendung als "Normal" an, wie im folgenden Code gezeigt:

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

Die Textur ist jetzt für Ihre Materialien verfügbar. Damit sie angezeigt werden können, muss das Material für den Parameter normalMap angefordert werden. Andernfalls wird der Sampler als nicht verwendet angezeigt und gelöscht. Aufgrund des Namens bumps in unserem Sampler-Block sollte der Materialblock folgenden Code haben:

    {
      normalMap: 'bumps',
    },

Für den Injektionsblock sind BaseColor, Metallic, Normal, Emissive, Roughness und Occlusion verfügbar.