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

サブスペースは、アプリ内の 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][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