XR_ANDROID_device_anchor_persistence OpenXR 확장 프로그램

이름 문자열

XR_ANDROID_device_anchor_persistence

확장 프로그램 유형

인스턴스 연장

등록된 부속 번호

458

버전

1

확장 프로그램 및 버전 종속 항목

XR_EXT_uuid와(과) XR_ANDROID_trackables

최종 수정일

2024-10-10

IP 상태

알려진 IP 소유권 주장이 없습니다.

도움을 주신 분들

니하브 자인, Google

레바나 첸, Google

스펜서 퀸, Google

케니 베르카머, Google

개요

이 확장 프로그램을 사용하면 애플리케이션이 애플리케이션과 기기 세션 전반에서 현재 사용자의 현재 기기에 있는 앵커를 유지, 검색, 유지 해제할 수 있습니다.

시스템 기능 검사

XrSystemDeviceAnchorPersistencePropertiesANDROID 구조는 다음과 같이 정의됩니다.

typedef struct XrSystemDeviceAnchorPersistencePropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsAnchorPersistence;
} XrSystemDeviceAnchorPersistencePropertiesANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • nextNULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • supportsAnchorPersistence는 현재 시스템이 공간 앵커의 앵커 지속성을 지원하는지 나타내는 XrBool32입니다.

애플리케이션은 xrGetSystemProperties를 호출할 때 XrSystemPropertiesXrSystemDeviceAnchorPersistencePropertiesANDROID 구조로 확장하여 시스템이 공간 앵커를 유지할 수 있는지 검사 (xrCreateAnchorSpaceANDROID 참고) 할 수 있습니다. 지원되는 추적 가능한 앵커의 경우 애플리케이션은 xrEnumerateSupportedPersistenceAnchorTypesANDROID를 사용하여 지원되는 유형을 쿼리할 수 있습니다.

supportsAnchorPersistenceXR_FALSE이 반환되면 공간 앵커에서 작동하는 기기 앵커 지속성 함수에서 XR_ERROR_FEATURE_UNSUPPORTED이 반환됩니다.

유효한 사용 (암시적)

xrEnumerateSupportedPersistenceAnchorTypesANDROID 함수는 다음과 같이 정의됩니다.

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

매개변수 설명

  • sessionXrDeviceAnchorPersistenceANDROID를 만드는 XrSession입니다.
  • trackableTypeCapacityInputtrackableTypes의 용량 또는 필요한 용량을 검색하기 위한 0입니다.
  • trackableTypeCountOutput는 배열의 개수에 대한 포인터이거나 trackableTypeCapacityInput가 충분하지 않은 경우 필요한 용량에 대한 포인터입니다.
  • trackableTypesXrTrackableTypeANDROID 배열에 대한 포인터이지만 trackableTypeCapacityInput0인 경우 NULL 있습니다.
  • 필요한 trackableTypes 크기를 검색하는 방법에 관한 자세한 내용은 버퍼 크기 매개변수 섹션을 참고하세요.

애플리케이션은 xrEnumerateSupportedPersistenceAnchorTypesANDROID를 사용하여 다른 XrTrackableTypeANDROID 추적 가능한 항목에서 앵커 지속성 지원을 확인할 수 있습니다.

지정된 XrTrackableTypeANDROIDtrackableTypes 배열에서 반환되지 않으면 해당 유형의 앵커에서 작동하는 기기 앵커 지속성 함수에서 XR_ERROR_FEATURE_UNSUPPORTED이 반환됩니다.

유효한 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS

실패

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

기기 앵커 지속성 핸들 만들기

XrDeviceAnchorPersistenceANDROID는 영구 앵커를 유지하고 추적하는 데 필요한 리소스를 나타내는 핸들입니다.

XR_DEFINE_HANDLE(XrDeviceAnchorPersistenceANDROID)

xrCreateDeviceAnchorPersistenceANDROID 함수는 다음과 같이 정의됩니다.

XrResult xrCreateDeviceAnchorPersistenceANDROID(
    XrSession                                   session,
    const XrDeviceAnchorPersistenceCreateInfoANDROID* createInfo,
    XrDeviceAnchorPersistenceANDROID*           outHandle);

매개변수 설명

애플리케이션은 xrCreateDeviceAnchorPersistenceANDROID를 호출하여 XrDeviceAnchorPersistenceANDROID 핸들을 만들 수 있습니다(있음). XrDeviceAnchorPersistenceANDROID는 후속 API 호출에서 앵커를 유지하거나 유지 해제하는 데 사용할 수 있습니다. XrDeviceAnchorPersistenceANDROID 핸들은 결국 xrDestroyDeviceAnchorPersistenceANDROID 함수를 사용하여 해제해야 합니다.

