XR_ANDROID_composition_layer_passthrough_mesh Расширение OpenXR

Строка имени

XR_ANDROID_composition_layer_passthrough_mesh

Тип расширения

Расширение экземпляра

Зарегистрированный внутренний номер

463

Редакция

1

Зависимости расширений и версий

ОпенXR 1.0

Дата последнего изменения

2024-09-18

IP-статус

Нет известных претензий на интеллектуальную собственность.

Авторы

Грант Йошида, Google

Кевин Мул, Google

Василий Баранов, Google

Питер Чен, Google

Левана Чен, Google

Обзор

Для устройств, которые поддерживают несколько режимов смешивания сред, система может предоставлять сквозные конфигурации, чтобы показать пользователю свою физическую среду с эффектом погружения.

Это расширение позволяет приложениям проецировать сквозные текстуры на произвольную геометрию через дополнительный слой композиции XrCompositionLayerPassthroughANDROID .

Характеристики слоя прохождения задаются следующими параметрами, в которых проекция представлена ​​XrPassthroughLayerANDROID .

  XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;

Для полноэкранного перехода приложения могут использовать Environment Blend Mode .

Проверьте возможности системы

Приложение может проверить, способна ли система использовать сквозную сетку слоя композиции, связывая структуру XrSystemPassthroughLayerPropertiesANDROID с XrSystemProperties при вызове xrGetSystemProperties .

typedef struct XrSystemPassthroughLayerPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsPassthroughLayer;
    uint32_t           maxMeshIndexCount;
    uint32_t           maxMeshVertexCount;
} XrSystemPassthroughLayerPropertiesANDROID;

Описания участников

• type — это XrStructureType этой структуры.
• next имеет значение NULL или указатель на следующую структуру в цепочке структур. Никакие такие структуры не определены в ядре OpenXR или этом расширении.
• supportsPassthroughLayer — это XrBool32 , указывающий, поддерживает ли текущая система сквозную сетку слоя композиции.
• maxMeshIndexCount — это uint32_t который возвращает максимальное количество индексов, которые будут приняты для сквозной сетки.
• maxMeshVertexCount — это uint32_t который возвращает максимальное количество вершин, которые будут приняты для сквозной сетки.

Если supportsPassthroughLayer возвращает XR_FALSE , система не поддерживает сквозную сетку слоя композиции и, следовательно, получит XR_ERROR_FEATURE_UNSUPPORTED от xrCreatePassthroughLayerANDROID . Приложению следует избегать использования сквозной сетки слоя композиции, когда supportsPassthroughLayer имеет значение XR_FALSE .

Если supportsPassthroughLayer возвращает XR_TRUE , система поддерживает сквозную сетку слоя композиции. В этом случае maxMeshIndexCount и maxMeshVertexCount вернут ненулевое число. Приложение должно использовать maxMeshIndexCount и maxMeshVertexCount в качестве максимальных значений для установки сквозных сеток при вызове xrCreatePassthroughLayerANDROID и xrSetPassthroughLayerMeshANDROID , в противном случае может быть возвращен XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID , чтобы указать, что данные сетки превышают поддерживаемый предел.

Допустимое использование (неявное)

• Расширение XR_ANDROID_composition_layer_passthrough_mesh должно быть включено перед использованием XrSystemPassthroughLayerPropertiesANDROID.
• type должен быть XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.

Композиция сквозного слоя

XrCompositionLayerPassthroughANDROID содержит информацию, необходимую для рендеринга сквозной текстуры на треугольную сетку при вызове xrEndFrame . XrCompositionLayerPassthroughANDROID — это тип псевдонима для базовой структуры XrCompositionLayerBaseHeader, используемой в XrFrameEndInfo .

typedef struct XrCompositionLayerPassthroughANDROID {
    XrStructureType              type;
    const void*                  next;
    XrCompositionLayerFlags      layerFlags;
    XrSpace                      space;
    XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;
} XrCompositionLayerPassthroughANDROID;

Описания участников

• type — это XrStructureType этой структуры.
• next имеет значение NULL или указатель на следующую структуру в цепочке структур. Никакие такие структуры не определены в ядре OpenXR или этом расширении.
• layerFlags — это битовая маска XrCompositionLayerFlags, описывающая флаги, применяемые к слою.
• space — это XrSpace , в котором pose сетки слоя оценивается с течением времени.
• pose — это XrPosef определяющий положение и ориентацию сетки слоя в системе координат space .
• scale — это XrVector3f определяющий масштаб сетки слоев.
• opacity — это float , определяющее непрозрачность сквозной текстуры в диапазоне [0, 1].
• layer — это XrPassthroughLayerANDROID, ранее созданный с помощью xrCreatePassthroughLayerANDROID .

