SDL3 for Scala Native

sdl3_ttf — text

2026-06-07T00:00:41.559004835Z

import io.github.edadma.sdl3_ttf.*

TrueType text rendering, layered on the core binding. Pulls in sdl3 transitively and adds @link("SDL3_ttf"); install the native library with brew install sdl3_ttf (or your platform’s package). Colours are the core sdl3.Color.

Lifecycle and fonts

ttfInit()                                       // initialise SDL_ttf
val font = openFont("/path/to/font.ttf", 24.0)  // path, point size
// …
font.close()
ttfQuit()

A Font is an AnyVal over the SDL_ttf handle:

font.isNull
font.setSize(18.0)              // re-set point size
font.style = STYLE_BOLD | STYLE_ITALIC
font.style                      // current style bitmask

font.height                    // line height, pixels
font.ascent
font.descent
font.lineSkip                  // recommended line spacing

Style flags: STYLE_NORMAL, STYLE_BOLD, STYLE_ITALIC, STYLE_UNDERLINE, STYLE_STRIKETHROUGH (combine with |).

Measuring

Get the pixel size a string would occupy without rendering it — the basis for laying text out before you draw:

val (w, h): (Int, Int) = font.size("Hello, SDL3")

Rendering

Each render call produces an sdl3.Surface. The quality/cost ladder:

font.renderSolid(text, fg)                    // fast, aliased, transparent bg
font.renderShaded(text, fg, bg)               // antialiased on a solid box
font.renderBlended(text, fg)                  // antialiased with alpha — the usual choice
font.renderBlendedWrapped(text, fg, wrapPixels) // word-wrapped; 0 wraps only on newlines

Upload the surface to a texture and free it, or let texture do both:

val tex = font.texture(renderer, "Hello, SDL3", Color(241, 243, 245))
renderer.copy(tex, 20, 20)
tex.destroy()

For text that doesn’t change every frame, cache the texture rather than rebuilding it each frame — texture allocates a surface, uploads it, and frees the surface on every call.

A note on colour passing

SDL_ttf’s render functions take SDL_Color by value in C. Scala Native mis-marshals a small by-value struct argument, so the binding passes the colour as a packed little-endian uint32 instead — ABI-identical to the 4-byte struct on the supported platforms. This is internal; you just pass an sdl3.Color.

Quick Start

2026-06-07T00:00:41.559004835Z

A complete program: open a window, run an event loop, and draw an animated frame.

A window and a frame loop

import io.github.edadma.sdl3.*

@main def main(): Unit =
  setMainReady()
  if !init(INIT_VIDEO) then
    System.err.println(s"SDL_Init failed: $error")
    return

  val window = createWindow("sdl3 quick start", 640, 480)
  if window.isNull then
    System.err.println(s"createWindow failed: $error")
    return

  val renderer = window.createRenderer()
  renderer.setVSync(true) // throttle the loop to the display refresh

  var running = true
  while running do
    // Drain the event queue each frame.
    var e = pollEvent()
    while e.isDefined do
      val ev = e.get
      if ev.kind == QUIT then running = false
      e = pollEvent()

    // Clear, draw, present.
    renderer.clear(Color(24, 24, 28))
    renderer.setDrawColor(Color(247, 103, 7))
    renderer.fillRect(270, 190, 100, 100)
    renderer.fillCircle(320, 240, 40, Color(255, 255, 255))
    renderer.present()

  renderer.destroy()
  window.destroy()
  quit()

Build and run it with sbt run (it blocks on the window). sbt nativeLink just produces the binary.

Reading input

Poll discrete events from the queue, or read the live device state at any time:

// Event-driven: react to a key press as it happens.
val ev = pollEvent().get
if ev.kind == KEY_DOWN && ev.keyScancode == Scancode.Escape then running = false

// State-driven: query held keys / the mouse each frame.
val keys = Keyboard.state
if keys(Scancode.Space) then jump()

