Vulkan スタートガイド
コレクションでコンテンツを整理
必要に応じて、コンテンツの保存と分類を行います。
このドキュメントでは、Khronos© サンプルアプリをダウンロードし、コンパイルして実行することにより、Vulkan グラフィック ライブラリの使用を開始する方法について概説します。
前提条件
始める前に、適切なバージョンのハードウェアとプラットフォームが揃っていることを確認してください。Android 7.0（Nougat）、API レベル 24 以上を搭載し、Vulkan をサポートするデバイスまたはエミュレータを使用する必要があります。
Android のバージョンを確認するには、[設定] メニューに移動して [デバイス情報] > [Android バージョン] を選択します。適切なバージョンのハードウェアとプラットフォームをセットアップしていることを確認したら、必要なソフトウェアをダウンロードできます。
ダウンロード
まず、いくつかのツールとその他のソフトウェアをダウンロードする必要があります。Windows ホスト上では、ツールとソースコードを深い階層のファイルパスに保存しないようおすすめします。これは Windows OS の一部のバージョンに存在するファイルパスの制約を回避するためです。
- Android Studio をダウンロードしていない場合は、こちらからダウンロードします。これには最新の Android SDK が含まれています。
- Android Studio 内から NDK と CMake をインストールするか、個別にダウンロードしてインストールします。
- Hello JNI サンプルをビルドして実行し、Android Studio が正しく動作していることを確認します。
- ホスト プラットフォームの build.md に表示されている python3 とその他のコンポーネントをインストールします。
インポート
このセクションでは、Khronos© Vulkan© サンプル リポジトリをダウンロードし、Android Gradle プロジェクトを生成して Android Studio IDE で開きます。
- 次の環境変数を設定します。
export ANDROID_HOME=/path/to/sdk-directory
export ANDROID_NDK_HOME=$ANDROID_HOME/ndk/{your-ndk-version-dir}
- CMake を $PATH に追加します。これは、Android ビルド スクリプトの生成に使用されます。
export PATH=$PATH:$ANDROID_HOME/cmake/{your-cmake-version}/bin
- ターミナルを開いて、開発ディレクトリにソースコードをダウンロードします。
cd dev-directory
git clone --recursive https://github.com/KhronosGroup/Vulkan-Samples.git
- 以下の手順（Build.md にあります）に沿って、Android サンプル プロジェクトを生成します。
cd Vulkan-Samples
./scripts/generate.py android
- Android Studio を開きます。[File] > [Open] を選択し、
Vulkan-Samples/build/android_gradle/build.gradle を選択します。Android Studio がプロジェクトを読み込むと、次のような画面が表示されます。
図 1.
Android Studio 内のサンプル プロジェクト
コンパイル
このリポジトリ内のすべてのサンプルは、一つの Android プロジェクトにまとめられています。プロジェクトをコンパイルするには、次のいずれかを行います。
- 単にソースをコンパイルするには、メニューの [Build] > [Make Project] を使用するか、Ctrl+F9 ショートカット キーを押します。
- サンプル APK を生成するには、メニューの [Build] > [Build Bundle(s)/APK(s)] > [Build APK(s)] を選択します。
Android Studio の [Build] ウィンドウに、ビルド成功メッセージが表示されます。エラーが表示された場合は、修正して再コンパイルします。
図 2. 成功したサンプルビルド
実行
サンプル プロジェクトを実行する前に、Android Studio が接続済みの Vulkan デバイスまたは Android Emulator を認識していることを確認してください。次のような画面が表示されます。
図 3. テストデバイスを Android Studio に接続する
プロジェクトを実行する手順は次のとおりです。
- メニューの [Run] > [Run vulkan_sample] を使用するか、ツールバーの実行ボタン
をクリックし、サンプルがインストールされて接続済みのデバイスで起動されるのを待ちます。
- 接続済みの Android デバイスで、必要なアクセス リクエストを承認します。
- [全ファイルの管理権を付与] を有効にしてから戻る矢印ボタンをタップし、サンプルのメイン起動画面に戻ります。
- ディスクへのアクセスを許可します。
図 4. ディスクへのアクセスを有効にする
- 次のようなサンプル メインメニュー画面が表示されます。
図 5. サンプル メインメニュー
- サンプルリストを参照して、実行するサンプルをいくつか選択します。初めて Vulkan 開発を行う場合は、「API」サンプルから始めることができます。たとえば、[Hello Triangle] をタップすると、次のようなレンダリング済みの三角形が表示されます。
図 6. Hello Triangle サンプル
以上により、テストデバイスでサンプルを実行できるように開発システムがセットアップされました。
Vulkan サンプルは、複数のオペレーティング システム（パソコン用とモバイル用のものを含む）向けに開発されています。[Performance]、[Extensions]、[Tooling] にあるサンプルの一部は安定しておらず、デバイスでクラッシュすることがあります。これには、次のようなさまざまな理由が考えられます。
- Vulkan の特定の機能が Android 向けに設計されていない。
- 使用している Android OS バージョンがサポートされていない。
- ハードウェア プラットフォームの GPU 機能に問題がある。
確認
Vulkan サンプルの Java セクションは、NativeActivity クラスから派生したものです。このクラスは、アプリの作成、起動、停止、破棄などの一般的なアプリのライフサイクル イベントを C/C++ コードに渡します。サンプルの C/C++ セクションには、ランタイムのサブサンプル切り替え機能を実装するサンプル フレームワークがあります。大まかに言うと、Android システムのイベント / メッセージは、次のパスをたどってサンプルアプリの次の Vulkan コードに到達します。
NativeSampleActivity Java セクションNativeSampleActivity C/C++ セクションandroid_native_glue コードandroid_main- サンプル フレームワーク
- 個別のサブサンプルのコード
android_main は NativeSampleActivity とアプリコードの橋渡しとなっており、サンプルコードをたどる際の出発点にすることができます。Vulkan 固有のソースのみを確認したい場合は、次の内容を含む Vulkan_Samples\samples のコードを参照してください。
- 「api」カテゴリのサンプル
- 「performance」カテゴリのサンプル
- 「extensions」カテゴリのサンプル
- 「tooling」のサンプル
Vulkan_Samples\shaders は、すべてのシェーダーのホームです。
「API」カテゴリのサンプルを参照すると、Vulkan の基本的な使用方法とサンプル フレームワークの理解を深めることができます。次に、「Performance」および「Extensions」カテゴリのサンプルに進みます。シェーダー コードについては、Android Studio の [Project] ビューを使用できます。
図 7. Studio でシェーダーを確認する
参考情報
Vulkan API はいくつかのバージョンを経ているため、成熟しています。Vulkan 標準委員会と Vulkan コミュニティでは、API の使用方法とベスト プラクティスのデモを含む Vulkan マテリアルの豊富なセットを作成しています。Vulkan アプリの開発に役立つリソースを以下に示します。
このページのコンテンツやコードサンプルは、コンテンツ ライセンスに記載のライセンスに従います。Java および OpenJDK は Oracle および関連会社の商標または登録商標です。
最終更新日 2024-08-22 UTC。
[[["わかりやすい","easyToUnderstand","thumb-up"],["問題の解決に役立った","solvedMyProblem","thumb-up"],["その他","otherUp","thumb-up"]],[["必要な情報がない","missingTheInformationINeed","thumb-down"],["複雑すぎる / 手順が多すぎる","tooComplicatedTooManySteps","thumb-down"],["最新ではない","outOfDate","thumb-down"],["翻訳に関する問題","translationIssue","thumb-down"],["サンプル / コードに問題がある","samplesCodeIssue","thumb-down"],["その他","otherDown","thumb-down"]],["最終更新日 2024-08-22 UTC。"],[],[],null,["# Get started with Vulkan\n\n| **Note:** Although this page includes [NativeActivity](/reference/android/app/NativeActivity) description, [GameActivity inside AGDK jetpack library](/games/agdk/integrate-game-activity) is an updated and well maintained implementation of `NativeActivity`, with more functionality and fast release cycles. It is highly recommended to use `GameActivity` for your new projects.\n\nThis document outlines how to get started with the Vulkan graphics library\nby downloading, compiling, and running Khronos© sample app.\n\nPrerequisites\n-------------\n\nBefore beginning, make sure you have the right hardware and platform version prepared.\nYou should use a device or an [emulator](/studio/run/emulator) that supports Vulkan,\nrunning Android 7.0 (Nougat), API level 24 or higher.\n\nYou can confirm your Android version by going to the **Settings** menu,\nand selecting **About phone** \\\u003e **Android Version**. Once you've confirmed that\nyou have the right hardware and platform version set up, you can download the necessary software.\n\nDownload\n--------\n\nBefore getting started, you must download several tools and other software. Note that on a Windows host,\nit is recommended that you avoid a deep file path hierarchy for tools and source code;\nthis is to work around file path limits on some Windows OS versions.\n\n1. If you don't already have Android Studio, [download it](/studio). This includes the most recent Android SDK.\n2. [Install the NDK and CMake](/studio/projects/install-ndk) from within Android Studio or [download and install](/ndk/downloads) them separately.\n3. Build and Run the [Hello JNI sample](https://github.com/android/ndk-samples/tree/main/hello-jni) to ensure Android Studio is working properly.\n4. Install python3 and other components listed in [build.md](https://github.com/KhronosGroup/Vulkan-Samples/blob/main/docs/build.adoc#android) for your host platform.\n\nImport\n------\n\nIn this section, you download [the Khronos© Vulkan© sample repository](https://github.com/KhronosGroup/Vulkan-Samples/), generate an Android gradle\nproject, then open it with the Android Studio IDE.\n\n1. Set the following environment variables: \n\n ```\n export ANDROID_HOME=/path/to/sdk-directory\n export ANDROID_NDK_HOME=$ANDROID_HOME/ndk/{your-ndk-version-dir}\n ```\n2. Add CMake to the $PATH, which is used to generate Android build scripts: \n\n ```\n export PATH=$PATH:$ANDROID_HOME/cmake/{your-cmake-version}/bin\n ```\n3. Open a terminal and download the source code to your development directory: \n\n ```\n cd dev-directory\n git clone --recursive https://github.com/KhronosGroup/Vulkan-Samples.git\n ```\n4. Follow these instructions (from [Build.md](https://github.com/KhronosGroup/Vulkan-Samples/blob/master/docs/build.md#android)) to generate the Android sample project: \n\n ```\n cd Vulkan-Samples\n ./scripts/generate.py android\n ```\n5. Open Android Studio. Choose **File \\\u003e Open** and select `Vulkan-Samples/build/android_gradle/build.gradle`. You should see something similar to the following after Android Studio loads the project: \n\n \u003cbr /\u003e\n\n **Figure 1.** The sample project inside Android Studio.\n\n \u003cbr /\u003e\n\nCompile\n-------\n\nAll samples in this repo are organized into one Android project. To compile the\nproject, do one of the following:\n\n- To just compile the sources, use menu, **Build** \\\u003e **Make Project** , or type the **Ctrl-F9** shortcut key.\n- To generate the sample APK, select menu **Build** \\\u003e **Build Bundle(s)/APK(s)** \\\u003e **Build APK(s)**.\n\nYou should see the build successful message inside Android Studio's **Build** window.\nIn case there are errors showing up, fix them and re-compile. \n\n\u003cbr /\u003e\n\n**Figure 2.** A successful sample build.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nExecute\n-------\n\nBefore running the sample project, make sure Android Studio recognizes your\nconnected Vulkan device or Android Emulator. You should see something like the\nfollowing: \n\n\u003cbr /\u003e\n\n**Figure 3.** Connect the test device to Android Studio.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nTo run the project, do the following:\n\n1. Use menu **Run \\\u003e Run vulkan_sample** , or click on the run button on the toolbar, and wait for the sample to get installed and started on your connected device.\n2. On your connected Android device, authorize the needed access requests.\n - enable **Allow access to manage all files** , then tap the arrow **Back button** to return the sample main start screen.\n - allow the disk access: \n\n \u003cbr /\u003e\n\n **Figure 4.** Enable disk access.\n\n \u003cbr /\u003e\n\n3. You should see the sample main menu screen, similar to the following: \n\n \u003cbr /\u003e\n\n **Figure 5.** Sample main menu.\n\n \u003cbr /\u003e\n\n4. Browse through the sample list, and select a few to run. If you are new to Vulkan development, you can start with \"API\" samples. For example, tapping \"Hello Triangle\" should display a rendered triangle similar to the following: \n\n \u003cbr /\u003e\n\n **Figure 6.** Hello Triange sample.\n\n \u003cbr /\u003e\n\nYour development system is now set up to run samples on your test device.\n\nVulkan Samples are developed for multiple operating systems, including those for\ndesktop and mobile. Some samples under **Performance** , **Extensions** , and\n**Tooling** may be unstable and crash on your device. This might be due to various reasons, such\nas:\n\n- The specific Vulkan features weren't designed for Android.\n- Your Android OS version is unsupported.\n- The GPU capability of your hardware platform.\n\nExplore\n-------\n\nThe Java section of the Vulkan sample derives from the [NativeActivity](/reference/android/app/NativeActivity) class. It passes typical application\nlifecycle events, such as app creation, start, stop, and destroy to the C/C++\ncode. In the C/C++ section of the sample, there is a sample framework\nthat implements the run-time sub sample switching functionality. At a very\nhigh level, Android system events/messages go through the following path to\nreach the sample app's Vulkan code:\n\n- `NativeSampleActivity` Java section\n- `NativeSampleActivity` C/C++ section\n- `android_native_glue` code\n- `android_main`\n- Sample framework\n- Individual sub sample's code\n\n`android_main` is the bridge between `NativeSampleActivity` and the app code,\nwhich can be the starting point for you to follow the sample code. If you just\nwant to focus on the Vulkan specific sources, you can explore the code under\n`Vulkan_Samples\\samples`, which contains the following:\n\n- The \"api\" category samples.\n- The \"performance\" category samples.\n- The \"extensions\" category samples.\n- The \"tooling\" samples.\n\nThe `Vulkan_Samples\\shaders` are the home for all shaders.\n\nYou can start browsing the \"API\" category samples to get familiar with basic\nVulkan usage and the sample framework. Then you can progress to the\n\"Performance\" and \"Extenstions\" category samples. For shader code, you can use\nthe **Project** view in Android Studio. \n\n\u003cbr /\u003e\n\n**Figure 7.** Explore shader with Studio.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nAdditional resources\n--------------------\n\nThe Vulkan API has been through a few versions, so it is maturing. The Vulkan\nstandard committee and the Vulkan community have created a rich set of Vulkan\nmaterial that demonstrates the API's usage and best practices. The following\nlist contains some resources for Vulkan application development:\n\n- **Vulkan Specification.**\n The Khronos Group maintains the Vulkan specification. See\n the [Vulkan homepage](https://www.khronos.org/vulkan) for the full specification,\n training, [guides](https://github.com/KhronosGroup/Vulkan-Guide)\n and [tutorials](https://www.vulkan.org/learn#key-resources).\n\n- **Validation Layers.**\n Validation Layers are essential for application development.\n See the [Vulkan validation layers on Android](/ndk/guides/graphics/validation-layer)\n documentation for details.\n\n- **Shaderc.**\n Shaderc code in the NDK is the downstream of the\n [Shaderc repo](https://github.com/google/shaderc). For the usage documentation\n and instructions to get the latest version, see\n [Shader compilers](/ndk/guides/graphics/shader-compilers)."]]
