طول_نام_ساختار_گسترده_XR_KHR

رشته نام

XR_KHR_extended_struct_name_lengths

نوع افزونه

افزونه نمونه

شماره داخلی ثبت شده

۱۴۹

بازنگری

۲

وضعیت تصویب

تصویب شده

وابستگی‌های افزونه و نسخه

اوپن‌ایکس‌آر ۱.۰

آخرین تاریخ اصلاح

۲۰۲۵-۱۲-۰۴

وضعیت آی‌پی

هیچ ادعای مالکیت معنوی شناخته‌شده‌ای وجود ندارد.

مشارکت‌کنندگان

متیو لانگیل، متا پلتفرمز
آندریاس سلویک، متا پلتفرم
رایلی پاولیک، شرکت کولابورا

نمای کلی

این افزونه حداکثر اندازه نام ساختار را افزایش می‌دهد و تابع جدیدی برای دسترسی به این نام‌های توسعه‌یافته جدید ارائه می‌دهد.

xrStructureTypeToString2KHR برای بازیابی نام‌های رشته‌ای شمارشگرهای نوع ساختار با طول‌هایی که از حد اولیه ۶۳ بایت (۶۴ بایت شامل پایانه تهی) بیشتر هستند، ارائه شده است. xrStructureTypeToString2KHR رشته‌های نام را برای شمارشگرهای نوع ساختار تا طول ۲۵۵ بایت (۲۵۶ بایت شامل پایانه تهی) برمی‌گرداند. یک برنامه می‌تواند از xrStructureTypeToString2KHR به عنوان جایگزینی برای xrStructureTypeToString استفاده کند، زیرا با تمام شمارشگرهای نوع ساختار، صرف نظر از طول نام رشته، کار می‌کند.

بازیابی رشته‌های شمارشی از نوع ساختار

اگر xrStructureTypeToString اصلی برای بازیابی نام‌های رشته‌ای برای شمارشگرهای نوع ساختار با طول نام بیش از ۶۳ بایت استفاده شود، رفتار آن به شرح زیر توضیح داده می‌شود. xrStructureTypeToString باید بافر را با نام صحیح پر کند، با این تفاوت که رشته باید در مرز یک نقطه کد کوتاه شود تا در بافر موجود جا شود. یعنی، رشته برگردانده شده باید همیشه UTF-8 معتبر باشد.

تابع xrStructureTypeToString2KHR به صورت زیر تعریف می‌شود:

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

توضیحات پارامتر

  • instance هندل (handle) نمونه‌ای است که قرار است رشته را درخواست کند.
  • value مقدار XrStructureType است که قرار است به یک رشته تبدیل شود.
  • buffer بافری است که برای برگرداندن رشته استفاده خواهد شد.

با کپی کردن یک رشته معتبر UTF-8 با انتهای تهی در buffer ، نام مقدار XrStructureType ارائه شده را برمی‌گرداند.

در همه موارد، رشته برگردانده شده باید یکی از موارد زیر باشد:

نوع ساختار رشته مقادیر خروجی

  • رشته‌ی تحت‌اللفظی تعریف‌شده برای مقدار عددی ارائه‌شده در مشخصات اصلی یا افزونه. (مثلاً مقدار XR_TYPE_INSTANCE_CREATE_INFO منجر به رشته‌ی XR_TYPE_INSTANCE_CREATE_INFO می‌شود.)
  • XR_UNKNOWN_STRUCTURE_TYPE_ به همراه شماره نوع ساختار که به صورت یک عدد اعشاری بیان می‌شود، الحاق شده است.

برای شمارشگرهای نوع ساختار که نام آنها در محدوده اندازه اصلی ۶۳ بایت قرار می‌گیرد، 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

تاریخچه نسخه

  • نسخه ۱، ۲۰۲۴-۰۲-۲۹ (متیو لانگیل)

    • توضیحات اولیه افزونه

  • نسخه ۲، ۲۰۲۵-۱۲-۰۴ (کنی ورکامر)

    • اصلاح مشخصات طول نام ساختار