Docs: Adding shader-compiler documentation to initial Vulkan doc set.

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>