بدء استخدام Vulkan
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يوضّح هذا المستند كيفية بدء استخدام مكتبة رسومات Vulkan
عن طريق تنزيل نموذج تطبيق Khronos© وتجميعه وتشغيله.
المتطلّبات الأساسية
قبل البدء، تأكد من إعداد الأجهزة وإصدار النظام الأساسي المناسب.
يجب استخدام جهاز أو محاكي يتوافق مع Vulkan
تعمل بنظام التشغيل Android 7.0 (Nougat)، المستوى 24 من واجهة برمجة التطبيقات أو الإصدارات الأحدث
يمكنك التأكّد من إصدار Android بالانتقال إلى قائمة الإعدادات
واختيار لمحة عن الهاتف > إصدار Android: بمجرد التأكد من أن
إعداد الأجهزة وإصدار النظام الأساسي المناسب، يمكنك تنزيل البرامج اللازمة.
تنزيل
قبل البدء، يجب تنزيل عدة أدوات وبرامج أخرى. لاحظ أنه في مضيف Windows،
يُوصى بتجنب التسلسل الهرمي لمسار الملفات العميق للأدوات ورمز المصدر؛
وذلك للتغلب على حدود مسار الملفات في بعض إصدارات نظام التشغيل Windows.
- إذا لم يكن لديك "استوديو Android"، يمكنك تنزيله.
ويشمل ذلك أحدث حزمة تطوير برامج (SDK) لنظام التشغيل Android.
- تثبيت NDK وCMake من داخل "استوديو Android"
أو تنزيلها وتثبيتها بشكل منفصل
- إنشاء نموذج مرحبًا JNI وتشغيله
لضمان عمل "استوديو Android" بشكل صحيح
- تثبيت python3 والمكونات الأخرى المدرجة في build.md
للنظام الأساسي المضيف.
استيراد
في هذا القسم، يمكنك تنزيل نموذج مستودع Acronos© Vulkan©، وإنشاء إصدار Android Gradle
ثم افتحه باستخدام بيئة تطوير البرامج (IDE) الخاصة بـ "استوديو Android".
- اضبط متغيّرات البيئة التالية:
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". اختر ملف > فتح واختيار
Vulkan-Samples/build/android_gradle/build.gradle
من المفترض أن يظهر تطبيق مشابه لما يلي بعد تحميل "استوديو Android"
المشروع:
الشكل 1.
نموذج المشروع في "استوديو Android"
التجميع
تم تنظيم جميع النماذج في هذا المستودع في مشروع Android واحد. لتجميع
مشروعك، فيمكنك تنفيذ أي مما يلي:
- لتجميع المصادر فقط، استخدِم القائمة إنشاء > إنشاء المشروع،
أو اكتب مفتاح الاختصار Ctrl-F9.
- لإنشاء نموذج حزمة APK، اختَر القائمة إنشاء >.
إنشاء حِزم/حِزم APK > إنشاء حِزم APK:
من المفترض أن تظهر لك رسالة الإصدار بنجاح ضمن نافذة إنشاء في "استوديو Android".
في حال ظهور أخطاء، عليك إصلاحها ثم إعادة تجميعها.
الشكل 2. إنشاء نموذج ناجح
تنفيذ
قبل تنفيذ نموذج المشروع، تأكَّد من أنّ "استوديو Android" يتعرّف على
جهاز Vulkan أو محاكي Android المتصل. من المفترض أن ترى شيئًا مثل
التالي:
الشكل 3. اربط الجهاز الاختباري بـ "استوديو Android".
لتشغيل المشروع، قم بما يلي:
- استخدم القائمة تشغيل > شغِّل vulkan_ sample أو انقر على زر التشغيل.
في شريط الأدوات، وانتظر
العيّنة ليتم تثبيتها وبدء تشغيلها على جهازك المتصل.
- على جهاز Android المرتبط، عليك الموافقة على طلبات الوصول المطلوبة.
- تفعيل السماح بالوصول لإدارة كل الملفات، ثم النقر على السهم زر الرجوع
لعرض نموذج شاشة البدء الرئيسية.
- السماح بالوصول إلى القرص:
الشكل 4. فعِّل الوصول إلى القرص.
- يُفترض أن يظهر لك نموذج شاشة القائمة الرئيسية، على غرار ما يلي:
الشكل 5. عيّنات من القائمة الرئيسية
- تصفح القائمة النموذجية واختر بعضها لتشغيلها.
إذا كنت حديث العهد بتطوير Vulkan، يمكنك البدء بنماذج "واجهة برمجة التطبيقات".
على سبيل المثال، عند النقر على "مثلّث مرحبًا"، يجب عرض مثلث.
مشابه لما يلي:
الشكل 6. نموذج Hello Triange
تم إعداد نظام التطوير الآن لتشغيل العيّنات على جهاز الاختبار.
تم تطوير Vulkan Samples لأنظمة تشغيل متعددة، بما فيها تلك الخاصة
الكمبيوتر المكتبي والهاتف المحمول. بعض النماذج ضمن الأداء والإضافات
قد تكون الأدوات غير مستقرة وتتعطّل على جهازك. وقد يرجع ذلك إلى أسباب مختلفة، مثل
كـ:
- لم يتم تصميم ميزات Vulkan المحدَّدة لنظام Android.
- إصدار نظام التشغيل Android غير متوافق.
- قدرة وحدة معالجة الرسومات في النظام الأساسي لأجهزتك
استكشاف
يُستمَد قسم Java في نموذج Vulkan من فئة NativeActivity. يجتاز التطبيق العادي
أحداث مراحل النشاط، مثل إنشاء تطبيق وبدئه وإيقافه وتدميره إلى C/C++
الرمز. في قسم C/C++ من العينة، يوجد نموذج إطار عمل
تنفِّذ وظيفة تبديل النموذج الفرعي في وقت التشغيل. بشكل عام
أحداث/رسائل نظام Android، تمر عبر المسار التالي إلى
الوصول إلى نموذج رمز Vulkan للتطبيق:
NativeSampleActivity قسم Java- قسم
NativeSampleActivity C/C++
- رمز
android_native_glue
android_main- نموذج إطار عمل
- رمز العينة الفرعية الفردية
android_main هو الجسر بين NativeSampleActivity ورمز التطبيق،
والتي يمكن أن تكون نقطة البداية لاتباع التعليمات البرمجية النموذجية. إذا قمت للتو
تريد التركيز على مصادر Vulkan المحددة، يمكنك استكشاف التعليمات البرمجية ضمن
Vulkan_Samples\samples، الذي يحتوي على ما يلي:
- نماذج لفئة "واجهة برمجة التطبيقات".
- نماذج لفئة "الأداء"
- نماذج فئات "الإضافات".
- عينات "الأدوات".
تتيح غرفة "Vulkan_Samples\shaders" تثبيت كل أدوات تظليل الألوان.
يمكنك البدء في تصفح عينات فئات "واجهة برمجة التطبيقات" للتعرف على الأساسيات
استخدام Vulkan ونموذج إطار العمل. بعد ذلك يمكنك التقدم إلى
نماذج لفئات "الأداء" و"الإضافات". بالنسبة إلى رمز أداة التظليل، يمكنك استخدام
عرض المشروع في "استوديو Android".
الشكل 7. استكشِف أداة التظليل باستخدام "استوديو YouTube".
مصادر إضافية
واجهت واجهة برمجة التطبيقات Vulkan API عدة إصدارات، وبالتالي فهي في مرحلة التطوير. ذا فولكان
ومجتمع Vulkan مجموعة كبيرة من شخصيات Vulkan
توضح استخدام واجهة برمجة التطبيقات وأفضل الممارسات. ما يلي:
بعض الموارد لتطوير تطبيق Vulkan:
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2024-08-22 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],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)."]]
