Tiện ích OpenXR XR_ANDROID_scene_meshing

Chuỗi tên XR_ANDROID_scene_meshing

Loại tiện ích Tiện ích phiên bản

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

Bản sửa đổi 3

Phần mở rộng và các phần phụ thuộc vào phiên bản OpenXR 1.0

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

Trạng thái IP Không có thông báo xác nhận quyền sở hữu nào về IP.

Nhóm đóng góp 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 dữ liệu lưới cho các lưới đại diện gần đúng cho các đối tượng thực trong môi trường của bạn. Bạn có thể dùng tính năng này để hình dung cảnh trong một ứng dụng sống động 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 về việc tạo mô hình lưới cảnh có thể 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 lập mô hình 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 được liệt kê trong tệp kê khai. Quyền android.permission.SCENE_UNDERSTANDING_FINE được coi là một quyền 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 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:

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

Kiểm tra khả năng của hệ thố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 cấu trúc XrSystemSceneMeshingPropertiesANDROID với XrSystemProperties khi gọi xrGetSystemProperties.

XrSystemSceneMeshingPropertiesANDROID

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

Nội dung mô tả của 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 tạo lưới cảnh hay không.

Nếu supportsSceneMeshing là XR_FALSE, thì hệ thống không hỗ trợ tính năng tạo lưới cảnh. Ứ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, vì các lệnh gọi đến xrCreateSceneMeshingTrackerANDROID sẽ không thành công.

Nếu supportsSceneMeshing là XR_TRUE, 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)

XrSceneMeshSemanticLabelSetANDROID

Liệt kê XrSceneMeshSemanticLabelSetANDROID để mô tả các tập hợp nhãn ngữ nghĩa cho tính năng tạo mô hình 3D 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;

xrEnumerateSupportedSemanticLabelSetsANDROID

Ứng dụng có thể nhận 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.

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

Nội dung mô tả 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à độ dài của supportedSemanticLabelSets.
  • supportedSemanticLabelSetsOutputCount là số lượng phần tử trong supportedSemanticLabelSets do thời gian chạy sửa đổi kể từ đầu mảng.
  • supportedSemanticLabelSets là một mảng XrSceneMeshSemanticLabelSetANDROID mà thời gian chạy ghi các tập hợp nhãn ngữ nghĩa được hỗ trợ vào.

Mọi hệ thống dự kiến sẽ hỗ trợ ít nhất XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID vì giá trị enum này không biểu thị 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.

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

XrSceneMeshingTrackerANDROID

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.

xrCreateSceneMeshingTrackerANDROID

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

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

Nội dung mô tả tham số

Nếu hệ thống không hỗ trợ tính năng tạo lưới cảnh, xrCreateSceneMeshingTrackerANDROID sẽ trả về XR_ERROR_FEATURE_UNSUPPORTED. Ứng dụng có thể kiểm tra khả năng hỗ trợ của hệ thống bằng cách gọi xrGetSystemProperties với cấu trúc XrSystemSceneMeshingPropertiesANDROID.

Bạn có thể chỉ sử dụng các tập hợp 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. Bạn có thể dùng hàm xrEnumerateSupportedSemanticLabelSetsANDROID để lấy danh sách các tập hợp nhãn ngữ nghĩa được hỗ trợ.

Nếu ứng dụng yêu cầu một semanticLabelSet không được hỗ trợ, xrCreateSceneMeshingTrackerANDROID sẽ trả về XR_ERROR_FEATURE_UNSUPPORTED.

Xử lý xrCreateSceneMeshingTrackerANDROID sở hữu tất cả cá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.

XrSceneMeshingTrackerCreateInfoANDROID

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

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

Nội dung mô tả của 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 được dùng để chỉ định tập hợp nhãn ngữ nghĩa sẽ được dùng cho việc 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 đệm XrSceneSubmeshDataANDROID::vertexSemantics.
  • enableNormals là một XrBool32 dùng để chỉ định có nên thêm các đỉnh pháp tuyến cho các đỉnh lưới trong vùng đệm lưới cảnh khi nhận dữ liệu lưới cảnh hay không.

xrDestroySceneMeshingTrackerANDROID

Hàm xrDestroySceneMeshingTrackerANDROID 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.

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID          tracker);

Nội dung mô tả tham số

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

XrSceneMeshSnapshotANDROID

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. Về cơ bản, ảnh chụp nhanh này sẽ lấy ảnh 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.

XrSceneMeshSnapshotCreateInfoANDROID

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

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

Nội dung mô tả của 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 dùng để mô tả không gian tham chiếu mà thông tin về tư thế của các lưới phụ cảnh phải đượ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ị.
  • boundingBox là một XrBoxf mô tả hộp giới hạn mà trong đó sẽ thu được lưới cảnh.

XrSceneMeshTrackingStateANDROID

Liệt kê XrSceneMeshTrackingStateANDROID mô tả trạng thái theo dõi cho trình theo dõi tạo 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. Liệt kê này được gói trong cấu trúc XrSceneMeshSnapshotCreationResultANDROID do xrCreateSceneMeshSnapshotANDROID trả về.

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;

XrSceneMeshSnapshotCreationResultANDROID

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 do xrCreateSceneMeshSnapshotANDROID trả về. Kết quả bao gồm mã nhận dạng ảnh chụp nhanh và trạng thái theo dõi của trình theo dõi tạo mô hình lưới cảnh tại thời điểm tạo ảnh chụp nhanh.

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

Nội dung mô tả của 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 đối tượng XrSceneMeshSnapshotANDROID do thời gian chạy tạo.
  • 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.

xrCreateSceneMeshSnapshotANDROID

