مرجع فایل دارایی Sceneform

فایل Sceneform Asset Definition ( *.sfa ) یک توصیف قابل خواندن برای انسان از دارایی Sceneform Binary ( *.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 است. اگر درست باشد، مختصات عمودی در حین وارد کردن معکوس می شود ( (u, v) -> (u, 1 - v) . این به تطبیق تفاوت های تاریخی بین OpenGL/Direct3D کمک می کند.

model.fix_infacing_normals

ویژگی اختیاری، پیش‌فرض روی false است. اگر درست باشد، import سعی می‌کند تا نرمال‌های روبه‌رو شده را بیابد و تصحیح کند (نرمال‌هایی که «به داخل» سطح را نشان می‌دهند، در مقابل «خارج» از سطح.

samplers[].params.usage_type

نحوه تفسیر زمان اجرا داده های تصویر کدگذاری شده را مشخص می کند. از "Color" برای بافت های تصویر sRGB استفاده کنید. از "Data" یا "Normal" استفاده کنید تا با محتوای تصویر طوری رفتار کنید که انگار در فضای خطی قرار دارند. مقدار پیش فرض "Color" است.

samplers[].params.mag_filter

فیلتر کوچک‌سازی را تعریف می‌کند که زمانی که mipmap نمونه‌برداری شده بزرگ‌تر از اندازه پیکسل هندسه نمونه‌برداری از آن است. مقدار پیش فرض "Linear" است. مقادیر ممکن عبارتند از:

ارزش	شرح
"Nearest"	مربوط به GL_NEAREST است. مقدار عنصر بافت را که نزدیک‌ترین (در فاصله منهتن) به مرکز پیکسل در حال بافت است، برمی‌گرداند.
"Linear"	مربوط به GL_LINEAR است. میانگین وزنی چهار عنصر بافت را که به مرکز پیکسل در حال بافت نزدیک‌تر هستند، برمی‌گرداند. بسته به مقادیر بافت wrap_s و بافت wrap_t و نگاشت دقیق، اینها می توانند شامل عناصر بافت حاشیه باشند.

samplers[].params.min_filter

فیلتر کوچک‌سازی را تعریف می‌کند که زمانی که mipmap نمونه‌برداری شده بزرگ‌تر از اندازه پیکسل هندسه نمونه‌برداری از آن است. مقدار پیش فرض "NearestMipmapLinear" است. مقادیر ممکن عبارتند از:

ارزش	شرح
"Nearest"	مربوط به GL_NEAREST است. مقدار عنصر بافت را که نزدیک‌ترین (در فاصله منهتن) به مرکز پیکسل در حال بافت است، برمی‌گرداند.
"Linear"	مربوط به GL_LINEAR است. میانگین وزنی چهار عنصر بافت را که به مرکز پیکسل در حال بافت نزدیک‌تر هستند، برمی‌گرداند. بسته به مقادیر بافت wrap_s و بافت wrap_t و نگاشت دقیق، اینها می توانند شامل عناصر بافت حاشیه باشند.
"NearestMipmapNearest"	مربوط به GL_NEAREST_MIPMAP_NEAREST است. نقشه mipm را انتخاب می کند که بیشتر با اندازه پیکسل در حال بافت مطابقت دارد و از معیار "Nearest" (نزدیک ترین عنصر بافت به مرکز پیکسل) برای تولید یک مقدار بافت استفاده می کند.
"LinearMipmapNearest"	مربوط به GL_NEAREST_MIPMAP_LINEAR است. دو mipmap را انتخاب می‌کند که بیشتر با اندازه پیکسل در حال بافت مطابقت دارند و از معیار "Nearest" (نزدیک‌ترین عنصر بافت به مرکز پیکسل) برای تولید یک مقدار بافت از هر mipmap استفاده می‌کند. ارزش بافت نهایی میانگین وزنی آن دو مقدار است.
"LinearMipmapLinear"	مربوط به GL_LINEAR_MIPMAP_LINEAR است. دو mipmap را انتخاب می‌کند که بیشترین تطابق را با اندازه پیکسل در حال بافت دارند و از معیار "Linear" (میانگین وزنی چهار عنصر بافت که نزدیک‌ترین نقطه به مرکز پیکسل هستند) برای تولید یک مقدار بافت از هر mipmap استفاده می‌کند. ارزش بافت نهایی میانگین وزنی آن دو مقدار است.

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>	مقیاس metallicRoughness برای کنترل فلزی بودن مواد. از 0.0 برای مواد غیر فلزی استفاده کنید. از 1.0 برای مواد فلزی استفاده کنید.
roughnessFactor	<float_value>	مقیاس 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 برای پارامتر نرمال Map خود درخواست می‌کند (در غیر این صورت نمونه‌گر استفاده نشده ظاهر می‌شود و حذف می‌شود). با توجه به bumps نام در بلوک نمونه‌گر ما، به این معنی است که بلوک مواد ما باید کد زیر را داشته باشد:

    {
      normalMap: 'bumps',
    },

موارد استفاده موجود برای بلوک تزریق عبارتند از: Metallic BaseColor Normal ، Emissive ، Roughness و Occlusion .