유효한 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • 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

XrDeviceAnchorPersistenceCreateInfoANDROID 구조는 다음과 같이 정의됩니다.

typedef struct XrDeviceAnchorPersistenceCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrDeviceAnchorPersistenceCreateInfoANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • nextNULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.

XrDeviceAnchorPersistenceCreateInfoANDROID 구조체는 xrCreateDeviceAnchorPersistenceANDROID에 전달될 때 XrDeviceAnchorPersistenceANDROID의 생성 옵션을 제공합니다.

유효한 사용 (암시적)

xrDestroyDeviceAnchorPersistenceANDROID 함수는 다음과 같이 정의됩니다.

XrResult xrDestroyDeviceAnchorPersistenceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle);

매개변수 설명

xrDestroyDeviceAnchorPersistenceANDROID 함수는 기기 앵커 지속성 핸들을 소멸합니다.

유효한 사용 (암시적)

스레드 안전

  • handle 및 모든 하위 핸들에 대한 액세스는 외부에서 동기화해야

반품 코드

성공

  • XR_SUCCESS

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

앵커 유지

xrPersistAnchorANDROID 함수는 다음과 같이 정의됩니다.

XrResult xrPersistAnchorANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrPersistedAnchorSpaceInfoANDROID*    persistedInfo,
    XrUuidEXT*                                  anchorIdOutput);

매개변수 설명

애플리케이션은 xrPersistAnchorANDROID를 호출하여 앵커가 유지되도록 요청할 있습니다. 애플리케이션은 성공 반환 값이 앵커가 즉시 유지된다는 것을 의미한다고 가정해서는 안 됩니다. 애플리케이션은 반환된 앵커 XrUuidEXT를 사용하여 앵커의 지속 상태를 확인하기 위해 xrGetAnchorPersistStateANDROID사용해야 합니다. 애플리케이션은 xrUnpersistAnchorANDROID를 사용하여 앵커의 지속성을 해제할 있습니다.

  • 호출 시 앵커가 추적되지 않으면 XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID이 반환됩니다.
  • 앵커가 지속성을 위해 대기열에 추가되면 XR_SUCCESS이 반환됩니다.

유효한 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • 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

XrPersistedAnchorSpaceInfoANDROID 구조는 다음과 같이 정의됩니다.

typedef struct XrPersistedAnchorSpaceInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrSpace            anchor;
} XrPersistedAnchorSpaceInfoANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • nextNULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • anchor는 이전에 xrCreateAnchorSpaceANDROID로 만들어 지속되는 앵커 XrSpace입니다.

유효한 사용 (암시적)

xrGetAnchorPersistStateANDROID 함수는 다음과 같이 정의됩니다.

XrResult xrGetAnchorPersistStateANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrUuidEXT*                            anchorId,
    XrAnchorPersistStateANDROID*                persistState);

매개변수 설명

  • handleXrDeviceAnchorPersistenceANDROID입니다.
  • anchorId는 앵커의 XrUuidEXT입니다.
  • persistState는 앵커의 상태가 반환되는 XrAnchorPersistStateANDROID에 대한 포인터입니다.
  • 앵커 XrUuidEXT를 찾을 수 없는 경우 XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID이 반환됩니다.
  • anchorId의 영구 저장 데이터가 준비되지 않은 경우 XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID이 반환됩니다.

유효한 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID

XrAnchorPersistStateANDROID enum은 다음과 같이 정의됩니다.

typedef enum XrAnchorPersistStateANDROID {
    XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID = 0,
    XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID = 1,
    XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID = 2
} XrAnchorPersistStateANDROID;

enum

설명

XR_ANCHOR_PERSIST_STATE_PERSIST_NOT_REQUESTED_ANDROID

앱에서 고정되도록 요청된 앵커가 없습니다.

XR_ANCHOR_PERSIST_STATE_PERSIST_PENDING_ANDROID

고정된 상태로 유지하도록 요청되었지만 아직 유지되지 않았습니다.

XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID

런타임에서 앵커를 성공적으로 유지했습니다.

영구 저장된 데이터에서 앵커 만들기

xrCreatePersistedAnchorSpaceANDROID 함수는 다음과 같이 정의됩니다.

XrResult xrCreatePersistedAnchorSpaceANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrPersistedAnchorSpaceCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorOutput);

매개변수 설명

