4 releases
0.1.3 | Jan 12, 2019 |
---|---|
0.1.2 | Jan 5, 2019 |
0.1.1 | Jan 5, 2019 |
0.1.0 | Jan 5, 2019 |
#858 in GUI
1.5MB
24K
SLoC
nsf-imgui
Rust bindings for Dear ImGui 1.66b. Experimental personal project, created due to the following reasons:
- Wanted to learn rust.
- Mildly interested in game development.
- Wasn't entirely happy with existing bindings.
Goals
- Generate most of FFI bindings automatically (helps with maintenance) using cimgui data files.
- Generate most of native wrappers automatically as well.
- Native wrappers should not be focused too much on safety, instead provide some level of convenience when it comes to types (refs to pointers, string management, etc.).
- Closely follow original C++ API, hence avoid being paranoid about safety. E.g. as long as original lib allows you to break things with mismatched begin()/end() calls, allow that as well.
Implementation details
- A lot of code is generated using
generate.js
script. Generation is triggered manually, the repository includes generated files. To run this script you will need to install npm packages vianpm install
. In addition togenerate.js
script, seegen.bash
script to understand how files are being generated. - Unsafe part uses "bitflags" crate to implement enums which act as bit flags.
- Safe part is currently very limited. Only functions that are considered safe are being wrapped. E.g. ones which don't contain function pointers or
void*
or things like that. const char*
arguments become&CStr
, there is also customcstr!
macro to help building those at compile-time.const char*
return values are converted intoString
. Other types are propagated as-is,*mut
becomes&mut
,*const
becomes&
.- "Format" portion of the function arguments that normally consists of a format string and arguments is converted to a single string argument. Which is then passed in as
"%s"
. - Custom
cstr!
macro supports formatting, e.g.cstr!("{}", myint)
. This variant usesformat!
macro underneath, which allocates a String. - All imgui functions are methods of
ImGui
struct. You can create one withImGui::new()
. Only one instance of this struct is allowed (protected via static mutex). Although the struct is Clone, Rc inside.ImGui::new()
function will calligCreateContext()
. When lastImGui
instance is dropped, it will calligDestroyContext(igGetCurrentContext())
. - Original library uses C types, such as int, unsigned int, float, double, size_t. I assume those are i32, u32, f32, f64, usize and so on. Basically implying they have fixed sizes. While it's not true in theory, in many cases it's true in practice. It will work for typical 64 bit desktop setups, it might not work for some esoteric embedded scenarios in case if you want to use imgui there.
- Original library is written in C++, which allows specifying default values for trailing function arguments. It's implemented using generic
impl Into<Option<>>
types. Sadly, references within those types require explicit lifetimes for some reason, hence I have to generate explicit lifetimes for all ref types in a function signature.
Q & A
Q: Where are the examples?
A: There are none. The goal for this lib is to stay as close as possible to C++ API, you can refer to original C++ examples. There are no safe wrappers around structs yet, hence if you want to integrate this lib into your renderer, you'll just fetch ImDrawData using FFI API and do it in a fully "unsafe" manner, just like you would do it in C++.
Q: Do you plan to maintain this library?
A: It depends. Currently I'm using it in my personal hobby gamedevy project. As long as I keep working on it, this library probably will be maintained to some degree. Then - who knows. Don't expect it to be well maintained.
Changelog
nsf-imgui
- 0.1.3
- Implement
input_text
usingString
. - Fix
cstr!
macro again, now for sure. - Fix snake case conversion on
color_convert_hsv_to_rgb
andcolor_convert_rgb_to_hsv
functions. - Blacklist
igTextUnformatted
.
- Implement
- 0.1.2 Implement default function values using
impl Into<Option<>>
generic parameters. - 0.1.1 Fix
cstr!
macro variant with arguments. - 0.1.0 Initial release.
nsf-imgui-raw
- 0.1.0 Initial release.