EAGL.Texture (eagl v0.4.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: :clamp_to_edge, min_filter: :linear)
load_texture_data(width, height, pixel_data, format: :rgb)
:gl.generateMipmap(@gl_texture_2d)
check("After generating mipmaps")
# Clean up
:gl.deleteTextures([texture_id])
Texture Parameters
- Wrapping:
:repeat
,:mirrored_repeat
,:clamp_to_edge
,:clamp_to_border
- Filtering:
:nearest
,:linear
,:nearest_mipmap_nearest
,:linear_mipmap_linear
, etc. - Format:
:rgb
,:rgba
,:red
,:rg
Philosophy
This module provides substantial helper functions rather than thin wrappers:
create_texture()
- Returns{:ok, id}
tuples for error handlingset_texture_parameters()
- Converts atoms to GL constantsload_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.
Types
@type filter_mode() ::
:nearest
| :linear
| :nearest_mipmap_nearest
| :linear_mipmap_nearest
| :nearest_mipmap_linear
| :linear_mipmap_linear
@type pixel_type() ::
:unsigned_byte
| :byte
| :unsigned_short
| :short
| :unsigned_int
| :int
| :float
@type texture_format() ::
:red | :rg | :rgb | :rgba | :depth_component | :depth_stencil
@type texture_id() :: non_neg_integer()
@type wrap_mode() :: :repeat | :mirrored_repeat | :clamp_to_edge | :clamp_to_border
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: :rgb)format
: Pixel data format (default: :rgb)type
: Pixel data type (default: :unsigned_byte)level
: Mipmap level (default: 0)
Examples
# RGB data
load_texture_data(256, 256, pixel_data, format: :rgb)
# RGBA data with alpha channel
load_texture_data(256, 256, pixel_data,
internal_format: :rgba,
format: :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.
Options
wrap_s
: Wrapping mode for S coordinate (default: :repeat)wrap_t
: Wrapping mode for T coordinate (default: :repeat)min_filter
: Minification filter (default: :linear)mag_filter
: Magnification filter (default: :linear)
Examples
# Use default parameters (repeat wrapping, linear filtering)
set_texture_parameters()
# Custom parameters
set_texture_parameters(
wrap_s: :clamp_to_edge,
wrap_t: :clamp_to_edge,
min_filter: :nearest,
mag_filter: :nearest
)