सैंपल

Android Game Development Extension के सैंपल में, एक्सटेंशन की मुख्य सुविधाओं का इस्तेमाल करने का तरीका बताया गया है. इस विषय में सैंपल और उन्हें चलाने के लिए ज़रूरी सेटिंग के बारे में बताया गया है.

ये सैंपल, डाउनलोड पेज पर उपलब्ध हैं:

• HelloJNI: यह एक शुरुआती प्रोजेक्ट है.
• Endless-Tunnel: यह सिर्फ़ Android के लिए उपलब्ध प्रोजेक्ट है.
• Teapot: यह Windows और Android के लिए एक क्रॉस-प्लैटफ़ॉर्म प्रोजेक्ट है.
• AssemblyCode-Link-Objects: एक टेंप्लेट प्रोजेक्ट, जिसमें असेंबली सोर्स कोड है.

शुरू करने से पहले

• Android Game Development Extension और सैंपल इंस्टॉल करें. ज़्यादा जानकारी के लिए, शुरुआती जानकारी देखें. इस विषय में, सैंपल बनाने और चलाने का तरीका भी बताया गया है. साथ ही, उदाहरण के तौर पर Teapot सैंपल के Android वर्शन का इस्तेमाल किया गया है.

• प्रोजेक्ट कॉन्फ़िगरेशन गाइड में, एक्सटेंशन का इस्तेमाल करने वाले प्रोजेक्ट की सेटिंग कॉन्फ़िगर करने का तरीका बताया गया है. जैसे, Android प्लैटफ़ॉर्म और APK जोड़ना.

HelloJNI

HelloJNI सैंपल एक आसान प्रोजेक्ट है. यह ऐप्लिकेशन विंडो में “JNI से नमस्ते” मैसेज दिखाता है. यह प्रोजेक्ट, Windows और Android के लिए सोर्स कोड के अलग-अलग सेट का इस्तेमाल करता है.

• Android सोर्स कोड और Gradle बिल्ड स्क्रिप्ट डायरेक्ट्री: HelloJNI\AndroidPackaging
• Windows सोर्स कोड और Visual Studio प्रोजेक्ट डायरेक्ट्री: HelloJNI

प्रोजेक्ट बनाने पर, Visual Studio ऐप्लिकेशन-लेवल की build.gradle फ़ाइल में ये सेटिंग पास करता है. Gradle बिल्ड स्क्रिप्ट में बदलाव करके, इन सेटिंग को बदला जा सकता है.

• MSBUILD_NDK_VERSION
• MSBUILD_MIN_SDK_VERSION
• MSBUILD_JNI_LIBS_SRC_DIR
• MSBUILD_ANDROID_OUTPUT_APK_NAME
• MSBUILD_ANDROID_GRADLE_BUILD_OUTPUT_DIR

सैंपल को सेट अप और चलाने के लिए:

निर्देश दिखाएं / छिपाएं

1. Visual Studio में, HelloJNI सैंपल खोलें और उसे बिल्ड करें.
2. Android arm64-v8a प्लैटफ़ॉर्म जोड़ें. ज़्यादा जानकारी के लिए, Android प्लैटफ़ॉर्म जोड़ना देखें.
3. नए प्लैटफ़ॉर्म में Android APK आइटम जोड़ें.
4. प्रोजेक्ट को कंपाइल करें.
5. यहां दिए गए Android प्लैटफ़ॉर्म जोड़ें. इसके बाद, उनमें से हर एक में Android APK आइटम जोड़ें: Android-armeabi-v7a, Android-x86, और Android-x86_64.
6. सैंपल बनाएं और चलाएं.

Endless-Tunnel

Endless-Tunnel सैंपल एक Android गेम है. इसमें खिलाड़ी को सुरंग के आखिर तक पहुंचने के लिए, सफ़ेद घन इकट्ठा करने होते हैं. इसे GitHub पर मौजूद Android एनडीके (NDK) रेपो में मौजूद OpenGL के सैंपल से पोर्ट किया गया था. सैंपल में गेम का Windows वर्शन उपलब्ध नहीं है.

सैंपल में पहले से ही सेटिंग और Android प्लैटफ़ॉर्म कॉन्फ़िगर किए गए हैं. इसलिए, बिना किसी बदलाव के Visual Studio में प्रोजेक्ट को बनाया और चलाया जा सकता है. समाधान खोलने पर, समाधान एक्सप्लोरर ये मॉड्यूल दिखाता है:

