موجودیت ها را ایجاد، کنترل و مدیریت کنید

Jetpack XR SDK به شما امکان می‌دهد از Jetpack SceneCore برای ایجاد، کنترل و مدیریت نمونه‌های Entity مانند مدل‌های سه‌بعدی ، ویدیوی استریوسکوپی و PanelEntity با استفاده از Jetpack SceneCore استفاده کنید.

Jetpack SceneCore از دو الگوی معماری رایج برای پشتیبانی از توسعه سه بعدی استفاده می کند: یک نمودار صحنه و یک سیستم مؤلفه موجود (ECS).

از نمودار صحنه برای ایجاد و کنترل موجودیت ها استفاده کنید

برای ایجاد و کنترل اشیاء در فضای سه بعدی، باید از Session API Jetpack SceneCore برای دسترسی به نمودار صحنه استفاده کنید. نمودار صحنه با دنیای واقعی کاربر همسو می شود و به شما امکان می دهد موجودیت های سه بعدی مانند پانل ها و مدل های سه بعدی را در یک ساختار سلسله مراتبی سازماندهی کنید و وضعیت آن موجودیت ها را حفظ کنید.

هنگامی که به نمودار صحنه دسترسی پیدا کردید، می‌توانید از APIهای موجود در Jetpack Compose برای XR برای ایجاد رابط کاربری فضایی (مثلاً SpatialPanel و Orbiter s) در نمودار صحنه استفاده کنید. برای محتوای سه بعدی مانند مدل های سه بعدی، می توانید مستقیماً به Session دسترسی داشته باشید. برای کسب اطلاعات بیشتر، درباره ActivitySpace در این صفحه مراجعه کنید.

سیستم اجزای نهاد

یک سیستم موجودیت مؤلفه از اصل ترکیب بر ارث پیروی می کند. می‌توانید با پیوست کردن مؤلفه‌های تعیین‌کننده رفتار، رفتار موجودیت‌ها را گسترش دهید، که به شما امکان می‌دهد رفتار مشابهی را برای انواع مختلف موجودیت‌ها اعمال کنید. برای اطلاعات بیشتر، افزودن رفتار مشترک به نهادها را در این صفحه بررسی کنید.

درباره ActivitySpace

هر Session دارای یک ActivitySpace است که به طور خودکار با Session ایجاد می شود. ActivitySpace Entity سطح بالا در نمودار صحنه است.

ActivitySpace یک فضای 3 بعدی با یک سیستم مختصات سمت راست را نشان می دهد (محور x به سمت راست، محور y به سمت بالا و محور z به عقب نسبت به مبدا) و با متر برای واحدهایی که مطابقت دارند. دنیای واقعی مبدا ActivitySpace تا حدودی دلخواه است (چون کاربران می‌توانند موقعیت ActivitySpace را در دنیای واقعی بازنشانی کنند)، بنابراین توصیه می‌شود محتوا را به جای نسبت به مبدا، نسبت به یکدیگر قرار دهید.

با نهادها کار کنید

موجودیت ها در SceneCore مرکزی هستند. بیشتر هر چیزی که کاربر می بیند و با آنها تعامل می کند، موجودیت هایی هستند که پنل ها، مدل های سه بعدی و موارد دیگر را نشان می دهند.

از آنجایی که ActivitySpace گره سطح بالای نمودار صحنه است، به طور پیش فرض، همه موجودیت های جدید مستقیماً در ActivitySpace قرار می گیرند. می‌توانید با فراخوانی setParent یا addChild موجودیت‌ها را در امتداد نمودار صحنه جابجا کنید.

موجودیت ها دارای برخی رفتارهای پیش فرض برای چیزهایی هستند که برای همه موجودیت ها جهانی هستند، مانند تغییر موقعیت، چرخش یا قابلیت مشاهده. زیر کلاس های Entity خاص، مانند GltfEntity ، رفتارهای اضافی دارند که از زیر کلاس پشتیبانی می کنند.

دستکاری نهادها

