Справочник по файлу актива формы сцены

Файл определения актива Sceneform ( *.sfa ) представляет собой удобочитаемое описание двоичного актива Sceneform ( *.sfb ). Он указывает на модели, определения материалов и текстуры в исходном активе, а также предоставляет параметры материалов для физически основанных материалов Sceneform.

Этот файл автоматически создается при первом импорте подключаемым модулем Sceneform Android Studio, но вы можете настроить атрибуты, чтобы изменить внешний вид вашего актива. В этом справочнике описываются атрибуты, которые можно настроить для изменения внешнего вида вашего актива. Необязательные атрибуты, отсутствующие в sfa , будут иметь значение по умолчанию. Синтаксис sfa — jsonnet , расширение JSON .

Синтаксис

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

Атрибуты

materials[].parameters

Содержимое этого блока зависит от определения материала, заданного source атрибутом.

Материалы по умолчанию ( *.sfm ) см. в списке поддерживаемых параметров:

• Активы OBJ: obj_material.sfm
• Активы FBX: fbx_material.sfm
• Ресурсы glTF: gltf_material.sfm

Для пользовательских материалов ( *.mat ) список поддерживаемых параметров указан в файле *.mat :

• См. ссылку на пользовательский материал

materials[].source

Указывает файл определения материала, либо файл определения материала по умолчанию ( *.sfm ), либо файл пользовательского определения материала ( *.mat ).

model.attributes

Определяет набор экспортируемых потоков вершин, вычисляемых при импорте исходной модели. Возможные значения:

Ценность	Описание
"Color"	COLOR вершины.
"Orientation"	TANGENT вершина .
"Position"	POSITION вершины.
"TexCoord"	TEXCOORD0 , первая координата UV.

model.file

Обязательный атрибут, содержит путь в файловой системе к исходному файлу актива. В настоящее время поддерживаются следующие форматы: *.fbx , *.obj , *.gltf , *.glb .

model.scale

Необязательный атрибут, по умолчанию 1.0 . Управляет масштабом экспортируемой модели по сравнению с содержимым исходного актива. Масштаб 2.0 сделает актив вдвое больше.

Значения положения формы сцены указаны в метрах. Чтобы учесть разницу в стандартных единицах измерения, член масштаба автоматически вычисляется во время первоначального импорта, чтобы наибольшая ось не была меньше 5 см, а наименьшая ось не превышала 1 м. Это ради первоначального опыта импорта; эти ограничения не соблюдаются.

model.recenter

Необязательный атрибут, по умолчанию false . Управляет положением экспортируемой геометрии. Возможные значения:

Ценность	Описание
false	Геометрия будет экспортирована как авторская, без преобразования.
true	Центр геометрии будет размещен в начале координат.
"root"	Геометрия будет экспортирована таким образом, чтобы она располагалась по центру по горизонтали над исходной точкой и смещалась по вертикали так, чтобы ее нижние вершины находились на одном уровне с исходной точкой. Это можно использовать для того, чтобы экспортируемая модель, расположенная на якоре или плоскости, находилась над этой точкой привязки.
{x:float, y:float, z:float}	Геометрия будет экспортирована таким образом, что начало координат будет размещено в соответствии с указанной точкой. {x:0, y:0, z:0} соответствует минимуму выровненной по оси ограничивающей рамки геометрии. {x:1, y:1, z:1} соответствует максимуму выровненного по осям ограничивающего прямоугольника геометрии.}

model.smoothing_angle

Необязательный атрибут, указанный в градусах, по умолчанию 45 . Исходные активы без нормалей для каждой вершины (например, obj ) будут иметь нормали для каждой вершины, сгенерированные с помощью smoothing_angle, чтобы ограничить набор нормалей граней, используемых при вычислении нормали вершины. Края в модели, которые превышают этот угол, будут выглядеть «жесткими» или гранеными, а края, которые не превышают этого угла, будут казаться сглаженными.

model.flip_texture_coordinates

Необязательный атрибут, по умолчанию false . Если true, вертикальная координата инвертируется ( (u, v) -> (u, 1 - v) ) во время импорта. Это помогает учесть исторические различия между OpenGL/Direct3D.

model.fix_infacing_normals

