Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

OpenXR 空間實體

對於任何型別的增強現實應用,你都需要存取真實世界的資訊並能追蹤其位置軌道,OpenXR的空間實體API正是為這個目的而引入的。

它採用了非常模組化的設計。這套 API 的核心主要定義了現實世界中的實體(entities)是如何建置的、如何被找到的,以及關於它們的資訊是如何被儲存和存取的。

在此基礎上還新增了各種擴充,用於實作特定的系統,例如標記追蹤、平面追蹤以及錨點。這些統稱為空間能力。

系統處理的每一個實體都能被分解為更小的元件,這使得系統易於拓展與新增新的功能。

供應商有能力去實作並公開可與核心 API 配合使用的額外能力和元件型別。對於Godot而言,這些功能可以通過拓展來實作。儘管這種實作並非本手冊的討論範圍。

最後需要指出的是,空間實體系統使用了非同步函式,這意味著你可以啟動一個處理程序,稍後才得到他的完成通知。

設定

想要使用空間實體(spatial entities)功能,你需要先開啟對應的專案設定。你可以在 OpenXR 選項分類下找到這些設定。

../../_images/openxr_spatial_entities_project_settings.webp
空間實體設定

Settings(設定)

說明

已啟用

請啟用空間實體系統核心。任何空間實體系統必須啟動該核心才能工作。

啟用空間錨點

啟用空間錨點功能以允許建立並追蹤空間錨點。

啟用持久化錨點

啟用空間錨點持久化功能,意味著空間錨點的位置會被儲存並可以在後續的會話之中檢索。

啟用內建錨點檢測,

啟用內建錨點檢測邏輯,這將在追蹤更新時自動檢索持久錨點並調整錨點的位置。

啟用平面追蹤

啟用平面追蹤能力,以便檢測地面、牆壁、天花板以及桌面等表面。

啟用內建的平面檢測

啟用內建的平面檢測邏輯,這將自動對變得可用的新平面資料做出反應。

啟用標記追蹤

啟用我們的標記追蹤能力,以便檢測二維碼、Aruco 標記以及 April 標籤等標記。

啟用內建標記追蹤,

啟用我們的內建標記檢測邏輯,這會對發現新標記或是玩家空間內標記的移動做出自動的反應。

備註

請注意,各種 XR 裝置還要求設定權限標誌。這些需要在匯出預設設定中啟用。

啟用不同的能力會啟用相關的 OpenXR API,但是,為了這些資訊互動,仍需要額外的邏輯才行。對於每個核心系統,我們都擁有可以啟用的內建邏輯來為你完成這些工作。

我們會先假設內建邏輯已經開啟,在這個前提下討論空間實體(spatial entities)系統。然後,我們會去瞭解一下底層的 API,看看如何自己去實作這套功能。不過需要注意的是,自己手動實作往往有點‘殺雞用牛刀’(多此一舉),因為暴露這些底層 API 主要是為了讓 GDExtension 外掛能夠去實作額外的擴充功能。

建立我們的空間管理器

當空間實體被偵測到或是建立,一個 OpenXRSpatialEntityTracker 物件會被實例化並注冊到 XRServer。

每一個種類的空間實體都會實作自己的子類別,並且我們可以對每種不同型別的實體作出反應。

一般來說,我們將為每種實體型別實例化不同的子場景。由於追蹤器物件可與 XRAnchor3D 節點配合使用,因此這些子場景應將該節點設為其根節點。

素有的實體追蹤器最終會通過其 default 姿態暴露其座標。

通過建立一個管理器物件,我們可以自動建立這些子場景並將它們新增到我們的場景樹中。由於所有位置都是相對於 XROrigin3D 節點的區域位置,我們應該將管理器建立為原始節點的子節點。

以下是實作我們管理器邏輯的腳本基礎:

class_name SpatialEntitiesManager
extends Node3D

## Signals a new spatial entity node was added.
signal added_spatial_entity(node: XRNode3D)

## Signals a spatial entity node is about to be removed.
signal removed_spatial_entity(node: XRNode3D)

## Scene to instantiate for spatial anchor entities.
@export var spatial_anchor_scene: PackedScene

## Scene to instantiate for plane tracking spatial entities.
@export var plane_tracker_scene: PackedScene

## Scene to instantiate for marker tracking spatial entities.
@export var marker_tracker_scene: PackedScene

# Trackers we manage nodes for.
var _managed_nodes: Dictionary[XRTracker, XRAnchor3D]

# Enter tree is called whenever our node is added to our scene.
func _enter_tree():
    # Connect to signals that inform us about tracker changes.
    XRServer.tracker_added.connect(_on_tracker_added)
    XRServer.tracker_updated.connect(_on_tracker_updated)
    XRServer.tracker_removed.connect(_on_tracker_removed)

    # Set up existing trackers.
    var trackers : Dictionary = XRServer.get_trackers(XRServer.TRACKER_ANCHOR)
    for tracker_name in trackers:
        var tracker: XRTracker = trackers[tracker_name]
        if tracker and tracker is OpenXRSpatialEntityTracker:
            _add_tracker(tracker)


# Exit tree is called whenever our node is removed from our scene.
func _exit_tree():
    # Clean up our signals.
    XRServer.tracker_added.disconnect(_on_tracker_added)
    XRServer.tracker_updated.disconnect(_on_tracker_updated)
    XRServer.tracker_removed.disconnect(_on_tracker_removed)

    # Clean up trackers.
    for tracker in _managed_nodes:
        removed_spatial_entity.emit(_managed_nodes[tracker])
        remove_child(_managed_nodes[tracker])
        _managed_nodes[tracker].queue_free()

    _managed_nodes.clear()


# See if this tracker should be managed by us and add it.
func _add_tracker(tracker: OpenXRSpatialEntityTracker):
    var new_node: XRAnchor3D

    if _managed_nodes.has(tracker):
        # Already being managed by us!
        return

    if tracker is OpenXRAnchorTracker:
        # Note: Generally spatial anchors are controlled by the developer and
        # are unlikely to be handled by our manager.
        # But just for completeness we'll add it in.
        if spatial_anchor_scene:
            var new_scene = spatial_anchor_scene.instantiate()
            if new_scene is XRAnchor3D:
                new_node = new_scene
            else:
                push_error("Spatial anchor scene doesn't have an XRAnchor3D as a root node and can't be used!")
                new_scene.free()
    elif tracker is OpenXRPlaneTracker:
        if plane_tracker_scene:
            var new_scene = plane_tracker_scene.instantiate()
            if new_scene is XRAnchor3D:
                new_node = new_scene
            else:
                push_error("Plane tracking scene doesn't have an XRAnchor3D as a root node and can't be used!")
                new_scene.free()
    elif tracker is OpenXRMarkerTracker:
        if marker_tracker_scene:
            var new_scene = marker_tracker_scene.instantiate()
            if new_scene is XRAnchor3D:
                new_node = new_scene
            else:
                push_error("Marker tracking scene doesn't have an XRAnchor3D as a root node and can't be used!")
                new_scene.free()
    else:
        # Type of spatial entity tracker we're not supporting?
        push_warning("OpenXR Spatial Entities: Unsupported anchor tracker " + tracker.get_name() + " of type " + tracker.get_class())

    if not new_node:
        # No scene defined or able to be instantiated? We're done!
        return

    # Set up and add to our scene.
    new_node.tracker = tracker.name
    new_node.pose = "default"
    _managed_nodes[tracker] = new_node
    add_child(new_node)

    added_spatial_entity.emit(new_node)


# A new tracker was added to our XRServer.
func _on_tracker_added(tracker_name: StringName, type: int):
    if type == XRServer.TRACKER_ANCHOR:
        var tracker: XRTracker = XRServer.get_tracker(tracker_name)
        if tracker and tracker is OpenXRSpatialEntityTracker:
            _add_tracker(tracker)


# A tracked managed by XRServer was changed.
func _on_tracker_updated(_tracker_name: StringName, _type: int):
    # For now we ignore this, there aren't any changes here we need to react
    # to and the instantiated scene can react to this itself if needed.
    pass


# A tracker was removed from our XRServer.
func _on_tracker_removed(tracker_name: StringName, type: int):
    if type == XRServer.TRACKER_ANCHOR:
        var tracker: XRTracker = XRServer.get_tracker(tracker_name)
        if _managed_nodes.has(tracker):
            # We emit this right before we remove it!
            removed_spatial_entity.emit(_managed_nodes[tracker])

            # Remove the node.
            remove_child(_managed_nodes[tracker])

            # Queue free the node.
            _managed_nodes[tracker].queue_free()

            # And remove from our managed nodes.
            _managed_nodes.erase(tracker)

