zig-sdl3

A lightweight wrapper to zig-ify SDL3.

Warning

While all of the subsystems are done, it is not quite production ready as certain bugs, namings, and examples have not been ironed out!

However, most of the library is stable and usable! If you're a hobbyist, you are recommended to try it out so that I can get early feedback for bugs and changes!

See the milestones for more details on progress.

If something does not work, see the FAQ first.

Documentation

https://7games.codeberg.page/zig-sdl3/@docs

About

This library aims to unite the power of SDL3 with general zigisms to feel right at home alongside the zig standard library. SDL3 is compatible with many different platforms, making it the perfect library to pair with zig. Some advantages of SDL3 include windowing, audio, gamepad, keyboard, mouse, rendering, and GPU abstractions across all supported platforms.

Building and using

To use zig-sdl3 with zig 0.16.0, you need to add it as a dependency to your project. The master branch of zig is not currently supported. Choose the command that matches your desired zig-sdl3 version and run it in your project's root directory:

• For the latest tagged release:

zig fetch --save git+https://codeberg.org/7Games/zig-sdl3#v0.2.0

• For in progress updates (nightly):

zig fetch --save git+https://codeberg.org/7Games/zig-sdl3#master

Then add zig-sdl3 as a dependency and import its modules and artifact in your build.zig:

constsdl3=b.dependency("sdl3",.{.target=target,.optimize=optimize,// Lib options./// .ext_image = false,/// .ext_net = false,/// .ext_ttf = false,/// .log_message_stack_size = 1024,/// .main = false,/// .renderer_debug_text_stack_size = 1024,// Options passed directly to https://github.com/castholm/SDL (SDL3 C Bindings):// .c_sdl_preferred_linkage = .static,// .c_sdl_strip = false,// .c_sdl_sanitize_c = .off,// .c_sdl_lto = .none,// .c_sdl_emscripten_pthreads = false,// .c_sdl_install_build_config_h = false,// Options if `ext_image` is enabled:// .image_enable_bmp = true,// .image_enable_gif = true,// .image_enable_jpg = true,// .image_enable_lbm = true,// .image_enable_pcx = true,// .image_enable_png = true,// .image_enable_pnm = true,// .image_enable_qoi = true,// .image_enable_svg = true,// .image_enable_tga = true,// .image_enable_xcf = true,// .image_enable_xpm = true,// .image_enable_xv = true,});

Now add the modules and artifact to your target as you would normally:

lib.root_module.addImport("sdl3",sdl3.module("sdl3"));

Example

Simple hello world:

constsdl3=@import("sdl3");conststd=@import("std");constfps=60;constscreen_width=640;constscreen_height=480;pubfnmain()!void{defersdl3.shutdown();// Initialize SDL with subsystems you need here.constinit_flags=sdl3.InitFlags{.video=true};trysdl3.init(init_flags);defersdl3.quit(init_flags);// Initial window setup.constwindow=trysdl3.video.Window.init("Hello SDL3",screen_width,screen_height,.{});deferwindow.deinit();// Useful for limiting the FPS and getting the delta time.varfps_capper=sdl3.extras.FramerateCapper(f32){.mode=.{.limited=fps}};varquit=false;while(!quit){// Delay to limit the FPS, returned delta time not needed.constdt=fps_capper.delay();_=dt;// Update logic.constsurface=trywindow.getSurface();trysurface.fillRect(null,surface.mapRgb(128,30,255));trywindow.updateSurface();// Event logic.while(sdl3.events.poll())|event|switch(event){.quit=>quit=true,.terminating=>quit=true,else=>{},};}}

See the examples directory for more detailed examples.

Structure

Source

The src folder was originally generated via a binding generator, but manually perfecting and testing the subsystems was found to be more productive. Each source file must also call each function at least once in testing if possible to ensure compilation is successful.

Examples

The examples directory has some example programs utilizing SDL3. All examples may be built with zig build examples, or a single example can be ran with zig build run -Dexample=<example name>.

Template

The template directory contains a sample hello world to get started using SDL3. Simply copy this folder to use as your project, and have fun!

Tests

Tests for the library can be ran by running zig build test.

Features

• SDL subsystems are divided into convenient namespaces.
• Functions that can fail have the return wrapped with an error type and can even call a custom error callback.
• C namespace exporting raw SDL functions in case it is ever needed.
• Standard init and deinit functions for creating and destroying resources.
• Skirts around C compat weirdness when possible (C pointers, anyopaque, C types).
• Naming and conventions are more consistent with zig.
• Functions return values rather than write to pointers.
• Types that are intended to be nullable are now clearly annotated as such with optionals.
• Easy conversion to/from SDL types from the wrapped types.
• The self.function() notation is used where applicable.

FAQ

How Do I Get Started?

The easiest way is to copy the template, and comment out the path in the zon file and uncomment the url. Fix the hash as needed. The template uses the callback method, an extension lib, and overall shows how the wrapper can be used to create an application.

When Is 1.0.0 Being Released?

When it's ready, you can track progress by looking at the milestones. My free time is limited, but trust me my top priority is getting this out soon!

GPU Examples?

There is progress on the shadercross branch at the moment.

HLSL Examples?

There will be at least one that exists before 1.0.0 is released.

FreeType TLS Error

You may need to run zig fetch 'git+https://github.com/allyourcodebase/freetype#884fd2235e6ae1ec4306eda30b3259f20930ed2e' due to a bug in zig if you encounter a TLS error.

Symlink Error

If you get something like this on Windows:

C:\...\zig\p\SDL_image-3.2.4--aJoHa0VAAC_C_du38OrOmZ4m23B5bCjXONc13NEpTYf\build.zig.zon:12:20: error: unable to unpack packfile
 .url = "git+https://github.com/libsdl-org/SDL_image#release-3.2.4",
 ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
note: unable to create symlink from 'Xcode\macOS\SDL3.framework\Headers' to 'Versions/Current/Headers': AccessDenied
note: unable to create symlink from 'Xcode\macOS\SDL3.framework\Resources' to 'Versions/Current/Resources': AccessDenied
note: unable to create symlink from 'Xcode\macOS\SDL3.framework\SDL3.tbd' to 'Versions/Current/SDL3.tbd': AccessDenied
note: unable to create symlink from 'Xcode\macOS\SDL3.framework\Versions\Current' to 'A': AccessDenied

See this: 7Games/zig-sdl3#21