SDL3 Haskell Bindings λ

Work in progress bindings for the SDL3 library written in Haskell.

Please report any bugs or suggestions you have for the bindings!

Setup Instructions

::: {.note} NOTE: These bindings are for SDL version 3.4.0 as of right now. :::

Cloning the Repository

This repository uses a git submodule for SDL3 headers. Clone with:

git clone --recurse-submodules https://github.com/klukaszek/sdl3-hs.git

Or if you've already cloned without submodules:

git submodule update --init

Installing SDL3

Install SDL3 from source: SDL GitHub

Tip: If you cloned with --recurse-submodules, the SDL3/ directory in this repository is your SDL3 source.

Unix-like

To build SDL3 from source on Unix-like systems (Linux, macOS, BSD):

# Navigate to SDL3 source directory
cd SDL3/

# Create and enter build directory
mkdir build
cd build

# Configure with cmake.
# CMAKE_BUILD_TYPE can be whatever you need it to be.
cmake -DCMAKE_BUILD_TYPE=Release -GNinja ..

# Build
cmake --build . --config Release --parallel

# Install (requires sudo)
sudo cmake --install . --config Release

This will install SDL3 to your system so that cabal can find and build the sdl3 package.

Find your way back to this project's directory and run cabal build sdl3 to build just the package.

Windows

Recommendation: Use the Developer PowerShell or Developer Command Prompt that comes with Visual Studio for best results.

# Navigate to SDL3 source directory
cd SDL3/

# Create and enter build directory
mkdir build
cd build

# Configure with cmake.
# CMAKE_BUILD_TYPE can be whatever you need it to be.
cmake -DCMAKE_BUILD_TYPE=Release -GNinja ..

# Build
cmake --build . --config Release --parallel

# Install (requires sudo)
cmake --install . --config Release

Make sure SDL3 compiles a .DLL file, and pkgconfig knows that SDL3 exists. (You might have to install pkgconfig using your pacman of choice.)

You can do this by setting:

set PKG_CONFIG_PATH="path\to\SDL3\lib\pkgconfig"
# or
$env:PKG_CONFIG_PATH="path\to\SDL3\lib\pkgconfig\"

Ensure the .DLL file is present in your PATH environment variable or within the root directory for this project.

You'll also want to add a cabal.project.local file to the root directory with:

package *
  extra-include-dirs: "path/to/SDL3/include/"
  extra-lib-dirs: "path/to/SDL3/lib/"

Once all of this is done, you can find your way into this directory and run cabal build sdl3 to build just the package.

Building and Running Examples

To build all examples:

cabal build --flag examples

To see a list of all available examples:

cabal run --flag examples

To run a specific example:

cabal run --flag examples EXAMPLE_NAME

For example, to run the init example:

cabal run --flag examples init

You can also build specific executables in a similar manner by specifying the target name.

Build Options

The bindings support two main build configurations:

Dynamic Linking (Default)

cabal build sdl3                    # Build library only
cabal build --flag examples        # Build with examples

This is the default and recommended approach for development. Your executable will depend on SDL3 shared libraries.

Static Linking

cabal build --flag static-linking  # Build with static SDL3 (Linux only)

Creates self-contained executables with SDL3 compiled in. Requires SDL3 to be built with static libraries enabled.

⚠️ macOS Limitation: Static linking is not supported on macOS due to Apple's linking restrictions. The static-linking flag is ignored on macOS. Use dynamic linking with bundled libraries instead (see DISTRIBUTION.md).

Note: Static linking requires SDL3 built with -DBUILD_SHARED_LIBS=OFF. See DISTRIBUTION.md for details.

Cabal Project Configuration

Add to cabal.project.local:

package sdl3
  flags: +static-linking  # Enable static linking

Distribution

For distributing applications to end users, see our comprehensive Distribution Guide which covers:

• Bundling official SDL3 releases (recommended)
• Static linking strategies
• Platform-specific distribution
• Testing and optimization
• Production considerations

Quick Summary:

• Development: Use dynamic linking (default)
• Distribution: Bundle SDL3 libraries with your executable
• Self-contained: Use static linking for single-file distribution (Linux only)
• macOS: Use dynamic linking with bundled libraries