val mouse = Mouse.state
if mouse.left then paint(mouse.x, mouse.y)

Adding text

Bring in sdl3_ttf to draw a label. Initialise it alongside SDL, open a font once, and blit rendered text as a texture:

import io.github.edadma.sdl3.*
import io.github.edadma.sdl3_ttf.*

ttfInit()
val font = openFont("/System/Library/Fonts/Helvetica.ttc", 24)

// each frame, after clear:
val tex = font.texture(renderer, "Hello, SDL3", Color(241, 243, 245))
renderer.copy(tex, 20, 20)
tex.destroy()

// at shutdown:
font.close()
ttfQuit()

For real apps, cache the text texture instead of rebuilding it every frame. See the modules section for each library’s full surface.

sdl3_mixer — audio

2026-06-07T00:00:41.559004835Z

import io.github.edadma.sdl3_mixer.*

Audio playback, layered on the core binding. Pulls in sdl3 transitively and adds @link("SDL3_mixer"); install the native library with brew install sdl3_mixer (or your platform’s package).

SDL3_mixer’s model is a mixer device that plays audio clips, optionally through named tracks you can control individually (gain, pause, fades, looping).

Setup

mixInit()
val mixer = openMixer()        // default playback device
// …
mixer.destroy()
mixQuit()

Fire-and-forget playback

The simplest path — load a clip and play it once on the device:

val clip = mixer.loadAudio("assets/blip.wav")   // predecode = true by default
mixer.play(clip)
// …
clip.destroy()

loadAudio(path, predecode = false) streams from disk instead of decoding up front — prefer it for long music tracks.

Tracks: control a sound over time

For looping, fades, pausing, or per-sound gain, play through a Track:

val track = mixer.createTrack()
track.setAudio(clip)

track.play()                   // play once
track.play(loops = 2)          // play, then repeat twice more
track.play(loops = LOOP_FOREVER)

track.setGain(0.5)             // 0.0 … 1.0
track.pause(); track.resume()
track.playing                  // Boolean

track.stop()                   // stop now
track.stop(fadeOutFrames = 4096) // fade out over N sample frames

track.destroy()

LOOP_FOREVER is -1. Most calls return Boolean success. Destroy tracks and audio clips when done, then the mixer, then mixQuit().

Installation

2026-06-07T00:00:41.559004835Z

These are Scala Native bindings, so there are two halves: the native SDL3 libraries (C shared objects on your system) and the Scala artifacts (added to your build).

Requirements

Scala 3
sbt with the sbt-scala-native plugin
LLVM/Clang (the Scala Native toolchain)
The SDL3 shared libraries on your system

Install the native SDL3 libraries

The Scala layer links against the system SDL3 libraries via @link, so they must be installed and discoverable by the linker. On macOS with Homebrew:

brew install sdl3 sdl3_ttf sdl3_image sdl3_mixer

On Linux, install the SDL3 development packages from your distribution (or build from source). You only need the satellite libraries for the modules you use — sdl3 alone needs just SDL3 itself.

Enable Scala Native

In project/plugins.sbt:

addSbtPlugin("org.scala-native" % "sbt-scala-native" % "0.5.12")

Add the dependencies

Each module is published for Scala Native under io.github.edadma. Enable the Scala Native plugin on your module and add the artifacts you need:

lazy val app = project
  .in(file("app"))
  .enablePlugins(ScalaNativePlugin)
  .settings(
    libraryDependencies += "io.github.edadma" %%% "sdl3"       % "0.2.1",
    libraryDependencies += "io.github.edadma" %%% "sdl3_ttf"   % "0.2.1",
    libraryDependencies += "io.github.edadma" %%% "sdl3_image" % "0.2.1",
    libraryDependencies += "io.github.edadma" %%% "sdl3_mixer" % "0.2.1",
  )

The satellites (sdl3_ttf, sdl3_image, sdl3_mixer) depend on sdl3 transitively, so you do not list the core separately when you use one of them. Each satellite also adds its own @link to the matching native library (SDL3_ttf, etc.), pulling SDL3 in with it.