Приложение может создать структуру XrCompositionLayerPassthroughANDROID с созданным layer и соответствующими сетками, предоставленными XrPassthroughLayerMeshANDROID .

Указатель на XrCompositionLayerPassthroughANDROID может быть отправлен в xrEndFrame как указатель на базовую структуру XrCompositionLayerBaseHeader в выбранном порядке слоев, чтобы запросить среду выполнения для объединения слоя сквозной передачи в конечный выходной кадр.

Допустимое использование (неявное)

• Расширение XR_ANDROID_composition_layer_passthrough_mesh должно быть включено перед использованием XrCompositionLayerPassthroughANDROID.
• type должен быть XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• layerFlags должен иметь значение 0 или допустимую комбинацию значений XrCompositionLayerFlagBits.
• space должен быть действительным дескриптором XrSpace
• layer должен быть действительным дескриптором XrPassthroughLayerANDROID.
• И layer , и space должны быть созданы, выделены или получены из одного и того же сеанса XrSession.

Создайте дескриптор слоя прохождения

Дескриптор XrPassthroughLayerANDROID представляет уровень передачи, который определяет поведение XrCompositionLayerPassthroughANDROID .

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

Приложение может создать дескриптор XrPassthroughLayerANDROID , вызвав xrCreatePassthroughLayerANDROID . Возвращенный дескриптор XrPassthroughLayerANDROID впоследствии можно использовать в вызовах API.

XrResult xrCreatePassthroughLayerANDROID(
    XrSession                                   session,
    const XrPassthroughLayerCreateInfoANDROID*  createInfo,
    XrPassthroughLayerANDROID*                  layer);

Описание параметров

• session — это XrSession , для которого будет создан транзитный уровень.
• createInfo — это указатель на структуру XrPassthroughLayerCreateInfoANDROID , определяющую начальные параметры транзитного слоя. Это поле также можно связать со структурой XrPassthroughLayerMeshANDROID, чтобы одновременно установить сетку.
• layer — это указатель на дескриптор, в котором возвращается созданный XrPassthroughLayerANDROID .

Приложение должно указать количество индексов сквозной сетки в XrPassthroughLayerCreateInfoANDROID::vertexCapacity и XrPassthroughLayerCreateInfoANDROID::indexCapacity, меньшее или равное максимальным значениям, возвращаемым XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount и XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount при вызове xrGetSystemProperties . xrCreatePassthroughLayerANDROID вернет ошибку XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID , если количество индексов сетки, определенных createInfo превышает максимальные значения.

Дескриптор XrPassthroughLayerANDROID в конечном итоге должен быть освобожден с помощью функции xrDestroyPassthroughLayerANDROID .

Допустимое использование (неявное)

• Расширение XR_ANDROID_composition_layer_passthrough_mesh должно быть включено перед вызовом xrCreatePassthroughLayerANDROID.
• session должен быть действительным дескриптором XrSession
• createInfo должен быть указателем на действительную структуру XrPassthroughLayerCreateInfoANDROID.
• layer должен быть указателем на дескриптор XrPassthroughLayerANDROID.

Коды возврата

Успех

• 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_SIZE_INSUFFICIENT
• XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

Структура XrPassthroughLayerCreateInfoANDROID определяется как:

typedef struct XrPassthroughLayerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    uint32_t           vertexCapacity;
    uint32_t           indexCapacity;
} XrPassthroughLayerCreateInfoANDROID;

Описания участников

• type — это XrStructureType этой структуры.
• next имеет значение NULL или указатель на следующую структуру в цепочке структур. XrPassthroughLayerMeshANDROID можно указать в следующей цепочке, чтобы указать начальную сетку для слоя прохождения при вызове xrCreatePassthroughLayerANDROID .
• vertexCapacity — это uint32_t представляющий максимальную емкость буфера вершин для сетки этого слоя, или 0 , если не указано. Если указано, XrPassthroughLayerMeshANDROID::vertexCount любого набора сеток для этого слоя должно быть меньше или равно vertexCapacity .
• indexCapacity — это uint32_t представляющий максимальную емкость буфера индекса для сетки этого слоя, или 0 , если не указано. Если указано, XrPassthroughLayerMeshANDROID::indexCount любого набора сеток для этого слоя должен быть меньше или равен indexCapacity .

Допустимое использование (неявное)

• Расширение XR_ANDROID_composition_layer_passthrough_mesh должно быть включено перед использованием XrPassthroughLayerCreateInfoANDROID.
• type должен быть XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
• next должен быть NULL или действительным указателем на следующую структуру в цепочке структур . См. также: XrPassthroughLayerMeshANDROID.