애플리케이션은 동일한 XrUuidEXT를 사용하여 xrCreatePersistedAnchorSpaceANDROID를 호출하여 이전에 저장된 앵커에서 XrSpace 앵커를 만들 수 있습니다. 이는 XR_ANDROID_trackables에 정의된 앵커를 만드는 또 다른 방법입니다.

  • 앵커 XrUuidEXT를 찾을 수 없는 경우 XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID이 반환됩니다.

유효한 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • 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_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

XrPersistedAnchorSpaceCreateInfoANDROID 구조는 다음과 같이 정의됩니다.

typedef struct XrPersistedAnchorSpaceCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrUuidEXT          anchorId;
} XrPersistedAnchorSpaceCreateInfoANDROID;

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • nextNULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • anchorId는 앵커 XrSpace를 만드는 데 사용할 영구 앵커의 XrUuidEXT입니다.

XrPersistedAnchorSpaceCreateInfoANDROID 구조는 xrCreateDeviceAnchorPersistenceANDROID에 전달될 때 앵커의 생성 옵션을 제공합니다.

유효한 사용 (암시적)

유지된 앵커 열거

xrEnumeratePersistedAnchorsANDROID 함수는 다음과 같이 정의됩니다.

XrResult xrEnumeratePersistedAnchorsANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    uint32_t                                    anchorIdsCapacityInput,
    uint32_t*                                   anchorIdsCountOutput,
    XrUuidEXT*                                  anchorIds);

매개변수 설명

  • handleXrDeviceAnchorPersistenceANDROID입니다.
  • anchorIdsCapacityInputanchorIds 배열의 용량 또는 0으로, 필요한 용량을 검색하라는 요청을 나타냅니다.
  • anchorIdsCountOutput는 작성된 anchorIds 개수의 포인터이거나 anchorIdsCapacityInput가 충분하지 않은 경우 필요한 용량의 포인터입니다.
  • anchorIdsXrUuidEXT 구조체 배열에 대한 포인터입니다. anchorIdsCapacityInput이 0인 경우 NULL 있습니다.
  • 필요한 anchorIds 크기를 검색하는 방법에 관한 자세한 내용은 버퍼 크기 매개변수 섹션을 참고하세요.

애플리케이션은 xrEnumeratePersistedAnchorsANDROID를 호출하여 현재 유지되는 모든 앵커를 열거할 있습니다. anchorIds는 배열의 용량까지 유지되는 앵커의 UUID를 보유합니다. 용량이 충분하지 않으면 애플리케이션은 어떤 앵커가 반환되는지 보장할 수 없습니다.

유효한 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT

영구 앵커의 지속성 해제

xrUnpersistAnchorANDROID 함수는 다음과 같이 정의됩니다.

XrResult xrUnpersistAnchorANDROID(
    XrDeviceAnchorPersistenceANDROID            handle,
    const XrUuidEXT*                            anchorId);

매개변수 설명

애플리케이션은 xrUnpersistAnchorANDROID를 호출하고 유지되지 않도록 할 앵커의 앵커 XrUuidEXT를 전달하여 유지되는 앵커를 유지 해제할 있습니다.

  • 영구 저장된 데이터가 준비되지 않은 경우 XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID이 반환됩니다.
  • 앵커 XrUuidEXT를 찾을 수 없는 경우 XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID이 반환됩니다.

유효한 사용 (암시적)

반품 코드

성공

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

실패

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • 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_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

앵커 지속성 코드 예시

다음 코드 예는 시스템 기능을 검사하고, 앵커를 유지, 열거, 유지 해제하는 방법과 유지된 앵커 XrUuidEXT에서 앵커를 만드는 방법을 보여줍니다.

XrSession session; // previously initialized
XrSpace anchor; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedPersistenceAnchorTypesANDROID xrEnumerateSupportedPersistenceAnchorTypesANDROID; // previously initialized
PFN_xrCreateDeviceAnchorPersistenceANDROID xrCreateDeviceAnchorPersistenceANDROID; // previously initialized
PFN_xrDestroyDeviceAnchorPersistenceANDROID xrDestroyDeviceAnchorPersistenceANDROID; // previously initialized
PFN_xrPersistAnchorANDROID xrPersistAnchorANDROID; // previously initialized
PFN_xrGetAnchorPersistStateANDROID xrGetAnchorPersistStateANDROID; // previously initialized
PFN_xrCreatePersistedAnchorSpaceANDROID xrCreatePersistedAnchorSpaceANDROID; // previously initialized
PFN_xrEnumeratePersistedAnchorsANDROID xrEnumeratePersistedAnchorsANDROID; // previously initialized
PFN_xrUnpersistAnchorANDROID xrUnpersistAnchorANDROID; // previously initialized

