axiom-graphics

グラフィックス

GPU レンダリング、グラフィックスプログラミング、3D コンテンツの表示、またはディスプレイ性能に関する作業では、必ずこのスキルを使用してください。

使用する場面

次の場合にこのルーターを使用します。

• OpenGL／OpenGL ES のコードを Metal に移植する
• DirectX のコードを Metal に移植する
• GLSL／HLSL シェーダーを Metal Shading Language に変換する
• MTKView または CAMetalLayer を設定する
• ウィンドウのサイズ変更時や画面間の移動時に、レンダリングが途切れたりぼやけたりする
• GPU レンダリングの問題（黒画面、色の誤り、クラッシュ）をデバッグする
• 変換レイヤー（MetalANGLE、MoltenVK）を評価する
• GPU の性能を最適化する、またはサーマルスロットリングを解消する
• ProMotion デバイスでアプリが 60fps に固定される
• CADisplayLink またはレンダーループを設定する
• 可変リフレッシュレートディスプレイの問題
• ゲーム以外の SwiftUI アプリで 3D コンテンツを表示する
• RealityKit を使って AR 体験を構築する
• SwiftUI で RealityView または Model3D を使用する
• 空間コンピューティングや visionOS の 3D コンテンツ
• Swift（USDKit）で USD／USDZ ファイルを読み取る、編集する、または書き出す
• レンダーパイプラインに ML を追加する（MetalFX デノイズ、Metal テンソル、ニューラルレンダリング）
• 長時間のゲームセッションをプロファイリングする（metalperftrace、look-back トレース）

ルーティングロジック

Metal への移行

戦略の判断 → skills/metal-migration.md を参照

• 変換レイヤーとネイティブな書き換えのどちらを選ぶか
• プロジェクトの評価と移行計画
• アンチパターンとよくある間違い
• 納期に追われる状況への対処

API リファレンスと変換 → skills/metal-migration-ref.md を参照

• GLSL → MSL シェーダー変換表
• HLSL → MSL シェーダー変換表
• GL／D3D API に対応する Metal API
• MTKView の設定、レンダーパイプライン、コンピュートシェーダー
• WWDC のコード例一式

診断 → skills/metal-migration-diag.md を参照

• 移植後の黒画面
• シェーダーのコンパイルエラー
• 色や座標系の誤り
• 性能の低下
• 診断方法ごとの所要時間の分析

ウィンドウのサイズ変更時のレンダリングサーフェス

サイズ変更可能なウィンドウ内のあらゆるレンダリングサーフェス → skills/resizable-rendering.md を参照

• MTKView の drawableSizeWillChange（投影とレンダーターゲットの再割り当て、ライブリサイズ時のスロットリング）
• CAMetalLayer の drawableSize／contentsScale を手動で管理する方法
• サーフェスごとの適応表：ビデオレイヤー、マップ、グラフ、Canvas、Web ビュー、PDF、SpriteKit／SceneKit
• シーンが画面間を移動した際の、displayScale をキーとするキャッシュの無効化（ミラーリング、外部ディスプレイ）

ディスプレイ性能

フレームレートとレンダーループ → skills/display-performance.md を参照

• ProMotion（120Hz）デバイスでアプリが 60fps に固定される
• MTKView または CADisplayLink の設定
• 可変リフレッシュレートの最適化
• システムによる上限（低電力モード、フレームレート制限、サーマル、適応型電力）
• フレーム予算の計算（120Hz では 8.33ms）
• 実際のフレームレートと報告されるフレームレートの測定

RealityKit（ゲーム以外の 3D コンテンツ）

ゲーム以外の SwiftUI アプリでの 3D コンテンツ、AR 体験、空間コンピューティングには、RealityKit のスキルを使用してください。ゲーム固有の RealityKit パターンには、代わりに axiom-games ルーターを使用してください。

アーキテクチャ、ECS、ベストプラクティス → skills/realitykit.md を参照

