com.jogamp.opengl.util.glsl
Class ShaderCode

java.lang.Object
  extended by 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.


Field Summary
static boolean DEBUG
           
static boolean DEBUG_CODE
           
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_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
 
Constructor Summary
ShaderCode(int type, int count, CharSequence[][] source)
           
ShaderCode(int type, int count, int binFormat, Buffer binary)
           
 
Method Summary
 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).
 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 Binary vertex: SUFFIX_VERTEX_BINARY fragment: SUFFIX_FRAGMENT_BINARY
 int hashCode()
           
 int id()
          returns the uniq shader id as an integer
 int insertShaderSource(int shaderIdx, int position, CharSequence data)
          Adds data at offset 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.
 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

public static final boolean DEBUG

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_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
Constructor Detail

ShaderCode

public ShaderCode(int type,
                  int count,
                  CharSequence[][] source)
Parameters:
type - either GL2ES2.GL_VERTEX_SHADER or GL2ES2.GL_FRAGMENT_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 or GL2ES2.GL_FRAGMENT_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 or GL2ES2.GL_FRAGMENT_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 or GL2ES2.GL_FRAGMENT_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:

Parameters:
binary - true for a binary resource, false for a source resource
type - either GL2ES2.GL_VERTEX_SHADER or GL2ES2.GL_FRAGMENT_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:

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 or GL2ES2.GL_FRAGMENT_SHADER
count - number of shaders
context - class used to help resolving the source and binary location
srcRoot - relative root path for srcBasenames
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 or GL2ES2.GL_FRAGMENT_SHADER
context - class used to help resolving the source and binary location
srcRoot - relative root path for basename
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 offset 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
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

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)


Copyright 2010 JogAmp Community.