# Dear ImGui Zig

A Zig interface for [Dear ImGui](https://github.com/ocornut/imgui).

Generated at build time from the JSON generated by [dear_bindings](https://github.com/dearimgui/dear_bindings).

## Which version of Dear ImGui is built?

The docking branch, for the exact version see [build.zig.con](/build.zig.zon). See Dear ImGui's [readme](https://github.com/ocornut/imgui) for info on the various Dear ImGui branches.

## Which version of Zig is targeted?

See [build.zig.con](/build.zig.zon). For previous Zig versions, see [releases](https://github.com/Games-by-Mason/dear_imgui_zig/releases).

## How to use Dear ImGui

Import the `dear_imgui` module provided by this package. It exports Dear ImGui types and functions, converted to standard Zig syntax. You can always check the generated file if you are unsure how the names map, but it should be fairly straightforward.

## How to build Dear ImGui extensions

The static library for Dear ImGui, and supported backends, are provided as artifacts under the same name as the Zig modules. You can link Dear Imgui extensions to these.

## How to use the backends

Right now, this package only exports the following backends:

- `dear_imgui_vulkan`
- `dear_imgui_sdl3`

Contributions are welcome if you'd like to add others. The process should be fairly straightforward.

## How it works

`dear_bindings` generates a C wrapper for Dear ImGui, and a JSON file detailing the declarations.

The results of executing `dear_bindings` are cached in `src/cached` to avoid a Python dependency
(`dear_bindings` is implemented in Python.)

At build time, `generate.zig` is called on the relevant JSON files to generate a Zig module that links to the wrapper generated by `dear_bindings`.

`dear_bindings` does not provide enough data to generate perfect pointer types for all situations, but a reasonable conservative heuristic is used to avoid `[*c]` where possible. This could be improved in the future through whitelists.

## How to update Dear ImGUI

Note that you never need to do this as a user of the library, unless you're making a PR that upgrades this library to a new Dear ImGUI version.

1. Update `build.zig.zon`
2. Add `python3` to your path
3. Set `$DEAR_BINDINGS` to a path to an appropriate version of [dear_bindings](https://github.com/dearimgui/dear_bindings) for the version of Dear ImGUI you're updating to
4. Run `zig build dear_bindings`. Output may need tweaks, glance over diff.
5. Run `zig build generate -- ...` to see if the generator still works. If it fails, you're probably missing values in an enumeration, `std.json` does not provide helper errors for this at the time of writing, the easiest way to debug this is to comment out the actual generation code, and all fields in `Header`, adding them back until you figure out which are causing the issue.
6. Test the bindings from a real Zig program that imports Dear ImGUI.

## Known differences

- doesn't build `binary_to_compressed_c`
- doesn't build `misc/cpp/imgui_stdlib.cpp`
- freetype mode not supported (but easily could be)
- only the vulkan backend is provided as of now (but others are easy to add)
- the Vulkan backend assumes `IMGUI_IMPL_VULKAN_NO_PROTOTYPES`
- the Vulkan backend assumes dynamic rendering is available (>= `VK_VERSION_1_3` or `VK_KHR_dynamic_rendering`)
  - we could add support for this conditional, but it seems unlikely to get much use