XR_ANDROID_scene_meshing

Name String

XR_ANDROID_scene_meshing

Loại phần mở rộng

Tiện ích Instance

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

719

Bản sửa đổi

3

Trạng thái phê chuẩn

Chưa được phê chuẩn

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

OpenXR 1.0

Ngày sửa đổi gần đây nhất

2025-05-15

Trạng thái IP

Không có thông báo xác nhận quyền sở hữu nào đã biết về quyền sở hữu trí tuệ.

Cộng tác viên

Spencer Quin, Google
Jared Finder, Google
Antonio Fontan, Google
Cairn Overturf, Google
Nihav Jain, Google
Salar Khan, Google
Sebastian Klose, Google
Jürgen Sturm, Google
Vinny DaSilva, Google
Ricardo Campbell, Google

Tổng quan

Tiện ích này nhằm cung cấp các lưới đại diện gần đúng cho các đối tượng thực tế trong môi trường của người dùng.

Các ứng dụng có thể dùng tiện ích này để hình dung cảnh và cho phép các đối tượng ảo tương tác với các đối tượng thực, chẳng hạn như va chạm.

Dữ liệu lưới cảnh được tạo bởi thời gian chạy và chia sẻ với ứng dụng bằng XrSceneMeshingTrackerANDROID và XrSceneMeshSnapshotANDROID . Các ứng dụng có thể truy cập vào các giá trị trong thông tin về lưới con của cảnh thông qua XrSceneSubmeshStateANDROID được trả về từ xrGetAllSubmeshStatesANDROID . Các ứng dụng có thể truy cập vào các giá trị trong dữ liệu lưới con của cảnh thông qua XrSceneSubmeshDataANDROID được trả về từ xrGetSubmeshDataANDROID .

Dữ liệu về mô hình hoá cảnh là thông tin cá nhân nhạy cảm và có liên kết chặt chẽ với quyền riêng tư và tính toàn vẹn của cá nhân. Các ứng dụng lưu trữ hoặc chuyển dữ liệu tạo mô hình lưới cảnh luôn phải yêu cầu người dùng chấp nhận một cách chủ động và cụ thể để thực hiện việc này.

Quyền

Các ứng dụng Android phải có quyền android.permission.SCENE_UNDERSTANDING_FINE trong tệp kê khai. Quyền android.permission.SCENE_UNDERSTANDING_FINE được coi là một quyền truy cập thông tin nhạy cảm vì quyền này cho phép thời gian chạy nghiên cứu môi trường của người dùng.

Ứng dụng phải yêu cầu cấp quyền trong thời gian chạy để sử dụng các chức năng sau:

(cấp độ bảo vệ: nguy hiểm)

Kiểm tra khả năng của hệ thống

Cấu trúc XrSystemSceneMeshingPropertiesANDROID được xác định là:

typedef struct XrSystemSceneMeshingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;

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. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • supportsSceneMeshing là một XrBool32 , cho biết liệu hệ thống có hỗ trợ tính năng tạo lưới cảnh hay không.

Một ứng dụng có thể kiểm tra xem hệ thống có khả năng tạo lưới cảnh hay không bằng cách liên kết một cấu trúc XrSystemSceneMeshingPropertiesANDROID với XrSystemProperties khi gọi xrGetSystemProperties .

Nếu một thời gian chạy trả về XR_FALSE cho supportsSceneMeshing , thì hệ thống không hỗ trợ tính năng tạo lưới cảnh. Do đó, bạn phải trả về XR_ERROR_FEATURE_UNSUPPORTED từ xrCreateSceneMeshingTrackerANDROID. Ứng dụng nên tránh sử dụng chức năng tạo lưới cảnh khi supportsSceneMeshing là XR_FALSE .

Nếu một thời gian chạy trả về XR_TRUE cho supportsSceneMeshing , thì hệ thống sẽ hỗ trợ tính năng tạo lưới cảnh.

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

Liệt kê XrSceneMeshSemanticLabelSetANDROID mô tả các bộ nhãn ngữ nghĩa để tạo lưới cảnh. Mỗi giá trị trong enum này đại diện cho một enum khác chứa các nhãn ngữ nghĩa. Ví dụ: giá trị XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID đại diện cho tập hợp XrSceneMeshSemanticLabelANDROID .

