RavEngine/RGLのサンプルを動かす上でのハマりどころまとめ

おそらく執筆時点でのノウハウに過ぎないと思われる、本家での解決までに使える一時的なノウハウを集めてみた。

ちなみに、サンプルの内容には全く言及しない。あくまでビルドが通るまでのノウハウであることに注意。

※ RavEngineとRGLの概要については自分の書いた以下の記事を参考にしていただければ。

なお、Windows/Mac/Linuxなどの様々なプラットフォームの問題が混在するので、見出しでわかるようにしておくので都度読み飛ばしてほしい。

(共通) ビルド済みのサンプルが動かない

README の How to try the samples without building に、ビルドせずにビルド済みのバイナリを動かす方法（例: #669 の CIビルド済ファイルをダウンロードなど）が紹介されているが、これが動かないことがある。

動けばバンザイでOKなのだけれど、おそらく環境要因等で動かない場合は、自分でビルドするしかない。（ただし、最低動作環境が非常に厳しいので、まず先に確認する。）

手動ビルドは、具体的なコマンドがドキュメント不足でわかりづらい点が多々あるので、必要に応じて .github/workflows/build.yml などを参考にすることをおすすめする。

ちなみに、mainブランチ (masterブランチ) の更新は、時にはビルドが失敗するものも含まれているはずなので、コミットログのCIの成功・失敗は一応参考にすると良い。

(共通) ヒープ領域を使い果たしたと言われてビルドに失敗する

これはいわゆるメモリ不足。本当にメモリが足りない場合もあるし、失敗した時点からやり直せば解決する場合もある。

本質的な対応策としては、ライブラリをstatic linkにしない、外部ライブラリを動的リンクするなどの対応策があるはずだけれど、これについては未調査。

(Win) ロングパスの有効化

ビルド時に、パスが256文字を超えているためにファイルが保存できないという主旨のエラーが出る。これは以下のようにロングパスを有効化することで回避。

(Win) DX12のバージョン問題 ( Agility SDK )

RavEngineではなく、RGLのサンプルをビルドする際に、実行時にDX12の構成エラーが出る。

これは、Agility SDKが同梱されていないのが問題で、C:¥Windows¥System32 にあるDX12関連のdllを読もうとして、実行時のバージョンのミスマッチにより動作に失敗する。

結論としては、RavEngine/Samplesの依存関係の方のRGLには、Agility SDKが同梱されているので、そちらをコピーして使う。（deps/RGLごとコピーして基本的に問題ないはず。）¹

(Mac) metalのビルドに失敗する

これは、CMakeの呼び出し時に -G Xcode を指定していないのが問題。Metalシェーダのビルドには、現時点でXcodeが必須のようで、READMEのSupported PlatformsでMacだけmakeやninjaが存在せずに、Xcodeだけがサポートされているのはこれが理由。

（エラーメッセージとしては、LANGUAGE METAL がサポートされていないなどのエラーが出る。）

(Linux) volkフォルダがない (volk copyとなってしまう)

これはタイトル通りで、Vulkan SDKの一部であるvolkが、なぜか deps/volk copy という名前のフォルダになってしまう。これは単純にリネームすればOK。（気付くのにちょっと時間がかかる。）

(Linux) CreatePipelineLayoutの作成に失敗する

おそらくgcc (clang)のバージョンが関連していると思われる、device->CreatePipelineLayout({ ... }); の構文読み取りエラーが起こることがある。

これは一度 RGL::PipelineLayoutDescriptor pld{ ... }; として変数に格納して、その後 pipelineLayout = device->CreatePipelineLayout(pld); とすれば解決する。

(Linux) RVE_VFS_get_name がないといわれる

これは、VirtualFileSystem.cppで、extern constとなっている2種類の関数が、CMakeによる動的生成によって実体が呼び出されるのが原因。

実は自分はまだこれをちゃんとは解決できていないのだけれど、HelloCubeの方のサンプルを動かすか、あるいはCMakeから不必要な add_sample(...) の行を除いて、extern constの行をコメントアウトしたり、あるいはサンプルのcppに追加の行やファイルを追加し、CMakeLists.txtから正しいものを目で読み取って記載するという手はある。

（Win/Macでは問題ないので、IssueやDiscussionを探せば解決策があるかもしれないし、CMakeのオプションなど、GitHub Workflowの記述を参考にするべきかもしれない。）

(Linux) Vulkanの実行時エラーで〇〇の機能がないといわれる

例えば、Cannot init - Fragment Shader Interlock is not supported のようなもの。

こればっかりは正直どうしようもなくて、WSLを使っていると起こりがち。デバッグ関連の最新機能が多いので、コメントアウトできる部分もありそうな気はするけれど、仮想環境ではないUbuntu 24.04を使うと解決することが多いけれど、おそらく使っているGPUにも依存する。

1. Agility SDKが存在しないように見える時は、gitのサブモジュールを再帰的に取得するのを忘れている。余談として、サブモジュールのサイズや転送量を削減するには次の記事を参照: https://qiita.com/tsuyoshi_cho/items/8ee621805332249a6fa5 ↩