قبل‌از سفارشی‌سازی مدل سه‌بعدی، ابتدا باید آن را به برنامه‌تان اضافه کنید. پس‌از اینکه مدل سه‌بعدی را به برنامه‌تان اضافه کردید، می‌توانید با سفارشی‌سازی ظاهر و حرکت مدل سه‌بعدی، تجربه دیداری و تعاملی را بهبود دهید.
برای مثال، می‌توانید پویانمایی‌های glTF جاسازی‌شده را پخش و کنترل کنید، به گره‌هایی که مدل شما را تشکیل می‌دهند دسترسی داشته باشید و آن‌ها را جابه‌جا کنید، یا حتی بافت‌های سفارشی بار کنید و ویژگی‌های مواد را تعریف کنید تا مش‌های داخلی را ملغی کنید. این قابلیت‌ها به شما امکان می‌دهند ظاهر و رفتار شیء را به‌صورت پویا در زمان اجرا تغییر دهید.
اجسام سه‌بعدی در Android XR
«کیت توسعه نرم‌افزار Jetpack XR» از استاندارد باز glTF 2.0 از Khronos Group برای مدل‌های سه‌بعدی و رندرها پشتیبانی می‌کند و این اشیا را با تکنیک‌های رندرینگ فیزیکی (PBR) که در استاندارد glTF 2.0 مشخص شده است (همراه با افزونه‌های پشتیبانی‌شده) رندر می‌کند. glTF (قالب انتقال کتابخانه گرافیکی) یک قالب فایل استاندارد برای انتقال و بار کردن صحنه‌ها و مدل‌های سه‌بعدی است. مدل glTF از ساختار سلسله‌مراتبی اجزای داخلی تشکیل شده است.
در اینجا عناصر کلیدی برای درک کردن آورده شده است:
- گره‌ها: این گره‌ها ساختار و سلسله مراتب مدل را تعریف می‌کنند. هر گره می‌تواند موقعیت، چرخش، و مقیاس خود را داشته باشد.
- توری‌ها: هندسه سه‌بعدی ساختاری که شکل یک شیء سه‌بعدی را تشکیل می‌دهد.
- مواد: این مواد ظاهر دیداری مش‌ها را تعریف می‌کنند، مثلاً رنگ، زبری، یا نحوه واکنش آن‌ها به نورپردازی.
- بافت‌ها: دارایی تصویری، مانند فایل PNG، که می‌توانید آن را روی سطح مدل سه‌بعدی اعمال کنید تا الگوهای سفارشی، رنگ، جزئیات، یا جلوه‌های بصری دیگر ایجاد کنید.
در Jetpack Compose برای XR، این فایل‌ها را بااستفاده از SpatialGltfModel
پردازش می‌کنید و وضعیت بارگیری آن را بااستفاده از SpatialGltfModelState پیگیری می‌کنید.
برای اطلاعات بیشتر، به افزودن مدل‌های سه‌بعدی به برنامه مراجعه کنید.
دستکاری گره‌ها: ژست‌ها و چرخش
برای دستکاری بخش‌های خاصی از مدل و تغییر دادن ویژگی‌های آن مثل چرخش یا ژست، باید بااستفاده از SpatialGltfModelState، nodes داخلی مدل glTF را پُرسمان کنید.
// Retrieve the list of nodes (individual components/meshes) defined within the glTF model. val entityNodes = modelState.nodes // Find a specific node by name to apply modifications, such as material overrides. val node = entityNodes.find { it.name == "node_name" }
پس‌از پیدا کردن گره صحیح، می‌توانید localPose آن را تنظیم کنید تا موقعیت و چرخش سه‌بعدی آن نسبت‌به والد بی‌واسطه‌اش GltfModelNode تغییر کند یا از modelPose برای تنظیم موقعیت نسبت‌به ریشه GltfModelEntity استفاده کنید. به‌همین ترتیب، می‌توانید از localScale/modelScale برای تغییر مقیاس مدل نسبت‌به والد یا ریشه آن استفاده کنید.
LaunchedEffect(node, degrees) { val rotation = Quaternion.fromEulerAngles(degrees, 0f, degrees) node?.let { it.localPose = Pose(it.localPose.translation, rotation) } }
سفارشی‌سازی کردن ویژگی‌های مواد مدل سه‌بعدی
می‌توانید مشخصه‌های مواد را درطول زمان اجرا تنظیم کنید تا ظاهر شیء را به‌صورت پویا براساس ورودی کاربر یا وضعیت فعلی برنامه تغییر دهید.
در Jetpack XR، از کلاس‌های KhronosPbrMaterial و KhronosUnlitMaterial
برای ایجاد و دستکاری این مواد استفاده می‌شود. همان‌طور که از نام آن پیداست،
KhronosUnlitMaterials روشن نیستند و تحت‌تأثیر نورپردازی صحنه قرار نمی‌گیرند.
KhronosPbrMaterial به شما امکان می‌دهد طیف وسیع‌تری از ویژگی‌ها را سفارشی‌سازی کنید،
ازجمله رنگ درخشش، میزان فلزی یا زبر بودن شیء، و اینکه آیا نور ساطع می‌کند یا نه.
برای اطلاعات بیشتر درباره هر دارایی پشتیبانی‌شده و پارامترهای سفارشی‌سازی‌پذیر در Android XR، به اسناد مرجع ما مراجعه کنید. برای درک بهتر این دارایی‌ها، به واژه‌نامه Khronos مراجعه کنید.
برای سفارشی‌سازی کردن ویژگی‌های مواد مدل سه‌بعدی، ابتدا باید بااستفاده از KhronosPbrMaterial ماده جدیدی بسازید. باید AlphaMode مناسب را برای ظاهر دیداری‌ای که می‌خواهید به آن برسید تنظیم کنید:
سپس، ویژگی‌هایی را که می‌خواهید تغییر دهید تعریف کنید. این مثال از
setBaseColorFactor برای تغییر رنگ پایه مش به بنفش استفاده می‌کند. این روش به Vector4 نیاز دارد که در آن عناصر x, y, z و w به‌ترتیب با مقادیر RGBA (قرمز، سبز، آبی، و آلفا) مطابقت دارند:
// Maintain a reference to the custom material to avoid re-creating it on every recomposition. var pbrMaterial by remember { mutableStateOf<KhronosPbrMaterial?>(null) } // Create and apply the custom material once the session is ready and the target node is available. LaunchedEffect(node) { val material = KhronosPbrMaterial.create( session = xrSession, alphaMode = AlphaMode.OPAQUE ).also { pbrMaterial = it // Apply a base color factor (RGBA) to change the color of the model. it.setBaseColorFactor( Vector4( x = 0.5f, y = 0.0f, z = 0.5f, w = 1.0f ) ) }
بار کردن بافت‌های سفارشی برای مدل سه‌بعدی
Texture یک دارایی تصویری است که می‌توانید آن را روی سطح یک مدل سه‌بعدی اعمال کنید تا رنگ، جزئیات، یا اطلاعات سطحی دیگری ارائه دهید. «میانای برنامه‌سازی کاربردی بافت Jetpack XR» به شما امکان می‌دهد داده‌های تصویر، مثل فایل‌های PNG، را به‌صورت ناهم‌زمان از پوشه /assets/ برنامه بار کنید.
هنگام بار کردن بافت، می‌توانید TextureSampler مشخص کنید که نحوه پرداز بافت را کنترل می‌کند. نمونه‌گیر ویژگی‌های فیلتر کردن را تعریف می‌کند (برای زمانی که بافت کوچک‌تر یا بزرگ‌تر از اندازه اصلی‌اش ظاهر می‌شود) و حالت‌های پیچیدن (برای مدیریت مختصات خارج از محدوده استاندارد [0, 1]). یک Texture باید به یک KhronosPbrMaterial اختصاص داده شود تا جلوه دیداری روی مدل سه‌بعدی داشته باشد.
برای بار کردن بافت سفارشی، ابتدا باید فایل تصویر را در پوشه /assets/ ذخیره کنید. به‌عنوان روال مطلوب، بهتر است textures
زیرپوشه‌ای نیز در آن پوشه ایجاد کنید.
پس‌از ذخیره کردن فایل در دایرکتوری مناسب، بااستفاده از
میانای برنامه‌سازی کاربردی Texture بافت را ایجاد کنید. در اینجا همچنین می‌توانید درصورت نیاز
TextureSampler اختیاری را اعمال کنید.
این مثال بافت انسداد را اعمال می‌کند و قدرت انسداد را تنظیم می‌کند:
LaunchedEffect(node) { val material = KhronosPbrMaterial.create( session = xrSession, alphaMode = AlphaMode.OPAQUE ).also { pbrMaterial = it // Load a texture val texture = Texture.create( session = xrSession, path = Path("textures/texture_name.png") ) // Set the texture and configure occlusion to define how the material surface handles ambient lighting. it.setOcclusionTexture( texture = texture, strength = 1.0f ) } node?.setMaterialOverride( material = material ) }
اعمال مواد و بافت‌ها روی اشیای سه‌بعدی
برای اعمال کردن جنس یا بافت جدید، جنس موجود را برای گره خاصی در گره glTF لغو کنید. این کار را با تماس گرفتن با
setMaterialOverride انجام دهید:
node?.setMaterialOverride( material = material )
برای برداشتن مطالب تازه ایجادشده، با clearMaterialOverride در
گره قبلاً ملغی‌شده تماس بگیرید. با این کار، «مدل سه‌بعدی» شما به حالت پیش‌فرض خود برمی‌گردد:
if (removeMaterial) { node?.clearMaterialOverride() }
پویانمایی مدل‌های سه‌بعدی
مدل‌های سه‌بعدی می‌توانند پویانمایی‌های جاسازی‌شده داشته باشند. درون‌برنامه‌ای، پویانمایی‌ها از
نمونه‌بردارها برای تعریف زمان‌بندی و مقادیر حرکت، و
کانال‌ها برای اتصال آن حرکت‌ها به گره‌های منفرد و
مش‌ها استفاده می‌کنند. پویانمایی‌های استخوانی و پویانمایی‌های مواد ایجادشده با
KHR_animation_pointer افزونه glTF در
«کیت توسعه نرم‌افزار Jetpack XR» پشتیبانی می‌شوند.
پویانمایی‌ها را فقط می‌توان بااستفاده از GltfAnimation در SceneCore با
GltfModelEntity کنترل کرد. برای افزودن این نهاد به چیدمان «نوشتن برای XR»،
باید به‌جای SpatialGltfModel از SceneCoreEntity استفاده کنید.
نام قطعه خاص را از فهرست animations در GltfModelEntity خود مشخص کنید. برای کنترل کردن بازپخش پویانمایی، از
GltfAnimationStartOptions استفاده کنید. به‌صورت اختیاری، می‌توانید سرعت، زمان جستجو، و اینکه پویانمایی باید حلقه شود یا نه را مشخص کنید:
val animation = gltfEntity.getAnimations().find { it.name == "Walk" } animation?.start(GltfAnimationStartOptions(shouldLoop = true))
glTF و نشان‌واره glTF علامت‌های تجاری Khronos Group Inc. هستند.