• endless-tunnel: यह गेम लॉजिक दिखाने वाला ऐप्लिकेशन मॉड्यूल है.
• glm: OpenGL Math repo का स्नैपशॉट, जो स्टैटिक लाइब्रेरी के तौर पर बनाया गया है.
• native_app_glue: यह एक NDK रैपर है, जो NativeActivity ऑब्जेक्ट के साथ काम करता है.

टीपॉट

टीपोट सैंपल में एक क्लासिक टीपोट दिखाया गया है, जिसे OpenGL ES की मदद से रेंडर किया गया है और Android गेम डेवलपमेंट एक्सटेंशन में पोर्ट किया गया है. ऐसा इन सुविधाओं को दिखाने के लिए किया गया है:

• अलग-अलग प्लैटफ़ॉर्म के लिए प्रोजेक्ट डेवलप करना: आपके पास Windows और Android के लिए, Teapot सैंपल बनाने का विकल्प है.
• कस्टम Android पैकेजिंग का इस्तेमाल: Gradle बिल्ड स्क्रिप्ट को सैंपल की रूट डायरेक्ट्री में ले जाया गया था, जहां Teapot.sln फ़ाइल मौजूद है.
• कस्टम Android कॉन्फ़िगरेशन, जिनमें पते की गड़बड़ी ठीक करने वाले टूल (ASan) और हार्डवेयर पते की गड़बड़ी ठीक करने वाले टूल (HWASan) का इस्तेमाल करने का तरीका बताया गया है.

टीपोट सैंपल को लागू करने की प्रोसेस को कई हिस्सों में बांटा गया है. यह प्रोसेस, बड़े क्रॉस-प्लैटफ़ॉर्म ऐप्लिकेशन और गेम के लिए आम तौर पर इस्तेमाल की जाती है:

• GameApplication मॉड्यूल: उपयोगकर्ता की कार्रवाइयों और ऐप्लिकेशन की स्थितियों के बारे में बताता है. जैसे, कोई उपयोगकर्ता टीपॉट घुमाता है या ऐप्लिकेशन के आंकड़े अपडेट करता है.
• GameEngine मॉड्यूल: रेंडरिंग का मुख्य मॉड्यूल लागू करता है.

सैंपल को सेट अप करने और उसे Android पर चलाने के लिए, क्विकस्टार्ट देखें. सैंपल को सेट अप करने और उसे Windows पर चलाने के लिए:

निर्देश दिखाएं / छिपाएं

1. GLEW इंस्टॉल करें:
   1. GLEW डाउनलोड करें और अनज़िप करें.
   2. बाइनरी फ़ाइलों को $your-glew-directory\bin\Release\x64 से %SystemRoot%\system32 में कॉपी करें.
2. freeglut इंस्टॉल करें:
   1. freeglut डाउनलोड करें और अनज़िप करें.
   2. $your-freeglut-directory\bin\x86\freeglut.dll को %SystemRoot%\system32 में कॉपी करें.
3. freeglut प्रोजेक्ट की डिपेंडेंसी जोड़ें:
   1. Visual Studio में Teapot.sln खोलें.
   2. मेन्यू में, डीबग करें > x64 > लोकल Windows डीबगर पर क्लिक करें.
   3. सलूशन एक्सप्लोरर में, GameApplication पर राइट क्लिक करें और प्रॉपर्टी > C/C++ > सामान्य > अन्य शामिल डायरेक्ट्री चुनें.
   4. पाथ में $your-freeglut-dir\include जोड़ें.
      
   5. ठीक है पर क्लिक करें.
   6. लिंकर > सामान्य > अन्य लाइब्रेरी डायरेक्ट्री चुनें.
   7. पाथ में $your-freeglut-dir\lib\x64 जोड़ें.
   8. ठीक है पर क्लिक करें.
   9. लिंकर > सामान्य > अन्य लाइब्रेरी डायरेक्ट्री चुनें.
   10. पाथ में freeglut.lib जोड़ें.
   11. ठीक है पर क्लिक करें.
4. GLEW प्रोजेक्ट की डिपेंडेंसी जोड़ें:
   1. सलूशन एक्सप्लोरर पैनल में, GameApplication पर राइट क्लिक करें और प्रॉपर्टी > C/C++ > सामान्य > अन्य शामिल डायरेक्ट्री चुनें.
   2. पाथ में $your-glew-dir\include जोड़ें.
   3. ठीक है पर क्लिक करें.
   4. लिंकर > सामान्य > अन्य लाइब्रेरी डायरेक्ट्री चुनें.
   5. पाथ में $your-glew-dir\lib\Release\x86 जोड़ें.
   6. ठीक है पर क्लिक करें.
   7. लिंकर > सामान्य > अन्य लाइब्रेरी डायरेक्ट्री चुनें.
   8. पाथ में glew32.lib जोड़ें.
   9. ठीक है पर क्लिक करें.
