XR_EXT_spatial_plane_tracking

Name String

XR_EXT_spatial_plane_tracking

Loại phần mở rộng

Tiện ích phiên bản

Số máy nhánh đã đăng ký

742

Bản sửa đổi

1

Trạng thái phê chuẩn

Được phê chuẩn

Phần mở rộng và các phần phụ thuộc của phiên bản

XR_EXT_spatial_entity

Cộng tác viên

Nihav Jain, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

Tổng quan

Tiện ích này dựa trên XR_EXT_spatial_entity và xác định khả năng không gian theo dõi mặt phẳng cho khung thực thể không gian.

Hỗ trợ thời gian chạy

Nếu thời gian chạy hỗ trợ tính năng theo dõi mặt phẳng, thì phải cho biết điều này bằng cách liệt kê XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT trong xrEnumerateSpatialCapabilitiesEXT .

Cấu hình

Cấu trúc XrSpatialCapabilityConfigurationPlaneTrackingEXT được xác định như sau:

typedef struct XrSpatialCapabilityConfigurationPlaneTrackingEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationPlaneTrackingEXT;

Nội dung mô tả thành viên

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
• capability là một XrSpatialCapabilityEXT và phải là XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT .
• enabledComponentCount là một uint32_t mô tả số lượng phần tử trong mảng enabledComponents.
• enabledComponents là con trỏ đến một mảng XrSpatialComponentTypeEXT .

Các ứng dụng có thể bật khả năng không gian XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT bằng cách thêm một con trỏ vào cấu trúc XrSpatialCapabilityConfigurationPlaneTrackingEXT trong XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE nếu capability không phải là XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT .

Sử dụng hợp lệ (Ngầm ẩn)

• Bạn phải bật tiện ích XR_EXT_spatial_plane_tracking trước khi sử dụng XrSpatialCapabilityConfigurationPlaneTrackingEXT
• type phải là XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• capability phải là giá trị XrSpatialCapabilityEXT hợp lệ
• enabledComponents phải là con trỏ đến một mảng gồm enabledComponentCount giá trị XrSpatialComponentTypeEXT hợp lệ
• Tham số enabledComponentCount phải lớn hơn 0

Thành phần được đảm bảo

Thời gian chạy hỗ trợ XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT phải cung cấp các thành phần không gian sau đây dưới dạng các thành phần được đảm bảo của tất cả thực thể được phát hiện bởi khả năng này và phải liệt kê các thành phần đó trong xrEnumerateSpatialCapabilityComponentTypesEXT :

• XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
• XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

Thành phần 2D có ranh giới

Thành phần 2D có ranh giới cung cấp tâm và phạm vi của mặt phẳng do thực thể mà thành phần đó nằm trên biểu thị. Hãy xem phần 2D có ranh giới để biết thêm thông tin.

Thành phần căn chỉnh mặt phẳng

Dữ liệu thành phần

