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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Имя Строка

XR_ANDROID_composition_layer_passthrough_mesh

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

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

Зарегистрированный добавочный номер

463

Пересмотр

1

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

OpenXR 1.0

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

2024-09-18

Статус ИС

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

Участники

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

Кевин Моул, Google

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

Питер Чен, Google

Левана Чен, Google

Обзор

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

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

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

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

Для полноэкранного просмотра приложения могут использовать режим смешивания окружения .

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

Приложение может проверить, способна ли система создавать сетку сквозного прохождения слоя композиции, привязав структуру 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 , определяющую начальные параметры слоя passthrough. Это поле также может быть связано со структурой 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

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

• xrСоздатьПроходнойСлойANDROID
• xrDestroyPassthroughLayerANDROID
• xrSetPassthroughLayerMeshANDROID

Проблемы

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

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

OpenXR™ и логотип OpenXR являются товарными знаками компании Khronos Group Inc. и зарегистрированы в качестве товарного знака в Китае, Европейском Союзе, Японии и Великобритании.