XR_EXT_spatial_entity

নাম স্ট্রিং

XR_EXT_spatial_entity

এক্সটেনশন টাইপ

ইনস্ট্যান্স এক্সটেনশন

নিবন্ধিত এক্সটেনশন নম্বর

৭৪১

সংশোধন

১

অনুমোদনের অবস্থা

অনুমোদিত

এক্সটেনশন এবং সংস্করণ নির্ভরতা

XR_EXT_future

অবদানকারীরা

নিহাব জৈন, গুগল
জ্যারেড ফাইন্ডার, গুগল
নাটালি ফ্লেউরি, মেটা
ইউইচি তাগুচি, মেটা
রন বেসেমস, মেটা
ইয়িন লি, মাইক্রোসফট
কার্তিক কাডাপ্পান, ম্যাজিক লিপ
জিমি আলামপারাম্বিল, বাইটড্যান্স
ঝিপেং লিউ, বাইটড্যান্স
জুন ইয়ান, বাইটড্যান্স

সংক্ষিপ্ত বিবরণ

এই এক্সটেনশনটি OpenXR-এ সিন আন্ডারস্ট্যান্ডিং এবং স্পেশিয়াল রিজনিং-এর ধারণা ও ভিত্তি উপস্থাপন করে। এটি কার্যকারিতার বেশ কয়েকটি সম্পর্কিত কিন্তু স্বতন্ত্র ক্ষেত্রকে একীভূত করে, যেগুলোকে এই এক্সটেনশন দ্বারা সংজ্ঞায়িত একটি মোটামুটি অভিন্ন পদ্ধতিতে গণনা, কনফিগার এবং ব্যবহার করা হয়। যেহেতু এই এক্সটেনশনে এই কার্যকরী ক্ষেত্রগুলোর কোনোটিরই সুনির্দিষ্ট সংজ্ঞা নেই, তাই এর আনুষ্ঠানিক স্পেসিফিকেশন টেক্সট কিছুটা বিমূর্ত হয়ে থাকে। এই এক্সটেনশন স্পেসিফিকেশন টেক্সটে অন্তর্ভুক্ত উদাহরণগুলো, দৃষ্টান্ত প্রদর্শনের উদ্দেশ্যে, কখনও কখনও কোনো আসন্ন বা কাল্পনিক সম্পর্কিত এক্সটেনশনে সংজ্ঞায়িত কার্যকারিতার উল্লেখ করে, তবে তা সহজাতভাবে সেই অতিরিক্ত কার্যকারিতাকে সীমাবদ্ধ বা নির্দিষ্ট করে না।

এই সম্প্রসারণের প্রধান অংশগুলো হলো নিম্নরূপ:

  • স্থানিক সত্তা : কার্যকারিতাটি সত্তাগুলোকে কেন্দ্র করে গড়ে উঠেছে, যেগুলো নিজেরা খুব সামান্যই কার্যকারিতা প্রদান করে।
  • স্থানিক উপাদানসমূহ : এই সত্তাগুলোর সাথে এমন উপাদান যুক্ত থাকে যা তথ্য এবং আচরণ প্রদান করে।
  • স্থানিক উপাদানের প্রকারভেদ : প্রতিটি স্থানিক উপাদান একটি নির্দিষ্ট উপাদান প্রকারের হয়ে থাকে, এবং যেকোনো প্রদত্ত সত্তার যেকোনো একটি প্রদত্ত উপাদান প্রকারের সর্বাধিক একটি উপাদান থাকতে পারে।
  • স্থানিক প্রেক্ষাপট : প্রারম্ভিকীকরণ এবং কনফিগারেশন পর্বের পর সমস্ত স্থানিক সত্তার মিথস্ক্রিয়া একটি প্রেক্ষাপটের মধ্যে সংঘটিত হয়।
  • স্থানিক সক্ষমতা : স্থানিক সত্তা পরিচালনা প্রধানত সক্ষমতার মাধ্যমে প্রদান করা হয়। সক্ষমতা হলো কার্যকারিতার কোনো একক, উদাহরণস্বরূপ (সীমাবদ্ধতা ছাড়া) অ্যাপ্লিকেশন-সংজ্ঞায়িত অ্যাঙ্কর, প্লেন ডিটেকশন বা ইমেজ ট্র্যাকিং। প্রতিটি সক্ষমতা সাধারণত একটি পৃথক এক্সটেনশনে সংজ্ঞায়িত করা হয় (যথারীতি ইনস্ট্যান্স তৈরির সময় সক্রিয় করা হয়) এবং তৈরির সময় একটি নির্দিষ্ট প্রেক্ষাপটের জন্য সক্রিয় করা হয়।
  • প্রতিটি ক্যাপাবিলিটি এক সেট কম্পোনেন্ট টাইপের সাথে যুক্ত থাকে, যেগুলোর কম্পোনেন্ট সেই ক্যাপাবিলিটি দ্বারা উন্মুক্ত প্রতিটি এনটিটিতে উপস্থিত থাকে। একটি ক্যাপাবিলিটি সংজ্ঞায়িতকারী এক্সটেনশনটি নির্দিষ্ট করে দেয় যে কোন কম্পোনেন্ট টাইপগুলো সেই ক্যাপাবিলিটির জন্য বাধ্যতামূলক ("গ্যারান্টিযুক্ত"), যেখানে সেই একই এক্সটেনশন বা অন্যগুলো কিছু সম্ভাব্য ইমপ্লিমেন্টেশন দ্বারা সরবরাহকৃত ঐচ্ছিক কম্পোনেন্ট টাইপগুলো নির্দিষ্ট করতে পারে । যেকোনো সংখ্যক ক্যাপাবিলিটি একটি নির্দিষ্ট কম্পোনেন্ট টাইপের কম্পোনেন্টসহ এনটিটিগুলোকে সরবরাহ করতে পারে, যা কোন ক্যাপাবিলিটি থেকে উৎপন্ন হয়েছে তা নির্বিশেষে সর্বজনীনভাবে ব্যবহারযোগ্য।
  • স্থানিক সক্ষমতার বৈশিষ্ট্যসমূহ : অধিকন্তু, কিছু সক্ষমতার জন্য কনফিগারেশনের প্রয়োজন হয়, এবং সেই কারণে সেগুলোকে সক্ষমতার বৈশিষ্ট্য দ্বারা প্যারামিটারাইজ করা হয়।

এই এক্সটেনশনটি বর্তমান সিস্টেমে সমর্থিত প্রতিটি সক্ষমতার অন্তর্ভুক্ত উপাদানগুলো , বাধ্যতামূলক এবং ঐচ্ছিক উভয় উপাদানই , গণনা করার একটি পদ্ধতি প্রদান করে।

যেহেতু কিছু বাস্তবায়নে ক্যাপাবিলিটিগুলোর জন্য বিভিন্ন মাত্রার প্যারামিটারাইজেশনের প্রয়োজন হতে পারে , তাই এই এক্সটেনশনটি বর্তমান সিস্টেমে একটি নির্দিষ্ট ক্যাপাবিলিটির সাথে সংশ্লিষ্ট সমর্থিত ক্যাপাবিলিটি ফিচারগুলো গণনা করার জন্য একটি পদ্ধতি প্রদান করে।

এই এক্সটেনশনটি এমন বেশ কিছু সাধারণ উপাদানও সংজ্ঞায়িত করে, যেগুলো বিভিন্ন ধরনের কার্যক্ষমতা জুড়ে ব্যবহৃত হবে বলে আশা করা যায়।

স্থানিক সত্তা

স্থানিক সত্তা হলো এমন সত্তা যা কোনো স্থানে বিদ্যমান থাকে এবং যার সাথে বিভিন্ন উপাদান-ভিত্তিক তথ্য বিন্যস্ত থাকে। এগুলি নিম্নলিখিতগুলির যেকোনোটি হতে পারে :

  • ভৌত (যেমন দেয়াল ও মেঝের মতো সমতল পৃষ্ঠ, চেয়ার ও বইয়ের তাকের মতো বস্তু ইত্যাদি)
  • ভার্চুয়াল (যেমন অন্য কোনো অ্যাপ্লিকেশন বা ব্যবহারকারীর দ্বারা রাখা এবং শেয়ার করা বিষয়বস্তু),
  • অ্যাপ-নির্ধারিত (যেমন, অ্যাপ্লিকেশন দ্বারা কোনো এলাকাকে 'বসার ঘর' বা 'রান্নাঘর' হিসেবে চিহ্নিত করা, অথবা টিভি রাখার স্থান হিসেবে কোনো একটি বিন্দু চিহ্নিত করা ইত্যাদি)।

অ্যাকশন সিস্টেমের মাধ্যমে প্রকাশিত বিষয়গুলো, যেমন কন্ট্রোলার বা চোখের দৃষ্টি, স্থানিক সত্তা হিসেবে মডেল করার উদ্দেশ্যে তৈরি নয়।

OpenXR-এ স্থানিক সত্তাগুলোকে একটি সত্তা-উপাদান সিস্টেম (Entity-Component system) হিসেবে মডেল করা হয়। প্রতিটি স্থানিক সত্তার এক সেট উপাদান থাকে, এবং প্রতিটি উপাদান সেই সত্তার জন্য এক অনন্য ডেটা ও আচরণের সেট প্রদান করে।

স্থানিক সত্তাগুলোকে একটি XrSpatialEntityIdEXT অ্যাটম অথবা একটি XrSpatialEntityEXT হ্যান্ডেল দ্বারা উপস্থাপন করা হয়, যেগুলোর বিস্তারিত বিবরণ ‘স্থানিক সত্তা উপস্থাপনা’ (Spatial Entity Representations) বিভাগে দেওয়া আছে।

স্থানিক উপাদানের প্রকারভেদ

একটি স্থানিক সত্তার এক বা একাধিক উপাদান থাকে, যেগুলো সেই সত্তার জন্য ডেটা বা আচরণ সরবরাহ করে। এই এক্সটেনশন দ্বারা সংজ্ঞায়িত কিছু সাধারণ উপাদানের জন্য ‘সাধারণ উপাদানসমূহ’ দেখুন। 