typedef enum XrSceneMeshSemanticLabelSetANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

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

Nội dung mô tả về enum

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

Bộ nhãn ngữ nghĩa này biểu thị việc không có nhãn ngữ nghĩa.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

Tập hợp nhãn ngữ nghĩa này đại diện cho XrSceneMeshSemanticLabelANDROID.

Hàm xrEnumerateSupportedSemanticLabelSetsANDROID được xác định như sau:

XrResult xrEnumerateSupportedSemanticLabelSetsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedSemanticLabelSetsInputCapacity,
    uint32_t*                                   supportedSemanticLabelSetsOutputCount,
    XrSceneMeshSemanticLabelSetANDROID*         supportedSemanticLabelSets);

Nội dung mô tả về tham số

  • instance là một XrInstance do ứng dụng tạo.
  • systemId là một XrSystemId được thử lại từ xrGetSystem .
  • supportedSemanticLabelSetsInputCapacity là dung lượng của supportedSemanticLabelSets hoặc 0 để truy xuất dung lượng cần thiết.
  • supportedSemanticLabelSetsOutputCount là con trỏ đến số lượng supportedSemanticLabelSets đã ghi hoặc con trỏ đến dung lượng cần thiết trong trường hợp supportedSemanticLabelSetsInputCapacity không đủ.
  • supportedSemanticLabelSets là con trỏ đến một mảng XrSceneMeshSemanticLabelSetANDROID . Giá trị này có thể là NULL nếu supportedSemanticLabelSetsInputCapacity là 0.
  • Hãy xem chương Tham số kích thước vùng đệm để biết nội dung mô tả chi tiết về cách truy xuất kích thước supportedSemanticLabelSets bắt buộc.

Ứng dụng có thể liệt kê các tập hợp nhãn ngữ nghĩa mà hệ thống hỗ trợ bằng cách sử dụng hàm xrEnumerateSupportedSemanticLabelSetsANDROID.

Mọi hệ thống phải hỗ trợ ít nhất XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID vì giá trị enum này không đại diện cho tập hợp nhãn ngữ nghĩa và có thể được dùng trong trường hợp ứng dụng không cần ngữ nghĩa đỉnh.

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

  • Bạn phải bật tiện ích XR_ANDROID_scene_meshing trước khi gọi xrEnumerateSupportedSemanticLabelSetsANDROID
  • instance phải là một đối tượng XrInstance hợp lệ
  • supportedSemanticLabelSetsOutputCount phải là con trỏ đến giá trị uint32_t
  • Nếu supportedSemanticLabelSetsInputCapacity không phải là 0 , thì supportedSemanticLabelSets phải là con trỏ đến một mảng gồm các giá trị supportedSemanticLabelSetsInputCapacity XrSceneMeshSemanticLabelSetANDROID

Mã trả về

Thành công

  • XR_SUCCESS

Thất bại

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

Tạo một đối tượng theo dõi kết hợp cảnh

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

Xử lý XrSceneMeshingTrackerANDROID đại diện cho một trình theo dõi tạo lưới cảnh để tạo lưới cảnh và quản lý các tài nguyên liên quan.

Bạn có thể dùng mã nhận dạng này để tạo ảnh chụp nhanh lưới cảnh bằng xrCreateSceneMeshSnapshotANDROID trong tiện ích này.

Hàm xrCreateSceneMeshingTrackerANDROID được xác định như sau:

XrResult xrCreateSceneMeshingTrackerANDROID(
    XrSession                                   session,
    const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
    XrSceneMeshingTrackerANDROID*               tracker);

Nội dung mô tả về tham số

Một ứng dụng có thể tạo một đối tượng XrSceneMeshingTrackerANDROID bằng cách sử dụng hàm xrCreateSceneMeshingTrackerANDROID.

Nếu hệ thống không hỗ trợ tính năng tạo lưới cảnh, thì thời gian chạy phải trả về XR_ERROR_FEATURE_UNSUPPORTED từ xrCreateSceneMeshingTrackerANDROID . Trong trường hợp này, thời gian chạy phải trả về XR_FALSE cho XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing khi hàm xrGetSystemProperties được gọi, để ứng dụng có thể tránh tạo trình theo dõi tạo mô hình lưới cảnh.