No linkingOptions are needed: Scala Native finds the Homebrew-installed libraries through each binding’s @link("SDL3") / @link("SDL3_ttf") declaration.

Provide a `main`

SDL apps call SDL_SetMainReady so SDL knows you own main. The binding exposes it as setMainReady(); call it before init. Continue to the quick start for a full window-and-loop example.

sdl3_image — images

2026-06-07T00:00:41.559004835Z

import io.github.edadma.sdl3_image.*

Image loading and PNG saving, layered on the core binding. Pulls in sdl3 transitively and adds @link("SDL3_image"); install the native library with brew install sdl3_image (or your platform’s package). SDL_image handles PNG, JPEG, and the other formats SDL3 supports.

Loading

Load straight to a GPU texture (the common case — ready to draw), or to a CPU surface when you need to inspect or transform pixels first:

// To a texture, ready for renderer.copy:
val tex = loadTexture(renderer, "assets/sprite.png")
val (w, h) = tex.size
renderer.copy(tex, 100, 100)
tex.destroy()

// To a surface (CPU pixels):
val surface = load("assets/sprite.png")
surface.width; surface.height
val gpu = renderer.createTextureFromSurface(surface)
surface.free()

Both return the core Texture / Surface handles, so everything in sdl3 applies. Check isNull after loading to detect failure (a missing or unreadable file).

Saving

Write a surface out as a PNG:

val ok: Boolean = savePNG(surface, "out.png")

sdl3 — core

2026-06-07T00:00:41.559004835Z

import io.github.edadma.sdl3.*

The core artifact: lifecycle, a window, the 2D renderer, textures and surfaces, filled geometry, events, and live input state. Everything here lives in the io.github.edadma.sdl3 package object.

Lifecycle

setMainReady()                  // tell SDL you provide main (call before init)
val ok: Boolean = init(INIT_VIDEO)
val msg: String = error         // last SDL error message
delay(16)                       // sleep, milliseconds
setHint(HINT_RENDER_VSYNC, "1")
quit()

init takes a bitmask of subsystem flags: INIT_TIMER, INIT_AUDIO, INIT_VIDEO, INIT_EVENTS (default INIT_VIDEO). It returns true on success; on failure read error.

Window

val window = createWindow("title", 640, 480)          // flags default to 0
val window = createWindow("title", 640, 480, WINDOW_RESIZABLE)

Window flags: WINDOW_FULLSCREEN, WINDOW_OPENGL, WINDOW_HIDDEN, WINDOW_BORDERLESS, WINDOW_RESIZABLE, WINDOW_HIGH_PIXEL_DENSITY. A Window is an AnyVal over the SDL handle:

window.isNull                       // creation failed?
window.createRenderer()             // or createRenderer("metal") to pick a driver
window.setPosition(x, y)            // SDL3 has no creation-time position
window.pixelFormat                  // Int
window.size            : (Int, Int) // logical size, in points
window.sizeInPixels    : (Int, Int) // backbuffer size, in pixels (≠ size on HiDPI)
window.destroy()

A window is not high-DPI unless created with WINDOW_HIGH_PIXEL_DENSITY; otherwise sizeInPixels == size.

Renderer

The renderer is the 2D drawing context. Coordinates are Double.

val r = window.createRenderer()
r.setVSync(true)                    // sync present to the display refresh

r.setDrawColor(Color(247, 103, 7))  // or setDrawColor(r, g, b, a)
r.setBlendMode(BLENDMODE_BLEND)     // NONE / BLEND / ADD / MOD / MUL

r.clear()                           // clear to the current draw colour
r.clear(Color(24, 24, 28))          // set colour and clear

r.drawPoint(x, y)
r.drawLine(x1, y1, x2, y2)
r.drawRect(x, y, w, h)              // outline
r.fillRect(x, y, w, h)              // filled

