XR_ANDROID_scene_meshing

Name String

XR_ANDROID_scene_meshing

Loại tiện ích

Phần mở rộng thực thể

Số máy lẻ đã đăng ký

719

Bản sửa đổi

3

Trạng thái phê chuẩn

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

Phần phụ thuộc của tiện ích và 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ó tuyên bố nào về tài sản 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.

Ứng dụng có thể sử dụng tiện ích này để trực quan hoá 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 tế, chẳng hạn như va chạm.

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

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

Quyền

Ứ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à 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 quyền trong thời gian chạy để sử dụng các hàm sau:

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

Kiểm tra chức năng của hệ thống

Cấu trúc XrSystemSceneMeshingPropertiesANDROID được định nghĩa như sau:

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ 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 chia lưới cảnh hay không.

Ứ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 cấu trúc XrSystemSceneMeshingPropertiesANDROID với XrSystemProperties khi gọi xrGetSystemProperties .

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

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

Cách sử dụng hợp lệ (Ngầm ẩn)

Enum XrSceneMeshSemanticLabelSetANDROID mô tả các tập hợp nhãn ngữ nghĩa cho tính năng 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_DEFAULT2_ANDROID = 1000801000,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

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

Nội dung mô tả enum

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

Bộ nhãn ngữ nghĩa này thể hiện 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.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID

Tập hợp nhãn ngữ nghĩa này đại diện cho XrSceneMeshSemanticLabel2ANDROID. (Do tiện ích XR_ANDROID_scene_meshing_semantic_label2 thêm)

Hàm xrEnumerateSupportedSemanticLabelSetsANDROID được định nghĩa 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 được 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.
  • Xem chương Tham số dung lượng bộ nhớ đệm để biết nội dung mô tả chi tiết về cách truy xuất kích thước supportedSemanticLabelSets cần thiết.

Ứng dụng có thể liệt kê các nhóm nhãn ngữ nghĩa mà hệ thống hỗ trợ bằ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.

Cách 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 tên người dù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à một con trỏ đến một mảng các giá trị supportedSemanticLabelSetsInputCapacity XrSceneMeshSemanticLabelSetANDROID

Mã trả về

Thành công

  • XR_SUCCESS

Không thành công

  • 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 trình xử lý trình theo dõi lưới cảnh

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

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

Bạn có thể dùng tên người 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 định nghĩa như sau:

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

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

Ứng dụng có thể tạo một tay điều khiển XrSceneMeshingTrackerANDROID bằ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 lưới cảnh.

Ứng dụng chỉ được sử dụng các nhóm nhãn ngữ nghĩa mà hệ thống hỗ trợ trong XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet khi tạo 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 nhóm nhãn ngữ nghĩa được hỗ trợ bằng hàm xrEnumerateSupportedSemanticLabelSetsANDROID.

Tên người dùng xrCreateSceneMeshingTrackerANDROID sở hữu tất cả tài nguyên cho tính năng 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 điều khiển thông qua hàm xrDestroySceneMeshingTrackerANDROID.

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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 định nghĩa như sau:

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ 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 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 vùng đệm XrSceneSubmeshDataANDROID :: vertexSemantics.
  • enableNormals là một XrBool32 dùng để chỉ định xem có đưa pháp tuyến đỉnh cho các đỉnh lưới vào vùng đệm lưới cảnh khi lấy dữ liệu lưới cảnh hay không.

Cấu trúc XrSceneMeshingTrackerCreateInfoANDROID mô tả thông tin để tạo một tay điều khiển XrSceneMeshingTrackerANDROID.

Cách sử dụng hợp lệ (Ngầm ẩn)

Hàm xrDestroySceneMeshingTrackerANDROID được định nghĩa như sau:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

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

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

Cách sử dụng hợp lệ (Ngầm ẩn)

Độ an toàn cho chuỗi

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

Mã trả về

Thành công

  • XR_SUCCESS

Không thành công

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Tạo trình xử lý ảnh chụp nhanh lưới cảnh

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

Tay điều khiển XrSceneMeshSnapshotANDROID đại diện cho ảnh chụp nhanh lưới cảnh. Ảnh chụp nhanh này được tạo bằng cách sử dụng xrCreateSceneMeshSnapshotANDROID, giúp 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 tên người dùng này để truy xuất thông tin và dữ liệu về lưới phụ bằng xrGetAllSubmeshStatesANDROID và xrGetSubmeshDataANDROID .

Hàm xrCreateSceneMeshSnapshotANDROID được định nghĩa như sau:

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

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

Ứng dụng có thể sử dụng hàm xrCreateSceneMeshSnapshotANDROID để tạo ảnh chụp nhanh lưới cảnh từ trình theo dõi lưới cảnh. Hàm này trả về một handle XrSceneMeshSnapshotANDROID cùng với XrSceneMeshTrackingStateANDROID được gói trong cấu trúc XrSceneMeshSnapshotCreationResultANDROID. Về mặt kỹ thuật, tay điều khiển 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 tên người 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.

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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 định nghĩa như sau:

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ 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 để lấy lưới cảnh.

Cấu trúc XrSceneMeshSnapshotCreateInfoANDROID mô tả thông tin để tạo một tay điều khiển XrSceneMeshSnapshotANDROID