Ứng dụng chỉ được sử dụng các bộ nhãn ngữ nghĩa mà hệ thống hỗ trợ trong XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet khi tạo một trình theo dõi lưới cảnh. Nếu ứng dụng sử dụng một tập hợp nhãn ngữ nghĩa đỉnh lưới cảnh không được hỗ trợ, thì thời gian chạy phải trả về XR_ERROR_FEATURE_UNSUPPORTED từ xrCreateSceneMeshingTrackerANDROID .

Ứng dụng có thể liệt kê danh sách các tập hợp nhãn ngữ nghĩa được hỗ trợ bằng hàm xrEnumerateSupportedSemanticLabelSetsANDROID.

Xử lý xrCreateSceneMeshingTrackerANDROID sở hữu tất cả tài nguyên để tạo lưới cảnh. Sau khi hoàn tất trải nghiệm tạo lưới cảnh, ứng dụng phải huỷ tay cầm thông qua hàm xrDestroySceneMeshingTrackerANDROID.

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

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSceneMeshingTrackerCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrSceneMeshSemanticLabelSetANDROID    semanticLabelSet;
    XrBool32                              enableNormals;
} XrSceneMeshingTrackerCreateInfoANDROID;

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. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • semanticLabelSet là một XrSceneMeshSemanticLabelSetANDROID dùng để chỉ định tập hợp nhãn ngữ nghĩa sẽ được dùng cho tính năng tạo lưới cảnh. Nếu bạn đặt giá trị này thành XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID , thì thời gian chạy sẽ bỏ qua trường bộ đệm XrSceneSubmeshDataANDROID :: vertexSemantics.
  • enableNormals là một XrBool32 dùng để chỉ định có bao gồm các vectơ pháp tuyến đỉnh cho các đỉnh lưới trong vùng đệm lưới cảnh hay không khi nhận dữ liệu lưới cảnh.

Cấu trúc XrSceneMeshingTrackerCreateInfoANDROID mô tả thông tin để tạo một đối tượng XrSceneMeshingTrackerANDROID.

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

Hàm xrDestroySceneMeshingTrackerANDROID được xác định như sau:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

Nội dung mô tả về tham số

Hàm xrDestroySceneMeshingTrackerANDROID sẽ giải phóng tracker và các tài nguyên cơ bản khi hoàn tất các trải nghiệm tạo lưới cảnh.

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

Độ an toàn cho luồng

  • Quyền truy cập vào tracker và mọi đối tượng con phải được đồng bộ hoá bên ngoài

Mã trả về

Thành công

  • XR_SUCCESS

Thất bại

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Tạo một đối tượng chụp nhanh lưới cảnh

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

Xử lý XrSceneMeshSnapshotANDROID đại diện cho ảnh chụp nhanh lưới cảnh. Ảnh chụp nhanh này được tạo bằng xrCreateSceneMeshSnapshotANDROID. Hàm này chụp nhanh dữ liệu lưới cảnh tại thời điểm gọi hàm.

Bạn có thể dùng mã nhận dạng này để truy xuất thông tin và dữ liệu về lưới con bằng cách sử dụng xrGetAllSubmeshStatesANDROID và xrGetSubmeshDataANDROID .

Hàm xrCreateSceneMeshSnapshotANDROID được xác định như sau:

XrResult xrCreateSceneMeshSnapshotANDROID(
    XrSceneMeshingTrackerANDROID                tracker,
    const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
    XrSceneMeshSnapshotCreationResultANDROID*   outSnapshotCreationResult);

Nội dung mô tả về tham số

Ứng dụng có thể dùng hàm xrCreateSceneMeshSnapshotANDROID để tạo ảnh chụp nhanh lưới cảnh từ trình theo dõi tạo lưới cảnh. Hàm này trả về một đối tượng XrSceneMeshSnapshotANDROID cùng với XrSceneMeshTrackingStateANDROID được gói trong cấu trúc XrSceneMeshSnapshotCreationResultANDROID. Về mặt kỹ thuật, tay cầm là ảnh chụp nhanh dữ liệu lưới cảnh tại thời điểm tạo. Bạn có thể dùng mã nhận dạng này để truy vấn thông tin và dữ liệu về lưới cảnh bằng cách sử dụng xrGetAllSubmeshStatesANDROID và xrGetSubmeshDataANDROID tương ứng.

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

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID

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

typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrBoxf             boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;

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. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • baseSpace là một XrSpace trong đó thông tin về tư thế của lưới phụ cảnh được biểu thị.
  • time là XrTime mô tả thời điểm lưới cảnh sẽ được xử lý hoặc hiển thị, thường là XrFrameState :: predictedDisplayTime .
  • boundingBox là một XrBoxf mô tả hộp giới hạn để thu thập lưới cảnh.

Cấu trúc XrSceneMeshSnapshotCreateInfoANDROID mô tả thông tin để tạo một đối tượng XrSceneMeshSnapshotANDROID

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

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

typedef struct XrSceneMeshSnapshotCreationResultANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrSceneMeshSnapshotANDROID         snapshot;
    XrSceneMeshTrackingStateANDROID    trackingState;
} XrSceneMeshSnapshotCreationResultANDROID;

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. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • snapshot là một đối tượng XrSceneMeshSnapshotANDROID do thời gian chạy tạo ra.
  • trackingState là một XrSceneMeshTrackingStateANDROID mô tả trạng thái của trình theo dõi lưới cảnh tại thời điểm tạo ảnh chụp nhanh.

Cấu trúc XrSceneMeshSnapshotCreationResultANDROID lưu trữ kết quả của quá trình tạo ảnh chụp nhanh lưới cảnh được trả về từ xrCreateSceneMeshSnapshotANDROID .

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

Liệt kê XrSceneMeshTrackingStateANDROID để mô tả trạng thái theo dõi của một trình theo dõi lưới cảnh. Mỗi giá trị trong enum này đại diện cho một trạng thái của trình theo dõi tạo lưới cảnh.

typedef enum XrSceneMeshTrackingStateANDROID {
    XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID = 0,
    XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID = 1,
    XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID = 2,
    XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID = 3,
    XR_SCENE_MESH_TRACKING_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshTrackingStateANDROID;

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

Nội dung mô tả enum

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

Thiết bị theo dõi chưa sẵn sàng cung cấp dữ liệu mạng lưới.

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

Thiết bị theo dõi đang chủ động theo dõi.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

Thiết bị theo dõi đang chờ các phép đo hợp lệ để tích hợp kể từ lần cập nhật lưới gần đây nhất.

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

Thiết bị theo dõi chưa nhận được các chỉ số hợp lệ trong nhiều chu kỳ và đang ở trạng thái lỗi.

Trạng thái này chỉ đóng vai trò là thông tin bổ sung cho ứng dụng. Nếu không có các nguồn lỗi khác, thời gian chạy phải tiếp tục cho phép ứng dụng tạo ảnh chụp nhanh và truy xuất dữ liệu từ các ảnh đó, bất kể XrSceneMeshTrackingStateANDROID hiện tại của trình theo dõi là gì. Nếu trạng thái không phải là XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID , thì ảnh chụp nhanh có thể không phải là ảnh mới nhất hoặc không có ảnh.

Thu thập dữ liệu lưới cảnh từ ảnh chụp nhanh lưới cảnh

Hàm xrGetAllSubmeshStatesANDROID được xác định như sau:

XrResult xrGetAllSubmeshStatesANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshStateCapacityInput,
    uint32_t*                                   submeshStateCountOutput,
    XrSceneSubmeshStateANDROID*                 submeshStates);

Nội dung mô tả về tham số

  • snapshot là một đối tượng XrSceneMeshSnapshotANDROID được tạo trước đó bằng xrCreateSceneMeshSnapshotANDROID .
  • submeshStateCapacityInput là dung lượng của submeshStates hoặc 0 để truy xuất dung lượng cần thiết.
  • submeshStateCountOutput là con trỏ đến số lượng submeshStates đã ghi hoặc con trỏ đến dung lượng cần thiết trong trường hợp submeshStateCapacityInput không đủ.
  • submeshStates là con trỏ đến một mảng gồm các cấu trúc XrSceneSubmeshStateANDROID mà thời gian chạy sẽ xuất trạng thái của tất cả các lưới con trong lưới cảnh. Giá trị này có thể là NULL nếu submeshStateCapacityInput là 0.
  • Hãy xem chương Tham số kích thước vùng đệm để biết nội dung mô tả chi tiết về cách truy xuất kích thước submeshStates bắt buộc.

