# dear-imgui-sdl3

SDL3 platform backend (with optional OpenGL3 renderer) for the `dear-imgui-rs`
crate. This wraps the official Dear ImGui C++ backends:

- `imgui_impl_sdl3.cpp` (platform layer)
- `imgui_impl_opengl3.cpp` (OpenGL3 renderer)

and exposes a small, Rust-friendly API that plugs into an existing
`dear-imgui-rs::Context`.

Typical use cases:

- Drive Dear ImGui input from an SDL3 window (keyboard/mouse/gamepad/IME).
- Render Dear ImGui via the official OpenGL3 backend.
- Use SDL3 only for the platform layer together with a Rust renderer
  (e.g. `dear-imgui-glow` or `dear-imgui-wgpu`).

## Notes

- This crate assumes a single Dear ImGui context and a single SDL3 event pump. The upstream
  SDL3 backend notes that multi-context usage is not well tested and may be dysfunctional.
- The vendored SDL3 backend sources currently include a few compatibility branches for
  older SDL 3.x preview APIs; these will be removed as upstream APIs stabilize.

## Features

- `opengl3-renderer`: builds and exposes the official C++ OpenGL3 renderer backend.
- `multi-viewport`: enables multi-viewport helpers (requires `dear-imgui-rs/multi-viewport`).

Platform-only usage (SDL3 + WGPU/Glow, no official OpenGL3 renderer):

```toml
dear-imgui-sdl3 = { version = "0.10", default-features = false }
```

Enable the official OpenGL3 renderer:

```toml
dear-imgui-sdl3 = { version = "0.10", features = ["opengl3-renderer"] }
```

## Compatibility

| Item          | Version  |
|---------------|----------|
| Crate         | 0.10.x   |
| dear-imgui-rs | 0.10.x   |
| SDL3 crate    | 0.17     |
| sdl3-sys      | 0.6      |

