From 2f7fc45b2bf1bc02349479c6f5c4e89597201f01 Mon Sep 17 00:00:00 2001 From: Alejandro Saucedo Date: Wed, 14 Oct 2020 08:42:42 +0100 Subject: [PATCH] Updated documentation --- README.md | 23 ++++----- docs/conf.py | 4 +- docs/index.rst | 5 +- docs/overview/advanced-examples.rst | 9 +++- docs/overview/game-engine-godot.rst | 7 +++ docs/overview/memory-management.rst | 13 +++++ docs/overview/mobile-android.rst | 3 ++ docs/overview/shaders-to-headers.rst | 47 +++++++++++++++++++ examples/android/android-simple/README.md | 9 +++- examples/godot_logistic_regression/README.md | 3 +- .../custom_module/README.md | 7 ++- .../gdnative_shared/README.md | 10 +++- 12 files changed, 115 insertions(+), 25 deletions(-) create mode 100644 docs/overview/game-engine-godot.rst create mode 100644 docs/overview/mobile-android.rst create mode 100644 docs/overview/shaders-to-headers.rst diff --git a/README.md b/README.md index 201837992..ff15caf44 100644 --- a/README.md +++ b/README.md @@ -25,13 +25,13 @@

Blazing fast, lightweight, mobile-enabled, and optimized for advanced GPU processing usecases.

