Merge "Docs: Adding shader-compiler documentation to initial Vulkan doc set." into mnc-docs
diff --git a/docs/html/ndk/guides/graphics/shader-compilers.jd b/docs/html/ndk/guides/graphics/shader-compilers.jd
new file mode 100644
index 0000000..c51c21c
--- /dev/null
+++ b/docs/html/ndk/guides/graphics/shader-compilers.jd
@@ -0,0 +1,194 @@
+page.title=Vulkan Shader Compilers on Android
+@jd:body
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>On this page</h2>
+
+ <ol>
+ <li><a href="#aot">AOT Compilation</a></li>
+ <li><a href="#runtime">Runtime Compilation</a></li>
+ <li><a href="#integrating">Integrating Into your Project</a></li>
+ </ol>
+ </div>
+ </div>
+
+<p>
+A Vulkan app must manage shaders differently from the way an OpenGL ES app does so:
+In OpenGL ES, you provide a shader as a set of strings forming the source text of a
+GLSL shader program. By contrast, the Vulkan API requires you to provide a shader in
+the form of an entry point in a <a href=”https://www.khronos.org/spir”>SPIR-V</a> module.
+</p>
+
+<p>
+The NDK includes a runtime library for compiling GLSL into SPIR-V.
+The runtime library is the same as the one in the
+<a href="https://github.com/google/shaderc">Shaderc</a> open source project, and use the same
+<a href="https://github.com/KhronosGroup/glslang">Glslang GLSL</a> reference compiler as a
+back end. By default, the Shaderc version of the
+compiler assumes you are compiling for Vulkan. After checking whether your code is valid for
+Vulkan, the compiler automatically enables the {@code KHR_vulkan_glsl} extension. The Shaderc
+version of the compiler also generates Vulkan-compliant SPIR-V code.
+</p>
+
+<p>
+You can choose to compile SPIR-V modules into your Vulkan app during development, a
+practice called <em>ahead-of-time</em>, or <em>AOT</em>, compiling. Alternatively,
+you can have your app compile them from shipped or procedurally generated shader
+source when needed during runtime. This practice is called <em>runtime compiling</em>.
+</p>
+
+<p>
+The rest of this page provides more detail about each practice, and then explains
+how to integrate shader compilation into your Vulkan app.
+</p>
+
+<h2 id=”aot”>AOT Compilation</h2>
+
+<p>
+For AOT compilation, we recommend the <em>glslc</em> command-line compiler from GLSL to SPIR-V.
+This compiler is available from the <a href="https://github.com/google/shaderc">Shaderc</a>
+project.</a>Many of its command-line options are similar to those of GCC and Clang, allowing
+you to integrate glslc into build systems easily.
+</p>
+
+<p>
+The glslc tool compiles a single-source file to a SPIR-V module with a single shader
+entry point. By default, the output file has the same name as that of the source file,
+but with the {@code .spv} extension appended.
+</p>
+
+<p>
+You use filename extensions to tell the glslc tool which graphics shader stage to compile,
+or whether a compute shader is being compiled. For information on how to use these filename
+extensions, and options you can use with the tool, see
+<a href="https://github.com/google/shaderc/tree/master/glslc#user-content-shader-stage-specification">
+Shader stage specification</a> in the
+<a href="https://github.com/google/shaderc/tree/master/glslc">
+glslc</a> manual.
+</p>
+
+<h2 id="runtime">Runtime Compilation</h2>
+
+<p>
+For JIT compilation of shaders during runtime, the NDK provides the libshaderc library,
+which has both C and C++ APIs.
+</p>
+
+<p>
+C++ applications should use the C++ API. We recommend that apps in other languages
+use the C API, because the C ABI is lower level, and likely to provide better stability.
+</p>
+
+<p>
+The following example shows how to use the C++ API:
+</p>
+
+<pre>
+#include <iostream>
+#include <string>
+#include <vector>
+#include <shaderc/shaderc.hpp>
+
+std::vector<uint32_t> compile_file(const std::string& name,
+ shaderc_shader_kind kind,
+ const std::string& data) {
+ shaderc::Compiler compiler;
+ shaderc::CompileOptions options;
+
+ // Like -DMY_DEFINE=1
+ options.AddMacroDefinition("MY_DEFINE", "1");
+
+ shaderc::SpvCompilationResult module = compiler.CompileGlslToSpv(
+ data.c_str(), data.size(), kind, name.c_str(), options);
+
+ if (module.GetCompilationStatus() !=
+ shaderc_compilation_status_success) {
+ std::cerr << module.GetErrorMessage();
+ }
+
+ std::vector<uint32_t> result(module.cbegin(), module.cend());
+ return result;
+}
+</pre>
+
+
+
+<h2 id=”integrating”>Integrating into Your Projects</h2>
+
+<p>
+You can integrate the Vulkan shader compiler into your app using either the project's
+{@code Android.mk} file or Gradle.
+</p>
+
+<h3 id=”androidmk”>Android.mk</h3>
+
+<p>
+Perform the following steps to use your project's {@code Android.mk}
+file to integrate the shader compiler.
+</p>
+
+<ol>
+<li>
+Include the following lines in your Android.mk file:
+<pre class="no-pretty-print">
+include $(CLEAR_VARS)
+ ...
+LOCAL_STATIC_LIBRARIES := shaderc
+ ...
+include $(BUILD_SHARED_LIBRARY)
+
+$(call import-module, third_party/shaderc)
+</pre>
+</li>
+
+<li>
+Set APP_STL to one of {@code c++_static}, {@code c++_shared}, {@code gnustl_static},
+or {@code gnustl_shared}.
+</li>
+</ol>
+
+
+
+<h3 id=”gradle”>Gradle</h3>
+
+<ol>
+<li>
+In a terminal window, navigate to
+{@code <ndk_root>/sources/third_party/shaderc/}.
+</li>
+
+<li>
+Run the following command:
+
+<pre class="no-pretty-print">
+$ ../../../ndk-build NDK_PROJECT_PATH=. APP_BUILD_SCRIPT=Android.mk \
+APP_STL:=<stl_version> APP_ABI=all libshaderc_combined
+</pre>
+
+<p>
+This command places two folders in <ndk_root>/sources/third_party/shaderc/. The directory
+structure is as follows:
+</p>
+
+<pre class="no-pretty-print">
+include/
+ shaderc/
+ shaderc.h
+ shaderc.hpp
+libs/
+ <stl_version>/
+ {all of the abis}
+ libshaderc.a
+</pre>
+</li>
+
+<li>
+Add includes and link lines as you normally would for external libraries.
+</li>
+<p>
+The STL that you use to build your program must match the {@code stl} specified in
+{@code stl_version}.
+Only {@code c++_static}, {@code c++_shared}, {@code gnustl_static}, and
+{@code gnustl_shared} are supported.
+</p>