Ứng dụng có thể sử dụng hàm xrGetAllSubmeshStatesANDROID để lấy trạng thái của tất cả các lưới con trong lưới cảnh. Thông tin này chứa thông tin cơ bản để cho phép ứng dụng chọn các lưới con mà ứng dụng muốn lấy dữ liệu.

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

  • Bạn phải bật tiện ích XR_ANDROID_scene_meshing trước khi gọi xrGetAllSubmeshStatesANDROID
  • snapshot phải là một đối tượng XrSceneMeshSnapshotANDROID hợp lệ
  • submeshStateCountOutput phải là con trỏ đến giá trị uint32_t
  • Nếu submeshStateCapacityInput không phải là 0 , thì submeshStates phải là con trỏ đến một mảng gồm các cấu trúc submeshStateCapacityInput XrSceneSubmeshStateANDROID

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

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

Cấu trúc XrSceneSubmeshStateANDROID được xác định là:

typedef struct XrSceneSubmeshStateANDROID {
    XrStructureType    type;
    void*              next;
    XrUuid             submeshId;
    XrTime             lastUpdatedTime;
    XrPosef            submeshPoseInBaseSpace;
    XrExtent3Df        bounds;
} XrSceneSubmeshStateANDROID;

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. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • submeshId là một XrUuid xác định lưới con.
  • lastUpdatedTime là một XrTime biểu thị thời điểm lưới con được cập nhật lần gần đây nhất.
  • submeshPoseInBaseSpace là một XrPosef biểu thị tư thế của lưới con trong không gian cơ sở dùng để tạo ảnh chụp nhanh lưới cảnh. Tư thế này cũng là tâm của hộp giới hạn lưới con.
  • bounds là một XrExtent3Df mô tả kích thước của hộp bao quanh chứa lưới con. Ranh giới này được xác định trong không gian cơ sở dùng để tạo tay cầm lưới cảnh.

Thời gian chạy cố gắng hết sức để ánh xạ submeshId với khu vực của không gian thực mà lưới phụ chiếm giữ. Thời gian chạy có thể mất ánh xạ này bất cứ lúc nào và chỉ định một UUID mới cho bất kỳ tập hợp con nào của các lưới con được phát hiện. Cụ thể, các thời gian chạy không bắt buộc phải sử dụng lại cùng một UUID cho cùng một lưới trong các phiên bản ứng dụng tiếp theo.

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

Hàm xrGetSubmeshDataANDROID được xác định như sau:

XrResult xrGetSubmeshDataANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshDataCount,
    XrSceneSubmeshDataANDROID*                  inoutSubmeshData);

Nội dung mô tả về tham số

Ứng dụng có thể sử dụng hàm xrGetSubmeshDataANDROID để lấy các lô lưới con hoặc tất cả các lưới con cùng một lúc bằng cách truyền một danh sách XrSceneSubmeshDataANDROID với mỗi XrSceneSubmeshDataANDROID :: submeshId được đặt thành mã nhận dạng tương ứng của lưới con cần truy xuất.

XrSceneSubmeshDataANDROID :: submeshId phải là duy nhất cho mọi phần tử trong inoutSubmeshData và có thể truy xuất bằng xrGetAllSubmeshStatesANDROID cho cùng một snapshot . Nếu mã nhận dạng lưới con không hợp lệ hoặc nhiều phần tử trong inoutSubmeshData có cùng mã nhận dạng lưới con, thì thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE .

submeshDataCount phải bằng hoặc nhỏ hơn giá trị mà xrGetAllSubmeshStatesANDROID trả về :: submeshStateCountOutput, nếu không, thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE .

Bạn có thể dùng phương thức này trong một thành ngữ gồm 2 lệnh gọi để truy vấn số lượng đỉnh và chỉ mục cho tất cả các lưới con đã chọn.

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

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

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

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

