ShaderHandle

Identifier and container for UI shaders, referencing external resource paths or embedding GLSL source code.

Architecture & GLSL Resolution

ShaderHandle represents a GPU shader pipeline used by DrawCommandType.SHADER and DrawScope#shader.

Two Operating Modes

1. Resource Identifier (ShaderHandle.resource(id)): Refers to a named shader resource (e.g. minecraft:rendertype_gui or a mod shader). The active RenderBackend queries registered ShaderProvider instances to resolve vertex and fragment source.
2. Embedded GLSL Source (ShaderHandle.source(...) or fragmentSource(...)): Embeds vertex and/or fragment GLSL source strings directly in the handle for rapid procedural effects without packaging loose resource files.

Shader Execution Pipeline

When drawing via DrawScope#shader:

1. ShaderHandle identifies the program.
2. ShaderUniforms supplies custom uniforms (resolution, time, colors, vectors).
3. ShaderDrawOptions configures blending and automatic built-in uniforms (SquareVertex).

Backends compile and cache GLSL programs keyed by id(). Redundant recompilation is avoided across frames.

Procedural Radial Gradient Shader

// Define embedded fragment shader for procedural glowing portal
String glsl = """
#version 150
uniform vec2 u_resolution;
uniform float u_time;
out vec4 fragColor;

void main() {
    vec2 st = gl_FragCoord.xy / u_resolution;
    float dist = distance(st, vec2(0.5));
    float pulse = 0.5 + 0.5 * sin(u_time * 3.0);
    fragColor = vec4(0.2, 0.6, 1.0, (1.0 - smoothstep(0.1, 0.5, dist)) * pulse);
}
""";

ShaderHandle portalShader = ShaderHandle.fragmentSource("mod:portal_effect", glsl);

API

Factory Methods

Method	Description
resource(String)	Creates a ShaderHandle referencing an external shader resource resolved by ShaderProviders.
fragmentSource(String, String)	Creates a ShaderHandle with embedded fragment shader GLSL source.
source(String, String, String)	Creates a ShaderHandle with embedded vertex and fragment GLSL source strings.

ShaderHandle::resource(String)

Create Resource Handle

Creates a ShaderHandle referencing an external shader resource resolved by ShaderProviders.

Parameter	Type	Description
id	String	Shader resource or embedded program identifier.

Returns ShaderHandle: New resource ShaderHandle..

ShaderHandle::fragmentSource(String, String)

Create Embedded Fragment Handle

Creates a ShaderHandle with embedded fragment shader GLSL source.

Parameter	Type	Description
id	String	Shader resource or embedded program identifier.
fragmentSource	String	GLSL fragment shader code.

Returns ShaderHandle: New ShaderHandle with embedded fragment source..

ShaderHandle::source(String, String, String)

Create Embedded Vertex and Fragment Handle

Creates a ShaderHandle with embedded vertex and fragment GLSL source strings.

Parameter	Type	Description
id	String	Shader resource or embedded program identifier.
vertexSource	String	GLSL vertex shader code.
fragmentSource	String	GLSL fragment shader code.

Returns ShaderHandle: New ShaderHandle with full embedded source..

Properties & Sources

Method	Description
id()	Returns stable shader identifier string.
vertexSource()	Returns embedded vertex GLSL code or null.
fragmentSource()	Returns embedded fragment GLSL code or null.
hasEmbeddedVertexSource()	Returns true if this handle contains embedded vertex source.
hasEmbeddedFragmentSource()	Returns true if this handle contains embedded fragment source.
copy()	Creates an independent duplicate of this ShaderHandle.

ShaderHandle::id()

Get Shader ID

Returns stable shader identifier string.

Returns String: Normalized shader ID string..

ShaderHandle::vertexSource()

Get Vertex Source

Returns embedded vertex GLSL code or null.

Returns String: Vertex GLSL source string, or null..

ShaderHandle::fragmentSource()

Get Fragment Source

Returns embedded fragment GLSL code or null.

Returns String: Fragment GLSL source string, or null..

ShaderHandle::hasEmbeddedVertexSource()

Has Embedded Vertex Source

Returns true if this handle contains embedded vertex source.

Returns boolean: True if vertex source is present..

ShaderHandle::hasEmbeddedFragmentSource()

Has Embedded Fragment Source

Returns true if this handle contains embedded fragment source.

Returns boolean: True if fragment source is present..

ShaderHandle::copy()

Copy ShaderHandle

Creates an independent duplicate of this ShaderHandle.

Returns ShaderHandle: New ShaderHandle with identical id and sources..