空間錨點

空間錨點允許我們在虛擬世界中確定真實世界位置,這樣 XR 執行時會追蹤這些位置並根據需要調整它們。如果受到支援,錨點可以被持久化,這意味著當您再次啟動應用的時候,這些錨點會在正確的位置建立。

您可以考慮這樣的應用場景:在您周圍的空間放置虛擬視窗,並在您的應用啟動的時候重新建置;在您的桌子或者牆上放置虛擬物品,並使得它們可以被重新建置

空間錨點是使用注冊在 XRServer 中的 OpenXRAnchorTracker 物件進行追蹤的。

在需要時,空間錨點的位置將自動更新;相關追蹤器的姿勢會隨著更新,因此 XRAnchor3D 節點將重新定位。

當一個特殊錨點被持久化,一個全域唯一標識符(UUID)被分配給此錨點。您將需要儲存它與所有重構場景所需的資訊。在下面的範例程式碼中,我們簡單地呼叫 set_scene_path 與 get_scene_path ,但您需要提供這些函式的私人實作版本。

為建立持久化錨點,您需要進行以下特殊流程:建立一個空間錨點;等待其追蹤狀態變為 ENTITY_TRACKING_STATE_TRACKING ;使錨點持久化;取得其UUID並儲存

當一個持久化的錨點被找到,會新增一個設定好 UUID 的新的追蹤器。就是這種工作流上的差異允許我們正確地對新的和已有的持久化錨點進行響應。

備註

如果您對一個錨點去持久化,UUID 會被銷毀但是錨點本身不會自動刪除。您需要在完成去持久化錨點之後進行響應,然後清除它。而且如果您嘗試銷毀一個持久化的錨點,您會得到一個錯誤。

為了完成我們黨額錨點系統,我們首先建立一個場景,我們把它設定為用於在我們的空間管理節點上實例化錨點的場景。

這個場景應該有一個 XRAnchor3D 節點,並且沒有其它任何東西。我們會給它新增一個腳本用於載入一個子場景,子場景包含我們的錨點的實際的視角,這樣我們就可以在場景中建立不同的錨點。我們假設這裡的意圖是要把這些錨點持久化,並且儲存這些子場景的路徑作為我們 UUID 的中繼資料。

class_name OpenXRSpatialAnchor3D
extends XRAnchor3D

var anchor_tracker: OpenXRAnchorTracker
var child_scene: Node
var made_persistent: bool = false

## Return the scene path for our UUID.
func get_scene_path(p_uuid: String) -> String:
    # Placeholder, implement this.
    return ""


## Store our scene path for our UUID.
func set_scene_path(p_uuid: String, p_scene_path: String):
    # Placeholder, implement this.
    pass


## Remove info related to our UUID.
func remove_uuid(p_uuid: String):
    # Placeholder, implement this.
    pass


## Set our child scene for this anchor, call this when creating a new anchor.
func set_child_scene(p_child_scene_path: String):
    var packed_scene: PackedScene = load(p_child_scene_path)
    if not packed_scene:
        return

    child_scene = packed_scene.instantiate()
    if not child_scene:
        return

    add_child(child_scene)


# Called when our tracking state changes.
func _on_spatial_tracking_state_changed(new_state) -> void:
    if new_state == OpenXRSpatialEntityTracker.ENTITY_TRACKING_STATE_TRACKING and not made_persistent:
        # Only attempt to do this once.
        made_persistent = true

        # This warning is optional if you don't want to rely on persistence.
        if not OpenXRSpatialAnchorCapability.is_spatial_persistence_supported():
            push_warning("Persistent spatial anchors are not supported on this device!")
            return

        # Make this persistent, this will notify that the UUID changed on the anchor,
        # we can then store our scene path which we've already applied to our
        # tracked scene.
        OpenXRSpatialAnchorCapability.persist_anchor(anchor_tracker, RID(), Callable())


func _on_uuid_changed() -> void:
    if anchor_tracker.uuid != "":
        made_persistent = true

        if child_scene:
            # If we already have a subscene, save that with the UUID.
            set_scene_path(anchor_tracker.uuid, child_scene.scene_file_path)
        else:
            # If we do not, look up the UUID in our stored cache.
            var scene_path: String = get_scene_path(anchor_tracker.uuid)
            if scene_path.is_empty():
                # Give a warning that we don't have a scene file stored for this UUID.
                push_warning("Unknown UUID given, can't determine child scene.")

                # Load a default scene so we can at least see something.
                set_child_scene("res://unknown_anchor.tscn")
                return

            set_child_scene(scene_path)


func _ready():
    anchor_tracker = XRServer.get_tracker(tracker)
    if anchor_tracker:
        _on_uuid_changed()

        anchor_tracker.spatial_tracking_state_changed.connect(_on_spatial_tracking_state_changed)
        anchor_tracker.uuid_changed.connect(_on_uuid_changed)

既然我們的錨點場景(anchor scene)已經準備就緒了,接下來就可以在空間管理器(spatial manager)的腳本里新增幾個函式,用來建立或移除錨點啦:

...

## Create a new spatial anchor with the associated child scene.
## If persistent anchors are supported, this will be created as a persistent node
## and we will store the child scene path with the anchor's UUID for future recreation.
func create_spatial_anchor(p_transform: Transform3D, p_child_scene_path: String):
    # Do we have anchor support?
    if not OpenXRSpatialAnchorCapability.is_spatial_anchor_supported():
        push_error("Spatial anchors are not supported on this device!")
        return

    # Adjust our transform to local space.
    var t: Transform3D = global_transform.inverse() * p_transform

    # Create anchor on our current manager.
    var new_anchor = OpenXRSpatialAnchorCapability.create_new_anchor(t, RID())
    if not new_anchor:
        push_error("Couldn't create an anchor for %s." % [ p_child_scene_path ])
        return

    # Creating a new anchor should have resulted in an XRAnchor being added to the scene
    # by our manager. We can thus continue assuming this has happened.

    var anchor_scene = get_tracked_scene(new_anchor)
    if not anchor_scene:
        push_error("Couldn't locate anchor scene for %s, has the manager been configured with an applicable anchor scene?" % [ new_anchor.name ])
        return
    if not anchor_scene is OpenXRSpatialAnchor3D:
        push_error("Anchor scene for %s is not an OpenXRSpatialAnchor3D scene, has the manager been configured with an applicable anchor scene?" % [ new_anchor.name ])
        return

    anchor_scene.set_child_scene(p_child_scene_path)


## Removes this spatial anchor from our scene.
## If the spatial anchor is persistent, the associated UUID will be cleared.
func remove_spatial_anchor(p_anchor: XRAnchor3D):
    # Do we have anchor support?
    if not OpenXRSpatialAnchorCapability.is_spatial_anchor_supported():
        push_error("Spatial anchors are not supported on this device!")
        return

    var tracker: XRTracker = XRServer.get_tracker(p_anchor.tracker)
    if tracker and tracker is OpenXRAnchorTracker:
        var anchor_tracker: OpenXRAnchorTracker = tracker
        if anchor_tracker.has_uuid() and OpenXRSpatialAnchorCapability.is_spatial_persistence_supported():
            # If we have a UUID we should first make the anchor unpersistent
            # and then remove it on its callback.
            remove_uuid(anchor_tracker.uuid)
            OpenXRSpatialAnchorCapability.unpersist_anchor(anchor_tracker, RID(), _on_unpersist_complete)
        else:
            # Otherwise we can just remove it.
            # This will remove it from the XRServer, which in turn will trigger cleaning up our node.
            OpenXRSpatialAnchorCapability.remove_anchor(tracker)


func _on_unpersist_complete(p_tracker: XRTracker):
    # Our tracker is now no longer persistent, we can remove it.
    OpenXRSpatialAnchorCapability.remove_anchor(p_tracker)


## Retrieve the scene we've added for a given tracker (if any).
func get_tracked_scene(p_tracker: XRTracker) -> XRNode3D:
    for node in get_children():
        if node is XRNode3D and node.tracker == p_tracker.name:
            return node

    return null

備註