وقتی تغییری در یک ویژگی Entity که متعلق به کلاس Entity است ایجاد می‌کنید، این تغییر به همه فرزندان آن کاهش می‌یابد. به عنوان مثال، تنظیم Pose یک Entity والد منجر به این می شود که همه فرزندان آن تعدیل یکسانی داشته باشند. ایجاد تغییر در Entity فرزند تأثیری بر والدین آن ندارد.

Pose نشان دهنده مکان و چرخش موجودیت در فضای سه بعدی است. مکان یک Vector3 است که از موقعیت های عددی x، y، z تشکیل شده است. چرخش با یک Quaternion نشان داده می شود. موقعیت یک Entity همیشه نسبت به موجودیت اصلی آن است. به عبارت دیگر، Entity که موقعیت آن (0، 0، 0) است در مبدأ موجودیت اصلی خود قرار می گیرد.

//place the entity forward 2 meters
val modelPosition = Vector3(0f, 0f, -2f)
//rotate the entity by 180 degrees on the up axis (upside-down)
val newOrientation = Quaternion.fromEulerAngles(0f, 0f, 180f)
//update the position and rotation on the entity
entity.setPose(Pose(newPosition, newOrientation))

مهم: هنگام بحث در مورد مکان یک Entity ، به یاد داشته باشید که Entity می تواند در یک نقطه خاص در نمودار صحنه قرار گیرد و همچنین موقعیتی در فضای سه بعدی دارد.

برای تغییر نمایان بودن یک Entity ، از setHidden استفاده کنید.

//hide the entity
entity.setHidden(true)

برای تغییر اندازه یک Entity با حفظ شکل کلی آن، از setScale استفاده کنید.

//double the size of the entity
entity.setScale(2f)

احتیاط: مقیاس یک Entity بر واحدهای سیستم مختصات آن تأثیر می گذارد. برای مثال، تغییر مقیاس به 2، باعث می شود که هر واحد در این موجودیت دیگر نشان دهنده 1 متر در دنیای واقعی نباشد، بلکه نشان دهنده 2 متر در دنیای واقعی است. این امر به فرزندان موجودیت نیز می رسد.

رفتار مشترک را به موجودیت ها اضافه کنید

برای افزودن رفتار مشترک به موجودیت ها می توانید از اجزای زیر استفاده کنید:

• MovableComponent : به کاربر اجازه می دهد تا موجودیت ها را جابجا کند
• ResizableComponent : به کاربر اجازه می دهد تا اندازه موجودیت ها را با الگوهای رابط کاربری سازگار تغییر دهد
• InteractableComponent : به شما امکان می دهد رویدادهای ورودی را برای تعاملات سفارشی ضبط کنید

نمونه سازی اجزاء باید از طریق روش ایجاد مناسب در کلاس Session انجام شود. برای مثال، برای ایجاد یک ResizableComponent ، session.createResizableComponent() را فراخوانی کنید.

پیش نمایش: در حال حاضر، به استثنای InteractableComponent ، که می تواند در GltfEntity استفاده شود، کامپوننت ها فقط می توانند به PanelEntity یا زیر کلاس های آن متصل شوند.

برای افزودن رفتار جزء خاص به یک Entity از متد addComponent() استفاده کنید.

از MovableComponent برای تبدیل شدن یک Entity به کاربر استفاده کنید

MovableComponent به یک Entity اجازه می دهد تا توسط کاربر قابل جابجایی باشد. همچنین می‌توانید مشخص کنید که آیا موجودیت می‌تواند به یک نوع سطح مانند سطوح افقی یا عمودی، یا سطوح معنایی خاص مانند میز، دیوار یا سقف متصل شود. برای تعیین گزینه‌های لنگر، مجموعه‌ای از AnchorPlacement هنگام ایجاد MovableComponent مشخص کنید.

در اینجا نمونه ای از موجودیتی است که می توان آن را به هر سطح عمودی و فقط سطوح افقی کف و سقف منتقل کرد و لنگر انداخت.

