Merge pull request #1381 from jasonrandrews/review

Review WebGPU Learning Path

content/learning-paths/smartphones-and-mobile/android_webgpu_dawn/1-webgpu-fundamentals.md

@@ -8,9 +8,9 @@ layout: learningpathall
 
 ## What is WebGPU?
 
-WebGPU is the successor to [WebGL](https://www.khronos.org/webgl/wiki/), a well adopted modern API standard for interfacing with GPUs. WebGPU provides better compatibility with modern GPUs, support for general-purpose GPU computations, faster operations, and access to more advanced GPU features. It is designed to provide a _unified access_ to GPUs, agnostic to GPU vendors and operating systems.
+WebGPU is the successor to WebGL, a well adopted modern API standard for interfacing with GPUs. WebGPU provides better compatibility with modern GPUs, support for general-purpose GPU computations, faster operations, and access to more advanced GPU features. It is designed to provide a _unified access_ to GPUs, agnostic to GPU vendors and operating systems.
 
-WebGPU is a Render Hardware Interface built on top of various backends APIs like Vulkan, DirectX, and Metal (depending on the operating system). 
+WebGPU is a Render Hardware Interface built on top of various backend APIs like Vulkan, DirectX, and Metal (depending on the operating system). 
 
 WebGPU is available through web browsers using the webgpu.h header file. 
 
@@ -42,7 +42,7 @@ The limitations of the API due to privacy considerations can be disabled when us
 
 The initial target for WebGPU was JavaScript.  The initial `webgpu.h` header file is written in C. 
 
-This Learning Path uses C++ rather than JavaScript or C because of the following benefits:
+This Learning Path uses C++ rather than JavaScript or C because for the following reasons:
 
 * C++ is still the primary language used for high performance graphics applications, such as video games, render engines, and modeling tools.
 * The level of abstraction and control of C++ is well suited for interacting with graphics APIs in general.
@@ -52,7 +52,7 @@ This Learning Path uses C++ rather than JavaScript or C because of the following
 
 Since WebGPU is a standard and not an implementation, there are different implementations. 
 
-[Dawn](https://github.com/google/dawn) is an open-source and cross-platform implementation of the WebGPU standard. 
+[Dawn](https://github.com/google/dawn) is an open-source, cross-platform implementation of the WebGPU standard. 
 
 It implements the WebGPU functionality specified in `webgpu.h`. Dawn is meant to be integrated as part of a larger system like Chromium or a native Android Application.
 
@@ -61,7 +61,7 @@ Dawn provides several WebGPU building blocks:
 * WebGPU C/C++ headers that applications and other building blocks use, including a header file and C++ wrapper.
 * A "native" implementation of WebGPU using appropriate APIs: D3D12, Metal, Vulkan and OpenGL. 
 * A client-server implementation of WebGPU for applications that are in a sandbox without access to native drivers.
-* Tint, a compiler for the WebGPU Shader Language (WGSL), that can be used to convert shaders to and from WGSL.
+* Tint, a compiler for the WebGPU Shader Language (WGSL), that converts shaders to and from WGSL.
 
 Because it is written in C++, Dawn provides better error messages and logging. Because it is open-source, it is easier to inspect stack traces when applications crash.
 

content/learning-paths/smartphones-and-mobile/android_webgpu_dawn/2-env-setup.md

@@ -16,7 +16,6 @@ The first step is to prepare a development environment with the required softwar
 
 * [Android Studio](https://developer.android.com/studio)
 * [Arm Performance Studio](https://www.arm.com/products/development-tools/graphics/arm-performance-studio) 
-* Git
 * Python 3.10 or later
 
 You can use any computer and operating system which supports the above software. 
@@ -50,7 +49,7 @@ Profiling is an important step in the Android application development cycle.
 
 The default profiler in the Android Studio is great to profile CPU related metrics, but does not provide GPU details. 
 
-Arm Performance Studio is a comprehensive profiling tool to profile both CPU and GPU. 
+Arm Performance Studio is a comprehensive profiling tool to profile both CPUs and GPUs. 
 
 One of the components of Performance Studio is Streamline. Streamline captures data from multiple sources, including:
 
@@ -62,7 +61,7 @@ One of the components of Performance Studio is Streamline. Streamline captures d
 Install Arm Performance Studio using the [install guide](/install-guides/ams/).
 
 {{% notice Tip %}}
-If you want to learn more about Arm Performance Studio and Streamline before continuing, refer to ["Get started with Arm Performance Studio for mobile"](https://learn.arm.com/learning-paths/smartphones-and-mobile/ams/ams/)
+If you want to learn more about Arm Performance Studio and Streamline before continuing, refer to [Get started with Arm Performance Studio for mobile](https://learn.arm.com/learning-paths/smartphones-and-mobile/ams/ams/)
 {{% /notice %}}
 
 Android Studio and Arm Performance Studio are now installed and you are ready to create a WebGPU Android application. 

content/learning-paths/smartphones-and-mobile/android_webgpu_dawn/3-integrate-dawn.md

@@ -14,10 +14,14 @@ Open Android studio, click `New Project` and select `Game Activity (C++)` as sho
 
 ![New Game Activity #center](./images/android_studio_new_game_activity.png "New C++ Game Activity")
 
+Set the `Name` to be `dawnwebgpu`. 
+
 Select `Next` to continue. 
 
 Finish the new project creation by accepting all defaults until the project is created. 
 
+The project is created in `~/AndroidStudioProjects`.
+
 ## About the Game Activity
 
 GameActivity is a Jetpack library designed to assist Android games in processing app cycle commands, input events, and text input in the application's C/C++ code. 
@@ -26,7 +30,7 @@ GameActivity is a direct descendant of NativeActivity and shares a similar archi
 
 ![Game Activity Architecture #center](./images/GameActivityArchitecture.png "Game Activity Architecture")
 
-With GameActivity, you can focus on your core game development and avoid spending excessive time dealing with the Java Native Interface (JNI) code.
+With GameActivity, you can focus on your game development and avoid spending excessive time dealing with the Java Native Interface (JNI) code.
 
 GameActivity performs the following functions:
 
@@ -38,17 +42,40 @@ GameActivity performs the following functions:
 You can find more information about Android Game Activity and its capabilities in the [Game Activity documentation](https://developer.android.com/games/agdk/game-activity).
 {{% /notice %}}
 
+## Download project source files
+
+To create a WebGPU application, a number of files from GitHub are doing to be added to your Game Activity project. The objective is to show you how to take the Game Activity template and modify it to become a WebGPU application. 
+
+To get started, open a terminal, create a new directory, and download the project files:
+
+```bash
+mkdir ~/webgpu-files ; cd ~/webgpu-files
+wget https://github.com/varunchariArm/Android_DawnWebGPU/archive/refs/heads/main.zip
+```
+
+Unzip the project files:
+
+```bash
+unzip main.zip
+```
+
+Yow now have a directory named `Android_DawnWebGPU-main` in your `webgpu-files` directory. 
+
+During the next sections you will copy some of the required files from the `Android_DawnWebGPU-main` directory to your Game Activity project to learn how to create WebGPU applications.
+
 ## Upgrade the application to include Dawn
 
+Return to Android Studio and start work on the WebGPU application. 
+
 The Android Game Activity framework uses OpenGLES3 for graphics. 
 
 You can remove this dependency and replace it with WebGPU. 
 
-Start by including the [webgpu.hpp](https://github.com/varunchariArm/Android_DawnWebGPU/blob/main/app/src/main/cpp/webgpu/include/webgpu/webgpu.hpp) header file in the project:
+Add WebGPU to the project using the following steps:
 
 1. In Android Studio, navigate to the project view and find the `app` --> `cpp` folder.
 
-Open terminal in Android Studio. You should be in the MyApplication directory.
+Open terminal in Android Studio. You should be in the `dawnwebgpu` directory.
 
 2. Create a new directory and download the WebGPU header file from GitHub
 
@@ -57,57 +84,62 @@ Run the commands below to download the `webgpu.hpp` header file:
 ```console
 mkdir -p app/src/main/cpp/webgpu/include/webgpu
 cd app/src/main/cpp/webgpu/include/webgpu
-wget https://raw.githubusercontent.com/varunchariArm/Android_DawnWebGPU/refs/heads/main/app/src/main/cpp/webgpu/include/webgpu/webgpu.hpp
+cp ~/webgpu-files/Android_DawnWebGPU-main/app/src/main/cpp/webgpu/include/webgpu/webgpu.hpp .
 cd ../..
 ```
 
-3. Next copy the remaining files in the [webgpu](https://github.com/varunchariArm/Android_DawnWebGPU/tree/main/app/src/main/cpp/webgpu) directory to corresponding directory in your project.
+3. Next copy the remaining WebGPU files to your project. 
 
 ```console
-wget https://raw.githubusercontent.com/varunchariArm/Android_DawnWebGPU/refs/heads/main/app/src/main/cpp/webgpu/CMakeLists.txt
-wget https://raw.githubusercontent.com/varunchariArm/Android_DawnWebGPU/refs/heads/main/app/src/main/cpp/webgpu/FetchDawn.cmake
-wget https://raw.githubusercontent.com/varunchariArm/Android_DawnWebGPU/refs/heads/main/app/src/main/cpp/webgpu/fetch_dawn_dependencies.py
-wget https://raw.githubusercontent.com/varunchariArm/Android_DawnWebGPU/refs/heads/main/app/src/main/cpp/webgpu/webgpu.cmake
+cp ~/webgpu-files/Android_DawnWebGPU-main/app/src/main/cpp/webgpu/CMakeLists.txt .
+cp ~/webgpu-files/Android_DawnWebGPU-main/app/src/main/cpp/webgpu/FetchDawn.cmake .
+cp ~/webgpu-files/Android_DawnWebGPU-main/app/src/main/cpp/webgpu/fetch_dawn_dependencies.py .
+cp ~/webgpu-files/Android_DawnWebGPU-main/app/src/main/cpp/webgpu/webgpu.cmake .
+cd ..
 ```
 
-Notice the [FetchDawn.cmake](https://github.com/varunchariArm/Android_DawnWebGPU/blob/main/app/src/main/cpp/webgpu/FetchDawn.cmake) uses a stable `chromium/6536` branch of Dawn repository. 
+Notice that `FetchDawn.cmake` uses a stable `chromium/6536` branch of Dawn repository. 
 
 {{% notice Note %}}
 WebGPU is constantly evolving standard and hence its implementation, Dawn is also under active development. For sake of stability, we have chosen a stable branch for our development. Updating to latest or different branch may cause breakage.
 {{% /notice %}}
 
-To add Dawn to our application, we have 2 options:
+To add Dawn to our application, there are 2 options:
 
 * Create a shared/static library from the Dawn source and use it in application.
-* Download the source as a dependency and build it as part of the project build
+* Download the source as a dependency and build it as part of the project build.
 
-We are choosing the second option, since it provides more debug flexibility.
+You will use the second option, since it provides more debug flexibility.
 
-The [webgpu/webgpu.cmake](https://github.com/varunchariArm/Android_DawnWebGPU/blob/main/app/src/main/cpp/webgpu/webgpu.cmake) and [CMakeLists.txt](https://github.com/varunchariArm/Android_DawnWebGPU/blob/main/app/src/main/cpp/CMakeLists.txt) file facilitates downloading and building WebGPU with Dawn implementation and integrating Dawn into our main project
+The files `webgpu/webgpu.cmake` and `CMakeLists.txt` facilitate downloading and building WebGPU with Dawn implementation and integrating Dawn into the project.
 
-Run the build:
+4. Add WebGPU to the project.
 
-```console
-cmake .
-make -C _deps/dawn-build
-```
+WebGPU is added to the project in the file `CMakeLists.txt`.
 
-This section doesn't seen needed, just information:
+Copy the updated file by running the command:
 
 ```bash
+cp ~/webgpu-files/Android_DawnWebGPU-main/app/src/main/cpp/CMakeLists.txt .
+```
+
+Review `CMakeLists.txt` and see that the `options`, `include`, and `add_subdirectory` are added from the original Game Activity file.
+
+```output
 #Set Dawn build options
 option(DAWN_FETCH_DEPENDENCIES "" ON)
 option(DAWN_USE_GLFW "" ON)
 option(DAWN_SUPPORTS_GLFW_FOR_WINDOWING "" OFF)
 option(DAWN_USE_X11 "" OFF)
 option(ENABLE_PCH "" OFF)
-```
 
-4. Add WebGPU to the project.
+include(utils.cmake)
+add_subdirectory(webgpu)
+```
 
-Edit the file `CMakeLists.txt` to remove the WebGL and add `webgpu` libraries. 
+Also look at the `CMakeLists.txt` file and see that the `target_link_libraries` is changed to remove the WebGL components and add the `webgpu` libraries. 
 
-``` bash
+```output
 # Configure libraries CMake uses to link your target library.
 target_link_libraries(dawnwebgpu
         # The game activity
@@ -120,6 +152,7 @@ target_link_libraries(dawnwebgpu
         log)
 ```
 
-The project is now ready to build. 
 
 The `webgpu.hpp` header file acts like an interface, exposing all WebGPU functions and variables to the main Application.
+
+Navigate to the next section to continue building the WebGPU application.