dasSDL3: Idiomatic SDL3 bindings for daslang

Developer GaijinEntertainment released dasSDL3, a set of idiomatic SDL3 bindings for the daslang programming language, generated with the dasClangBind tool and layered with an sdl_boost helper library. The bindings cover all of SDL3's functionality across several platforms, including its abstraction over modern GPU APIs such as DirectX, Metal, OpenGL, and Vulkan, and add daslang-specific idioms including the |> pipeline operator, builder-style object construction, and named initialization. The interface design was modeled on the Rust SDL3 bindings.

This is an AI-assisted English translation of the original post: dasSDL3 Russian original https://spiiin.github.io/blog/3531085095/ . I made SDL https://www.libsdl.org/ bindings for daslang https://daslang.io/ . SDL3 sdl3 SDL abstracts access to hardware and operating system facilities. Version 3 also introduced an abstraction over modern GPU APIs https://wiki.libsdl.org/SDL3/CategoryGPU . You can still use SDL just to create a window and draw into it through another graphics API: DirectX, Metal, OpenGL, or Vulkan. There are also several companion libraries https://wiki.libsdl.org/SDL3/Libraries that extend SDL with image loading, higher-level audio and networking APIs, and simple 2D graphics. I wanted this kind of Swiss Army knife for daslang , so I used AI to build bindings for all of SDL3’s functionality across several platforms. Automatic binding generation automatic-binding-generation The bindings are generated with dasClangBind https://github.com/GaijinEntertainment/daScript/tree/master/modules/dasClangBind , which works with a subset of C++. It parses the library’s code and generates basic bindings. These still need some polishing: removing helper macros and functions that do not belong in the bindings, and adapting idioms that do not translate well between languages, such as raw pointers and objects with different lifetimes or memory management rules. Getting working bindings is the first and easiest part of the job. Idiomatic APIs idiomatic-apis The next layer is sdl boost , a set of helpers on top of the basic bindings that makes the library easier to use and the code more expressive. Every language has its own idioms. Good bindings let you use library functions in forms that feel natural in the target language. The syntax macros in daslang are a great fit for this. I used the Rust SDL3 bindings https://docs.rs/sdl3/latest/sdl3/index.html as a reference when designing the interface. I have already written about the Rust community’s approach to API design: Elegant APIs in Rust https://spiiin.github.io/blog/3198586047/ . Here I adapted those ideas to daslang . Pipelines pipelines Pipelines are one of the features that make an interface convenient to use. See Pipelining might be my favorite programming language feature https://herecomesthemoon.net/2025/04/pipelining/ . In daslang , the | operator makes value | function argument equivalent to function value, argument . The result of one call becomes the first argument of the next, so the code reads in execution order. Builder builder You can build up an object description step by step. For example, set a window’s size, add a flag, and choose its position: window options creates a WindowOptions , and each subsequent call returns an updated description. The window does not exist yet: you can prepare the settings separately and then pass them to with window . Similar chains are available for textures, shaders, samplers, and graphics pipelines. For example, here is a sampler description with linear filtering, interpolation between mip levels, and texture wrapping: filters sets the minification and magnification filters, mipmap mode controls filtering between mip levels, and address modes determines how coordinates outside the texture are handled. The result is an ordinary SDL GPUSamplerCreateInfo , which you can pass to with gpu sampler device, sampler settings to create a GPU resource with a defined lifetime. These are ordinary free functions. You do not need to turn the description into a class with methods to get a chain of calls. The parentheses around the multiline expression allow continuation lines starting with | . Named initialization named-initialization For short descriptions, it is convenient to specify the fields directly: A builder is useful when you assemble a description step by step; named initialization is useful when all the settings are known up front. Return values and Result return-values-and-result In C APIs, results are often written to parameters passed by pointer. The helper layer can return them as ordinary values. For example, window size window returns a Result<int2, SdlError containing either the window size or an error description. In daslang syntax, this type is written as $Result<int2; SdlError . Long type names can be shortened with typedef . For example, the library defines this type for operations without a meaningful success value: Function signatures can now use SdlStatus instead of the full type. SdlUnit represents an empty success value, and sdl ok creates that successful result. SdlError stores the operation name and the error message, copied before resources are released. You can also introduce aliases for a specific task: For results with different value types, the library provides the generic form $SdlResult<T . For example, $SdlResult<int2 is the same type as $Result<int2; SdlError . It is implemented by a type macro that supplies SdlError to the standard Result . These abbreviations give types convenient names while preserving their representation and behavior. Option represents an absent value. For example, an SDL hint may not be set, in which case you can supply a fallback: The interface thus distinguishes an operation failure from the normal absence of a value. Early returns with sdl try early-returns-with-sdl-try When several operations return Result , you have to check for an error after each one. For example, let’s get the window size, print it, and clear the renderer. Without any helper syntax, the code looks like this: window size and the enclosing function return results with different success types: int2 and SdlUnit . If the first call fails, its SdlError must be placed into a result with the appropriate success type. For clear , the result can be returned directly. With sdl try , the same function becomes shorter: sdl try is a syntax macro: on success, it extracts the value; on failure, it returns early from the current function or block, preserving the SdlError . The checks from the first example are still there, but the macro generates them. The calls read as a sequence of actions, and error reporting can be left to the application boundary. The enclosing function or block must return a Result whose error type is SdlError . sdl try does not unwrap an Option or manage pointer lifetimes; resources use with scopes. The same idea in other languages the-same-idea-in-other-languages In daslang , the idiom is implemented at the library level: sdl try generates checks and early returns through a syntax macro. Explicitly marking potential exit points seemed the most convenient approach to me: it shows where execution may end while keeping the code linear, without nested blocks or extra braces. Other languages have similar mechanisms for stopping a chain when a value is absent. The examples below use a fictional SDL API: first we create a window, then a renderer for it. The creation functions return Option / Maybe ; if either step produces no value, the remaining steps are skipped. Rust: the ? https://doc.rust-lang.org/std/option/index.html the-question-mark-operator operator extracts a value from Some , or returns None from the current function when it encounters None . The potential exit points are visible in the expressions: Haskell: in a do block for Maybe , <- extracts a value from Just . On Nothing , the whole block evaluates to Nothing and the continuation is skipped. This behavior comes from binding computations for Maybe https://downloads.haskell.org/~ghc/9.0.1-alpha1/docs/html/libraries/base-4.15.0.0/src/GHC-Base.html : the point where the chain stops lies “between the lines,” without a separate exit operator. Resource lifetimes through blocks resource-lifetimes-through-blocks In C++, RAII is the usual approach to resource management: an owning object acquires a resource when constructed and releases it in its destructor when it leaves scope. This model of owning objects is less typical in daslang : explicit blocks and deferred cleanup through defer are convenient ways to define the lifetimes of external resources. The language has finalizers and inscope , but a pointer to an SDL object alone does not define its ownership or cleanup rules. Creating a window or texture is only half the job: the resource must be released, including on an early return caused by an error. The with functions pass a resource to a block and release it when the block finishes. sdl scope and sdl use let you write several nested blocks as a linear sequence: This example draws one frame; an application needs an event and rendering loop inside the resource lifetime. When the block ends, the renderer is released first, then the window, and finally SDL is shut down. If renderer creation or drawing fails, resources that have already been created are also released. The sdl use macro moves the rest of the block into the callback of the corresponding with function. The pointers remain borrowed: they can be used inside that scope, but must not be saved for later use or released manually. Resource lifetimes follow the structure of the program; no separate resource collector is needed. For comparison, here is the same example without with and sdl use expand sdl try as well, and it looks almost like C . Each resource is created before entering its cleanup block. defer is moved to the finalization section of its entire block, so placing it after resource creation in the same block is not enough: cleanup could also run on an early return before creation succeeds. If renderer creation fails, the window and SDL are cleaned up. If drawing fails, all three resources are released in reverse order. with encapsulates these blocks and cleanup rules, while sdl use lets you use them without writing the nesting by hand. Events as a sequence events-as-a-sequence You can process the event queue with an ordinary loop: poll events is a lazy iterator: it retrieves one event at a time and stops when the queue is empty. If you leave the loop early, subsequent events remain queued. Instead of a raw SDL Event containing a C union, the code receives an SdlEvent , a variant type containing decoded event data. Strings and lists in that data belong to the resulting value, so the next poll will not overwrite them. Pattern matching on events pattern-matching-on-events The SdlEvent variant type can be inspected with match . Each branch receives the data for its corresponding event: Borrowed memory access borrowed-memory-access Pixel operations use another form of the same block idiom: the library temporarily provides access to texture memory. For example, let’s fill a 32 × 32 RGBA32 streaming texture with a gradient: with texture pixels rgba8 locks the texture while its block runs, and with row provides a borrowed array of pixels from one row. Here, marks temporary borrowed access: this data cannot be retained or passed out of the block. rgba8 packs the components into a single uint . The code operates directly on texture memory, while the library accounts for row pitch and unlocks the texture when the block finishes, including on an error return. The wrapper also defines the data type, avoiding unsafe access through void pointers. Different types for different resources different-types-for-different-resources An ordinary typedef shortens a type name without separating it from the original type. The checked GPU API needs genuinely different types: buffers, textures, and samplers must not accidentally replace each other. Their handles are therefore registered as distinct types. Their definitions are equivalent to the following; you should not redeclare them in your script: All three have the same machine representation, but the compiler treats them as different types. For example, vertex binding takes an array specifically of GpuBufferHandle : Passing a GpuTextureHandle in place of buffer is a compile-time error. At runtime, the checked API also validates the resource kind, whether it still exists, and which device it belongs to. A copied handle remains an alias to the same resource: it does not create separate ownership or extend its lifetime. These checks apply to the checked GPU API; direct SDL calls using native pointers retain their original contracts. Arrays instead of pointers and counts arrays-instead-of-pointers-and-counts Many C functions accept a data pointer and a separate element count. An array is more convenient for scripts because its size is already known. For example, let’s draw a triangle: The adapter passes the pointers and counts to SDL itself. Before the call, it checks index bounds, supported array sizes, and vertex values. Temporary state changes temporary-state-changes A block can also define how long a setting applies. For example, with render target saves the current render target, switches to a texture, and restores the previous target when the block finishes: Partial results together with status partial-results-together-with-status For IO, a Result<array<uint8 , SdlError may be insufficient: an operation might transfer some data and then fail. Therefore, read io and write io return IoTransfer , which stores the transferred byte count separately from the status: transferred is available even when status contains an error. Shader DSL shader-dsl Another feature is writing shaders in daslang . This uses the existing dasSpirv compiler: annotations mark shader functions, and the compiler generates SPIR-V and reflection metadata while compiling the script. The SDL layer uses those results to create GPU resources. The chain looks like this: annotated function → SPIR-V and reflection → resource layout validation → SDL GPU shader creation. The shader is compiled when the script is compiled, while the GPU object is created at runtime, once a device is available. Describing a shader describing-a-shader For example, here is a fragment shader that reads its color from a uniform block: @uniform describes data supplied to the shader by the application, while @out describes its output. The annotation produces two arrays: solid fragment : array<uint containing SPIR-V and solid fragment reflect : array<uint containing reflection. Reflection describes the shader stage and the resources it uses. The source function is named fragment main , but the generated SPIR-V entry point is named main . Creating an SDL GPU shader creating-an-sdl-gpu-shader Once a device is available, both arrays are passed to with gpu dsl shader . This fragment uses the definitions from the previous example: The wrapper reads reflection, validates the resources against SDL conventions, and fills in SDL GPUShaderCreateInfo : the stage and the number of uniform blocks and samplers. SPIR-V is converted from an array of words to an array of bytes and passed to the regular shader creation function. The resulting object’s lifetime is managed by the familiar with scope. Code and reflection must come from the same compilation. Reflection helps fill in creation parameters, but the application still controls compatibility between vertex and fragment shaders, data formats, and graphics pipeline configuration. You can also use precompiled shaders, skipping the compilation stage. Passing uniform structures passing-uniform-structures The Tint structure can also be used on the application side. However, its ordinary memory representation cannot be uploaded directly: the GPU expects std140 layout. A packing adapter handles this: The application’s structure must match the shader declaration: the wrapper does not determine the active shader from the command buffer. To pack repeatedly without allocating a new temporary buffer, use pack gpu dsl uniform with a reusable byte array. Compute and graphics backends compute-and-graphics-backends The same mechanism works for compute shaders: compute shader generates SPIR-V and reflection, and with gpu dsl compute pipeline creates an SDL compute pipeline, deriving workgroup dimensions and resource counts from reflection. For storage resources, the additional sdl shader access annotation records read and write access modes, while std430 adapters pack arrays of structures into storage buffers. The direct SPIR-V path is used for Vulkan. D3D12 has a separate SDL shadercross integration: with gpu dsl shader cross and with gpu dsl compute pipeline cross translate the same SPIR-V into the format required by the backend. This path requires shadercross and the corresponding compiler dependencies. Articles about shaders in SDL: https://moonside.games/posts/introducing-sdl-shadercross/ https://moonside.games/posts/introducing-sdl-shadercross/ https://moonside.games/posts/layers-all-the-way-down/ https://moonside.games/posts/layers-all-the-way-down/ Language and ecosystem integration language-and-ecosystem-integration JIT/AOT jit-aot daslang is more than a scripting language. On supported platforms, its JIT compilation modes often make interpreted code several times faster. Where JIT is unavailable, it can transpile code to C++. This is also supported and covered by tests to prevent regressions. Live mode live-mode The language also supports live reload. You can start an application with an empty window and keep adding functionality without restarting it. The mechanism is described in Running it live https://daslang.io/blog/running-it-live.html . In the SDL examples, the window, renderer, and ImGui context belong to the native host and survive script reloads. The live watch boost module watches for file changes and requests a reload after a save. Values annotated with @live are restored during incremental reloads; a full reload resets the script’s state. Examples on GitHub: - 01 widgets.das https://github.com/spiiin/dasSDL3/blob/main/examples/live/01 widgets.das — an SDL/ImGui application with automatic reload and control through stdin/stdout. - 02 widgets http.das https://github.com/spiiin/dasSDL3/blob/main/examples/live/02 widgets http.das — the same application controlled through a local HTTP API, with support for connecting an MCP client. - 03 widgets recording.das https://github.com/spiiin/dasSDL3/blob/main/examples/live/03 widgets recording.das — a version that records frames to APNG. A minimal live interface fragment: Tests and automated tutorials tests-and-automated-tutorials UI automation integrates with imgui playwright from daslang. It provides a scripting API for ImGui applications: widgets are addressed by names such as MAIN/INCREMENT , and you can take snapshots, click or drag, wait for a value to change, and request a reload. For example, after connecting app to the HTTP example, you can check that a click worked and its result survived a reload: The complete playwright widgets.das https://github.com/spiiin/dasSDL3/blob/main/examples/live/playwright widgets.das also drags a slider through synthetic mouse events and checks its value after a reload. The automated test https://github.com/spiiin/dasSDL3/blob/main/tests/test live mcp.py additionally compares UI pixels to verify changes in rendering. The same scenario can record a demonstration or tutorial. record widgets.das https://github.com/spiiin/dasSDL3/blob/main/examples/live/record widgets.das runs a sequence of actions inside with recording app : it pauses, moves a slider, clicks a button, and checks the result. The application captures frames through SDL, and dasStbImage writes them to APNG. On Windows, the build with recording support can be launched with one command from the repository root: This makes tutorial actions reproducible after UI changes. The scenario both describes the demonstration and checks that its actions produce the expected results. AI agents are good at using this interface. daspkg integration daspkg-integration The library can be installed as a ready-to-use package through daspkg https://daslang.io/daspkg.html , without generating bindings or building it yourself. The source distribution also includes generated bindings, so you do not need to bring in LLVM and Clang. Platforms and graphics backends platforms-and-graphics-backends The library has separate profiles for Windows, Linux, macOS, and the browser. Shared boost modules sit on top of bindings that account for each platform’s ABI and available functions. | Platform | Supported features | |---|---| | Windows x64 | Native MSVC build, interpreter and AOT; GPU examples for Vulkan and Direct3D 12. | | Linux | Core profile with GCC, interpreter and strict AOT; 2D examples on Ubuntu/WSL2 through WSLg. GPU rendering requires a working Vulkan device. | | macOS | Native Apple Clang build, Cocoa/Metal, interpreter and strict AOT; Metal tests include rendering and readback. | | Browser | Emscripten build targeting WebAssembly: SDL Renderer through WebGL, input and audio. There is also a separate standalone wasm32 AOT example. | Graphics uses two paths. SDL Renderer provides ready-made 2D operations for textures, rectangles, and geometry. SDL GPU gives you control over shaders, buffers, graphics pipelines, and compute pipelines. The browser profile uses Renderer/WebGL; the native SDL GPU examples have not yet been ported to it, and the pinned SDL version has no WebGPU backend. Shader format also matters for SDL GPU. Vulkan accepts SPIR-V, Direct3D 12 accepts DXIL, and Metal accepts MSL or Metallib. In the GPU examples, a single daslang source is compiled to SPIR-V: Vulkan uses it directly, while Direct3D 12 and Metal use SDL shadercross. The Direct3D 12 path also needs DXC. You can also supply precompiled shaders in the appropriate format. The backend can be selected through SDL GPU DRIVER : vulkan , direct3d12 , or metal . SDL can also be used with the separate Vulkan and OpenGL bindings available in daslang through dasVulkan and dasOpenGL. SDL then handles the window, input, and platform integration, while the application calls the graphics API directly. For OpenGL , create a window with SDL WINDOW OPENGL and a context through with gl context . Once the context is current, you can use require opengl and ordinary glViewport , glClear , drawing, and resource upload calls. Present the frame with SDL GL SwapWindow . There is a context creation example https://github.com/spiiin/dasSDL3/blob/main/examples/89 gl context.das and dasOpenGL rendering examples https://github.com/spiiin/dasSDL3/tree/main/examples/web/opengl , which use OpenGL ES/WebGL 2 in the browser. For Vulkan , SDL creates a window with SDL WINDOW VULKAN , reports the required instance extensions through vulkan instance extensions , and creates a window surface through with vulkan surface . The instance itself is created through Vulkan with those extensions enabled; devices, queues, swapchains, and rendering commands also remain the responsibility of Vulkan code. dasVulkan provides access to this API from daslang , while the SDL wrapper handles the platform-specific window and surface work. The extension query example https://github.com/spiiin/dasSDL3/blob/main/examples/90 vulkan extensions.das and Vulkan interop contracts https://github.com/spiiin/dasSDL3/blob/main/docs/vulkan-metal.md illustrate this boundary. This path requires a Vulkan module or a custom native host; the standard SDL runner does not include it by itself. Portability is checked through tests and GitHub CI https://github.com/spiiin/dasSDL3/tree/main/.github/workflows for Windows, Linux, and macOS. Build, API, and AOT checks are supplemented by separate graphics and browser test runs. Otherwise, updating or adding features would become a nightmare. Examples examples To test the API, I ported several BGFX examples; they also make a useful performance reference: bgfx examples ported to daslang and SDL GPU https://github.com/spiiin/dasSDL3/tree/main/examples/gpu . The shaders in these examples are also written in daslang . The latest port is Shadow volumes https://github.com/spiiin/dasSDL3/blob/main/examples/gpu/10 shadowvolumes.das : a scene with shadow volumes and several light sources. Here is a screenshot of the example running on the Vulkan backend: For the web version, I also made an NES emulator that runs in the browser: https://github.com/spiiin/dasNES https://github.com/spiiin/dasNES https://spiiin.github.io/dasNES/ https://spiiin.github.io/dasNES/