val anchorPlacement = AnchorPlacement.createForPlanes(
    planeTypeFilter = setOf(PlaneSemantic.FLOOR, PlaneSemantic.TABLE),
    planeSemanticFilter = setOf(PlaneType.VERTICAL))

val movableComponent = xrSession.createMovableComponent(
    systemMovable = false,
    scaleInZ = false,
    anchorPlacement = setOf(anchorPlacement)
)
entity.addComponent(movableComponent)

توجه: اگر رابط کاربری خود را با نوشتن ایجاد می‌کنید، می‌توانید از اصلاح‌کننده زیرفضای متحرک برای فعال کردن حرکت پانل‌های خود استفاده کنید.

از ResizableComponent برای ایجاد یک Entity قابل تغییر اندازه توسط کاربر استفاده کنید

ResizableComponent به کاربران اجازه می دهد اندازه یک Entity را تغییر دهند. ResizableComponent شامل نشانه‌های تعامل بصری است که کاربر را به تغییر اندازه یک Entity دعوت می‌کند. هنگام ایجاد ResizeableComponent ، می توانید اندازه حداقل یا حداکثر (بر حسب متر) را مشخص کنید. شما همچنین می توانید یک نسبت تصویر ثابت را هنگام تغییر اندازه تعیین کنید تا اندازه عرض و ارتفاع متناسب با یکدیگر تغییر کنند.

در اینجا مثالی از استفاده از ResizableComponent با نسبت تصویر ثابت آورده شده است:

val resizableComponent = xrSession.createResizableComponent()
resizableComponent.minimumSize = Dimensions(177f, 100f, 1f )
resizableComponent.fixedAspectRatio = 16f / 9f //Specify a 16:9 aspect ratio
entity.addComponent(resizableComponent)

توجه: اگر رابط کاربری خود را با نوشتن ایجاد می‌کنید، می‌توانید برای فعال کردن تغییر اندازه پانل‌های خود از اصلاح‌کننده فضای فرعی قابل تغییر اندازه استفاده کنید.

از InteractableComponent برای ثبت رویدادهای ورودی کاربر استفاده کنید

InteractableComponent به شما امکان می دهد رویدادهای ورودی را از کاربر ضبط کنید، مانند زمانی که کاربر درگیر می شود یا ماوس را روی یک Entity قرار می دهد. هنگام ایجاد یک InteractableComponent ، باید یک InputEventListener را برای دریافت رویدادهای ورودی مشخص کنید. هنگامی که کاربر هر اقدام ورودی را انجام می دهد، متد onInputEvent با اطلاعات ورودی خاص ارائه شده در پارامتر InputEvent فراخوانی می شود.

• InputEvent.action نوع ورودی مانند شناور کردن یا ضربه زدن (ACTION_DOWN) روی یک موجودیت را مشخص می‌کند.
• InputEvent.source مشخص می کند که ورودی از کجا آمده است مانند ورودی دست یا کنترلر
• InputEvent.pointerType مشخص می کند که آیا ورودی از دست راست یا چپ آمده است

برای فهرست کامل همه ثابت‌های InputEvent ، به مستندات مرجع مراجعه کنید.

قطعه کد زیر نمونه ای از استفاده از InteractableComponent برای افزایش اندازه یک موجودیت با دست راست و کاهش با دست چپ را نشان می دهد.

private val executor by lazy { Executors.newSingleThreadExecutor() }
val interactableComponent = xrSession.createInteractableComponent(executor) {
    //when the user disengages with the entity with their hands
    if (it.source == InputEvent.SOURCE_HANDS && it.action == InputEvent.ACTION_UP) {
        // increase size with right hand and decrease with left
        if (it.pointerType == InputEvent.POINTER_TYPE_RIGHT){
            entity.setScale(1.5f)
        } else if (it.pointerType == InputEvent.POINTER_TYPE_LEFT){
            entity.setScale(0.5f)
        }
    }
}
entity.addComponent(interactableComponent)