CSDL3

KO | EN

gitlite — search

#devops #git #golang #go #monitoring #data-science #shell #gemini #agents #graphql

(★ 9)

An Idomatic, object-oriented C# wrapper for SDL3 and its official satellite libraries

File Explorer

ZIP Download

- - ci.yml
  - publish.yml
- - AudioClip.cs
  - AudioConvert.cs
  - AudioDeviceBase.cs
  - AudioDevices.cs
  - AudioFormats.cs
  - AudioLoader.cs
  - AudioMixer.cs
  - AudioSpec.cs
  - AudioStream.cs
  - AudioStreamProperties.cs
  - Drivers.cs
  - PlaybackDevice.cs
  - PlaybackDeviceInfo.cs
  - RecordingDevice.cs
  - RecordingDeviceInfo.cs
- - Events.cs
- - ArrayExtensions.cs
  - CBoolExtensions.cs
  - Disposable.cs
  - FloatExtensions.cs
  - IntExtensions.cs
  - IntPtrExtensions.cs
  - LongExtensions.cs
  - NativePtrExtensions.cs
  - NullableExtensions.cs
  - UIntPtrExtensions.cs
- - GPUBuffer.cs
  - GPUColorTargetBlendState.cs
  - GPUCommandBuffer.cs
  - GPUComputePass.cs
  - GPUComputePipeline.cs
  - GPUCopyPass.cs
  - GPUDevice.cs
  - GPUDeviceInfo.cs
  - GPUDeviceProperties.cs
  - GPUFence.cs
  - GPUGraphicsPipeline.cs
  - GPURenderer.cs
  - GPURenderPass.cs
  - GPUSampler.cs
  - GPUShader.cs
  - GPUShaderCreateInfo.cs
  - GPUTexture.cs
  - GPUTextureFormatExtension.cs
  - GPUTransferBuffer.cs
- - Animation.cs
  - AnimationDecoder.cs
  - AnimationDecoderProperties.cs
  - AnimationEncoder.cs
  - AnimationEncoderProperties.cs
  - Image.cs
  - Image.DirectLoad.cs
  - ImageType.cs
  - Metadata.cs
- - InputConstants.cs
- - CallbackRegistry.cs
  - CBool.cs
  - Counter.cs
  - InvalidationRegistration.cs
  - NativeLibrary.cs
  - NativeStringArray.cs
- - Audio.cs
  - AudioDecoder.cs
  - AudioLoadProperties.cs
  - AudioProperties.cs
  - Group.cs
  - GroupProperties.cs
  - Mixer.cs
  - MixerProperties.cs
  - Track.cs
  - TrackProperties.cs
- - Address.cs
  - DatagramSocket.cs
  - Net.cs
  - ReceivedDatagram.cs
  - Server.cs
  - StreamSocket.cs
- - Android.cs
  - Apple.cs
  - CPUInfo.cs
  - DialogFileFilter.cs
  - FileDialog.cs
  - FileDialogProperties.cs
  - GUID.cs
  - Locales.cs
  - Memory.cs
  - MessageBox.cs
  - MessageBoxData.cs
  - Platform.cs
  - Platform.Device.cs
  - Platform.Id.cs
  - Platform.Misc.cs
  - Power.cs
  - Process.cs
  - ProcessCreateProperties.cs
  - ProcessProperties.cs
  - Rand.cs
  - SharedObject.cs
  - Tray.cs
  - TrayCreateProperties.cs
  - TrayEntry.cs
  - TrayMenu.cs
  - Windows.cs
- - DateTime.cs
  - FrameTimer.cs
  - Time.cs
  - Timer.Callbacks.cs
  - Timer.cs
  - Timer.CSDL_IMPL.cs
- - Font.cs
  - FontCreateProperties.cs
  - FontProperties.cs
  - GLAtlasDrawSequence.cs
  - GLTextEngine.cs
  - GLTextEngineCreateProperties.cs
  - GPUAtlasDrawSequence.cs
  - GPUTextEngine.cs
  - GPUTextEngineCreateProperties.cs
  - RendererTextEngine.cs
  - RendererTextEngineCreateProperties.cs
  - SurfaceTextEngine.cs
  - TextEngine.cs
  - TextObject.cs
  - TextObject.DrawData.cs
  - TextProperties.cs
  - TTF.cs
  - TTF.CSDL_IMPL.cs