5. Windows पर सैंपल चलाएं:
   1. Visual Studio टूलबार में, लोकल Windows डीबगर चलाने के बटन पर क्लिक करें.
   2. सैंपल इस तरह दिखना चाहिए:
      

AssemblyCode-Link-Objects

यह एक टेंप्लेट प्रोजेक्ट है, जिसमें असेंबली और C/C++ सोर्स कोड से Android नेटिव लाइब्रेरी जनरेट करने का तरीका बताया गया है. ये मुख्य कॉम्पोनेंट हैं:

• AssemblyCode-Link-Objects: C++ और असेंबली सोर्स कोड से बनाई गई मुख्य Android नेटिव लाइब्रेरी.
• StaticLib: एक हेल्पर स्टैटिक लाइब्रेरी, जो from_static_lib_assembly_code_as फ़ंक्शन को एक्सपोर्ट करती है.

यह प्रोजेक्ट, कई आर्किटेक्चर के साथ काम करता है. काम करने वाले हर आर्किटेक्चर की अपनी सोर्स फ़ाइलें होती हैं. इनमें StaticLib से एक्सपोर्ट किए गए फ़ंक्शन लागू होते हैं. आपको सिर्फ़ उन प्लैटफ़ॉर्म के लिए असेंबली सोर्स फ़ाइलें शामिल करनी चाहिए जिनके लिए ऐप्लिकेशन बनाया जा रहा है. इस प्रोजेक्ट में, कस्टम बिल्ड टूल का इस्तेमाल करके, बिल्ड में असेंबली फ़ाइलें शामिल की जाती हैं.

सैंपल सेट अप करने और उसे बनाने के लिए:

निर्देश दिखाएं / छिपाएं

1. Visual Studio में, पुष्टि करें कि कस्टम बिल्ड टूल, assembly फ़ाइलों के लिए कॉन्फ़िगर किए गए हैं:
   1. सलूशन एक्सप्लोरर में, असेंबली फ़ाइल पर राइट क्लिक करें और प्रॉपर्टी पर क्लिक करें. इससे, फ़ाइल के लिए प्रॉपर्टी पेज डायलॉग खुलेगा.
   2. कॉन्फ़िगरेशन और प्लैटफ़ॉर्म चुनें. जैसे, Android-arm64-v8a के लिए सभी कॉन्फ़िगरेशन.
   3. पक्का करें कि सामान्य > बिल्ड से बाहर रखें को नहीं पर सेट किया गया हो.
   4. पक्का करें कि सामान्य > आइटम टाइप को कस्टम बिल्ड टूल पर सेट किया गया हो.
   5. अगर आपको कोई बदलाव लागू करना है, तो लागू करें पर क्लिक करें.
   6. पक्का करें कि कॉन्फ़िगरेशन प्रॉपर्टी > कस्टम बिल्ड टूल > कमांड लाइन: को $(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath) पर सेट किया गया हो. NDK में हर सीपीयू आर्किटेक्चर के लिए एक अलग असेंबलर शामिल होता है और $(AsToolExe) सही असेंबलर से मैप होता है. यह सैंपल, x86 और x86_64, दोनों तरह के Android प्रोजेक्ट बनाने के लिए, NDK टूलचैन का इस्तेमाल करता है. अगर आपको x86_64 Android प्लैटफ़ॉर्म के लिए yasm का इस्तेमाल करना है, तो इसके बजाय $(YasmToolExe) का इस्तेमाल करें.
   7. पक्का करें कि कॉन्फ़िगरेशन प्रॉपर्टी > कस्टम बिल्ड टूल > आउटपुट: को $(IntDir)%(FileName).o पर सेट किया गया हो. इस स्ट्रिंग को कमांड लाइन सेटिंग में शामिल करना ज़रूरी है.
   8. पक्का करें कि कॉन्फ़िगरेशन प्रॉपर्टी > कस्टम बिल्ड टूल > लिंक ऑब्जेक्ट: को Yes पर सेट किया गया हो.

   उदाहरण के लिए, Android-arm64-v8a सेटिंग, नीचे दिए गए स्क्रीनशॉट की तरह दिखनी चाहिए:

   
2. प्रोजेक्ट बनाएं. इससे, libAssmeblyCodeLinkObjects.so फ़ाइल बनती है:
   1. AssemblyCode-Link-Objects.sln फ़ाइल खोलें.
   2. मेन्यू में, बिल्ड करें > समाधान बनाएं पर क्लिक करें.