• エンティティ・コンポーネント・システムのアーキテクチャ
• SwiftUI との統合：RealityView、Model3D、アタッチメント
• iOS での AR：AnchorEntity の種類、SpatialTrackingSession
• マテリアル、物理、インタラクション
• 性能の最適化

API リファレンス → skills/realitykit-ref.md を参照

• コンポーネントカタログ一式
• RealityView と Model3D の API
• マテリアルシステム（PBR、Unlit、Occlusion、Custom）
• RealityRenderer（Metal との統合）

トラブルシューティング → skills/realitykit-diag.md を参照

• エンティティが表示されない、アンカーがトラッキングされない
• ジェスチャーが反応しない、性能の問題
• マテリアルの問題、物理の問題

HDR のトーンマッピングとカラー

HDR 描画とカラーのメタデータ → skills/hdr-color-ref.md を参照

• CGContext に描画した HDR 画像が白っぽくなる、クリップされる、または暗くなる
• トーンマッピング方式の選択（CGContentToneMappingInfo と CGToneMapping）
• ICC プロファイルの Headroom Adaptive Gain Curve メタデータ（OS27）
• CGColor／CGColorSpace の永続化（OS27 の Codable）

USD オーサリング（USDKit）OS27

Swift での USD ファイル操作 → skills/usdkit.md を参照

• USD ステージとプリムを開いて、走査・編集します
• リファレンスとコンポジション
• 3D アセットのアクセシビリティメタデータ
• メッシュ／テクスチャ圧縮を使った USDZ エクスポート
• RealityKit で USD ステージをレンダリングします（USDStageComponent）

判断ツリー

1. 変換レイヤーとネイティブでの書き換えのどちらを選ぶべきですか？ → metal-migration
2. コードを Metal に移植／変換しますか？ → metal-migration
3. API リファレンス／シェーダー変換表を探していますか？ → metal-migration-ref
4. MTKView／レンダリングパイプラインを設定しますか？ → metal-migration-ref
5. 移植後に問題が発生しましたか（黒い画面、色がおかしいなど）？ → metal-migration-diag
6. ProMotion デバイスで 60fps に固定されていますか？ → display-performance
7. CADisplayLink／可変リフレッシュレートについて調べていますか？ → display-performance
8. フレームレートが期待どおりではありませんか？ → display-performance
9. SwiftUI で 3D モデルを表示しますか？ → realitykit
10. AR エクスペリエンスを構築しますか？ → realitykit
11. RealityView または Model3D を設定しますか？ → realitykit-ref
12. 3D コンテンツが表示されない、またはトラッキングされませんか？ → realitykit-diag
13. RealityKit コンテンツを Metal でカスタムレンダリングしますか？ → realitykit-ref (RealityRenderer)
14. 経路探索、LOD、ソフトシャドウ、スプラット、リバーブメッシュについて調べていますか？ → realitykit-ref (Part 10)
15. Swift で USD または USDZ ファイルを読み取り／編集／エクスポートしますか？ → usdkit
16. レンダリングパイプラインで ML を使いますか（デノイズ、Metal テンソルなど）？ → metal-migration-ref (Part 6)
17. 長時間のプレイセッションでフレーム落ちが発生しますか？ → display-performance (Part 12)
18. HDR 画像を描画すると色あせたり、クリップされたりしますか？ → hdr-color-ref
19. トーンマッピング方式を選ぶ、または HAGC メタデータを読み取りますか？ → hdr-color-ref
20. ウィンドウのサイズ変更や画面間の移動で、レンダリングが引き伸ばされたり、ぼやけたり、レターボックス表示になったりしますか？ → resizable-rendering
21. 3D ゲームを構築しますか？ → 代わりに axiom-games ルーターを使用します

不合理な判断を避ける