typedef enum XrSpatialPlaneAlignmentEXT {
    XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_UPWARD_EXT = 0,
    XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_DOWNWARD_EXT = 1,
    XR_SPATIAL_PLANE_ALIGNMENT_VERTICAL_EXT = 2,
    XR_SPATIAL_PLANE_ALIGNMENT_ARBITRARY_EXT = 3,
    XR_SPATIAL_PLANE_ALIGNMENT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPlaneAlignmentEXT;

Liệt kê XrSpatialPlaneAlignmentEXT mô tả sự liên kết của mặt phẳng được liên kết với thực thể không gian bằng một thành phần XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT.

Các giá trị liệt kê có ý nghĩa như sau:

Nội dung mô tả về enum

XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_UPWARD_EXT

Thực thể này nằm ngang và hướng lên trên (ví dụ: sàn nhà).

XR_SPATIAL_PLANE_ALIGNMENT_HORIZONTAL_DOWNWARD_EXT

Thực thể này nằm ngang và hướng xuống dưới (ví dụ: trần nhà).

XR_SPATIAL_PLANE_ALIGNMENT_VERTICAL_EXT

Thực thể này là thực thể dọc (ví dụ: tường).

XR_SPATIAL_PLANE_ALIGNMENT_ARBITRARY_EXT

Thực thể có hướng tuỳ ý, không phải hướng dọc và không phải hướng ngang.

Cấu trúc danh sách thành phần để truy vấn dữ liệu

Cấu trúc XrSpatialComponentPlaneAlignmentListEXT được xác định như sau:

typedef struct XrSpatialComponentPlaneAlignmentListEXT {
    XrStructureType                type;
    void*                          next;
    uint32_t                       planeAlignmentCount;
    XrSpatialPlaneAlignmentEXT*    planeAlignments;
} XrSpatialComponentPlaneAlignmentListEXT;

Nội dung mô tả thành viên

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
• planeAlignmentCount là một uint32_t mô tả số lượng phần tử trong mảng planeAlignments.
• planeAlignments là một mảng XrSpatialPlaneAlignmentEXT .

Để truy vấn thành phần căn chỉnh mặt phẳng của các thực thể không gian trong XrSpatialSnapshotEXT , hãy thêm XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT vào XrSpatialComponentDataQueryConditionEXT :: componentTypes và thêm XrSpatialComponentPlaneAlignmentListEXT vào chuỗi XrSpatialComponentDataQueryResultEXT :: next.

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrQuerySpatialComponentDataEXT nếu XrSpatialComponentPlaneAlignmentListEXT nằm trong chuỗi XrSpatialComponentDataQueryResultEXT :: next nhưng XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT không có trong XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Thời gian chạy phải trả về XR_ERROR_SIZE_INSUFFICIENT từ xrQuerySpatialComponentDataEXT nếu planeAlignmentCount nhỏ hơn XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Sử dụng hợp lệ (Ngầm ẩn)

• Bạn phải bật tiện ích XR_EXT_spatial_plane_tracking trước khi sử dụng XrSpatialComponentPlaneAlignmentListEXT
• type phải là XR_TYPE_SPATIAL_COMPONENT_PLANE_ALIGNMENT_LIST_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• planeAlignments phải là con trỏ đến một mảng gồm các giá trị planeAlignmentCount XrSpatialPlaneAlignmentEXT
• Tham số planeAlignmentCount phải lớn hơn 0

Cấu hình

Nếu XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT được liệt kê trong XrSpatialCapabilityComponentTypesEXT :: componentTypes cho một số khả năng, thì ứng dụng có thể bật khả năng đó bằng cách đưa giá trị liệt kê vào danh sách XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents của cấu trúc dẫn xuất XrSpatialCapabilityConfigurationBaseHeaderEXT của khả năng hỗ trợ thành phần này.

Thành phần này không yêu cầu bất kỳ cấu hình đặc biệt nào để được đưa vào chuỗi XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Thành phần không bắt buộc

Thời gian chạy hỗ trợ XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT có thể hỗ trợ các thành phần không gian khác ngoài những thành phần được liệt kê trong phần Thành phần được đảm bảo. Một ứng dụng sử dụng xrEnumerateSpatialCapabilityComponentTypesEXT để lấy danh sách đầy đủ các thành phần mà một thời gian chạy hỗ trợ, sau đó định cấu hình những thành phần mà ứng dụng quan tâm khi tạo bối cảnh không gian.

Thành phần lưới 2D

Dữ liệu thành phần

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT sử dụng cấu trúc XrSpatialMeshDataEXT cho dữ liệu của mình.

Cấu trúc danh sách thành phần để truy vấn dữ liệu

Cấu trúc XrSpatialComponentMesh2DListEXT được xác định như sau:

typedef struct XrSpatialComponentMesh2DListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 meshCount;
    XrSpatialMeshDataEXT*    meshes;
} XrSpatialComponentMesh2DListEXT;

Nội dung mô tả thành viên

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
• meshCount là một uint32_t mô tả số lượng phần tử trong mảng meshes.
• meshes là một mảng XrSpatialMeshDataEXT .

Để truy vấn thành phần 2D dạng lưới của các thực thể không gian trong XrSpatialSnapshotEXT , hãy thêm XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT vào XrSpatialComponentDataQueryConditionEXT :: componentTypes và thêm XrSpatialComponentMesh2DListEXT vào chuỗi XrSpatialComponentDataQueryResultEXT :: next.

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrQuerySpatialComponentDataEXT nếu XrSpatialComponentMesh2DListEXT nằm trong chuỗi XrSpatialComponentDataQueryResultEXT :: next nhưng XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT không có trong XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Thời gian chạy phải trả về XR_ERROR_SIZE_INSUFFICIENT từ xrQuerySpatialComponentDataEXT nếu meshCount nhỏ hơn XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Đối với XrSpatialMeshDataEXT do thời gian chạy điền vào mảng meshes, XrSpatialBufferEXT :: bufferType cho XrSpatialMeshDataEXT :: vertexBuffer phải là XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT và XrSpatialBufferEXT :: bufferType cho XrSpatialMeshDataEXT :: indexBuffer phải là XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

Sử dụng hợp lệ (Ngầm ẩn)

