com.jogamp.opengl.util.glsl

## Class ShaderCode

- java.lang.Object
- - com.jogamp.opengl.util.glsl.ShaderCode

-     public class ShaderCode
      extends Object

  Convenient shader code class to use and instantiate vertex or fragment programs.

  A documented example of how to use this code is available `here` and `here`.

  Support for `GL4.GL_TESS_CONTROL_SHADER` and `GL4.GL_TESS_EVALUATION_SHADER` was added since 2.2.1.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `DEBUG_CODE`
    `static String` | `DISABLE` Behavior for GLSL extension directive, see `createExtensionDirective(String, String)`, value "disable".
    `static String` | `ENABLE` Behavior for GLSL extension directive, see `createExtensionDirective(String, String)`, value "enable".
    `static String` | `es2_default_precision_fp` Default precision of `ES2` for `fragment-shader`: "\nprecision mediump float;\nprecision mediump int;\n/*precision lowp sampler2D;*/\n/*precision lowp samplerCube;*/\n"
    `static String` | `es2_default_precision_vp` Default precision of `ES2` for `vertex-shader`: "\nprecision highp float;\nprecision highp int;\n/*precision lowp sampler2D;*/\n/*precision lowp samplerCube;*/\n"
    `static String` | `es3_default_precision_fp` Default precision of `ES3` for `fragment-shader`: "\nprecision highp float;\nprecision highp int;\n/*precision lowp sampler2D;*/\n/*precision lowp samplerCube;*/\n", same as for `vertex-shader`, i.e `es3_default_precision_vp`, due to ES 3.x requirements of using same precision for uniforms!
    `static String` | `es3_default_precision_vp` Default precision of `ES3` for `vertex-shader`: "\nprecision highp float;\nprecision highp int;\n/*precision lowp sampler2D;*/\n/*precision lowp samplerCube;*/\n"
    `static String` | `gl3_default_precision_fp` Default precision of GLSL ≥ 1.30 as required until < 1.50 for `fragment-shader`: "\nprecision highp float;\nprecision mediump int;\n/*precision mediump sampler2D;*/\n".
    `static String` | `gl3_default_precision_vp_gp` Default precision of GLSL ≥ 1.30 as required until < 1.50 for `vertex-shader` or `geometry-shader`: "\nprecision highp float;\nprecision highp int;\n".
    `static String` | `REQUIRE` Behavior for GLSL extension directive, see `createExtensionDirective(String, String)`, value "require".
    `static String` | `SUB_PATH_NVIDIA` Unique relative path for binary shader resources for `NVIDIA`: `"nvidia"`
    `static String` | `SUFFIX_FRAGMENT_BINARY` Unique resource suffix for `GL2ES2.GL_FRAGMENT_SHADER` in binary: `"bfp"`
    `static String` | `SUFFIX_FRAGMENT_SOURCE` Unique resource suffix for `GL2ES2.GL_FRAGMENT_SHADER` in source code: `"fp"`
    `static String` | `SUFFIX_GEOMETRY_BINARY` Unique resource suffix for `GL3.GL_GEOMETRY_SHADER` in binary: `"bgp"`
    `static String` | `SUFFIX_GEOMETRY_SOURCE` Unique resource suffix for `GL3.GL_GEOMETRY_SHADER` in source code: `"gp"`
    `static String` | `SUFFIX_TESS_CONTROL_BINARY` Unique resource suffix for `GL4.GL_TESS_CONTROL_SHADER` in binary: `"btcp"`
    `static String` | `SUFFIX_TESS_CONTROL_SOURCE` Unique resource suffix for `GL4.GL_TESS_CONTROL_SHADER` in source code: `"tcp"`
    `static String` | `SUFFIX_TESS_EVALUATION_BINARY` Unique resource suffix for `GL4.GL_TESS_EVALUATION_SHADER` in binary: `"btep"`
    `static String` | `SUFFIX_TESS_EVALUATION_SOURCE` Unique resource suffix for `GL4.GL_TESS_EVALUATION_SHADER` in source code: `"tep"`
    `static String` | `SUFFIX_VERTEX_BINARY` Unique resource suffix for `GL2ES2.GL_VERTEX_SHADER` in binary: `"bvp"`
    `static String` | `SUFFIX_VERTEX_SOURCE` Unique resource suffix for `GL2ES2.GL_VERTEX_SHADER` in source code: `"vp"`
    `static String` | `WARN` Behavior for GLSL extension directive, see `createExtensionDirective(String, String)`, value "warn".

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ShaderCode(int type, int count, CharSequence[][] source)`
    `ShaderCode(int type, int count, int binFormat, Buffer binary)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `addDefaultShaderPrecision(GL2ES2 gl, int pos)` Adds default precision to source code at given position if required, i.e.
    `int` | `addGLSLVersion(GL2ES2 gl)` Add GLSL version at the head of this shader source code.
    `boolean` | `compile(GL2ES2 gl)`
    `boolean` | `compile(GL2ES2 gl, PrintStream verboseOut)`
    `static ShaderCode` | `create(GL2ES2 gl, int type, Class<?> context, String srcRoot, String binRoot, String basename, boolean mutableStringBuilder)` Simplified variation of `#create(GL2ES2, int, int, Class, String, String[], String, String)`.
    `static ShaderCode` | `create(GL2ES2 gl, int type, int count, Class<?> context, String[] sourceFiles, boolean mutableStringBuilder)` Creates a complete `ShaderCode` object while reading all shader source of `sourceFiles`, which location is resolved using the `context` class, see `#readShaderSource(Class, String)`.
    `static ShaderCode` | `create(GL2ES2 gl, int type, int count, Class<?> context, String srcRoot, String[] srcBasenames, String binRoot, String binBasename, boolean mutableStringBuilder)` Convenient creation method for instantiating a complete `ShaderCode` object either from source code using `#create(GL2ES2, int, int, Class, String[])`, or from a binary code using `create(int, int, Class, int, String)`, whatever is available first.
    `static ShaderCode` | `create(int type, int count, Class<?> context, int binFormat, String binaryFile)` Creates a complete `ShaderCode` object while reading the shader binary of `binaryFile`, which location is resolved using the `context` class, see `readShaderBinary(Class, String)`.
    `static String` | `createExtensionDirective(String extensionName, String behavior)` Creates a GLSL extension directive.
    `int` | `defaultShaderCustomization(GL2ES2 gl, boolean preludeVersion, boolean addDefaultPrecision)` Default customization of this shader source code.
    `int` | `defaultShaderCustomization(GL2ES2 gl, boolean preludeVersion, String esDefaultPrecision)` Default customization of this shader source code.
    `void` | `destroy(GL2ES2 gl)`
    `void` | `dumpShaderSource(PrintStream out)`
    `boolean` | `equals(Object obj)`
    `static String` | `getBinarySubPath(int binFormat)` Returns a unique relative path for binary shader resources as follows: `NVIDIA`: `SUB_PATH_NVIDIA`
    `static String` | `getFileSuffix(boolean binary, int type)` Returns a unique suffix for shader resources as follows: Source `vertex`: `SUFFIX_VERTEX_SOURCE` `fragment`: `SUFFIX_FRAGMENT_SOURCE` `geometry`: `SUFFIX_GEOMETRY_SOURCE` `tess-ctrl`: `SUFFIX_TESS_CONTROL_SOURCE` `tess-eval`: `SUFFIX_TESS_EVALUATION_SOURCE` Binary `vertex`: `SUFFIX_VERTEX_BINARY` `fragment`: `SUFFIX_FRAGMENT_BINARY` `geometry`: `SUFFIX_GEOMETRY_BINARY` `tess-ctrl`: `SUFFIX_TESS_CONTROL_BINARY` `tess-eval`: `SUFFIX_TESS_EVALUATION_BINARY`
    `int` | `hashCode()`
    `int` | `id()` returns the uniq shader id as an integer
    `int` | `insertShaderSource(int shaderIdx, int position, CharSequence data)` Adds `data` at `position` in shader source for shader `shaderIdx`.
    `int` | `insertShaderSource(int shaderIdx, int position, Class<?> context, String path)` Adds shader source located in `path`, either relative to the `context` class or absolute as-is at `position` in shader source for shader `shaderIdx`.
    `int` | `insertShaderSource(int shaderIdx, String tag, int fromIndex, CharSequence data)` Adds `data` after the line containing `tag`.
    `boolean` | `isValid()`
    `static ByteBuffer` | `readShaderBinary(Class<?> context, String path)` Reads shader binary located in `path`, either relative to the `context` class or absolute as-is.
    `static CharSequence` | `readShaderSource(Class<?> context, String path, boolean mutableStringBuilder)` Reads shader source located in `path`, either relative to the `context` class or absolute as-is.
    `static void` | `readShaderSource(Class<?> context, URLConnection conn, StringBuilder result)`
    `int` | `replaceInShaderSource(String oldName, String newName)` Replaces `oldName` with `newName` in all shader sources.
    `static boolean` | `requiresDefaultPrecision(GL2ES2 gl)` Returns true, if GLSL version requires default precision, i.e.
    `static boolean` | `requiresGL3DefaultPrecision(GL2ES2 gl)` Returns true, if GL3 GLSL version requires default precision, i.e.
    `IntBuffer` | `shader()`
    `Buffer` | `shaderBinary()`
    `int` | `shaderBinaryFormat()`
    `CharSequence[][]` | `shaderSource()`
    `int` | `shaderType()`
    `String` | `shaderTypeStr()`
    `static String` | `shaderTypeStr(int type)`
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DEBUG_CODE

          public static final boolean DEBUG_CODE

    - #### SUFFIX_VERTEX_SOURCE

          public static final String SUFFIX_VERTEX_SOURCE

      Unique resource suffix for `GL2ES2.GL_VERTEX_SHADER` in source code: `"vp"`
      See Also:
        Constant Field Values

    - #### SUFFIX_VERTEX_BINARY

          public static final String SUFFIX_VERTEX_BINARY

      Unique resource suffix for `GL2ES2.GL_VERTEX_SHADER` in binary: `"bvp"`
      See Also:
        Constant Field Values

    - #### SUFFIX_GEOMETRY_SOURCE

          public static final String SUFFIX_GEOMETRY_SOURCE

      Unique resource suffix for `GL3.GL_GEOMETRY_SHADER` in source code: `"gp"`
      See Also:
        Constant Field Values

    - #### SUFFIX_GEOMETRY_BINARY

          public static final String SUFFIX_GEOMETRY_BINARY

      Unique resource suffix for `GL3.GL_GEOMETRY_SHADER` in binary: `"bgp"`
      See Also:
        Constant Field Values

    - #### SUFFIX_TESS_CONTROL_SOURCE

          public static final String SUFFIX_TESS_CONTROL_SOURCE

      Unique resource suffix for `GL4.GL_TESS_CONTROL_SHADER` in source code: `"tcp"`
      Since:
        2.2.1
      See Also:
        Constant Field Values

    - #### SUFFIX_TESS_CONTROL_BINARY

          public static final String SUFFIX_TESS_CONTROL_BINARY

      Unique resource suffix for `GL4.GL_TESS_CONTROL_SHADER` in binary: `"btcp"`
      Since:
        2.2.1
      See Also:
        Constant Field Values

    - #### SUFFIX_TESS_EVALUATION_SOURCE

          public static final String SUFFIX_TESS_EVALUATION_SOURCE

      Unique resource suffix for `GL4.GL_TESS_EVALUATION_SHADER` in source code: `"tep"`
      Since:
        2.2.1
      See Also:
        Constant Field Values

    - #### SUFFIX_TESS_EVALUATION_BINARY

          public static final String SUFFIX_TESS_EVALUATION_BINARY

      Unique resource suffix for `GL4.GL_TESS_EVALUATION_SHADER` in binary: `"btep"`
      Since:
        2.2.1
      See Also:
        Constant Field Values

    - #### SUFFIX_FRAGMENT_SOURCE

          public static final String SUFFIX_FRAGMENT_SOURCE

      Unique resource suffix for `GL2ES2.GL_FRAGMENT_SHADER` in source code: `"fp"`
      See Also:
        Constant Field Values

    - #### SUFFIX_FRAGMENT_BINARY

          public static final String SUFFIX_FRAGMENT_BINARY

      Unique resource suffix for `GL2ES2.GL_FRAGMENT_SHADER` in binary: `"bfp"`
      See Also:
        Constant Field Values

    - #### SUB_PATH_NVIDIA

          public static final String SUB_PATH_NVIDIA

      Unique relative path for binary shader resources for `NVIDIA`: `"nvidia"`
      See Also:
        Constant Field Values

    - #### es2_default_precision_vp

          public static final String es2_default_precision_vp

      Default precision of `ES2` for `vertex-shader`: "\nprecision highp float;\nprecision highp int;\n/*precision lowp sampler2D;*/\n/*precision lowp samplerCube;*/\n"
      See Also:
        Constant Field Values

    - #### es2_default_precision_fp

          public static final String es2_default_precision_fp

      Default precision of `ES2` for `fragment-shader`: "\nprecision mediump float;\nprecision mediump int;\n/*precision lowp sampler2D;*/\n/*precision lowp samplerCube;*/\n"
      See Also:
        Constant Field Values

    - #### es3_default_precision_vp

          public static final String es3_default_precision_vp

      Default precision of `ES3` for `vertex-shader`: "\nprecision highp float;\nprecision highp int;\n/*precision lowp sampler2D;*/\n/*precision lowp samplerCube;*/\n"
      See Also:
        Constant Field Values

    - #### es3_default_precision_fp

          public static final String es3_default_precision_fp

      Default precision of `ES3` for `fragment-shader`: "\nprecision highp float;\nprecision highp int;\n/*precision lowp sampler2D;*/\n/*precision lowp samplerCube;*/\n", same as for `vertex-shader`, i.e `es3_default_precision_vp`, due to ES 3.x requirements of using same precision for uniforms!
      See Also:
        Constant Field Values

    - #### gl3_default_precision_vp_gp

          public static final String gl3_default_precision_vp_gp

      Default precision of GLSL ≥ 1.30 as required until < 1.50 for `vertex-shader` or `geometry-shader`: "\nprecision highp float;\nprecision highp int;\n". See GLSL Spec 1.30-1.50 Section 4.5.3.
      See Also:
        Constant Field Values

    - #### gl3_default_precision_fp

          public static final String gl3_default_precision_fp

      Default precision of GLSL ≥ 1.30 as required until < 1.50 for `fragment-shader`: "\nprecision highp float;\nprecision mediump int;\n/*precision mediump sampler2D;*/\n". See GLSL Spec 1.30-1.50 Section 4.5.3.
      See Also:
        Constant Field Values

    - #### REQUIRE

          public static final String REQUIRE

      Behavior for GLSL extension directive, see `createExtensionDirective(String, String)`, value "require".
      See Also:
        Constant Field Values

    - #### ENABLE

          public static final String ENABLE

      Behavior for GLSL extension directive, see `createExtensionDirective(String, String)`, value "enable".
      See Also:
        Constant Field Values

    - #### DISABLE

          public static final String DISABLE

      Behavior for GLSL extension directive, see `createExtensionDirective(String, String)`, value "disable".
      See Also:
        Constant Field Values

    - #### WARN

          public static final String WARN

      Behavior for GLSL extension directive, see `createExtensionDirective(String, String)`, value "warn".
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ShaderCode

          public ShaderCode(int type,
                    int count,
                    CharSequence[][] source)

      Parameters:
        `type` - either `GL2ES2.GL_VERTEX_SHADER`, `GL2ES2.GL_FRAGMENT_SHADER`, `GL3.GL_GEOMETRY_SHADER`, `GL4.GL_TESS_CONTROL_SHADER` or `GL4.GL_TESS_EVALUATION_SHADER`.
        `count` - number of shaders
        `source` - CharSequence array containing the shader sources, organized as `source[count][strings-per-shader]`. May be either an immutable `String` - or mutable `StringBuilder` array.
      Throws:
        `IllegalArgumentException` - if `count and `source.length` do not match`

    - #### ShaderCode

          public ShaderCode(int type,
                    int count,
                    int binFormat,
                    Buffer binary)

      Parameters:
        `type` - either `GL2ES2.GL_VERTEX_SHADER`, `GL2ES2.GL_FRAGMENT_SHADER`, `GL3.GL_GEOMETRY_SHADER`, `GL4.GL_TESS_CONTROL_SHADER` or `GL4.GL_TESS_EVALUATION_SHADER`.
        `count` - number of shaders
        `binary` - binary buffer containing the shader binaries,

  - ### Method Detail

    - #### create

          public static ShaderCode create(GL2ES2 gl,
                          int type,
                          int count,
                          Class<?> context,
                          String[] sourceFiles,
                          boolean mutableStringBuilder)

      Creates a complete `ShaderCode` object while reading all shader source of `sourceFiles`, which location is resolved using the `context` class, see `#readShaderSource(Class, String)`.
      Parameters:
        `gl` - current GL object to determine whether a shader compiler is available. If null, no validation is performed.
        `type` - either `GL2ES2.GL_VERTEX_SHADER`, `GL2ES2.GL_FRAGMENT_SHADER`, `GL3.GL_GEOMETRY_SHADER`, `GL4.GL_TESS_CONTROL_SHADER` or `GL4.GL_TESS_EVALUATION_SHADER`.
        `count` - number of shaders
        `context` - class used to help resolving the source location
        `sourceFiles` - array of source locations, organized as `sourceFiles[count]`
        `mutableStringBuilder` - if `true` method returns a mutable `StringBuilder` instance which can be edited later on at the costs of a String conversion when passing to `GL2ES2.glShaderSource(int, int, String[], IntBuffer)`. If `false` method returns an immutable `String` instance, which can be passed to `GL2ES2.glShaderSource(int, int, String[], IntBuffer)` at no additional costs.
      Throws:
        `IllegalArgumentException` - if `count and `sourceFiles.length` do not match`
      See Also:
        `#readShaderSource(Class, String)`

    - #### create

          public static ShaderCode create(int type,
                          int count,
                          Class<?> context,
                          int binFormat,
                          String binaryFile)

      Creates a complete `ShaderCode` object while reading the shader binary of `binaryFile`, which location is resolved using the `context` class, see `readShaderBinary(Class, String)`.
      Parameters:
        `type` - either `GL2ES2.GL_VERTEX_SHADER`, `GL2ES2.GL_FRAGMENT_SHADER`, `GL3.GL_GEOMETRY_SHADER`, `GL4.GL_TESS_CONTROL_SHADER` or `GL4.GL_TESS_EVALUATION_SHADER`.
        `count` - number of shaders
        `context` - class used to help resolving the source location
        `binFormat` - a valid native binary format as they can be queried by `ShaderUtil.getShaderBinaryFormats(GL)`.
        `sourceFiles` - array of source locations, organized as `sourceFiles[count]`
      See Also:
        `readShaderBinary(Class, String)`, `ShaderUtil.getShaderBinaryFormats(GL)`

    - #### getFileSuffix

          public static String getFileSuffix(boolean binary,
                             int type)

      Returns a unique suffix for shader resources as follows:
      - Source
        - `vertex`: `SUFFIX_VERTEX_SOURCE`
        - `fragment`: `SUFFIX_FRAGMENT_SOURCE`
        - `geometry`: `SUFFIX_GEOMETRY_SOURCE`
        - `tess-ctrl`: `SUFFIX_TESS_CONTROL_SOURCE`
        - `tess-eval`: `SUFFIX_TESS_EVALUATION_SOURCE`
      - Binary
        - `vertex`: `SUFFIX_VERTEX_BINARY`
        - `fragment`: `SUFFIX_FRAGMENT_BINARY`
        - `geometry`: `SUFFIX_GEOMETRY_BINARY`
        - `tess-ctrl`: `SUFFIX_TESS_CONTROL_BINARY`
        - `tess-eval`: `SUFFIX_TESS_EVALUATION_BINARY`
      Parameters:
        `binary` - true for a binary resource, false for a source resource
        `type` - either `GL2ES2.GL_VERTEX_SHADER`, `GL2ES2.GL_FRAGMENT_SHADER`, `GL3.GL_GEOMETRY_SHADER`, `GL4.GL_TESS_CONTROL_SHADER` or `GL4.GL_TESS_EVALUATION_SHADER`.
      Throws:
        `GLException` - if `type` is not supported
      See Also:
        `create(GL2ES2, int, Class, String, String, String, boolean)`

    - #### getBinarySubPath

          public static String getBinarySubPath(int binFormat)

      Returns a unique relative path for binary shader resources as follows:
      - `NVIDIA`: `SUB_PATH_NVIDIA`
      Throws:
        `GLException` - if `binFormat` is not supported
      See Also:
        `create(GL2ES2, int, Class, String, String, String, boolean)`

    - #### create

          public static ShaderCode create(GL2ES2 gl,
                          int type,
                          int count,
                          Class<?> context,
                          String srcRoot,
                          String[] srcBasenames,
                          String binRoot,
                          String binBasename,
                          boolean mutableStringBuilder)

      Convenient creation method for instantiating a complete `ShaderCode` object either from source code using `#create(GL2ES2, int, int, Class, String[])`, or from a binary code using `create(int, int, Class, int, String)`, whatever is available first.

      The source and binary location names are expected w/o suffixes which are resolved and appended using `getFileSuffix(boolean, int)`.

      Additionally, the binary resource is expected within a subfolder of `binRoot` which reflects the vendor specific binary format, see `getBinarySubPath(int)`. All `ShaderUtil.getShaderBinaryFormats(GL)` are being iterated using the binary subfolder, the first existing resource is being used.

      Example:

             Your std JVM layout (plain or within a JAR):

                org/test/glsl/MyShaderTest.class
                org/test/glsl/shader/vertex.vp
                org/test/glsl/shader/fragment.fp
                org/test/glsl/shader/bin/nvidia/vertex.bvp
                org/test/glsl/shader/bin/nvidia/fragment.bfp

             Your Android APK layout:

                classes.dex
                assets/org/test/glsl/shader/vertex.vp
                assets/org/test/glsl/shader/fragment.fp
                assets/org/test/glsl/shader/bin/nvidia/vertex.bvp
                assets/org/test/glsl/shader/bin/nvidia/fragment.bfp
                ...

             Your invocation in org/test/glsl/MyShaderTest.java:

                ShaderCode vp0 = ShaderCode.create(gl, GL2ES2.GL_VERTEX_SHADER, 1, this.getClass(),
                                                   "shader", new String[] { "vertex" }, "shader/bin", "vertex");
                ShaderCode fp0 = ShaderCode.create(gl, GL2ES2.GL_FRAGMENT_SHADER, 1, this.getClass(),
                                                   "shader", new String[] { "vertex" }, "shader/bin", "fragment");
                ShaderProgram sp0 = new ShaderProgram();
                sp0.add(gl, vp0, System.err);
                sp0.add(gl, fp0, System.err);
                st.attachShaderProgram(gl, sp0, true);

      A simplified entry point is `create(GL2ES2, int, Class, String, String, String, boolean)`.

      The location is finally being resolved using the `context` class, see `readShaderBinary(Class, String)`.

      Parameters:
        `gl` - current GL object to determine whether a shader compiler is available (if `source` is used), or to determine the shader binary format (if `binary` is used).
        `type` - either `GL2ES2.GL_VERTEX_SHADER`, `GL2ES2.GL_FRAGMENT_SHADER`, `GL3.GL_GEOMETRY_SHADER`, `GL4.GL_TESS_CONTROL_SHADER` or `GL4.GL_TESS_EVALUATION_SHADER`.
        `count` - number of shaders
        `context` - class used to help resolving the source and binary location
        `srcRoot` - relative root path for `srcBasenames` optional
        `srcBasenames` - basenames w/o path or suffix relative to `srcRoot` for the shader's source code
        `binRoot` - relative root path for `binBasenames`
        `binBasename` - basename w/o path or suffix relative to `binRoot` for the shader's binary code
        `mutableStringBuilder` - if `true` method returns a mutable `StringBuilder` instance which can be edited later on at the costs of a String conversion when passing to `GL2ES2.glShaderSource(int, int, String[], IntBuffer)`. If `false` method returns an immutable `String` instance, which can be passed to `GL2ES2.glShaderSource(int, int, String[], IntBuffer)` at no additional costs.
      Throws:
        `IllegalArgumentException` - if `count and `srcBasenames.length` do not match`
      See Also:
        `#create(GL2ES2, int, int, Class, String[])`, `create(int, int, Class, int, String)`, `#readShaderSource(Class, String)`, `getFileSuffix(boolean, int)`, `ShaderUtil.getShaderBinaryFormats(GL)`, `getBinarySubPath(int)`

    - #### create

          public static ShaderCode create(GL2ES2 gl,
                          int type,
                          Class<?> context,
                          String srcRoot,
                          String binRoot,
                          String basename,
                          boolean mutableStringBuilder)

      Simplified variation of `#create(GL2ES2, int, int, Class, String, String[], String, String)`.
      Example:

             Your std JVM layout (plain or within a JAR):

                org/test/glsl/MyShaderTest.class
                org/test/glsl/shader/vertex.vp
                org/test/glsl/shader/fragment.fp
                org/test/glsl/shader/bin/nvidia/vertex.bvp
                org/test/glsl/shader/bin/nvidia/fragment.bfp

             Your Android APK layout:

                classes.dex
                assets/org/test/glsl/shader/vertex.vp
                assets/org/test/glsl/shader/fragment.fp
                assets/org/test/glsl/shader/bin/nvidia/vertex.bvp
                assets/org/test/glsl/shader/bin/nvidia/fragment.bfp
                ...

             Your invocation in org/test/glsl/MyShaderTest.java:

                ShaderCode vp0 = ShaderCode.create(gl, GL2ES2.GL_VERTEX_SHADER, this.getClass(),
                                                   "shader", "shader/bin", "vertex");
                ShaderCode fp0 = ShaderCode.create(gl, GL2ES2.GL_FRAGMENT_SHADER, this.getClass(),
                                                   "shader", "shader/bin", "fragment");
                ShaderProgram sp0 = new ShaderProgram();
                sp0.add(gl, vp0, System.err);
                sp0.add(gl, fp0, System.err);
                st.attachShaderProgram(gl, sp0, true);

      Parameters:
        `gl` - current GL object to determine whether a shader compiler is available (if `source` is used), or to determine the shader binary format (if `binary` is used).
        `type` - either `GL2ES2.GL_VERTEX_SHADER`, `GL2ES2.GL_FRAGMENT_SHADER`, `GL3.GL_GEOMETRY_SHADER`, `GL4.GL_TESS_CONTROL_SHADER` or `GL4.GL_TESS_EVALUATION_SHADER`.
        `context` - class used to help resolving the source and binary location
        `srcRoot` - relative root path for `basename` optional
        `binRoot` - relative root path for `basename`
        `mutableStringBuilder` - TODO
        `basenames` - basename w/o path or suffix relative to `srcRoot` and `binRoot` for the shader's source and binary code.
        `mutableStringBuilder` - if `true` method returns a mutable `StringBuilder` instance which can be edited later on at the costs of a String conversion when passing to `GL2ES2.glShaderSource(int, int, String[], IntBuffer)`. If `false` method returns an immutable `String` instance, which can be passed to `GL2ES2.glShaderSource(int, int, String[], IntBuffer)` at no additional costs.
      Throws:
        `IllegalArgumentException` - if `count is not 1`
      See Also:
        `#create(GL2ES2, int, int, Class, String, String[], String, String)`

    - #### id

          public int id()

      returns the uniq shader id as an integer

    - #### shaderType

          public int shaderType()

    - #### shaderTypeStr

          public String shaderTypeStr()

    - #### shaderTypeStr

          public static String shaderTypeStr(int type)

    - #### shaderBinaryFormat

          public int shaderBinaryFormat()

    - #### shaderBinary

          public Buffer shaderBinary()

    - #### shaderSource

          public CharSequence[][] shaderSource()

    - #### isValid

          public boolean isValid()

    - #### shader

          public IntBuffer shader()

    - #### compile

          public boolean compile(GL2ES2 gl)

    - #### compile

          public boolean compile(GL2ES2 gl,
                        PrintStream verboseOut)

    - #### destroy

          public void destroy(GL2ES2 gl)

    - #### equals

          public boolean equals(Object obj)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### dumpShaderSource

          public void dumpShaderSource(PrintStream out)

    - #### insertShaderSource

          public int insertShaderSource(int shaderIdx,
                               String tag,
                               int fromIndex,
                               CharSequence data)

      Adds `data` after the line containing `tag`.

      Note: The shader source to be edit must be created using a mutable StringBuilder.

      Parameters:
        `shaderIdx` - the shader index to be used.
        `tag` - search string
        `fromIndex` - start search `tag` begininig with this index
        `data` - the text to be inserted. Shall end with an EOL '\n' character.
      Returns:
        index after the inserted `data`
      Throws:
        `IllegalStateException` - if the shader source's CharSequence is immutable, i.e. not of type `StringBuilder`

    - #### replaceInShaderSource

          public int replaceInShaderSource(String oldName,
                                  String newName)

      Replaces `oldName` with `newName` in all shader sources.

      In case `oldName` and `newName` are equal, no action is performed.

      Note: The shader source to be edit must be created using a mutable StringBuilder.

      Parameters:
        `oldName` - the to be replace string
        `newName` - the replacement string
      Returns:
        the number of replacements
      Throws:
        `IllegalStateException` - if the shader source's CharSequence is immutable, i.e. not of type `StringBuilder`

    - #### insertShaderSource

          public int insertShaderSource(int shaderIdx,
                               int position,
                               CharSequence data)

      Adds `data` at `position` in shader source for shader `shaderIdx`.

      Note: The shader source to be edit must be created using a mutable StringBuilder.

      Parameters:
        `shaderIdx` - the shader index to be used.
        `position` - in shader source segments of shader `shaderIdx`, -1 will append data
        `data` - the text to be inserted. Shall end with an EOL '\n' character
      Returns:
        index after the inserted `data`
      Throws:
        `IllegalStateException` - if the shader source's CharSequence is immutable, i.e. not of type `StringBuilder`

    - #### insertShaderSource

          public int insertShaderSource(int shaderIdx,
                               int position,
                               Class<?> context,
                               String path)
                                 throws IOException

      Adds shader source located in `path`, either relative to the `context` class or absolute as-is at `position` in shader source for shader `shaderIdx`.

      Final location lookup is performed via `ClassLoader.getResource(String)` and `ClassLoader.getSystemResource(String)`, see `IOUtil.getResource(Class, String)`.

      Note: The shader source to be edit must be created using a mutable StringBuilder.

      Parameters:
        `shaderIdx` - the shader index to be used.
        `position` - in shader source segments of shader `shaderIdx`, -1 will append data
        `context` - class used to help resolve the source location
        `path` - location of shader source
      Returns:
        index after the inserted code.
      Throws:
        `IOException`
        `IllegalStateException` - if the shader source's CharSequence is immutable, i.e. not of type `StringBuilder`
      See Also:
        `IOUtil.getResource(Class, String)`

    - #### readShaderSource

          public static void readShaderSource(Class<?> context,
                              URLConnection conn,
                              StringBuilder result)
                                       throws IOException

      Parameters:
        `context` -
        `conn` -
        `result` -
      Throws:
        `IOException`

    - #### readShaderSource

          public static CharSequence readShaderSource(Class<?> context,
                                      String path,
                                      boolean mutableStringBuilder)
                                               throws IOException

      Reads shader source located in `path`, either relative to the `context` class or absolute as-is.

      Final location lookup is performed via `ClassLoader.getResource(String)` and `ClassLoader.getSystemResource(String)`, see `IOUtil.getResource(Class, String)`.

      Parameters:
        `context` - class used to help resolve the source location
        `path` - location of shader source
        `mutableStringBuilder` - if `true` method returns a mutable `StringBuilder` instance which can be edited later on at the costs of a String conversion when passing to `GL2ES2.glShaderSource(int, int, String[], IntBuffer)`. If `false` method returns an immutable `String` instance, which can be passed to `GL2ES2.glShaderSource(int, int, String[], IntBuffer)` at no additional costs.
      Throws:
        `IOException`
      See Also:
        `IOUtil.getResource(Class, String)`

    - #### readShaderBinary

          public static ByteBuffer readShaderBinary(Class<?> context,
                                    String path)
                                             throws IOException

      Reads shader binary located in `path`, either relative to the `context` class or absolute as-is.

      Final location lookup is perfomed via `ClassLoader.getResource(String)` and `ClassLoader.getSystemResource(String)`, see `IOUtil.getResource(Class, String)`.

      Parameters:
        `context` - class used to help resolve the source location
        `path` - location of shader binary
      Throws:
        `IOException`
      See Also:
        `IOUtil.getResource(Class, String)`

    - #### createExtensionDirective

          public static String createExtensionDirective(String extensionName,
                                        String behavior)

      Creates a GLSL extension directive.

      Prefer `ENABLE` over `REQUIRE`, since the latter will force a failure if not supported.

      Parameters:
        `extensionName` -
        `behavior` - shall be either `REQUIRE`, `ENABLE`, `DISABLE` or `WARN`
      Returns:
        the complete extension directive

    - #### addGLSLVersion

          public final int addGLSLVersion(GL2ES2 gl)

      Add GLSL version at the head of this shader source code.

      Note: The shader source to be edit must be created using a mutable StringBuilder.

      Parameters:
        `gl` - a GL context, which must have been made current once
      Returns:
        the index after the inserted data, maybe 0 if nothing has be inserted.

    - #### addDefaultShaderPrecision

          public final int addDefaultShaderPrecision(GL2ES2 gl,
                                      int pos)

      Adds default precision to source code at given position if required, i.e. `es2_default_precision_vp`, `es2_default_precision_fp`, `gl3_default_precision_vp_gp`, `gl3_default_precision_fp` or none, depending on the `GLSL version` being used.

      Note: The shader source to be edit must be created using a mutable StringBuilder.

      Parameters:
        `gl` - a GL context, which must have been made current once
        `pos` - position within this mutable shader source.
      Returns:
        the index after the inserted data, maybe 0 if nothing has be inserted.

    - #### requiresDefaultPrecision

          public static final boolean requiresDefaultPrecision(GL2ES2 gl)

      Returns true, if GLSL version requires default precision, i.e. ES2 or GLSL [1.30 .. 1.50[.

    - #### requiresGL3DefaultPrecision

          public static final boolean requiresGL3DefaultPrecision(GL2ES2 gl)

      Returns true, if GL3 GLSL version requires default precision, i.e. GLSL [1.30 .. 1.50[.

    - #### defaultShaderCustomization

          public final int defaultShaderCustomization(GL2ES2 gl,
                                       boolean preludeVersion,
                                       boolean addDefaultPrecision)

      Default customization of this shader source code.

      Note: The shader source to be edit must be created using a mutable StringBuilder.

      Parameters:
        `gl` - a GL context, which must have been made current once
        `preludeVersion` - if true `GLContext.getGLSLVersionString()` is preluded, otherwise not.
        `addDefaultPrecision` - if `true` default precision source code line(s) are added, i.e. `es2_default_precision_vp`, `es2_default_precision_fp`, `gl3_default_precision_vp_gp`, `gl3_default_precision_fp` or none, depending on the `GLSL version` being used.
      Returns:
        the index after the inserted data, maybe 0 if nothing has be inserted.
      See Also:
        `addGLSLVersion(GL2ES2)`, `addDefaultShaderPrecision(GL2ES2, int)`

    - #### defaultShaderCustomization

          public final int defaultShaderCustomization(GL2ES2 gl,
                                       boolean preludeVersion,
                                       String esDefaultPrecision)

      Default customization of this shader source code.

      Note: The shader source to be edit must be created using a mutable StringBuilder.

      Parameters:
        `gl` - a GL context, which must have been made current once
        `preludeVersion` - if true `GLContext.getGLSLVersionString()` is preluded, otherwise not.
        `esDefaultPrecision` - optional default precision source code line(s) preluded if not null and if `GLBase.isGLES()`. You may use `es2_default_precision_fp` for fragment shader and `es2_default_precision_vp` for vertex shader.
      Returns:
        the index after the inserted data, maybe 0 if nothing has be inserted.
      See Also:
        `addGLSLVersion(GL2ES2)`, `addDefaultShaderPrecision(GL2ES2, int)`

Copyright 2010 JogAmp Community.