考え	実際
「シェーダーを一行ずつ変換すればいいだけです」	GLSL→MSL には、型、座標、精度の違いがあります。metal-migration-ref に変換表があります。
「MetalANGLE がすべて処理してくれます」	変換レイヤーには、本番環境で大きな制限があります。metal-migration でトレードオフを評価できます。
「黒い画面が出るだけだから、おそらく単純なバグです」	黒い画面の原因は 6 種類あります。metal-migration-diag を使えば、30 分以上かかるところを 5 分で診断できます。
「アプリは 60fps で動いているから問題ありません」	ProMotion デバイスは 120Hz に対応しています。display-performance で適切なフレームレートを設定できます。
「3D モデルには SceneKit を使えばいいです」	SceneKit はソフトウェア上で非推奨になっています。現代的な方法は RealityView と Model3D です。SwiftUI との統合については skills/realitykit.md を参照してください。
「3D モデルが 1 つだけなら ECS は必要ありません」	Model3D なら ECS をまったく使わずにモデルを 1 つ表示できます。RealityView は複雑なシーンにも対応できます。skills/realitykit.md で両方の方法を説明しています。
「USD ファイルは自分で解析する／OpenUSD をバンドルします」	USDKit は 27 リリースでシステム提供の USD を使います。ステージ、編集、圧縮エクスポートについては skills/usdkit.md を参照してください。
「シーングラフ上で経路探索を自作します」	RealityKit 27 には、コストとオフメッシュ接続に対応したナビゲーションメッシュが搭載されています。skills/realitykit-ref.md Part 10 を参照してください。
「フレーム落ちはプレイ開始から 1 時間後にしか起きないので、追跡できません」	27 リリースでは Metal のメトリクスが継続的に記録されます。事後に metalperftrace で収集できます。skills/display-performance.md Part 12 を参照してください。
「画面の境界からレンダーターゲットのサイズを決めます」	27 ではウィンドウのサイズが継続的に変わり、シーンはスケールの異なる画面間を移動します。drawable／view と trait のスケールからサイズを決めてください — skills/resizable-rendering.md を参照してください。
「CGContentToneMappingInfo を使います。これは最新の Swift 列挙型です」	Headroom Adaptive Gain Curve を表現できるのは C からインポートされた CGToneMapping だけです。新しい表記ですが、機能はより限定されています。skills/hdr-color-ref.md Part 1 を参照してください。

重要なパターン

metal-migration：

• 手早いデモ向けの変換レイヤー（MetalANGLE）
• 本番環境向けのネイティブ Metal への書き換え
• 状態管理の違い（GL は状態を保持 → Metal は明示的に指定）
• 座標系の注意点（Y 軸反転、NDC の違い）

metal-migration-ref：

• シェーダー型の完全な対応表
• API の対応関係の表
• MTKView と CAMetalLayer の選択
• レンダーパイプラインのセットアップパターン

metal-migration-diag：

• GPU Frame Capture のワークフロー（推測に 30 分以上かける代わりに 2～5 分）
• 変数を調べるシェーダーデバッガー
• API の誤用を検出する Metal 検証レイヤー
• パフォーマンス低下の診断

display-performance：

• MTKView はデフォルトで 60fps です（preferredFramesPerSecond = 120 の設定が必要です）
• CADisplayLink preferredFrameRateRange による明示的なフレームレート制御
• システム側の上限：低電力モード、フレームレート制限、熱、Adaptive Power（iOS 26）
• 120Hz のフレーム予算は 8.33ms
• UIScreen.maximumFramesPerSecond は当てになりません。正しい値は CADisplayLink が示します

realitykit（ゲーム以外の 3D）：

• RealityView の make/update クロージャーパターン
• シンプルなモデル表示には Model3D
• AnchorEntity による AR アンカリング
• マテリアルの選択（SimpleMaterial、PBR、Occlusion）

realitykit-ref（API）：