r.present()                         // show the frame
r.destroy()

Filled geometry

Shapes SDL has no primitive for are drawn as triangle meshes via SDL_RenderGeometry:

r.fillCircle(cx, cy, radius, Color.White)
r.thickLine(x1, y1, x2, y2, width = 4.0, Color(247, 103, 7))
r.fillConvexPolygon(Array(x0, y0, x1, y1, x2, y2, /* … */), Color.White)

fillConvexPolygon takes a flat Array[Double] of x, y pairs (a triangle fan from the first vertex). The mesh builders are pure and unit-tested.

Render targets

Draw into an off-screen texture, then blit it to the window — useful for supersampling or flicker-free compositing:

val target = r.createTexture(window.pixelFormat, TEXTUREACCESS_TARGET, w, h)
r.setTarget(target)
// … draw …
r.resetTarget()
r.copy(target)                      // blit the whole texture across the window
r.present()

Texture access modes: TEXTUREACCESS_STATIC, TEXTUREACCESS_STREAMING, TEXTUREACCESS_TARGET.

Textures and surfaces

A surface is CPU pixels; a texture is GPU pixels. Upload a surface (from sdl3_ttf or sdl3_image) to a texture, then draw it:

val tex = r.createTextureFromSurface(surface)
tex.setScaleMode(SCALEMODE_LINEAR)  // NEAREST / LINEAR / PIXELART
val (w, h) = tex.size

r.copy(tex)                         // fill the whole target
r.copy(tex, x, y)                   // at (x, y), the texture's own size
r.copy(tex, x, y, w, h)            // into a destination rect

tex.destroy()

surface.width; surface.height
surface.free()

Events

pollEvent() returns Option[Event]; drain it each frame. An Event is a view over a reusable union buffer, so read kind first, then only the fields valid for that kind:

var e = pollEvent()
while e.isDefined do
  val ev = e.get
  ev.kind match
    case QUIT              => running = false
    case KEY_DOWN          => onKey(ev.keyScancode, ev.keyRepeat)
    case MOUSE_BUTTON_DOWN => onClick(ev.mouseX, ev.mouseY, ev.mouseButton)
    case MOUSE_MOTION      => onMove(ev.mouseX, ev.mouseY)
    case MOUSE_WHEEL       => onScroll(ev.wheelX, ev.wheelY)
    case _                 => ()
  e = pollEvent()

Event kinds: QUIT, KEY_DOWN, KEY_UP, MOUSE_MOTION, MOUSE_BUTTON_DOWN, MOUSE_BUTTON_UP, MOUSE_WHEEL. Field accessors: keyScancode, keyRepeat, mouseX, mouseY, mouseButton (1 = left, 2 = middle, 3 = right), wheelX, wheelY (positive y = away from the user).

Event watches

val id = addEventWatch { ev => if ev.kind == QUIT then save() }
removeEventWatch(id)

Live input state

Instead of (or alongside) events, read the current device state directly:

val keys = Keyboard.state
if keys(Scancode.Space) then jump()
if keys(Scancode.Escape) then running = false

val m = Mouse.state          // MouseState(buttons, x, y)
if m.left then paint(m.x, m.y)
m.middle; m.right

Scancode names the physical keys: letters A–Z, digits Num0–Num9, Return, Escape, Backspace, Tab, Space, Minus, Equals, LeftBracket, RightBracket, and the arrows Left, Right, Up, Down. These are the standard USB-HID scancodes SDL reports.

Design

2026-06-07T00:00:41.559004835Z

The binding is deliberately two-layered, and follows a few consistent conventions. You rarely need to know this to use it, but it explains why the API looks the way it does and is essential if you extend it.

Two layers

The @extern layer is the raw FFI: one object per native library (extern.LibSDL3, extern.LibSDL3Ttf, …) that declares the C functions with Scala Native FFI types and @links the shared library. This is the only place Ptr, CStruct, CString, and UInt appear. You never import it.