• Bạn phải bật tiện ích XR_EXT_spatial_plane_tracking trước khi sử dụng XrSpatialComponentMesh2DListEXT
• type phải là XR_TYPE_SPATIAL_COMPONENT_MESH_2D_LIST_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• meshes must là con trỏ đến một mảng gồm các cấu trúc meshCount XrSpatialMeshDataEXT
• Tham số meshCount phải lớn hơn 0

Cấu hình

Nếu XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT được liệt kê trong XrSpatialCapabilityComponentTypesEXT :: componentTypes cho một số khả năng, thì ứng dụng có thể bật khả năng đó bằng cách đưa giá trị liệt kê vào danh sách XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents của cấu trúc dẫn xuất XrSpatialCapabilityConfigurationBaseHeaderEXT của khả năng hỗ trợ thành phần này.

Thành phần này không yêu cầu bất kỳ cấu hình đặc biệt nào để được đưa vào chuỗi XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Thành phần đa giác 2D

Dữ liệu thành phần

Cấu trúc XrSpatialPolygon2DDataEXT được xác định như sau:

typedef struct XrSpatialPolygon2DDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
} XrSpatialPolygon2DDataEXT;

Nội dung mô tả thành viên

• origin là một XrPosef xác định nguồn gốc của đa giác. Tất cả các đỉnh của đa giác đều tương ứng với gốc này trên mặt phẳng X-Y.
• vertexBuffer là một XrSpatialBufferEXT cung cấp mã nhận dạng cho một vùng đệm thuộc loại XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT và đại diện cho vùng đệm đỉnh của thực thể mà thành phần này nằm trên đó. Bạn phải trả về các đỉnh theo chiều ngược chiều kim đồng hồ. Đa giác do các đỉnh này đại diện không được tự giao nhau và có thể lõm.

XrSpatialBufferEXT :: bufferType cho vertexBuffer phải là XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

Sử dụng hợp lệ (Ngầm ẩn)

• Bạn phải bật tiện ích XR_EXT_spatial_plane_tracking trước khi sử dụng XrSpatialPolygon2DDataEXT
• vertexBuffer phải là một cấu trúc XrSpatialBufferEXT hợp lệ

Cấu trúc danh sách thành phần để truy vấn dữ liệu

Cấu trúc XrSpatialComponentPolygon2DListEXT được xác định như sau:

typedef struct XrSpatialComponentPolygon2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      polygonCount;
    XrSpatialPolygon2DDataEXT*    polygons;
} XrSpatialComponentPolygon2DListEXT;

Nội dung mô tả thành viên

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
• polygonCount là một uint32_t mô tả số lượng phần tử trong mảng polygons.
• polygons là một mảng XrSpatialPolygon2DDataEXT .

Để truy vấn thành phần đa giác 2D của các thực thể không gian trong XrSpatialSnapshotEXT , hãy thêm XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT vào XrSpatialComponentDataQueryConditionEXT :: componentTypes và thêm XrSpatialComponentPolygon2DListEXT vào chuỗi XrSpatialComponentDataQueryResultEXT :: next.

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrQuerySpatialComponentDataEXT nếu XrSpatialComponentPolygon2DListEXT nằm trong chuỗi XrSpatialComponentDataQueryResultEXT :: next nhưng XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT không có trong XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Thời gian chạy phải trả về XR_ERROR_SIZE_INSUFFICIENT từ xrQuerySpatialComponentDataEXT nếu polygonCount nhỏ hơn XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Sử dụng hợp lệ (Ngầm ẩn)

• Bạn phải bật tiện ích XR_EXT_spatial_plane_tracking trước khi sử dụng XrSpatialComponentPolygon2DListEXT
• type phải là XR_TYPE_SPATIAL_COMPONENT_POLYGON_2D_LIST_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• polygons phải là con trỏ đến một mảng gồm polygonCount cấu trúc XrSpatialPolygon2DDataEXT
• Tham số polygonCount phải lớn hơn 0

Cấu hình

Nếu XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT được liệt kê trong XrSpatialCapabilityComponentTypesEXT :: componentTypes cho một số khả năng, thì ứng dụng có thể bật khả năng đó bằng cách đưa giá trị liệt kê vào danh sách XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents của cấu trúc dẫn xuất XrSpatialCapabilityConfigurationBaseHeaderEXT của khả năng hỗ trợ thành phần này.

Thành phần này không yêu cầu bất kỳ cấu hình đặc biệt nào để được đưa vào chuỗi XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Nhãn ngữ nghĩa về máy bay

Dữ liệu thành phần