typedef struct XrSceneSubmeshDataANDROID {
    XrStructureType    type;
    const void*        next;
    XrUuid             submeshId;
    uint32_t           vertexCapacityInput;
    uint32_t           vertexCountOutput;
    XrVector3f*        vertexPositions;
    XrVector3f*        vertexNormals;
    uint8_t*           vertexSemantics;
    uint32_t           indexCapacityInput;
    uint32_t           indexCountOutput;
    uint32_t*          indices;
} XrSceneSubmeshDataANDROID;

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. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • submeshId là một XrUuid xác định lưới con.
  • vertexCapacityInput là dung lượng của vertexPositions , vertexNormals và vertexSemantics , hoặc 0 để truy xuất dung lượng cần thiết.
  • vertexCountOutput là con trỏ đến số lượng vertexPositions, vertexNormals và vertexSemantics đã ghi hoặc con trỏ đến dung lượng cần thiết trong trường hợp vertexCapacityInput không đủ.
  • vertexPositions là một mảng XrVector3f mà thời gian chạy sẽ xuất vị trí đỉnh của lưới con.
  • vertexNormals là một mảng XrVector3f mà thời gian chạy sẽ xuất các vectơ pháp tuyến đỉnh của lưới con. Bạn có thể để trống trường này NULL nếu ứng dụng đã tạo một trình theo dõi mà các giá trị chuẩn bị vô hiệu hoá.
  • vertexSemantics là một mảng uint8_t mà thời gian chạy sẽ xuất ngữ nghĩa đỉnh của lưới con. Bạn có thể bỏ trống trường này NULL nếu ứng dụng đã tạo một trình theo dõi có bộ nhãn ngữ nghĩa XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID.
  • indexCapacityInput là dung lượng của indices hoặc 0 để truy xuất dung lượng cần thiết.
  • indexCountOutput là con trỏ đến số lượng indices đã ghi hoặc con trỏ đến dung lượng cần thiết trong trường hợp vertexCapacityInput không đủ.
  • indices là một mảng uint32_t mà thời gian chạy sẽ xuất ra các chỉ mục của lưới phụ.
  • Hãy xem chương Tham số kích thước vùng đệm để biết nội dung mô tả chi tiết về cách truy xuất kích thước vertexPositions, vertexNormals, vertexSemantics và indices bắt buộc.

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

  • Bạn phải bật tiện ích XR_ANDROID_scene_meshing trước khi sử dụng XrSceneSubmeshDataANDROID
  • type phải là XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
  • 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
  • Nếu vertexCapacityInput không phải là 0 , thì vertexPositions phải là con trỏ đến một mảng gồm vertexCapacityInput cấu trúc XrVector3f
  • Nếu vertexCapacityInput không phải là 0 , thì vertexNormals phải là con trỏ đến một mảng gồm vertexCapacityInput cấu trúc XrVector3f
  • Nếu vertexCapacityInput không phải là 0 , thì vertexSemantics phải là con trỏ đến một mảng gồm các giá trị vertexCapacityInput uint8_t
  • Nếu indexCapacityInput không phải là 0 , thì indices phải là con trỏ đến một mảng gồm các giá trị indexCapacityInput uint32_t

Liệt kê XrSceneMeshSemanticLabelANDROID là tập hợp nhãn ngữ nghĩa mặc định mà có thể dùng để gắn nhãn các đỉnh lưới nhằm mô tả đỉnh lưới nằm trên bề mặt môi trường thực tế nào. Tập hợp enum này được biểu thị bằng giá trị XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID trong XrSceneMeshSemanticLabelSetANDROID .

typedef enum XrSceneMeshSemanticLabelANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID = 2,
    XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID = 3,
    XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID = 4,
    XR_SCENE_MESH_SEMANTIC_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelANDROID;

Các enum có ý nghĩa như sau:

Nội dung mô tả enum

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

Nhãn ngữ nghĩa này cho biết phần tử lưới tương ứng đại diện cho một đối tượng không xác định.

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

Nhãn ngữ nghĩa này cho biết rằng phần tử lưới tương ứng biểu thị một sàn nhà.

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

Nhãn ngữ nghĩa này cho biết rằng phần tử lưới tương ứng biểu thị một trần nhà.

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