上面的程式碼看起來好像有點‘魔法’在起作用。每當我們建立或移除一個空間錨點(spatial anchor)時,對應的追蹤器物件(tracker object)也會隨之被建立或銷毀。這樣一來,空間管理器(spatial manager)就會自動為這個錨點新增或移除對應的子場景。所以,我們在這裡完全可以放心地相依性這套機制。

平面追蹤

平面追蹤(Plane tracking)可檢測玩家附近的牆面、地面、天花板和桌面等表面。這些資料可能來自使用者過往任意時間執行的房間採集(room capture),也可能由光學傳感器即時檢測取得。平面追蹤擴充(plane tracking extension)對此不做區分。

備註

有些 XR 執行環境(XR runtimes)確實需要借助廠商的擴充介面,才能開啟和/或設定這一過程,但(最終取得到的)資料都會通過這個擴充介面暴露出來。

我們上面為空間管理器(spatial manager)寫的那些程式碼,已經能夠自動檢測到我們新建立的平面了。不過,我們還需要新建一個場景,並把這個場景指派給空間管理器。

該場景的根節點必須是一個 XRAnchor3D 節點。我們會新增一個 StaticBody3D 節點作為子節點,並新增一個 CollisionShape3D 和一個 MeshInstance3D 節點作為該靜態體的子節點。

../../_images/openxr_plane_anchor.webp

有了靜態剛體(StaticBody)和碰撞形狀(CollisionShape),我們就能讓這個平面具有可互動性啦。

該網格實例節點允許我們將一個“打孔”(hole punch)材質套用至平面上,與透視模式結合時,這會將我們的平面變成一個視覺遮擋器。或者,我們也可以指定一種材質來視覺化該平面,以便除錯。

我們把這個材質設為 MeshInstance3D 的 material_override 材質。對於我們的“打孔”材質("hole punch" material),建立一個 ShaderMaterial 並使用以下程式碼作為著色器程式碼:

shader_type spatial;
render_mode unshaded, shadow_to_opacity;

void fragment() {
    ALBEDO = vec3(0.0, 0.0, 0.0);
}

我們還需要向場景中新增一個腳本,來確保我們的碰撞和網格都已被應用。

extends XRAnchor3D

var plane_tracker: OpenXRPlaneTracker

func _update_mesh_and_collision():
    if plane_tracker:
        # Place our static body using our offset so both collision
        # and mesh are positioned correctly.
        $StaticBody3D.transform = plane_tracker.get_mesh_offset()

        # Set our mesh so we can occlude the surface.
        $StaticBody3D/MeshInstance3D.mesh = plane_tracker.get_mesh()

        # And set our shape so we can have things collide things with our surface.
        $StaticBody3D/CollisionShape3D.shape = plane_tracker.get_shape()


func _ready():
    plane_tracker = XRServer.get_tracker(tracker)
    if plane_tracker:
        _update_mesh_and_collision()

        plane_tracker.mesh_changed.connect(_update_mesh_and_collision)

如果 XR 執行時支援,你還可以在平面追蹤器物件上查詢額外的中繼資料。特別值得注意的是 plane_label 屬性,如果可用,它會標識表面的型別。請查閱 OpenXRPlaneTracker 類文件以取得更多資訊。

標記點追蹤

標記點追蹤可以檢測現實世界中的特定標記。這些標記通常是印刷影像,例如二維碼。

這個 API 開放了對 4 種不同碼的支援,分別是 QR 碼(也就是我們常說的二維碼)、Micro QR 碼、Aruco 碼以及 April 標籤。不過需要注意的是,並不是所有的 XR 執行環境(XR runtimes)都必須支援這全部 4 種碼。

在發現標記點時,將會實例化 OpenXRMarkerTracker 物件並向 XRServer 注冊。

我們現有的空間管理器程式碼已經能檢測到這些,我們只需建立一個以 XRAnchor3D 節點為根的場景,儲存它,然後將其分配給空間管理器,作為要針對標記實例化的場景。

標記追蹤器被分配時應已完全設定好,因此只需一個對標記資料做出響應的 _ready 函式 。以下是所需程式碼的範本:

extends XRAnchor3D

var marker_tracker: OpenXRMarkerTracker

func _ready():
    marker_tracker = XRServer.get_tracker(tracker)
    if marker_tracker:
        match marker_tracker.marker_type:
            OpenXRSpatialComponentMarkerList.MARKER_TYPE_QRCODE:
                var data = marker_tracker.get_marker_data()
                if data is String:
                    # Data is a QR code as a string, usually a URL.
                    pass
                elif data is PackedByteArray:
                    # Data is binary, can be anything.
                    pass
            OpenXRSpatialComponentMarkerList.MARKER_TYPE_MICRO_QRCODE:
                var data = marker_tracker.get_marker_data()
                if data is String:
                    # Data is a QR code as a string, usually a URL.
                    pass
                elif data is PackedByteArray:
                    # Data is binary, can be anything.
                    pass
            OpenXRSpatialComponentMarkerList.MARKER_TYPE_ARUCO:
                # Use marker_tracker.marker_id to identify the marker.
                pass
            OpenXRSpatialComponentMarkerList.MARKER_TYPE_APRIL_TAG:
                # Use marker_tracker.marker_id to identify the marker.
                pass

正如我們所看到的,二維碼提供一個資料塊,該資料塊可以是字串或位元組陣列。Aruco 和 April 標記則提供一個從標記中讀取的 ID。

如何將標記資料與需要載入的場景關聯起來,這取決於你的具體用例。一個例子是將你想要顯示的資源名稱編碼到二維碼中。

後端存取

對於大多數用途而言,核心系統連同所有廠商擴充,應該就是大多數使用者會直接拿來用的東西。

對於需要實作廠商擴充的人,或是內建邏輯無法滿足需求的人,可以通過一組單例物件來存取後端。

這些物件也可用於查詢目前使用的頭顯支援哪些功能。我們已經在上面各節的空間管理器和空間錨點程式碼中新增了相應的檢查。

備註

空間實體系統會將許多 OpenXR 實體封裝為以 RID 形式回傳的資源。

空間實體核心

可通過 OpenXRSpatialEntityExtension 單例實現底層存取。

特定邏輯通過能力層得以體現——這些能力引入了專用元件型別,並提供了對特定型別實體的存取權限;然而,所有這些能力均採用相同的機制來存取由空間實體系統管理的實體資料。

我們先來看看構成核心系統的各個元件。

空間情境(Spatial contexts)

空間情境是我們查詢空間實體系統的主要物件。空間情境允許我們設定如何與一個或多個能力進行互動。

建議為你想要互動的每個能力都建立一個空間情境;事實上,Godot 對其內建邏輯就是這麼做的。

我們首先為想要存取的能力設定能力設定物件。每個能力會啟用我們為該能力所支援的元件。設定可以決定哪些元件將被啟用。我們將在介紹每個支援的能力時,更詳細地瞭解這些設定物件。

建立空間情境是一個非同步操作。這意味著我們請求 XR 執行時建立一個空間情境,並在未來的某個時間點,XR 執行時會向我們提供結果。

以下腳本是我們範例的起始部分,可以將其作為節點新增到你的場景中。它展示了為平面追蹤建立空間情境,並設定我們的實體發現功能。

extends Node

var spatial_context: RID

func _set_up_spatial_context():
    # Already set up?
    if spatial_context:
        return

    # Not supported or we're not yet ready?
    if not OpenXRSpatialPlaneTrackingCapability.is_supported():
        return

    # We'll use plane tracking as an example here, our configuration object
    # here does not have any additional configuration. It just needs to exist.
    var plane_capability : OpenXRSpatialCapabilityConfigurationPlaneTracking = OpenXRSpatialCapabilityConfigurationPlaneTracking.new()

    var future_result : OpenXRFutureResult = OpenXRSpatialEntityExtension.create_spatial_context([ plane_capability ])

    # Wait for async completion.
    await future_result.completed

    # Obtain our result.
    spatial_context = future_result.get_spatial_context()
    if spatial_context:
        # Connect to our discovery signal.
        OpenXRSpatialEntityExtension.spatial_discovery_recommended.connect(_on_perform_discovery)

        # Perform our initial discovery.
        _on_perform_discovery(spatial_context)


func _enter_tree():
    var openxr_interface : OpenXRInterface = XRServer.find_interface("OpenXR")
    if openxr_interface and openxr_interface.is_initialized():
        # Just in case our session hasn't started yet,
        # call our spatial context creation on start.
        openxr_interface.session_begun.connect(_set_up_spatial_context)

        # And in case it is already up and running, call it already,
        # it will exit if we've called it too early.
        _set_up_spatial_context()