Ứ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, đối tượng xử lý là thông tin tổng quan nhanh về 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 lần lượt xrGetAllSubmeshStatesANDROID và xrGetSubmeshDataANDROID.

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

Nội dung mô tả tham số

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

XrSceneSubmeshStateANDROID

XrSceneSubmeshStateANDROID mô tả một lưới con. Nó chứa thông tin cơ bản về lưới con (mã nhận dạng, tư thế, ranh giới, thời gian cập nhật gần đây nhất).

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

Nội dung mô tả của 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 biểu thị thời gian cập nhật gần đây nhất của lưới con.
  • 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. Đây cũng là tư thế của tâm hộp giới hạn lưới con.
  • bounds là một XrExtent3Df mô tả kích thước của hộp giới hạn bao quanh lưới con. Ranh giới này nằm trong không gian cơ sở được dùng để tạo tay cầm lưới cảnh.

xrGetAllSubmeshStatesANDROID

Ứ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ành phần 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. Bạn có thể dùng hàm này trong một thành ngữ gồm 2 lệnh gọi.

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

Nội dung mô tả tham số

  • snapshot là một đối tượng XrSceneMeshSnapshotANDROID được tạo trước đó bằng xrCreateSceneMeshSnapshotANDROID.
  • submeshStateCapacityInput là độ dài của submeshStates.
  • submeshStateCountOutput là số lượng phần tử trong submeshStates được thời gian chạy sửa đổi kể từ đầu mảng.
  • submeshStates là 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.

XrSceneSubmeshDataANDROID

XrSceneSubmeshDataANDROID chứa dữ liệu tam giác cho một lưới con cùng với mã nhận dạng lưới con. Cấu trúc này được dùng trong xrGetSubmeshDataANDROID để lấy dữ liệu của lưới con. Ứng dụng phải đặt mã nhận dạng lưới con của cấu trúc này và con trỏ vùng đệm đến các vùng đệm được phân bổ để dữ liệu được trả về cho lưới con có thể được điền vào các vùng đệm được phân bổ. Ứng dụng có thể sử dụng xrGetSubmeshDataANDROID làm thành ngữ 2 lệnh gọi, trong đó lệnh gọi đầu tiên sẽ yêu cầu ứng dụng đặt mã nhận dạng lưới con và lấy kích thước của các bộ đệm cần thiết cho dữ liệu lưới con, sau đó ứng dụng có thể phân bổ các bộ đệm và lấy dữ liệu trong lệnh gọi thứ hai.

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ả của 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à độ dài của vertexPositions, vertexNormals và vertexSemantics.
  • vertexCountOutput là số lượng phần tử trong vertexPositions, vertexNormals và vertexSemantics đã được thời gian chạy sửa đổi kể từ đầu mả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 khi tắt các giá trị chuẩn 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ể để trống trường này 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 được đặt.
  • indexCapacityInput là độ dài của indices.
  • indexCountOutput là số lượng phần tử trong indices đã được thời gian chạy sửa đổi kể từ đầu mả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.

xrGetSubmeshDataANDROID

Ứng dụng có thể dùng hàm xrGetSubmeshDataANDROID để lấy dữ liệu cho một danh sách con đã chọn. Bạn có thể dùng hàm này trong một thành ngữ gồm 2 lệnh gọi. Trong lệnh gọi đầu tiên, ứng dụng phải đặt một mã nhận dạng lưới con hợp lệ (tức là có thể truy xuất từ xrGetAllSubmeshStatesANDROID bằng cùng một ảnh chụp nhanh lưới cảnh) và dung lượng bằng 0 cho từng phần tử trong danh sách lưới con đã chọn để lấy kích thước của các vùng đệm cần thiết cho dữ liệu lưới con. Trong lệnh gọi thứ hai, ứng dụng phải đặt con trỏ bộ nhớ đệm thành một bộ nhớ đệm được phân bổ cho từng phần tử trong danh sách được chọn gồm các lưới phụ cùng với dung lượng của bộ nhớ đệm để lấy dữ liệu của các lưới phụ.

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

Nội dung mô tả tham số

XrSceneMeshSemanticLabelANDROID

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;

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

xrDestroySceneMeshSnapshotANDROID

Ứng dụng có thể 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. Cú pháp này sẽ tự động bị huỷ khi trình theo dõi bị huỷ vì cú pháp trình theo dõi là gốc của cú pháp ảnh chụp nhanh lưới cảnh.

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID            snapshot);

Nội dung mô tả tham số

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
  std::vector<XrSceneSubmeshStateANDROID> states;
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  states.resize(submeshCount);
  for (XrSceneSubmeshStateANDROID& state : states) {
    state = {.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.vertexCountOutput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCountOutput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCountOutput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCountOutput];
  }
  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 =
      reinterpret_cast<XrSceneMeshSemanticLabelANDROID*>(data.vertexSemantics);
    XrPosef pose = submeshesPoses[i];

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

    // Release the allocated memory for the data buffers when done using
    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

Hằng số Enum mới

Liệt kê XrObjectType bằng:

  • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
  • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

Liệt kê XrStructureType được mở rộng bằng:

  • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID
  • 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_STATE_ANDROID
  • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID

Enum mới

Cấu trúc mới

Hàm mới

Vấn đề

Nhật ký phiên bản

  • Bản sửa đổi 3, ngày 15/5/2025 (Salar Khan) ** Nội dung mô tả ban đầu về tiện ích

OpenXR™ và biểu trưng OpenXR là các nhãn hiệu thuộc sở hữu của The Khronos Group Inc. và được đăng ký làm nhãn hiệu ở Trung Quốc, Liên minh Châu Âu, Nhật Bản và Vương quốc Anh.