// Create a device anchor persistence handle
XrDeviceAnchorPersistenceCreateInfoANDROID persistenceHandleCreateInfo;
persistenceHandleCreateInfo.type = XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID;
persistenceHandleCreateInfo.next = nullptr;

XrDeviceAnchorPersistenceANDROID persistenceHandle;
CHK_XR(xrCreateDeviceAnchorPersistenceANDROID(session, &persistenceHandleCreateInfo, &persistenceHandle));

/// Persist an anchor
XrPersistedAnchorSpaceInfo anchorSpaceInfo;
anchorSpaceInfo.type = XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID;
anchorSpaceInfo.next = nullptr;
anchorSpaceInfo.anchor = anchor;

XrUuidEXT anchorId;
CHK_XR(xrPersistAnchorANDROID(persistenceHandle, &anchorSpaceInfo, &anchorId));

// ... Update loop ...
// Poll for anchor persist state to confirm if it was successfully persisted
XrAnchorPersistStateANDROID persistState;
CHK_XR(xrGetAnchorPersistStateANDROID(persistenceHandle, &anchorId, &persistState));
if (persistState == XR_ANCHOR_PERSIST_STATE_PERSISTED_ANDROID)  {
  // The anchor was persisted successfully
}

// Enumerate all persisted anchors
uint32_t anchorCountOutput = 0;
std::vector<XrUuidEXT> allAnchors;

CHK_XR(xrEnumeratePersistedAnchorsANDROID(
  persistenceHandle,
  anchorCountOutput,
  &anchorCountOutput,
  nullptr
));
allAnchors.resize(anchorCountOutput, XR_NULL_HANDLE);

// Fetch the actual anchors in an appropriately resized array.
CHK_XR(xrEnumeratePersistedAnchorsANDROID(
  persistenceHandle,
  anchorCountOutput,
  &anchorCountOutput,
  allAnchors.data()
));

// Creating an anchor from a previously persisted anchor using its UUID
XrTime updateTime; // Time used for the current frame's simulation update.
XrUuidEXT anchorId = allAnchors[0];

XrPersistedAnchorSpaceCreateInfo createInfo;
createInfo.type = XR_TYPE_PERSISTED_ANCHOR_CREATE_INFO_ANDROID;
createInfo.next = nullptr;
createInfo.anchorId = anchorId;

XrSpace anchorSpace = XR_NULL_HANDLE;
CHK_XR(xrCreatePersistedAnchorSpaceANDROID(
  persistenceHandle,
  &createInfo,
  &anchorSpace
));

// The anchor was found and retrieved from the local device successfully.
XrSpaceLocation anchorLocation = { XR_TYPE_SPACE_LOCATION };
CHK_XR(xrLocateSpace(anchorSpace, appSpace, updateTime, &anchorLocation));
XrPosef pose = anchorLocation.pose;

// Once app is done with all persistence related tasks
CHK_XR(xrDestroySpace(anchorSpace));
CHK_XR(xrDestroyDeviceAnchorPersistenceANDROID(persistenceHandle));

새로운 객체 유형

새로운 enum 상수

XrObjectType 열거형은 다음으로 확장됩니다.

  • XR_OBJECT_TYPE_DEVICE_ANCHOR_PERSISTENCE_ANDROID

XrResult 열거형이 다음과 같이 확장되었습니다.

  • XR_ERROR_ANCHOR_ID_NOT_FOUND_ANDROID
  • XR_ERROR_ANCHOR_ALREADY_PERSISTED_ANDROID
  • XR_ERROR_ANCHOR_NOT_TRACKING_ANDROID
  • XR_ERROR_PERSISTED_DATA_NOT_READY_ANDROID

XrStructureType 열거형이 다음과 같이 확장되었습니다.

  • XR_TYPE_PERSISTED_ANCHOR_ANDROID
  • XR_TYPE_PERSISTED_ANCHOR_SPACE_CREATE_INFO_ANDROID
  • XR_TYPE_PERSISTED_ANCHOR_SPACE_INFO_ANDROID
  • XR_TYPE_DEVICE_ANCHOR_PERSISTENCE_CREATE_INFO_ANDROID

새로운 enum

새로운 구조

새로운 함수

문제

버전 기록

  • 버전 1, 2024년 10월 10일 (케니 베르카머)
    • 초기 확장 프로그램 설명