func _exit_tree():
    if spatial_context:
        # Disconnect from our discovery signal.
        OpenXRSpatialEntityExtension.spatial_discovery_recommended.disconnect(_on_perform_discovery)

        # Free our spatial context, this will clean it up.
        OpenXRSpatialEntityExtension.free_spatial_context(spatial_context)
        spatial_context = RID()

    var openxr_interface : OpenXRInterface = XRServer.find_interface("OpenXR")
    if openxr_interface and openxr_interface.is_initialized():
        openxr_interface.session_begun.disconnect(_set_up_spatial_context)


func _on_perform_discovery(p_spatial_context):
    # See next section.
    pass

發現狀態快照(Discovery snapshots)

一旦我們的空間情境建立完成,XR 執行時就會根據指定能力的設定,開始管理空間實體。

為了找到新的實體,或取得目前實體的資訊,我們可以建立一個發現快照(Discovery Snapshot)。這會告訴 XR 執行時去收集與空間情境目前管理的所有空間實體相關的特定資料。

此函式是非同步的,因為收集這些資料並回傳結果可能需要一些時間。一般來說,你會在發現新實體時執行一次發現快照(Discovery Snapshot )。OpenXR 在有新實體需要處理時會發出一個事件,這會導致我們的 OpenXRSpatialEntityExtension 單例發出 spatial_discovery_recommended 訊號。

請注意,在上面展示的範例程式碼中,我們已經連接了這個訊號,並在節點上呼叫了 _on_perform_discovery 方法。下面我們來具體實作它:

...

var discovery_result : OpenXRFutureResult

func _on_perform_discovery(p_spatial_context):
    # We get this signal for all spatial contexts, so exit if this is not for us.
    if p_spatial_context != spatial_context:
        return

    # If we currently have an ongoing discovery result, cancel it.
    if discovery_result:
        discovery_result.cancel_discovery()

    # Perform our discovery.
    discovery_result = OpenXRSpatialEntityExtension.discover_spatial_entities(spatial_context, [ \
            OpenXRSpatialEntityExtension.COMPONENT_TYPE_BOUNDED_2D, \
            OpenXRSpatialEntityExtension.COMPONENT_TYPE_PLANE_ALIGNMENT \
        ])

    # Wait for async completion.
    await discovery_result.completed

    var snapshot : RID = discovery_result.get_spatial_snapshot()
    if snapshot:
        # Process our snapshot result.
        _process_snapshot(snapshot)

        # And clean up our snapshot.
        OpenXRSpatialEntityExtension.free_spatial_snapshot(snapshot)


func _process_snapshot(p_snapshot):
    # See further down.
    pass

請注意,在呼叫 discover_spatial_entities 時,我們指定了一個元件清單。這個發現查詢會找到任何由該空間情境管理、且至少擁有其中一個指定元件的實體。

更新快照(Update snapshots)

執行更新快照可以讓我們取得之前通過發現快照已找到的實體的更新資訊。此函式是同步的,主要用於取得狀態和定位資料,並且可以每影格執行。

一般來說,你只應在實體可能發生變化或具有生命週期過程時執行更新快照。持久化錨點和標記就是很好的例子。請查閱相關能力的文件,以確定是否需要這樣做。

不過,為了完成我們的範例,平面追蹤並不需要更新快照。這裡是一個範例,展示如果我們需要為平面追蹤執行更新快照的話,程式碼會是甚麼樣子:

...

func _process(_delta):
    if not spatial_context:
        return

    if entities.is_empty():
        return

    var entity_rids: Array[RID]
    for entity_id in entities:
        entity_rids.push_back(entities[entity_id].entity)

    var snapshot : RID = OpenXRSpatialEntityExtension.update_spatial_entities(spatial_context, entity_rids, [ \
            OpenXRSpatialEntityExtension.COMPONENT_TYPE_BOUNDED_2D, \
            OpenXRSpatialEntityExtension.COMPONENT_TYPE_PLANE_ALIGNMENT \
        ])
    if snapshot:
        # Process our snapshot.
        _process_snapshot(snapshot)

        # And clean up our snapshot.
        OpenXRSpatialEntityExtension.free_spatial_snapshot(snapshot)

請注意,在這個範例中,我們使用同一個 _process_snapshot 函式來處理快照。這在大多數情況下是合理的。但是,如果你在建立發現快照和更新快照時所指定的元件不同,就需要將這些不同的元件考慮在內。

查詢快照(Querying snapshots)

一旦我們有了快照,就可以對該快照執行查詢以取得其中包含的資料。在你釋放該快照之前,它保證保持不變。

對於我們新增到快照中的每個元件,都有一個對應的資料物件。這個資料物件有雙重作用:將它新增到查詢中可確保我們會查詢該元件型別,同時它也是查詢到的資料載入的目標物件。

有一個特殊的資料物件必須始終作為第一項新增到我們的請求清單中,那就是 OpenXRSpatialQueryResultData 。這個物件將為每個回傳的實體儲存一條記錄,包含其唯一 ID 和實體的目前狀態。

為完成我們的發現邏輯,我們新增以下內容:

...

var entities : Dictionary[int, OpenXRSpatialEntityTracker]

func _process_snapshot(p_snapshot):
    # Always include our query result data.
    var query_result_data : OpenXRSpatialQueryResultData = OpenXRSpatialQueryResultData.new()

    # Add our bounded 2D component data.
    var bounded2d_list : OpenXRSpatialComponentBounded2DList = OpenXRSpatialComponentBounded2DList.new()

    # And our plane alignment component data.
    var alignment_list : OpenXRSpatialComponentPlaneAlignmentList = OpenXRSpatialComponentPlaneAlignmentList.new()

    if OpenXRSpatialEntityExtension.query_snapshot(p_snapshot, [ query_result_data, bounded2d_list, alignment_list]):
        for i in query_result_data.get_entity_id_size():
            var entity_id = query_result_data.get_entity_id(i)
            var entity_state = query_result_data.get_entity_state(i)

            if entity_state == OpenXRSpatialEntityTracker.ENTITY_TRACKING_STATE_STOPPED:
                # This state should only appear when doing an update snapshot
                # and tells us this entity is no longer tracked.
                # We thus remove it from our dictionary which should result
                # in the entity being cleaned up.
                if entities.has(entity_id):
                    var entity_tracker : OpenXRSpatialEntityTracker = entities[entity_id]
                    entity_tracker.spatial_tracking_state = entity_state
                    XRServer.remove_tracker(entity_tracker)
                    entities.erase(entity_id)
            else:
                var entity_tracker : OpenXRSpatialEntityTracker
                var register_with_xr_server : bool = false
                if entities.has(entity_id):
                    entity_tracker = entities[entity_id]
                else:
                    entity_tracker = OpenXRSpatialEntityTracker.new()
                    entity_tracker.entity = OpenXRSpatialEntityExtension.make_spatial_entity(spatial_context, entity_id)
                    entities[entity_id] = entity_tracker
                    register_with_xr_server = true

                # Copy the state.
                entity_tracker.spatial_tracking_state = entity_state

                # If we're tracking, we should query the rest of our components.
                if entity_state == OpenXRSpatialEntityTracker.ENTITY_TRACKING_STATE_TRACKING:
                    var center_pose : Transform3D = bounded2d_list.get_center_pose(i)
                    entity_tracker.set_pose("default", center_pose, Vector3(), Vector3(), XRPose.XR_TRACKING_CONFIDENCE_HIGH)

                    # For this example I'm using OpenXRSpatialEntityTracker which does not
                    # hold further data. You should extend this class to store the additional
                    # state retrieved. For plane tracking this would be OpenXRPlaneTracker
                    # and we can store the following data in the tracker:
                    var size : Vector2 = bounded2d_list.get_size(i)
                    var alignment = alignment_list.get_plane_alignment(i)
                else:
                    entity_tracker.invalidate_pose("default")

                # We don't register our tracker until after we've set our initial data.
                if register_with_xr_server:
                    XRServer.add_tracker(entity_tracker)

備註

在上面的範例中,我們相依性 ENTITY_TRACKING_STATE_STOPPED 來清理不再被追蹤的空間實體。這僅適用於更新快照。

對於僅相依性發現快照的能力,你可能希望基於不再屬於快照的實體來執行清理,而不是相依性狀態變化。

