移行ガイド
このガイドでは、AR Foundation 4.x と 5.x の違いについて説明します。
ARSubsystems パッケージを ARFoundation に統合
これまで、AR (拡張現実) 関連のサブシステムのインターフェースは、AR Subsystems パッケージ で提供されていました。これらのインターフェースは、AR Foundation パッケージに移行されました。ただし、これらの AR 関連のサブシステムはすべて、同じ Unity.XR.ARSubsystems 名前空間を引き続き使用します。
既存のプロジェクトの適応
ここでの互換性に影響する変更は、主にパッケージの依存関係です。以前のバージョンでは、ARFoundation パッケージは ARSubsystems パッケージに依存していました。この依存関係が排除されました。これにより、明示的な依存関係として AR Subsystems パッケージを使用している以前のアプリケーションは、AR Foundation パッケージに置き換えることができるようになっています。
移行を容易にするために、ARFoundation に依存する空の ARSubsystems パッケージを引き続き公開しています。これにより、ARSubsystems パッケージへの明示的な依存関係を持つプロジェクトは、引き続き期待どおりに動作することが保証されます。
テクスチャインポーター
TextureImporterInternals.GetSourceTextureDimensions が削除されました。代わりに TextureImporter.GetSourceTextureWidthAndHeight を使用します。
XRSubsystem
XRSubsystem は非推奨になりました。代わりに SubsystemWithProvider を使用してください。これは Unity コアの新しい Subsystem 基本クラスであり、SubsystemDescriptorWithProvider と SubsystemProvider の実装が必要です。
- 非推奨の API を使用したサブシステムの実装:
public class TestSubsystemDescriptor : SubsystemDescriptor<TestSubsystem>
{ }
public class TestSubsystem : XRSubsystem<TestSubsystemDescriptor>
{
protected override void OnStart() { }
protected override void OnStop() { }
protected override void OnDestroyed() { }
}
- 新しい API を使用したサブシステムの実装:
public class TestSubsystemDescriptor : SubsystemDescriptorWithProvider<TestSubsystem, TestSubsystemProvider>
{ }
public class TestSubsystem : SubsystemWithProvider<TestSubsystem, TestSubsystemDescriptor, TestSubsystemProvider>
{ }
public class TestSubsystemProvider : SubsystemProvider<TestSubsystem>
{
public override void Start() { }
public override void Stop() { }
public override void Destroy() { }
}
XR Origin
ARSessionOrigin が非推奨になり、XROrigin に置き換えられます。ARSessionOrigin の最終的な削除に向けてプロジェクトを準備するために、以下の手順に従ってください。
- カスタムスクリプト内のすべての参照を
ARSessionOriginからXROriginに置き換えます。 XROriginへのアップグレードが完了したら、ARSessionOrigin(現在はXROrigin) のプロパティへのすべての参照を camelCase から PascalCase に変更します。- プロジェクト内の
ARSessionOriginコンポーネントをすべて削除し、それらをXROriginに置き換えます。 ARSessionOriginがアタッチされている既存のオブジェクトを変換する場合は、必ず Camera Offset (カメラオフセット) オブジェクトの下でカメラを親にします。
XR Origin の詳細については、XR Core Utilities パッケージのドキュメント を参照してください。
ARSessionOrigin.MakeContentAppearAt の削除
XR Interaction Toolkit などの Unity XR パッケージ間の互換性を確保するために、ARSessionOrigin が再実装され、非推奨になり、XROrigin から派生するようになりました。
XROrigin には、古いバージョンの AR Foundation に導入された ARSessionOrigin.MakeContentAppearAt と同等のメソッドは含まれていません。MakeContentAppearAt を使用するプロジェクトを移行する場合は、プロジェクトに拡張メソッドを追加することで、XROrigin でこの API を引き続きサポートできます。拡張メソッドの実装例は、AR Foundation Samples プロジェクトの arfoundation-samples/Assets/Scripts/XROriginExtensions.cs にあります。
XRDepthSubsystem から XRPointCloudSubsystem に名前を変更
深度情報は、複数のフレーム間で相互に関連付けることができる特徴点で表されます。点群は、これらの特徴点のセットです。XRDepthSubsystem は、XRPointCloud をトラッカブルとして使用してこのデータにアクセスするための トラッキングサブシステム インターフェースでした。
このサブシステムの目的をより正確に伝えるために、XRDepthSubsystem から XRPointCloudSubsystem に名前が変更されました。XRDepthSubsystem は非推奨になっており、将来のリリースで削除される予定です。
変更点
XRDepthSubsystemからXRPointCloudSubsystemに名前が変更されました。XRDepthSubsystemDescriptorからXRPointCloudSubsystemDescriptorに名前が変更されました。
ARCameraBackground、ARCameraManager、XRCameraBackgroundRenderingMode
これまで、ARCameraBackground と ARCameraManager は、すべての不透明なジオメトリの前に背景をレンダリングする必要があることを前提としていました。そのため、カメラの背景の上に不透明な要素をレンダリングするときに、不要なオーバードローが発生していました。現在は、ARCameraManager.requestedBackgroundRenderingMode と ARCameraManager.currentRenderingMode を使用して、レンダリング順序を選択できるようになりました。これにより、プラットフォームが提供するマテリアルに対して、BeforeOpaques と AfterOpaques のいずれかを選択することが可能になっています。
Invalid (カメラレンダリングなし/カメラレンダリングがサポートされていない)、Any (プラットフォームが決定)、BeforeOpaques (デフォルトの動作)、AfterOpaques (不透明な要素の終了後にレンダリング) の各レンダリングモードをリクエストできるようになりました。リクエストしたモードをプラットフォームがサポートしている場合は、そのモードをレンダリングするときに使用する適切なマテリアルが返されます。プラットフォームが特定のモードしかサポートしていない場合、必ず XRCameraSubsystem.currentRenderingMode プロパティから、サポートされているレンダリングモードが返されるか、背景のレンダリングがまったくサポートされていない場合または内部で無効になっている場合は Invalid が返されます。
AfterOpaques は、レンダリング順序以外にもレンダリング動作が少し異なります。AfterOpaques を使用すると、ARCameraBackground は farClipPlane でフルスクリーンクアッドをレンダリングして、深度テストで不透明なジオメトリの背後にあるフラグメントが適切にカリングされるようにします。
ARCameraBackground でのカスタムシェーダーとカスタムマテリアル
ARCameraBackground コンポーネントでカスタムマテリアルを使用する場合は、レンダリングモードを変更するときにマテリアルのスワップを適切に処理する必要があります。これを行うには、ARCameraBackground.OnCameraRenderingModeChanged をサブスクライブします。コマンドバッファ 設定の前にコールバックが発生します。
カスタムマテリアルシェーダーでは、AfterOpaques モードでレンダリングする場合、背景をレンダリングするときにジオメトリを不適切に遮蔽しないように、ZTest を使用して深度テストを適切に処理する必要があります。このユースケースには ZTest LEqual が適しています。
オクルージョンでのカスタムシェーダーとカスタムマテリアル
カスタムシェーダーで オクルージョン を処理する場合、不透明なジオメトリによって深度バッファがすでに書き込まれており、ZTest LEqual を使用して色と深度をレンダリングするときに正しい結果が得られないことを考慮する必要があります。シェーダーでは、オクルージョンテクスチャのサンプリングに加え、現在の深度バッファとオクルージョンテクスチャ間の深度テストに失敗したフラグメントの適切な破棄を処理する必要があります。
カメラの現在の深度テクスチャ とオクルージョン深度テクスチャの値を比較して、現在の深度がオクルージョン深度の "手前" にあるフラグメントを破棄することによって、AfterOpaque レンダリングモードでオクルージョンを実現できます。また、これを別のパスに分離して、シェーダーの分岐が不透明なジオメトリを含むフラグメントに限定されるようにすることが有効な場合もあります。疑似コードの例を以下に示します。
SubShader
{
Pass
{
Name "Custom Camera Background Pass"
ZWrite On
// ジオメトリの背後にあるフラグメントのみを処理します。
ZTest LEqual
// ...
// フラグメントシェーダー内
fragmentOut fragment(v2f in)
{
// ...
fragmentOut.depth = occlusionDepth;
fragmentOut.color = backgroundColor;
}
}
Pass
{
Name "Custom Camera Background Occlusion Pass"
ZWrite On
// ジオメトリが背景の手前にあるフラグメントのみを処理します。
// これにより、分岐を必要とするフラグメントに分岐が限定されます。
ZTest Greater
// ...
// カメラの深度テクスチャが使用可能な場合はそれを挿入します。
// 詳細については、https://docs.unity3d.com/Manual/SL-CameraDepthTexture.html を参照してください。
UNITY_DECLARE_DEPTH_TEXTURE(_CameraDepthTexture);
// フラグメントシェーダー内
fragmentOut fragment(v2f in)
{
// ...
float cameraDepth = SAMPLE_DEPTH_TEXTURE(_CameraDepthTexture, in.uvCoords);
// ...
// 不透明なジオメトリの背後にあると考えられるフラグメントを破棄します。
// それ以外の場合は色と深度を書き込みます。
if (cameraDepth > occlusionDepth)
{
discard;
}
fragmentOut.depth = occlusionDepth;
fragmentOut.color = backgroundColor;
}
}
}
URP バージョン 14.0.2 の非互換性
URP バージョン 14.0.2 を使用している場合、URP が RendererFeature の入力リクエストを考慮しなくなるバグがあります。そのため、ARCameraBackground がカメラの深度テクスチャをリクエストしても、URP はこのリクエストを考慮せず、カメラの背景によってジオメトリが上書きされます。
この問題を回避するには、必ず URP バージョン 14.0.3 以降を使用してください。