アプリにサブスペースを追加する

サブスペースは、アプリ内の 3D 空間を区切ったパーティションです。これにより、3D モデルの配置、3D レイアウトの構築、2D コンテンツへの奥行き追加ができるようになります。サブスペースは、空間化が有効になっている場合にのみレンダリングされます。ホーム スペースまたは XR 以外のデバイスでは、そのサブスペース内のコードは無視されます。

3D モデルを配置するには、Volume や SpatialPanel などのサブスペース コンポーザブルを使用できます。Orbiter や SpatialDialog などの一部の XR コンポーネントは、2D UI 階層内の任意の場所で使用できる標準の 2D コンポーザブルですが、SubspaceComposable はアプリのサブスペースで呼び出す必要があります。これを行うには、ApplicationSubspace コンポーザブルまたは Subspace コンポーザブルを使用します。

名前が示すように、ApplicationSubspace コンポーザブルには、アプリの空間化されたコンテンツをすべて含める必要があります。Subspace コンポーザブルは、アプリの既存の UI 階層のさらに深い階層に 3D 空間のパーティションをネストする場合に最適です。

他のコンポーザブルと同様に、2D UI 階層で Subspace を直接呼び出すことができます。ただし、Subspace を呼び出す階層内の場所が持つ意味を理解することが重要です。

サブスペース階層について

トップレベルのサブスペースは、アプリによって呼び出される最も外側のサブスペースです。トップレベルのサブスペースには ApplicationSubspace コンポーザブルを使用しますが、アプリで Subspace コンポーザブルのみを使用する場合は、最も外側の Subspace コンポーザブルがトップレベルのサブスペースになります。デフォルトでは、この最上位のサブスペースはアプリの表示に推奨されるスペースで囲まれます。通常、アプリの空間レイアウトと SpatialPanel はここに配置します。最上位サブスペースの境界を変更する必要がある場合は、別の VolumeConstraints を ApplicationSubspace に渡します。

ただし、トップレベルのサブスペースに含まれるパネルの 2D UI 階層内に別のサブスペースをネストすると、そのネストされたサブスペースの動作は異なります。

ネストされたサブスペースには、トップレベルの Subspace と次の 2 つの主な違いがあります。

  • 呼び出された 2D レイアウトに参加します。つまり、サブスペースの高さと幅は、2D 親レイアウトの高さと幅によって制限されます。
  • 呼び出されたエンティティの子として動作します。つまり、SpatialPanel 内にネストされた Subspace コンポーザブルを呼び出す場合、そのサブスペースは、呼び出された SpatialPanel の子になります。

ネストされたサブスペースのこれらの動作により、次のような機能が有効になります。

  • 親エンティティとともに子を移動する
  • オフセット SubspaceModifier を使用して子の位置をオフセットする
  • 2D UI の上にホバーし、2D レイアウト内の適切なスペースの高さと幅と一致する 3D オブジェクトを表示する

アプリにサブスペースを追加する

次のコード例は、トップレベルとネストされたサブスペースをアプリに追加する方法を示しています。

setContent {
    // This is a top-level subspace
    ApplicationSubspace {
        SpatialPanel {
            MyComposable()
        }
    }
}
Subspace.kt

@Composable
private fun MyComposable() {
    Row {
        PrimaryPane()
        SecondaryPane()
    }
}

@Composable
private fun PrimaryPane() {
    // This is a nested subspace, because PrimaryPane is in a SpatialPanel
    // and that SpatialPanel is in a top-level Subspace
    Subspace {
        ObjectInAVolume(true)
    }
}
Subspace.kt