typedef enum XrSpatialPlaneSemanticLabelEXT {
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT = 2,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT = 3,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT = 4,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT = 5,
    XR_SPATIAL_PLANE_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPlaneSemanticLabelEXT;

Liệt kê XrSpatialPlaneSemanticLabelEXT mô tả một tập hợp nhãn ngữ nghĩa cho các mặt phẳng.

Nội dung mô tả về enum

XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT

Thời gian chạy không phân loại được thực thể này.

XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT

Thực thể là một sàn nhà.

XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT

Thực thể là một bức tường.

XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT

Thực thể là trần nhà.

XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT

Thực thể là một bảng.

Cấu trúc danh sách thành phần để truy vấn dữ liệu

Cấu trúc XrSpatialComponentPlaneSemanticLabelListEXT được xác định như sau:

typedef struct XrSpatialComponentPlaneSemanticLabelListEXT {
    XrStructureType                    type;
    void*                              next;
    uint32_t                           semanticLabelCount;
    XrSpatialPlaneSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentPlaneSemanticLabelListEXT;

Nội dung mô tả thành viên

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
• semanticLabelCount là một uint32_t mô tả số lượng phần tử trong mảng semanticLabels.
• semanticLabels là một mảng XrSpatialPlaneSemanticLabelEXT .

Để truy vấn thành phần nhãn ngữ nghĩa mặt phẳng của các thực thể không gian trong XrSpatialSnapshotEXT , hãy thêm XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT vào XrSpatialComponentDataQueryConditionEXT :: componentTypes và thêm XrSpatialComponentPlaneSemanticLabelListEXT vào chuỗi XrSpatialComponentDataQueryResultEXT :: next.

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrQuerySpatialComponentDataEXT nếu XrSpatialComponentPlaneSemanticLabelListEXT nằm trong chuỗi tiếp theo của XrSpatialComponentDataQueryResultEXT :: next nhưng XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT không có trong XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Thời gian chạy phải trả về XR_ERROR_SIZE_INSUFFICIENT từ xrQuerySpatialComponentDataEXT nếu semanticLabelCount nhỏ hơn XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Sử dụng hợp lệ (Ngầm ẩn)

• Bạn phải bật tiện ích XR_EXT_spatial_plane_tracking trước khi sử dụng XrSpatialComponentPlaneSemanticLabelListEXT
• type phải là XR_TYPE_SPATIAL_COMPONENT_PLANE_SEMANTIC_LABEL_LIST_EXT
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• semanticLabels phải là con trỏ đến một mảng gồm các giá trị semanticLabelCount XrSpatialPlaneSemanticLabelEXT
• Tham số semanticLabelCount phải lớn hơn 0

Cấu hình

Nếu XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT được liệt kê trong XrSpatialCapabilityComponentTypesEXT :: componentTypes cho một số khả năng, thì ứng dụng có thể bật khả năng đó bằng cách đưa giá trị liệt kê vào danh sách XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents của cấu trúc dẫn xuất XrSpatialCapabilityConfigurationBaseHeaderEXT của khả năng hỗ trợ thành phần này.

Thành phần này không yêu cầu bất kỳ cấu hình đặc biệt nào để được đưa vào chuỗi XrSpatialCapabilityConfigurationBaseHeaderEXT :: next.

Mã ví dụ

Định cấu hình khả năng theo dõi mặt phẳng

Đoạn mã ví dụ sau đây minh hoạ cách định cấu hình khả năng theo dõi mặt phẳng khi tạo một bối cảnh không gian.

// Check if plane tracking capability is supported
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount, &capabilityCount, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT) == capabilities.end()) {
  return;
}

// Enumerate supported components for plane tracking capability
XrSpatialCapabilityComponentTypesEXT planeComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &planeComponents));
std::vector<XrSpatialComponentTypeEXT> planeCapabilityComponents(planeComponents.componentTypeCountOutput);
planeComponents.componentTypeCapacityInput = planeCapabilityComponents.size();
planeComponents.componentTypes = planeCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &planeComponents));

// Check if polygon 2D and plane semantic labels optional components are supported
const auto supportsComponent = [&planeCapabilityComponents](XrSpatialComponentTypeEXT component) {
  return std::find(planeCapabilityComponents.begin(), planeCapabilityComponents.end(), component) != planeCapabilityComponents.end();
};

const bool supportsPolygon2DComponent = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT);
const bool supportsSemanticLabelComponent = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT);

// Create a spatial context
XrSpatialContextEXT spatialContext{};