• RealityKit コンテンツをカスタム Metal でレンダリングする RealityRenderer
• マテリアルプロパティの完全なリファレンス
• RealityView のジェスチャー連携
• RealityKit 27 の追加機能：ナビゲーションメッシュ、LOD、ソフトシャドウ、ガウススプラッティング、リバーブメッシュ（Part 10）、クロスシミュレーション（ClothBodyComponent）、ComputeGraph フレームワーク

usdkit（USD のオーサリング、27 リリース）：

• USDStage のオープン／走査／編集、参照とコンポジション
• 3D アセット向けアクセシビリティメタデータスキーマ
• 圧縮 USDZ のエクスポート（AOM メッシュ + AVIF テクスチャ）
• USDStageComponent / USDPlayer による RealityKit ブリッジ

使用例

ユーザー：「iPad のウインドウサイズを変更すると、MTKView のコンテンツが引き伸ばされます」 → skills/resizable-rendering.md を参照してください

ユーザー：「キャッシュしたサムネイルが iPhone Mirroring でぼやけて見えます」 → skills/resizable-rendering.md を参照してください

ユーザー：「MetalANGLE を使うべきですか、それともネイティブ Metal に書き換えるべきですか？」 → skills/metal-migration.md を参照してください

ユーザー：「projectM を OpenGL ES から iOS に移植しています」 → skills/metal-migration.md を参照してください

ユーザー：「この GLSL シェーダーを Metal に変換するにはどうすればよいですか？」 → skills/metal-migration-ref.md を参照してください

ユーザー：「MTKView を初めてセットアップしています」 → skills/metal-migration-ref.md を参照してください

ユーザー：「移植したアプリが黒い画面になります」 → skills/metal-migration-diag.md を参照してください

ユーザー：「Metal に移植した後、パフォーマンスが低下しました」 → skills/metal-migration-diag.md を参照してください

ユーザー：「iPhone Pro でアプリが 60fps のままです」 → skills/display-performance.md を参照してください

ユーザー：「CADisplayLink を 120Hz に設定するにはどうすればよいですか？」 → skills/display-performance.md を参照してください

ユーザー：「Metal アプリで ProMotion が動作しません」 → skills/display-performance.md を参照してください

ユーザー：「SwiftUI アプリで 3D モデルを表示するにはどうすればよいですか？」 → skills/realitykit.md を参照してください

ユーザー：「USDZ モデルを表示したいです」 → skills/realitykit.md を参照してください

ユーザー：「RealityView をセットアップするにはどうすればよいですか？」 → skills/realitykit-ref.md を参照してください

ユーザー：「RealityView に 3D モデルが表示されません」 → skills/realitykit-diag.md を参照してください

ユーザー：「Metal で RealityRenderer を使うにはどうすればよいですか？」 → skills/realitykit-ref.md を参照してください

ユーザー：「アプリに AR を追加したいです」 → skills/realitykit.md を参照してください

ユーザー：「Swift で USD ファイルを読み込んで編集するにはどうすればよいですか？」 → skills/usdkit.md を参照してください

ユーザー：「配布用に USDZ アセットのサイズを小さくするにはどうすればよいですか？」 → skills/usdkit.md を参照してください

ユーザー：「RealityKit シーンに経路探索を追加するにはどうすればよいですか？」 → skills/realitykit-ref.md（Part 10）を参照してください

ユーザー：「ゲームを 1 時間プレイするとフレームレートが低下します」 → skills/display-performance.md（Part 12）を参照してください

ユーザー：「Metal シェーダー内でニューラルネットワークを実行するにはどうすればよいですか？」 → skills/metal-migration-ref.md（Part 6）を参照してください

ユーザー：「HDR 写真を CGContext に描画すると白っぽくなります」 → skills/hdr-color-ref.md を参照してください

ユーザー：「画像の ICC プロファイルにゲインカーブが含まれているか確認するにはどうすればよいですか？」 → skills/hdr-color-ref.md を参照してください