libgdx API

com.badlogic.gdx.graphics.glutils
Class ShaderProgram

java.lang.Object
  extended by com.badlogic.gdx.graphics.glutils.ShaderProgram
All Implemented Interfaces:
Disposable

public class ShaderProgram
extends java.lang.Object
implements Disposable

A shader program encapsulates a vertex and fragment shader pair linked to form a shader program useable with OpenGL ES 2.0.

After construction a ShaderProgram can be used to draw Mesh. To make the GPU use a specific ShaderProgram the programs begin() method must be used which effectively binds the program.

When a ShaderProgram is bound one can set uniforms, vertex attributes and attributes as needed via the respective methods.

A ShaderProgram can be unbound with a call to end()

A ShaderProgram must be disposed via a call to dispose() when it is no longer needed

ShaderPrograms are managed. In case the OpenGL context is lost all shaders get invalidated and have to be reloaded. This happens on Android when a user switches to another application or receives an incoming call. Managed ShaderPrograms are automatically reloaded when the OpenGL context is recreated so you don't have to do this manually.

Author:
mzechner

Field Summary
static java.lang.String BINORMAL_ATTRIBUTE
          default name for binormal attribute
static java.lang.String COLOR_ATTRIBUTE
          default name for color attributes
static java.lang.String NORMAL_ATTRIBUTE
          default name for normal attribtues
static boolean pedantic
          flag indicating whether attributes & uniforms must be present at all times
static java.lang.String POSITION_ATTRIBUTE
          default name for position attributes
static java.lang.String TANGENT_ATTRIBUTE
          default name for tangent attribute
static java.lang.String TEXCOORD_ATTRIBUTE
          default name for texcoords attributes, append texture unit number
 
Constructor Summary
ShaderProgram(java.lang.String vertexShader, java.lang.String fragmentShader)
          Construcs a new JOglShaderProgram and immediatly compiles it.
 
Method Summary
 void begin()
          Makes OpenGL ES 2.0 use this vertex and fragment shader pair.
static void clearAllShaderPrograms(Application app)
           
 void disableVertexAttribute(java.lang.String name)
          Disables the vertex attribute with the given name
 void dispose()
          Disposes all resources associated with this shader.
 void enableVertexAttribute(java.lang.String name)
          Enables the vertex attribute with the given name
 void end()
          Disables this shader.
 int getAttributeLocation(java.lang.String name)
           
 java.lang.String[] getAttributes()
           
 int getAttributeType(java.lang.String name)
           
 java.lang.String getLog()
           
static java.lang.String getManagedStatus()
           
 int getUniformLocation(java.lang.String name)
           
 java.lang.String[] getUniforms()
           
 int getUniformType(java.lang.String name)
           
 boolean hasAttribute(java.lang.String name)
           
 boolean hasUniform(java.lang.String name)
           
static void invalidateAllShaderPrograms(Application app)
          Invalidates all shaders so the next time they are used new handles are generated
 boolean isCompiled()
           
 void setAttributef(java.lang.String name, float value1, float value2, float value3, float value4)
          Sets the given attribute
 void setUniform1fv(java.lang.String name, float[] values, int offset, int length)
           
 void setUniform2fv(java.lang.String name, float[] values, int offset, int length)
           
 void setUniform3fv(java.lang.String name, float[] values, int offset, int length)
           
 void setUniform4fv(java.lang.String name, float[] values, int offset, int length)
           
 void setUniformf(java.lang.String name, float value)
          Sets the uniform with the given name.
 void setUniformf(java.lang.String name, float value1, float value2)
          Sets the uniform with the given name.
 void setUniformf(java.lang.String name, float value1, float value2, float value3)
          Sets the uniform with the given name.
 void setUniformf(java.lang.String name, float value1, float value2, float value3, float value4)
          Sets the uniform with the given name.
 void setUniformi(java.lang.String name, int value)
          Sets the uniform with the given name.
 void setUniformi(java.lang.String name, int value1, int value2)
          Sets the uniform with the given name.
 void setUniformi(java.lang.String name, int value1, int value2, int value3)
          Sets the uniform with the given name.
 void setUniformi(java.lang.String name, int value1, int value2, int value3, int value4)
          Sets the uniform with the given name.
 void setUniformMatrix(java.lang.String name, Matrix3 matrix)
          Sets the uniform matrix with the given name.
 void setUniformMatrix(java.lang.String name, Matrix3 matrix, boolean transpose)
          Sets the uniform matrix with the given name.
 void setUniformMatrix(java.lang.String name, Matrix4 matrix)
          Sets the uniform matrix with the given name.
 void setUniformMatrix(java.lang.String name, Matrix4 matrix, boolean transpose)
          Sets the uniform matrix with the given name.
 void setVertexAttribute(java.lang.String name, int size, int type, boolean normalize, int stride, java.nio.FloatBuffer buffer)
          Sets the vertex attribute with the given name.
 void setVertexAttribute(java.lang.String name, int size, int type, boolean normalize, int stride, int offset)
          Sets the vertex attribute with the given name.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

