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

Файл определения актива 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 ) см. в списке поддерживаемых параметров:

Для пользовательских материалов ( *.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

Параметр Ценность Описание
baseColor <sampler_name> Вычислите baseColor как значение из сэмплера, умноженное на интерполированный цвет.
null Вычислите baseColor как интерполированный цвет или белый, если интерполированный цвет отсутствует.
baseColorTint <vec4> Применяет оттенок к вычисленному значению baseColor в виде [r, b, g, a] .
metallic <float_value> Контролирует металличность материала.
Используйте 0.0 для неметаллических материалов.
Используйте 1.0 для металлических материалов.
roughness <float_value> Контролирует шероховатость материала.
Используйте низкие значения для блестящих материалов ( 0.0 соответствует идеальному зеркалу).
Используйте высокие значения для диффузных материалов ( 1.0 представляет материал без блеска).
opacity null Полностью непрозрачный.
<float_value> Прозрачность включена.
1.0 полностью непрозрачный.
0.0 полностью прозрачен.

fbx_material.sfm

Параметр Ценность Описание
baseColor <vec4> Коэффициент оттенка в результате baseColorMap в виде [r, g, b, a] .
baseColorMap <sampler_name> Результатом является значение сэмплера baseColorMap .
null Решает на белый.
normalMap <sampler_name> Интерпретирует результат выборки как нормаль касательного пространства, используемую в вычислениях освещения.
null Используйте константу [0, 0, 1] в качестве нормали нашего касательного пространства.
metallic <float_value> Масштабирует metallicMap для управления металличностью материала.
Используйте 0.0 для неметаллических материалов
Используйте 1.0 для металлических материалов.
metallicMap <sampler_name> Используйте значение красного канала из сэмплера в качестве нашего значения metallicMap .
null Используйте константу 1.0 , чтобы масштабировать metallic .
roughness <float_value> Масштабирует roughnessMap для управления шероховатостью материала.
Используйте низкую шероховатость для блестящих материалов.
Используйте высокую шероховатость для диффузных материалов.
roughnessMap <sampler_name> Используйте значение красного канала из сэмплера в качестве нашего значения roughnessMap .
null Используйте константу 1.0 для масштабирования по roughness .
reflectance <float_value> Управляет отражательной способностью материала.
Значение по умолчанию 0.5 охватывает почти все возможные материалы.
opacity null Нет явного контроля прозрачности.
Если в исходных данных была указана карта непрозрачности, материал будет отображаться с прозрачным смешиванием.

gltf_material.sfm

Параметр Ценность Описание
baseColorFactor <vec4> Коэффициент оттенка результата baseColor в виде [r, g, b, a] .
normal <sampler_name> Интерпретирует результат выборки как нормаль касательного пространства, используется в вычислениях освещения.
null Используйте константу [0, 0, 1] в качестве нормали нашего касательного пространства.
metallicFactor <float_value> Scales metallicRoughness для управления металличностью материала.
Используйте 0.0 для неметаллических материалов.
Используйте 1.0 для металлических материалов.
roughnessFactor <float_value> Scales metallicRoughness для контроля шероховатости материала.
Используйте низкую шероховатость для блестящих материалов.
Используйте высокую шероховатость для диффузных материалов.
metallicRoughness <sampler_name> Используйте зеленый канал из сэмплера для шероховатости (масштабируется с помощью roughnessFactor ).
Используйте синий канал из сэмплера для металлика (масштабируется с помощью metallicFactor ).
null Используйте metallicFactor и roughnessFactor .
occlusion <sampler_name> Используйте красный канал сэмплера для окружающего затенения.
null Если присутствует текстура metallicRoughness , используйте красный канал для управления окклюзией окружающей среды.
emissiveFactor <float_value> Масштабы emissive контролируют эмиссию материала.
Используйте 0.0 для материалов, которые не излучают собственный свет.
emissive <sampler_name> Используйте цвет из сэмплера в качестве нашего коэффициента излучения.
null Нет эмиссии.
reflectance <float_value> Управляет отражательной способностью материала.
Значение по умолчанию 0.5 охватывает почти все возможные материалы.


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

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

Блок 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 .