3. यह पुष्टि करने के लिए कि फ़ंक्शन, Android लाइब्रेरी में सही तरीके से एक्सपोर्ट किए गए हैं, nm.exe NDK टूल का इस्तेमाल करें:
   1. कमांड लाइन में, सैंपल डायरेक्ट्री पर जाएं.
   2. उस Android लाइब्रेरी की जगह पर जाएं जिसे आपके बिल्ड से जनरेट किया गया था. arm64-v8a प्लैटफ़ॉर्म के लिए, डिफ़ॉल्ट जगह की जानकारी $sample_dir\$solution_configuration\$solution_platform\$platform और $sample_dir\Debug\Android-arm64-v8a\arm64-v8a जैसी होती है.
   3. यह पुष्टि करने के लिए कि एक्सपोर्ट किए गए सिंबल सेक्शन में फ़ंक्शन मौजूद हैं, यहां दिया गया निर्देश चलाएं:

        …\ndk\toolschains\llvm\prebuilt\windows-x86_64\aarch64-linux-android\bin\nm.exe --defined-only …\Debug\Android-arm64-v8a\arm64-v8a\libAssmeblyCodeLinkObjects.so

      आउटपुट में, आपको सिंबल की एक सूची दिखेगी. इसमें ये शामिल हैं:

         T from_shared_object_assembly_code_as
         T from_static_lib_assembly_code_as

PoolAllocator

PoolAllocator सैंपल एक Android ऐप्लिकेशन है. इसमें पूल पर आधारित मेमोरी ऐलोकेटर है, जो तय साइज़ के ब्लॉक को काफ़ी असरदार तरीके से उपलब्ध कराता है.

एलोकेटर, mmap का इस्तेमाल करके, शुरू करने के समय पूरी मेमोरी को पहले से तय कर देता है. मुफ़्त ब्लॉक, लिंक की गई सूची का इस्तेमाल करके ट्रैक किए जाते हैं. इसके बाद, मेमोरी ऐलोकेशन एक तेज़ O(1) ऑपरेशन है, जो लिंक की गई सूची का हेड दिखाता है. साथ ही, डिएलोकेशन भी O(1) ऑपरेशन है, क्योंकि यह लिंक की गई सूची के पीछे ब्लॉक जोड़ता है.

सैंपल में, HWASan का इस्तेमाल करने के लिए दो सलूशन कॉन्फ़िगरेशन हैं.

• HWASan: इस कॉन्फ़िगरेशन में, पसंद के मुताबिक मेमोरी ऐलोकेटर के साथ, HWASan का इस्तेमाल करने का सबसे आसान तरीका दिखाया गया है. मेमोरी ऐलोकेटर के इंटरनल लागू होने की प्रोसेस को malloc/free कॉल से बदल दिया गया है. इन कॉल को HWASan अपने-आप ट्रैक करता है. मेमोरी ऐलोकेटर अब पूल पर आधारित ऐलोकेटर के तौर पर काम नहीं करता. हालांकि, HWASan अब भी मेमोरी से जुड़ी अहम गड़बड़ियों की पहचान करने में आपकी मदद कर सकता है. जैसे, फ़्री की गई मेमोरी को इस्तेमाल करने की गड़बड़ी.

• HWASan-Advanced: इस कॉन्फ़िगरेशन में, एलोकेटर के इस्तेमाल किए गए मूल एलोकेशन तरीके में बदलाव किए बिना, कस्टम मेमोरी एलोकेटर में HWASan को पूरी तरह से इंटिग्रेट करने का तरीका बताया गया है. यह पहले से तय किए गए पूल में मौजूद मेमोरी ब्लॉक को टैग करने के लिए, HWASan टैगिंग के तरीकों का इस्तेमाल करता है. साथ ही, ब्लॉक के साइज़ को HWASan के लिए ज़रूरी कम से कम ब्लॉक साइज़ तक राउंड करता है. साथ ही, ब्लॉक को पूल में वापस भेजने पर टैग को रीसेट करता है.

HWASan कॉन्फ़िगरेशन का इस्तेमाल करें, क्योंकि यह आसान है और इससे आपको आम तौर पर मेमोरी से जुड़ी गड़बड़ियों की पहचान करने में मदद मिल सकती है. अगर आपको यह समझना है कि HWASan कैसे काम करता है या HWASan का इस्तेमाल करते समय, अपने मेमोरी एलोकेटर के इंटरनल सेमेटिक्स को बनाए रखना है, तो HWASan-Advanced कॉन्फ़िगरेशन को लागू करने के बारे में जानें.