- CSDL.csproj
- NativeHandle.cs
- NativePtr.cs
- - AudioSafetyTests.cs
  - MixerNativeTests.cs
- - CallbackLifetimeNativeTests.cs
  - FrameTimerTests.cs
  - HintCallbackNativeTests.cs
  - LogNativeTests.cs
  - SdlCoreNativeTests.cs
- - EventDispatchNativeTests.cs
- - FileNativeTests.cs
- - GPUConfigurationTests.cs
- - ImageNativeTests.cs
- - InputNativeTests.cs
- - NetNativeTests.cs
- - SdlFixture.cs
  - SdlVersionNumber.cs
- - TtfNativeTests.cs
- - RendererSafetyTests.cs
  - WindowRendererNativeTests.cs
- CSDL.Tests.csproj
- README.md
- - ExpandInheritDoc.csproj
  - Program.cs
- - GenericBenchmark.csproj
  - Program.cs
.editorconfig
.gitignore
CONTRIBUTING.md
CSDL.sln
LICENSE
logo.png
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**CSDL3 is an idiomatic, object-oriented C# wrapper for working with [SDL3](https://wiki.libsdl.org/SDL3/FrontPage),
making it easier to build cross-platform games and multimedia applications in .NET.**

[![NuGet](https://img.shields.io/nuget/v/CSDL3)](https://www.nuget.org/packages/CSDL3)
[![License: zlib](https://img.shields.io/badge/license-zlib-blue.svg)](https://raw.githubusercontent.com/Atompapst/CSDL3/main/LICENSE)
[![.NET](https://img.shields.io/badge/.NET-10-purple)](https://dotnet.microsoft.com)

> **Status**: SDL3 is essentially fully implemented across the high-level wrappers - this isn't a partial wrapper
> covering just a few subsystems. It hasn't been exhaustively tested yet though, so occasional bugs can still show
> up here and there. Issues and PRs are very welcome. Going forward, the primary focus is adding new convenience
> methods to the high-level wrappers.

## What's covered

CSDL wraps [SDL3](https://wiki.libsdl.org/SDL3/FrontPage) itself (video, audio, input, GPU, threads, file I/O, and
more), plus the official satellite libraries: [SDL_image](https://wiki.libsdl.org/SDL3_image/FrontPage),
[SDL_mixer](https://wiki.libsdl.org/SDL3_mixer/FrontPage), [SDL_ttf](https://wiki.libsdl.org/SDL3_ttf/FrontPage), and
[SDL_net](https://wiki.libsdl.org/SDL3_net/FrontPage).

[SDL_shadercross](https://github.com/libsdl-org/SDL_shadercross) is not covered yet - because there's no SDL wiki
documentation for it for now.

## Requirements

- **.NET 10.0**
- **SDL3 runtime** available on your system

## Compatibility

CI builds and tests on a self-hosted Linux runner. Before testing, it fast-forwards the local source checkouts for SDL,
SDL_image, SDL_mixer, SDL_net, and SDL_ttf, then builds and installs them into a job-local prefix. The workflows are the
source of truth for the validated native runtime setup.

## Getting Started

### 1. Installation

```bash
dotnet add package CSDL3
```

### 2. Get the SDL3 Native Libraries

**⚠️ Important**: CSDL3 is bindings only - it does not ship with native SDL3 binaries. You need to obtain them
separately and place them where your app can find them.

#### Recommended approach:

Use prebuilt native packages from [edwardgushchin/SDL3-CS](https://github.com/edwardgushchin/SDL3-CS) for SDL3,
SDL_image, SDL_mixer, and SDL_ttf:

```bash
dotnet add package SDL3-CS.Linux
dotnet add package SDL3-CS.Linux.Image
dotnet add package SDL3-CS.Linux.Mixer
dotnet add package SDL3-CS.Linux.TTF
```

Replace `Linux` with `Windows` or `macOS` for those platforms. Install SDL_net separately from
its [official releases](https://github.com/libsdl-org/SDL_net/releases).

#### Manual approach:

Download binaries directly from:

- [SDL3 releases](https://github.com/libsdl-org/SDL/releases/latest) - grab `SDL3.dll`/`.so`/`.dylib`
- [SDL_image releases](https://github.com/libsdl-org/SDL_image/releases/latest)
- [SDL_mixer releases](https://github.com/libsdl-org/SDL_mixer/releases/latest)
- [SDL_ttf releases](https://github.com/libsdl-org/SDL_ttf/releases/latest)
- [SDL_net releases](https://github.com/libsdl-org/SDL_net/releases/latest) (if needed)

Place the `.dll`/`.so`/`.dylib` files next to your executable.

### 3. Quick Start

Choose your preferred approach:

#### Option A: Manual Event Loop

```csharp
using CSDL;
using CSDL.Input;
using CSDL.Video;

namespace CSDL3.Example {
    public static class Program {
        public static void Main(string[] args) {
            Init.RunOnMainThread(Run, $"Everything works on {Platform.Name}!", true);
            Init.Quit(); // important!!!
        }

private static void Run(object userdata) {
            // Performs automatically when specific resources accessed
            //if (!Init.Initialize(InitFlags.Video | InitFlags.Events)) throw; 
            
            //Log.UseCustomOutput();
            //Log.CategoryPriority.SetForAll(LogPriority.Debug);
            
            using (var window = new Window("My Application", 800, 600)) {
                using (var renderer = new Renderer(window)) {
                    string text = (string)userdata;
                    // ClearColor Applied when Clear() is called; adjust to your liking
                    renderer.ClearColor = Color.Random();

// Window queries must stay on the main thread, so cache the size once and
                    // hand it to the timer callback instead of touching `window` from its thread.
                    Point windowSize = window.Size;
                    int textX = CSDL.Rand.Global.Next(50, windowSize.X / 2);
                    int textY = CSDL.Rand.Global.Next(10, windowSize.Y / 2);

// CSDL.Timer + CSDL.Rand together: jump the text to a new random spot once a second
                    using (var repositionTimer = new CSDL.Timer(CSDL.Timer.MsPerSecond, (object ud, TimerID id, uint interval) => {
                        textX = CSDL.Rand.Global.Next(50, windowSize.X / 2);
                        textY = CSDL.Rand.Global.Next(10, windowSize.Y / 2);
                        return interval; // returning the interval keeps the timer repeating
                    })) {
                        bool running = true;
                        while (running) {
                            Events.PollAll();
                            if (Events.Common.QuitRequested()) running = false;
                            if (Events.Keyboard.IsDown(Scancode.Escape)) running = false;

renderer.Clear();
                            renderer.DrawColor = Color.Red;
                            renderer.RenderDebugText(textX, textY, text);
                            renderer.Present();
                            CSDL.Timer.Delay(10);
                        }
                    }
                }
            }
        }
    }
}
```

#### Option B: Game Lifecycle

Derive from `Game` and let SDL's native main-callback mechanism (`SDL_MAIN_USE_CALLBACKS`) handle your event loop:

```csharp
using CSDL;

public sealed class MyGame : CSDL.Game {
    protected override AppResult OnInit(string[] args) {
        // create your window/renderer here
        return AppResult.Continue;
    }

protected override AppResult OnIterate() {
        // one frame of your game loop
        return AppResult.Continue;
    }

protected override AppResult OnEvent(ref Event @event) {
        return AppResult.Continue;
    }

protected override void OnQuit(AppResult result) {
        // dispose your resources here
    }
}

public static class Program {
    public static int Main() => new MyGame().Run();
}
```

Use `Game<TState>` if you'd prefer to keep your app's state in an explicit object rather than `this`.

## How the Bindings Are Generated

The low-level `_Generated` layer underneath the hand-written wrapper classes is produced by a private code generator
(not part of this repo) that reads the [SDL wiki](https://github.com/libsdl-org/sdlwiki) directly. Function signatures,
structs, enums, and documentation all come from there automatically.

### Properties

Properties are handled specially since the SDL wiki doesn't document them well. They're derived from reading the actual
SDL source code, parsing the surrounding syntax, and inferring return values from context.

## Managed Implementations (`CSDL_IMPL`)

A small number of tiny, frequently called SDL helpers are reimplemented directly in managed C# instead of calling
through P/Invoke, because the native transition overhead can exceed the actual work done.

Each managed port is marked with a `CSDL_IMPL` region and tracked against the SDL source it mirrors, so it gets
flagged for review once the SDL side changes. Live tracking status: [csdl.spieleins.de](https://csdl.spieleins.de/?lang=en).
See [CONTRIBUTING.md](CONTRIBUTING.md) for the region format and the full guide on adding or updating a managed port.

## Contributing

Issues and PRs are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, including the `CSDL_IMPL`
convention for managed SDL ports.

## License

Licensed under the [zlib License](LICENSE).

CSDL3

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README