XR_ANDROID_raycast OpenXR uzantısı

Ad dizesi

XR_ANDROID_raycast

Uzantı Türü

Örnek uzatma

Kayıtlı Uzatma Numarası

464

Düzeltme

1

Uzantı ve Sürüm Bağımlılıkları

XR_ANDROID_trackables

Son Değiştirilme Tarihi

2024-10-02

IP Durumu

Bilinen IP hak talepleri yok.

Katkıda bulunanlar

Spencer Quin, Google

Nihav Jain, Google

John Pursey, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Genel Bakış

Bu uzantı, uygulamanın ortamdaki izlenebilirlere karşı ışın izleme gerçekleştirmesine olanak tanır. Işın izleme, ortamdaki bir ışının kesişeceği nesneleri algılamak için yararlı olabilir. Örnek:

  • Dikey bir ışın atışı kullanarak, yüzen bir nesnenin yere bırakıldığında nereye düşeceğini belirlemek için kullanılır.
  • Kullanıcının nereye baktığını belirlemek için ileriye dönük bir ışın ışını kullanarak.

Desteklenen ışın izleme özelliklerini sorgulayın

xrEnumerateRaycastSupportedTrackableTypesANDROID işlevi şu şekilde tanımlanır:

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

Parametre Açıklamaları

  • instance, systemId'ın alındığı XrInstance'tır.
  • systemId, ışın izleme için desteklenen izlenebilir türlerinin listelendiği XrSystemId bağımsız değişkenidir.
  • trackableTypeCapacityInput, trackableTypes öğesinin kapasitesidir veya gerekli kapasiteyi almak için 0 değerini alır.
  • trackableTypeCountOutput, dizinin sayısının işaretçisidir veya trackableTypeCapacityInput yetersiz olduğunda gerekli kapasitenin işaretçisidir.
    • trackableTypes, XrTrackableTypeANDROID dizisinin işaretçisidir ancak trackableTypeCapacityInput 0 ise NULL olabilir.
  • Gerekli trackableTypes boyutunu almayla ilgili ayrıntılı açıklama için Arabellek Boyutu Parametreleri bölümüne bakın.

xrEnumerateRaycastSupportedTrackableTypesANDROID, mevcut oturum tarafından ışın izlemeyi destekleyen izlenebilir türleri listeler.

Geçerli Kullanım (Dolayı)

İade Kodları

Başarılı

  • XR_SUCCESS

Hata

  • 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

Işın izleme gerçekleştirme

xrRaycastANDROID işlevi şu şekilde tanımlanır:

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

Parametre Açıklamaları

Uygulama, xrRaycastANDROID'ı çağırarak ışın izleme işlemi yapabilir.

Geçerli Kullanım (Dolayı)

İade Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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

XrRaycastInfoANDROID yapısı şu şekilde tanımlanır: 

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;

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.
  • maxResults, döndürülecek maksimum sonuç sayısıdır (uint32_t).
  • trackerCount, trackers dizisinin uint32_t sayısıdır.
  • trackers, yayınlanan ışının test edilmesi gereken XrTrackableTrackerANDROID dizisidir.
  • origin, ışının gönderildiği XrVector3f bağımsız değişkenidir.
  • trajectory, ışının hedeflediği XrVector3f öğesidir.
  • space, ışının gönderildiği XrSpace'tir.
  • time, ışının gönderildiği XrTime öğesidir.

XrRaycastInfoANDROID yapısı, gönderilecek ışını tanımlar.

Geçerli Kullanım (Dolayı)

  • XrRaycastInfoANDROID'ı kullanmadan önce XR_ANDROID_raycast uzantısı etkinleştirilmelidir.
  • type XR_TYPE_RAYCAST_INFO_ANDROID olmalıdır
  • next NULL veya yapı zincirindeki sonraki yapıya işaret eden geçerli bir işaretçi olmalıdır.
  • trackers olmalıdır trackerCount geçerli XrTrackableTrackerANDROID mülklerinin dizisine işaret eden bir işaretçi
  • space geçerli bir XrSpace herkese açık kullanıcı adı olmalıdır.
  • trackerCount parametresi 0 değerinden büyük olmalıdır.
  • Hem space hem de trackers öğeleri aynı XrSession'de oluşturulmuş, ayrılmış veya alınmış olmalıdır.

XrRaycastHitResultsANDROID yapısı şu şekilde tanımlanır: 

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.
  • resultsCapacityInput, results dizisinin kapasitesidir veya gerekli kapasiteyi alma isteğini belirtmek için 0 değerini alır.
  • resultsCountOutput, yazılan results sayısının işaretçisidir veya resultsCapacityInput yetersiz olduğunda gereken kapasitenin işaretçisidir.
  • results, XrRaycastHitResultANDROID yapılarının dizisine işaret eden bir işaretçidir. resultsCapacityInput 0 ise NULL olabilir.
  • Gerekli results boyutunu almayla ilgili ayrıntılı açıklama için Arabellek Boyutu Parametreleri bölümüne bakın.

XrRaycastHitResultsANDROID, bir ışın izlemenin isabet dizisini içerir.

Çalışma zamanı, resultsCountOutput değerini XrRaycastInfoANDROID::maxResults değerinden küçük veya bu değere eşit olacak şekilde ayarlamalıdır.

Geçerli Kullanım (Dolayı)

XrRaycastHitResultANDROID yapısı şu şekilde tanımlanır: 

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

Üye Açıklamaları

  • type, ışın izlemenin isabet ettiği izlenebilir öğenin XrTrackableTypeANDROID değeridir.
  • trackable, ışın izlemenin isabet ettiği XrTrackableANDROID veya izlenebilir type XR_NULL_TRACKABLE_ANDROID ise XR_TRACKABLE_TYPE_DEPTH_ANDROID olur.
  • pose, ışın izlemenin isabet ettiği XrPosef'tir.

XrRaycastHitResultANDROID, bir ışın izleme isabetinin ayrıntılarını içerir.

Bir düzlem isabeti için XrRaycastHitResultANDROID::pose, X ve Z'nin düzleme paralel, Y ekseninin ise düzleme normal olacak şekilde olmalıdır.

İzlenebilir isabet türü

Açıklama

XR_TRACKABLE_TYPE_PLANE_ANDROID

Bir noktanın doğru derinliğini ve yönünü belirlemek için yatay ve/veya dikey yüzeylere çarpar.

XR_TRACKABLE_TYPE_DEPTH_ANDROID

Bir noktanın doğru derinliğini ve yönünü belirlemek için sahnenin tamamındaki derinlik bilgilerini kullanır.

Geçerli Kullanım (Dolayı)

Işın izleme için örnek kod

Aşağıdaki örnek kodda, ışın izlemenin nasıl yapılacağı gösterilmektedir.

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]
}

Yeni Enum Constants

XrStructureType dizini aşağıdakilerle genişletildi:

  • XR_TYPE_RAYCAST_INFO_ANDROID
  • XR_TYPE_RAYCAST_HIT_RESULTS_ANDROID

Yeni Yapılar

Yeni İşlevler

Sorunlar

Sürüm Geçmişi

  • Düzeltme 1, 02.10.2024 (Kenny Vercaemer)
    • İlk uzantı açıklaması