libgdx-shaders

libGDX ShaderProgram & GLSL

Quick reference for ShaderProgram, GLSL authoring, SpriteBatch/Mesh integration, and cross-platform shader compatibility. Covers GL ES 2.0 and GL ES 3.0 targeting.

ShaderProgram Basics

// Construction — from source strings or FileHandles
ShaderProgram shader = new ShaderProgram(vertexSrc, fragmentSrc);
ShaderProgram shader = new ShaderProgram(Gdx.files.internal("vert.glsl"),
                                         Gdx.files.internal("frag.glsl"));

// ALWAYS check compilation
if (!shader.isCompiled()) {
    Gdx.app.error("Shader", shader.getLog());
    // handle failure — do not proceed
}

// Bind before setting uniforms (standalone usage)
shader.bind();
shader.setUniformf("u_time", elapsed);

// Disposal
shader.dispose();

ShaderProgram is a managed resource — auto-recompiles on Android GL context loss. Source strings are retained internally.

DO NOT use begin()/end() — they are deprecated. begin() just calls bind(). end() is a no-op. Use bind() directly.

Configuration (Static Fields)

// Strict uniform checking (default: true)
// true  → IllegalArgumentException if uniform name not found in shader
// false → silently ignores missing uniforms (GL no-op on location -1)
ShaderProgram.pedantic = false;

// Prepended to ALL shader source before compilation (default: "")
// Affects every ShaderProgram created after being set, including internal ones
ShaderProgram.prependVertexCode = "#version 150\n";
ShaderProgram.prependFragmentCode = "#version 150\n";

prependVertexCode/prependFragmentCode are useful for injecting #version directives globally (e.g., fixing macOS GL 3.2 core profile). Caution: they affect libGDX's internal shaders (SpriteBatch, ShapeRenderer) too.

Standard Attribute Names

Constant	Value	Components
ShaderProgram.POSITION_ATTRIBUTE	"a_position"	3 (xyz)
ShaderProgram.COLOR_ATTRIBUTE	"a_color"	4 (rgba)
ShaderProgram.TEXCOORD_ATTRIBUTE	"a_texCoord"	2 (uv) — unit appended: a_texCoord0
ShaderProgram.NORMAL_ATTRIBUTE	"a_normal"	3 (xyz)
ShaderProgram.TANGENT_ATTRIBUTE	"a_tangent"	3
ShaderProgram.BINORMAL_ATTRIBUTE	"a_binormal"	3
ShaderProgram.BONEWEIGHT_ATTRIBUTE	"a_boneWeight"	2 — unit appended: a_boneWeight0