POSITION_ATTRIBUTE

public static final java.lang.String POSITION_ATTRIBUTE
default name for position attributes

See Also:
Constant Field Values

NORMAL_ATTRIBUTE

public static final java.lang.String NORMAL_ATTRIBUTE
default name for normal attribtues

See Also:
Constant Field Values

COLOR_ATTRIBUTE

public static final java.lang.String COLOR_ATTRIBUTE
default name for color attributes

See Also:
Constant Field Values

TEXCOORD_ATTRIBUTE

public static final java.lang.String TEXCOORD_ATTRIBUTE
default name for texcoords attributes, append texture unit number

See Also:
Constant Field Values

TANGENT_ATTRIBUTE

public static final java.lang.String TANGENT_ATTRIBUTE
default name for tangent attribute

See Also:
Constant Field Values

BINORMAL_ATTRIBUTE

public static final java.lang.String BINORMAL_ATTRIBUTE
default name for binormal attribute

See Also:
Constant Field Values

pedantic

public static boolean pedantic
flag indicating whether attributes & uniforms must be present at all times

Constructor Detail

ShaderProgram

public ShaderProgram(java.lang.String vertexShader,
                     java.lang.String fragmentShader)
Construcs a new JOglShaderProgram and immediatly compiles it.

Parameters:
vertexShader - the vertex shader
fragmentShader - the fragment shader
Method Detail

getLog

public java.lang.String getLog()
Returns:
the log info for the shader compilation and program linking stage. The shader needs to be bound for this method to have an effect.

isCompiled

public boolean isCompiled()
Returns:
whether this ShaderProgram compiled successfully.

setUniformi

public void setUniformi(java.lang.String name,
                        int value)
Sets the uniform with the given name. Throws an IllegalArgumentException in case it is not called in between a begin()/end() block.

Parameters:
name - the name of the uniform
value - the value

setUniformi

public void setUniformi(java.lang.String name,
                        int value1,
                        int value2)
Sets the uniform with the given name. Throws an IllegalArgumentException in case it is not called in between a begin()/end() block.

Parameters:
name - the name of the uniform
value1 - the first value
value2 - the second value

setUniformi

public void setUniformi(java.lang.String name,
                        int value1,
                        int value2,
                        int value3)
Sets the uniform with the given name. Throws an IllegalArgumentException in case it is not called in between a begin()/end() block.

Parameters:
name - the name of the uniform
value1 - the first value
value2 - the second value
value3 - the third value

setUniformi

public void setUniformi(java.lang.String name,
                        int value1,
                        int value2,
                        int value3,
                        int value4)
Sets the uniform with the given name. Throws an IllegalArgumentException in case it is not called in between a begin()/end() block.

Parameters:
name - the name of the uniform
value1 - the first value
value2 - the second value
value3 - the third value
value4 - the fourth value

setUniformf

public void setUniformf(java.lang.String name,
                        float value)
Sets the uniform with the given name. Throws an IllegalArgumentException in case it is not called in between a begin()/end() block.

Parameters:
name - the name of the uniform
value - the value

setUniformf

public void setUniformf(java.lang.String name,
                        float value1,
                        float value2)
Sets the uniform with the given name. Throws an IllegalArgumentException in case it is not called in between a begin()/end() block.

Parameters:
name - the name of the uniform
value1 - the first value
value2 - the second value

setUniformf

public void setUniformf(java.lang.String name,
                        float value1,
                        float value2,
                        float value3)
Sets the uniform with the given name. Throws an IllegalArgumentException in case it is not called in between a begin()/end() block.

Parameters:
name - the name of the uniform
value1 - the first value
value2 - the second value
value3 - the third value

setUniformf

public void setUniformf(java.lang.String name,
                        float value1,
                        float value2,
                        float value3,
                        float value4)
Sets the uniform with the given name. Throws an IllegalArgumentException in case it is not called in between a begin()/end() block.

Parameters:
name - the name of the uniform
value1 - the first value
value2 - the second value
value3 - the third value
value4 - the fourth value

setUniform1fv

public void setUniform1fv(java.lang.String name,
                          float[] values,
                          int offset,
                          int length)

setUniform2fv

public void setUniform2fv(java.lang.String name,
                          float[] values,
                          int offset,
                          int length)

setUniform3fv

public void setUniform3fv(java.lang.String name,
                          float[] values,
                          int offset,
                          int length)

setUniform4fv

public void setUniform4fv(java.lang.String name,
                          float[] values,
                          int offset,
                          int length)

setUniformMatrix

public void setUniformMatrix(java.lang.String name,
                             Matrix4 matrix)
Sets the uniform matrix with the given name. Throws an IllegalArgumentException in case it is not called in between a begin()/end() block.

Parameters:
name - the name of the uniform
matrix - the matrix

setUniformMatrix

public void setUniformMatrix(java.lang.String name,
                             Matrix4 matrix,
                             boolean transpose)
Sets the uniform matrix with the given name. Throws an IllegalArgumentException in case it is not called in between a begin()/end() block.

Parameters:
name - the name of the uniform
matrix - the matrix
transpose - whether the matrix shouls be transposed