Cách sử dụng hợp lệ (Ngầm ẩn)

Cấu trúc XrSceneMeshSnapshotCreationResultANDROID được định nghĩa như sau:

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ 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 tay điều khiển 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 .

Cách sử dụng hợp lệ (Ngầm ẩn)

Enum XrSceneMeshTrackingStateANDROID mô tả trạng thái theo dõi của 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 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ị enum có ý nghĩa như sau:

Nội dung mô tả enum

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

Trình theo dõi chưa sẵn sàng cung cấp dữ liệu lưới.

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

Bộ theo dõi hoạt động đang hoạt động.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

Trình 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

Trình theo dõi không nhận được kết quả đo lường 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ó nguồn lỗi nào khác, thì 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 chụp nhanh đó, bất kể XrSceneMeshTrackingStateANDROID hiện tại của trình theo dõi. 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 được cập nhật hoặc trống.

Lấy dữ liệu lưới cảnh từ ảnh chụp nhanh lưới cảnh

Hàm xrGetAllSubmeshStatesANDROID được định nghĩa 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 tay điều khiển 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 được 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 cấu trúc XrSceneSubmeshStateANDROID mà thời gian chạy sẽ xuất trạng thái của tất cả lưới con trong lưới cảnh. Giá trị này có thể là NULL nếu submeshStateCapacityInput là 0.
  • Xem chương Tham số dung lượng bộ nhớ đệm để biết nội dung mô tả chi tiết về cách truy xuất kích thước submeshStates cần thiết.

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

Cách sử dụng hợp lệ (Ngầm ẩn)

  • Phải bật tiện ích XR_ANDROID_scene_meshing trước khi gọi xrGetAllSubmeshStatesANDROID
  • snapshot phải là một tay điều khiển 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à một 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

Không thành công

  • 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 định nghĩa như sau:

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ 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 thể hiện thời điểm lưới con được cập nhật gần đây nhất.
  • submeshPoseInBaseSpace là một XrPosef đại diện cho tư thế của lưới phụ trong không gian cơ sở dùng để tạo ảnh chụp nhanh lưới cảnh. Tư thế cũng là tâm của hộp giới hạn lưới phụ.
  • bounds là một XrExtent3Df mô tả kích thước của hộp giới hạn bao quanh lưới con. Giới hạn này được xác định trong không gian cơ sở dùng để tạo tay điều khiển lưới cảnh.

Thời gian chạy nỗ lực hết sức để liên kết submeshId với vùng không gian thực mà lưới con chiếm giữ. Thời gian chạy có thể mất mối liên kết này bất cứ lúc nào và chỉ định một UUID mới cho bất kỳ nhóm nhỏ nào của các lưới con được phát hiện. Cụ thể, 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.

Cách sử dụng hợp lệ (Ngầm ẩn)

Hàm xrGetSubmeshDataANDROID được định nghĩa 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ả lưới con cùng một lúc bằng cách truyền 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 phụ không hợp lệ hoặc có nhiều phần tử trong inoutSubmeshData có cùng mã nhận dạng lưới phụ, 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ị do xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput trả về, nếu không thì thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE .

Bạn có thể dùng hàm này trong một thành ngữ 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.

Cách sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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 định nghĩa 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ả về thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ 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 được 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 ra các vị trí đỉnh của lưới con.
  • vertexNormals là một mảng XrVector3f mà thời gian chạy sẽ xuất ra các pháp tuyến đỉnh của lưới con. Trường này có thể được để NULL nếu ứng dụng tạo một trình theo dõi có tắt chế độ bình thường.
  • 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. Trường này có thể được để NULL nếu ứng dụng đã tạo một trình theo dõi có 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 được 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 con.
  • 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 cần thiết.

Cách 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à một con trỏ đến một mảng cấu trúc vertexCapacityInput XrVector3f
  • Nếu vertexCapacityInput không phải là 0 , thì vertexNormals phải là một con trỏ đến một mảng cấu trúc vertexCapacityInput 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

Enum XrSceneMeshSemanticLabelANDROID là tập hợp nhãn ngữ nghĩa mặc định 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 phần tử lưới tương ứng đại diện cho một sàn.

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

Nhãn ngữ nghĩa này cho biết phần tử lưới tương ứng đại diện cho trần nhà.

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_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 bức tường.

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_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 bảng.

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

Hàm xrDestroySceneMeshSnapshotANDROID được định nghĩa 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 tay điều khiển bị huỷ, ứng dụng không thể sử dụng tay điều khiển đó để lấy thông tin hoặc dữ liệu về lưới phụ nữa. Phần điều khiển sẽ tự động bị huỷ khi trình theo dõi bị huỷ vì phần điều khiển trình theo dõi là phần tử mẹ của phần điều khiển ảnh chụp nhanh lưới cảnh.

Cách sử dụng hợp lệ (Ngầm ẩn)

Độ an toàn cho chuỗi

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

Mã trả về

Thành công

  • XR_SUCCESS

Không thành công

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Mã ví dụ về tính năng chia lưới cảnh

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 tháng 5 năm 2025 (Salar Khan)

    • Nội dung mô tả ban đầu về tiện ích