Rust bindings for Dear ImGui

Last update: Jan 7, 2023

Related tags

Overview

imgui-rs: Rust bindings for Dear ImGui

(Recently under new maintenance, things subject to change)

ui.window("Hello world")
    .size([300.0, 100.0], Condition::FirstUseEver)
    .build(|| {
        ui.text("Hello world!");
        ui.text("こんにちは世界！");
        ui.text("This...is...imgui-rs!");
        ui.separator();
        let mouse_pos = ui.io().mouse_pos;
        ui.text(format!(
            "Mouse Position: ({:.1},{:.1})",
            mouse_pos[0], mouse_pos[1]
        ));
    });

Main library crates

imgui: High-level safe API
imgui-winit-support: Backend platform implementation that uses the winit crate (latest by default, but earlier versions are supported via feature flags)
imgui-glow-renderer: Renderer implementation that uses the glow crate
imgui-glium-renderer: Renderer implementation that uses the glium crate
imgui-sys: Low-level unsafe API (automatically generated)

Additionally, the following are no longer maintained, but might work still:

imgui-gfx-renderer: Renderer implementation that uses the gfx crate (not the new gfx-hal crate). This can be found at imgui-rs/imgui-gfx-renderer

Features

Bindings for Dear ImGui that can be used with safe Rust. Note: API coverage is not 100%, but will keep improving over time.
Builder structs for use cases where the original C++ library uses optional function parameters
Easy integration with glow/ glium
Easy integration with winit (backend platform)
Optional support for the freetype font rasterizer

Minimum Support Rust Version (MSRV)

The MSRV for imgui-rs and all of the backend crates is 1.54. We update our MSRV periodically, and issue a minor bump for it.

Choosing a backend platform and a renderer

Almost every application that uses imgui-rs needs two additional components in addition to the main imgui crate: a backend platform, and a renderer.

imgui-rs is not tied to any particular renderer or platform.

The backend platform is responsible for integrating imgui-rs with the operating system and its window management. Its responsibilities include the following:

Handling input events (e.g. keyboard, mouse) and updating imgui-rs state accordingly
Passing information about the OS window (e.g. size, DPI factor) to imgui-rs
Updating the OS-side mouse cursor when imgui-rs requests it

The renderer is responsible for taking generic, renderer-agnostic draw lists generated by imgui-rs, and rendering them using some graphics API. Its responsibilities include the following:

Rendering using vertex/index buffers and command lists
Handling of DPI factors and scissor rects
Texture management

We provide the following renderers as an official source (ie, they will always be up to date and working): imgui-glow-renderer and imgui-glium-renderer.

Additionally, we provide the following backends as an official source (ie, they will always be up to date and working): imgui-winit-support and imgui-sdl2-support.

The most tested platform/renderer combination is imgui-glium-renderer + glium + imgui-winit-support + winit, but this is not the only possible combination. There's also imgui-glow-renderer, which will increasingly replace glium.

Additionally, there are other libraries which provide other kinds of renderers, which may be out of date with imgui-rs releases, but might work well for your use case:

You can also write your own support code if you have a more advanced use case, because imgui-rs is not tied to any specific graphics / OS API.

Compiling and running the demos

git clone https://github.com/imgui-rs/imgui-rs
cd imgui-rs

Main examples are located in the imgui-examples directory. These can be run like so:

# At the reposity root
cargo test

cargo run --example hello_world
cargo run --example test_window
cargo run --example test_window_impl

Examples for the Glow renderer are under the imgui-glow-renderer/examples/ directory. These can be run the same way as any other examples:

cargo test

cargo run --example glow_01_basic

Note to Windows users: You will need to use the MSVC ABI version of the Rust compiler along with its associated dependencies to build this libary and run the examples.

How to contribute

Change or add something
Make sure you're using the latest stable Rust
Run rustfmt to guarantee code style conformance
```
rustup component add rustfmt
cargo fmt
```
Open a pull request in Github

License

Licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Uses Dear ImGui and cimgui.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Comments

Update cimgui to 1.53.1

Update cimgui, fixing #97 and #88.

As a side note, the previous version has some compiler warning showing up during build:

warning: third-party/cimgui/imgui/imgui.cpp: In function ‘void ImGui::RenderTriangle(ImVec2, ImGuiDir, float)’:
warning: third-party/cimgui/imgui/imgui.cpp:3136:11: warning: this statement may fall through [-Wimplicit-fallthrough=]
warning:          r = -r; // ...fall through, no break!
warning:          ~~^~~~

The new version has no warning.

opened by malikolivier 26

glow renderer

Apologies if this is a bit over-complicated, it got away from me a bit. However, the vast majority of the OpenGL logic is based on the upstream example, so I hope it is mostly correct.

Where it differs are in three traits (ContextStateManager, ShaderProvider, and TextureMap) which users can implement to customise how the renderer behaves. It also supports either owning the OpenGL context, or borrowing it when needed. But, as the 01_basic.rs example shows, basic usage remains simple.

Hopefully the examples and code are relatively self-explanatory. I started writing docs, but then I got a compiler crash while running cargo doc, so I just sort of stopped.

Happy to change/fix as needed. Any testing would be great -- I've only tested on Linux with nvidia drivers.

opened by jmaargh 24
Wraps the dear ImGui custom drawing API
This is an attempt at wrapping ImGui's custom drawing API.

The custom rendering example provided with ImGui has been completely implemented. The result is as below:

Each patch should be self-explanatory and can be reviewed separately.

This collection of patches can be split into 4 sections.

Implementation of window_draw_list.rs, the API itself

Add a few helper methods in Ui. These functions will be used for the examples.

Add show_example_app_custom_rendering in test_window_impl

Add another example test_drawing_channels_split, showing how channels_split can be used. => The example can be removed from this PR if you do not like it.