空間實體

根據以上資訊,我們現在知道如何查詢空間實體並取得其相關資訊了,但關於實體本身,還有一些內容需要瞭解。

理論上,我們是從快照中取得所有資料的,但 OpenXR 還提供了一個額外的 API,讓我們可以通過實體 ID 來建立空間實體物件。只要這個物件存在,XR 執行時就知道我們正在使用該實體,而不會過早清理該實體。這是對該實體執行更新查詢的前提條件。

在我們的範例程式碼中,我們通過呼叫 OpenXRSpatialEntityExtension.make_spatial_entity 來實現這一點。

有些空間實體 API 會自動為我們建立物件。在這種情況下,我們需要呼叫 OpenXRSpatialEntityExtension.add_spatial_entity 將建立好的物件注冊到我們的實作中。

這兩個函式都會回傳一個 RID,我們可以在後續需要實體物件的函式中使用它。

使用完畢後,我們可以呼叫 OpenXRSpatialEntityExtension.free_spatial_entity 。

請注意,我們在範例程式碼中並沒有這樣做。當我們的 OpenXRSpatialEntityTracker 實例被銷毀時,這會自動處理。

空間錨點功能

空間錨點(Spatial anchors)是由我們的 OpenXRSpatialAnchorCapability 單例物件來管理的。在 OpenXR 會話(session)建立完成後,你可以呼叫 OpenXRSpatialAnchorCapability.is_spatial_anchor_supported 來檢測你的硬體裝置是否支援空間錨點功能。

空間錨點功能和我們上面展示的內容相比,稍微有點“不按套路出牌”(或者說有些與眾不同)。

空間錨點系統讓我們能夠識別、追蹤、持久化儲存以及共享一個物理位置。而它與眾不同的地方在於,我們需要親自建立和銷毀錨點,也就是說,我們要負責管理它的整個生命週期。

因此,我們只是利用發現系統來尋找那些在之前的會話中建立並持久化儲存的錨點,或者是別人共享給我們的錨點。

備註

空間實體(spatial entities)規範目前還不支援錨點共享功能。

正如我們之前例子里展示的,我們總是要從建立一個空間情境(spatial context)開始。不過這一次,我們要用的是 OpenXRSpatialCapabilityConfigurationAnchor 這個設定物件。關於這段程式碼的具體範例,我們等聊完“持久化範圍”(persistence scopes)之後再展示。接下來,我們先來看看如何管理本機錨點。

建立空間錨點的過程,和我們之前討論內建邏輯時的操作並沒有甚麼不同。唯一需要特別注意的是,在呼叫 OpenXRSpatialAnchorCapability.create_new_anchor 這個方法時,記得把你自己的空間情境(spatial context)作為參數傳進去。

讓錨點持久化需要你先等待,直到它進入“正在追蹤”(tracking)的狀態。這意味著,對於你建立的每一個錨點,都必須不斷地進行更新查詢(update queries),這樣你才能及時捕捉並處理它的狀態變化。

想要讓錨點能夠持久化儲存,你還得先設定一個“持久化範圍”(persistence scope)。在 OpenXR 的核心規範中,目前支援兩種型別的持久化範圍:

持久化範圍

列舉

說明

PERSISTENCE_SCOPE_SYSTEM_MANAGED

它為應用提供了對系統持久化並管理的空間實體的只讀存取權限(也就是說,應用無法修改這個儲存空間)。應用可以利用該儲存空間中持久化元件里的 UUID(通用唯一識別碼),在不同的空間情境以及裝置重啓後,來關聯對應的實體。

PERSISTENCE_SCOPE_LOCAL_ANCHORS

持久化操作與資料存取僅限於同一裝置、同一使用者及同一應用程式下的空間錨點(使用 persist_anchor() 和 unpersist_anchor() 函式)

我們將從一個新的腳本開始,這個腳本專門用來處理我們的空間錨點。它和我們之前展示的那個腳本很像,不過會有一些小小的不同。

首先,是建立我們的持久化範圍。

extends Node

var persistence_context : RID

func _set_up_persistence_context():
    # Already set up?
    if persistence_context:
        # Check our spatial context.
        _set_up_spatial_context()
        return

    # Not supported or we're not yet ready? Just exit.
    if not OpenXRSpatialAnchorCapability.is_spatial_anchor_supported():
        return

    # If we can't use a persistence scope, just create our spatial context without one.
    if not OpenXRSpatialAnchorCapability.is_spatial_persistence_supported():
        _set_up_spatial_context()
        return

    var scope : int = 0
    if OpenXRSpatialAnchorCapability.is_persistence_scope_supported(OpenXRSpatialAnchorCapability.PERSISTENCE_SCOPE_LOCAL_ANCHORS):
        scope = OpenXRSpatialAnchorCapability.PERSISTENCE_SCOPE_LOCAL_ANCHORS
    elif OpenXRSpatialAnchorCapability.is_persistence_scope_supported(OpenXRSpatialAnchorCapability.PERSISTENCE_SCOPE_SYSTEM_MANAGED):
        scope = OpenXRSpatialAnchorCapability.PERSISTENCE_SCOPE_SYSTEM_MANAGED
    else:
        # Don't have a known persistence scope, report and just set up without it.
        push_error("No known persistence scope is supported.")
        _set_up_spatial_context()
        return

    # Create our persistence scope.
    var future_result : OpenXRFutureResult = OpenXRSpatialAnchorCapability.create_persistence_context(scope)
    if not future:
        # Couldn't create persistence scope? Just set up without it.
        _set_up_spatial_context()
        return

    # Now wait for our process to complete.
    await future_result.completed

    # Get our result.
    persistence_context = future_result.get_result()
    if persistence_context:
        # Now set up our spatial context.
        _set_up_spatial_context()


func _enter_tree():
    var openxr_interface : OpenXRInterface = XRServer.find_interface("OpenXR")
    if openxr_interface and openxr_interface.is_initialized():
        # Just in case our session hasn't started yet,
        # call our context creation on start beginning with our persistence scope.
        openxr_interface.session_begun.connect(_set_up_persistence_context)

        # And in case it is already up and running, call it already,
        # it will exit if we've called it too early.
        _set_up_persistence_context()


func _exit_tree():
    if spatial_context:
        # Disconnect from our discovery signal.
        OpenXRSpatialEntityExtension.spatial_discovery_recommended.disconnect(_on_perform_discovery)

        # Free our spatial context, this will clean it up.
        OpenXRSpatialEntityExtension.free_spatial_context(spatial_context)
        spatial_context = RID()

    if persistence_context:
        # Free our persistence context...
        OpenXRSpatialAnchorCapability.free_persistence_context(persistence_context)
        persistence_context = RID()

    var openxr_interface : OpenXRInterface = XRServer.find_interface("OpenXR")
    if openxr_interface and openxr_interface.is_initialized():
        openxr_interface.session_begun.disconnect(_set_up_persistence_context)

建立好持久化範圍後,我們現在就可以建立空間情境了。

...

var spatial_context: RID

func _set_up_spatial_context():
    # Already set up?
    if spatial_context:
        return

    # Not supported or we're not yet set up.
    if not OpenXRSpatialAnchorCapability.is_spatial_anchor_supported():
        return

    # Create our anchor capability.
    var anchor_capability : OpenXRSpatialCapabilityConfigurationAnchor = OpenXRSpatialCapabilityConfigurationAnchor.new()

    # And set up our persistence configuration object (if needed).
    var persistence_config : OpenXRSpatialContextPersistenceConfig
    if persistence_context:
        persistence_config = OpenXRSpatialContextPersistenceConfig.new()
        persistence_config.add_persistence_context(persistence_context)

    var future_result : OpenXRFutureResultg = OpenXRSpatialEntityExtension.create_spatial_context([ anchor_capability ], persistence_config)

    # Wait for async completion.
    await future_result.completed

    # Obtain our result.
    spatial_context = future_result.get_spatial_context()
    if spatial_context:
        # Connect to our discovery signal.
        OpenXRSpatialEntityExtension.spatial_discovery_recommended.connect(_on_perform_discovery)

        # Perform our initial discovery.
        _on_perform_discovery(spatial_context)

為我們錨點建立“發現快照”的過程,和之前做的幾乎一樣。不過,這次只為持久化錨點(persistent anchors)建立快照才有意義。因為我們自己在這次會話(session)中建立的錨點,自己都心裡有數,我們真正想要的,其實是去取得那些來自 XR 執行時(XR runtime)的錨點。