See also: [docs/COMPATIBILITY.md](https://github.com/Latias94/dear-imgui-rs/blob/main/docs/COMPATIBILITY.md)
for the full workspace matrix.

## Quick Start

Minimal SDL3 + OpenGL3 flow (single window):

```rust,no_run
use dear_imgui_rs::{Context, Condition};
use dear_imgui_sdl3::{
    enable_native_ime_ui, init_for_opengl, new_frame, render, sdl3_poll_event_ll,
    process_sys_event,
};
use sdl3::{video::GLProfile, EventPump};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // SDL3 initialization (simplified)
    let sdl = sdl3::init()?;
    let video = sdl.video()?;

    // Recommended on IME-heavy platforms (Windows/Asia locales)
    enable_native_ime_ui();

    // Configure GL context attributes
    {
        let gl_attr = video.gl_attr();
        gl_attr.set_context_profile(GLProfile::Core);
        gl_attr.set_context_version(3, 3);
    }

    let window = video
        .window("Dear ImGui + SDL3 + OpenGL", 1280, 720)
        .opengl()
        .resizable()
        .build()?;
    let gl_context = window.gl_create_context()?;
    window.gl_make_current(&gl_context)?;

    // ImGui context
    let mut imgui = Context::create();

    // Initialize SDL3 + OpenGL3 backends
    init_for_opengl(&mut imgui, &window, &gl_context, "#version 150")?;

    let mut event_pump: EventPump = sdl.event_pump()?;
    'main: loop {
        // 1) Poll SDL3 events and feed ImGui
        while let Some(event) = sdl3_poll_event_ll() {
            if process_sys_event(&event) {
                // ImGui consumed the event; continue if you do not need it.
            }

            // Handle your own events or quit logic as needed...
        }

        // 2) Start a new frame for the SDL3 + OpenGL backends
        new_frame(&mut imgui);
        let ui = imgui.frame();

        // 3) Build UI
        ui.window("Hello")
            .size([400.0, 300.0], Condition::FirstUseEver)
            .build(|| {
                ui.text("ImGui + SDL3 + OpenGL3");
            });

        // 4) Render via OpenGL backend
        let draw_data = imgui.render();
        unsafe {
            use sdl3::video::Window;
            use sdl3::video::GLContext;
            // Make context current if needed, clear framebuffer, etc.
            // window.gl_make_current(&gl_context)?;
        }
        render(&draw_data);
        window.gl_swap_window();
    }
}
```

APIs of interest (see `src/lib.rs` for full docs):

- `init_for_opengl(&mut Context, &Window, &GLContext, &str)`:
  initialize SDL3 platform + OpenGL3 renderer.
- `init_for_opengl_default(&mut Context, &Window, &GLContext)`:
  initialize SDL3 platform + OpenGL3 renderer using the upstream default GLSL version.
- `init_platform_for_opengl(&mut Context, &Window, &GLContext)`:
  initialize only the platform backend (for use with Rust OpenGL renderers).
- `init_for_other(&mut Context, &Window)`:
  initialize only the platform backend (for use with WGPU or other APIs).
- `init_for_vulkan(&mut Context, &Window)` / `init_for_metal(&mut Context, &Window)` /
  `init_for_d3d(&mut Context, &Window)` / `init_for_sdl_gpu(&mut Context, &Window)`:
  initialize the SDL3 platform backend for specific renderer families (use `init_for_vulkan` for Vulkan multi-viewport support).
- `unsafe init_for_sdl_renderer(&mut Context, &Window, *mut SDL_Renderer)`:
  initialize SDL3 platform backend for SDL_Renderer-based renderers.
- `shutdown_for_opengl(&mut Context)` / `shutdown(&mut Context)`:
  shut down the backends before destroying the ImGui context or window.
- `new_frame(&mut Context)`:
  begin a frame for SDL3 + OpenGL3.
- `sdl3_new_frame(&mut Context)`:
  begin a frame for SDL3 platform only.
- `sdl3_poll_event_ll() -> Option<SDL_Event>` and
  `process_sys_event(&SDL_Event) -> bool`:
  low-level event polling/processing helpers.
- `render(&DrawData)`:
  render Dear ImGui draw data via the OpenGL3 backend.
- `update_texture(&mut TextureData)`:
  advanced helper that delegates texture updates to `ImGui_ImplOpenGL3_UpdateTexture`.
- `create_device_objects()` / `destroy_device_objects()`:
  advanced OpenGL3 helpers mirroring upstream device object management.

## SDL3 & Build Requirements

The crate depends on:

- `sdl3` and `sdl3-sys` for SDL3 bindings.
- A system SDL3 installation **or** a build-from-source configuration (OS-dependent).

Build behavior is aligned with `Cargo.toml`:

- **Linux / Windows**
  - The `sdl3` dependency is configured with `features = ["build-from-source"]`.
  - This means SDL3 is downloaded and built via CMake and does **not** require
    a pre-installed system SDL3 library.
  - You still need a working C toolchain (compiler, linker, CMake).

- **macOS**
  - The crate expects a system SDL3 install (for example via Homebrew):
    - `brew install sdl3`
  - SDL3 headers are typically found under:
    - `/opt/homebrew/include/SDL3/SDL.h` (Apple Silicon)
    - `/usr/local/include/SDL3/SDL.h` (Intel / custom setups)
  - Linking parameters are handled by `sdl3-sys` / `sdl3`; this crate only
    needs the headers to build the C++ backend sources.

### Header Search Order and `SDL3_INCLUDE_DIR`

For cases where a system SDL3 is used, `build.rs` locates the headers in the
following order:

1. `SDL3_INCLUDE_DIR` environment variable (highest priority).
2. `pkg-config sdl3` (if available).
3. A small set of common default paths (e.g. `/opt/homebrew/include`,
   `/usr/local/include`, `/opt/local/include`).

**1. Explicit `SDL3_INCLUDE_DIR`**

Set this when SDL3 is installed in a non-standard location:

- macOS (custom Homebrew prefix):

  ```bash
  export SDL3_INCLUDE_DIR=/opt/homebrew/include
  ```

- Linux (hand-built SDL3):

  ```bash
  export SDL3_INCLUDE_DIR=/opt/sdl3/include
  ```

- Windows (PowerShell, headers under `C:\libs\SDL3\include`):

  ```powershell
  $env:SDL3_INCLUDE_DIR="C:\libs\SDL3\include"
  ```

`build.rs` adds this directory to the C/C++ include path and expects to find
`SDL3/SDL.h` under it.

**2. `pkg-config sdl3`**

If `SDL3_INCLUDE_DIR` is not set, the build script tries:

```bash
pkg-config --cflags sdl3
```

On success, the reported `include_paths` are added to the compiler flags. This
is the preferred route for most Linux distributions and pkg-config-enabled
macOS setups.

**3. Fallback paths**

If both the environment variable and pkg-config checks fail, `build.rs` tries
a few common include roots (such as Homebrew / MacPorts locations) and looks
for `SDL3/SDL.h` there.

### When Headers Cannot Be Found

If the build script cannot locate SDL3 headers, it will panic with a message
similar to:

> dear-imgui-sdl3: could not find SDL3 headers. \
> Install SDL3 development files (e.g. `brew install sdl3`) \
> or set SDL3_INCLUDE_DIR to the SDL3 include path.

To fix this:

1. Install SDL3 development packages and verify `pkg-config sdl3` works, **or**
2. Set `SDL3_INCLUDE_DIR` to the correct include root.

## IME and Gamepad Configuration

The underlying SDL3 ImGui backend supports IME and gamepad input. This crate
exposes a couple of small helpers to configure them.

### IME UI

On platforms with heavy IME usage (e.g. Chinese/Japanese/Korean locales), it is
recommended to enable the native IME UI before creating any SDL3 windows:

```rust
// Call this before creating SDL3 windows.
dear_imgui_sdl3::enable_native_ime_ui();
```

This is a convenience wrapper over `SDL_HINT_IME_SHOW_UI`, and failures are
treated as non-fatal.

### Gamepad Mode

By default, the SDL3 backend opens the first available gamepad and feeds its
state into Dear ImGui (the upstream default behavior).

You can switch to a mode where **all** detected gamepads are opened and merged:

```rust
use dear_imgui_sdl3::{set_gamepad_mode, GamepadMode};

// After init_for_opengl/init_for_other/init_platform_for_opengl:
set_gamepad_mode(GamepadMode::AutoAll);
```

This is useful for local multiplayer setups or testing environments.

For advanced use cases, you can also opt into **manual** gamepad selection by
providing raw `SDL_Gamepad*` handles opened by your application:

```rust
// Safety: gamepads must be valid, opened SDL_Gamepad pointers.
unsafe {
    dear_imgui_sdl3::set_gamepad_mode_manual(&[gamepad1, gamepad2]);
}
```

## Examples

The workspace includes several examples that use this backend:

Multi-viewport status on SDL3:

- **SDL3 + OpenGL3**: multi-viewport is provided by the upstream C++ backends and
  considered stable for desktop use.
- **SDL3 + Glow**: multi-viewport is experimental but functional on native targets.
- **SDL3 + WGPU**: multi-viewport is experimental on native targets; WebGPU/wasm is
  single-window to match upstream `imgui_impl_wgpu`.

- SDL3 + OpenGL3, multi-viewport:

  ```bash
  cargo run -p dear-imgui-examples --bin sdl3_opengl_multi_viewport --features "multi-viewport sdl3-opengl3"
  ```

- SDL3 + OpenGL3, multi-viewport (Glow renderer wrapper):

  ```bash
  cargo run -p dear-imgui-examples --bin sdl3_glow_multi_viewport --features "multi-viewport sdl3-platform"
  ```

- SDL3 + WGPU, single-window:

  ```bash
  cargo run -p dear-imgui-examples --bin sdl3_wgpu --features sdl3-platform
  ```

- SDL3 + WGPU, multi-viewport (experimental, native only):

  ```bash
  cargo run -p dear-imgui-examples --bin sdl3_wgpu_multi_viewport --features sdl3-wgpu-multi-viewport
  ```

Note: WGPU multi-viewport support is experimental and only available on native targets
via `dear-imgui-wgpu/multi-viewport-sdl3`. WebGPU/wasm remains single-window to match
upstream `imgui_impl_wgpu`.