typedef enum XrSpatialComponentTypeEXT {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT = 1,
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT = 2,
    XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT = 3,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT = 4,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT = 1000741000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT = 1000741001,
    XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT = 1000741002,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT = 1000741003,
    XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT = 1000743000,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT = 1000744000,
    XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT = 1000744001,
    XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT = 1000744002,
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT = 1000763000,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT = 1000782000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT = 1000783000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT = 1000783001,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT = 1000783002,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID = 1000785000,
    XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID = 1000786000,
    XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID = 1000791000,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS = 1000792002,
    XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS = 1000792003,
    XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS = 1000792004,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS = 1000792005,
    XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1 = 1000793000,
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID = 1000794000,
    XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2 = 1000798000,
    XR_SPATIAL_COMPONENT_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

XrSpatialComponentTypeEXT এনুমারেশনটি রানটাইম দ্বারা সমর্থিত হতে পারে এমন বিভিন্ন ধরণের কম্পোনেন্টকে শনাক্ত করে।

তালিকাভুক্ত সব ধরনের উপাদান এই এক্সটেনশনটি নিজে থেকে সরবরাহ করে না: নথিভুক্ত করা অনুযায়ী, কয়েকটির জন্য ইনস্ট্যান্স তৈরির সময় অতিরিক্ত এক্সটেনশন সক্রিয় করার প্রয়োজন হয়।

গণনাকারীগুলোর নিম্নলিখিত মান রয়েছে:

এনামের বিবরণ

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

যে কম্পোনেন্টটি একটি স্থানিক সত্তার দ্বি-মাত্রিক সীমানা প্রদান করে। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচারটি হলো XrSpatialComponentBounded2DListEXT ; এবং সংশ্লিষ্ট ডেটা স্ট্রাকচারটি হলো XrSpatialBounded2DDataEXT।

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

একটি স্থানিক সত্তার ত্রিমাত্রিক সীমানা প্রদানকারী উপাদান। এর সংশ্লিষ্ট তালিকা কাঠামো হলো XrSpatialComponentBounded3DListEXT ; এবং সংশ্লিষ্ট ডেটা কাঠামো হলো XrBoxf।

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

এমন একটি কম্পোনেন্ট যা একটি স্পেশিয়াল এনটিটির প্যারেন্টের XrSpatialEntityIdEXT প্রদান করে। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচারটি হলো XrSpatialComponentParentListEXT ; এবং সংশ্লিষ্ট ডেটা স্ট্রাকচারটি হলো XrSpatialEntityIdEXT

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

একটি স্থানিক সত্তার জন্য ত্রিমাত্রিক জালিকা প্রদানকারী উপাদান। এর সংশ্লিষ্ট তালিকা কাঠামো হলো XrSpatialComponentMesh3DListEXT ; এবং সংশ্লিষ্ট ডেটা কাঠামো হলো XrSpatialMeshDataEXT।

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

একটি স্পেশিয়াল এনটিটির জন্য প্লেন অ্যালাইনমেন্ট এনাম প্রদানকারী কম্পোনেন্ট। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচারটি হলো XrSpatialComponentPlaneAlignmentListEXT ; সংশ্লিষ্ট ডেটা স্ট্রাকচারটি হলো XrSpatialPlaneAlignmentEXT ( XR_EXT_spatial_plane_tracking এক্সটেনশন দ্বারা যুক্ত)।

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

একটি স্থানিক সত্তার জন্য দ্বি-মাত্রিক মেশ প্রদানকারী কম্পোনেন্ট। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচার হলো XrSpatialComponentMesh2DListEXT ; সংশ্লিষ্ট ডেটা স্ট্রাকচার হলো XrSpatialMeshDataEXT (যা XR_EXT_spatial_plane_tracking এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

একটি কম্পোনেন্ট যা কোনো স্পেশিয়াল এনটিটির জন্য একটি দ্বি-মাত্রিক সীমানা বহুভুজ প্রদান করে। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচার হলো XrSpatialComponentPolygon2DListEXT ; এবং সংশ্লিষ্ট ডেটা স্ট্রাকচার হলো XrSpatialPolygon2DDataEXT (যা XR_EXT_spatial_plane_tracking এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

একটি প্লেনের জন্য শব্দার্থিক লেবেল প্রদানকারী কম্পোনেন্ট। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচারটি হলো XrSpatialComponentPlaneSemanticLabelListEXT ; এবং এর সংশ্লিষ্ট ডেটা স্ট্রাকচারটি হলো XrSpatialPlaneSemanticLabelEXT (যা XR_EXT_spatial_plane_tracking এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

মার্কারের ধরন, আইডি এবং অবস্থান বর্ণনা করে এমন একটি উপাদান। এর সংশ্লিষ্ট তালিকা কাঠামো হলো XrSpatialComponentMarkerListEXT ; সংশ্লিষ্ট ডেটা কাঠামো হলো XrSpatialMarkerDataEXT ( XR_EXT_spatial_marker_tracking এক্সটেনশন দ্বারা যুক্ত)।

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

একটি দৃশ্যের জন্য শব্দার্থিক লেবেল প্রদানকারী উপাদান; এর সংশ্লিষ্ট তালিকা কাঠামো হলো XrSpatialComponentObjectSemanticLabelListEXT । এর সংশ্লিষ্ট ডেটা কাঠামো হলো XrSpatialObjectSemanticLabelEXT । ( XR_EXT_spatial_object_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

একটি কম্পোনেন্ট যা কিবোর্ডের জন্য একটি সিম্যান্টিক লেবেল প্রদান করে; এর সংশ্লিষ্ট লিস্ট স্ট্রাকচারটি হলো XrSpatialComponentKeyboardSemanticLabelListEXT । এর সংশ্লিষ্ট ডেটা স্ট্রাকচারটি হলো XrSpatialKeyboardSemanticLabelEXT (যা XR_EXT_spatial_object_tracking এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

একটি কম্পোনেন্ট যা মাউসের জন্য একটি সিম্যান্টিক লেবেল প্রদান করে; এর সংশ্লিষ্ট লিস্ট স্ট্রাকচারটি হলো XrSpatialComponentMouseSemanticLabelListEXT । এর সংশ্লিষ্ট ডেটা স্ট্রাকচারটি হলো XrSpatialMouseSemanticLabelEXT (যা XR_EXT_spatial_object_tracking এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

অ্যাঙ্করের অবস্থান নির্ধারণকারী কম্পোনেন্ট। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচার হলো XrSpatialComponentAnchorListEXT ; সংশ্লিষ্ট ডেটা স্ট্রাকচার হলো XrPosef (যা XR_EXT_spatial_anchor এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

যে কম্পোনেন্টটি একটি স্পেশিয়াল এনটিটির জন্য সংরক্ষিত UUID প্রদান করে। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচারটি হলো XrSpatialComponentPersistenceListEXT ; এবং সংশ্লিষ্ট ডেটা স্ট্রাকচারটি হলো XrSpatialPersistenceDataEXT (যা XR_EXT_spatial_persistence এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

প্ল্যানার ইমেজ টাইপ বর্ণনাকারী একটি কম্পোনেন্ট। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচার হলো XrSpatialComponentImage2DListEXT ; এবং সংশ্লিষ্ট ডেটা স্ট্রাকচার হলো XrSpatialImageSizeEXT । ( XR_EXT_spatial_image_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

একটি স্থানিক সত্তার 3D মেশের জন্য নর্মাল প্রদানকারী কম্পোনেন্ট। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচার হলো XrSpatialComponentMesh3DNormalsListEXT ; সংশ্লিষ্ট ডেটা স্ট্রাকচার হলো XrSpatialBufferEXT ( XR_EXT_spatial_mesh_tracking এক্সটেনশন দ্বারা যুক্ত)।

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

একটি স্থানিক সত্তার 3D মেশের জন্য প্রতি-ভার্টেক্স শব্দার্থিক লেবেল প্রদানকারী উপাদান। এর সংশ্লিষ্ট তালিকা কাঠামো হলো XrSpatialComponentMesh3DVertexSemanticLabelsListEXT ; এর সংশ্লিষ্ট ডেটা কাঠামো হলো XrSpatialBufferEXT ; বাফারের ভেতরের ডেটা XrSpatialMeshSemanticLabelEXT- এ ম্যাপ করা হয় ( XR_EXT_spatial_mesh_tracking এক্সটেনশন দ্বারা যুক্ত)।

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

একটি স্পেশিয়াল এনটিটির 3D মেশের জন্য প্রতিটি ত্রিভুজ-তলের সিমান্টিক লেবেল প্রদানকারী কম্পোনেন্ট। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচারটি হলো XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT ; এর সংশ্লিষ্ট ডেটা স্ট্রাকচারটি হলো XrSpatialBufferEXT ; বাফারের ভেতরের ডেটা XrSpatialMeshSemanticLabelEXT- এর সাথে ম্যাপ করা হয় ( XR_EXT_spatial_mesh_tracking এক্সটেনশন দ্বারা যুক্ত)।

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

একটি অবজেক্টের জন্য শব্দার্থিক লেবেল প্রদানকারী কম্পোনেন্ট; এর সংশ্লিষ্ট লিস্ট স্ট্রাকচারটি হলো XrSpatialComponentObjectSemanticLabelListANDROID ; এবং এর সংশ্লিষ্ট ডেটা স্ট্রাকচারটি হলো XrSpatialObjectSemanticLabelANDROID (যা XR_ANDROID_spatial_object_tracking এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

এমন একটি কম্পোনেন্ট যা কোনো এনটিটির উপর রে-কাস্ট হিটের পোজ প্রদান করে। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচারটি হলো XrSpatialComponentRaycastResultListANDROID ; এবং সংশ্লিষ্ট ডেটা স্ট্রাকচারটি হলো XrSpatialRaycastResultDataANDROID (যা XR_ANDROID_spatial_discovery_raycast এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

যে কম্পোনেন্টটি সংযুক্ত এনটিটিকে অন্তর্ভুক্তকারী এনটিটির এনটিটি আইডি প্রদান করে। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচারটি হলো XrSpatialComponentSubsumedByListANDROID ; এবং সংশ্লিষ্ট ডেটা স্ট্রাকচারটি হলো XrSpatialEntityIdEXT (যা XR_ANDROID_spatial_component_subsumed_by এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

একটি শু-বক্সের মাত্রা এবং রুমের ধরন প্রদানকারী কম্পোনেন্ট; এর সংশ্লিষ্ট লিস্ট স্ট্রাকচার হলো XrSpatialComponentRoomListANDROIDSYS ; সংশ্লিষ্ট ডেটা স্ট্রাকচার হলো XrSpatialRoomDataANDROIDSYS ( XR_ANDROIDSYS_spatial_room_tracking এক্সটেনশন দ্বারা যুক্ত)।

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

একটি সীমানা পৃষ্ঠের উপাদানের ধরণ প্রদানকারী কম্পোনেন্ট; এর সংশ্লিষ্ট লিস্ট স্ট্রাকচার হলো XrSpatialComponentMaterialTypeListANDROIDSYS ; সংশ্লিষ্ট ডেটা স্ট্রাকচার হলো XrSpatialMaterialTypeANDROIDSYS ( XR_ANDROIDSYS_spatial_room_tracking এক্সটেনশন দ্বারা যুক্ত)।

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

ট্র্যাকযোগ্যতার নির্ভরযোগ্যতা প্রদানকারী কম্পোনেন্ট; সংশ্লিষ্ট লিস্ট স্ট্রাকচারটি হলো XrSpatialComponentConfidenceListANDROIDSYS ; সংশ্লিষ্ট ডেটা স্ট্রাকচারটি হলো float ( XR_ANDROIDSYS_spatial_room_tracking এক্সটেনশন দ্বারা যুক্ত)।

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

একটি রুমের শূন্যতা প্রদানকারী কম্পোনেন্ট; এর সংশ্লিষ্ট লিস্ট স্ট্রাকচার হলো XrSpatialComponentRoomEmptinessListANDROIDSYS ; সংশ্লিষ্ট ডেটা স্ট্রাকচার হলো float ( XR_ANDROIDSYS_spatial_room_tracking এক্সটেনশন দ্বারা যুক্ত)।

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

এই কম্পোনেন্টটি সংযুক্ত এনটিটির অকুপেন্সি গ্রিডের তথ্য প্রদান করে। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচারটি হলো XrSpatialComponentOccupancyGridListANDROIDX1 ; এবং সংশ্লিষ্ট ডেটা স্ট্রাকচারটি হলো XrSpatialOccupancyGridDataANDROIDX1 (যা XR_ANDROIDX1_spatial_occupancy_grid এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

একটি কোয়াড অ্যানোটেশন বর্ণনা করে এমন একটি কম্পোনেন্ট। এর সংশ্লিষ্ট লিস্ট স্ট্রাকচার হলো XrSpatialComponentAnnotationQuadListANDROID ; সংশ্লিষ্ট ডেটা স্ট্রাকচার হলো XrSpatialAnnotationQuadDataANDROID ( XR_ANDROID_spatial_annotation_tracking এক্সটেনশন দ্বারা যুক্ত)।

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

স্ট্রিটস্কেপ জ্যামিতির মেটাডেটা প্রদানকারী কম্পোনেন্ট; সংশ্লিষ্ট লিস্ট স্ট্রাকচারটি হলো XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2 ; সংশ্লিষ্ট ডেটা স্ট্রাকচারটি হলো XrSpatialStreetscapeGeometryMetadataANDROIDX2 ( XR_ANDROIDX2_geospatial_streetscape এক্সটেনশন দ্বারা যুক্ত)।

স্থানিক ক্ষমতা এবং সেটআপ

স্পেশাল ক্যাপাবিলিটি একটি রানটাইমের সেইসব এনটিটি খুঁজে বের করার ক্ষমতাকে সংজ্ঞায়িত করে, যেগুলোর উপর একটি নিশ্চিত কম্পোনেন্ট সেট থাকে। অ্যাপ্লিকেশনগুলো XrSpatialContextEXT তৈরি করার সময় একটি স্পেশাল ক্যাপাবিলিটির কম্পোনেন্টগুলো সক্রিয় করে, এবং এর ফলে রানটাইমকে অবশ্যই খুঁজে পাওয়া এনটিটিগুলোর উপর শুধুমাত্র সক্রিয় করা কম্পোনেন্টগুলোই সরবরাহ করতে হয়। উদাহরণস্বরূপ, যদি একটি রানটাইম রিপোর্ট করে যে কোনো একটি নির্দিষ্ট ক্যাপাবিলিটির কম্পোনেন্টগুলোর মধ্যে একটি হলো "সিমান্টিক লেবেল", এর মানে হলো অ্যাপ্লিকেশনটি সেই ক্যাপাবিলিটির কনফিগারেশনের মাধ্যমে সিমান্টিক লেবেল সক্রিয় করতে পারে এবং রানটাইমকে শুধুমাত্র সিমান্টিক লেবেল কম্পোনেন্টটিই সরবরাহ করতে হবে যদি তা কনফিগার করা থাকে। 

typedef enum XrSpatialCapabilityEXT {
    XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT = 1000741000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT = 1000743002,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT = 1000743003,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID = 1000785000,
    XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID = 1000786000,
    XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS = 1000792000,
    XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS = 1000792001,
    XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID = 1000794000,
    XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2 = 1000798000,
    XR_SPATIAL_CAPABILITY_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityEXT;

XrSpatialCapabilityEXT এনুমারেশনটি রানটাইম দ্বারা সমর্থিত হতে পারে এমন বিভিন্ন ধরণের সক্ষমতা শনাক্ত করে।

গণনাকারীগুলোর নিম্নলিখিত মান রয়েছে:

এনামের বিবরণ

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

প্লেন ট্র্যাকিং ( XR_EXT_spatial_plane_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

কিউআর কোড শনাক্ত ও ট্র্যাক করার সক্ষমতা। ( XR_EXT_spatial_marker_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

মাইক্রো কিউআর কোড শনাক্ত ও ট্র্যাক করার সক্ষমতা। ( XR_EXT_spatial_marker_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

আরুকো মার্কার সনাক্ত ও ট্র্যাক করার সক্ষমতা। ( XR_EXT_spatial_marker_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

এপ্রিলট্যাগ শনাক্ত ও ট্র্যাক করার সক্ষমতা। ( XR_EXT_spatial_marker_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

অবজেক্ট ট্র্যাকিং ( XR_EXT_spatial_object_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

স্পেশিয়াল অ্যাঙ্কর তৈরি করার সক্ষমতা ( XR_EXT_spatial_anchor এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

সমতল রেফারেন্স চিত্র সনাক্ত এবং ট্র্যাক করার ক্ষমতা। ( XR_EXT_spatial_image_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

পরিবেশের মেশ ট্র্যাক করার ক্ষমতা। ( XR_EXT_spatial_mesh_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

অবজেক্ট ট্র্যাকিং ( XR_ANDROID_spatial_object_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

ডেপথ বাফারের বিপরীতে রেকাস্ট ( XR_ANDROID_spatial_discovery_raycast এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

একটি রুম ট্র্যাক করার ক্ষমতা ( XR_ANDROIDSYS_spatial_room_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

রুমের সীমানা ট্র্যাক করার ক্ষমতা ( XR_ANDROIDSYS_spatial_room_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

অ্যানোটেশন ট্র্যাকিং ( XR_ANDROID_spatial_annotation_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

রাস্তার জ্যামিতি ( XR_ANDROIDX2_geospatial_streetscape এক্সটেনশন দ্বারা যুক্ত)

xrEnumerateSpatialCapabilitiesEXT ফাংশনটি নিম্নরূপে সংজ্ঞায়িত করা হয়েছে:

XrResult xrEnumerateSpatialCapabilitiesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    capabilityCapacityInput,
    uint32_t*                                   capabilityCountOutput,
    XrSpatialCapabilityEXT*                     capabilities);

প্যারামিটার বিবরণ

  • instance হলো একটি XrInstance- এর হ্যান্ডেল।
  • systemId হলো সেই XrSystemId যার স্থানিক সক্ষমতাগুলো গণনা করা হবে।
  • capabilityCapacityInput হলো capabilities অ্যারের ধারণক্ষমতা, অথবা প্রয়োজনীয় ধারণক্ষমতা পুনরুদ্ধারের অনুরোধ বোঝাতে এর মান ০।
  • capabilityCountOutput হলো সক্ষমতার সংখ্যা, অথবা capabilityCapacityInput অপর্যাপ্ত হলে প্রয়োজনীয় ধারণক্ষমতা।
  • capabilities হলো XrSpatialCapabilityEXT- এর একটি অ্যারে। capabilityCapacityInput মান 0 হলে এটি NULL হতে পারে ।
  • প্রয়োজনীয় capabilities সাইজ নির্ধারণের বিস্তারিত বিবরণের জন্য বাফার সাইজ প্যারামিটার বিভাগটি দেখুন।

অ্যাপ্লিকেশনটি xrEnumerateSpatialCapabilitiesEXT ব্যবহার করে একটি প্রদত্ত XrSystemId দ্বারা সমর্থিত স্থানিক সক্ষমতাগুলির তালিকা গণনা করতে পারে ।

instance , রানটাইম সেইসব স্পেশিয়াল ক্যাপাবিলিটি গণনা করবে না, যেগুলোর এক্সটেনশন সক্রিয় করা নেই।

বৈধ ব্যবহার (অন্তর্নিহিত)

  • xrEnumerateSpatialCapabilitiesEXT কল করার আগে XR_EXT_spatial_entity এক্সটেনশনটি অবশ্যই সক্রিয় করতে হবে।
  • instance অবশ্যই একটি বৈধ XrInstance হ্যান্ডেল হতে হবে
  • capabilityCountOutput অবশ্যই একটি uint32_t মানের পয়েন্টার হতে হবে।
  • যদি capabilityCapacityInput মান 0 না হয়, তাহলে capabilities অবশ্যই capabilityCapacityInput XrSpatialCapabilityEXT মানগুলোর একটি অ্যারের পয়েন্টার হতে হবে।

রিটার্ন কোড

সাফল্য

  • XR_SUCCESS

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

xrEnumerateSpatialCapabilityComponentTypesEXT ফাংশনটি নিম্নরূপে সংজ্ঞায়িত করা হয়েছে:

XrResult xrEnumerateSpatialCapabilityComponentTypesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    XrSpatialCapabilityComponentTypesEXT*       capabilityComponents);

প্যারামিটার বিবরণ

  • instance হলো একটি XrInstance- এর হ্যান্ডেল।
  • systemId হলো সেই XrSystemId যার স্থানিক সক্ষমতার উপাদানগুলো গণনা করা হবে।
  • capability হলো XrSpatialCapabilityEXT , যার জন্য কম্পোনেন্টগুলো গণনা করা হবে।
  • capabilityComponents হলো XrSpatialCapabilityComponentTypesEXT- এর একটি পয়েন্টার, যা একটি ইনপুট/আউটপুট স্ট্রাকচার এবং যেখানে অ্যাপ্লিকেশন দ্বারা বরাদ্দকৃত একটি অ্যারে পূরণ করা হয়।

এই ফাংশনটি কনফিগার করা অনুযায়ী, প্রদত্ত ক্যাপাবিলিটি সিস্টেমের এনটিটিগুলোর উপর যে কম্পোনেন্ট টাইপগুলো সরবরাহ করে, সেগুলোকে তালিকাভুক্ত করে।

অ্যাপ্লিকেশনটি XrSpatialCapabilityComponentTypesEXT :: componentTypes এ তালিকাভুক্ত কম্পোনেন্ট টাইপগুলো ব্যবহার করে systemId capability জন্য যে সকল কম্পোনেন্ট সমর্থন করে তার সম্পূর্ণ সেটটি বুঝতে পারে এবং এর জন্য একটি XrSpatialContextEXT তৈরি করার সময় capability জন্য একটি বৈধ কনফিগারেশন কী হবে তা নির্ধারণ করতে এই তালিকাটি ব্যবহার করতে পারে ।

যদি xrEnumerateSpatialCapabilitiesEXT দ্বারা capability গণনা করা না হয়, তাহলে রানটাইমকে অবশ্যই XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT রিটার্ন করতে হবে।

instance , রানটাইম সেইসব স্পেশিয়াল কম্পোনেন্ট টাইপগুলিকে গণনা করবে না, যেগুলির এক্সটেনশন সক্রিয় করা নেই।

বৈধ ব্যবহার (অন্তর্নিহিত)

  • xrEnumerateSpatialCapabilityComponentTypesEXT কল করার আগে XR_EXT_spatial_entity এক্সটেনশনটি অবশ্যই সক্রিয় করতে হবে।
  • instance অবশ্যই একটি বৈধ XrInstance হ্যান্ডেল হতে হবে
  • capability অবশ্যই একটি বৈধ XrSpatialCapabilityEXT মান হতে হবে
  • capabilityComponents অবশ্যই একটি XrSpatialCapabilityComponentTypesEXT স্ট্রাকচারের একটি পয়েন্টার হতে হবে।

রিটার্ন কোড

সাফল্য

  • XR_SUCCESS

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialCapabilityComponentTypesEXT কাঠামোটি নিম্নরূপে সংজ্ঞায়িত করা হয়:

typedef struct XrSpatialCapabilityComponentTypesEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      componentTypeCapacityInput;
    uint32_t                      componentTypeCountOutput;
    XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialCapabilityComponentTypesEXT;

সদস্যদের বিবরণ

  • type হলো এই স্ট্রাকচারটির XrStructureType ।
  • next হলো NULL অথবা একটি স্ট্রাকচার চেইনের পরবর্তী স্ট্রাকচারের একটি পয়েন্টার। কোর OpenXR বা এই এক্সটেনশনে এই ধরনের কোনো স্ট্রাকচার সংজ্ঞায়িত করা নেই।
  • componentTypeCapacityInput হলো অ্যারের ধারণক্ষমতা, অথবা প্রয়োজনীয় ধারণক্ষমতা পুনরুদ্ধারের অনুরোধ বোঝাতে এর মান ০ হবে।
  • componentTypeCountOutput হলো কম্পোনেন্ট টাইপের সংখ্যা, অথবা componentTypeCapacityInput অপর্যাপ্ত হলে প্রয়োজনীয় ধারণক্ষমতা।
  • componentTypes হলো XrSpatialComponentTypeEXT- এর একটি অ্যারে। যদি componentTypeCapacityInput 0 হয়, তবে এটি NULL হতে পারে ।
  • প্রয়োজনীয় componentTypes সাইজ নির্ধারণের বিস্তারিত বিবরণের জন্য Buffer Size Parameters সেকশনটি দেখুন।

বৈধ ব্যবহার (অন্তর্নিহিত)

স্থানিক ক্ষমতার বৈশিষ্ট্য 

typedef enum XrSpatialCapabilityFeatureEXT {
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID = 1000761000,
    XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID = 1000761001,
    XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID = 1000761002,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT = 1000782001,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT = 1000782002,
    XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_FEATURE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityFeatureEXT;

কিছু ক্যাপাবিলিটির প্যারামিটার অ্যাপ্লিকেশনের কাছে উন্মুক্ত থাকে, যা রানটাইম দ্বারা কম্পোনেন্ট ডেটা কীভাবে গণনা করা হবে তা কনফিগার করতে ব্যবহৃত হয়। প্যারামিটারাইজেশন/কনফিগারযোগ্যতার এই মাত্রাগুলো ক্যাপাবিলিটি ফিচার নামে পরিচিত। উদাহরণস্বরূপ, একটি ইমেজ ট্র্যাকিং ক্যাপাবিলিটির জন্য, রানটাইম এমন একটি ফিচার সমর্থন করতে পারে যার মাধ্যমে অ্যাপ্লিকেশন নির্দিষ্ট করতে পারে যে ট্র্যাক করা ছবিগুলো স্থির কি না।

একটি কনফিগারেশন কাঠামোর মাধ্যমে রানটাইমকে এই তথ্য সরবরাহ করার ফলে সংশ্লিষ্ট সত্তাগুলিতে (যেমন ট্র্যাক করা ছবিতে) উপস্থিত কম্পোনেন্ট টাইপের সেট পরিবর্তন হওয়া উচিত নয়। তবে, রানটাইম ইমেজ ট্র্যাকিং ক্ষমতার মতো বিষয়গুলোকে অপ্টিমাইজ করতে এবং অ্যাপ্লিকেশনটিকে আরও ভালো অভিজ্ঞতা প্রদান করতে সক্ষম হতে পারে ।

এই ধরনের বৈশিষ্ট্যগুলো XrSpatialCapabilityFeatureEXT দ্বারা উপস্থাপিত হয় এবং অ্যাপ্লিকেশনটি xrEnumerateSpatialCapabilityFeaturesEXT ব্যবহার করে সেগুলোকে গণনা করে।

প্রতিটি ক্যাপাবিলিটি ফিচার সক্রিয় করার জন্য একটি সংশ্লিষ্ট কনফিগারেশন স্ট্রাকচার থাকে। এই ধরনের কনফিগারেশন স্ট্রাকচারগুলোকে অবশ্যই সংশ্লিষ্ট ক্যাপাবিলিটির XrSpatialCapabilityConfigurationBaseHeaderEXT :: next এর সাথে চেইন করতে হবে।

গণনাকারীগুলোর নিম্নলিখিত মান রয়েছে:

এনামের বিবরণ

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

অ্যাপ্লিকেশনগুলিকে মার্কারের আকার নির্দিষ্ট করার সুযোগ দেওয়ার একটি সক্ষমতা বৈশিষ্ট্য। এর সংশ্লিষ্ট কনফিগারেশন কাঠামোটি হলো XrSpatialMarkerSizeEXT (যা XR_EXT_spatial_marker_tracking এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

মার্কারগুলো স্থির থাকবে কিনা, তা অ্যাপ্লিকেশনগুলোকে নির্দিষ্ট করার সুযোগ দেওয়ার একটি সক্ষমতা বৈশিষ্ট্য। এর সংশ্লিষ্ট কনফিগারেশন কাঠামোটি হলো XrSpatialMarkerStaticOptimizationEXT (যা XR_EXT_spatial_marker_tracking এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

একটি স্থানিক বৈশিষ্ট্য যা অ্যাপ্লিকেশনগুলিকে রানটাইমের ট্র্যাক করার জন্য XrSpatialObjectSemanticLabelEXT থেকে লেবেলের একটি উপসেট নির্দিষ্ট করার সুযোগ দেয়। এর সংশ্লিষ্ট কনফিগারেশন কাঠামোটি হলো XrSpatialFeatureObjectSemanticLabelSubsetEXT । ( XR_EXT_spatial_object_tracking এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

রানটাইমটি XrSpatialDiscoverySnapshotCreateInfoEXT- এর জন্য XrSpatialBoundsSpherefANDROID ফিল্টার সমর্থন করে; এর জন্য স্পেশিয়াল কনটেক্সট তৈরির সময় কোনো কনফিগারেশন কাঠামো অন্তর্ভুক্ত করার প্রয়োজন হয় না। ( XR_ANDROID_spatial_discovery_bounds এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID

রানটাইমটি XrSpatialDiscoverySnapshotCreateInfoEXT- এর জন্য XrSpatialBoundsBoxfANDROID ফিল্টার সমর্থন করে; এর জন্য স্পেশিয়াল কনটেক্সট তৈরির সময় কোনো কনফিগারেশন কাঠামো অন্তর্ভুক্ত করার প্রয়োজন হয় না। ( XR_ANDROID_spatial_discovery_bounds এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID

রানটাইমটি XrSpatialDiscoverySnapshotCreateInfoEXT- এর জন্য XrSpatialBoundsFrustumfANDROID ফিল্টার সমর্থন করে; এর জন্য স্পেশিয়াল কনটেক্সট তৈরির সময় কোনো কনফিগারেশন কাঠামো অন্তর্ভুক্ত করার প্রয়োজন হয় না। ( XR_ANDROID_spatial_discovery_bounds এক্সটেনশন দ্বারা যুক্ত)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT

রানটাইমটি শনাক্তকৃত এবং ট্র্যাক করা ইমেজগুলির ভৌত আকার স্বয়ংক্রিয়ভাবে নির্ণয় করতে সমর্থন করে। এর সংশ্লিষ্ট কনফিগারেশন কাঠামোটি হলো XrSpatialImageSizeEXT (যা XR_EXT_spatial_image_tracking এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

রানটাইমটি XrSpatialImageStaticOptimizationEXT সমর্থন করে। এর সংশ্লিষ্ট কনফিগারেশন কাঠামোটি হলো XrSpatialImageStaticOptimizationEXT । ( XR_EXT_spatial_image_tracking এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT

রানটাইমটি XrSpatialImageSizeEXT সমর্থন করে। এর সংশ্লিষ্ট কনফিগারেশন কাঠামোটি হলো XrSpatialImageSizeEXT (যা XR_EXT_spatial_image_tracking এক্সটেনশন দ্বারা যুক্ত করা হয়েছে)।

XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

পরিবেশের একটি ওয়াটারটাইট মেশ ট্র্যাক করার সক্ষমতা বৈশিষ্ট্য। এর সংশ্লিষ্ট কনফিগারেশন কাঠামোটি হলো XrSpatialFeatureTrackWatertightMeshEXT । ( XR_EXT_spatial_mesh_tracking এক্সটেনশন দ্বারা যুক্ত)

xrEnumerateSpatialCapabilityFeaturesEXT ফাংশনটি নিম্নরূপে সংজ্ঞায়িত করা হয়েছে:

XrResult xrEnumerateSpatialCapabilityFeaturesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    capabilityFeatureCapacityInput,
    uint32_t*                                   capabilityFeatureCountOutput,
    XrSpatialCapabilityFeatureEXT*              capabilityFeatures);

প্যারামিটার বিবরণ

  • instance হলো একটি XrInstance- এর হ্যান্ডেল।
  • systemId হলো সেই XrSystemId যার স্থানিক সক্ষমতার বৈশিষ্ট্যগুলো গণনা করা হবে।
  • capability হলো XrSpatialCapabilityEXT, যার জন্য ফিচারগুলো তালিকাভুক্ত করা হবে।
  • capabilityFeatureCapacityInput হলো অ্যারের ধারণক্ষমতা, অথবা প্রয়োজনীয় ধারণক্ষমতা পুনরুদ্ধারের অনুরোধ বোঝাতে এর মান ০ হবে।
  • capabilityFeatureCountOutput হলো ফিচারের সংখ্যা, অথবা capabilityFeatureCapacityInput অপর্যাপ্ত হলে প্রয়োজনীয় ধারণক্ষমতা।
  • capabilityFeatures হলো XrSpatialCapabilityFeatureEXT- এর একটি অ্যারে। capabilityFeatureCapacityInput মান 0 হলে এটি NULL হতে পারে ।
  • প্রয়োজনীয় capabilityFeatures সাইজ নির্ধারণের বিস্তারিত বিবরণের জন্য Buffer Size Parameters বিভাগটি দেখুন।

অ্যাপ্লিকেশনটি xrEnumerateSpatialCapabilityFeaturesEXT ব্যবহার করে একটি XrSpatialCapabilityEXT- এর জন্য প্রদত্ত সিস্টেম দ্বারা সমর্থিত বৈশিষ্ট্যগুলি খুঁজে বের করে।

যেসব ক্যাপাবিলিটির ফিচার উন্মুক্ত থাকে, অ্যাপ্লিকেশনটি সক্রিয় করার জন্য ফিচার বা ফিচারগুলো নির্বাচন করে এবং XrSpatialContextCreateInfoEXT :: capabilityConfigs এ ক্যাপাবিলিটি কনফিগারেশন স্ট্রাকচারের পরবর্তী চেইনে সংশ্লিষ্ট কনফিগারেশন স্ট্রাকচারটি সরবরাহ করে।

যদি capability xrEnumerateSpatialCapabilitiesEXT দ্বারা তালিকাভুক্ত কোনো ক্যাপাবিলিটি না হয়, তাহলে রানটাইমকে অবশ্যই XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT রিটার্ন করতে হবে।

instance , রানটাইম সেইসব স্পেশিয়াল ক্যাপাবিলিটি ফিচারগুলোকে গণনা করবে না, যেগুলোর এক্সটেনশন সক্রিয় করা নেই।

বৈধ ব্যবহার (অন্তর্নিহিত)

  • xrEnumerateSpatialCapabilityFeaturesEXT কল করার আগে XR_EXT_spatial_entity এক্সটেনশনটি অবশ্যই সক্রিয় করতে হবে।
  • instance অবশ্যই একটি বৈধ XrInstance হ্যান্ডেল হতে হবে
  • capability অবশ্যই একটি বৈধ XrSpatialCapabilityEXT মান হতে হবে
  • capabilityFeatureCountOutput অবশ্যই একটি uint32_t মানের পয়েন্টার হতে হবে।
  • যদি capabilityFeatureCapacityInput 0 না হয়, তাহলে capabilityFeatures অবশ্যই capabilityFeatureCapacityInput XrSpatialCapabilityFeatureEXT মানগুলোর একটি অ্যারের পয়েন্টার হতে হবে।

রিটার্ন কোড

সাফল্য

  • XR_SUCCESS

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

স্থানিক প্রেক্ষাপট

একটি স্থানিক প্রেক্ষাপট তৈরি করুন 

XR_DEFINE_HANDLE(XrSpatialContextEXT)

XrSpatialContextEXT হ্যান্ডেলটি ব্যবহারকারীর পরিবেশে থাকা নির্দিষ্ট সংখ্যক স্থানিক সত্তা আবিষ্কার এবং হালনাগাদ করার রিসোর্সসমূহকে প্রতিনিধিত্ব করে। অ্যাপ্লিকেশনটি এই এক্সটেনশনের অন্যান্য ফাংশন ব্যবহার করে স্থানিক সত্তাগুলো আবিষ্কার ও হালনাগাদ করার জন্য এই হ্যান্ডেলটি ব্যবহার করতে পারে ।

xrCreateSpatialContextAsyncEXT ফাংশনটি নিম্নরূপে সংজ্ঞায়িত করা হয়েছে:

XrResult xrCreateSpatialContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialContextCreateInfoEXT*        createInfo,
    XrFutureEXT*                                future);

প্যারামিটার বিবরণ

  • session একটি XrSession , যেখানে স্থানিক প্রেক্ষাপটটি সক্রিয় থাকবে।
  • createInfo হলো XrSpatialContextCreateInfoEXT যা স্পেশিয়াল কনটেক্সট প্যারামিটারগুলো নির্দিষ্ট করতে ব্যবহৃত হয়।
  • future হলো XrFutureEXT এর একটি পয়েন্টার।

অ্যাপ্লিকেশনটি নিম্নলিখিত উপায়ে একটি XrSpatialContextEXT হ্যান্ডেল তৈরি করতে পারে :

  • XrSpatialContextCreateInfoEXT :: capabilityConfigs এ XrSpatialCapabilityConfigurationBaseHeaderEXT থেকে উদ্ভূত স্ট্রাকচার প্রদান করার মাধ্যমে ক্যাপাবিলিটি এবং সেই ক্যাপাবিলিটির জন্য কম্পোনেন্টগুলো সক্রিয় করা হয়।
  • এর XrSpatialCapabilityFeatureEXT- এর সংশ্লিষ্ট কনফিগারেশন কাঠামো ব্যবহার করে সক্ষমতাগুলোকে কনফিগার করা।

যদি XrSpatialContextCreateInfoEXT ::capabilityConfigCount-এর মান ০ হয়, তাহলে রানটাইমকে অবশ্যই XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT রিটার্ন করতে হবে। একটি স্পেশিয়াল কনটেক্সট হ্যান্ডেলের অন্তত একটি ক্যাপাবিলিটি থাকা প্রয়োজন।

যদি XrSpatialContextCreateInfoEXT :: capabilityConfigs অ্যারের কোনো ক্যাপাবিলিটি xrEnumerateSpatialCapabilitiesEXT দ্বারা গণনা করা না হয়, তাহলে রানটাইমকে অবশ্যই XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT রিটার্ন করতে হবে।

যদি XrSpatialContextCreateInfoEXT :: capabilityConfigs এর মধ্যে থাকা XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount ০ হয়, তাহলে রানটাইমকে অবশ্যই XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT রিটার্ন করতে হবে। কোনো ক্যাপাবিলিটির জন্য সক্রিয় করার মতো কম্পোনেন্ট টাইপের তালিকা ছাড়া সেই ক্যাপাবিলিটি কনফিগারেশনটি অসম্পূর্ণ থাকে।

যদি XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents এ তালিকাভুক্ত কোনো কম্পোনেন্ট টাইপ, xrEnumerateSpatialCapabilityComponentTypesEXT- এ XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability এর জন্য গণনা করা না হয়, তাহলে রানটাইমকে অবশ্যই XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT রিটার্ন করতে হবে।

যদি XrSpatialContextCreateInfoEXT :: capabilityConfigs এর পরবর্তী চেইনের কোনো স্ট্রাকচার এমন একটি XrSpatialCapabilityFeatureEXT- এর সাথে সঙ্গতিপূর্ণ হয়, যা xrEnumerateSpatialCapabilityFeaturesEXT- এ সেই ক্যাপাবিলিটির জন্য তালিকাভুক্ত নয়, তবে রানটাইমকে অবশ্যই সেই XrSpatialCapabilityFeatureEXT স্ট্রাকচারটিকে উপেক্ষা করতে হবে।

যদি XrSpatialContextCreateInfoEXT :: capabilityConfigs একই XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability সহ একাধিক স্ট্রাকচার থাকে, তাহলে রানটাইমকে অবশ্যই XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT রিটার্ন করতে হবে।

সিস্টেম রিসোর্সের সর্বোত্তম ব্যবহার নিশ্চিত করতে, রানটাইম আগত স্পেশিয়াল রিকোয়েস্টের জন্য নিজেকে প্রস্তুত করতে XrSpatialContextCreateInfoEXT অ্যারেতে প্রদত্ত কনফিগারেশনগুলো ব্যবহার করতে পারে । উদাহরণস্বরূপ, একটি রানটাইম যা প্লেন ট্র্যাকিং ক্ষমতা সমর্থন করে, সেটি কেবল তখনই তার প্লেন ট্র্যাকিং পাইপলাইন শুরু করতে পারে, যদি অ্যাপ্লিকেশনটি প্লেন ট্র্যাকিং ক্ষমতা ধারণকারী একটি স্পেশিয়াল কনটেক্সট হ্যান্ডেল তৈরি করে। যদি কনফিগার করা ক্ষমতাগুলোর ওয়ার্ম-আপ সময় দীর্ঘ হয়, তাহলে xrCreateSpatialDiscoverySnapshotAsyncEXT- এ কল করার ফলে একটি খালি স্ন্যাপশট তৈরি হতে পারে । অন্তর্নিহিত ট্র্যাকিং পরিষেবাগুলো ওয়ার্ম-আপ হয়েছে কিনা তা নিশ্চিত হতে, অ্যাপ্লিকেশনটি xrCreateSpatialDiscoverySnapshotAsyncEXT ব্যবহার করার আগে XrEventDataSpatialDiscoveryRecommendedEXT- এর জন্য অপেক্ষা করতে পারে ।

যদি কোনো রানটাইম XrSpatialContextEXT- এর জন্য কনফিগার করা স্পেশিয়াল ক্যাপাবিলিটিগুলোতে অ্যাপ্লিকেশনের অ্যাক্সেস নিয়ন্ত্রণ করতে একটি পারমিশন সিস্টেম প্রয়োগ করে, তাহলে এই অ্যাপ্লিকেশনটিকে সেই পারমিশনগুলো প্রদান করা না হয়ে থাকলে রানটাইমটিকে অবশ্যই XR_ERROR_PERMISSION_INSUFFICIENT রিটার্ন করতে হবে।

এই ফাংশনটি একটি অ্যাসিঙ্ক্রোনাস অপারেশন শুরু করে এবং একটি সংশ্লিষ্ট XrFutureEXT তৈরি করে, যা xrPollFutureEXT এবং সম্পর্কিত ফাংশনগুলির সাথে ব্যবহারযোগ্য। এই ফাংশনের রিটার্ন ভ্যালু শুধুমাত্র নির্দেশ করে যে অ্যাসিঙ্ক্রোনাস অপারেশনটি শিডিউল করার জন্য প্যারামিটারগুলো গ্রহণযোগ্য ছিল কিনা। এর সংশ্লিষ্ট কমপ্লিশন ফাংশনটি হলো xrCreateSpatialContextCompleteEXT , যা তখন ব্যবহারযোগ্য যখন এই ফাংশন থেকে প্রাপ্ত কোনো ফিউচার READY অবস্থায় থাকে এবং এর আউটপুটগুলো XrCreateSpatialContextCompletionEXT নামক কমপ্লিশন স্ট্রাকচারে সেই ফাংশন দ্বারা পপুলেট করা হয়।

বৈধ ব্যবহার (অন্তর্নিহিত)

  • xrCreateSpatialContextAsyncEXT কল করার আগে XR_EXT_spatial_entity এক্সটেনশনটি অবশ্যই সক্রিয় করতে হবে।
  • session অবশ্যই একটি বৈধ XrSession হ্যান্ডেল হতে হবে।
  • createInfo অবশ্যই একটি বৈধ XrSpatialContextCreateInfoEXT স্ট্রাকচারের পয়েন্টার হতে হবে।
  • future অবশ্যই একটি XrFutureEXT মানের দিকে নির্দেশকারী একটি পয়েন্টার হতে হবে।

রিটার্ন কোড

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContextCreateInfoEXT কাঠামোটি নিম্নরূপে সংজ্ঞায়িত করা হয়: 

typedef struct XrSpatialContextCreateInfoEXT {
    XrStructureType                                                type;
    const void*                                                    next;
    uint32_t                                                       capabilityConfigCount;
    const XrSpatialCapabilityConfigurationBaseHeaderEXT* const*    capabilityConfigs;
} XrSpatialContextCreateInfoEXT;

সদস্যদের বিবরণ

  • type হলো এই স্ট্রাকচারটির XrStructureType ।
  • next হলো NULL অথবা একটি স্ট্রাকচার চেইনের পরবর্তী স্ট্রাকচারের একটি পয়েন্টার। কোর OpenXR বা এই এক্সটেনশনে এই ধরনের কোনো স্ট্রাকচার সংজ্ঞায়িত করা নেই।
  • capabilityConfigCount হলো একটি uint32_t যা capabilityConfigs অ্যারের উপাদান সংখ্যা বর্ণনা করে।
  • capabilityConfigs হলো XrSpatialCapabilityConfigurationBaseHeaderEXT পয়েন্টারগুলোর একটি অ্যারের দিকে নির্দেশকারী একটি পয়েন্টার।

XrSpatialContextCreateInfoEXT স্ট্রাকচারটি একটি XrSpatialContextEXT হ্যান্ডেল তৈরি করার জন্য প্রয়োজনীয় তথ্য বর্ণনা করে।

বৈধ ব্যবহার (অন্তর্নিহিত)

XrSpatialCapabilityConfigurationBaseHeaderEXT স্ট্রাকচারটি নিম্নরূপে সংজ্ঞায়িত করা হয়েছে: 

typedef struct XrSpatialCapabilityConfigurationBaseHeaderEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationBaseHeaderEXT;

এই স্ট্রাকচারটি সরাসরি এপিআই-তে ব্যবহৃত হয় না, বরং এর চাইল্ড স্ট্রাকচারগুলো XrSpatialContextCreateInfoEXT- এর সাথে ব্যবহার করে স্পেশিয়াল ক্যাপাবিলিটি কনফিগার করা যায় ।

সদস্যদের বিবরণ

  • type হলো এই স্ট্রাকচারটির XrStructureType ।
  • next হলো NULL অথবা একটি স্ট্রাকচার চেইনের পরবর্তী স্ট্রাকচারের দিকে নির্দেশকারী একটি পয়েন্টার।
  • capability হল একটি XrSpatialCapabilityEXT ।
  • enabledComponentCount হলো একটি uint32_t যা enabledComponents অ্যারের উপাদান সংখ্যা নির্দেশ করে।
  • enabledComponents হলো XrSpatialComponentTypeEXT- এর একটি অ্যারের পয়েন্টার।

যদি xrEnumerateSpatialCapabilitiesEXT দ্বারা capability গণনা করা না হয়, তাহলে রানটাইমকে অবশ্যই XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT রিটার্ন করতে হবে। যদি enabledComponents এ তালিকাভুক্ত কোনো কম্পোনেন্ট টাইপ xrEnumerateSpatialCapabilityComponentTypesEXT- এ capability জন্য গণনা করা না হয়, তাহলে রানটাইমকে অবশ্যই XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT রিটার্ন করতে হবে।

বৈধ ব্যবহার (অন্তর্নিহিত)

xrCreateSpatialContextCompleteEXT ফাংশনটি নিম্নরূপে সংজ্ঞায়িত করা হয়েছে: 

XrResult xrCreateSpatialContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialContextCompletionEXT*        completion);

প্যারামিটার বিবরণ

xrCreateSpatialContextCompleteEXT completes the asynchronous operation started by xrCreateSpatialContextAsyncEXT . The runtime must return XR_ERROR_FUTURE_PENDING_EXT if future is not in ready state. The runtime must return XR_ERROR_FUTURE_INVALID_EXT if future has already been completed or cancelled.

Valid Usage (Implicit)

Return Codes

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

The XrCreateSpatialContextCompletionEXT structure is defined as: 

typedef struct XrCreateSpatialContextCompletionEXT {
    XrStructureType        type;
    void*                  next;
    XrResult               futureResult;
    XrSpatialContextEXT    spatialContext;
} XrCreateSpatialContextCompletionEXT;

Member Descriptions

Future Return Codes

futureResult values:

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT

If futureResult is a success code, spatialContext must be valid. If spatialContext is valid, it remains so only within the lifecycle of xrCreateSpatialContextAsyncEXT :: session or until the application destroys the spatialContext with xrDestroySpatialContextEXT , whichever comes first.

Valid Usage (Implicit)

Destroy the spatial context

The xrDestroySpatialContextEXT function is defined as: 

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

Parameter Descriptions

The application can call xrDestroySpatialContextEXT function to release the spatialContext handle and the underlying resources when finished with spatial entity discovery and update tasks. If there is no other valid XrSpatialContextEXT that was created with the same spatial capabilities as spatialContext , this call serves as a suggestion to the runtime to disable the tracking services required for those capabilities to save system resources.

Valid Usage (Implicit)

Thread Safety

  • Access to spatialContext , and any child handles, must be externally synchronized

Return Codes

সাফল্য

  • XR_SUCCESS

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Spatial Entity Representations

Spatial Entity ID 

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT is used to represent any kind of entity discovered by the runtime in the spatial environment of the user. An XrSpatialEntityIdEXT is valid for the XrSpatialContextEXT in which it is discovered, and the runtime must not reuse the same XrSpatialEntityIdEXT for different entities within the same XrSpatialContextEXT . Also, the runtime must not reuse the same XrSpatialEntityIdEXT across multiple XrSpatialContextEXT within the same XrSession regardless of whether it represents the same entity or different ones. 

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT is a reserved value representing an invalid XrSpatialEntityIdEXT . It may be passed to and returned from API functions only when specifically allowed.

Spatial Entity Handle 

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

The XrSpatialEntityEXT handle represents a spatial entity. An application can create such a handle to express its interest in a specific entity to the runtime.

Create Spatial Entity Handle from ID

The xrCreateSpatialEntityFromIdEXT function is defined as: 

XrResult xrCreateSpatialEntityFromIdEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialEntityFromIdCreateInfoEXT*   createInfo,
    XrSpatialEntityEXT*                         spatialEntity);

Parameter Descriptions

The application can use xrCreateSpatialEntityFromIdEXT to create an XrSpatialEntityEXT handle which is a reference to an entity that exists in the user's environment.

The runtime must return XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT if XrSpatialEntityFromIdCreateInfoEXT :: entityId is not a valid ID for spatialContext .

Valid Usage (Implicit)

Return Codes

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The XrSpatialEntityFromIdCreateInfoEXT structure is defined as: 

typedef struct XrSpatialEntityFromIdCreateInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    entityId;
} XrSpatialEntityFromIdCreateInfoEXT;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • entityId is the XrSpatialEntityIdEXT of the entity that the application wants to create a handle for.

Valid Usage (Implicit)

Destroy Spatial Entity Handle

The xrDestroySpatialEntityEXT function is defined as: 

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

Parameter Descriptions

The application can use xrDestroySpatialEntityEXT to release the spatialEntity handle when it is no longer interested in the entity referenced by this handle.

Valid Usage (Implicit)

Thread Safety

  • Access to spatialEntity , and any child handles, must be externally synchronized

Return Codes

সাফল্য

  • XR_SUCCESS

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Spatial Snapshot 

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

The application can create spatial snapshots for the purpose of discovering spatial entities or for updating its information about known spatial entities. The XrSpatialSnapshotEXT handle represents the immutable data for the discovered or updated spatial entities and a subset of their components as selected by the application. The spatial snapshot represents a coherent view of the entities and their component data. Once a snapshot is created, the snapshot's data must remain constant while the snapshot is valid.

The application can create any number of snapshots it wants but must be mindful of the memory being allocated for each new snapshot and must destroy the snapshots once it no longer needs them.

Create discovery snapshot

The xrCreateSpatialDiscoverySnapshotAsyncEXT function is defined as: 

XrResult xrCreateSpatialDiscoverySnapshotAsyncEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialDiscoverySnapshotCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Parameter Descriptions

The application can discover spatial entities by creating a discovery snapshot by using xrCreateSpatialDiscoverySnapshotAsyncEXT .

This function starts an asynchronous operation and creates a corresponding XrFutureEXT , usable with xrPollFutureEXT and related functions. The return value of this function only indicates whether the parameters were acceptable to schedule the asynchronous operation. The corresponding completion function is xrCreateSpatialDiscoverySnapshotCompleteEXT , usable when a future from this function is in the READY state, with outputs populated by that function in the completion structure XrCreateSpatialDiscoverySnapshotCompletionEXT .

The application can submit multiple discovery snapshot creation requests without needing to wait for the previous one to be completed. The runtime may process and complete the snapshot creation in any order. The runtime may delay the completion of the discovery snapshot creation to throttle the application if it needs to reduce the use of system resources due to power, thermal or other policies of the device.

The application can use XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes to filter the list of entities and the components whose data the runtime must include in the snapshot. If the application provides a valid list of spatial component types in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , then the runtime must only include spatial entities in the snapshot that have at least one of the components provided in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes . Also, the runtime must only include data for only those components in the snapshot.

The runtime must return XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT if any of the XrSpatialComponentTypeEXT in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes are not enabled for the spatial capabilities passed to XrSpatialContextCreateInfoEXT :: capabilityConfigs when creating spatialContext .

If the application does not provide a list of spatial component types in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , the runtime must include all the spatial entities in the snapshot that have the set of components which are enumerated in XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents for the capabilities configured for spatialContext . The runtime must include the data for all the enabled components of the capabilities configured for spatialContext .

If XrEventDataReferenceSpaceChangePending is queued before the completion of future , and XrEventDataReferenceSpaceChangePending :: poseValid is false, then the runtime may either create an XrSpatialSnapshotEXT that has no entities in it or set the XrSpatialEntityTrackingStateEXT of the entities that are no longer locatable in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace at XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time to XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT . The runtime must not set XrCreateSpatialContextCompletionEXT :: futureResult to an error code because of XrEventDataReferenceSpaceChangePending .

Valid Usage (Implicit)

Return Codes

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_VALIDATION_FAILURE

The XrSpatialDiscoverySnapshotCreateInfoEXT structure is defined as: 

typedef struct XrSpatialDiscoverySnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialDiscoverySnapshotCreateInfoEXT;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • componentTypeCount is a uint32_t describing the count of elements in the componentTypes array.
  • componentTypes is an array of XrSpatialComponentTypeEXT .

The XrSpatialDiscoverySnapshotCreateInfoEXT structure describes the information to create an XrSpatialSnapshotEXT handle when discovering spatial entities.

Valid Usage (Implicit)

The xrCreateSpatialDiscoverySnapshotCompleteEXT function is defined as: 

XrResult xrCreateSpatialDiscoverySnapshotCompleteEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrCreateSpatialDiscoverySnapshotCompletionInfoEXT* createSnapshotCompletionInfo,
    XrCreateSpatialDiscoverySnapshotCompletionEXT* completion);

Parameter Descriptions

xrCreateSpatialDiscoverySnapshotCompleteEXT completes the asynchronous operation started by xrCreateSpatialDiscoverySnapshotAsyncEXT . The runtime must return XR_ERROR_FUTURE_PENDING_EXT if XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future is not in ready state. The runtime must return XR_ERROR_FUTURE_INVALID_EXT if XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future has already been completed or cancelled.

Valid Usage (Implicit)

Return Codes

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

The XrCreateSpatialDiscoverySnapshotCompletionInfoEXT structure is defined as: 

typedef struct XrCreateSpatialDiscoverySnapshotCompletionInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrFutureEXT        future;
} XrCreateSpatialDiscoverySnapshotCompletionInfoEXT;

Member Descriptions

The locations in the various component data included in the created snapshot will be represented in baseSpace , located at time .

Valid Usage (Implicit)

The XrCreateSpatialDiscoverySnapshotCompletionEXT structure is defined as: 

typedef struct XrCreateSpatialDiscoverySnapshotCompletionEXT {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialSnapshotEXT    snapshot;
} XrCreateSpatialDiscoverySnapshotCompletionEXT;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • futureResult is the XrResult of the spatial discovery snapshot creation operation.
  • snapshot is an XrSpatialSnapshotEXT which can be used to query the component data of the discovered spatial entities.

Future Return Codes

futureResult values:

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

Valid Usage (Implicit)

Discovery Recommendation Event

The XrEventDataSpatialDiscoveryRecommendedEXT structure is defined as: 

typedef struct XrEventDataSpatialDiscoveryRecommendedEXT {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
} XrEventDataSpatialDiscoveryRecommendedEXT;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • spatialContext is the XrSpatialContextEXT for which discovery is being recommended by the runtime.

The application can retrieve this event by using xrPollEvent . The application can avoid excessive calls to xrCreateSpatialDiscoverySnapshotAsyncEXT to discover spatial entities by waiting for this event. If the application creates multiple discovery snapshots with the same XrSpatialDiscoverySnapshotCreateInfoEXT between two XrEventDataSpatialDiscoveryRecommendedEXT events, the resultant snapshots may contain the same entities and therefore the snapshot creation and data queries would be wasteful.

Waiting for this event to create a new discovery snapshot ensures that the application is not overloading the system with discovery requests for which the runtime may not return any new data and helps avoid the risk of overusing the system resources, and getting throttled due to power or thermal policies of the device. This also helps create parity between runtimes that are discovering spatial entities on the fly with live tracking and runtimes which are providing spatial entities off of a previously recorded state (where the runtime may queue the discovery recommendation event only once for each XrSpatialContextEXT ).

The runtime must not queue this event for notifying the application about changes or adjustments made to the component data of existing spatial entities. The application can use the xrCreateSpatialUpdateSnapshotEXT to keep track of component data updates for the spatial entities it is interested in.

A runtime may queue a discovery recommendation event without waiting for the application to first call xrCreateSpatialDiscoverySnapshotAsyncEXT . For example, a runtime may base the decision of queueing the discovery recommendation event on the configuration of the XrSpatialContextEXT , its own understanding of the environment around the user (discovery of new entities or loss of existing ones), or for hinting an appropriate discovery request cadence to the application so as not to overload the system resources. The runtime may choose to never queue this event for an XrSpatialContextEXT if no entities are found in the user's environment throughout the lifetime of that XrSpatialContextEXT .

The runtime must not queue this event for a given spatialContext until the application completes its creation by using xrCreateSpatialContextCompleteEXT .

After the application calls xrDestroySpatialContextEXT , the runtime must not queue any more discovery recommendation events for that spatial context nor return any such events for that context from xrPollEvent .

Valid Usage (Implicit)

Query Component Data

The xrQuerySpatialComponentDataEXT function is defined as: 

XrResult xrQuerySpatialComponentDataEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialComponentDataQueryConditionEXT* queryCondition,
    XrSpatialComponentDataQueryResultEXT*       queryResult);

Parameter Descriptions

The application can use xrQuerySpatialComponentDataEXT to query the component data of the entities in the snapshot by attaching a list structure to XrSpatialComponentDataQueryResultEXT :: next corresponding to each XrSpatialComponentTypeEXT in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

If the application attaches a list structure to XrSpatialComponentDataQueryResultEXT :: next that does not correspond to any of the components listed in XrSpatialComponentDataQueryConditionEXT :: componentTypes , the runtime must return XR_ERROR_VALIDATION_FAILURE .

The application can choose to attach the list structures corresponding to only a subset of components listed in XrSpatialComponentDataQueryConditionEXT :: componentTypes . The application can choose to omit the list structures altogether if it only wishes to know the ids and tracking state of the spatial entities that satisfy the queryCondition . The runtime must not treat the absence of list structures from the XrSpatialComponentDataQueryResultEXT :: next chain as a failure.

If XrEventDataReferenceSpaceChangePending is queued and XrEventDataReferenceSpaceChangePending :: changeTime elapsed while the application is querying component data from an XrSpatialSnapshotEXT , the application may use the event data to adjust the poses accordingly.

The runtime must populate XrSpatialComponentDataQueryResultEXT :: entityIds only with entities that have all the components specified in XrSpatialComponentDataQueryConditionEXT :: componentTypes . If XrSpatialComponentDataQueryConditionEXT :: componentTypeCount is 0, the runtime must populate queryResult with all the entities (and their tracking states) that are in the snapshot. If additional query conditions are added to XrSpatialComponentDataQueryConditionEXT :: next , the runtime must treat those as an "AND" with the component types availability ie the runtime must populate XrSpatialComponentDataQueryResultEXT ::entityIds only with entities that satisfy all of the provided conditions. The runtime must populate the component data in the list structures in the same order as the entities in XrSpatialComponentDataQueryResultEXT :: entityIds ie the component data at a given index in the list structure array must correspond to the entity at the same index.

If the tracking state for an entity is not XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT , the runtime must not change the data at the index corresponding to that entity in the array contained in the list structures attached to XrSpatialComponentDataQueryResultEXT .

Valid Usage (Implicit)

Return Codes

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

As an example the application creates an XrSpatialSnapshotEXT which contains 5 entities, where -

  • Entity 1 and 2 have components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT and XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
  • Entity 3 and 4 have components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
  • Entity 5 has components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT .

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

১

১

২

২

৩

৩

৪

৪

৫

৫

Bounded2D

Bounded2D

হ্যাঁ

হ্যাঁ

হ্যাঁ

হ্যাঁ

না

না

না

না

হ্যাঁ

হ্যাঁ

অভিভাবক

অভিভাবক

হ্যাঁ

হ্যাঁ

হ্যাঁ

হ্যাঁ

না

না

না

না

না

না

Mesh3D

Mesh3D

না

না

না

না

হ্যাঁ

হ্যাঁ

হ্যাঁ

হ্যাঁ

হ্যাঁ

হ্যাঁ

Bounded3D

Bounded3D

না

না

না

না

হ্যাঁ

হ্যাঁ

হ্যাঁ

হ্যাঁ

না

No Text is not SVG - cannot display

Figure 20. Example snapshot

xrQuerySpatialComponentDataEXT on the above snapshot with XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT listed in the query condition will result in entity #1, #2, and #5 being returned to the application and the application can attach an array of XrSpatialBounded2DDataEXT as part of the XrSpatialComponentBounded2DListEXT structure to the next chain of XrSpatialComponentDataQueryResultEXT to get the bounded2D data.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

১

১

২

২

৫

৫

Bounded2D

Bounded2D

Data for entityId #1

Data for entit...

Data for entityId #2

Data for entit...

Data for entityId #5

Data for entit...

entityIds

entityIds

পরবর্তী

পরবর্তী

XrSpatialComponent DataQueryResultEXT

XrSpatialComponent Dat...

সীমানা

সীমানা

XrSpatialComponent Bounded2DListEXT

XrSpatialComponent Bou... Text is not SVG - cannot display

Figure 21. Example query result

xrQuerySpatialComponentDataEXT on the above snapshot with XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT components listed in the query condition will result in entity #3 and #4 being returned to the application and the application can attach arrays of XrBoxf and XrSpatialMeshDataEXT as part of the XrSpatialComponentBounded3DListEXT and XrSpatialComponentMesh3DListEXT structures respectively to the next chain of XrSpatialComponentDataQueryResultEXT to get the component data.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

৩

৩

৪

৪

Bounded3D

Bounded3D

Data for entityId #3

Data for entit...

Data for entityId #4

Data for entit...

Mesh3D

Mesh3D

Data for entityId #3

Data for entit...

Data for entityId #4

Data for entit...

entityIds

entityIds

পরবর্তী

পরবর্তী

XrSpatialComponent DataQueryResultEXT

XrSpatialComponent Da...

সীমানা

সীমানা

পরবর্তী

পরবর্তী

XrSpatialComponent Bounded3DListEXT

XrSpatialComponent Bo...

XrSpatialComponent Mesh3DListEXT

XrSpatialComponent Me...

meshes

meshes Text is not SVG - cannot display

Figure 22. Example query result

The XrSpatialComponentDataQueryConditionEXT structure is defined as: 

typedef struct XrSpatialComponentDataQueryConditionEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialComponentDataQueryConditionEXT;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • componentTypeCount is a uint32_t describing the count of elements in the componentTypes array.
  • componentTypes is an array of XrSpatialComponentTypeEXT for which to get the data from the snapshot.

Valid Usage (Implicit)

The XrSpatialComponentDataQueryResultEXT structure is defined as: 

typedef struct XrSpatialComponentDataQueryResultEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            entityIdCapacityInput;
    uint32_t                            entityIdCountOutput;
    XrSpatialEntityIdEXT*               entityIds;
    uint32_t                            entityStateCapacityInput;
    uint32_t                            entityStateCountOutput;
    XrSpatialEntityTrackingStateEXT*    entityStates;
} XrSpatialComponentDataQueryResultEXT;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • entityIdCapacityInput is the capacity of the entityIds array, or 0 to indicate a request to retrieve the required capacity.
  • entityIdCountOutput is the number of XrSpatialEntityIdEXT in entityIds , or the required capacity in the case that entityIdCapacityInput is insufficient.
  • entityIds is an array of XrSpatialEntityIdEXT . It can be NULL if entityIdCapacityInput is 0.
  • entityStateCapacityInput is the capacity of the entityStates array, or 0 to indicate a request to retrieve the required capacity.
  • entityStateCountOutput is the number of XrSpatialEntityTrackingStateEXT in entityStates , or the required capacity in the case that entityStateCapacityInput is insufficient. This must always be the same as entityIdCountOutput .
  • entityStates is an array of XrSpatialEntityTrackingStateEXT . It can be NULL if entityStateCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required entityIds size.

An application can use the entityIds with xrCreateSpatialEntityFromIdEXT to create XrSpatialEntityEXT handles for the entities it is interested in getting regular updates for. The application can then use these XrSpatialEntityEXT handles with xrCreateSpatialUpdateSnapshotEXT to create an update snapshot that has the runtime's latest known data of the components for the provided entities.

Valid Usage (Implicit)

typedef enum XrSpatialEntityTrackingStateEXT {
    XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT = 1,
    XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT = 2,
    XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT = 3,
    XR_SPATIAL_ENTITY_TRACKING_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialEntityTrackingStateEXT;

The XrSpatialEntityTrackingStateEXT enumerates the possible spatial entity tracking states:

The enums have the following meanings:

Enum Description

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

The runtime has stopped tracking this entity and will never resume tracking it.

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

The runtime has paused tracking this entity but may resume tracking it in the future.

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

The runtime is currently tracking this entity and its component data is valid.

TRACKING

PAUSED

STOPPED

Figure 23. XrSpatialEntityTrackingStateEXT

  • The runtime may change the state of the spatial entity from XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT to XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT if it suspends the tracking of that spatial entity but has the possibility of resuming its tracking in the future. Some examples of when the runtime may do this include (but not limited to) if the application loses input focus; or if the given spatial entity is too far from the user to be accurately tracked; or if there are too many entities being tracked and the runtime wants to reduce the cost of tracking. XrSpatialEntityTrackingStateEXT helps the application insulate itself from the different tracking policies of each runtime.
  • The runtime may change the state of an entity from XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT to XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT .
  • The runtime must change the state of the spatial entity from XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT to XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT if the spatial entity is lost and its tracking will never be recovered or resumed. An example of such a case would be if the device loses tracking, restarts its tracking session but is unable to relocalize in its environment, and therefore treats discovered entities of this tracking session as new entities.
  • Once the tracking state of an entity is set to XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , the runtime must never change it any other state.
  • When querying the component data of a spatial entity using xrQuerySpatialComponentDataEXT , the runtime must set valid data in the contents of the buffers provided by the application in the next chain of XrSpatialComponentDataQueryResultEXT if the entity state is XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . If the entity state is XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT , the runtime must not change the content of the buffers.

Two-call idiom for component data

The XrSpatialBufferEXT structure is defined as: 

typedef struct XrSpatialBufferEXT {
    XrSpatialBufferIdEXT      bufferId;
    XrSpatialBufferTypeEXT    bufferType;
} XrSpatialBufferEXT;

Member Descriptions

  • bufferId the XrSpatialBufferIdEXT of the buffer data.
  • bufferType is the XrSpatialBufferTypeEXT to indicate the type of data in bufferId . The application can use bufferType to determine which function to use to retrieve the actual data of the buffer.

Some spatial components have variable-sized data and therefore require using the two-call idiom to retrieve their data. In such cases, the spatial component data structure provides an XrSpatialBufferEXT for each variable sized buffer needed in that component's data.

For the same bufferId , the runtime must provide the same data from one component data query to another, even across one snapshot to another. A different bufferId between component data query calls indicates to the application that the data for that component may have changed.

Valid Usage (Implicit)

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT is used to represent any kind of variable sized data for a spatial component.

The runtime must keep the XrSpatialBufferIdEXT and its data in memory for at least the lifecycle of the XrSpatialSnapshotEXT that contains it. The runtime may keep the XrSpatialBufferIdEXT and its data in memory for longer than the lifecycle of the XrSpatialSnapshotEXT in order to return the same ID as part of snapshots created later on by the application. For the same XrSpatialBufferIdEXT , the runtime must always return the same data via the appropriate xrGetSpatialBuffer* function. 

typedef enum XrSpatialBufferTypeEXT {
    XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT = 0,
    XR_SPATIAL_BUFFER_TYPE_STRING_EXT = 1,
    XR_SPATIAL_BUFFER_TYPE_UINT8_EXT = 2,
    XR_SPATIAL_BUFFER_TYPE_UINT16_EXT = 3,
    XR_SPATIAL_BUFFER_TYPE_UINT32_EXT = 4,
    XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT = 5,
    XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT = 6,
    XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT = 7,
    XR_SPATIAL_BUFFER_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialBufferTypeEXT;

The XrSpatialBufferTypeEXT enumeration identifies the different data types of the buffer represented XrSpatialBufferIdEXT .

Enumerant Descriptions

The xrGetSpatialBufferStringEXT function is defined as: 

XrResult xrGetSpatialBufferStringEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

Parameter Descriptions

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of characters, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of char . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_STRING_EXT by using xrGetSpatialBufferStringEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_STRING_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

buffer filled by the runtime must be a null-terminated UTF-8 string.

Valid Usage (Implicit)

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferStringEXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput char values

Return Codes

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The xrGetSpatialBufferUint8EXT function is defined as: 

XrResult xrGetSpatialBufferUint8EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint8_t*                                    buffer);

Parameter Descriptions

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of uint8_t . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_UINT8_EXT by using xrGetSpatialBufferUint8EXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_UINT8_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferUint8EXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput uint8_t values

Return Codes

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The xrGetSpatialBufferUint16EXT function is defined as: 

XrResult xrGetSpatialBufferUint16EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint16_t*                                   buffer);

Parameter Descriptions

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of uint16_t . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_UINT16_EXT by using xrGetSpatialBufferUint16EXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferUint16EXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput uint16_t values

Return Codes

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The xrGetSpatialBufferUint32EXT function is defined as: 

XrResult xrGetSpatialBufferUint32EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint32_t*                                   buffer);

Parameter Descriptions

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of uint32_t . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_UINT32_EXT by using xrGetSpatialBufferUint32EXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferUint32EXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput uint32_t values

Return Codes

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The xrGetSpatialBufferFloatEXT function is defined as: 

XrResult xrGetSpatialBufferFloatEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    float*                                      buffer);

Parameter Descriptions

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of float . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT by using xrGetSpatialBufferFloatEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferFloatEXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput float values

Return Codes

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The xrGetSpatialBufferVector2fEXT function is defined as: 

XrResult xrGetSpatialBufferVector2fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector2f*                                 buffer);

Parameter Descriptions

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of XrVector2f . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT by using xrGetSpatialBufferVector2fEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

Return Codes

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The xrGetSpatialBufferVector3fEXT function is defined as: 

XrResult xrGetSpatialBufferVector3fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector3f*                                 buffer);

Parameter Descriptions

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of XrVector3f . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT by using xrGetSpatialBufferVector3fEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

Valid Usage (Implicit)

Return Codes

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The XrSpatialBufferGetInfoEXT structure is defined as: 

typedef struct XrSpatialBufferGetInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialBufferIdEXT    bufferId;
} XrSpatialBufferGetInfoEXT;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • bufferId an XrSpatialBufferIdEXT for the buffer whose data to retrieve.

Valid Usage (Implicit)

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT is a reserved value representing an invalid XrSpatialBufferIdEXT . It may be passed to and returned from API functions only when specifically allowed.

Create Update Snapshot

The xrCreateSpatialUpdateSnapshotEXT function is defined as: 

XrResult xrCreateSpatialUpdateSnapshotEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialUpdateSnapshotCreateInfoEXT* createInfo,
    XrSpatialSnapshotEXT*                       snapshot);

Parameter Descriptions

The application can use xrCreateSpatialUpdateSnapshotEXT to create a snapshot and get the latest component data for specific entities as known by the runtime. Applications can provide the XrSpatialEntityEXT handles and the component types they are interested in when creating the snapshot.

The application can use XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes to filter the list of components whose data must be included in the snapshot. If the application provides a valid list of spatial component types in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , then the runtime must only include spatial entities in the snapshot that have at least one of the components provided in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Also, the runtime must only include data for those components in the snapshot.

The runtime must return XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT if any of the XrSpatialComponentTypeEXT in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes are not enabled for the spatial capabilities passed to XrSpatialContextCreateInfoEXT :: capabilityConfigs when creating spatialContext .

If the application does not provide a list of spatial component types in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , the runtime must include all the spatial entities listed in XrSpatialUpdateSnapshotCreateInfoEXT :: entities in the snapshot and it must include the data for all the enabled components of the capabilities configured for spatialContext .

The runtime must not include spatial entities that are not listed in XrSpatialUpdateSnapshotCreateInfoEXT :: entities in snapshot .

The application can create any number of snapshots it wants but must be mindful of the memory being allocated for each new snapshot and must destroy the snapshots once it no longer needs them.

Valid Usage (Implicit)

Return Codes

সাফল্য

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

The XrSpatialUpdateSnapshotCreateInfoEXT structure is defined as: 

typedef struct XrSpatialUpdateSnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            entityCount;
    const XrSpatialEntityEXT*           entities;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
    XrSpace                             baseSpace;
    XrTime                              time;
} XrSpatialUpdateSnapshotCreateInfoEXT;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • entityCount is a uint32_t describing the count of elements in the entities array.
  • entities is an array of XrSpatialEntityEXT for which the runtime must include the component data in the snapshot.
  • componentTypeCount is a uint32_t describing the count of elements in the componentTypes array.
  • componentTypes is an array of XrSpatialComponentTypeEXT for which the runtime must include the data in the snapshot.
  • baseSpace is the XrSpace relative to which all the locations of the update XrSpatialSnapshotEXT will be located.
  • time is the XrTime at which all the locations of the update XrSpatialSnapshotEXT will be located.

Valid Usage (Implicit)

  • The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialUpdateSnapshotCreateInfoEXT
  • type must be XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT
  • next must be NULL or a valid pointer to the next structure in a structure chain
  • entities must be a pointer to an array of entityCount valid XrSpatialEntityEXT handles
  • If componentTypeCount is not 0 , componentTypes must be a pointer to an array of componentTypeCount valid XrSpatialComponentTypeEXT values
  • baseSpace must be a valid XrSpace handle
  • The entityCount parameter must be greater than 0
  • Both of baseSpace and the elements of entities must have been created, allocated, or retrieved from the same XrSession

Destroy snapshot

The xrDestroySpatialSnapshotEXT function is defined as: 

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

Parameter Descriptions

The application can call xrDestroySpatialSnapshotEXT to destroy the XrSpatialSnapshotEXT handle and the resources associated with it.

Valid Usage (Implicit)

Thread Safety

  • Access to snapshot , and any child handles, must be externally synchronized

Return Codes

সাফল্য

  • XR_SUCCESS

ব্যর্থতা

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Common Components

Bounded 2D

Component data

The XrSpatialBounded2DDataEXT structure is defined as: 

typedef struct XrSpatialBounded2DDataEXT {
    XrPosef        center;
    XrExtent2Df    extents;
} XrSpatialBounded2DDataEXT;

Member Descriptions

  • center is an XrPosef defining the geometric center of the bounded 2D component.
  • extents is extents of the bounded 2D component along the x-axis (extents.width), y-axis (extents.height), centered on center .

The extents of the XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT refer to the entity's size in the xy plane of the plane's coordinate system. A plane with a position of {0, 0, 0}, rotation of {0, 0, 0, 1} (no rotation), and an extent of {1, 1} refers to a 1 meter x 1 meter plane centered at {0, 0, 0} with its front face normal vector pointing towards the +Z direction in the component's space.

XXYYZZ Height Height YYZZXX Vertical plane Vertical plane Horizontal Plane Horizontal Plane Width Width Width Width Height Height

Figure 24. Bounded2D Component Coordinate System

দ্রষ্টব্য

OpenXR uses an XY plane with +Z as the plane normal but other APIs may use an XZ plane with +Y as the plane normal. The XY plane can be converted to an XZ plane by rotating -π/2 radians around the +X axis.

Valid Usage (Implicit)

Component list structure to query data

The XrSpatialComponentBounded2DListEXT structure is defined as: 

typedef struct XrSpatialComponentBounded2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      boundCount;
    XrSpatialBounded2DDataEXT*    bounds;
} XrSpatialComponentBounded2DListEXT;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • boundCount is a uint32_t describing the count of elements in the bounds array.
  • bounds is an array of XrSpatialBounded2DDataEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentBounded2DListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if boundCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialDiscoverySnapshotCompleteEXT , then the runtime must provide XrSpatialBounded2DDataEXT :: center in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace and XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialUpdateSnapshotEXT , then the runtime must provide XrSpatialBounded2DDataEXT :: center in XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace and XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Valid Usage (Implicit)

কনফিগারেশন

If XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum value in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list. This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

Bounded 3D

Component data

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT uses XrBoxf for its data.

Component list structure to query data

The XrSpatialComponentBounded3DListEXT structure is defined as: 

typedef struct XrSpatialComponentBounded3DListEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           boundCount;
    XrBoxf*            bounds;
} XrSpatialComponentBounded3DListEXT;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • boundCount is a uint32_t describing the count of elements in the bounds array.
  • bounds is an array of XrBoxf .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentBounded3DListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if boundCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialDiscoverySnapshotCompleteEXT , then the runtime must provide XrBoxf :: center in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace at XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialUpdateSnapshotEXT , then the runtime must provide XrBoxf :: center in XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace at XrSpatialUpdateSnapshotCreateInfoEXT :: time .

Valid Usage (Implicit)

কনফিগারেশন

If XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list. This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

অভিভাবক

Component data

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT uses XrSpatialEntityIdEXT for its data.

Component list structure to query data

The XrSpatialComponentParentListEXT structure is defined as: 

typedef struct XrSpatialComponentParentListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 parentCount;
    XrSpatialEntityIdEXT*    parents;
} XrSpatialComponentParentListEXT;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • parentCount is a uint32_t describing the count of elements in the parents array.
  • parents is an array of XrSpatialEntityIdEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentParentListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if parentCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Valid Usage (Implicit)

  • The XR_EXT_spatial_entity extension must be enabled prior to using XrSpatialComponentParentListEXT
  • type must be XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
  • next must be NULL or a valid pointer to the next structure in a structure chain
  • parents must be a pointer to an array of parentCount XrSpatialEntityIdEXT values
  • The parentCount parameter must be greater than 0
কনফিগারেশন

If XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list. This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

Mesh 3D

Component data

The XrSpatialMeshDataEXT structure is defined as: 

typedef struct XrSpatialMeshDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
    XrSpatialBufferEXT    indexBuffer;
} XrSpatialMeshDataEXT;

Member Descriptions

  • origin is an XrPosef defining the origin of the mesh. All vertices of the mesh must be relative to this origin.
  • vertexBuffer is an XrSpatialBufferEXT that provides the ID for a buffer that represents the vertex buffer of the entity this component is on. The position of vertices must be relative to origin .
  • indexBuffer is an XrSpatialBufferEXT that provides the ID for a buffer that represents an array of triangle indices, specifying the indices of the mesh vertices in the vertexBuffer . The triangle indices must be returned in counter-clockwise order and three indices denote one triangle.

The component type using XrSpatialMeshDataEXT must specify the XrSpatialBufferTypeEXT of the vertexBuffer and indexBuffer .

Valid Usage (Implicit)

Component list structure to query data

The XrSpatialComponentMesh3DListEXT structure is defined as: 

typedef struct XrSpatialComponentMesh3DListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 meshCount;
    XrSpatialMeshDataEXT*    meshes;
} XrSpatialComponentMesh3DListEXT;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • meshCount is a uint32_t describing the count of elements in the meshes array.
  • meshes is an array of XrSpatialMeshDataEXT .

The application can query the mesh 3D component of the spatial entities in an XrSpatialSnapshotEXT by adding XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT in XrSpatialComponentDataQueryConditionEXT :: componentTypes and adding XrSpatialComponentMesh3DListEXT to the next pointer chain of XrSpatialComponentDataQueryResultEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentMesh3DListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if meshCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

For the XrSpatialMeshDataEXT filled out by the runtime in the meshes array, the XrSpatialBufferEXT :: bufferType for XrSpatialMeshDataEXT :: vertexBuffer must be XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT and XrSpatialBufferEXT :: bufferType for XrSpatialMeshDataEXT :: indexBuffer must be XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

Valid Usage (Implicit)

কনফিগারেশন

If XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list of the XrSpatialCapabilityConfigurationBaseHeaderEXT derived structure of the capability that supports this component.

This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

Tracking state filters

The XrSpatialFilterTrackingStateEXT structure is defined as: 

typedef struct XrSpatialFilterTrackingStateEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialEntityTrackingStateEXT    trackingState;
} XrSpatialFilterTrackingStateEXT;

Member Descriptions

The application can use XrSpatialFilterTrackingStateEXT in the next chain of XrSpatialDiscoverySnapshotCreateInfoEXT to scope the discovery to only those entities whose tracking state is trackingState .

The application can use XrSpatialFilterTrackingStateEXT in the next chain of XrSpatialComponentDataQueryConditionEXT to scope the component data query from a snapshot only to entities whose tracking state is trackingState .

Valid Usage (Implicit)

Example code

Application Usage

Applications typically use the spatial entity extension in the following pattern:

Discover spatial entities & query component data

The following example code demonstrates how to discover spatial entities for capability "Foo" query its component data. 

/****************************/
/* Capability definition    */
/****************************/
// Foo capability has the following components -
// - XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
#define XR_SPATIAL_CAPABILITY_FOO ((XrSpatialCapabilityEXT)1000740000U)

#define XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT ((XrStructureType)1000740000U)
// Derives from XrSpatialCapabilityConfigurationBaseHeaderEXT
typedef struct XrSpatialCapabilityConfigurationFooEXT {
  XrStructureType                     type;
  const void* XR_MAY_ALIAS            next;
  XrSpatialCapabilityEXT              capability;
  uint32_t                            enabledComponentCount;
  const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationFooEXT;

/******************************/
/* End capability definition  */
/******************************/

auto waitUntilReady = [](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  };

  // Configure Foo capability for the spatial context
  XrSpatialCapabilityConfigurationFooEXT fooConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT};
  fooConfig.capability = XR_SPATIAL_CAPABILITY_FOO;
  fooConfig.enabledComponentCount = enabledComponents.size();
  fooConfig.enabledComponents = enabledComponents.data();

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&fooConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components.
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT future = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT;
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = &componentToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    queryResult.entityIdCapacityInput = 0;
    queryResult.entityIds = nullptr;
    queryResult.entityStateCapacityInput = 0;
    queryResult.entityStates = nullptr;
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        // 2D extents for entity entityIds[i] is bounded2d[i].extents.
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // ...
  // Finish frame loop
  // ...
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Query buffer data

The following example code demonstrates how to get the data of a component that provides an XrSpatialBufferEXT . 

/****************************/
/* Component definition     */
/****************************/
// Foo component that provides an XrVector3f buffer
#define XR_SPATIAL_COMPONENT_TYPE_FOO_EXT ((XrSpatialComponentTypeEXT)1000740000U)

#define XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT ((XrStructureType)1000740000U)

// XrSpatialComponentFooListEXT extends XrSpatialComponentDataQueryResultEXT
typedef struct XrSpatialComponentFooListEXT {
    XrStructureType                   type;
    void* XR_MAY_ALIAS                next;
    uint32_t                          fooCount;
    XrSpatialBufferEXT*               foo;
} XrSpatialComponentFooListEXT;

/******************************/
/* End Component definition  */
/******************************/

// Query for the foo component data
XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_FOO_EXT;
XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypeCount = 1;
queryCond.componentTypes = &componentToQuery;

XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
queryResult.entityIdCapacityInput = entityIds.size();
queryResult.entityIds = entityIds.data();

std::vector<XrSpatialBufferEXT> fooBuffers(queryResult.entityIdCountOutput);
XrSpatialComponentFooListEXT fooList{XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT};
fooList.fooCount = fooBuffers.size();
fooList.foo = fooBuffers.data();
queryResult.next = &fooList;

CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // foo component data for entity entityIds[i]
  if (fooBuffers[i].bufferType == XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT) {
    XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
    getInfo.bufferId = fooBuffers[i].bufferId;
    uint32_t bufferCountOutput;
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, 0, &bufferCountOutput, nullptr));
    std::vector<XrVector3f> vertexBuffer(bufferCountOutput);
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, bufferCountOutput, &bufferCountOutput, vertexBuffer.data()));

    // XrVertex3f buffer for entity entityIds[i] is now available in vertexBuffer vector.
  }
}

Extension guidelines

  • If an extension is defining a new XrSpatialComponentTypeEXT which provides additional data about a spatial entity,

  • Extensions can define structures that extend XrSpatialDiscoverySnapshotCreateInfoEXT to provide additional filters for discovery. The filters for creating the snapshot must not affect the configuration of the spatial context, but instead are to be used to provide hints to the runtime on what entities and data are to be included in the snapshot as tracked by the current configuration of the spatial context (and therefore the current configuration of the underlying services).

  • If an extension defines a new XrSpatialCapabilityEXT ,

  • If an extension defines a new XrSpatialCapabilityFeatureEXT , it must also define a corresponding configuration structure that can be chained to the next pointer of XrSpatialCapabilityConfigurationBaseHeaderEXT , that the application can use to enable the feature when creating an XrSpatialContextEXT .

  • An extension defining a new XrSpatialCapabilityEXT should follow this template for the specification -

    • সংক্ষিপ্ত বিবরণ
    • Runtime support
    • কনফিগারেশন
    • Guaranteed components
    • Example Code

  • An extension defining a new XrSpatialComponentTypeEXT should follow this template for the specification -

    • Component data
    • Component list structure to query data
    • কনফিগারেশন

  • When writing an api that provides the application with a XrSpatialBufferIdEXT , it must be accompanied with a XrSpatialBufferTypeEXT to inform the application what the data type of the buffer is and the application can use an appropriate xrGetSpatialBuffer* function to retrieve the actual contents of the buffer.

Semantic Label Design & Extension Guidelines

While this extension does not define any component for conveying the semantic label information of an entity, it lays down the design rules and guidelines for any extensions that do define such a component. In the following text, " should " and " must " constrain the authors of such functionality, rather than constraining a runtime implementation or an application using the API.

  • If an extension is defining semantic labels for any XrSpatialCapabilityEXT , it should do so by defining a new XrSpatialComponentTypeEXT as well as a new enumeration with a set of labels (a "semantic label set") to be the data for that component.
  • An enumeration representing a semantic label set must have a value to indicate that the entity is not categorized into any of the labels of this set. The name of this enumerant must include 'UNCATEGORIZED', eg XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT . This value indicates to applications that the runtime does recognize this entity, but that there are other semantic label sets where this entity is categorized.
  • Enumeration of this newly defined XrSpatialComponentTypeEXT in xrEnumerateSpatialCapabilityComponentTypesEXT implies that the runtime supports the semantic label set (and therefore the labels defined in the set) corresponding to that component type.
  • Applications express their desire to discover entities that have labels belonging to this semantic label set by including the corresponding XrSpatialComponentTypeEXT in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents array of the configuration struct for the capability that the component type is enumerated for.
  • It is possible that a single spatial entity has multiple components on it, each providing it with a label from their own semantic label set. Consider the following example with some hypothetical semantic label sets - XrSpatialObjectSemanticLabel , which might have values like chair, sofa, table etc., XrSpatialSofaBrand , which might have values like IKEA, Wayfair, etc., and XrSpatialIkeaSofa , which might have specific IKEA model names of sofas. In this scenario, the same sofa entity has all 3 components (labels from all 3 semantic label sets) on it, each giving a different granularity of information about the entity.
  • If an extension is defining a new XrSpatialComponentTypeEXT which provides a new semantic label set containing multiple labels in addition to the UNCATEGORIZED label, the extension should consider defining an XrSpatialCapabilityFeatureEXT which allows applications to activate only a subset of the labels defined in the semantic label set corresponding to that component type. This subset, provided in the next chain of the capability configuration, acts as a hint for runtimes to optimize their tracking pipelines and only track the subset provided. An example of such a feature struct is provided below .
  • Extensions must not add labels to existing semantic label set enumeration. They must instead define a new enumeration which contains equivalent enumerants with identical semantics and with values equal to those from the other set, in addition to the newly added enumerants. The specification of the newly defined semantic label set must also establish the mapping between the old label set and the new one. See example below .
Example Spatial Feature Definition for Semantic Label Subset 
// New example semantic label set.
typedef enum XrSpatialExampleSemanticLabelEXT {
  // ... label values
} XrSpatialExampleSemanticLabelEXT;

/*
typedef enum XrSpatialCapabilityFeatureEXT {
  // .. existing values

  // new spatial feature value
  XR_SPATIAL_CAPABILITY_FEATURE_EXAMPLE_SEMANTIC_LABEL_SUBSET_EXT

  // .. existing values
} XrSpatialCapabilityFeatureEXT;
*/

// New spatial feaure configuration structure
typedef struct XrSpatialFeatureExampleSemanticLabelSubsetEXT {
    XrStructureType                             type;
    const void* XR_MAY_ALIAS                    next;
    uint32_t                                    semanticLabelCount;
    const XrSpatialExampleSemanticLabelEXT*     semanticLabels;
} XrSpatialFeatureExampleSemanticLabelSubsetEXT;
Example Spatial Semantic Label Extension 
typedef enum XrSpatialExamplePlaneSemanticLabelExtensionEXT {
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT = 2,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT = 3,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT = 4,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT = 5,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT = 6,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT = 7,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialExamplePlaneSemanticLabelExtensionEXT;

Consider the above example where an extension defines an enumeration XrSpatialExamplePlaneSemanticLabelExtensionEXT in order to extend the existing XrSpatialPlaneSemanticLabelEXT with values to represent doors and windows. The specification for the new enumeration must include text for the following form - 

For all non-UNCATEGORIZED label enumerants in elink:XrSpatialPlaneSemanticLabelEXT,
the runtime must: return that enumerant if and only if it returns the corresponding
label enumerant from elink:XrSpatialExamplePlaneSemanticLabelExtensionEXT with the same value
i.e.
the ename:XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT value for that entity must:
correspond with the ename:XR_SPATIAL_COMPONENT_TYPE_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_EXT values
according to the following table -

[width="100%",options="header"]
|====
| XrSpatialExamplePlaneSemanticLabelExtensionEXT                | XrSpatialPlaneSemanticLabelEXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT | XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT  | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
|====

New Macros

New Base Types

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

New Object Types

New Commands

New Structures

New Enums

New Enum Constants

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

  • Extending XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
    • XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
    • XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT

  • Extending XrResult :

    • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
    • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT

  • Extending XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT
    • XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
    • XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_FILTER_TRACKING_STATE_EXT
    • XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT

সমস্যা

  • Does a single entity always derive from solely a single capability?

    • Resolved
    • Answer: No. It is completely upto the runtime based on its own tracking capabilities and how it wants to represent a detected entity. The spec does not prescribe any particular representation of spatial entity except for the guaranteed components of a given capability to set a minimum expectation. A runtime may be able to merge entities detected by separate capabilities and represent them as a single entity with the guaranteed components of all the capabilities that helped identify it. An example of this could be that tables can be detected by both a plane tracking capability and an object tracking capability, with plane tracking providing the XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT component on the entity and object tracking providing XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT . A certain runtime may provide the table as 2 separate entities, each with their own set of guaranteed components, while certain runtimes may provide just 1 entity to represent the table, and have both XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT and XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT on the same entity. What is important to note here is that a given spatial entity can have at most a single component of any given component type . Therefore, if the component data produced by the different capabilities conflicts for a certain entity, the runtime must represent them as 2 separate entities.

সংস্করণ ইতিহাস

  • Revision 1, 2024-04-12 (Nihav Jain, Google)

    • Initial extension description