EAGL.Shader (eagl v0.9.0)

View Source

OpenGL shader compilation and program management.

Handles the complex multi-step process of shader compilation, linking, and uniform management with Wings3D-inspired error handling.

Original Source

Uniform helper functions (uloc/2, set_uloc/3) are inspired by Wings3D's wings_gl.erl module: https://github.com/dgud/wings/blob/master/src/wings_gl.erl

Usage

import EAGL.Shader
import EAGL.Math

# Compile and link shaders with typed parameters
{:ok, vertex} = create_shader(:vertex, "vertex.glsl")
{:ok, fragment} = create_shader(:fragment, "fragment.glsl")
{:ok, program} = create_attach_link([vertex, fragment])

# Set uniforms with automatic type detection
set_uniform(program, "model_matrix", model_matrix)
set_uniform(program, "light_position", vec3(10.0, 10.0, 5.0))

# Set multiple uniforms efficiently
set_uniforms(program, [
  model: model_matrix,
  view: view_matrix,
  projection: projection_matrix
])

# Use OpenGL directly for program binding
:gl.useProgram(program)

# Clean up when done
cleanup_program(program)

Summary

Functions

Convenience function to cache uniform locations for repeated use. Returns a map of uniform names to their locations.

Checks if a shader compiled successfully.

Cleans up a shader program and all its attached shaders.

Cleans up a shader.

Creates a program, attaches shaders, links, and returns the link status.

Creates and compiles a shader from a file.

Creates and compiles a shader from source code.

Get uniform location for a program. Similar to wings_gl:uloc/2. Returns the uniform location or -1 if not found.

Set uniform value with automatic type detection. Similar to wings_gl:set_uloc/3. Supports various EAGL.Math types and basic values.

Set uniform value at a specific location with automatic type detection.

Convenience function to set multiple uniforms at once. Takes a program and a list of {name, value} tuples where name can be atom or string.

Types

mat2()

@type mat2() :: EAGL.Math.mat2()

mat3()

@type mat3() :: EAGL.Math.mat3()

mat4()

@type mat4() :: EAGL.Math.mat4()

program_id()

@type program_id() :: non_neg_integer()

quat()

@type quat() :: EAGL.Math.quat()

shader_id()

@type shader_id() :: non_neg_integer()

shader_type()

@type shader_type() :: non_neg_integer()

uniform_value()

@type uniform_value() ::
  vec2()
  | vec3()
  | vec4()
  | mat2()
  | mat3()
  | mat4()
  | quat()
  | float()
  | integer()
  | boolean()

vec2()

@type vec2() :: EAGL.Math.vec2()

vec3()

@type vec3() :: EAGL.Math.vec3()

vec4()

@type vec4() :: EAGL.Math.vec4()

Functions

cache_uniform_locations(program, uniform_names)

@spec cache_uniform_locations(program_id(), [String.t() | atom()]) :: %{
  required(String.t()) => integer()
}

Convenience function to cache uniform locations for repeated use. Returns a map of uniform names to their locations.

check_compile_status(shader)

Checks if a shader compiled successfully.

cleanup_program(program)

Cleans up a shader program and all its attached shaders.

cleanup_shader(shader)

Cleans up a shader.

create_attach_link(shaders)

@spec create_attach_link([shader_id()]) :: {:ok, program_id()} | {:error, String.t()}

Creates a program, attaches shaders, links, and returns the link status.

create_shader(shader_type, file_path)

@spec create_shader(shader_type(), String.t()) ::
  {:ok, shader_id()} | {:error, String.t()}

Creates and compiles a shader from a file.

Parameters

  • shader_type: OpenGL shader type constant (e.g., @gl_vertex_shader, @gl_fragment_shader)
  • file_path: Path to the shader file (relative to priv/shaders/ or absolute)

Examples

{:ok, vertex_shader} = create_shader(@gl_vertex_shader, "vertex.glsl")
{:ok, fragment_shader} = create_shader(@gl_fragment_shader, "fragment.glsl")

create_shader_from_source(shader_type, source, name \\ "inline shader")

@spec create_shader_from_source(shader_type(), String.t() | charlist(), String.t()) ::
  {:ok, shader_id()} | {:error, String.t()}

Creates and compiles a shader from source code.

Parameters

  • shader_type: OpenGL shader type constant (e.g., @gl_vertex_shader, @gl_fragment_shader)
  • source: GLSL source code as string or charlist
  • name: Optional name for error reporting (defaults to "inline shader")

Examples

vertex_source = "#version 330 core

layout (location = 0) in vec3 aPos; void main() { gl_Position = vec4(aPos, 1.0); }"

{:ok, shader_id} = create_shader_from_source(@gl_vertex_shader, vertex_source, "my_vertex")

get_uniform_location(program, uniform_name)

@spec get_uniform_location(program_id(), String.t() | charlist()) :: integer()

Get uniform location for a program. Similar to wings_gl:uloc/2. Returns the uniform location or -1 if not found.

set_uniform(program, uniform_name, value)

@spec set_uniform(program_id(), String.t() | charlist(), uniform_value()) :: :ok

Set uniform value with automatic type detection. Similar to wings_gl:set_uloc/3. Supports various EAGL.Math types and basic values.

set_uniform_at_location(location, matrix)

@spec set_uniform_at_location(integer(), uniform_value()) ::
  :ok | {:error, String.t()}
@spec set_uniform_at_location(integer(), vec3()) :: :ok
@spec set_uniform_at_location(integer(), vec2()) :: :ok
@spec set_uniform_at_location(integer(), vec4() | quat()) :: :ok
@spec set_uniform_at_location(integer(), mat4()) :: :ok
@spec set_uniform_at_location(integer(), mat3()) :: :ok
@spec set_uniform_at_location(integer(), mat2()) :: :ok
@spec set_uniform_at_location(integer(), integer()) :: :ok
@spec set_uniform_at_location(integer(), float()) :: :ok
@spec set_uniform_at_location(integer(), boolean()) :: :ok

Set uniform value at a specific location with automatic type detection.

set_uniforms(program, uniforms)

@spec set_uniforms(program_id(), [{atom() | String.t(), uniform_value()}]) :: :ok

Convenience function to set multiple uniforms at once. Takes a program and a list of {name, value} tuples where name can be atom or string.