Ekstensi OpenXR XR_ANDROID_raycast

String Nama

XR_ANDROID_raycast

Jenis Ekstensi

Ekstensi instance

Registered Extension Number

464

Revisi

1

Dependensi Ekstensi dan Versi

XR_ANDROID_trackables

Tanggal Terakhir Diubah

2024-10-02

Status IP

Tidak ada klaim IP yang diketahui.

Kontributor

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Ringkasan

Ekstensi ini memungkinkan aplikasi melakukan raycast terhadap objek yang dapat dilacak di lingkungan. Raycast dapat berguna untuk mendeteksi objek di lingkungan yang akan bersimpangan dengan sinar. Contoh:

• Untuk menentukan tempat objek mengambang akan jatuh saat dijatuhkan, dengan menggunakan raycast vertikal.
• Untuk menentukan tempat pengguna melihat, dengan menggunakan raycast yang menghadap ke depan.

Kemampuan raycast yang didukung kueri

Fungsi xrEnumerateRaycastSupportedTrackableTypesANDROID ditentukan sebagai:

XrResult xrEnumerateRaycastSupportedTrackableTypesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    trackableTypeCapacityInput,
    uint32_t*                                   trackableTypeCountOutput,
    XrTrackableTypeANDROID*                     trackableTypes);

Deskripsi Parameter

• instance adalah XrInstance tempat systemId diambil.
• systemId adalah XrSystemId yang jenis yang dapat dilacak dan didukung untuk raycasting sedang dihitung.
• trackableTypeCapacityInput adalah kapasitas trackableTypes, atau 0 untuk mengambil kapasitas yang diperlukan.
• trackableTypeCountOutput adalah pointer ke jumlah array, atau pointer ke kapasitas yang diperlukan jika trackableTypeCapacityInput tidak memadai.
  • trackableTypes adalah pointer ke array XrTrackableTypeANDROID, tetapi dapat berupa NULL jika trackableTypeCapacityInput adalah 0.
• Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi lengkap pengambilan ukuran trackableTypes yang diperlukan.

xrEnumerateRaycastSupportedTrackableTypesANDROID mengenumerasi jenis yang dapat dilacak yang mendukung raycasting oleh sesi saat ini.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_raycast harus diaktifkan sebelum memanggil xrEnumerateRaycastSupportedTrackableTypesANDROID
• instance harus berupa nama sebutan channel XrInstance yang valid
• trackableTypeCountOutput harus berupa pointer ke nilai uint32_t
• Jika trackableTypeCapacityInput bukan 0, trackableTypes harus berupa pointer ke array nilai trackableTypeCapacityInput XrTrackableTypeANDROID

Kode Status

Berhasil

• XR_SUCCESS

Kegagalan

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

Melakukan raycast

Fungsi xrRaycastANDROID ditentukan sebagai:

XrResult xrRaycastANDROID(
    XrSession                                   session,
    const XrRaycastInfoANDROID*                 rayInfo,
    XrRaycastHitResultsANDROID*                 results);

Deskripsi Parameter

• session adalah XrSession yang melakukan raycast.
• rayInfo adalah XrRaycastInfoANDROID yang menjelaskan sinar yang akan dipancarkan.
• results adalah pointer ke XrRaycastHitResultsANDROID yang menerima hasil raycast.

Aplikasi dapat melakukan raycast dengan memanggil xrRaycastANDROID.

• Jika raycast memotong lebih banyak objek yang dapat dilacak daripada XrRaycastHitResultsANDROID::maxResults, runtime harus menampilkan hasil hit yang paling dekat dengan XrRaycastHitResultsANDROID::origin sinar.
• Jika raycast memotong trackable dari jenis XR_TRACKABLE_TYPE_ANDROID_PLANE, yang digabungkan oleh bidang lain, runtime harus menampilkan hasil hit hanya untuk bidang yang digabungkan.
• Runtime harus menampilkan hasil hit dalam urutan terdekat ke terjauh dari XrRaycastInfoANDROID::origin di sepanjang vektor XrRaycastInfoANDROID::trajectory.
• Runtime harus menampilkan XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID jika jenis yang dapat dilacak yang sesuai dengan handle XrTrackableTrackerANDROID di XrRaycastInfoANDROID::trackers tidak dihitung oleh xrEnumerateRaycastSupportedTrackableTypesANDROID.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_raycast harus diaktifkan sebelum memanggil xrRaycastANDROID
• session harus berupa nama sebutan channel XrSession yang valid
• rayInfo harus berupa pointer ke struktur XrRaycastInfoANDROID yang valid
• results harus berupa pointer ke struktur XrRaycastHitResultsANDROID