Nhãn ngữ nghĩa này cho biết rằng phần tử lưới tương ứng biểu thị một bức tường.

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

Nhãn ngữ nghĩa này cho biết rằng phần tử lưới tương ứng đại diện cho một bảng.

Huỷ ảnh chụp nhanh lưới cảnh

Hàm xrDestroySceneMeshSnapshotANDROID được xác định như sau:

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

Nội dung mô tả về tham số

Ứng dụng có thể sử dụng hàm xrDestroySceneMeshSnapshotANDROID để huỷ ảnh chụp nhanh lưới cảnh. Sau khi huỷ tay cầm, ứng dụng không thể sử dụng tay cầm đó để lấy thông tin hoặc dữ liệu về lưới con nữa. Đối tượng xử lý sẽ tự động bị huỷ khi trình theo dõi bị huỷ vì đối tượng xử lý trình theo dõi là đối tượng mẹ của đối tượng xử lý ảnh chụp nhanh lưới cảnh.

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

Độ an toàn cho luồng

  • Quyền truy cập vào snapshot và mọi đối tượng con phải được đồng bộ hoá bên ngoài

Mã trả về

Thành công

  • XR_SUCCESS

Thất bại

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Mã mẫu để tạo lưới cảnh

Đoạn mã ví dụ sau đây minh hoạ cách truy cập vào dữ liệu lưới cảnh để kết xuất.

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // Received from xrGetSystem() at app startup
XrSession session;    // Created at app startup
XrSpace appPlaySpace; // Created at app startup

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateSceneMeshingTrackerANDROID xrCreateSceneMeshingTrackerANDROID;
PFN_xrDestroySceneMeshingTrackerANDROID xrDestroySceneMeshingTrackerANDROID;
PFN_xrEnumerateSupportedSemanticLabelSetsANDROID xrEnumerateSupportedSemanticLabelSetsANDROID;
PFN_xrCreateSceneMeshSnapshotANDROID xrCreateSceneMeshSnapshotANDROID;
PFN_xrDestroySceneMeshSnapshotANDROID xrDestroySceneMeshSnapshotANDROID;
PFN_xrGetAllSubmeshStatesANDROID xrGetAllSubmeshStatesANDROID;
PFN_xrGetSubmeshDataANDROID xrGetSubmeshDataANDROID;

// Inspect system capability
XrSystemSceneMeshingPropertiesANDROID sceneMeshingProps = {
  .type = XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &sceneMeshingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!sceneMeshingProps.supportsSceneMeshing) {
    // scene meshing is not supported.
    return;
}

uint32_t supportedsemanticLabelSetsCount = 0;
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, 0, &supportedsemanticLabelSetsCount, nullptr);
std::vector<XrSceneMeshSemanticLabelSetANDROID> supportedSemanticLabelSets(
  supportedsemanticLabelSetsCount);
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, supportedsemanticLabelSetsCount,
  &supportedsemanticLabelSetsCount, supportedSemanticLabelSets.data());

XrSceneMeshSemanticLabelSetANDROID semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID;
// Check if system supports XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID
if (std::find(supportedSemanticLabelSets.begin(), supportedSemanticLabelSets.end(),
              XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID) !=
    supportedSemanticLabelSets.end()) {
  semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID;
}

XrSceneMeshingTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID,
  .semanticLabelSet = semanticLabelSet,
  .enableNormals = XR_TRUE
};

XrSceneMeshingTrackerANDROID tracker = XR_NULL_HANDLE;
CHK_XR(xrCreateSceneMeshingTrackerANDROID(session, &trackerCreateInfo, &tracker));

XrSceneMeshSnapshotCreationResultANDROID snapshotResult {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID,
  .snapshot = XR_NULL_HANDLE
};
XrSceneMeshSnapshotANDROID& snapshot = snapshotResult.snapshot;
XrSceneMeshSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
};