setUniformMatrix

public void setUniformMatrix(java.lang.String name,
                             Matrix3 matrix)
Sets the uniform matrix with the given name. Throws an IllegalArgumentException in case it is not called in between a begin()/end() block.

Parameters:
name - the name of the uniform
matrix - the matrix

setUniformMatrix

public void setUniformMatrix(java.lang.String name,
                             Matrix3 matrix,
                             boolean transpose)
Sets the uniform matrix with the given name. Throws an IllegalArgumentException in case it is not called in between a begin()/end() block.

Parameters:
name - the name of the uniform
matrix - the matrix
transpose - whether the uniform matrix should be transposed

setVertexAttribute

public void setVertexAttribute(java.lang.String name,
                               int size,
                               int type,
                               boolean normalize,
                               int stride,
                               java.nio.FloatBuffer buffer)
Sets the vertex attribute with the given name. Throws an IllegalArgumentException in case it is not called in between a begin()/end() block.

Parameters:
name - the attribute name
size - the number of components, must be >= 1 and <= 4
type - the type, must be one of GL20.GL_BYTE, GL20.GL_UNSIGNED_BYTE, GL20.GL_SHORT, GL20.GL_UNSIGNED_SHORT,GL20.GL_FIXED, or GL20.GL_FLOAT. GL_FIXED will not work on the desktop
normalize - whether fixed point data should be normalized. Will not work on the desktop
stride - the stride in bytes between successive attributes
buffer - the buffer containing the vertex attributes.

setVertexAttribute

public void setVertexAttribute(java.lang.String name,
                               int size,
                               int type,
                               boolean normalize,
                               int stride,
                               int offset)
Sets the vertex attribute with the given name. Throws an IllegalArgumentException in case it is not called in between a begin()/end() block.

Parameters:
name - the attribute name
size - the number of components, must be >= 1 and <= 4
type - the type, must be one of GL20.GL_BYTE, GL20.GL_UNSIGNED_BYTE, GL20.GL_SHORT, GL20.GL_UNSIGNED_SHORT,GL20.GL_FIXED, or GL20.GL_FLOAT. GL_FIXED will not work on the desktop
normalize - whether fixed point data should be normalized. Will not work on the desktop
stride - the stride in bytes between successive attributes
offset - byte offset into the vertex buffer object bound to GL20.GL_ARRAY_BUFFER.

begin

public void begin()
Makes OpenGL ES 2.0 use this vertex and fragment shader pair. When you are done with this shader you have to call end().


end

public void end()
Disables this shader. Must be called when one is done with the shader. Don't mix it with dispose, that will release the shader resources.


dispose

public void dispose()
Disposes all resources associated with this shader. Must be called when the shader is no longer used.

Specified by:
dispose in interface Disposable

disableVertexAttribute

public void disableVertexAttribute(java.lang.String name)
Disables the vertex attribute with the given name

Parameters:
name - the vertex attribute name

enableVertexAttribute

public void enableVertexAttribute(java.lang.String name)
Enables the vertex attribute with the given name

Parameters:
name - the vertex attribute name

invalidateAllShaderPrograms

public static void invalidateAllShaderPrograms(Application app)
Invalidates all shaders so the next time they are used new handles are generated

Parameters:
app -

clearAllShaderPrograms

public static void clearAllShaderPrograms(Application app)

getManagedStatus

public static java.lang.String getManagedStatus()

setAttributef

public void setAttributef(java.lang.String name,
                          float value1,
                          float value2,
                          float value3,
                          float value4)
Sets the given attribute

Parameters:
name - the name of the attribute
value1 - the first value
value2 - the second value
value3 - the third value
value4 - the fourth value

hasAttribute

public boolean hasAttribute(java.lang.String name)
Parameters:
name - the name of the attribute
Returns:
whether the attribute is available in the shader

getAttributeType

public int getAttributeType(java.lang.String name)
Parameters:
name - the name of the attribute
Returns:
the type of the attribute, one of GL20.GL_FLOAT, GL20.GL_FLOAT_VEC2 etc.

getAttributeLocation

public int getAttributeLocation(java.lang.String name)
Parameters:
name - the name of the attribute
Returns:
the location of the attribute or -1.

hasUniform

public boolean hasUniform(java.lang.String name)
Parameters:
name - the name of the uniform
Returns:
whether the uniform is available in the shader

getUniformType

public int getUniformType(java.lang.String name)
Parameters:
name - the name of the uniform
Returns:
the type of the uniform, one of GL20.GL_FLOAT, GL20.GL_FLOAT_VEC2 etc.

getUniformLocation

public int getUniformLocation(java.lang.String name)
Parameters:
name - the name of the uniform
Returns:
the location of the uniform or -1.

getAttributes

public java.lang.String[] getAttributes()
Returns:
the attributes

getUniforms

public java.lang.String[] getUniforms()
Returns:
the uniforms

libgdx API

Copyright 2010 Mario Zechner (contact@badlogicgames.com), Nathan Sweet (admin@esotericsoftware.com)