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 dilepaskan, 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 terperinci tentang mengambil ukuran trackableTypes yang diperlukan.

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

Penggunaan yang Valid (Implisit)

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

Aplikasi dapat melakukan raycast dengan memanggil xrRaycastANDROID.

Penggunaan yang Valid (Implisit)

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 akan 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.

Penggunaan yang Valid (Implisit)

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 terperinci tentang mengambil 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)

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.

Jenis hit yang dapat dilacak

Deskripsi

XR_TRACKABLE_TYPE_PLANE_ANDROID

Menampilkan permukaan horizontal dan/atau vertikal untuk menentukan kedalaman dan orientasi titik yang benar.

XR_TRACKABLE_TYPE_DEPTH_ANDROID

Menggunakan informasi kedalaman dari seluruh tampilan untuk menentukan kedalaman dan orientasi titik yang benar.

Penggunaan yang Valid (Implisit)

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

Fungsi Baru

Masalah

Histori Versi

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