55 lines
3 KiB
Markdown
55 lines
3 KiB
Markdown
# 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?
|
|
|
|
See `build.zig.zon`, at the time of writing it's a recent commit on the docking branch. See Dear ImGui's readme for info on Dear ImGui branches.
|
|
|
|
## 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 Vulkan backend: `dear_imgui_vulkan`.
|
|
|
|
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 change versions
|
|
|
|
Update `build.zig.zon`, and then if the headers changed, regenerate them into `src/cached` with [dear_bindings](https://github.com/dearimgui/dear_bindings).
|
|
|
|
Building `cimgui.h` is explained in their README, here'd how to build a backend. You can also see the command format in their `bindings.bat` file.
|
|
|
|
```sh
|
|
python3 dear_bindings.py --backend --imconfig-path ~/Documents/imgui/imconfig.h -o cimgui_internal ~/Documents/imgui/imgui_internal.h
|
|
```
|
|
|
|
If `generator.zig` fails, you may need to add missing values to the enumeration. `std.json` does not provide helpful errors 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.
|
|
|
|
## 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
|