XR_KHR_extended_struct_name_lengths

Name String

XR_KHR_extended_struct_name_lengths

Extension Type

ส่วนขยายอินสแตนซ์

Registered Extension Number

149

Revision

2

Ratification Status

ได้รับการอนุมัติ

Extension and Version Dependencies

OpenXR 1.0

Last Modified Date

2025-12-04

IP Status

ไม่มีการอ้างสิทธิ์ IP ที่ทราบ

Contributors

Matthew Langille, Meta Platforms
Andreas Selvik, Meta Platforms
Rylie Pavlik, Collabora, Ltd.

ภาพรวม

ส่วนขยายนี้จะขยายขนาดชื่อ struct สูงสุดและมีฟังก์ชันใหม่สำหรับการเข้าถึงชื่อที่ขยายใหม่เหล่านี้

xrStructureTypeToString2KHR มีไว้เพื่อให้ดึงข้อมูลชื่อสตริงของตัวแจงนับประเภทโครงสร้างที่มีความยาวเกินขีดจำกัดเดิมที่ 63 ไบต์ (64 ไบต์รวมตัวสิ้นสุด null) ได้ โดย xrStructureTypeToString2KHR จะแสดงผลสตริงชื่อสำหรับตัวแจงนับประเภทโครงสร้างที่มีความยาวสูงสุด 255 ไบต์ (256 ไบต์รวมตัวสิ้นสุด null) แอปพลิเคชัน สามารถ ใช้ 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 ที่ถูกต้องซึ่งสิ้นสุดด้วย null ลงใน buffer

ในทุกกรณี สตริงที่แสดงผลต้อง เป็นหนึ่งในสตริงต่อไปนี้

ค่าเอาต์พุตสตริงประเภทโครงสร้าง

  • สตริงตัวอักษรที่กำหนดไว้สำหรับค่าตัวเลขที่ระบุในข้อกำหนดหลักหรือส่วนขยาย (เช่น ค่า XR_TYPE_INSTANCE_CREATE_INFO จะแสดงผลสตริง XR_TYPE_INSTANCE_CREATE_INFO)
  • XR_UNKNOWN_STRUCTURE_TYPE_ ต่อท้ายด้วยหมายเลขประเภทโครงสร้างที่แสดงเป็นเลขฐานสิบ

สำหรับตัวแจงนับประเภทโครงสร้างที่มีชื่อพอดีกับขีดจำกัดขนาดเดิมที่ 63 ไบต์ xrStructureTypeToString2KHR ต้อง แสดงผลสตริงผลลัพธ์เดียวกันกับ xrStructureTypeToString จนถึงตัวสิ้นสุด null

การใช้งานที่ถูกต้อง (โดยนัย)

  • ต้องเปิดใช้ส่วนขยาย 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

คำสั่งใหม่

ค่าคงที่ Enum ใหม่

  • XR_KHR_EXTENDED_STRUCT_NAME_LENGTHS_EXTENSION_NAME
  • XR_KHR_extended_struct_name_lengths_SPEC_VERSION
  • XR_MAX_STRUCTURE_NAME_SIZE_EXTENDED_KHR

ประวัติเวอร์ชัน

  • การแก้ไข 1, 2024-02-29 (Matthew Langille)

    • คำอธิบายส่วนขยายเริ่มต้น

  • การแก้ไข 2, 2025-12-04 (Kenny Vercaemer)

    • แก้ไขข้อกำหนดความยาวชื่อโครงสร้าง