我們還需要定期執行更新查詢。不過,在這裡我們只關心錨點的“狀態”,所以我們處理快照的方式會和之前稍微有點不一樣。

錨點系統讓我們可以存取兩個元件:

錨點元件

Component

Data 類

說明

COMPONENT_TYPE_ANCHOR

OpenXRSpatialComponentAnchorList

它為我們提供了每個錨點的位姿(即位置 + 方向)

COMPONENT_TYPE_PERSISTENCE

OpenXRSpatialComponentPersistenceList

它為我們提供了每個錨點的持久化狀態和 UUID(通用唯一識別碼

...

var discovery_result : OpenXRFutureResult
var entities : Dictionary[int, OpenXRAnchorTracker]

func _on_perform_discovery(p_spatial_context):
    # We get this signal for all spatial contexts, so exit if this is not for us.
    if p_spatial_context != spatial_context:
        return

    # Skip this if we don't have a persistence context.
    if not persistence_context:
        return

    # If we currently have an ongoing discovery result, cancel it.
    if discovery_result:
        discovery_result.cancel_discovery()

    # Perform our discovery.
    discovery_result = OpenXRSpatialEntityExtension.discover_spatial_entities(spatial_context, [ \
            OpenXRSpatialEntityExtension.COMPONENT_TYPE_ANCHOR, \
            OpenXRSpatialEntityExtension.COMPONENT_TYPE_PERSISTENCE \
        ])

    # Wait for async completion.
    await discovery_result.completed

    var snapshot : RID = discovery_result.get_spatial_snapshot()
    if snapshot:
        # Process our snapshot result.
        _process_snapshot(snapshot, true)

        # And clean up our snapshot.
        OpenXRSpatialEntityExtension.free_spatial_snapshot(snapshot)


func _process(_delta):
    if not spatial_context:
        return

    if entities.is_empty():
        return

    var entity_rids: Array[RID]
    for entity_id in entities:
        entity_rids.push_back(entities[entity_id].entity)

    # We just want our anchor component here.
    var snapshot : RID = OpenXRSpatialEntityExtension.update_spatial_entities(spatial_context, entity_rids, [ \
            OpenXRSpatialEntityExtension.COMPONENT_TYPE_ANCHOR, \
        ])
    if snapshot:
        # Process our snapshot.
        _process_snapshot(snapshot)

        # And clean up our snapshot.
        OpenXRSpatialEntityExtension.free_spatial_snapshot(snapshot)


func _process_snapshot(p_snapshot, p_get_uuids):
    pass

最後,我們可以來處理我們的快照(snapshot)了。注意,這裡我們使用的是 OpenXRAnchorTracker 作為我們的追蹤器類,因為這個類已經內建了對空間錨(anchors)的全部支援。

...

func _process_snapshot(p_snapshot, p_get_uuids):
    var result_data : Array

    # Always include our query result data.
    var query_result_data : OpenXRSpatialQueryResultData = OpenXRSpatialQueryResultData.new()
    result_data.push_back(query_result_data)

    # Add our anchor component data.
    var anchor_list : OpenXRSpatialComponentAnchorList = OpenXRSpatialComponentAnchorList.new()
    result_data.push_back(anchor_list)

    # And our persistent component data.
    var persistent_list : OpenXRSpatialComponentPersistenceList
    if p_get_uuids:
        # Only add this when we need it.
        persistent_list = OpenXRSpatialComponentPersistenceList.new()
        result_data.push_back(persistent_list)

    if OpenXRSpatialEntityExtension.query_snapshot(p_snapshot, result_data):
        for i in query_result_data.get_entity_id_size():
            var entity_id = query_result_data.get_entity_id(i)
            var entity_state = query_result_data.get_entity_state(i)

            if entity_state == OpenXRSpatialEntityTracker.ENTITY_TRACKING_STATE_STOPPED:
                # This state should only appear when doing an update snapshot
                # and tells us this entity is no longer tracked.
                # We thus remove it from our dictionary which should result
                # in the entity being cleaned up.
                if entities.has(entity_id):
                    var entity_tracker : OpenXRAnchorTracker = entities[entity_id]
                    entity_tracker.spatial_tracking_state = entity_state
                    XRServer.remove_tracker(entity_tracker)
                    entities.erase(entity_id)
            else:
                var entity_tracker : OpenXRAnchorTracker
                var register_with_xr_server : bool = false
                if entities.has(entity_id):
                    entity_tracker = entities[entity_id]
                else:
                    entity_tracker = OpenXRAnchorTracker.new()
                    entity_tracker.entity = OpenXRSpatialEntityExtension.make_spatial_entity(spatial_context, entity_id)
                    entities[entity_id] = entity_tracker
                    register_with_xr_server = true

                # Copy the state.
                entity_tracker.spatial_tracking_state = entity_state

                # If we're tracking, we update our position.
                if entity_state == OpenXRSpatialEntityTracker.ENTITY_TRACKING_STATE_TRACKING:
                    var anchor_transform = anchor_list.get_entity_pose(i)
                    entity_tracker.set_pose("default", anchor_transform, Vector3(), Vector3(), XRPose.XR_TRACKING_CONFIDENCE_HIGH)
                else:
                    entity_tracker.invalidate_pose("default")

                # But persistence data is a big exception, it can be provided even if we're not tracking.
                if p_get_uuids:
                    var persistent_state = persistent_list.get_persistent_state(i)
                    if persistent_state == 1:
                        entity_tracker.uuid = persistent_list.get_persistent_uuid(i)

                # We don't register our tracker until after we've set our initial data.
                if register_with_xr_server:
                    XRServer.add_tracker(entity_tracker)

平面追蹤能力

平面追蹤(Plane tracking)是由 OpenXRSpatialPlaneTrackingCapability 這個單例(singleton)類來處理的。

在建立完 OpenXR 會話(session)之後,你就可以呼叫 OpenXRSpatialPlaneTrackingCapability.is_supported 來檢查你的硬體裝置是否支援平面追蹤功能啦。

雖然我們在上面已經提供了平面追蹤的大部分程式碼,但下面還是會展示完整的實作,因為裡面做了一些小的調整。在這裡不需要持續更新快照,我們只需要做一次發現快照,然後實作我們的處理函式就行了。

平面追蹤功能提供了兩個保證支援的元件,以及三個可選的元件。

平面追蹤元件

Component

Data 類

說明

COMPONENT_TYPE_BOUNDED_2D

OpenXRSpatialComponentBounded2DList

它為我們提供了每個平面的中心位姿和邊界矩形。

COMPONENT_TYPE_PLANE_ALIGNMENT

OpenXRSpatialComponentPlaneAlignmentList

為我們提供了每個平面的對齊方向

COMPONENT_TYPE_MESH_2D

OpenXRSpatialComponentMesh2DList

為我們提供了一個用來勾勒每個平面形狀的 2D 網格(Mesh)

COMPONENT_TYPE_POLYGON_2D

OpenXRSpatialComponentPolygon2DList

為我們提供了一個用來勾勒每個平面形狀的 2D 多邊形(Polygon)

COMPONENT_TYPE_PLANE_SEMANTIC_LABEL

OpenXRSpatialComponentPlaneSemanticLabelList

告訴我們識別出來的每個平面具體屬於甚麼型別

我們的平面追蹤設定物件已經啟用了所有受支援的元件,但為了能夠查詢(或檢查)這些元件,我們需要將設定物件的實例儲存到一個成員變數中。我們可以使用 OpenXRPlaneTracker 追蹤器物件來儲存這些元件的資料。

extends Node

var plane_capability : OpenXRSpatialCapabilityConfigurationPlaneTracking
var spatial_context: RID
var discovery_result : OpenXRFutureResult
var entities : Dictionary[int, OpenXRPlaneTracker]

func _set_up_spatial_context():
    # Already set up?
    if spatial_context:
        return

    # Not supported or we're not yet ready?
    if not OpenXRSpatialPlaneTrackingCapability.is_supported():
        return

    # We'll use plane tracking as an example here, our configuration object
    # here does not have any additional configuration. It just needs to exist.
    plane_capability = OpenXRSpatialCapabilityConfigurationPlaneTracking.new()

    var future_result : OpenXRFutureResult = OpenXRSpatialEntityExtension.create_spatial_context([ plane_capability ])

    # Wait for async completion.
    await future_result.completed

    # Obtain our result.
    spatial_context = future_result.get_spatial_context()
    if spatial_context:
        # Connect to our discovery signal.
        OpenXRSpatialEntityExtension.spatial_discovery_recommended.connect(_on_perform_discovery)

        # Perform our initial discovery.
        _on_perform_discovery(spatial_context)


func _enter_tree():
    var openxr_interface : OpenXRInterface = XRServer.find_interface("OpenXR")
    if openxr_interface and openxr_interface.is_initialized():
        # Just in case our session hasn't started yet,
        # call our spatial context creation on start.
        openxr_interface.session_begun.connect(_set_up_spatial_context)

        # And in case it is already up and running, call it already,
        # it will exit if we've called it too early.
        _set_up_spatial_context()


func _exit_tree():
    if spatial_context:
        # Disconnect from our discovery signal.
        OpenXRSpatialEntityExtension.spatial_discovery_recommended.disconnect(_on_perform_discovery)

        # Free our spatial context, this will clean it up.
        OpenXRSpatialEntityExtension.free_spatial_context(spatial_context)
        spatial_context = RID()

    var openxr_interface : OpenXRInterface = XRServer.find_interface("OpenXR")
    if openxr_interface and openxr_interface.is_initialized():
        openxr_interface.session_begun.disconnect(_set_up_spatial_context)


func _on_perform_discovery(p_spatial_context):
    # We get this signal for all spatial contexts, so exit if this is not for us.
    if p_spatial_context != spatial_context:
        return

    # If we currently have an ongoing discovery result, cancel it.
    if discovery_result:
        discovery_result.cancel_discovery()

    # Perform our discovery.
    discovery_result = OpenXRSpatialEntityExtension.discover_spatial_entities(spatial_context, \
            plane_capability.get_enabled_components())

    # Wait for async completion.
    await discovery_result.completed

    var snapshot : RID = discovery_result.get_spatial_snapshot()
    if snapshot:
        # Process our snapshot result.
        _process_snapshot(snapshot)

        # And clean up our snapshot.
        OpenXRSpatialEntityExtension.free_spatial_snapshot(snapshot)


func _process_snapshot(p_snapshot):
    var result_data : Array

    # Make a copy of the entities we've currently found.
    var org_entities : PackedInt64Array
    for entity_id in entities:
        org_entities.push_back(entity_id)

    # Always include our query result data.
    var query_result_data : OpenXRSpatialQueryResultData = OpenXRSpatialQueryResultData.new()
    result_data.push_back(query_result_data)

    # Add our bounded 2D component data.
    var bounded2d_list : OpenXRSpatialComponentBounded2DList = OpenXRSpatialComponentBounded2DList.new()
    result_data.push_back(bounded2d_list)

    # And our plane alignment component data.
    var alignment_list : OpenXRSpatialComponentPlaneAlignmentList = OpenXRSpatialComponentPlaneAlignmentList.new()
    result_data.push_back(alignment_list)

    # We need either a Mesh2D or a Polygon2D, we don't need both.
    var mesh2d_list : OpenXRSpatialComponentMesh2DList
    var polygon2d_list : OpenXRSpatialComponentPolygon2DList
    if plane_capability.get_supports_mesh_2d():
        mesh2d_list = OpenXRSpatialComponentMesh2DList.new()
        result_data.push_back(mesh2d_list)
    elif plane_capability.get_supports_polygons():
        polygon2d_list = OpenXRSpatialComponentPolygon2DList.new()
        result_data.push_back(polygon2d_list)

    # And add our semantic labels if supported.
    var label_list : OpenXRSpatialComponentPlaneSemanticLabelList
    if plane_capability.get_supports_labels():
        label_list = OpenXRSpatialComponentPlaneSemanticLabelList.new()
        result_data.push_back(label_list)

    if OpenXRSpatialEntityExtension.query_snapshot(p_snapshot, result_data):
        for i in query_result_data.get_entity_id_size():
            var entity_id = query_result_data.get_entity_id(i)
            var entity_state = query_result_data.get_entity_state(i)

            # Remove the entity from our original list.
            if org_entities.has(entity_id):
                org_entities.erase(entity_id)

            if entity_state == OpenXRSpatialEntityTracker.ENTITY_TRACKING_STATE_STOPPED:
                # We're not doing update snapshots so we shouldn't get this,
                # but just to future proof:
                if entities.has(entity_id):
                    var entity_tracker : OpenXRPlaneTracker = entities[entity_id]
                    entity_tracker.spatial_tracking_state = entity_state
                    XRServer.remove_tracker(entity_tracker)
                    entities.erase(entity_id)
            else:
                var entity_tracker : OpenXRPlaneTracker
                var register_with_xr_server : bool = false
                if entities.has(entity_id):
                    entity_tracker = entities[entity_id]
                else:
                    entity_tracker = OpenXRPlaneTracker.new()
                    entity_tracker.entity = OpenXRSpatialEntityExtension.make_spatial_entity(spatial_context, entity_id)
                    entities[entity_id] = entity_tracker
                    register_with_xr_server = true

                # Copy the state.
                entity_tracker.spatial_tracking_state = entity_state

                # If we're tracking, we should query the rest of our components.
                if entity_state == OpenXRSpatialEntityTracker.ENTITY_TRACKING_STATE_TRACKING:
                    var center_pose : Transform3D = bounded2d_list.get_center_pose(i)
                    entity_tracker.set_pose("default", center_pose, Vector3(), Vector3(), XRPose.XR_TRACKING_CONFIDENCE_HIGH)

                    entity_tracker.bounds_size = bounded2d_list.get_size(i)
                    entity_tracker.plane_alignment = alignment_list.get_plane_alignment(i)

                    if mesh2d_list:
                        entity_tracker.set_mesh_data( \
                                mesh2d_list.get_transform(i), \
                                mesh2d_list.get_vertices(p_snapshot, i), \
                                mesh2d_list.get_indices(p_snapshot, i))
                    elif polygon2d_list:
                        # The logic in our tracker will convert the polygon to a mesh.
                        entity_tracker.set_mesh_data( \
                                polygon2d_list.get_transform(i), \
                                polygon2d_list.get_vertices(p_snapshot, i))
                    else:
                        entity_tracker.clear_mesh_data()

                    if label_list:
                        entity_tracker.plane_label = label_list.get_plane_semantic_label(i)
                else:
                    entity_tracker.invalidate_pose("default")

                # We don't register our tracker until after we've set our initial data.
                if register_with_xr_server:
                    XRServer.add_tracker(entity_tracker)

    # Any entities we've got left over, we can remove.
    for entity_id in org_entities:
        var entity_tracker : OpenXRPlaneTracker = entities[entity_id]
        entity_tracker.spatial_tracking_state = OpenXRSpatialEntityTracker.ENTITY_TRACKING_STATE_STOPPED
        XRServer.remove_tracker(entity_tracker)
        entities.erase(entity_id)

標記追蹤能力

標記追蹤功能是由 OpenXRSpatialMarkerTrackingCapability 這個單例類來處理的。

標記追蹤的工作原理和平面追蹤非常相似,不過現在我們追蹤的是現實世界中特定的實體,依據的是印在物體(比如一張紙)上的特定編碼。

標記追蹤有多種不同的選項。OpenXR 原生支援其中的 4 種,下表提供了更多詳細資訊,以及用於檢查你的頭顯裝置是否支援特定選項的函式名稱:

標記追蹤選項

最佳化

檢查支援情況

設定物件

April 標籤

is_april_tag_supported

OpenXRSpatialCapabilityConfigurationAprilTag

Aruco

is_aruco_supported

OpenXRSpatialCapabilityConfigurationAruco

二維碼

is_qrcode_supported

OpenXRSpatialCapabilityConfigurationQrCode

微型二維碼

is_micro_qrcode_supported

OpenXRSpatialCapabilityConfigurationMicroQrCode

每個選項都有它專屬的設定物件,你可以在建立空間實體(spatial entity)的時候來使用它。

二維碼(QR codes)允許你編碼一段字串,這段字串會被 XR 執行時解碼,並在檢測到標記時直接取得。而對於 AprilTag 和 Aruco 標記,它們編碼的是二進位資料,你同樣可以在檢測到標記時存取這些資料,不過你需要使用正確的解碼格式來設定檢測系統。

舉個例子,我們將建立一個空間情境(spatial context),用來尋找二維碼和 Aruco 標記。

extends Node

var qrcode_config : OpenXRSpatialCapabilityConfigurationQrCode
var aruco_config : OpenXRSpatialCapabilityConfigurationAruco
var spatial_context: RID

func _set_up_spatial_context():
    # Already set up?
    if spatial_context:
        return

    var configurations : Array

    # Add our QR code configuration.
    if not OpenXRSpatialMarkerTrackingCapability.is_qrcode_supported():
        qrcode_config = OpenXRSpatialCapabilityConfigurationQrCode.new()
        configurations.push_back(qrcode_config)

    # Add our Aruco marker configuration.
    if not OpenXRSpatialMarkerTrackingCapability.is_aruco_supported():
        aruco_config = OpenXRSpatialCapabilityConfigurationAruco.new()
        aruco_config.aruco_dict = OpenXRSpatialCapabilityConfigurationAruco.ARUCO_DICT_7X7_1000
        configurations.push_back(aruco_config)

    # Nothing supported?
    if configurations.is_empty():
        return

    var future_result : OpenXRFutureResult = OpenXRSpatialEntityExtension.create_spatial_context(configurations)

    # Wait for async completion.
    await future_result.completed

    # Obtain our result.
    spatial_context = future_result.get_spatial_context()
    if spatial_context:
        # Connect to our discovery signal.
        OpenXRSpatialEntityExtension.spatial_discovery_recommended.connect(_on_perform_discovery)

        # Perform our initial discovery.
        _on_perform_discovery(spatial_context)


func _enter_tree():
    var openxr_interface : OpenXRInterface = XRServer.find_interface("OpenXR")
    if openxr_interface and openxr_interface.is_initialized():
        # Just in case our session hasn't started yet,
        # call our spatial context creation on start.
        openxr_interface.session_begun.connect(_set_up_spatial_context)

        # And in case it is already up and running, call it already,
        # it will exit if we've called it too early.
        _set_up_spatial_context()


func _exit_tree():
    if spatial_context:
        # Disconnect from our discovery signal.
        OpenXRSpatialEntityExtension.spatial_discovery_recommended.disconnect(_on_perform_discovery)

        # Free our spatial context, this will clean it up.
        OpenXRSpatialEntityExtension.free_spatial_context(spatial_context)
        spatial_context = RID()

    var openxr_interface : OpenXRInterface = XRServer.find_interface("OpenXR")
    if openxr_interface and openxr_interface.is_initialized():
        openxr_interface.session_begun.disconnect(_set_up_spatial_context)

無論是甚麼型別的標記,每一個標記都會由兩個部分組成。

標記點追蹤元件

Component

Data 類

說明

COMPONENT_TYPE_MARKER

OpenXRSpatialComponentMarkerList

它為我們提供了每個標記的型別、ID(針對 Aruco 和 AprilTag 標記)以及/或者資料(針對二維碼)。

COMPONENT_TYPE_BOUNDED_2D

OpenXRSpatialComponentBounded2DList

它為我們提供了每個平面的中心位姿和邊界矩形。

我們新增了我們的發現實作方案:

...

var discovery_result : OpenXRFutureResult
var entities : Dictionary[int, OpenXRMarkerTracker]

func _on_perform_discovery(p_spatial_context):
    # We get this signal for all spatial contexts, so exit if this is not for us.
    if p_spatial_context != spatial_context:
        return

    # If we currently have an ongoing discovery result, cancel it.
    if discovery_result:
        discovery_result.cancel_discovery()

    # Perform our discovery.
    discovery_result = OpenXRSpatialEntityExtension.discover_spatial_entities(spatial_context, [\
            OpenXRSpatialEntityExtension.COMPONENT_TYPE_MARKER, \
            OpenXRSpatialEntityExtension.COMPONENT_TYPE_BOUNDED_2D \
        ])

    # Wait for async completion.
    await discovery_result.completed

    var snapshot : RID = discovery_result.get_spatial_snapshot()
    if snapshot:
        # Process our snapshot result.
        _process_snapshot(snapshot, true)

        # And clean up our snapshot.
        OpenXRSpatialEntityExtension.free_spatial_snapshot(snapshot)


func _process_snapshot(p_snapshot, bool p_is_discovery):
    var result_data : Array

    # Make a copy of the entities we've currently found.
    var org_entities : PackedInt64Array
    if p_is_discovery:
        # Only on discovery will we check if we have untracked entities to clean up.
        for entity_id in entities:
            org_entities.push_back(entity_id)

    # Always include our query result data.
    var query_result_data : OpenXRSpatialQueryResultData = OpenXRSpatialQueryResultData.new()
    result_data.push_back(query_result_data)

    # And our marker component data.
    var marker_list : OpenXRSpatialComponentMarkerList
    if p_is_discovery:
        # Only on discovery do we check our marker data
        marker_list = OpenXRSpatialComponentMarkerList.new()
        result_data.push_back(marker_list)

    # Add our bounded 2D component data.
    var bounded2d_list : OpenXRSpatialComponentBounded2DList = OpenXRSpatialComponentBounded2DList.new()
    result_data.push_back(bounded2d_list)

    if OpenXRSpatialEntityExtension.query_snapshot(p_snapshot, result_data):
        for i in query_result_data.get_entity_id_size():
            var entity_id = query_result_data.get_entity_id(i)
            var entity_state = query_result_data.get_entity_state(i)

            # Remove the entity from our original list.
            if org_entities.has(entity_id):
                org_entities.erase(entity_id)

            if entity_state == OpenXRSpatialEntityTracker.ENTITY_TRACKING_STATE_STOPPED:
                # We should only get this when doing an update,
                # and we'll remove our marker in that case.
                if entities.has(entity_id):
                    var entity_tracker : OpenXRMarkerTracker = entities[entity_id]
                    entity_tracker.spatial_tracking_state = entity_state
                    XRServer.remove_tracker(entity_tracker)
                    entities.erase(entity_id)
            else:
                var entity_tracker : OpenXRMarkerTracker
                var register_with_xr_server : bool = false
                if entities.has(entity_id):
                    entity_tracker = entities[entity_id]
                else:
                    entity_tracker = OpenXRMarkerTracker.new()
                    entity_tracker.entity = OpenXRSpatialEntityExtension.make_spatial_entity(spatial_context, entity_id)
                    entities[entity_id] = entity_tracker
                    register_with_xr_server = true

                # Copy the state.
                entity_tracker.spatial_tracking_state = entity_state

                # If we're tracking, we should query the rest of our components.
                if entity_state == OpenXRSpatialEntityTracker.ENTITY_TRACKING_STATE_TRACKING:
                    var center_pose : Transform3D = bounded2d_list.get_center_pose(i)
                    entity_tracker.set_pose("default", center_pose, Vector3(), Vector3(), XRPose.XR_TRACKING_CONFIDENCE_HIGH)

                    entity_tracker.bounds_size = bounded2d_list.get_size(i)

                    if p_is_discovery:
                        entity_tracker.marker_type = marker_list.get_marker_type(i)
                        entity_tracker.marker_id = marker_list.get_marker_id(i)
                        entity_tracker.marker_data = marker_list.get_marker_data(p_snapshot, i)
                else:
                    entity_tracker.invalidate_pose("default")

                # We don't register our tracker until after we've set our initial data.
                if register_with_xr_server:
                    XRServer.add_tracker(entity_tracker)

    if p_is_discovery:
        # Any entities we've got left over, we can remove.
        for entity_id in org_entities:
            var entity_tracker : OpenXRMarkerTracker = entities[entity_id]
            entity_tracker.spatial_tracking_state = OpenXRSpatialEntityTracker.ENTITY_TRACKING_STATE_STOPPED
            XRServer.remove_tracker(entity_tracker)
            entities.erase(entity_id)

然後我們新增更新功能:

...


func _process(_delta):
    if not spatial_context:
        return

    if entities.is_empty():
        return

    var entity_rids: Array[RID]
    for entity_id in entities:
        entity_rids.push_back(entities[entity_id].entity)

    # We just want our anchor component here.
    var snapshot : RID = OpenXRSpatialEntityExtension.update_spatial_entities(spatial_context, entity_rids, [ \
            OpenXRSpatialEntityExtension.COMPONENT_TYPE_BOUNDED_2D, \
        ])
    if snapshot:
        # Process our snapshot.
        _process_snapshot(snapshot, false)

        # And clean up our snapshot.
        OpenXRSpatialEntityExtension.free_spatial_snapshot(snapshot)