EAGL.Texture (eagl v0.7.0)
View SourceOpenGL texture management utilities.
Handles texture creation, loading, and parameter configuration with Wings3D-inspired helper functions, focusing on meaningful abstractions rather than thin wrappers around OpenGL calls.
Original Source
Texture management patterns and helper functions are inspired by Wings3D's
wings_gl.erl
module:
https://github.com/dgud/wings/blob/master/src/wings_gl.erl
Basic Usage
import EAGL.Texture
import EAGL.Error
# Load texture from image file (requires optional stb_image dependency)
{:ok, texture_id, width, height} = load_texture_from_file("priv/images/eagl_logo_black_on_white.jpg")
# Or create procedural textures
{:ok, texture_id, width, height} = create_checkerboard_texture(256, 32)
# Manual texture creation and configuration
{:ok, texture_id} = create_texture()
:gl.bindTexture(@gl_texture_2d, texture_id)
set_texture_parameters(wrap_s: @gl_clamp_to_edge, min_filter: @gl_linear)
load_texture_data(width, height, pixel_data, format: @gl_rgb)
:gl.generateMipmap(@gl_texture_2d)
check("After generating mipmaps")
# Clean up
:gl.deleteTextures([texture_id])
Texture Parameters
Use OpenGL constants for texture parameters:
- Wrapping:
@gl_repeat
,@gl_mirrored_repeat
,@gl_clamp_to_edge
,@gl_clamp_to_border
- Filtering:
@gl_nearest
,@gl_linear
,@gl_nearest_mipmap_nearest
,@gl_linear_mipmap_linear
, etc. - Format:
@gl_rgb
,@gl_rgba
,@gl_red
,@gl_rg
Philosophy
This module provides substantial helper functions rather than thin wrappers:
create_texture()
- Returns{:ok, id}
tuples for error handlingset_texture_parameters()
- Type-safe parameter configurationload_texture_data()
- Handles format/type conversion with defaultscreate_checkerboard_texture()
- Generates procedural textures
For simple operations like binding, unbinding, or generating mipmaps,
call the OpenGL functions directly and use EAGL.Error.check()
as needed.
Summary
Functions
Creates a simple checkerboard texture for testing purposes. Returns a tuple of {texture_id, width, height}.
Creates a new texture object and returns its ID.
Creates multiple texture objects and returns their IDs.
Loads pixel data into the currently bound texture.
Loads a texture from an image file.
Sets texture parameters for wrapping and filtering with type-safe options.
Types
@type filter_mode() :: non_neg_integer()
@type pixel_type() :: non_neg_integer()
@type texture_format() :: non_neg_integer()
@type texture_id() :: non_neg_integer()
@type wrap_mode() :: non_neg_integer()
Functions
@spec create_checkerboard_texture(pos_integer(), pos_integer()) :: {:ok, texture_id(), pos_integer(), pos_integer()} | {:error, String.t()}
Creates a simple checkerboard texture for testing purposes. Returns a tuple of {texture_id, width, height}.
Parameters
size
: Size of the checkerboard (default: 256)square_size
: Size of each square (default: 32)
Examples
{:ok, texture_id, width, height} = create_checkerboard_texture()
{:ok, texture_id, width, height} = create_checkerboard_texture(128, 16)
@spec create_texture() :: {:ok, texture_id()} | {:error, String.t()}
Creates a new texture object and returns its ID.
@spec create_textures(pos_integer()) :: {:ok, [texture_id()]} | {:error, String.t()}
Creates multiple texture objects and returns their IDs.
@spec load_texture_data(pos_integer(), pos_integer(), binary(), keyword()) :: :ok
Loads pixel data into the currently bound texture.
Parameters
width
: Texture width in pixelsheight
: Texture height in pixelspixel_data
: Binary containing pixel dataopts
: Options for format and type
Options
internal_format
: Internal storage format (default: @gl_rgb)format
: Pixel data format (default: @gl_rgb)type
: Pixel data type (default: @gl_unsigned_byte)level
: Mipmap level (default: 0)
Examples
# RGB data
load_texture_data(256, 256, pixel_data, format: @gl_rgb)
# RGBA data with alpha channel
load_texture_data(256, 256, pixel_data,
internal_format: @gl_rgba,
format: @gl_rgba
)
@spec load_texture_from_file( String.t(), keyword() ) :: {:ok, texture_id(), pos_integer(), pos_integer()} | {:error, String.t()}
Loads a texture from an image file.
Requires the optional stb_image
dependency. If not available, falls back to
checkerboard texture with a helpful warning message.
Parameters
file_path
: Path to the image file (relative to project root or absolute)opts
: Options for texture loading
Options
flip_y
: Flip image vertically (default: true, matches OpenGL convention)fallback_size
: Size of fallback checkerboard if image loading fails (default: 256)fallback_square_size
: Square size for fallback checkerboard (default: 32)
Examples
# Load EAGL logo
{:ok, texture_id, width, height} = load_texture_from_file("priv/images/eagl_logo_black_on_white.jpg")
# Load with custom options
{:ok, texture_id, width, height} = load_texture_from_file("container.jpg", flip_y: false)
@spec set_texture_parameters(keyword()) :: :ok
Sets texture parameters for wrapping and filtering with type-safe options.
Options
wrap_s
: Wrapping mode for S coordinate (default: @gl_repeat)wrap_t
: Wrapping mode for T coordinate (default: @gl_repeat)min_filter
: Minification filter (default: @gl_linear)mag_filter
: Magnification filter (default: @gl_linear)
Examples
# Use default parameters (repeat wrapping, linear filtering)
set_texture_parameters()
# Custom parameters with type-safe options
set_texture_parameters(
wrap_s: @gl_clamp_to_edge,
wrap_t: @gl_clamp_to_edge,
min_filter: @gl_nearest,
mag_filter: @gl_nearest
)