Working Examples

Core Functionality

Initialization & System

• Init - Basic SDL initialization
• System - System information and capabilities
• Platform - Platform-specific functionality
• CPU Info - Processor information
• Power - Power state monitoring
• Hints - SDL configuration hints

Window & Rendering

Rendering

• Render - 2D rendering basics

Misc

• Rect - Rectangle basics (no rendering here)

GPU & Graphics

These examples are based off of the original SDL3 GPU Examples

• GPU Triangle - Raw triangle rendering
• GPU Clear - Basic screen clearing
• GPU Vertex Buffer - Vertex buffer usage (matches gpu-vbuf)
• GPU Textured Quad - Texture mapping
• GPU Custom Sampling - Implementing custom texture sampling logic
• GPU Animated Quad - Animation basics
• GPU Instanced - Instanced rendering
• GPU Stencil - Stencil buffer operations
• GPU Cull - Culling techniques
• GPU Multi-Window - Multiple window rendering
• GPU Draw Indirect - Leveraging indirect draw commands for GPU-driven rendering
• GPU Basic Compute - Basic compute shader usage
• GPU Clear 3D Slice - Clearing a slice of a 3D texture
• GPU Compute Uniforms - Using uniforms with compute shaders
• GPU Compute Sampler - Using samplers within compute shaders
• GPU Compute Tonemapping - Using compute pipelines for HDRI texture tonemapping.
• GPU Copy Consistency - Copy a texture to the GPU, alter it, and draw it to the framebuffer.
• GPU Copy & Readback - Write texture to GPU and read it back, verifying data integrity.
• GPU Texture 2D Array - Rendering with 2D texture arrays
• GPU Texture Type Test - Testing various texture types and formats
• GPU Compressed Textures - BCn and ASTC texture loading
• GPU Generate Mipmaps - On-the-fly mipmap generation
• GPU Blit 2D Array - Blitting 2D texture array layers
• GPU Blit Cube - Blitting cubemap faces
• GPU Blit Mirror - Mirroring blit operations
• GPU Latency - Measuring and managing input-to-display latency
• GPU Window Resize - Efficiently handling window resizing with GPU resources
• GPU Triangle MSAA - Multi-sample anti-aliasing basics
• GPU Cubemap - Cubemap rendering and skybox
• GPU Depth Sampler - Depth buffer sampling and post-processing
• GPU Compute Sprite Batch - GPU-driven sprite batching with compute
• GPU Pull Sprite Batch - Pull-based vertex shader sprite batching
• (... More coming ...)

Input & Interaction

User Input

• Events - Event handling
• Gamepad - Controller input
• Touch Device - Touch input handling (Can't test properly but compiles.)
• Haptic - Force feedback (Can't test properly but compiles.)

User Interface

• Dialog - Dialog boxes
• Message Box - Simple message dialogs
• Clipboard - Clipboard manipulation
• Tray - System tray integration

Audio & Media

Audio

• Audio - Audio playback
• WAV - WAV file handling

Camera

• Camera - Camera device access (tested on macOS)

System Integration

File & Data

• Filesystem - File system operations
• Storage - Persistent storage
• GUID - Globally unique identifier handling

Internationalization

• Locale - Localization support

Time & Process Management

Time

• Time - Time functions
• Timer - Timer functionality

Process

• Process - Process management

Sensors

Hardware

• Sensor - Hardware sensor access (Can't test properly but compiles.)

📊 Binding Status

Last updated: 2026-01-10 11:05 UTC

Summary

• Total Modules: 55
• Modules with Bindings: 55
• Complete Bindings: 54
• Missing Functions: 2
• Completion Rate: 98%

Status by Module

Legend

• ✅ Complete: All functions from the header are bound
• ⚠️ X missing: Header has bindings but X functions are missing
• ❌ No bindings: No Haskell bindings exist for this header
• ❓ Unknown: Status could not be determined

Notes

• Status reflects core SDL3 headers (test/internal headers excluded)
• Missing function details are available in the broken/ directory after running the binding checker
• Some modules may intentionally have no bindings if not applicable to Haskell