Приложение может использовать функцию xrDestroyPassthroughLayerANDROID для освобождения транзитного уровня и базовых ресурсов.

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

Описание параметров

• layer — это XrPassthroughLayerANDROID , который необходимо уничтожить.

Допустимое использование (неявное)

• Расширение XR_ANDROID_composition_layer_passthrough_mesh должно быть включено до вызова xrDestroyPassthroughLayerANDROID.
• layer должен быть действительным дескриптором XrPassthroughLayerANDROID.

Безопасность потоков

• Доступ к layer и любым дочерним дескрипторам должен быть синхронизирован извне.

Коды возврата

Успех

• XR_SUCCESS

Отказ

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID

Установить сетку сквозного слоя

Приложение может использовать функцию xrSetPassthroughLayerMeshANDROID , чтобы установить сетку для сквозного слоя.

XrResult xrSetPassthroughLayerMeshANDROID(
    XrPassthroughLayerANDROID                   layer,
    const XrPassthroughLayerMeshANDROID*        mesh);

Описание параметров

• layer — это дескриптор XrPassthroughLayerANDROID , в котором можно обновить данную mesh .
  • mesh — это указатель на структуру XrPassthroughLayerMeshANDROID , определяющую информацию о сетке.

Приложение должно указать количество индексов сквозной сетки в XrPassthroughLayerMeshANDROID::vertexCount и XrPassthroughLayerMeshANDROID::indexCount, меньшее или равное максимальным значениям, возвращаемым XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount и XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount при вызове. xrGetSystemProperties . Если количество индексов сетки, заданное mesh из xrSetPassthroughLayerMeshANDROID , превышает максимальное значение, будет возвращено XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID .

Если емкость буфера сетки указана XrPassthroughLayerCreateInfoANDROID::vertexCapacity и XrPassthroughLayerCreateInfoANDROID::indexCapacity при создании layer с помощью xrCreatePassthroughLayerANDROID , то ошибка XR_ERROR_SIZE_INSUFFICIENT будет возвращена в xrSetPassthroughLayerMeshANDROID, если количество индексов сетки, определенных mesh превышает емкость.

Допустимое использование (неявное)

• Расширение XR_ANDROID_composition_layer_passthrough_mesh должно быть включено перед вызовом xrSetPassthroughLayerMeshANDROID.
• layer должен быть действительным дескриптором XrPassthroughLayerANDROID.
• mesh должна быть указателем на действительную структуру XrPassthroughLayerMeshANDROID.

Коды возврата

Успех

• 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_SIZE_INSUFFICIENT
• XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

Структура XrPassthroughLayerMeshANDROID определяется как:

typedef struct XrPassthroughLayerMeshANDROID {
    XrStructureType          type;
    const void*              next;
    XrWindingOrderANDROID    windingOrder;
    uint32_t                 vertexCount;
    const XrVector3f*        vertices;
    uint32_t                 indexCount;
    const uint16_t*          indices;
} XrPassthroughLayerMeshANDROID;

Описания участников

• type — это XrStructureType этой структуры.
• next имеет значение NULL или указатель на следующую структуру в цепочке структур.
• windingOrder — это XrWindingOrderANDROID треугольников сетки, который будет использоваться для отсеивания задней поверхности при рендеринге сетки.
• vertexCount — это uint32_t представляющий количество вершин в сетке. Если указан XrPassthroughLayerCreateInfoANDROID::vertexCapacity , vertexCount должно быть меньше или равно значению vertexCapacity .
  • vertices — это указатель на массив XrVector3f , который содержит позиции вершин треугольной сетки.
• indexCount — это uint32_t представляющий количество индексов в треугольной сетке. Последние индексы indexCount % 3 , если таковые имеются, не будут нарисованы. Если указан XrPassthroughLayerCreateInfoANDROID::indexCapacity , indexCount должен быть меньше или равен indexCapacity .
• indices — это указатель на массив uint16_t , который содержит индексы треугольной сетки.

Допустимое использование (неявное)

• Расширение XR_ANDROID_composition_layer_passthrough_mesh должно быть включено перед использованием XrPassthroughLayerMeshANDROID.
• type должен быть XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• windingOrder должен быть допустимым значением XrWindingOrderANDROID.
• Если vertexCount не равен 0, vertices должны быть указателями на массив структур vertexCount XrVector3f .
• Если indexCount не равен 0, indices должны быть указателями на массив значений indexCount uint16_t

Перечисление XrWindingOrderANDROID определяет порядок намотки треугольников сетки, используемый средой выполнения для отсеивания обратной грани при отрисовке сетки сквозного слоя.

