Vulkan 시작하기
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이 문서에서는 Khronos© 샘플 앱을 다운로드, 컴파일, 실행하여 Vulkan 그래픽 라이브러리를 시작하는 방법을 설명합니다.
기본 요건
시작하기 전에 적합한 하드웨어 및 플랫폼 버전이 준비되어 있어야 합니다.
Vulkan을 지원하며 Android 7.0(Nougat), API 수준 24 이상을 실행하는 기기나 에뮬레이터를 사용해야 합니다.
Android 버전을 확인하려면 설정 메뉴로 이동하여 휴대전화 정보 > Android 버전을 선택하면 됩니다. 적합한 하드웨어 및 플랫폼 버전이 설치되어 있는 것이 확인되면 필요한 소프트웨어를 다운로드할 수 있습니다.
다운로드
시작하기 전에 먼저 여러 도구와 기타 소프트웨어를 다운로드해야 합니다. Windows 호스트에서는 도구 및 소스 코드에 심층적 파일 경로 계층 구조를 사용하지 않는 것이 좋습니다. 이렇게 하면 일부 Windows OS 버전에서 발생하는 파일 경로 제한을 해결할 수 있습니다.
- Android 스튜디오가 아직 없으면 다운로드합니다.
Android 스튜디오에는 최신 Android SDK가 포함되어 있습니다.
- Android 스튜디오 내에서 NDK 및 CMake를 설치하거나 별도로 다운로드하여 설치합니다.
- Hello JNI 샘플을 빌드하고 실행하여 Android 스튜디오가 제대로 작동하는지 확인합니다.
- build.md에 나열된 호스트 플랫폼용 python3 및 기타 구성요소를 설치합니다.
가져오기
이 섹션에서는 Khronos© Vulkan© 샘플 저장소를 다운로드하고 Android Gradle 프로젝트를 생성한 후 Android 스튜디오 IDE를 사용하여 엽니다.
- 다음 환경 변수를 설정합니다.
export ANDROID_HOME=/path/to/sdk-directory
export ANDROID_NDK_HOME=$ANDROID_HOME/ndk/{your-ndk-version-dir}
- Android 빌드 스크립트를 생성하는 데 사용되는 $PATH에 CMake를 추가합니다.
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 스튜디오를 엽니다. File > Open을 선택하고
Vulkan-Samples/build/android_gradle/build.gradle을 선택합니다.
Android 스튜디오에서 프로젝트를 로드하고 나면 다음과 같이 표시됩니다.
그림 1.
Android 스튜디오 내 샘플 프로젝트
컴파일
이 저장소의 모든 샘플은 하나의 Android 프로젝트로 구성됩니다. 프로젝트를 컴파일하려면 다음 중 하나를 실행하세요.
- 소스만 컴파일하려면 메뉴 Build > Make Project를 사용하거나 Ctrl-F9 단축키를 입력합니다.
- 샘플 APK를 생성하려면 메뉴 Build > Build Bundle(s)/APK(s) > Build APK(s)를 선택합니다.
Android 스튜디오의 Build 창 안에 빌드 성공 메시지가 표시됩니다.
오류가 표시되면 오류를 수정하고 다시 컴파일합니다.
그림 2. 성공적인 샘플 빌드
실행
샘플 프로젝트를 실행하기 전에 Android 스튜디오가 연결된 Vulkan 기기나 Android Emulator를 인식하는지 확인합니다. 다음과 같이 표시되어야 합니다.
그림 3. Android 스튜디오에 테스트 기기 연결
프로젝트를 실행하려면 다음 단계를 따르세요.
- 메뉴 Run > Run vulkan_sample을 사용하거나 툴바에서 실행 버튼
을 클릭한 후 샘플이 설치되고 연결된 기기에서 시작될 때까지 기다립니다.
- 연결된 Android 기기에서 필요한 액세스 요청을 승인합니다.
- Allow access to manage all files를 사용 설정하고 화살표 뒤로 버튼을 탭하여 샘플 기본 시작 화면으로 돌아갑니다.
- 디스크 액세스를 허용합니다.
그림 4. 디스크 액세스 사용 설정
- 아래와 같은 샘플 기본 메뉴 화면이 표시됩니다.
그림 5. 샘플 기본 메뉴
- 샘플 목록을 살펴보고 실행할 몇 가지를 선택합니다.
Vulkan 개발이 처음이라면 'API' 샘플부터 시작해 보세요.
예를 들어 'Hello Triangle'을 탭하면 다음과 같은 렌더링된 삼각형이 표시됩니다.
그림 6. Hello Triangle 샘플
이제 테스트 기기에서 샘플을 실행하도록 개발 시스템이 설정되었습니다.
Vulkan 샘플은 데스크톱 및 모바일용 운영체제를 비롯하여 여러 운영체제용으로 개발되었습니다. Performance, Extensions, Tooling의 일부 샘플은 불안정하거나 기기에서 비정상 종료될 수 있습니다. 다음과 같은 다양한 이유 때문일 수 있습니다.
- Android용으로 설계되지 않은 특정 Vulkan 기능
- 지원되지 않는 Android OS 버전
- 하드웨어 플랫폼의 GPU 기능
알아보기
Vulkan 샘플의 자바 섹션은 NativeActivity 클래스에서 파생됩니다. 앱 생성, 시작, 중지, 소멸과 같은 일반적인 애플리케이션 수명 주기 이벤트를 C/C++ 코드에 전달합니다. 샘플의 C/C++ 섹션에는 런타임 하위 샘플 전환 기능을 구현하는 샘플 프레임워크가 있습니다. 매우 높은 수준에서 Android 시스템 이벤트/메시지는 다음 경로를 거쳐 샘플 앱의 Vulkan 코드에 도달합니다.
NativeSampleActivity 자바 섹션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 스튜디오의 Project 뷰를 사용할 수 있습니다.
그림 7. 스튜디오를 사용하여 셰이더 살펴보기
추가 리소스
Vulkan API는 몇 가지 버전을 거쳤으며 계속 발전하고 있습니다. Vulkan 표준 위원회와 Vulkan 커뮤니티에서는 API의 사용법과 권장사항을 보여주는 다양한 Vulkan 머티리얼 세트를 만들었습니다. 다음 목록에는 Vulkan 애플리케이션 개발을 위한 리소스가 몇 가지 포함되어 있습니다.
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 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)."]]
