libGDX 1.14.2 · com.badlogic.gdx.graphics.g3d.Shader

Interface which is used to render one or more Renderables.

A Shader is responsible for the actual rendering of an Renderable. Typically, when using OpenGL ES 2.0 or higher, it encapsulates a ShaderProgram and takes care of all OpenGL calls necessary to render the Renderable. When using OpenGL ES 1.x it takes care of the fixed pipeline.

To start rendering the begin(Camera, RenderContext) method must be called. After which the end() method must be called to stop rendering. In between one or more calls to the render(Renderable) method can be made to render a Renderable. The render(Renderable) method must not be called before a call to begin(Camera, RenderContext) or after a call to end(). Each Shader needs exclusive access to the OpenGL state and RenderContext between the begin(Camera, RenderContext) and end() methods, therefore only one shader can be used at a time (they must not be nested).

A specific Shader instance might be (and usually is) dedicated to a specific type of Renderable. For example it might use a ShaderProgram that is compiled with uniforms (shader input) for specific Attribute types. Therefore the canRender(Renderable) method can be used to check if the Shader instance can be used for a specific Renderable. Rendering a Renderable using a Shader for which canRender(Renderable) returns false might result in unpredicted behavior or crash the application.

To manage multiple shaders and create a new shader when required, a ShaderProvider can be used. Therefore, in practice, a specific Shader implementation is usually accompanied by a specific ShaderProvider implementation (usually extending BaseShaderProvider).

When a Shader is constructed, the init() method must be called before it can be used. Most commonly, the init() method compiles the ShaderProgram, fetches uniform locations and performs other preparations for usage of the Shader. When the shader is no longer needed, it must disposed using the Disposable#dispose() method. This, for example, disposed (unloads for memory) the used ShaderProgram.

Method Summary

Modifier and Type	Method and Description
public void	begin(Camera The camera to use when rendering camera, RenderContext The context to be used, which must be exclusive available for the shader until the call to the `end()` method. context) Initializes the context for exclusive rendering by this shader.
public boolean	Returns: true if this shader is intended to render the `Renderable`, false otherwise. canRender(Renderable The renderable to check against this shader. instance) Checks whether this shader is intended to render the `Renderable`.
public int	compareTo(Shader other) Compare this shader against the other, used for sorting, light weight shaders are rendered first.
public void	end() Cleanup the context so other shaders can render.
public void	init() Initializes the Shader, must be called before the Shader can be used.
public void	render(final Renderable The renderable to render, all required fields (e.g. `Renderable#material` and others) must be set. The `Renderable#shader` field will be ignored. renderable) Renders the `Renderable`, must be called between `begin(Camera, RenderContext)` and `end()`.

Inherited from com.badlogic.gdx.utils.Disposable:: dispose

Method Detail

begin back to summary

begin	back to summary
public void begin(Camera camera, RenderContext context) Initializes the context for exclusive rendering by this shader. Use the `render(Renderable)` method to render a `Renderable`. When done rendering the `end()` method must be called. Parameters camera:Camera The camera to use when rendering context:RenderContext The context to be used, which must be exclusive available for the shader until the call to the `end()` method.

public void begin(Camera camera, RenderContext context)

Initializes the context for exclusive rendering by this shader. Use the render(Renderable) method to render a Renderable. When done rendering the end() method must be called.

Parameters

camera:Camera: The camera to use when rendering
context:RenderContext: The context to be used, which must be exclusive available for the shader until the call to the end() method.

canRender back to summary

canRender	back to summary
public boolean canRender(Renderable instance) Checks whether this shader is intended to render the `Renderable`. Use this to make sure a call to the `render(Renderable)` method will succeed. This is expected to be a fast, non-blocking method. Note that this method will only return true if it is intended to be used. Even when it returns false the Shader might still be capable of rendering, but it's not preferred to do so. Parameters instance:Renderable The renderable to check against this shader. Returns:boolean true if this shader is intended to render the `Renderable`, false otherwise.

public boolean canRender(Renderable instance)

Checks whether this shader is intended to render the Renderable. Use this to make sure a call to the render(Renderable) method will succeed. This is expected to be a fast, non-blocking method. Note that this method will only return true if it is intended to be used. Even when it returns false the Shader might still be capable of rendering, but it's not preferred to do so.

Parameters

instance:Renderable: The renderable to check against this shader.

Returns:boolean

true if this shader is intended to render the Renderable, false otherwise.

compareTo	back to summary
public int compareTo(Shader other) Compare this shader against the other, used for sorting, light weight shaders are rendered first.

end	back to summary
public void end() Cleanup the context so other shaders can render. Must be called when done rendering using the `render(Renderable)` method, which must be preceded by a call to `begin(Camera, RenderContext)`. After a call to this method an call to the `render(Renderable)` method will fail until the `begin(Camera, RenderContext)` is called.

init	back to summary
public void init() Initializes the Shader, must be called before the Shader can be used. This typically compiles a `ShaderProgram`, fetches uniform locations and performs other preparations for usage of the Shader.

render back to summary

render	back to summary
public void render(final Renderable renderable) Renders the `Renderable`, must be called between `begin(Camera, RenderContext)` and `end()`. The Shader instance might not be able to render every type of `Renderable`s. Use the `canRender(Renderable)` method to check if the Shader is capable of rendering a specific `Renderable`. Parameters renderable:Renderable The renderable to render, all required fields (e.g. `Renderable#material` and others) must be set. The `Renderable#shader` field will be ignored.

public void render(final Renderable renderable)

Renders the Renderable, must be called between begin(Camera, RenderContext) and end(). The Shader instance might not be able to render every type of Renderables. Use the canRender(Renderable) method to check if the Shader is capable of rendering a specific Renderable.

Parameters

renderable:Renderable: The renderable to render, all required fields (e.g. Renderable#material and others) must be set. The Renderable#shader field will be ignored.

public Interface Shader

Method Summary

Method Detail