Kode Status

Berhasil

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Kegagalan

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_TRACKABLE_TYPE_NOT_SUPPORTED_ANDROID
• XR_ERROR_VALIDATION_FAILURE
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_POSE_INVALID
• XR_ERROR_TIME_INVALID
• XR_ERROR_FEATURE_UNSUPPORTED

Struktur XrRaycastInfoANDROID ditentukan sebagai:

typedef struct XrRaycastInfoANDROID {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            maxResults;
    uint32_t                            trackerCount;
    const XrTrackableTrackerANDROID*    trackers;
    XrVector3f                          origin;
    XrVector3f                          trajectory;
    XrSpace                             space;
    XrTime                              time;
} XrRaycastInfoANDROID;

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur semacam itu yang ditentukan di OpenXR inti atau ekstensi ini.
• maxResults adalah jumlah maksimum hasil uint32_t yang akan ditampilkan.
• trackerCount adalah jumlah uint32_t dari array trackers.
• trackers adalah array XrTrackableTrackerANDROID yang digunakan untuk menguji sinar yang ditransmisikan harus.
• origin adalah XrVector3f tempat sinar dipancarkan.
• trajectory adalah XrVector3f yang ditargetkan oleh sinar.
• space adalah XrSpace tempat sinar dipancarkan.
• time adalah XrTime tempat sinar dipancarkan.

Struktur XrRaycastInfoANDROID menjelaskan sinar yang akan ditransmisikan.

• Array XrRaycastInfoANDROID::trackers dapat berisi pelacak dari berbagai jenis.
• Array XrRaycastInfoANDROID::trackers harus tidak berisi beberapa pelacak dari jenis yang sama. Jika tidak, runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_raycast harus diaktifkan sebelum menggunakan XrRaycastInfoANDROID
• type harus berupa XR_TYPE_RAYCAST_INFO_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• trackers harus berupa pointer ke array handle XrTrackableTrackerANDROID trackerCount yang valid
• space harus berupa nama sebutan XrSpace yang valid
• Parameter trackerCount harus lebih besar dari 0
• space dan elemen trackers harus telah dibuat, dialokasikan, atau diambil dari XrSession yang sama

Struktur XrRaycastHitResultsANDROID ditentukan sebagai:

typedef struct XrRaycastHitResultsANDROID {
    XrStructureType               type;
    void*                         next;
    uint32_t                      resultsCapacityInput;
    uint32_t                      resultsCountOutput;
    XrRaycastHitResultANDROID*    results;
} XrRaycastHitResultsANDROID;

Deskripsi Anggota

• type adalah XrStructureType dari struktur ini.
• next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur semacam itu yang ditentukan di OpenXR inti atau ekstensi ini.
• resultsCapacityInput adalah kapasitas array results, atau 0 untuk menunjukkan permintaan guna mengambil kapasitas yang diperlukan.
• resultsCountOutput adalah pointer ke jumlah results yang ditulis, atau pointer ke kapasitas yang diperlukan jika resultsCapacityInput tidak memadai.
• results adalah pointer ke array struktur XrRaycastHitResultANDROID. Nilainya dapat berupa NULL jika resultsCapacityInput adalah 0.
• Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi lengkap pengambilan ukuran results yang diperlukan.

XrRaycastHitResultsANDROID berisi array hit raycast.

