com.jogamp.opengl.util.glsl

## Class ShaderState

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

-     public class ShaderState
      extends Object

  ShaderState allows to sharing data between shader programs, while updating the attribute and uniform locations when switching.

  This allows seamless switching of programs using almost same data but performing different artifacts.

  A `used` ShaderState is attached to the current GL context and can be retrieved via `#getShaderState(GL)`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `DEBUG`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ShaderState()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `attachObject(String name, Object obj)` Attach user object for the given name to this ShaderState.
    `boolean` | `attachShaderProgram(GL2ES2 gl, ShaderProgram prog, boolean enable)` Attach or switch a shader program
    `void` | `bindAttribLocation(GL2ES2 gl, int location, GLArrayData data)` Binds a shader `GLArrayData` attribute to a location.
    `void` | `bindAttribLocation(GL2ES2 gl, int location, String name)` Binds a shader attribute to a location.
    `void` | `destroy(GL2ES2 gl)` Calls `release(gl, true, true, true)`
    `Object` | `detachObject(String name)`
    `void` | `disableAllVertexAttributeArrays(GL2ES2 gl, boolean removeFromState)` Disables all vertex attribute arrays.
    `boolean` | `disableVertexAttribArray(GL2ES2 gl, GLArrayData data)` Disables a vertex attribute array This method uses the `GLArrayData`'s location if set and is the preferred alternative to `disableVertexAttribArray(GL2ES2, String)`.
    `boolean` | `disableVertexAttribArray(GL2ES2 gl, String name)` Disables a vertex attribute array This method retrieves the the location via `getAttribLocation(GL2ES2, GLArrayData)` hence `disableVertexAttribArray(GL2ES2, GLArrayData)` shall be preferred.
    `boolean` | `enableVertexAttribArray(GL2ES2 gl, GLArrayData data)` Enables a vertex attribute array, usually invoked by `GLArrayDataEditable.enableBuffer(GL, boolean)`.
    `boolean` | `enableVertexAttribArray(GL2ES2 gl, String name)` Enables a vertex attribute array.
    `Object` | `getAttachedObject(String name)` Returns the attached user object for the given name to this ShaderState.
    `int` | `getAttribLocation(GL2ES2 gl, GLArrayData data)` Validates and returns the location of a shader attribute. Uses either the cached value `getCachedAttribLocation(String)` if valid, or the GLSL queried via `GL2ES2.glGetAttribLocation(int, String)`. The location will be cached and set in the `GLArrayData` object.
    `int` | `getAttribLocation(GL2ES2 gl, String name)` Gets the location of a shader attribute with given `name`. Uses either the cached value `getCachedAttribLocation(String)` if valid, or the GLSL queried via `GL2ES2.glGetAttribLocation(int, String)`. The location will be cached.
    `GLArrayData` | `getAttribute(String name)` Get the previous cached vertex attribute data.
    `int` | `getCachedAttribLocation(String name)` Gets the cached location of a shader attribute.
    `int` | `getCachedUniformLocation(String name)` Gets the cached location of the shader uniform.
    `GLUniformData` | `getUniform(String name)` Get the uniform data, previously set.
    `int` | `getUniformLocation(GL2ES2 gl, GLUniformData data)` Validates and returns the location of a shader uniform. Uses either the cached value `getCachedUniformLocation(String)` if valid, or the GLSL queried via `GL2ES2.glGetUniformLocation(int, String)`. The location will be cached and set in the `GLUniformData` object.
    `int` | `getUniformLocation(GL2ES2 gl, String name)` Gets the location of a shader uniform with given `name`. Uses either the cached value `getCachedUniformLocation(String)` if valid, or the GLSL queried via `GL2ES2.glGetUniformLocation(int, String)`. The location will be cached.
    `boolean` | `inUse()`
    `boolean` | `isActiveAttribute(GLArrayData attribute)`
    `boolean` | `isVertexAttribArrayEnabled(GLArrayData data)`
    `boolean` | `isVertexAttribArrayEnabled(String name)`
    `boolean` | `linked()`
    `void` | `ownAttribute(GLArrayData attribute, boolean own)` Binds or unbinds the `GLArrayData` lifecycle to this ShaderState.
    `boolean` | `ownsAttribute(GLArrayData attribute)`
    `boolean` | `ownsUniform(GLUniformData uniform)`
    `void` | `ownUniform(GLUniformData uniform)` Bind the `GLUniform` lifecycle to this ShaderState.
    `void` | `release(GL2ES2 gl, boolean destroyBoundAttributes, boolean destroyShaderProgram, boolean destroyShaderCode)`
    `void` | `releaseAllAttributes(GL2ES2 gl)` Releases all mapped vertex attribute data, disables all enabled attributes and loses all indices
    `void` | `releaseAllData(GL2ES2 gl)` Calls `release(gl, false, false, false)`
    `void` | `releaseAllUniforms(GL2ES2 gl)` Releases all mapped uniform data and loses all indices
    `void` | `setVerbose(boolean v)`
    `ShaderProgram` | `shaderProgram()`
    `String` | `toString()`
    `StringBuilder` | `toString(StringBuilder sb, boolean alsoUnlocated)`
    `boolean` | `uniform(GL2ES2 gl, GLUniformData data)` Set the uniform data, if it's location is valid, i.e.
    `void` | `useProgram(GL2ES2 gl, boolean on)` Turns the shader program on or off.
    `boolean` | `verbose()`
    `boolean` | `vertexAttribPointer(GL2ES2 gl, GLArrayData data)` Set the `GLArrayData` vertex attribute data, if it's location is valid, i.e.

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

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DEBUG

          public static final boolean DEBUG

  - ### Constructor Detail

    - #### ShaderState

          public ShaderState()

  - ### Method Detail

    - #### verbose

          public boolean verbose()

    - #### setVerbose

          public void setVerbose(boolean v)

    - #### getAttachedObject

          public final Object getAttachedObject(String name)

      Returns the attached user object for the given name to this ShaderState.

    - #### attachObject

          public final Object attachObject(String name,
                            Object obj)

      Attach user object for the given name to this ShaderState. Returns the previously set object or null.
      Returns:
        the previous mapped object or null if none

    - #### detachObject

          public final Object detachObject(String name)

      Parameters:
        `name` - name of the mapped object to detach
      Returns:
        the previous mapped object or null if none

    - #### useProgram

          public void useProgram(GL2ES2 gl,
                        boolean on)
                          throws GLException

      Turns the shader program on or off.
      Throws:
        `GLException` - if no program is attached
      See Also:
        `useProgram(GL2ES2, boolean)`

    - #### linked

          public boolean linked()

    - #### inUse

          public boolean inUse()

    - #### attachShaderProgram

          public boolean attachShaderProgram(GL2ES2 gl,
                                    ShaderProgram prog,
                                    boolean enable)
                                      throws GLException

      Attach or switch a shader program

      Attaching a shader program the first time, as well as switching to another program on the fly, while managing all attribute and uniform data.

      [Re]sets all data and use program in case of a program switch.

      Use program, `useProgram(GL2ES2, boolean)`, if `enable` is `true`.

      Returns:
        true if shader program was attached, otherwise false (already attached)
      Throws:
        `GLException` - if program was not linked and linking fails

    - #### shaderProgram

          public ShaderProgram shaderProgram()

    - #### destroy

          public void destroy(GL2ES2 gl)

      Calls `release(gl, true, true, true)`
      See Also:
        `#glReleaseAllVertexAttributes`, `#glReleaseAllUniforms`, `release(GL2ES2, boolean, boolean, boolean)`

    - #### releaseAllData

          public void releaseAllData(GL2ES2 gl)

      Calls `release(gl, false, false, false)`
      See Also:
        `#glReleaseAllVertexAttributes`, `#glReleaseAllUniforms`, `release(GL2ES2, boolean, boolean, boolean)`

    - #### release

          public void release(GL2ES2 gl,
                     boolean destroyBoundAttributes,
                     boolean destroyShaderProgram,
                     boolean destroyShaderCode)

      See Also:
        `#glReleaseAllVertexAttributes`, `#glReleaseAllUniforms`, `ShaderProgram.release(GL2ES2, boolean)`

    - #### getCachedAttribLocation

          public int getCachedAttribLocation(String name)

      Gets the cached location of a shader attribute.
      Returns:
        -1 if there is no such attribute available, otherwise >= 0
      See Also:
        `bindAttribLocation(GL2ES2, int, String)`, `bindAttribLocation(GL2ES2, int, GLArrayData)`, `getAttribLocation(GL2ES2, String)`, `GL2ES2.glGetAttribLocation(int, String)`

    - #### getAttribute

          public GLArrayData getAttribute(String name)

      Get the previous cached vertex attribute data.
      Returns:
        the GLArrayData object, null if not previously set.
      See Also:
        `ownAttribute(GLArrayData, boolean)`, `#glEnableVertexAttribArray`, `#glDisableVertexAttribArray`, `#glVertexAttribPointer`, `#getVertexAttribPointer`, `#glReleaseAllVertexAttributes`, `#glResetAllVertexAttributes`, `ShaderProgram#glReplaceShader`

    - #### isActiveAttribute

          public boolean isActiveAttribute(GLArrayData attribute)

    - #### ownAttribute

          public void ownAttribute(GLArrayData attribute,
                          boolean own)

      Binds or unbinds the `GLArrayData` lifecycle to this ShaderState.

      If an attribute location is cached (ie `bindAttribLocation(GL2ES2, int, String)`) it is promoted to the `GLArrayData` instance.

      The attribute will be destroyed with `destroy(GL2ES2)` and it's location will be reset when switching shader with `#attachShaderProgram(GL2ES2, ShaderProgram)`.

      The data will not be transfered to the GPU, use `vertexAttribPointer(GL2ES2, GLArrayData)` additionally.

      The data will also be `associated` with this ShaderState.

      Parameters:
        `attribute` - the `GLArrayData` which lifecycle shall be managed
        `own` - true if owning shall be performs, false if disowning.
      See Also:
        `bindAttribLocation(GL2ES2, int, String)`, `getAttribute(String)`, `GLArrayData.associate(Object, boolean)`

    - #### ownsAttribute

          public boolean ownsAttribute(GLArrayData attribute)

    - #### bindAttribLocation

          public void bindAttribLocation(GL2ES2 gl,
                                int location,
                                String name)

      Binds a shader attribute to a location. Multiple names can be bound to one location. The value will be cached and can be retrieved via `getCachedAttribLocation(String)` before or after linking.
      Throws:
        `GLException` - if no program is attached
        `GLException` - if the program is already linked
      See Also:
        `GL2ES2.glBindAttribLocation(int, int, String)`, `getAttribLocation(GL2ES2, String)`, `getCachedAttribLocation(String)`

    - #### bindAttribLocation

          public void bindAttribLocation(GL2ES2 gl,
                                int location,
                                GLArrayData data)

      Binds a shader `GLArrayData` attribute to a location. Multiple names can be bound to one location. The value will be cached and can be retrieved via `getCachedAttribLocation(String)` and `getAttribute(String)`before or after linking. The `GLArrayData`'s location will be set as well.
      Throws:
        `GLException` - if no program is attached
        `GLException` - if the program is already linked
      See Also:
        `GL2ES2.glBindAttribLocation(int, int, String)`, `getAttribLocation(GL2ES2, String)`, `getCachedAttribLocation(String)`, `getAttribute(String)`

    - #### getAttribLocation

          public int getAttribLocation(GL2ES2 gl,
                              String name)

      Gets the location of a shader attribute with given `name`.
      Uses either the cached value `getCachedAttribLocation(String)` if valid, or the GLSL queried via `GL2ES2.glGetAttribLocation(int, String)`.
      The location will be cached.
      Returns:
        -1 if there is no such attribute available, otherwise >= 0
      Throws:
        `GLException` - if no program is attached
        `GLException` - if the program is not linked and no location was cached.
      See Also:
        `getCachedAttribLocation(String)`, `bindAttribLocation(GL2ES2, int, GLArrayData)`, `bindAttribLocation(GL2ES2, int, String)`, `GL2ES2.glGetAttribLocation(int, String)`

    - #### getAttribLocation

          public int getAttribLocation(GL2ES2 gl,
                              GLArrayData data)

      Validates and returns the location of a shader attribute.
      Uses either the cached value `getCachedAttribLocation(String)` if valid, or the GLSL queried via `GL2ES2.glGetAttribLocation(int, String)`.
      The location will be cached and set in the `GLArrayData` object.
      Returns:
        -1 if there is no such attribute available, otherwise >= 0
      Throws:
        `GLException` - if no program is attached
        `GLException` - if the program is not linked and no location was cached.
      See Also:
        `getCachedAttribLocation(String)`, `bindAttribLocation(GL2ES2, int, GLArrayData)`, `bindAttribLocation(GL2ES2, int, String)`, `GL2ES2.glGetAttribLocation(int, String)`, `getAttribute(String)`

    - #### isVertexAttribArrayEnabled

          public final boolean isVertexAttribArrayEnabled(String name)

      Returns:
        true if the named attribute is enable

    - #### isVertexAttribArrayEnabled

          public final boolean isVertexAttribArrayEnabled(GLArrayData data)

      Returns:
        true if the `GLArrayData` attribute is enable

    - #### enableVertexAttribArray

          public boolean enableVertexAttribArray(GL2ES2 gl,
                                        String name)

      Enables a vertex attribute array. This method retrieves the the location via `getAttribLocation(GL2ES2, GLArrayData)` hence `enableVertexAttribArray(GL2ES2, GLArrayData)` shall be preferred. Even if the attribute is not found in the current shader, it is marked enabled in this state.
      Returns:
        false, if the name is not found, otherwise true
      Throws:
        `GLException` - if the program is not linked and no location was cached.
      See Also:
        `#glEnableVertexAttribArray`, `#glDisableVertexAttribArray`, `#glVertexAttribPointer`, `#getVertexAttribPointer`

    - #### enableVertexAttribArray

          public boolean enableVertexAttribArray(GL2ES2 gl,
                                        GLArrayData data)

      Enables a vertex attribute array, usually invoked by `GLArrayDataEditable.enableBuffer(GL, boolean)`. This method uses the `GLArrayData`'s location if set and is the preferred alternative to `enableVertexAttribArray(GL2ES2, String)`. If data location is unset it will be retrieved via `getAttribLocation(GL2ES2, GLArrayData)` set and cached in this state. Even if the attribute is not found in the current shader, it is marked enabled in this state.
      Returns:
        false, if the name is not found, otherwise true
      Throws:
        `GLException` - if the program is not linked and no location was cached.
      See Also:
        `#glEnableVertexAttribArray`, `#glDisableVertexAttribArray`, `#glVertexAttribPointer`, `#getVertexAttribPointer`, `GLArrayDataEditable.enableBuffer(GL, boolean)`

    - #### disableVertexAttribArray

          public boolean disableVertexAttribArray(GL2ES2 gl,
                                         String name)

      Disables a vertex attribute array This method retrieves the the location via `getAttribLocation(GL2ES2, GLArrayData)` hence `disableVertexAttribArray(GL2ES2, GLArrayData)` shall be preferred. Even if the attribute is not found in the current shader, it is removed from this state enabled list.
      Returns:
        false, if the name is not found, otherwise true
      Throws:
        `GLException` - if no program is attached
        `GLException` - if the program is not linked and no location was cached.
      See Also:
        `#glEnableVertexAttribArray`, `#glDisableVertexAttribArray`, `#glVertexAttribPointer`, `#getVertexAttribPointer`

    - #### disableVertexAttribArray

          public boolean disableVertexAttribArray(GL2ES2 gl,
                                         GLArrayData data)

      Disables a vertex attribute array This method uses the `GLArrayData`'s location if set and is the preferred alternative to `disableVertexAttribArray(GL2ES2, String)`. If data location is unset it will be retrieved via `getAttribLocation(GL2ES2, GLArrayData)` set and cached in this state. Even if the attribute is not found in the current shader, it is removed from this state enabled list.
      Returns:
        false, if the name is not found, otherwise true
      Throws:
        `GLException` - if no program is attached
        `GLException` - if the program is not linked and no location was cached.
      See Also:
        `#glEnableVertexAttribArray`, `#glDisableVertexAttribArray`, `#glVertexAttribPointer`, `#getVertexAttribPointer`

    - #### vertexAttribPointer

          public boolean vertexAttribPointer(GL2ES2 gl,
                                    GLArrayData data)

      Set the `GLArrayData` vertex attribute data, if it's location is valid, i.e. ≥ 0.

      This method uses the `GLArrayData`'s location if valid, i.e. ≥ 0.
      If data's location is invalid, it will be retrieved via `getAttribLocation(GL2ES2, GLArrayData)`, set and cached in this state.

      Returns:
        false, if the location could not be determined, otherwise true
      Throws:
        `GLException` - if no program is attached
        `GLException` - if the program is not linked and no location was cached.
      See Also:
        `#glEnableVertexAttribArray`, `#glDisableVertexAttribArray`, `#glVertexAttribPointer`, `#getVertexAttribPointer`

    - #### releaseAllAttributes

          public void releaseAllAttributes(GL2ES2 gl)

      Releases all mapped vertex attribute data, disables all enabled attributes and loses all indices
      See Also:
        `#glEnableVertexAttribArray`, `#glDisableVertexAttribArray`, `#glVertexAttribPointer`, `#getVertexAttribPointer`, `#glReleaseAllVertexAttributes`, `#glResetAllVertexAttributes`, `#glResetAllVertexAttributes`, `ShaderProgram#glReplaceShader`

    - #### disableAllVertexAttributeArrays

          public void disableAllVertexAttributeArrays(GL2ES2 gl,
                                             boolean removeFromState)

      Disables all vertex attribute arrays. Their enabled stated will be removed from this state only if 'removeFromState' is true. This method purpose is more for debugging.
      See Also:
        `#glEnableVertexAttribArray`, `#glDisableVertexAttribArray`, `#glVertexAttribPointer`, `#getVertexAttribPointer`, `#glReleaseAllVertexAttributes`, `#glResetAllVertexAttributes`, `#glResetAllVertexAttributes`, `ShaderProgram#glReplaceShader`

    - #### getCachedUniformLocation

          public final int getCachedUniformLocation(String name)

      Gets the cached location of the shader uniform.
      Returns:
        -1 if there is no such uniform available, otherwise >= 0

    - #### ownUniform

          public void ownUniform(GLUniformData uniform)

      Bind the `GLUniform` lifecycle to this ShaderState.

      If a uniform location is cached it is promoted to the `GLUniformData` instance.

      The attribute will be destroyed with `destroy(GL2ES2)` and it's location will be reset when switching shader with `#attachShaderProgram(GL2ES2, ShaderProgram)`.

      The data will not be transfered to the GPU, use `uniform(GL2ES2, GLUniformData)` additionally.

      Parameters:
        `uniform` - the `GLUniformData` which lifecycle shall be managed
      See Also:
        `getUniform(String)`

    - #### ownsUniform

          public boolean ownsUniform(GLUniformData uniform)

    - #### getUniformLocation

          public final int getUniformLocation(GL2ES2 gl,
                               String name)

      Gets the location of a shader uniform with given `name`.
      Uses either the cached value `getCachedUniformLocation(String)` if valid, or the GLSL queried via `GL2ES2.glGetUniformLocation(int, String)`.
      The location will be cached.

      The current shader program (`#attachShaderProgram(GL2ES2, ShaderProgram)`) must be in use (`useProgram(GL2ES2, boolean)`) !

      Returns:
        -1 if there is no such attribute available, otherwise >= 0
      Throws:
        `GLException` - is the program is not linked
      See Also:
        `#glGetUniformLocation`, `GL2ES2.glGetUniformLocation(int, java.lang.String)`, `getUniformLocation(javax.media.opengl.GL2ES2, java.lang.String)`, `ShaderProgram#glReplaceShader`

    - #### getUniformLocation

          public int getUniformLocation(GL2ES2 gl,
                               GLUniformData data)

      Validates and returns the location of a shader uniform.
      Uses either the cached value `getCachedUniformLocation(String)` if valid, or the GLSL queried via `GL2ES2.glGetUniformLocation(int, String)`.
      The location will be cached and set in the `GLUniformData` object.

      The current shader program (`#attachShaderProgram(GL2ES2, ShaderProgram)`) must be in use (`useProgram(GL2ES2, boolean)`) !

      Returns:
        -1 if there is no such attribute available, otherwise >= 0
      Throws:
        `GLException` - is the program is not linked
      See Also:
        `#glGetUniformLocation`, `GL2ES2.glGetUniformLocation(int, java.lang.String)`, `getUniformLocation(javax.media.opengl.GL2ES2, java.lang.String)`, `ShaderProgram#glReplaceShader`

    - #### uniform

          public boolean uniform(GL2ES2 gl,
                        GLUniformData data)

      Set the uniform data, if it's location is valid, i.e. ≥ 0.

      This method uses the `GLUniformData`'s location if valid, i.e. ≥ 0.
      If data's location is invalid, it will be retrieved via `getUniformLocation(GL2ES2, GLUniformData)`, set and cached in this state.

      Returns:
        false, if the location could not be determined, otherwise true
      See Also:
        `#glGetUniformLocation`, `GL2ES2.glGetUniformLocation(int, java.lang.String)`, `GL2ES2.glUniform(javax.media.opengl.GLUniformData)`, `getUniformLocation(javax.media.opengl.GL2ES2, java.lang.String)`, `ShaderProgram#glReplaceShader`

    - #### getUniform

          public GLUniformData getUniform(String name)

      Get the uniform data, previously set.
      Returns:
        the GLUniformData object, null if not previously set.

    - #### releaseAllUniforms

          public void releaseAllUniforms(GL2ES2 gl)

      Releases all mapped uniform data and loses all indices

    - #### toString

          public StringBuilder toString(StringBuilder sb,
                               boolean alsoUnlocated)

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

Copyright 2010 JogAmp Community.