The pure-Scala layer is the package object you do import (io.github.edadma.sdl3, io.github.edadma.sdl3_ttf, …). It speaks in Int, Double, Boolean, String, a Color case class, and wrapped handles, and it does the marshalling — allocating C strings in a Zone, converting numbers, packing structs — so callers never touch FFI types.

This split keeps the unsafe surface small and auditable, and lets the ergonomic layer evolve without changing the ABI declarations.

Handle wrappers are zero-cost

SDL hands back opaque pointers — SDL_Window *, SDL_Renderer *, SDL_Texture *, SDL_Surface *. Each is wrapped in an AnyVal value class:

implicit class Renderer(val ptr: sdl.SDL_Renderer) extends AnyVal:
  def clear(c: Color): Unit = ...
  def present(): Unit       = ...

Because they extend AnyVal, the wrapper is erased at runtime — a Renderer is the pointer, with methods. You get renderer.present() instead of SDL_RenderPresent(ptr) at no allocation cost. Each wrapper carries an isNull check for the common “did this fail?” test.

Colours

Color(r, g, b, a) is a plain case class with channels 0–255 (a defaults to 255). Color.fromRGB(0xRRGGBB) unpacks a packed literal, and Color.blend(a, b, t) does a clamped linear interpolation. The renderer and text APIs take Color directly.

Conventions worth knowing

These are the rules the binding holds to internally. They matter if you read the source or add functions.

Structs are passed by pointer

SDL functions that take a struct (SDL_FRect, SDL_Vertex, …) are called with a pointer to a buffer the wrapper fills, never a by-value Scala CStruct. Scala Native’s marshalling of small by-value struct arguments is unreliable, so the binding avoids it entirely. Where a C API insists on a by-value struct, the wrapper passes it in an ABI-equivalent form instead — for example SDL_Color (four bytes) is passed to the SDL_ttf render functions as a packed little-endian uint32, which lands in the same register as the 4-byte struct on the SysV-AMD64 and AArch64 ABIs.

Scratch buffers outlive the call, not the helper

A C call that needs a temporary struct (a rect for SDL_RenderFillRect, an event union for SDL_PollEvent) reads it from a persistent heap buffer owned by the package object, refilled per call. It is never stackalloc‘d in a helper that returns the pointer: stack memory belongs to the frame that allocates it, so such a pointer would dangle the instant the helper returns and SDL would read garbage. Reuse is safe because SDL reads the buffer synchronously within the call and rendering is single-threaded.

Events are a view over a union

pollEvent() fills one reusable SDL_Event buffer and returns an Event view. The field accessors (kind, keyScancode, mouseX, wheelY, …) are only meaningful for the matching kind, because the underlying struct is a union. Read kind first, then the fields for that event type.

Geometry is floating-point

SDL3’s render API takes float coordinates — the SDL2-era 16-bit clamping is gone. The binding exposes Double throughout and narrows to float at the FFI boundary. Filled shapes SDL has no primitive for (circles, thick lines) are built as triangle meshes and drawn through SDL_RenderGeometry; the mesh builders are unit-tested headlessly.

SDL3 for Scala Native

sdl3_ttf — text

Lifecycle and fonts

Measuring

Rendering

A note on colour passing

Quick Start

A window and a frame loop

Reading input

Adding text

sdl3_mixer — audio

Setup

Fire-and-forget playback

Tracks: control a sound over time

Installation

Requirements

Install the native SDL3 libraries

Enable Scala Native

Add the dependencies

Provide a main

sdl3_image — images

Loading

Saving

sdl3 — core

Lifecycle

Window

Renderer

Filled geometry

Render targets

Textures and surfaces

Events

Event watches

Live input state

Design

Two layers

Handle wrappers are zero-cost

Colours

Conventions worth knowing

Structs are passed by pointer

Scratch buffers outlive the call, not the helper

Events are a view over a union

Geometry is floating-point

Provide a `main`