This is an improvement over #102. With support for safe use of channels_split and generics to allow a more convenient use of the API.
opened by malikolivier 17
Add `DrawListMut::add_image` etc
Exposed a few DrawList methods related to drawing images, they are quite useful for things like making custom controls (using ImageButton makes it

I personally only needed add_image but added the quad and rounded ones for completeness (well completeness plus the wavy Lenna button is quite entertaining)

There's a few things I questioned about these new bindings:

Could they be combined into one struct - my decision was nope, as you can't add rounded corners to add_image_quad (so some of the builder arguments would be mutually exclusive). Could have combined Image and ImageRounded and left ImageQuad separate, but it seemed neater just to keep each separate

There is already an Image struct at src/widgets/image.rs (Image as in ImageButton). I couldn't think of a good alternative name for these without being inconsistent with the other similar builders in draw_list.rs so I left it as-is

ImDrawCornerFlags is in crate::legacy` - is this okay? It felt slightly odd using something in a legacy folder to implement some new functionality!
opened by dbr 16
Discussion: maintainer change
I've decided to stop maintaining imgui-rs, because honestly it feels like 100% chore at this point without any fun. The ratio used to be a bit different earlier when there were interesting technical challenges :slightly_smiling_face: but now many of those are solved and I mostly face annoying technical challenges caused by choices I can't influence, and I keep having to spend time trying to defend the choices I have made.

Simply put, there's so many other projects I'd much rather spend time on...I've never been especially passionate about user interfaces since my own needs are very simple and I don't think Dear ImGui is that great from a Rust perspective, no matter if it's wrapped by current imgui-rs implementation, or some hypothetical better alternative wrapper.

From a practical point of view, I think the repo needs to be moved under some organization and I need to give crates.io release rights to somebody. What happens after that is 100% up to the next maintainer(s) :smile: personally I will be probably switching to egui in the few projects that currently use imgui-rs

Let's discuss here who wants to be the new maintainer(s)!

If you'd like to maintain imgui-rs, please answer the following three questions. This is not a "job interview" and there's no strict requirements, but I'd like to have some idea who I'm passing the torch to :slightly_smiling_face:

Why do you want to maintain imgui-rs?

Maybe you have some grand plans for imgui-rs? Or maybe you currently use it and just want it to be actively maintained? It would be nice to know why you're interested. I have never been very passionate about imgui-rs and have managed to maintain it for years, but some passion probably helps if you want to be a good maintainer.

Do you currently use imgui-rs?

It's not a strict requirement, but I think it's so much better if you use the thing you maintain, so I'd like to know if you use imgui-rs and how you use it. One of my own problems has been that I don't actually use imgui-rs very much, so I don't get to experience all pain points from a user point of view.

What kind of qualifications do you have for maintaining a crate like this?

No need to have a master's degree in user interfaces, games, or unsafe code :smile: But I'd like to know if you already maintain any crates related to game development or have some other relevant skills which would be useful with imgui-rs.
opened by Gekkio 16
support winit-0.24

I've checked the breaking changes in winit 0.24, and none of them affect this imgui-winit-support crate. Simply allowing the 0.24 version for the winit-23 feature should be sufficient.

I also have the change ready where there is a separate winit-24 feature, adjusting the imgui-winit-support/src/lib.rs file to take it into account. Let me know if you prefer that approach over this one.

opened by willemv 13
Discussion: future of this project

...discussion based on comments in #285

Can everybody please clarify what exactly is expected of me that is not being provided at the moment? I'll happily consider giving full access to more people, but I'm also getting very mixed signals here.

@rasky wants review of this branch, which I'm not capable of delivering because this pull request has very little information about the change, and reviewing the pull request requires a good understanding of both the Dear Imgui feature (which is still experimental), and how that maps to imgui-rs.

What about @Jasper-Bekkers, @jaynus? What needs do you have that are not being met at the moment but would be if I gave full admin access to some people (you?)? My criteria for a crate being "unmaintained" is usually that pull requests don't get merged, which doesn't seem to be the case here, because the problem seems to be lack of review and/or lack of active development. I'm not actively doing work on this crate, but it's not the same thing as not accepting any changes.

There's nothing preventing somebody else from reviewing this pull request right here. In fact, if docking was in dear imgui master and somebody from Embark had reviewed this pull request, I'd merge it without hesitation.

There's nothing preventing somebody else from implementing "critical changes that weren't finished". If reasonable pull requests were submitted, I'd merge them.

And just to be clear: in any case, forking won't be needed. I'd much rather completely give away this project to somebody else than let it rot. However, the discussion so far seems to be mostly about credentials, not about the actual effort that moves the project forward. I've already given contributor access to one other person, and will gladly do it again. But what exactly does it change in practice other than credentials?

TL;DR:

"I need X but Gekkio doesn't do/provide Y" <- please fill in X and Y

"Q is not possible right now, but if Gekkio gave admin access to <name of person>, it would be possible" <- please fill in Q

opened by Gekkio 13
ListClipper + table doens't create scrollbars with imgui 1.86

For some reason with the latest main version of imgui-rs, a simple usage of the ListClipper cominbed with the table API will not produce scrollbars. Either with SCROLL_Y (which creates a new child window and scrolls within that) or without (creates items in current window and causes that to scroll)

The clipper appears to be mostly doing it's job - only the visible items are created, and it correctly adjusts as the window is resized etc.. just, there is never a scrollbar created

The same code was working in previous imgui-rs release (which used a previous version of upstream imgui)

Most confusingly, the examples in ImGui's Demo Window work fine, and the wrappers around the ListClipper are pretty thin

There was a bunch of bugfixes with imgui 1.86 to help with very large tables, so it's presumably something to do with these chnages.. but I'm very unclear if this is a problem in the bindings (likely since it works in the demo window, but strange as the bindings look correct on first glance), or if it's a problem with the upstream changes

@ocornut any thoughts on if this could be a problem on the C++ side of things?

opened by dbr 12

Add "freetype" feature

Quick attempt at #359 - adds feature to enable the freetype font rasterizer

Not tested much beyond "seems to work" comparing before/after with:

cargo run --example multiple_fonts --features freetype

..which requires libfreetype6-dev on Debian. No idea how it'll get on under other platforms, particularly Windows

There is one compiler warning:

warning: ./third-party/imgui/misc/freetype/imgui_freetype.cpp:357:8: warning: ‘ImFontBuildSrcGlyphFT’ has a field ‘ImFontBuildSrcGlyphFT::Info’ whose type uses the anonymous namespace [-Wsubobject-linkage]
warning:  struct ImFontBuildSrcGlyphFT
warning:         ^~~~~~~~~~~~~~~~~~~~~
warning: ./third-party/imgui/misc/freetype/imgui_freetype.cpp:366:8: warning: ‘ImFontBuildSrcDataFT’ has a field ‘ImFontBuildSrcDataFT::Font’ whose type uses the anonymous namespace [-Wsubobject-linkage]
warning:  struct ImFontBuildSrcDataFT
warning:         ^~~~~~~~~~~~~~~~~~~~

..which I think is an upstream thing

opened by dbr 12

(WIP) First cut at removing ImStr from the API.
Ulimately we're going to still transition to the imgui sized str branch here, but this means if there's some reason that doesn't pan out or can't be used universally (if it doesnt mix with docking or other branches or w/e) then it doesn't actually impact the API.

Concretely this version copies strings to a smallvec<[u8; 128]>, in order to NUL terminate them without allocating in common cases.

This has a nice benefit: it having this buffer means we can take allow users to pass in e.g. format_args!(...) directly, and we can use it as the scratch space, conveniently avoiding allocations for cases where you dynamically build the text on a widget, which is nice.

Basic idea

all functions taking &ImStr to move to trait AsImStr.

trait AsImStr is implemented for all &T: AsRef<str> + ?Sized (e.g. references to AsRef types — this handles a lot of things, including &str, &String, &ImStr, &ImString, ...

trait AsImStr is also implemented for fmt::Arguments (not as a reference).

(not done yet) ImStr/ImString are deprecated, but will be kept around (possibly with a much smaller API surface) since y'all don't update shit ever (we still support winit 0.19 in this code... 😭).

The long term goal is for us to transition (possibly behind a feature) to the string_view branch, but this change is intended on making whether or not we use that branch an implementation detail that doesn't matter too much (it's pretty cheap either way).

Open questions:

I'd like a better name than AsImStr. If ImStr goes away, why should this be called that? This ends up showing up in a lot of our function signatures, so we should try to do a good job here.

Needs user-facing docs. I'd like to solve the other questions here first tho to avoid writing them multple times.

Docs on the implementation stuff need cleaning up a lot

I kind of half-explained how the macro and such works in like 4 places in the hope that one of them stuck.

It's not even that complex — it's just weird looking and almost only happens inside a macro.

We could probably generalize to implementations of Display rather than AsRef + format_args. Should we?

This is more flexible... Or, it looks that way. I think in reality, it doesn't give you anything that format_args doesn't also give you, but it might give you that in a cleaner way that's likely to be understood by a larger portion of Rust users...

Con: ommitting to this might make it hard to get benefits from the string_view branch (we'd need specialization).

Con: It also might be confusing if you pass an integer in an argument that takes a string, and it's accepted because it's Display-able, or w/e...

Pro: it likely helps solve the issue around "this shows up in all our func sigs, so it would be nice if users had a clue what it was" (how many APIs take a format_args! directly?)

More generally: there something other than Display that's better for our case? (Note that we're still limited by coherence — it's very easy to come up with a set of things that would be nice if they worked, but they do not)

Is it worth the trouble at all? I think yes, but @sanbox-irl was skeptical, and has more experience with using imgui from Rust, so maybe this doesn't actually help.

Does this hit any unanticipated issues with type inference? If it tends to fail to resolve, that would defeat the point, largely...

...

Also, note that I only translated a few parts, @sanbox-irl indicated he might take the rest up but no rush, I might get the rest of them later today, it also might be worth deciding some of the above questions first. ~~That's why this is a draft PR tho.~~ (nm, clicked wrong button)
opened by thomcc 12
Feat permissive dropping, in which i suffer
Most tokens through the repository (eg. WindowToken, TabBarToken, FontStackToken, etc) now allow for permissive dropping -- i.e, you don't need to actually call the .end() method on them anymore. In exchange, these tokens have taken on a lifetime, which allows them to be safe.

end() no longer takes Ui. This is a breaking change, but hopefully should be trivial (and perhaps nice) for users to fix. Simply delete the parameters, or add a _ before the token's binding name and allow it to be dropped on its own.

PopupModal's new was reworked so that it didn't take Ui until build was called. This is a breaking change if you were invoking it directly. Simply move your ui call to build or begin.

I've changed my mind and think we shouldn't merge this till after 0.7 drops. Although the breaking changes this PR introduces are trivial, they can be substantial in a larger project. In our examples, it was about 23 single token changes (generally just removing an argument), and in my own private project, it was about 53, equally trivial changes.

I've also decided to leave all the pop methods in place. They just call end (which is an empty method just to invoke drop), but since ImGui uses pop sometimes for these methods, I think it's reasonable to have pop for people looking at ImGui C++, and end for people used to seeing the same "end" method in imgui-rs (although I'd say the idiomatic thing is just to _bind the variable and let it drop on its own now).

A few tokens survived the purge. A very used one (TreeNode), I manually implemented -- we need to make sure to not drop it if a certain flag was passed in. For ListClipperToken, I made an issue because I have no idea what that is and should probably learn https://github.com/imgui-rs/imgui-rs/issues/438, and for a few style tokens, they didn't have required drops on them right now. That might have been an oversight that exists, but I'll look into it eventually. https://github.com/imgui-rs/imgui-rs/issues/439

I would also like some golf claps for all of these edits and an acknowledgement of the suffering of editing all of these files, thank you.
opened by sanbox-irl 12

How to use imgui-rs with glfw or winit?

I am fairly new to rust and but I have used imgui with C++. I don't understand how to use this library with glfw or winit for windowing stuff. I was not able to find a up to date example, all examples either are not minimal or too old like 4-5 years old.

I do have a minimal example using imgui-glfw-rs but that uses an old version of imgui. Here is the example. in Cargo.toml

[dependencies]
imgui-glfw-rs = "0.4.1"

and here is src file.

use imgui_glfw_rs::{glfw, imgui, ImguiGLFW};

fn main() {
    let mut glfw_init = glfw::init(glfw::FAIL_ON_ERRORS).unwrap();
    glfw_init.window_hint(glfw::WindowHint::ContextVersion(3, 3));

    let (mut window, events) = glfw_init
        .create_window(
            1024,
            768,
            "imgui-glfw-rs example",
            glfw::WindowMode::Windowed,
        )
        .expect("Failed to create window");

    glfw::Context::make_current(&mut window);
    window.set_all_polling(true);

    gl::load_with(|symbol| window.get_proc_address(symbol) as *const _);
    unsafe {
        gl::Enable(gl::BLEND);
        gl::BlendFunc(gl::SRC_ALPHA, gl::ONE_MINUS_SRC_ALPHA);
        gl::Enable(gl::DEPTH_TEST);
        gl::DepthFunc(gl::LESS);
        gl::ClearColor(0.1, 0.1, 0.1, 1.0);
    }

    let mut im_ctx = imgui::Context::create();

    let mut imgui_glfw = ImguiGLFW::new(&mut im_ctx, &mut window);

    while !window.should_close() {
        unsafe {
            gl::Clear(gl::COLOR_BUFFER_BIT | gl::DEPTH_BUFFER_BIT);
        }

        let ui = imgui_glfw.frame(&mut window, &mut im_ctx);

        ui.show_demo_window(&mut true);

        imgui_glfw.draw(ui, &mut window);

        glfw::Context::swap_buffers(&mut window);

        glfw_init.poll_events();
        for (_, event) in glfw::flush_messages(&events) {
            imgui_glfw.handle_event(&mut im_ctx, &event);
        }
    }
}

and I want to use the new version which has the docking feature.

Is there a minimal example of using imgui and either glfw or winit (I am fine with any), without using other stuff.

opened by apoorv569 0

Add impl `DataTypeKind` for size types (`usize`/`isize`)

Description

When using a slider, you need to pass in a value that implements DataTypeKind. Currently, this is only the primitive numeric types, and I propose to extend it to include usize and isize as well.

Proposal

We add an

unsafe impl DataTypeKind for usize {
    const KIND: DataType = <PLATFORM DEPENDENT>;
}

We may need to add some internal casting to whichever integer type it matches. I assume this could be done by conditional compilation, or size_of: const USIZE_WIDTH:usize = size_of::<usize>();

Alternatives

My current implementation is to cast to u64 everywhere:

        // usize can't be used in a slider, so we have to cast to u64, use that, then case back
        type SliderType = u64; // Might fail on 128-bit systems where usize > u64, but eh
        let mut num_track_frames_compat: SliderType = *track_frames as SliderType;
        ui.slider_config(
            "Num Tracked Frames",
            1,
            Self::HARD_LIMIT_MAX_FRAMES_TO_TRACK as SliderType,
        )
        .flags(SliderFlags::LOGARITHMIC)
        .build(&mut num_track_frames_compat);
        *track_frames = num_track_frames_compat as usize;
        /*...*/

        *displayed_frames = min(*displayed_frames, *track_frames); // Don't allow it to go over num_track_frames
        let mut num_displayed_frames_compat: SliderType = *displayed_frames as SliderType; // Might fail on 128-bit systems, but eh
        ui.slider_config(
            "Num Displayed Frames",
            1,
            min(Self::HARD_LIMIT_MAX_FRAMES_TO_TRACK, *track_frames) as SliderType,
        )
        .flags(SliderFlags::LOGARITHMIC)
        .build(&mut num_displayed_frames_compat);
        *displayed_frames = num_displayed_frames_compat as usize;
        /*...*/

Safety & Reliability

As far as I'm aware, usize changes depending on which platform it's being targeted at. On 32-bit systems, it's equivalent to u32, on 64-bit u64, etc. (Untested) solution: Modify src/internals.rs to include these lines:


unsafe impl DataTypeKind for usize {
    #[cfg(target_pointer_width = "8")]
    const KIND: DataType = DataType::U8;

    #[cfg(target_pointer_width = "16")]
    const KIND: DataType = DataType::U16;

    #[cfg(target_pointer_width = "32")]
    const KIND: DataType = DataType::U32;

    #[cfg(target_pointer_width = "64")]
    const KIND: DataType = DataType::U64;

    // Fallback for when we are on a weird system width
    //
    #[cfg(not(any(
    target_pointer_width = "8",
    target_pointer_width = "16",
    target_pointer_width = "32",
    target_pointer_width = "64"
    )))]
    compile_error!("cannot impl DataTypeKind for usize: unsupported target pointer width. supported values are 8, 16, 32, 64");
}

unsafe impl DataTypeKind for isize {
    #[cfg(target_pointer_width = "8")]
    const KIND: DataType = DataType::I8;

    #[cfg(target_pointer_width = "16")]
    const KIND: DataType = DataType::I16;

    #[cfg(target_pointer_width = "32")]
    const KIND: DataType = DataType::I32;

    #[cfg(target_pointer_width = "64")]
    const KIND: DataType = DataType::I64;

    // Fallback for when we are on a weird system width
    //
    #[cfg(not(any(
        target_pointer_width = "8",
        target_pointer_width = "16",
        target_pointer_width = "32",
        target_pointer_width = "64"
    )))]
    compile_error!("cannot impl DataTypeKind for isize: unsupported target pointer width. supported values are 8, 16, 32, 64");
}

opened by Ararem 0

Update ImGui and use event-based io
This PR updates ImGui to v1.89.1 and exposes the new event-based io functions.

Possibly breaking changes:

ImageButton now takes an explicit ID, ImageButton::new() changed, added ui.image_button() and ui.image_button_config()

some variables in ImGuiIO were removed
opened by Rob2309 20
Add a way to store rendered "frames"

Is your feature request related to a problem? Please describe. I want to support both, opengl and vulkan renderers of imgui. However, the opengl renderer is relying on having an object with a limited lifetime passed to the "render" function. At the same time, for Vulkan it is better to separate the "drawing" and "presentation" stages, due to the nature of vulkan. So I was sort of trying to support both APIs by separating the stages for opengl renderer too. However, this would require storing the imgui::Ui object with a limited lifetime which I can't guarantee. In other words, I'd have to own the data in my structure. With current imgui-rs API it is impossible to obtain the imgui draw state (vertex buffers and others) and own them. We only can get a reference to the current frame's data and guarantee its lifetime.

Another problem is that now it is impossible to, let's say, "draw" a bunch of frames of the imgui, then store these states, and later render those either to a frame buffer of an API of choice or dump to a file, or render without any API to a file, you would be able to do anything with it. The only option now is to render immediately at the same place where the imgui::Ui object is obtained.

Describe the solution you'd like I'd like to have a way to obtain an owned copy of imgui::DrawData, namely vertex and index buffers, so that I am not limited by the lifetime of a single frame but can postpone the rendering and split it into stages and actually can do whatever I want with this data at any time later. Currently, the imgui::Context::render returns only a reference to imgui::DrawData that can't be owned. Due to the limitations of imgui::Context, it is also not possible to store it directly as it is neither copyable nor clonable. The only solution now, which is dirty here, is to store an Rc<RefCell<imgui::Context>> that is ugly and not really a solution.

Describe alternatives you've considered Can't think of any alternatives.

Additional context imgui::DrawData implements neither Copy nor Clone.

opened by vityafx 0
Update glow beyond v0.10

Mostly to note this somewhere easier to find:

Currently we are using glow 0.10. To update to 0.11 is not straight-forward, explained nicely in the original glow-renderer PR:

https://github.com/imgui-rs/imgui-rs/pull/495#issuecomment-913056533

Don't fully understand this problem, but from the comments on the linked upstream issue it seems possible to workaround this with some std::mem::transmute calls, and a more robust option may end up in 0.12
help wanted

opened by dbr 0
Enable the missing_docs lint

Currently commented out as mentioned in #531

Bit tedious but shouldn't be hard to document the remaining missing bits - main cumbersome thing is probably some objects where the doc ends up copy-paste of method name whcih feels a bit redundant, but probably overall worth doing

opened by dbr 0

Releases(v0.9.0)

v0.9.0(Nov 30, 2022)
Thanks everyone for your patience with this long overdue release!

There has been a good chunk of work done on imgui-rs since the last release. For a complete list, see the CHANGELOG.markdown in the main repository

A few key changes:

Building everything of Ui

The aim is to make the API more consistent and easier to discover functinality by having widgets be created consistently.

For example, previously a button was made by ui.button(...) but a slider made by imgui::Slider::new(...).build(ui) - meaning both appeared in different sections of the docs/auto-completion, so easy to miss. Now a slider is now made via ui.slider(...) also

This means some commonly used widgets like Window change - although a tiny bit tedious, it is hopefully a fairly stight-forward syntax change, which can be done with some search-and-replace (change imgui::Window::new(...) to ui.window(...) and remove the ui argument from build)

This is still somewhat a work-in-progress (some items may still be created via separate builder structs), but the aim is to transition everything to Ui

Docking

The upstream docking branch is now available, enabled via the docking feature. Higher-level, safe Rust bindings for this will come in a future release, for now these can be used via the imgui-sys crate

Various version updates

Dear ImGui is now 1.86 - this isn't the latest release, but it was better to release now and get imgui-rs back to a more regular release cycle

Similarly there is updates to latest glium, winit

Automatic notes

What's Changed

Fix glow renderer doc links by @toyboot4e in https://github.com/imgui-rs/imgui-rs/pull/532

disabled debug_message_insert_support on apple by @sanbox-irl in https://github.com/imgui-rs/imgui-rs/pull/534

Add Style accessor functions to Ui by @lwiklendt in https://github.com/imgui-rs/imgui-rs/pull/526

fix typo in Ui::button documentation by @malikolivier in https://github.com/imgui-rs/imgui-rs/pull/535

Window::new -> Ui::window attempt 2 by @dbr in https://github.com/imgui-rs/imgui-rs/pull/537

Switch [f32; _] types in the public api to mint equivalents by @sanbox-irl in https://github.com/imgui-rs/imgui-rs/pull/536

Fix update_delta_time() assertion fail from zero Duration by @dzil123 in https://github.com/imgui-rs/imgui-rs/pull/479

Remove the lifetime from Ui by @sanbox-irl in https://github.com/imgui-rs/imgui-rs/pull/539

Use ControlFlow:Poll in glow renderer examples by @dbr in https://github.com/imgui-rs/imgui-rs/pull/545

Implement imgui-sdl2-support crate. by @NightShade256 in https://github.com/imgui-rs/imgui-rs/pull/541

Add input_scalar and allow setting float input precision by @EmbersArc in https://github.com/imgui-rs/imgui-rs/pull/544

Add basic polyline methods to draw list by @dbr in https://github.com/imgui-rs/imgui-rs/pull/550

Fix a bug in SDL 2 support crate (#549) by @NightShade256 in https://github.com/imgui-rs/imgui-rs/pull/552

menu rewrite by @sanbox-irl in https://github.com/imgui-rs/imgui-rs/pull/551

Docking as a Feature Mk2 by @dbr in https://github.com/imgui-rs/imgui-rs/pull/557

Test docking feature in CI by @dbr in https://github.com/imgui-rs/imgui-rs/pull/567

Fix incorrectly copy-pasted documentation for InputTextFlags.CALLBACK_EDIT by @Sejsel in https://github.com/imgui-rs/imgui-rs/pull/572

Add a StyleVar for CellPadding by @Sejsel in https://github.com/imgui-rs/imgui-rs/pull/571

Add missing fields to memory layout tests by @Sejsel in https://github.com/imgui-rs/imgui-rs/pull/574

Update xflags to 0.2.x by @thomcc in https://github.com/imgui-rs/imgui-rs/pull/577

Update slider example #565 by @dbr in https://github.com/imgui-rs/imgui-rs/pull/568

Remove NO_ALPHA flag insertion in ColorPicker4::build by @kazatsuyu in https://github.com/imgui-rs/imgui-rs/pull/579

Make sure docs get generated for optional features as well by @Jasper-Bekkers in https://github.com/imgui-rs/imgui-rs/pull/573

Fix DPI scaling in examples by @dbr in https://github.com/imgui-rs/imgui-rs/pull/570

Support winit-0.26 by @cwfitzgerald in https://github.com/imgui-rs/imgui-rs/pull/583

Minor fixes to README by @LoipesMas in https://github.com/imgui-rs/imgui-rs/pull/591

Fix glow renderer not working for minor version = 0 by @PieKing1215 in https://github.com/imgui-rs/imgui-rs/pull/599

Fix up glob patterns in imgui-sys by @dbr in https://github.com/imgui-rs/imgui-rs/pull/597

Upgrade Dear ImGui 1.84.2 -> 1.86 by @dbr in https://github.com/imgui-rs/imgui-rs/pull/600

Make ui.popup* methods consistent by @dbr in https://github.com/imgui-rs/imgui-rs/pull/603

Refactor Slider to work under new Ui-based architecture by @imlazyeye in https://github.com/imgui-rs/imgui-rs/pull/607

winit-support: fix dpi handling in attach_window() when not in defaul… by @filnet in https://github.com/imgui-rs/imgui-rs/pull/608

Color upgrade by @sanbox-irl in https://github.com/imgui-rs/imgui-rs/pull/614

Winit 0.26 by @sanbox-irl in https://github.com/imgui-rs/imgui-rs/pull/615

Return Bool in SDL2 if handled event by @sanbox-irl in https://github.com/imgui-rs/imgui-rs/pull/616

Remove im_str! usage from examples in docs by @Sejsel in https://github.com/imgui-rs/imgui-rs/pull/618

imgui: Upgrade parking_lot to 0.12 with windows-rs bindings by @MarijnS95 in https://github.com/imgui-rs/imgui-rs/pull/624

imgui-winit-support: Build-test documentation example and fix compiler errors by @MarijnS95 in https://github.com/imgui-rs/imgui-rs/pull/625

Clipper bugfix and iterator interface by @dbr in https://github.com/imgui-rs/imgui-rs/pull/626

Handle window focus lost event by @dbr in https://github.com/imgui-rs/imgui-rs/pull/628

TextCallbackData::selection causes problems when selecting from right to left by @wcassels in https://github.com/imgui-rs/imgui-rs/pull/635

Removing support for old winit versions by @dbr in https://github.com/imgui-rs/imgui-rs/pull/638

glow: move vertex creation to same method as deletion by @dbr in https://github.com/imgui-rs/imgui-rs/pull/644

Removing note in README about being under new management. by @robertkeizer in https://github.com/imgui-rs/imgui-rs/pull/647

Update MSRV to 1.56 by @dbr in https://github.com/imgui-rs/imgui-rs/pull/660

fix doc by @linw789 in https://github.com/imgui-rs/imgui-rs/pull/666

leave tree_node label None if not set by @linw789 in https://github.com/imgui-rs/imgui-rs/pull/662

Support winit v0.27.2 by @dbarkar in https://github.com/imgui-rs/imgui-rs/pull/659

add TextFilter by @tetenpapier in https://github.com/imgui-rs/imgui-rs/pull/658

Proposed branching/release process by @dbr in https://github.com/imgui-rs/imgui-rs/pull/672

Restoring "Include imgui/misc/freetype/ in crate package" from 0.8.x release by @dbr in https://github.com/imgui-rs/imgui-rs/pull/673

Re-export winit and glow crates by @lovelymono in https://github.com/imgui-rs/imgui-rs/pull/676

New Contributors

@NightShade256 made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/541

@EmbersArc made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/544

@Sejsel made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/572

@kazatsuyu made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/579

@cwfitzgerald made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/583

@LoipesMas made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/591

@PieKing1215 made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/599

@imlazyeye made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/607

@MarijnS95 made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/624

@wcassels made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/635

@robertkeizer made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/647

@linw789 made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/666

@dbarkar made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/659

@tetenpapier made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/658

@lovelymono made their first contribution in https://github.com/imgui-rs/imgui-rs/pull/676

Full Changelog: https://github.com/imgui-rs/imgui-rs/compare/v0.8.0...v0.9.0
Source code(tar.gz)
Source code(zip)
v0.8.2(Dec 26, 2021)
Merry uh Boxing Day, here's another imgui-rs patch.

FIXES: We incorrectly listed docking as a feature in imgui-rs's features list to doc.rs. This prevented our docs from building.

Additionally, glow-renderer ended up at 0.8.3 because someone messed up the intra-crate linking (i am someone)
Source code(tar.gz)
Source code(zip)
v0.8.1(Dec 24, 2021)
Merry Christmas Eve, here's an imgui-rs patch.

FIXES: various memory safety issues around input_text and input_text_multiline. We are primarily releasing this patch to fix this issue.

FIXES: docs are now generated for our feature branches on crates.io. Thanks @Jasper-Bekkers

ADD: adds winit-0.26 support. thanks @cwfitzgerald

We'll see you all soon for v0.9.0, which will include a reworked main API (no more imgui::Window::new) and the docking branch.
Source code(tar.gz)
Source code(zip)
v0.8.0(Sep 17, 2021)
v0.8.0

Welcome to the 0.8.0 update. This is one of the largest updates imgui-rs has ever seen; it will generate errors in a 0.7 project, but hopefully it should be both quick to fix, and enjoyable to update.

Thank you to everyone who uses imgui-rs, files issues, and spends their time and effort to PR new changes into the codebase. Because of all that effort, this is by far the best imgui-rs has looked!

For more details, please see the full changelog below, which lists all of the (many) breaking changes.

imgui-rs important changes

🎉🎊 Removed ImStr and ImString from the API. 🎉🎊 Currently im_str! is deprecated and will be removed in 0.9.0. Internally, this has been implemented using AsRef<str> bounds across the codebase. I expect that this bound will change in such a manner to allow more expressions to be accepted. We then copy this str into a buffer, appending a null byte, and give that to ImGui. In the nearer future, we will add a feature to instead use imgui's string_view branch, which will allow us to avoid the internal buffer copy.

We have three new features in imgui:

min-const-generics is a default-feature. Effectively, you can choose to ignore this feature to keep this crate valid on rustc 1.48, but with the feature enabled, our MSRV is 1.54. In 0.9.0, this feature gate will be removed and we will commit to 1.54 and more common, minor, version bumps.

freetype enabled the Dear ImGui freetype feature. See here for more info on its advantages.

tables-api enables the...tables api...which was introduced in Dear ImGui 1.80. I decided to place this behind a feature gate so that users know to opt into it. However, I would strongly encourage users to opt into it -- see here for more information on it.

Most tokens through the repository (eg. WindowToken, TabBarToken, FontStackToken, etc) now allow for permissive dropping -- i.e, you don't need to actually call the .end() method on them anymore.

The best way to use these begin_x functions is probably like so:

if let Some(_t) = ui.begin_popup("example") { // your code here }

As a minor note, if you just do if let Some(_) or ui.begin_popup("example").is_some(), you'll immediately drop the token, which of course, calls the corresponding end function. In the future, we may keep using closures, especially as we move onto Rust 2021.

We upgraded from v1.80 to Dear ImGui v1.84.2 See the Dear ImGui v1.84 release notes for more information on what has changed. Along with that, we have wrapped around begin_disabled!

Most functions with C++ default parameters now have with_x variants. This makes calling most functions simpler and more similar to the C++.

The most likely breaking changes users will see is button and same_line now take one fewer parameter -- if you were calling button with [0.0, 0.0], simply delete that -- otherwise, call button_with_size. Similarly, for same_line, if you were passing in 0.0. simply delete that argument. Otherwise, call same_line_with_pos.

In addition to all the above, many other smaller, but important, changes were made this cycle. Please see the changelog as always.

Backends

Added an imgui-glow-renderer which targets glow 0.10. We haven't quite worked out some necessary kinks to get to 0.11. (In fact, we will skip 0.11 entirely and be on glow 0.12 when that releases. Follow this branch here for more.)

Changed default version of Winit in imgui-winit-support to winit 0.25.

Removed automatically adding default features for imgui-winit-support with the exception of the current default winit feature/dep version. If you want to not have the default features of winit with 0.25, set default-features = false and add winit-25 as a normal feature.

Changed the version of glium to 0.30 in imgui-glium-renderer, as it now uses winit 0.25.

Contributors

Thank you to all of the contributors who have commented, made issues, and contributed code to imgui-rs this cycle. The support of so many is what sustains this project. In no particular order, thank you to:

@thomcc for handling the majority of the backend's setup and keeping this project's ffi in order

@dbr for not only doing the rest of the backend's setup, but also consistently PRing to fix thorny API problems

@jmaargh for contributing the imgui-glow-renderer and being so deeply pleasant to code review

@cfrantz for multiple contributions including fixing the ComboxBox and providing the basis for the tables-api

@repi for pushing us to change how our winit-support works

@dzil123 for making that winit support more comprehensible

@toyboot4e for a truly heroic amount of Doc Alias commenting. Now you can search on docs.rs by C++ function names for the corresponding rust code

@lwiklendt for adding input text hinting

@AngelOfSol for allowing build methods to return a value. Additionally, thank you for contributing a PR for the input text callbacks

@Jake-Shadle for fixing text input deletions, which let to fixing the input widgets (I hope) completely.

@atouchet for fixing our readme

@haenno for fixing up our example code

@hpwxf for fixing some of our GFX examples

and last but also latest, thank you to @davidpdrsn and @vojd, and really all of Embark Studios, for somehow both working at the same company and contributing nearly two identical PRs at the same time this morning. It made me chuckle.

If you have any issues with this release (and it's a big one), please file an issue!

sanbox-irl (Jonathan Spira)

Full changelog

Removed ImStr and ImString from the API. Currently im_str! is deprecated and will be removed in 0.9.0. To change your code:

If you were just wrapping a string literal, like im_str!("button"), just use "button". (Help: the regex im_str!$"((?:(?=(\\?))\2.)*?)"$, replacing matches with "$1", can get the majority of these quickly.);

If you were formatting, like &im_str!("My age is {}", 100), you can now just use format like format!("My age is {}, 100). Notice that due to the trait bounds, you can pass the string in directly too.

BREAKING: Most tokens through the repository (eg. WindowToken, TabBarToken, FontStackToken, etc) now allow for permissive dropping -- i.e, you don't need to actually call the .end() method on them anymore. In exchange, these tokens have taken on a lifetime, which allows them to be safe. This could make some patterns impossible. Please file an issue if this causes a problem.

end() no longer takes Ui. This is a breaking change, but hopefully should be trivial (and perhaps nice) for users to fix. Simply delete the argument, or add a _ before the token's binding name and allow it to be dropped on its own. In our code, we tend to write these now like:

if let Some(_t) = ui.begin_popup("example") { // your code here }

BREAKING: Created with_x variants for most functions which previously took multiple parameters where some had default arguments in the C++. This makes calling most functions simpler and more similar to the C++.

The most likely breaking changes users will see is button and same_line now take one fewer parameter -- if you were calling button with [0.0, 0.0], simply delete that -- otherwise, call button_with_size. Similarly, for same_line, if you were passing in 0.0. simply delete that argument. Otherwise, call same_line_with_pos.

ADDED: support for the tables API which was added in dear imgui 1.80. We currently have this feature gated behind tables-api. You should feel safe to use this in stable production, but be aware of two things:

The tables API is marked as "beta" meaning that it may change with fewer stability promises. This is unlikely and it seems fairly settled.

There are a few cases where the tables API will segfault by dereferencing a NULL where it should instead ASSERT and crash. This is simply annoying because you won't get a stacktrace. See here for more info on that.. If this is fixed upstream, we will issue a patch.

ADDED: an imgui-glow-renderer which targets glow 0.10. Before release, this will be updated to target current 0.11 glow when further features are added. Thank you to @jmaargh for the work implementing this here!

UPGRADED: from v1.80 to Dear ImGui v1.84.2 See the Dear ImGui v1.84 release notes for more information. Thank you to @dbr for doing the work (twice actually) of upgrading the repository.

BREAKING: Reworked how callbacks on InputText and InputTextMultiline work.

REMOVED .callback_name() methods in favor of one method: .callback(FLAGS, CallbackStruct).

Wrapped callback kinds into their own enums, InputTextCallback and InputTextCallbackMultiline.

Created a trait, InputTextCallbackHandler.

To see how to create an InputText callback, see examples/text_callback.rs.

Finally, please note that editing an &mut String which contains \0 within it will produce surprising truncation within ImGui. If you need to edit such a string, please pre-process it.

ADDED: begin_disable and begin_enable methods. These add (finally) support for disabling any widget. Thank you to @dbr for implementing this here.

BREAKING: MSRV is now 1.54. This is gives us access to min-const-generics, which we use in a few places, but will gradually use more. Because this is the first time we've bumped MSRV intentionally, we have added a new feature min-const-generics, which is enabled by default. If you are pre-1.54, you can hang onto this update by disabling that feature. In our next update, this feature will be removed and we will commit to our MSRVs going forward. Thank you to @dbr for changing our CI infrastructure to support better MSRVs here.

BREAKING: Changed default version of Winit in imgui-winit-support to winit 0.25. Thank you to @repi for implementing this here.

Removed automatically adding default features for imgui-winit-support with the exception of the current default winit feature/dep version. If you want to not have the default features of winit with 0.25, set default-features = false and add winit-25 as a normal feature. Thank you to @dzil123 for the work implementing this here!

ADDED: Support for the freetype font rasterizer. Enabled by the non-default freetype feature, e.g imgui = {version = "...", features=["freetype"]}) Thank you to @dbr for this work implementing this here.

ADDED: doc alias support throughout the repository. You can now, inside the docs, search for imgui-rs functions by their Dear ImGui C++ names. For example, searching for InputText will pull up Ui::input_text. This was quite a lot of documentation and effort, so thank you to @toyboot4e for implementing this here.

ADDED: text hinting into InputText. Thank you to @lwiklendt for implementing this here.

BREAKING: Reworked .range calls on Slider, VerticalSlider, and Drag to simply take two min and max values, and requires that they are provided in the constructor.

To update without changing behavior, use the range T::MIN and T::MAX for the given numerical type (such as i8::MIN and i8::MAX).

Using .range is still maintained for simplicity, but will likely be deprecated in 0.9 and removed in 0.10!

DrawListMut has new methods to draw images

The methods are add_image, add_image_quad, and add_image_rounded. The imgui-examples/examples/custom_textures.rs has been updated to show their usage.

Additionally the imgui::draw_list module is now public, which contains the various draw list objects. While the add_* methods are preferred, imgui::draw_list::Circle::new(&draw_list_mut, ...).build() is equivalent

Finally, we have relaxed the limits around having multiple draw lists such that you can have multiple mutable draw lists of different kinds (ie, a foreground and a background at the same time.).

Thank you to @dbr for implementing these changes.

ADDED: the ButtonFlags which previously prevented invisible_button from being usable. Thank you to @dbr for implementing this change here.

BREAKING: PopupModal's new was reworked so that it didn't take Ui until build was called. This is a breaking change if you were invoking it directly. Simply move your ui call to build or begin.

BREAKING: Restored methods to access keyboard based on backend-defined keyboard map indexes. These allow access to most keys, not just those defined in the small subset of imgui::Keys (note the available keys may be expanded in future by imgui PR #2625)

The new methods on imgui::Ui are is_key_index_down, is_key_index_pressed, is_key_index_pressed_no_repeat, is_key_index_released, is_key_index_released

For example ui.is_key_released(imgui::Key::A) is same as ui.is_key_index_released(winit::events::VirtualKeyCode::A as i32) when using the winit backend

BREAKING: Modifies build style methods to allow the provide closure to return a value. The build call will then return Some(value) if the closure is called, and None if it isn't.

The most likely breaking changes users will see is that they will need to add semicolons after calling build, because these function no longer return ().

Thank you to @AngelOfSol for implementing this here.

BREAKING: Removed imgui::legacy which contained the old style of flags. The remaining flags in imgui::legacy have been updated to be consistent with other flags in the project.

imgui::legacy::ImGuiDragDropFlags were accidentally not cleared when they were remade in drag_drop.rs in v0.7.0.

imgui::legacy::ImGuiInputTextFlags is now imgui::input_widgets::InputTextFlags

imgui::legacy::ImGuiTreeNodeFlags is now imgui::widget::tree::TreeNodeFlags

imgui::legacy::ImDrawListFlags is now imgui::draw_list::DrawListFlags

Full (32-bit) unicode support is enabled in Dear Imgui (e.g. -DIMGUI_USE_WCHAR32 is enabled now). Previously UTF-16 was used internally.

BREAKING: Some parts of the font atlas code now use char (or u32) instead of u16 to reflect this.

Note: u32 is used over char in some situations, such as when surrogates are allowed

BREAKING (sorta): Dear Imgui now will use 32 bits for character data internally. This impacts the ABI, including sizes of structs and such, and can break some low level or advanced use cases:

If you're linking against extensions or plugins to Dear Imgui not written in Rust, you need to ensure it is built using -DIMGUI_USE_WCHAR32.

However, if the DEP_IMGUI_DEFINE_ vars are used properly, this is non-breaking.

If you're using features="wasm" to "link" against emscripten-compiled Dear Imgui, you need to ensure you use -DIMGUI_USE_WCHAR32 when compile the C and C++ code.

If you're using DEP_IMGUI_DEFINE_s for this already, then no change is needed.

If you're using .cargo/config to apply a build script override and link against a prebuilt Dear Imgui (or something else along these lines), you need to ensure you link with a version that was built using -DIMGUI_USE_WCHAR32.

Source code(tar.gz)
Source code(zip)
v0.7.0(Feb 5, 2021)
v0.7.0

Upgrade to Dear ImGui v1.80. (Note that the new table functionality is not yet supported, however)

Ui::key_index() is now called internally when needed, and the various is_key_foo now take a Key directly: https://github.com/imgui-rs/imgui-rs/pull/416

is_key_down, is_key_pressed, is_key_released and key_pressed_amount now take a Key instead of u32 (breaking).

key_index is no longer public (breaking). If you need access to the key map, it can be accessed as ui.io().key_map[key] (If you need to do this, file a bug, since I'm open to exposing this if there's actually a use case).

winit 0.23/0.24 handling has been (hopefully) fixed: https://github.com/imgui-rs/imgui-rs/pull/420 (breaking, see also https://github.com/imgui-rs/imgui-rs/issues/412).

imgui-winit-support's winit-23 feature no longer supports winit version 0.24 (this caused an unintentional semver breakage in the imgui-winit-support crate before, unfortunately).

imgui-winit-support has a new winit-24 feature for 0.24 support.

By default imgui-winit-support feature now enables winit-24, and not winit-23 (by default it will always enable the latest).

The imgui crate no longer depends on gfx or glium directly: https://github.com/imgui-rs/imgui-rs/pull/420 (breaking, related to the previous change).

That is, the gfx and glium features are removed to reduce version compatibility issues going forward.

This only matters if you manually implement gfx or glium renderers without using the imgui-glium-renderer or imgui-gfx-renderer crates.

In the (somewhat unlikely) case you were relying on these this, you should define your own vertex type that's layout-compatible with imgui::DrawVert, and replace calls to imgui::DrawList::vtx_buffer() with imgui::DrawList::transmute_vtx_buffer::<MyDrawVert>(). You can see imgui_glium_renderer::GliumDrawVert and imgui_gfx_renderer::GfxDrawVert types respectively for examples of this, if needed, but it should be straightforward enough if you're already implementing a renderer from scratch.

This is admittedly less convenient, but avoids depending on any specific version of gfx or glium in the core imgui crate, which will ease maintenance and reduce unintentional breakage in the future.

Non-window DrawList support has been fixed/improved: https://github.com/imgui-rs/imgui-rs/pull/414

WindowDrawList has been renamed to DrawListMut, to reflect that it may refer to other kinds of draw lists, and is mutable, unlike imgui::DrawList (breaking).

Ui::get_background_draw_list() has been fixed when used outside of a window context, and now has an example.

Ui::get_foreground_draw_list() has been added, analogous to Ui::get_background_draw_list().

Added drag drop support, with a safe and an unsafe variant: https://github.com/imgui-rs/imgui-rs/pull/428

DragDropSource allows users to create a dragdrop payload which is either empty, of 'static + Copy data, or unsafe, allowing for theoretically arbitrary payloads.

DragDropTarget allows users to accept any of the above payloads.

Extensive documentation has been made on all of these features, hopefully as a target for future features.

ImColor (which is a wrapper around u32) has been renamed to ImColor32 in order to avoid confusion with the ImColor type from the Dear ImGui C++ code (which is a wrapper around ImVec4). In the future an ImColor type which maps more closely to the C++ one will be added.

Additionally, a number of constructor and accessor methods have been added to it ImColor, which are const fn where possible.

The im_str! macro can now be used in const contexts (when the format! version is not used).

im_str! now verifies that the parameter has no interior nuls at compile time. This can be avoided to get the old (truncating) behavior by forcing it to use the format!-like version, e.g. im_str!("for_some_reason_this_should_be_truncated\0 there {}", "").

This is not recommended, and is probably not useful.

Many functions are now const fn.

A large number of small functions are now #[inline], but many still aren't, so you probably will want to build with LTO for release builds if you use imgui heavily.

The io.config_windows_memory_compact_timer flag has been renamed to io.config_memory_compact_timer. This follows the similar rename in the C++ ImGui, and was done because it no longer only applies to window memory usage.

The variants of ColorEditInputMode and ColorEditDisplayMode have been renamed to be CamelCase instead of upper case (e.g. ColorEditFooMode::RGB => ColorEditFooMode::Rgb).

However, this change is probably not breaking (in practice if not in theory) because const aliases using the old names are provided.

Source code(tar.gz)
Source code(zip)
v0.6.0(Nov 15, 2020)
Added

Io::peek_input_characters

Changed

Upgrade to cimgui / imgui 1.79

Upgrade to winit 0.23

Bump minimum Rust version to 1.41

Source code(tar.gz)
Source code(zip)
v0.5.0(Oct 5, 2020)
Added

Support for ConfigFlags::RENDERER_HAS_VTX_OFFSET in imgui-glium-renderer and imgui-gfx-renderer. This makes it possible to output large meshes (e.g. complex UIs) without problems when using these renderers

Ui::begin_tooltip to support using tooltips with stack tokens instead of closures

API for accessing the background drawlist

Tab bar / tab item API

Redesigned drag slider API

Changed

Upgrade to cimgui / imgui 1.78

Store per-texture sampler parameters in imgui-glium-renderer to support customizing them

Slider widget constructors no longer require the range parameter. Call the range function on the builder to set the range.

Fixed

Reduce unnecessary winit cursor changes which earlier caused cursor flickering or invalid cursors on some platforms (at least Windows)

Removed

Various things that were deprecated in imgui-rs 0.4.0

Source code(tar.gz)
Source code(zip)
v0.4.0(Jun 5, 2020)
Added

WebAssembly FFI shells

Changed

Redesign tree / collapsing header API

Bump minimum Rust version to 1.40 (at least xml-rs crate requires it)

Upgrade to glium 0.27 / winit 0.22

Switch Glium renderer to use GL_CLAMP_TO_BORDER

Fixed

Bug in font name length checking

Source code(tar.gz)
Source code(zip)
v0.3.1(Mar 16, 2020)
Fixed

Narrowed supported winit version range in imgui-winit-support

Source code(tar.gz)
Source code(zip)
v0.3.0(Mar 16, 2020)
Added

Add ChildWindow::movable

ImString now implements fmt::Write

Changed

Upgrade to cimgui / imgui 1.75

Bump minimum Rust version to 1.38 (at least backtrace crate requires it)

Upgrade to glium 0.26 / winit 0.21

Switch imgui-winit-support to 0.20+ by default. Winit 0.19 support is still available via the winit-19 feature flag

Resources used by examples are no longer included in the published crate

Removed

Various things that were deprecated in imgui-rs 0.2.0

Fixed

Fix toggling behavior on using MenuItem::build_with_ref and Selectable::build_with_ref.

ImString nul terminator handling

Source code(tar.gz)
Source code(zip)
v0.2.1(Mar 16, 2020)
Fixed

Fix backspace handling on macOS

Fix ImageButton bool return value

Source code(tar.gz)
Source code(zip)
v0.2.0(Mar 16, 2020)
Added

Window scrolling API

Full support for the column API

Almost all small utility functions from upstream API

Support for winit 0.20 alpha via winit-20 feature

Changed

Redesigned window API

Redesigned progress bar API

Redesigned color editor/picker API

Redesigned child window API (previously known as child frame)

Redesigned image / image button API

Redesigned combo box API

Redesigned selectable API

Redesigned slider API. Generic scalar sliders support all main data types and replace previous individual sliders (int, int2, int3, int4, etc...)

Redesigned menu API

Updated layout API

Renderer errors implement std::error::Error

Glium renderer re-exports imgui and glium

Gfx renderer re-exports imgui and gfx

These functions now take/return PathBuf: log_filename, set_log_filename, ini_filename, set_logfilename

ID stack manipulation now uses stack tokens

Parameter stack pushes must almost always be paired by a manual call to stack pop

Container widget tokens must be ended manually by calling end. Closure-based function (e.g. build()) are unaffected and do this automatically

Bump minimum Rust version to 1.36 (some dependencies, including winit, require MaybeUninit)

Upgrade to cimgui / imgui 1.72b

Removed

Various things that were deprecated in imgui-rs 0.1.0

Source code(tar.gz)
Source code(zip)
v0.1.0(Jul 12, 2019)
Added

Support for font atlas sharing

Support for using multiple fonts

Support for suspended contexts (useful for having multiple independent operating system windows)

Support for DX11 in imgui-gfx-renderer

Support for navigation input system

Support for backend/renderer name strings

Support for saving/loading INI settings manually

Pluggable clipboard support

Changed

imgui-sys is now almost completely automatically generated. This is a big breaking change in imgui-sys API

ImGui/Context API is now safer

The library context (known as Context, previously known as ImGui) is no longer Send or Sync

Many getter/setter APIs have been replaced with direct access to struct fields

[f32; 2] and [f32; 4] are now the main vector types. ImVec/ImVec4 and corresponding tuples are no longer used in the main API

imgui-gfx-renderer is parameterized over the color format, so Rgba8 and Srgba8 are both supported

imgui-winit-support has been rewritten to provide a more robust abstraction that is easier to use correctly

Parameter stack (e.g. StyleVar) manipulation is now done using push functions and automatically or manually droppable stack tokens

Upgrade to glium 0.25

Upgrade to cimgui / imgui 1.71

Bump minimum Rust version to 1.33

Source code(tar.gz)
Source code(zip)
v0.0.23(Apr 10, 2019)
Added

Support for image buttons: Ui::image_button

Ui::set_keyboard_focus_here

Support for window position pivot

Changed

Upgrade to gfx 0.18

Removed

Various things that were deprecated in imgui-rs 0.0.21 and 0.0.22

Source code(tar.gz)
Source code(zip)
v0.0.22(Mar 5, 2019)
Added

Ui::with_test_wrap_pos

Ui::get_content_region_max

Ui::get_window_content_region_min

Ui::get_window_content_region_max

Changed

Upgrade to cimgui 1.66.2+ / imgui 1.66b. This is a very big update, so there are a lot of breaking changes

Bump minimum Rust version to 1.31 (1.28 required by the glutin crate, and 1.31 required by the stb_truetype crate)

Upgrade to glium 0.23

Replaced imgui-glutin-support with imgui-winit-support

Source code(tar.gz)
Source code(zip)
v0.0.21(Oct 12, 2018)
Added

ImGui::mouse_down

ImGui::key_super

Ui::get_window_pos

Ui::is_window_focused

Ui::is_root_window_focused

Ui::is_child_window_focused

Ui::popup_modal

imgui-glutin-support crate

Support for custom textures

Fixed

Possible crash if rendering was skipped during a frame

Changed

Bump minimum Rust version to 1.26 (required by the parking_lot_core crate)

Source code(tar.gz)
Source code(zip)
v0.0.20(Aug 15, 2018)
Fixed

Clip rect regression in the glium renderer

Removed

Various things that were deprecated in imgui-rs 0.0.19

Source code(tar.gz)
Source code(zip)
v0.0.19(Aug 12, 2018)
Added

New things in imgui/cimgui 1.53.1

Style: Add PopupRounding, FrameBorderSize, WindowBorderSize, PopupBorderSize.

DemoWindow: Add no_close state.

Input: Add no_undo_redo method.

imgui-sys:

igStyleColorsDark and igStyleColorsLight

DragDrop low level API

igGetFrameHeight

igBeginCombo, igEndCombo

igSetItemDefaultFocus

igGetOverlayDrawList and igGetDrawListSharedData

ImFontConfig_DefaultConstructor

ImDrawList_AddImageRounded

Input: Add read_only and password methods.

Various utility functions

Support for changing the mouse cursor

Custom font support

Support for item grouping (group function)

Custom drawing with draw list manipulation

Drag widgets

Input: Add input_text_multiline method

Changed

Upgrade to imgui/cimgui 1.53.1

Rename Ui::show_test_window to Ui::show_demo_window. Keep redirection.

Rename sys::igGetItemsLineHeightWithSpacing to sys::igGetFrameHeightWithSpacing. Keep redirection.

Rename ImGuiTreeNodeFlags::AllowOverlapMode to ImGuiTreeNodeFlags::AllowItemOverlap. sys::igSetNextWindowContentSize(). Keep redirection.

Rename sys::ImGuiTextBuffer_append() helper to appendf().

Rename ImGuiStyleVar::ChildWindowRounding to ImGuiStyleVar::ChildRounding. Keep redirection.

Rename StyleVar::ChildWindowRounding to StyleVar::ChildRounding. Keep redirection.

Rename ImGuiCol::ChildWindowBg to ImGuiCol::ChildBg. Keep redirection.

Upgrade glium to 0.22.0. This updates winit to 0.16. This changes the way HIDPI are calculated. Depending on your needs, you may want to set HIDPI to 1 by setting the environment variable WINIT_HIDPI_FACTOR=1 if you use X11.

frame() now takes a single FrameSize argument

Bump minimum Rust version to 1.24

set_mouse_down takes button states by value, not by reference

Deprecated

Various imgui-sys things that were deprecated in imgui/cimgui 1.53.1

Obsolete sys::igIsRootWindowFocused() in favor of using sys::igIsWindowFocused(ImGuiFocusedFlags::RootWindow).

Obsolete sys::igIsRootWindowOrAnyChildFocused() in favor of using sys::igIsWindowFocused(ImGuiFocusedFlags::RootAndChildWindows).

Obsolete sys::igIsRootWindowOrAnyChildHovered() in favor of using sys::igIsWindowHovered(ImGuiHoveredFlags::RootAndChildWindows).

Obsolete sys::SetNextWindowContentWidth() in favor of using

Obsolete Window::show_borders. Use StyleVar instead.

Obsolete ImGuiCol::ComboBg. Use PopupBg instead.

Removed

Features that were removed in imgui/cimgui 1.53.1

Remove anti_aliased: bool final parameter of sys::ImDrawList_AddPolyline and sys::ImDrawList_AddConvexPolyFilled.

Remove ImGuiWindowFlags::ShowBorders window flag. Borders are now fully set up in the ImGuiStyle structure.

Various imgui-sys things that were deprecated in imgui/cimgui 1.52

Source code(tar.gz)
Source code(zip)
v0.0.18(Jan 1, 2018)
Added

is_item_hovered

tooltip

tooltip_text

Changed

Upgrade to imgui/cimgui 1.52

Upgrade to glium 0.19

Deprecated

Various imgui-sys things that were deprecated in imgui/cimgui 1.52

Removed

Non-namespaced flags

Various imgui-sys things that were deprecated in imgui/cimgui 1.51

Window::bg_alpha. Push a color change with with_color_var instead

color_edit3

color_edit4

Source code(tar.gz)
Source code(zip)
v0.0.17(Nov 7, 2017)
Added

Namespaced flags (e.g. ImGuiWindowFlags)

Color picker widget

Color button widget

imgui_sys is now re-exported as sys in the main create

imgui::get_style_color_name

Changed

Upgrade to imgui/cimgui 1.51

Adapt to latest cimgui API changes

Bump minimum Rust version to 1.20

Upgrade to bitflags 1.0

Various minor ImString/ImStr changes

text now accepts normal Rust strings. ImStr is still needed everywhere else

Fixed

Default impl for ImString was incorrect and could cause a crash

Deprecated

Non-namespaced flags

Various imgui-sys things that were deprecated in imgui/cimgui 1.51

Window::bg_alpha. Push a color change with with_color_var instead

color_edit3. Use color_edit instead

color_edit4. Use color_edit instead

Removed

ImStr -> str Deref. Use to_str instead.

Source code(tar.gz)
Source code(zip)
v0.0.16(Nov 7, 2017)
Added

OpenGL ES 2.0+ support in gfx and glium renderers

Separate OpenGL 2.0, 3.0, 4.0 shaders in both renderers. This should fix an issue with some systems that refuse to use old GLSL shaders with modern OpenGL contexts

ImGui::add_font_global_scale

Support for radio buttons

Changed

Upgrade to glium 0.18

imgui-gfx-renderer Renderer::init now requires a shaders: Shaders parameter. Please see examples/support_gfx/mod.rs for a shader resolution example

Bump minimum Rust version to 1.19 because some dependencies require it.

Fixed

Glium renderer now uses MinifySamplerFilter::Nearest. This fixes a blurry font issue in some configurations

Removed

ImString::from_string_unchecked

ImString::from_bytes_unchecked

ImStr::from_bytes_unchecked

Source code(tar.gz)
Source code(zip)
v0.0.15(Nov 7, 2017)
Added

Support for new_line function

Support for text size calculation

Support for scoped style customization

Support for scoped color customization

Support for child frames

Unsafe ImString/ImStr creation functions for advanced users:

ImString::from_utf8_unchecked (renamed from ImString::from_bytes_unchecked)

ImString::from_utf8_with_nul_unchecked)

ImStr::from_utf8_with_nul_unchecked (renamed from ImStr::from_bytes_unchecked)

Changed

Button, selectable, histogram, plotlines, and progress bar accept size with Into<ImVec2>

ImString::new always succeeds and any interior NULs truncate the string. Breaking change

All builder constructor functions (e.g. Window::new) now take &Ui reference to tie the lifetime of the builder to it.

Bumped minimum Rust version to 1.17 because some dependencies require it.

Upgrade to glium 0.17

Deprecated

ImString::from_string_unchecked (please use ImString::new)

ImString::from_bytes_unchecked (renamed to ImString::from_utf8_unchecked)

ImStr::from_bytes_unchecked (renamed to ImStr::from_utf8_with_nul_unchecked)

Fixed

Histogram, plotlines, progressbar builders were not tied to the &Ui lifetime, so it was possible to misuse them.

Source code(tar.gz)
Source code(zip)
v0.0.14(Nov 7, 2017)
Added

ImString owned type for strings

Experimental support for gfx-rs in imgui-sys

Experimental renderer for gfx-rs

Changed

ImStr is now "a dear imgui -compatible string slice". This change significantly affects how strings are handled.

Upgrade to imgui/cimgui 1.50

Upgrade to bitflags 0.9

Fixed

String pointer compilation problems on ARM

Source code(tar.gz)
Source code(zip)
v0.0.13(Nov 7, 2017)
Changed

Make the crates publishable again after the Glium renderer separation

Source code(tar.gz)
Source code(zip)
v0.0.12(Nov 7, 2017)
Added

Support for progress bar

Support for push/pop item width

Support for ID stack manipulation (integer values)

Support for 2-4 -element int sliders

Support for 2-4 -element float sliders

ImVec4::zero()

Into array and tuple conversions for ImVec2 and ImVec4

gfx 0.15 support in imgui-sys

gfx 0.15 renderer implementation

Changed

imgui-sys no longer includes glium support by default

Move Glium renderer to a separate crate

Removed

Window::always_vertical_scollbar (typo)

igPushStyleVavrVec (typo)

ImGuiInputTextFlags::with

ImGuiTreeNodeFlags::with

ImGuiWindowFlags::with

Source code(tar.gz)
Source code(zip)
v0.0.11(Nov 7, 2017)
Added

ImVec2::zero()

Support for buttons

Support for closing current popup

Window::always_vertical_scrollbar (fix typo)

igPushStyleVarVec (fix typo)

Changed

Upgrade to bitflags 0.8

Upgrade to glium 0.16

Replace libc dependency with std::os::raw

Upgrade cimgui to include MinGW compilation fix

Deprecated

Window::always_vertical_scollbar (typo)

igPushStyleVavrVec (typo)

ImGuiInputTextFlags::with

ImGuiTreeNodeFlags::with

ImGuiWindowFlags::with

Source code(tar.gz)
Source code(zip)
v0.0.10(Nov 7, 2017)
Changed

Upgrade to glium 0.15

Examples use std::time instead of the deprecated time crate

Source code(tar.gz)
Source code(zip)
v0.0.9(Nov 7, 2017)
Added

Support for columns, combo, listbox

Support for plothistogram, plotlines

Support for color edit widgets

Support for int and float inputs

Support for int and float array inputs

Support for popups

Support for selectable

Better support for hidpi environments

Changed

ImStr::as_ptr is now part of the public API

Upgrade to bitflags 0.7

Upgrade to imgui/cimgui 1.49

Several imgui_sys structs have changed

CollapsingHeader API has changed

New window flags are supported

Source code(tar.gz)
Source code(zip)
v0.0.8(Nov 7, 2017)
Added

Add a change log

Changed

Upgrade to glium 0.14

Source code(tar.gz)
Source code(zip)
v0.0.7(Nov 7, 2017)
Changed

Upgrade to imgui/cimgui 1.47

Fixed

Fix Glium rendering error when more than one texture is used (issue #17)

Source code(tar.gz)
Source code(zip)