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

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

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

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

Install SDL3 from source: SDL GitHub

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

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.

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.

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.

The bindings support two main build configurations:

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.

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.

Add to cabal.project.local:

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

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

• 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

• Render - 2D rendering basics

• Rect - Rectangle basics (no rendering here)

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

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

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

• Audio - Audio playback
• WAV - WAV file handling

• Camera - Camera device access (tested on macOS)

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

• Locale - Localization support

• Time - Time functions
• Timer - Timer functionality

• Process - Process management

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

Last updated: 2025-12-20 03:29 UTC

• Total Modules: 55
• Modules with Bindings: 55
• Complete Bindings: 55
• Missing Functions: 0
• Completion Rate: 100%

• ✅ 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

• 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