Необязательный атрибут, по умолчанию false . Если значение равно true, импорт попытается найти и скорректировать пересекающиеся нормали (нормали, указывающие «внутрь» поверхности, а не «вне» поверхности.

samplers[].params.usage_type

Определяет, как среда выполнения интерпретирует закодированные данные изображения. Используйте "Color" для текстур изображения sRGB. Используйте "Data" или "Normal" , чтобы обрабатывать содержимое изображения так, как будто оно находится в линейном пространстве. Значение по умолчанию — "Color" .

samplers[].params.mag_filter

Определяет фильтр минимизации, используемый, когда выборка MIP-карты больше, чем размер пикселя сэмплируемой геометрии. Значение по умолчанию — "Linear" . Возможные значения:

Ценность	Описание
"Nearest"	Соответствует GL_NEAREST . Возвращает значение элемента текстуры, ближайшего (по манхэттенскому расстоянию) к центру текстурируемого пикселя.
"Linear"	Соответствует GL_LINEAR . Возвращает средневзвешенное значение четырех элементов текстуры, ближайших к центру текстурируемого пикселя. Они могут включать в себя элементы текстуры границ, в зависимости от значений texture wrap_s и texture wrap_t , а также от точного сопоставления.

samplers[].params.min_filter

Определяет фильтр минимизации, используемый, когда выборка MIP-карты больше, чем размер пикселя сэмплируемой геометрии. Значение по умолчанию — "NearestMipmapLinear" . Возможные значения:

Ценность	Описание
"Nearest"	Соответствует GL_NEAREST . Возвращает значение элемента текстуры, ближайшего (по манхэттенскому расстоянию) к центру текстурируемого пикселя.
"Linear"	Соответствует GL_LINEAR . Возвращает средневзвешенное значение четырех элементов текстуры, ближайших к центру текстурируемого пикселя. Они могут включать в себя элементы текстуры границ, в зависимости от значений texture wrap_s и texture wrap_t , а также от точного сопоставления.
"NearestMipmapNearest"	Соответствует GL_NEAREST_MIPMAP_NEAREST . Выбирает MIP-карту, которая наиболее точно соответствует размеру текстурируемого пикселя, и использует критерий "Nearest" (элемент текстуры, ближайший к центру пикселя) для создания значения текстуры.
"LinearMipmapNearest"	Соответствует GL_NEAREST_MIPMAP_LINEAR . Выбирает два MIP-карты, которые наиболее точно соответствуют размеру текстурируемого пикселя, и использует критерий "Nearest" (элемент текстуры, ближайший к центру пикселя) для создания значения текстуры из каждой MIP-карты. Окончательное значение текстуры представляет собой средневзвешенное значение этих двух значений.
"LinearMipmapLinear"	Соответствует GL_LINEAR_MIPMAP_LINEAR . Выбирает два MIP-карты, которые наиболее точно соответствуют размеру текстурируемого пикселя, и использует критерий "Linear" (средневзвешенное значение четырех элементов текстуры, ближайших к центру пикселя) для создания значения текстуры из каждой MIP-карты. Окончательное значение текстуры представляет собой средневзвешенное значение этих двух значений.

samplers[].params.wrap_s

Необязательный атрибут, по умолчанию "Repeat" . Управляет поведением переноса по горизонтали.

Ценность	Описание
"ClampToBorder"	Соответствует GL_CLAMP_TO_BORDER .
"ClampToEdge"	Соответствует GL_CLAMP_TO_BORDER .
"MirroredRepeat"	Соответствует GL_MIRRORED_REPEAT .
"MirrorClampToEdge"	Соответствует GL_MIRROR_CLAMP_TO_EDGE .
"Repeat"	Соответствует GL_REPEAT .

samplers[].params.wrap_t

Необязательный атрибут, по умолчанию "Repeat" . Управляет поведением вертикального переноса.

Ценность	Описание
"ClampToBorder"	Соответствует GL_CLAMP_TO_BORDER .
"ClampToEdge"	Соответствует GL_CLAMP_TO_BORDER .
"MirroredRepeat"	Соответствует GL_MIRRORED_REPEAT .
"MirrorClampToEdge"	Соответствует GL_MIRROR_CLAMP_TO_EDGE .
"Repeat"	Соответствует GL_REPEAT .

Параметры материалов по умолчанию

Sceneform предоставляет три определения материалов по умолчанию: одно для активов OBJ, одно для активов FBX и одно для активов glTF.

В этом разделе перечислены параметры материала, поддерживаемые каждым определением материала по умолчанию.

obj_material.sfm

fbx_material.sfm

gltf_material.sfm

Если в исходных данных была указана отсечка по альфа-каналу, материал будет визуализирован с маскированным смешиванием. Если для исходного контента было включено смешивание, будет включена прозрачность.

Замена или добавление текстур

Блок samplers определяет, какие текстуры доступны для ваших материалов. Записи сэмплера, происходящие из исходного актива, объявляют pipeline_name , тем самым однозначно идентифицируя их по исходному пути изображения в исходном активе. file поля можно изменить, чтобы он содержал путь к app/ относительному файлу. Например, код:

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

заменяет исходную текстуру, называемую andy.png в исходных ресурсах, содержимым файла ./sampledata/models/textures/dandy_andy.png .

Текстуры, которые полностью или частично объявлены в исходном ассете, не могут автоматически импортироваться в ассет, и в этом случае их можно добавить в SFA. Можно добавлять текстуры к любой модели, имеющей TexCoord в списке атрибутов. Вместо pipeline_name , которое применяется только к автоматически импортируемым пробоотборникам, пользователь указывает блок injections .

Рассмотрим пример FBX с атрибутами TexCoord , но без текстур. Вы можете добавить файл изображения в папку вашего проекта и связать его в новом блоке сэмплера, а затем в инъекциях объявить его использование как "Normal" , как в следующем коде:

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

На данный момент текстура доступна для ваших материалов. Чтобы отобразить его, убедитесь, что материал запрашивает этот сэмплер для своего параметра normalMap (в противном случае сэмплер будет казаться неиспользуемым и будет отбракован). Учитывая название bumps в нашем блоке сэмплера, это означает, что наш блок материала должен иметь следующий код:

    {
      normalMap: 'bumps',
    },

Доступные варианты использования блока впрыска: BaseColor , Metallic , Normal , Emissive , Roughness и Occlusion .