EAGL.Texture (eagl v0.7.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: @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 handling
  • set_texture_parameters() - Type-safe parameter configuration
  • 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 with type-safe options.

Types

filter_mode()

@type filter_mode() :: non_neg_integer()

pixel_type()

@type pixel_type() :: non_neg_integer()

texture_format()

@type texture_format() :: non_neg_integer()

texture_id()

@type texture_id() :: non_neg_integer()

wrap_mode()

@type wrap_mode() :: non_neg_integer()

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

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