Odwołanie do pliku zasobów podrzędnych

Plik definicji zasobu Sceneform (*.sfa) to zrozumiały dla człowieka opis zasobu binarnego Scene (*.sfb). Określa on modele, definicje materiałów i tekstury w zasobie źródłowym oraz udostępnia parametry materiału fizycznie opartego na Sceneform.

Ten plik jest automatycznie generowany przy pierwszym importowaniu przez wtyczkę Sceneform Android Studio, ale możesz dostosować atrybuty, aby zmienić wygląd zasobu. W tym artykule znajdziesz atrybuty, które możesz skonfigurować, aby zmienić wygląd zasobu. Atrybuty opcjonalne, których nie ma w polu sfa, będą miały wartość domyślną. Składnią elementu sfa jest jsonnet, czyli rozszerzenie JSON.

Składnia

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

Atrybuty

materials[].parameters

Zawartość tego bloku zależy od definicji materiału określonej w atrybucie source.

Listę parametrów domyślnych (*.sfm) znajdziesz w tym artykule:

• Zasoby OBJ: obj_material.sfm
• Zasoby Qwiklabs: fbx_material.sfm
• Zasoby glTF: gltf_material.sfm

W przypadku materiałów niestandardowych (*.mat) listę obsługiwanych parametrów znajdziesz w pliku *.mat:

• odwoływać się do materiałów niestandardowych.

materials[].source

Określa plik z definicją materiału: domyślną (*.sfm) lub niestandardową (*.mat).

model.attributes

Określa zestaw wyeksportowanych strumieni wierzchołków obliczonych podczas importowania modelu źródłowego. Możliwe wartości to:

Wartość	Opis
"Color"	Super wierzchołek COLOR.
"Orientation"	Super wierzchołek TANGENT.
"Position"	Super wierzchołek POSITION.
"TexCoord"	TEXCOORD0, pierwsza współrzędna UV.

model.file

Wymagany atrybut ze ścieżką systemu źródłowego pliku źródłowego. Aktualnie obsługiwane formaty to *.fbx, *.obj, *.gltf, *.glb.

model.scale

Atrybut opcjonalny, domyślny to 1.0. Określa skalę wyeksportowanego modelu w porównaniu z zawartością zasobu źródłowego. Skala zasobu 2.0 sprawi, że zasób będzie dwa razy większy.

Wartości położenia sceny są określone w metrach. Aby uwzględnić różnice w jednostkach standardowych, skala skalowana jest automatycznie podczas wstępnego importu, tak aby największa oś nie była mniejsza niż 5 cm, a najmniejsza o więcej niż 1 m. Chodzi o to, aby przeprowadzić początkowo importowanie. Te limity nie są egzekwowane.

model.recenter

Atrybut opcjonalny, domyślny to false. Określa położenie eksportowanej geometrii. Możliwe wartości to:

Wartość	Opis
false	Geometria zostanie wyeksportowana jako autor bez przekształcania.
true	Środek geometrii zostanie umieszczony w punkcie początkowym.
"root"	Geometria zostanie wyeksportowana, aby wyśrodkować się w poziomie względem punktu początkowego i przesunąć się w pionie, tak aby najniższe wierzchołki były wyrównane z punktem początkowym. Dzięki temu będziesz mieć pewność, że nad tym punktem zakotwiczenia znajdzie się wyeksportowany model umieszczony na zakotwiczeniu lub platformie.
{x:float, y:float, z:float}	Geometria zostanie wyeksportowana w taki sposób, aby punkt początkowy został umieszczony we wskazanym punkcie. {x:0, y:0, z:0}Odpowiada to minimalnej liczbie pól granicznych wyrównanych na osi. {x:1, y:1, z:1}odpowiada maksymalnym obramowaniu limitu geometrycznego osi geometrycznej.}

model.smoothing_angle