// app update loop
while (true) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState; // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;
  XrBoxf box; // populated with the bounding box of the camera frustum

  // ...

  createInfo.baseSpace = appPlaySpace;
  createInfo.time = time;
  createInfo.boundingBox = box;

  // Grab the scene mesh snapshot. This way the app can: know all of the submesh infos,
  // choose the appropriate submeshes for which to get data, allocate the necessary
  // buffer for those submeshes, and then get the data.
  CHK_XR(xrCreateSceneMeshSnapshotANDROID(tracker, &createInfo, &snapshotResult));

  // check the tracking state
  if (snapshotResult.trackingState == XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID) {
    // unrecoverable error. Exit the app.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    break;
  } else if (snapshotResult.trackingState != XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID) {
    // The tracker is not tracking. Try again later.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    continue;
  }

  // 2-call idiom for getting submesh states
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  std::vector<XrSceneSubmeshStateANDROID> states(submeshCount, {
    .type = XR_TYPE_SCENE_SUBMESH_STATE_ANDROID,
  });
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, submeshCount, &submeshCount, states.data()));

  // To store the poses for the selected submeshes
  std::vector<XrPosef> submeshesPoses;
  submeshesPoses.reserve(submeshCount);

  std::vector<XrSceneSubmeshDataANDROID> submeshes;
  submeshes.reserve(submeshCount);
  // Iterate the states and determine which submeshes the app wants data for
  for (XrSceneSubmeshStateANDROID& state : states) {
    // Modify this bool as necessary by looking at states. Maybe state.lastUpdatedTime
    // is below a threshold or maybe the bounding box does not intersect with camera view
    // frustum (The submesh will be culled).
    bool needed;
    if (needed) {
      // Add the selected submesh to the submeshes list. Set the capacity
      // zero for now since the size of the buffer will be determined later.
      XrSceneSubmeshDataANDROID submesh {
        .type = XR_TYPE_SCENE_SUBMESH_DATA_ANDROID,
        .submeshId = state.submeshId,
        .vertexCapacityInput = 0,
        .vertexCountOutput = 0,
        .vertexPositions = nullptr,
        .vertexNormals = nullptr,
        .vertexSemantics = nullptr,
        .indexCapacityInput = 0,
        .indexCountOutput = 0,
        .indices = nullptr,
      };
      submeshes.push_back(submesh);
      submeshesPoses.push_back(state.submeshPoseInBaseSpace);
    }
  }

  // Grab the data for the selected submeshes using the 2-call idiom.
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));
  for (XrSceneSubmeshDataANDROID& submesh : submeshes) {
    submesh.vertexCapacityInput = submesh.vertexCountOutput;
    submesh.vertexCountOutput = 0;
    submesh.vertexPositions = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCapacityInput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCapacityInput];
  }
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));

  // Destroy the scene mesh snapshot since we have finally grabbed the submeshes data. In
  // next iteration app can: create a new one to get latest mesh data
  CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
  snapshot = XR_NULL_HANDLE;

  // Iterate the submeshes and get the vertex positions, vertex normals and
  // vertex semantics data for the selected submeshes
  for (uint32_t i = 0; i < submeshes.size(); i++) {
    XrSceneSubmeshDataANDROID& data = submeshes[i];
    XrVector3f* vertexPositions = data.vertexPositions;
    XrVector3f* vertexNormals = data.vertexNormals;
    XrSceneMeshSemanticLabelANDROID* vertexSemantics =
      new XrSceneMeshSemanticLabelANDROID[data.vertexCountOutput];
    for (uint32_t j = 0; j < data.vertexCountOutput; j++) {
      vertexSemantics[j] =
        static_cast<XrSceneMeshSemanticLabelANDROID>(data.vertexSemantics[j]);
    }
    XrPosef pose = submeshesPoses[i];

    // *** Use the data as per needs ***

    // Release the allocated memory for the data buffers when done using
    delete [] vertexSemantics;
    delete [] data.vertexPositions;
    delete [] data.vertexNormals;
    delete [] data.vertexSemantics;
    delete [] data.indices;
  }

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

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

Các loại đối tượng mới

Lệnh mới

Cấu trúc mới

Enum mới

Hằng số Enum mới

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION

  • Mở rộng XrObjectType :

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

  • Mở rộng XrStructureType :

    • XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID
    • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
    • XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
    • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID

Vấn đề

Danh sách phiên bản

  • Bản sửa đổi 3, ngày 15/5/2025 (Salar Khan)

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