EAGL.Texture (eagl v0.6.0)

View Source

OpenGL 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 handling
  • set_texture_parameters() - Converts atoms to GL constants
  • load_texture_data() - Handles format/type conversion with defaults
  • create_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

filter_mode()

@type filter_mode() ::
  :nearest
  | :linear
  | :nearest_mipmap_nearest
  | :linear_mipmap_nearest
  | :nearest_mipmap_linear
  | :linear_mipmap_linear

pixel_type()

@type pixel_type() ::
  :unsigned_byte
  | :byte
  | :unsigned_short
  | :short
  | :unsigned_int
  | :int
  | :float

texture_format()

@type texture_format() ::
  :red | :rg | :rgb | :rgba | :depth_component | :depth_stencil

texture_id()

@type texture_id() :: non_neg_integer()

wrap_mode()

@type wrap_mode() :: :repeat | :mirrored_repeat | :clamp_to_edge | :clamp_to_border

Functions

create_checkerboard_texture(size \\ 256, square_size \\ 32)

@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)

create_texture()

@spec create_texture() :: {:ok, texture_id()} | {:error, String.t()}

Creates a new texture object and returns its ID.

create_textures(count)

@spec create_textures(pos_integer()) :: {:ok, [texture_id()]} | {:error, String.t()}

Creates multiple texture objects and returns their IDs.

load_texture_data(width, height, pixel_data, opts \\ [])

@spec load_texture_data(pos_integer(), pos_integer(), binary(), keyword()) :: :ok

Loads pixel data into the currently bound texture.

Parameters

  • width: Texture width in pixels
  • height: Texture height in pixels
  • pixel_data: Binary containing pixel data
  • opts: 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
)

load_texture_from_file(file_path, opts \\ [])

@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)

set_texture_parameters(opts \\ [])

@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
)