Opcjonalny atrybut określony w stopniach, domyślnie 45. Zasoby źródłowe bez wierzchołków (np. obj) będą mieć przypisane normalne wierzchołki wygenerowane za pomocą funkcji smoothing_angle (ograniczenie wierzchołków) w celu ograniczenia zestawu normalnych twarzy używanych do obliczania normalności wierzchołków. Krawędzie w modelu, które przekraczają ten kąt, będą wyświetlane jako „twarde” lub „aspekty” – krawędzie, które nie przekraczają tej wartości, będą wygładzone.

model.flip_texture_coordinates

Opcjonalny atrybut, domyślnie false. Jeśli wartość to prawda, pionowa współrzędna jest odwrócona ((u, v) -> (u, 1 - v)) podczas importu. Pomaga to uwzględnić różnice historyczne między OpenGL/Direct3D.

model.fix_infacing_normals

Opcjonalny atrybut, domyślnie false. Jeśli ustawisz wartość prawda, import spróbuje znaleźć i skorygować normalne wartości (normalne wskazujące na odpowiednią powierzchnię, a nie &#39);

samplers[].params.usage_type

Określa, jak środowisko wykonawcze interpretuje dane zakodowane. W przypadku tekstur obrazu SRGB użyj "Color". Użyj właściwości "Data" lub "Normal", aby potraktować zawartość obrazu tak, jakby znajdowała się w przestrzeni liniowej. Wartością domyślną jest "Color".

samplers[].params.mag_filter

Określa filtr minifikacji używany, gdy rozmiar próbki mapy jest większy niż rozmiar piksela w próbce geometrii. Wartością domyślną jest "Linear". Możliwe wartości to:

Wartość	Opis
"Nearest"	Odpowiada to GL_NEAREST. Zwraca wartość elementu tekstury, która jest najbliżej (w odległości Manhattanu) od środka środka tekstury.
"Linear"	Odpowiada to GL_LINEAR. Zwraca średnią ważoną 4 elementów tekstury najbliżej środka tekstury. Mogą to być elementy tekstur obramowania, zależnie od wartości tekstury wrap_s i tekstury wrap_t oraz dokładnego mapowania.

samplers[].params.min_filter

Określa filtr minifikacji używany, gdy rozmiar próbki mapy jest większy niż rozmiar piksela w próbce geometrii. Wartością domyślną jest "NearestMipmapLinear". Możliwe wartości to:

Wartość	Opis
"Nearest"	Odpowiada to GL_NEAREST. Zwraca wartość elementu tekstury, który jest najbliżej (w odległości Manhattanu) od środka środka tekstury.
"Linear"	Odpowiada to GL_LINEAR. Zwraca średnią ważoną 4 elementów tekstury najbliżej środka piksela, który jest teksturowany. Mogą to być elementy tekstury obramowania w zależności od wartości tekstury wrap_s i tekstury wrap_t oraz dokładnego mapowania.
"NearestMipmapNearest"	Odpowiada to GL_NEAREST_MIPMAP_NEAREST. Wybiera mapę miksingową, która najlepiej pasuje do rozmiaru piksela z teksturą, i używa kryterium "Nearest" (element tekstury najbliżej środka piksela), aby uzyskać wartość tekstury.
"LinearMipmapNearest"	Odpowiada to GL_NEAREST_MIPMAP_LINEAR. Wybiera 2 mapy powiązane z rozmiarem piksela, który jest teksturą, i używa kryterium "Nearest" (element tekstury najbliżej środka piksela), aby wygenerować wartość tekstury z każdej mapy mapy. Końcowa wartość tekstury to średnia ważona z tych dwóch wartości.
"LinearMipmapLinear"	Odpowiada to GL_LINEAR_MIPMAP_LINEAR. Wybiera 2 mapy z największym rozmiarem tekstury i stosuje kryterium "Linear" (średnią czwartą 4 elementów tekstury najbliżej krawędzi piksela). Końcowa wartość tekstury to średnia ważona z tych 2 wartości.

samplers[].params.wrap_s

Atrybut opcjonalny, domyślny to "Repeat". Steruje działaniem opakowania poziomego.

Wartość	Opis
"ClampToBorder"	Odpowiada to GL_CLAMP_TO_BORDER.
"ClampToEdge"	Odpowiada to GL_CLAMP_TO_BORDER.
"MirroredRepeat"	Odpowiada to GL_MIRRORED_REPEAT.
"MirrorClampToEdge"	Odpowiada to GL_MIRROR_CLAMP_TO_EDGE.
"Repeat"	Odpowiada to GL_REPEAT.

samplers[].params.wrap_t

Atrybut opcjonalny, domyślny to "Repeat". Steruje działaniem funkcji dodawania tagów.

Wartość	Opis
"ClampToBorder"	Odpowiada to GL_CLAMP_TO_BORDER.
"ClampToEdge"	Odpowiada to GL_CLAMP_TO_BORDER.
"MirroredRepeat"	Odpowiada to GL_MIRRORED_REPEAT.
"MirrorClampToEdge"	Odpowiada to GL_MIRROR_CLAMP_TO_EDGE.
"Repeat"	Odpowiada to GL_REPEAT.

Parametry domyślnych materiałów

Sceneform zawiera 3 domyślne definicje materiałów: jedną dla zasobów OBJ, jedną dla zasobów Anthos i jedną dla zasobów glTF.

Ta sekcja zawiera parametry materiałowe obsługiwane w przypadku poszczególnych domyślnych definicji materiałów.

obj_material.sfm

Parametr	Wartość	Opis
baseColor	<sampler_name>	Oblicz wartość baseColor jako wartość z próby interpolowanej przez kolor.
	null	Wartość baseColor musi być wartością interpolowaną, a białym – jeśli nie ma koloru do interpolowania.
baseColorTint	<vec4>	Stosuje odcień do obliczonej wartości typu baseColor określonej jako [r, b, g, a].
metallic	<float_value>	Kontroluje metalowość materiału. W przypadku materiałów niemetalicznych używaj właściwości 0.0. W przypadku materiałów metalowych użyj wartości 1.0.
roughness	<float_value>	Kontroluje grubość materiału. Użyj niskich wartości dla materiałów błyszczących (0.0 oznacza idealne odbicie lustrzane). Użyj wysokiej wartości dla materiałów rozproszonych (1.0 oznacza materiał, który nie ma blasku).
opacity	null	W pełni nieprzezroczysty
	<float_value>	Przezroczystość jest włączona. 1.0 jest w pełni nieprzezroczysty. 0.0 jest całkowicie przezroczysty.

fbx_material.sfm

Parametr	Wartość	Opis
baseColor	<vec4>	Współczynnik odcienia wyniku baseColorMap określony jako [r, g, b, a].
baseColorMap	<sampler_name>	Wynik to wartość próbki baseColorMap.
	null	Zmienia się na biały.
normalMap	<sampler_name>	Interpretuje przykładowy wynik jako normalne tangensowe miejsce na potrzeby obliczeń w oświetleniu.
	null	Użyj stałej wartości [0, 0, 1] jako odstępu tangensowego.
metallic	<float_value>	Skali metallicMap do kontrolowania metaliczności materiału. Użyj 0.0 do materiałów niemetalowych Użyj 1.0 do materiałów metalowych.
metallicMap	<sampler_name>	Użyj wartości z kanału czerwonego z próbki jako wartości metallicMap.
	null	Użyj stałej wartości 1.0, aby skalować ją o metallic.
roughness	<float_value>	Skali roughnessMap do kontrolowania intensywności materiału. Użyj niskiej grubości materiałów błyszczących. Użyj dużej grubości materiałów rozproszonych.
roughnessMap	<sampler_name>	Użyj wartości z kanału czerwonego z próbki jako wartości roughnessMap.
	null	Użyj stałej wartości 1.0, aby skalować ją o roughness.
reflectance	<float_value>	Steruje odzwierciedleniem materiału. Ustawienie domyślne to 0.5 wszystkich możliwych materiałów.
opacity	null	Brak wyraźnej kontroli przezroczystości. Jeśli w danych źródłowych określisz mapę przezroczystości, materiał zostanie wyrenderowany z wykorzystaniem przezroczystego mieszania.

gltf_material.sfm

Parametr	Wartość	Opis
baseColorFactor	<vec4>	Współczynnik odcienia wyniku baseColor, określony jako [r, g, b, a].
normal	<sampler_name>	Interpretuje przykładowy wynik jako normalną tangensową przestrzeń w oświetleniu.
	null	Jako separatora tangensów użyj stałej [0, 0, 1].
metallicFactor	<float_value>	Wagi metallicRoughness kontrolujące metalowość materiału. Użyj 0.0 dla materiałów niemetalicznych. 1.0 dla materiałów metalowych.
roughnessFactor	<float_value>	Skali metallicRoughness, aby kontrolować wilgotność materiału. Użyj niskiej grubości grubości materiałów błyszczących. Użyj dużej grubości materiałów rozproszonych.
metallicRoughness	<sampler_name>	Użyj zielonego kanału z próbki danych, aby uzyskać jej orientację (skalowanie przez roughnessFactor). Użyj niebieskiego kanału z próbki pod kątem metalu (skalowane przez metallicFactor).
	null	Należy użyć właściwości metallicFactor i roughnessFactor.
occlusion	<sampler_name>	Wykorzystaj czerwony kanał z próbki pod kątem przesłania otoczenia.
	null	Jeśli tekstura produktu metallicRoughness jest obecna, użyj czerwonego kanału, aby dopasować je do otoczenia.
emissiveFactor	<float_value>	Skala emissive kontroluje emisję materiałów. 0.0, jeśli nie jest to możliwe.
emissive	<sampler_name>	Jako wartości emisyjnej użyj koloru z próbki.
	null	Bez emisji.
reflectance	<float_value>	Steruje odbiciem materiału. Wartość domyślna parametru 0.5 obejmuje niemal wszystkie możliwe materiały.

Jeśli w danych źródłowych określono wersję, materiał będzie renderowany z użyciem maskowania. Jeśli w treści źródłowej włączone jest mieszanie, zostanie włączona przejrzystość.

Zastępowanie lub dodawanie tekstur

Blok samplers określa, które tekstury są dostępne dla Twoich materiałów. Rekordy próbkujące z zasobu źródłowego deklarują deklarację pipeline_name, dzięki czemu są jednoznacznie identyfikowane na podstawie pierwotnej ścieżki obrazu w zasobie źródłowym. Pole file można zmienić tak, aby zawierał względną ścieżkę pliku app/. Na przykład kod:

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

zastępuje teksturę źródłową zwaną andy.png w zasobach źródłowych zawartością pliku ./sampledata/models/textures/dandy_andy.png.

Tekstury, które są w całości lub częściowo zadeklarowane w zasobie źródłowym, mogą nie być automatycznie importowane do tego zasobu. W takim przypadku można je dodać do SFA. Istnieje możliwość dodawania tekstur do dowolnego modelu z atrybutem TexCoord na liście atrybutów. Zamiast pipeline_name, która ma zastosowanie tylko do automatycznie importowanych próbek, użytkownik określa blok injections.

Weźmy pod uwagę przykład elementu Anthos, który ma atrybuty TexCoord, ale nie zawiera tekstur. Możesz dodać plik obrazu w folderze projektu i połączyć go w nowym bloku próbkowania, a potem w zaświadczeniach zadeklarować jego użycie jako "Normal", jak w tym kodzie:

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

W tym momencie tekstura jest dostępna w przypadku materiałów. Aby go wyświetlić, upewnij się, że materiał materiałowy, którego próbka dotyczy parametru normalMap, zostanie użyty i nie zostanie użyty. Biorąc pod uwagę nazwę bumps w naszym bloku próbkowania, powinien on zawierać ten kod:

    {
      normalMap: 'bumps',
    },

Dostępne blokady bloku wstrzykiwania to BaseColor, Metallic, Normal, Emissive, Roughness i Occlusion.