Runtime harus menetapkan resultsCountOutput agar kurang dari atau sama dengan XrRaycastInfoANDROID::maxResults.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_raycast harus diaktifkan sebelum menggunakan XrRaycastHitResultsANDROID
• type harus berupa XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID
• next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
• results harus berupa pointer ke array struktur resultsCapacityInput berbasis XrRaycastHitResultANDROID
• Parameter resultsCapacityInput harus lebih besar dari 0

Struktur XrRaycastHitResultANDROID ditentukan sebagai:

typedef struct XrRaycastHitResultANDROID {
    XrTrackableTypeANDROID    type;
    XrTrackableANDROID        trackable;
    XrPosef                   pose;
} XrRaycastHitResultANDROID;

Deskripsi Anggota

• type adalah XrTrackableTypeANDROID dari trackable yang dihit raycast.
• trackable adalah XrTrackableANDROID yang terkena raycast, atau XR_NULL_TRACKABLE_ANDROID jika type yang dapat dilacak adalah XR_TRACKABLE_TYPE_DEPTH_ANDROID.
• pose adalah XrPosef yang dihit raycast.

XrRaycastHitResultANDROID berisi detail hit raycast.

XrRaycastHitResultANDROID::pose untuk hit bidang harus sedemikian rupa sehingga X dan Z sejajar dengan bidang, dan sumbu Y normal terhadap bidang.

Penggunaan yang Valid (Implisit)

• Ekstensi XR_ANDROID_raycast harus diaktifkan sebelum menggunakan XrRaycastHitResultANDROID
• type harus berupa nilai XrTrackableTypeANDROID yang valid

Contoh kode untuk raycasting

Contoh kode berikut menunjukkan cara melakukan raycast.

XrSession session; // previously initialized
XrTime updateTime; // previously initialized
XrSpace appSpace;  // space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
XrPosef headPose;  // latest pose of the HMD.
XrTrackableTrackerANDROID planeTracker; // tracker for plane trackables.
XrTrackableTrackerANDROID depthTracker; // tracker for depth trackables.

// Perform a raycast against multiple trackers.
XrTrackableTrackerANDROID trackers[] = {
  &planeTracker,
  &depthTracker,
};
XrRaycastInfoANDROID rayInfo = {XR_TYPE_RAYCAST_INFO_ANDROID};
rayInfo.trackerCount = sizeof(trackers) / sizeof(XrTrackableTrackerANDROID);
rayInfo.trackers = trackers;
rayInfo.origin = headPose.position;
rayInfo.trajectory = CalculateForwardDirectionFromHeadPose(headPose);
rayInfo.space = appSpace;
rayInfo.time = updateTime;

uint32_t totalHitResults = 0;
constexpr uint32 NUM_DESIRED_RESULTS = 2;
XrRaycastHitResultANDROID hitResult[NUM_DESIRED_RESULTS];
XrRaycastHitResultsANDROID hitResults = {XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID};
hitResults.maxResults = NUM_DESIRED_RESULTS;
hitResults.resultsCapacityInput = NUM_DESIRED_RESULTS;
hitResults.results = hitResult;
XrResult result = xrRaycastANDROID(session, &rayInfo, &hitResults);

if (result == XR_SUCCESS && hitResults.resultsCountOutput >= 1) {
  // Hit results are returned in closest-to-farthest order in
  // hitResults.results[0] .. hitResults.results[hitResults.resultsCountOutput - 1]
}

Konstanta Enum Baru

Enumerasi XrStructureType diperluas dengan:

• XR_TYPE_RAYCAST_INFO_ANDROID
• XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID

Struktur Baru

• XrRaycastInfoANDROID
• XrRaycastHitResultANDROID
• XrRaycastHitResultsANDROID

Fungsi Baru

• xrEnumerateRaycastSupportedTrackableTypesANDROID
• xrRaycastANDROID

Masalah

Histori Versi

• Revisi 1, 02-10-2024 (Kenny Vercaemer)
  • Deskripsi ekstensi awal

OpenXR™ dan logo OpenXR adalah merek dagang yang dimiliki oleh The Khronos Group Inc. dan terdaftar sebagai merek dagang di China, Uni Eropa, Jepang, dan Inggris Raya.