XR_KHR_extended_struct_name_lengths

سلسلة الاسم

XR_KHR_extended_struct_name_lengths

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

149

المراجعة

2

حالة التصديق

تم التصديق عليه

الاعتماديات على الإضافات والإصدارات

OpenXR 1.0

تاريخ آخر تعديل

2025-12-04

حالة عنوان IP

ما مِن مطالبات معروفة بملكية الملكية الفكرية.

المساهمون

Matthew Langille، شركة Meta Platforms
Andreas Selvik، شركة Meta Platforms
Rylie Pavlik، شركة Collabora, Ltd.

نظرة عامة

تزيد هذه الإضافة من الحد الأقصى لحجم أسماء البُنى وتوفّر دالة جديدة للوصول إلى هذه الأسماء الموسّعة الجديدة.

يتم توفير xrStructureTypeToString2KHR للسماح باسترداد أسماء السلاسل الخاصة بأنواع العناصر المُعدَّدة ذات الأطوال التي تتجاوز الحد الأصلي البالغ 63 بايت (64 بايت بما في ذلك حرف إنهاء السلسلة الفارغ). تعرض الدالة xrStructureTypeToString2KHR سلاسل الأسماء الخاصة بأنواع العناصر المُعدَّدة التي يصل طولها إلى 255 بايت (256 بايت بما في ذلك حرف إنهاء السلسلة الفارغ). يمكن للتطبيق استخدام xrStructureTypeToString2KHR كبديل مباشر لـ xrStructureTypeToString، لأنّه يعمل مع جميع أنواع التعدادات، بغض النظر عن طول اسم السلسلة.

استرداد سلاسل تعداد أنواع البنية

في حال استخدام xrStructureTypeToString الأصلي لاسترداد أسماء السلاسل لأنواع البنية التي تتضمّن تعدادات تتجاوز أطوال أسمائها 63 بايت، يتم توضيح سلوكها على النحو التالي. يجب أن تعمل الدالة xrStructureTypeToString على ملء المخزن المؤقت بالاسم الصحيح، باستثناء أنّه يجب اقتطاع السلسلة عند حدود نقطة الرمز لتناسب المخزن المؤقت المتاح. أي أنّ السلسلة المعروضة يجب أن تكون دائمًا بتنسيق UTF-8 صالح.

يتم تعريف الدالة xrStructureTypeToString2KHR على النحو التالي:

XrResult xrStructureTypeToString2KHR(
    XrInstance                                  instance,
    XrStructureType                             value,
    char                                        buffer[XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR]);

أوصاف المَعلمات

  • ‫instance هو معرّف المثيل الذي سيتم طلب السلسلة منه.
  • ‫value هي قيمة XrStructureType المطلوب تحويلها إلى سلسلة.
  • ‫buffer هو المخزن المؤقت الذي سيتم استخدامه لعرض السلسلة.

تعرض هذه الدالة اسم قيمة XrStructureType المقدَّمة من خلال نسخ سلسلة UTF-8 صالحة تنتهي بقيمة فارغة إلى buffer .

في جميع الحالات، يجب أن تكون السلسلة المعروضة إحدى القيم التالية:

قيم الناتج من السلسلة لنوع البنية

  • السلسلة الحرفية المحدّدة للقيمة الرقمية المقدَّمة في المواصفات الأساسية أو الإضافة (على سبيل المثال، تؤدي قيمة XR_TYPE_INSTANCE_CREATE_INFO إلى السلسلة XR_TYPE_INSTANCE_CREATE_INFO )
  • XR_UNKNOWN_STRUCTURE_TYPE_ مدمجة مع رقم نوع البنية معبّرًا عنه كرقم عشري

بالنسبة إلى تعدادات أنواع البنية التي تتناسب أسماؤها مع الحدّ الأقصى الأصلي للحجم البالغ 63 بايت، xrStructureTypeToString2KHR يجب أن تعرض السلسلة الناتجة نفسها مثل xrStructureTypeToString، حتى نهاية السلسلة الفارغة.

الاستخدام الصحيح (الضمني)

  • يجب تفعيل الإضافة XR_KHR_extended_struct_name_lengths قبل استدعاء xrStructureTypeToString2KHR
  • يجب أن يكون instance مقبض XrInstance صالحًا
  • يجب أن تكون قيمة value صالحة من XrStructureType
  • يجب أن يكون buffer مصفوفة أحرف بطول XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS

تعذُّر

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_VALIDATION_FAILURE

يحدّد العنصر XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR تعداد حجم المخزن المؤقت الذي تم تمريره إلى xrStructureTypeToString2KHR .

#define XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR 256

الأوامر الجديدة

ثوابت التعداد الجديدة

  • XR_KHR_EXTENDED_STRUCT_NAME_LENGTHS_EXTENSION_NAME
  • XR_KHR_extended_struct_name_lengths_SPEC_VERSION
  • XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR

سجلّ التعديلات

  • التعديل 1، ‎29-02-2024 (ماثيو لانغيلي)

    • الوصف الأوّلي للإضافة

  • Revision 2, 2025-12-04 (Kenny Vercaemer)

    • إصلاح مواصفات طول اسم البنية