// Enable the 2 guaranteed components of the plane tracking capability
std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};
// Optionally enable polygon2D if it is supported
if (supportsPolygon2DComponent) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT);
}
// Optionally enable semantic labels if it is supported
if (supportsSemanticLabelComponent) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT);
}

XrSpatialCapabilityConfigurationPlaneTrackingEXT planeConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT};
planeConfig.capability = XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT;
planeConfig.enabledComponentCount = enabledComponents.size();
planeConfig.enabledComponents = enabledComponents.data();

std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
  reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&planeConfig),
};

XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
XrFutureEXT createContextFuture;
CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

waitUntilReady(createContextFuture);

XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
if (completion.futureResult != XR_SUCCESS) {
  return;
}

spatialContext = completion.spatialContext;

// ...
// Discover entities with the spatial context
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Khám phá các thực thể không gian và dữ liệu thành phần truy vấn

Đoạn mã ví dụ sau đây minh hoạ cách khám phá các thực thể không gian cho một bối cảnh được định cấu hình bằng XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT và truy vấn dữ liệu thành phần của thực thể đó.

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};
if (supportsPolygon2DComponent) {
  snapshotComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT);
}
if (supportsSemanticLabelComponent) {
  snapshotComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT);
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2D(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT bounded2DList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    bounded2DList.boundCount = bounded2D.size();
    bounded2DList.bounds = bounded2D.data();
    queryResult.next = &bounded2DList;

    std::vector<XrSpatialPolygon2DDataEXT> polygons;
    XrSpatialComponentPolygon2DListEXT polygonList{XR_TYPE_SPATIAL_COMPONENT_POLYGON_2D_LIST_EXT};
    if (supportsPolygon2DComponent) {
      polygons.resize(queryResult.entityIdCountOutput);
      polygonList.polygonCount = polygons.size();
      polygonList.polygons = polygons.data();
      polygonList.next = queryResult.next;
      queryResult.next = &polygonList;
    }

    std::vector<XrSpatialPlaneSemanticLabelEXT> semanticLabels;
    XrSpatialComponentPlaneSemanticLabelListEXT semanticLabelsList{XR_TYPE_SPATIAL_COMPONENT_PLANE_SEMANTIC_LABEL_LIST_EXT};
    if (supportsSemanticLabelComponent) {
      semanticLabels.resize(queryResult.entityIdCountOutput);
      semanticLabelsList.semanticLabelCount = semanticLabels.size();
      semanticLabelsList.semanticLabels = semanticLabels.data();
      semanticLabelsList.next = queryResult.next;
      queryResult.next = &semanticLabelsList;
    }

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] != XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        continue;
      }

      // 2D bounds for entity entityIds[i] is bounded2D[i].extents centered on bounded2D[i].center.

      if (supportsPolygon2DComponent) {
        // 2D polygon for entity entityIds[i] is the buffer represented by polygons[i].bufferId.
        // Application uses flink:xrGetSpatialBufferVector2fEXT to get the buffer data.
      }

      if (supportsSemanticLabelComponent) {
        // semantic label for entity entityIds[i] is semanticLabels[i].
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

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

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

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

Cấu trúc mới

• XrSpatialCapabilityConfigurationPlaneTrackingEXT
• XrSpatialPolygon2DDataEXT

• Mở rộng XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentMesh2DListEXT
  • XrSpatialComponentPlaneAlignmentListEXT
  • XrSpatialComponentPlaneSemanticLabelListEXT
  • XrSpatialComponentPolygon2DListEXT

Enum mới

• XrSpatialPlaneAlignmentEXT
• XrSpatialPlaneSemanticLabelEXT

Hằng số Enum mới

• XR_EXT_SPATIAL_PLANE_TRACKING_EXTENSION_NAME
• XR_EXT_spatial_plane_tracking_SPEC_VERSION

• Mở rộng XrSpatialCapabilityEXT :

  • XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

• Mở rộng XrSpatialComponentTypeEXT :

  • XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT
  • XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT
  • XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

• Mở rộng XrStructureType :

  • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT
  • XR_TYPE_SPATIAL_COMPONENT_MESH_2D_LIST_EXT
  • XR_TYPE_SPATIAL_COMPONENT_PLANE_ALIGNMENT_LIST_EXT
  • XR_TYPE_SPATIAL_COMPONENT_PLANE_SEMANTIC_LABEL_LIST_EXT
  • XR_TYPE_SPATIAL_COMPONENT_POLYGON_2D_LIST_EXT

Vấn đề

Danh sách phiên bản

• Bản sửa đổi 1, ngày 2/7/2024 (Nihav Jain, Google)

  • Nội dung mô tả ban đầu của tiện ích