typedef enum XrWindingOrderANDROID {
    XR_WINDING_ORDER_UNKNOWN_ANDROID = 0,
    XR_WINDING_ORDER_CW_ANDROID = 1,
    XR_WINDING_ORDER_CCW_ANDROID = 2
} XrWindingOrderANDROID;

Описания перечислителей

• XR_WINDING_ORDER_UNKNOWN_ANDROID — Порядок намотки треугольников сетки неизвестен.
• XR_WINDING_ORDER_CW_ANDROID — Порядок намотки треугольников сетки — по часовой стрелке.
• XR_WINDING_ORDER_CCW_ANDROID — Порядок намотки треугольников сетки — против часовой стрелки.

Пример кода для композиции сквозного слоя

В следующем примере кода показано, как создать сквозной слой и использовать его при композиции.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
XrSpace space; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreatePassthroughLayerANDROID xrCreatePassthroughLayerANDROID; // previously initialized
PFN_xrDestroyPassthroughLayerANDROID xrDestroyPassthroughLayerANDROID; // previously initialized
PFN_xrSetPassthroughLayerMeshANDROID xrSetPassthroughLayerMeshANDROID; // previously initialized

// Inspect passthrough mesh system properties
XrSystemPassthroughLayerPropertiesANDROID passthroughLayerSystemProperties{
  XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{
  XR_TYPE_SYSTEM_PROPERTIES, &passthroughLayerSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!passthroughLayerSystemProperties.supportsPassthroughLayer) {
    // the system does not support composite layer passthrough mesh.
    return;
}

// The initial mesh for the layer.
XrPassthroughLayerMeshANDROID mesh = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID,
  .windingOrder = XR_WINDING_ORDER_CW_ANDROID,
  .vertexCount = 4,
  .vertices = {
    { 0, 0, 0 }, { 0, 1, 0 }, { 1, 1, 0 }, { 1, 0, 0 }
  },
  .indexCount = 6,
  .indices = {
    0, 1, 2,
    0, 2, 3
  },
};

// Create the layer. Layers are expected to persist across frames.
XrPassthroughLayerCreateInfoANDROID create_info = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID,
  .next = &mesh,
  .vertexCapacity = 0,
  .indexCapacity = 0,
};
XrPassthroughLayerANDROID layer;
CHK_XR(xrCreatePassthroughLayerANDROID(session, &create_info, &layer));

// Create a composition layer. Composition layers are submitted per frame.
XrCompositionLayerPassthroughANDROID passthrough_layer = {
  .type = XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID,
  .next = nullptr,
  .layerFlags = 0,
  .space = space,
  .pose = {
    .orientation = { 0.0f, 0.0f, 0.0f, 1.0f }
    .position = { 0.0f, 0.0f, 0.0f }
  },
  .scale = { 1.0f, 1.0f, 1.0f },
  .opacity = 1.0f,
  .layer = layer
};

while (1) {
    // ...
    // For every frame in frame loop
    // ...

    // Submit composition layer in xrEndFrame.
    std::vector<XrCompositionLayerBaseHeader*> layers = {
        ...,
        &passthrough_layer,
        ...,
    };
    XrFrameEndInfo end_frame_info = { XR_TYPE_FRAME_END_INFO, nullptr };
    end_frame_info.layerCount = (uint32_t)layers.size();
    end_frame_info.layers = layers.data();
    CHK_XR(xrEndFrame(session, &end_frame_info));

    // Update the layer. Results can be seen the next time a passthrough composition
    // layer is submitted.
    mesh.indexCount = 9;
    const uint16_t new_index_buffer[] = {
        0, 1, 2,
        0, 2, 3,
        0, 1, 2
    };
    mesh.indexBuffer = &new_index_buffer[0];
    CHK_XR(xrSetPassthroughLayerMeshANDROID(&layer, &mesh));

    // ...
    // Finish frame loop
    // ...
}

// Clean up.
CHK_XR(xrDestroyPassthroughLayerANDROID(layer));

Новые типы объектов

• XrPassthroughLayerANDROID

Новые константы перечисления

Перечисление XrObjectType расширено:

• XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID

Перечисление XrStructureType расширено:

• XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
• XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
• XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
• XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID

Перечисление XrResult расширено:

• XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

Новые перечисления

• XrWindingOrderANDROID

Новые структуры

• XrPassthroughLayerCreateInfoANDROID
• XrPassthroughLayerMeshANDROID
• XrCompositionLayerPassthroughANDROID
• XrSystemPassthroughLayerPropertiesANDROID

Новые функции

• xrCreatePassthroughLayerANDROID
• xrDestroyPassthroughLayerANDROID
• xrSetPassthroughLayerMeshANDROID

Проблемы

История версий

• Редакция 1, 11 сентября 2024 г. (Левана Чен)
  • Первоначальное описание расширения