-🔋 [Documentation](https://ethicalml.github.io/vulkan-kompute/) 💻 [Blog Post](https://medium.com/@AxSaucedo/machine-learning-and-data-processing-in-the-gpu-with-vulkan-kompute-c9350e5e5d3a) ⌨ [Examples](https://github.com/EthicalML/vulkan-kompute#your-first-kompute) 💾 +🔋 [Documentation](https://kompute.cc) 💻 [Blog Post](https://medium.com/@AxSaucedo/machine-learning-and-data-processing-in-the-gpu-with-vulkan-kompute-c9350e5e5d3a) ⌨ [Examples](#more-examples) 💾 ## Principles & Features * [Single header](single_include/kompute/Kompute.hpp) library for simple import to your project -* [Documentation](https://ethicalml.github.io/vulkan-kompute/) leveraging doxygen and sphinx +* [Documentation](https://kompute.cc) leveraging doxygen and sphinx * BYOV: Bring-your-own-Vulkan design to play nice with existing Vulkan applications * Non-Vulkan core naming conventions to disambiguate Vulkan vs Kompute components * Fast development cycles with shader tooling, but robust static shader binary bundles for prod @@ -51,7 +51,7 @@ This project is built using cmake, providing a simple way to integrate as static #### Your First Kompute -Pass compute shader data in glsl/hlsl text or compiled SPIR-V format (or as path to the file) - [view more examples](#more-examples). +Pass compute shader data in glsl/hlsl text or compiled SPIR-V format (or as path to the file). View [more examples](#simple-examples). ```c++ int main() { @@ -103,7 +103,7 @@ This project started after seeing that a lot of new and renowned ML & DL project The Vulkan SDK offers a great low level interface that enables for highly specialized optimizations - however it comes at a cost of highly verbose code which requires 500-2000 lines of code to even begin writing application code. This has resulted in each of these projects having to implement the same baseline to abstract the non-compute related features of Vulkan, although it's not always the case, this can result in slower development cycles, and opportunities for bugs to be introduced. -We are currently developing Vulkan Kompute not to hide the Vulkan SDK interface (as it's incredibly well designed) but to augment it with a direct focus on Vulkan's GPU computing capabilities. [This article](https://medium.com/swlh/machine-learning-and-data-processing-in-the-gpu-with-vulkan-kompute-c9350e5e5d3a) provides a high level overview of the motivations of Kompute, together with a set of hands on examples that introduce both GPU computing as well as the core Vulkan Kompute architecture. +We are currently developing Vulkan Kompute not to hide the Vulkan SDK interface (as it's incredibly well designed) but to augment it with a direct focus on Vulkan's GPU computing capabilities. [This article](https://towardsdatascience.com/machine-learning-and-data-processing-in-the-gpu-with-vulkan-kompute-c9350e5e5d3a) provides a high level overview of the motivations of Kompute, together with a set of hands on examples that introduce both GPU computing as well as the core Vulkan Kompute architecture. ## More examples @@ -111,7 +111,7 @@ We are currently developing Vulkan Kompute not to hide the Vulkan SDK interface * [Pass shader as raw string](#your-first-kompute) * [Create your custom Kompute Operations](#your-custom-kompute-operation) -* [Record batch commands with a Kompute Sequence](#record-batch-commands-with-a-kompute-sequence) +* [Record batch commands with a Kompute Sequence](#record-batch-commands) ### End-to-end examples @@ -121,7 +121,7 @@ We are currently developing Vulkan Kompute not to hide the Vulkan SDK interface ### Your Custom Kompute Operation -Build your own pre-compiled operations for domain specific workflows. +Build your own pre-compiled operations for domain specific workflows. Back to [more examples](#simple-examples) We also provide tools that allow you to [convert shaders into C++ headers](https://github.com/EthicalML/vulkan-kompute/blob/master/scripts/convert_shaders.py#L40). @@ -164,9 +164,9 @@ int main() { } ``` -#### Record batch commands with a Kompute Sequence +#### Record batch commands -Record commands in a single submit by using a Sequence to send in batch to GPU. +Record commands in a single submit by using a Sequence to send in batch to GPU. Back to [more examples](#simple-examples) ```c++ int main() { @@ -214,13 +214,6 @@ int main() { } ``` -## Advanced Examples - -We cover more advanced examples and applications of Vulkan Kompute, such as machine learning algorithms built on top of Kompute. - -You can find these in the end to end examples [section](#end-to-end-examples). - - ## Components & Architecture The core architecture of Kompute include the following: diff --git a/docs/conf.py b/docs/conf.py index 5ba4a71cb..cce062ef0 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,11 +18,11 @@ # -- Project information ----------------------------------------------------- project = 'Vulkan Kompute' -copyright = '2020, Alejandro Saucedo' +copyright = '2020, The Institute for Ethical AI & Machine Learning' author = 'Alejandro Saucedo' # The full version, including alpha/beta/rc tags -release = '0.1.0' +release = '0.3.2' # -- General configuration --------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index ecc6cbdb2..d29f1fbf6 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,7 +11,10 @@ Index :maxdepth: 2 :titlesonly: - Advanced Examples + Advanced Examples + Mobile App Intergration (Android) + Game Engine Integration (Godot Engine) + Converting GLSL/HLSL Shaders to C++ Headers Class Reference Memory management principles Code Index diff --git a/docs/overview/advanced-examples.rst b/docs/overview/advanced-examples.rst index dc0e43583..dcc7b1e08 100644 --- a/docs/overview/advanced-examples.rst +++ b/docs/overview/advanced-examples.rst @@ -2,8 +2,15 @@ Advanced Examples ================== -The power of Kompute comes in when the interface is used for complex computations. In this section we cover a set of advanced examples including machine learning and data processing applications that showcase the more advanced capabilities of Kompute. +The power of Kompute comes in when the interface is used for complex computations. This section contains an outline of the advanced / end-to-end examples available. +Currently the advanced examples available include: + +* `Machine Learning Logistic Regression Implementation `_ and consists primarily of a Python CLI that can be called to pass arguments. + +In order to use this Python utility, you will have to first install the dependencies outlined by the `scripts/requirements.txt` file. You will need to have python 3 and pip3 installed. + +.. code-block:: bash + :linenos: + + python3 -m pip install -r scripts/requirements.txt + +Once the dependencies can be installed, you can run the Python script directly through the file as `python3 scripts/convert_shaders.py`. + +You can run `python3 scripts/convert_shaders.py --help` to see all the options available - namely: + +.. code-block:: bash + :linenos: + + > python3 scripts/convert_shaders.py --help + + Usage: convert_shaders.py [OPTIONS] + + CLI function for shader generation + + Options: + -p, --shader-path TEXT The path for the directory to build and convert + shaders [required] + + -s, --shader-binary TEXT The path for the directory to build and convert + shaders [required] + + -c, --header-path TEXT The (optional) output file for the cpp header + files + + -v, --verbose Enable versbosity if flag is provided + --help Show this message and exit. + +You can see the command that converts the shaders `in the makefile `_ to get an idea of how you would be able to use this utility. + + diff --git a/examples/android/android-simple/README.md b/examples/android/android-simple/README.md index 5e8d53c45..e2a347589 100644 --- a/examples/android/android-simple/README.md +++ b/examples/android/android-simple/README.md @@ -1,10 +1,12 @@ +# Kompute Mobile App Integration (Android) + +This is the accompanying code for the Blog post ["Supercharging your Mobile Apps with On-Device GPU Accelerated Machine Learning using the Android NDK & Vulkan Kompute"](https://towardsdatascience.com/gpu-accelerated-machine-learning-in-your-mobile-applications-using-the-android-ndk-vulkan-kompute-1e9da37b7617). + - diff --git a/examples/godot_logistic_regression/README.md b/examples/godot_logistic_regression/README.md index c30de639e..2d96eacc8 100644 --- a/examples/godot_logistic_regression/README.md +++ b/examples/godot_logistic_regression/README.md @@ -1,4 +1,5 @@ -# Godot Kompute ML Example + +# Kompute Game Engine Integration (Godot) ![](https://github.com/EthicalML/vulkan-kompute/raw/master/docs/images/komputer-godot-4.gif) diff --git a/examples/godot_logistic_regression/custom_module/README.md b/examples/godot_logistic_regression/custom_module/README.md index 3fc2ee95d..97dda725c 100644 --- a/examples/godot_logistic_regression/custom_module/README.md +++ b/examples/godot_logistic_regression/custom_module/README.md @@ -1,4 +1,9 @@ -# Vulkan Kompute Godot Example + +## Godot Engine Integration: Godot Engine Source Module + +This is the accompanying code for the Blog post ["Supercharging Game Development with GPU Accelerated Machine Learning"](https://medium.com/@AxSaucedo/supercharging-game-development-with-gpu-accelerated-ml-using-vulkan-kompute-the-godot-game-engine-4e75a84ea9f0). + +This section contains the implementation of the Kompute module as a statically compile module built with the Godot engine source code. This approach requires re-compiling the Godot engine source code. ![](https://github.com/EthicalML/vulkan-kompute/raw/master/docs/images/komputer-godot-4.gif) diff --git a/examples/godot_logistic_regression/gdnative_shared/README.md b/examples/godot_logistic_regression/gdnative_shared/README.md index 975722e7b..433bf5b56 100644 --- a/examples/godot_logistic_regression/gdnative_shared/README.md +++ b/examples/godot_logistic_regression/gdnative_shared/README.md @@ -1,8 +1,14 @@ -# Vulkan Kompute Godot Example + +## Godot Engine Integration: GdNative Library + +This is the accompanying code for the Blog post ["Supercharging Game Development with GPU Accelerated Machine Learning"](https://medium.com/@AxSaucedo/supercharging-game-development-with-gpu-accelerated-ml-using-vulkan-kompute-the-godot-game-engine-4e75a84ea9f0). + +This section contains the implementation of the Kompute module as a shared GdNative Library that can be loaded dynamically through the Godot engine. This approach does not require re-compiling the Godot engine source code. + ![](https://github.com/EthicalML/vulkan-kompute/raw/master/docs/images/komputer-godot-4.gif) -## Set Up Dependencies +### Set Up Dependencies We can get all the required dependencies from godot by running
-

Vulkan Kompute Android

Example Running Logistic Regression with Vulkan Kompute in Android Phones

@@ -14,6 +16,9 @@ The example uses the Kompute build in the relative folder to build the respectiv The build structure provides a range of options to build in different Android hardware. This example was tested in various emulators including Pixel 2, and a physical Samsung S7 phone.

+ +
+