Future directions of ImGui-related packages

[Gnimuc]

Hi,

As you might notice, this package, CImGui.jl, has got stuck in v1.79 for about 7 months. The main reason is that Dear ImGUI introduced a new set of table APIs in v1.80 and it's a bunch of work to update the wrappers and examples. Another reason is Clang.jl. Until recently, Clang.jl had no support for handling C's forward declaration, so I had to manually tweak the auto-generated bindings from time to time, which was quite annoying.

In the last few months, I redesigned and reworked Clang.jl so that one can now regenerate bindings with a single click. However, I adopted a new way for dereferencing pointers and as a result, almost all example codes need to be updated.

For example, igGetIO() returns a pointer of type Ptr{ImGuiIO}. With this field access method in v1.79, say we have io::Ptr{ImGuiIO}=igGetIO(), then we can run ds = io.DisplaySize to get a value ds of type ImVec2. This may look handy at the first glance. But, it does not support chaining, for example, io.DisplaySize.x cannot work as expected and it's not trivial to make it work in an efficient way. The new field access method generated by Clang.jl now returns a pointer instead of a value. io.DisplaySize.x will return a pointer and one needs to explicitly write unsafe_load(io.DisplaySize.x) to get the value. In this way, we're able to read/load/copy a single value from a big nested struct without copying the whole struct object from C to Julia. So, I think it's worth reworking everything in this new style.

Adding support for docking-multiviewport has been in the feature request list for a loooong time(#34). To be honest, the docking feature is the reason why I adopt Dear ImGUI at the very beginning. I've been waited for this feature to be officially released for over two years, but it seems that there are still a few severe bugs on certain platforms and no one is currently working on them, so the development is kinda suspended. On the other hand, the docking branch of Dear ImGUI is relatively stable and is being used by many projects. In #43, @yamen suggested that we should switch to the docking branch and also integrate ImPlot for the sake of compatibility and I think this is the right direction.

In the last week, I started to rework the whole package to make it easier for long time sustainable maintenance:

1. JuliaImGui is the new home for ImGui-related Julia packages
2. JuliaImGui/cimgui-pack is a repo for controlling the compatibility(by using our own versioning) between different imgui addon projects. Now it integrates cimgui(1.82dock), cimplot(0.9(6b63f45)) and cimnodes(0.4(bf27f8d)). As it's not recommended to use Dear ImGUI in a style of a shared library, I choose to build the whole thing into a single giant shared library instead of a couple of shared libraries linked together. (Requirements for maintaining: know how to use git)
3. JuliaBinaryWrappers/CImGuiPack_jll.jl is the artifacts provided via the cool Yggdrasil service with this build script: https://github.com/JuliaPackaging/Yggdrasil/blob/master/C/CImGuiPack/build_tarballs.jl. (Requirements for maintaining: know how to build binaries by using BinaryBuilder.jl)
4. JuliaImGui/LibCImGui.jl provides Julia bindings for all of the low-level C APIs in CImGuiPack_jll. Its major version and minor version should always be the same as the Dear ImGui version used in cimgui-pack. As a result, we can enforce semantic versioning in high-level packages like CImGui.jl and CImPlot.jl without losing the version info of the Dear ImGui. This package is fully auto-generated by using Clang.jl with this generator script: https://github.com/JuliaImGui/LibCImGui.jl/blob/master/gen/generator.jl. The above-mentioned field access methods for certain types will be generated as long as the type name is in this list. (Requirements for maintaining: know how to install Julia package and run Julia script.)
5. JuliaImGui/ImGuiGLFWBackend.jl is the GLFW backend with docking-multiviewport support. For now, it only supports OpenGL but Vulkan support can be added in the future. (Requirements for maintaining: know how to use GLFW)
6. JuliaImGui/ImGuiOpenGLBackend.jl is the OpenGL backend with docking-multiviewport support. (Requirements for maintaining: know how to use OpenGL)
7. CImGui.jl now only provides a set of manually written helper functions to make the C API more like the original Dear ImGui API. This wrapper file can be auto-generated in the future by using Clang.jl. I'm also considering adding a default renderer module, so users do not need to work with those boilerplate codes.
8. ImPlot.jl written by @wsphillips provides a high-level Julian API for ImPlot.
9. JuliaImGui/Gallery is a repo for hosting all ImGui-related examples.

The next release(v1.82.0) of CImGui.jl will be breaking, but since it doesn't have many users, I guess it's just OK to not follow the semantic versioning at least for this release.

Anyway, the future direction is definitely to strictly follow semantic versioning. The following list contains the things, I think, that need to be improved before the v2.0.0 release:

• More tutorials (such as How to do simple state-management with pure CImGui #39)
• More unofficial but cool widgets (Toggle Button, Pie menu, Pinned Tooltip, Knob widget, Progress Indicators, Gray-out widget)
• More backends
  • SFML backend (by CSFML.jl) (@dmolina @scls19fr pinging your two guys as you're the member of JuliaMultimedia and may have thoughts on the future of CSFML/SDL)
  • SDL backend (by SimpleDirectMediaLayer.jl, but the audio support of this package has problems, see Warning messages about ALSA lib after fresh install on v0.2.1 JuliaMultimedia/SimpleDirectMediaLayer.jl#52)
  • GR backend (x-ref: Is there a way to use the gr framework with CImGui.jl? #37 from @yadmtr, this example from @jheinen)
  • GLMakie backend (I'm currently working on this. x-ref: this gist and this post from @SteffenPL)
• A font manager package for configuring non-ASCII Characters (x-ref: Unicode is not compatible? #30 from @yongheekim-dev, this post from @oheil)
• An image viewer package (x-ref: Implementing a simple image viewer in Julia #45, this post and this post)

Sorry in advance if this is disturbing, but you guys seem to be the only users of this package, any thoughts would be appreciated! :)

cc @jpsamaroo @sairus7 @iuliancioarca @PinkMushroom @IanButterworth @wookay

[Gnimuc]

imgui.mov

Here is a docking-multiviewport demo. You could also test it locally:

(@v1.6) pkg> dev CImGui

julia> using CImGui

julia> include(joinpath(pathof(CImGui), "..", "..", "examples", "demo.jl"))

[oheil]

The next release(v1.82.0) of CImGui.jl will be breaking, but since it doesn't have many users, I guess it's just OK to not follow the semantic versioning at least for this release.

Of course I am fine with that. Just want to leave an appreciation note here for your hard work! Thank you for your awesome efforts!

[iuliancioarca]

I'm not much of a developer but I hope I will be able to help with some examples. Please let me know how I can help with this topic. And as for the breaking change, no worries. Thank you very much for the hard work put into this package!

[sairus7]

I can help adopting imgui and implot examples to work with tables and new api.
Actually, I just use listboxes for now and looking for tables support.

In general, I think ImGui is underestimated as a working solution for writing GUIs in Julia. Maybe we can provide more pure Julia examples of compleх GUI to gain more popularity. Especially with interactive stuff where using other GUI libraries get overcomplicated.

As for GLMakie backend, for me it seems like it should be in opposite way - CImGui.jl should have some wrappers for Makie plots widget.

[Gnimuc]

I can help adopting imgui and implot examples to work with tables and new api.
Actually, I just use listboxes for now and looking for tables support.

That would be great! I've sent you an invitation so you can get things merged quickly in related repos.

[wsphillips]

Everything looks good but I'm not sure I agree about putting all the generated wrappers into one namespace with default Clang.jl output. At least for cimplot, this makes a lot of work for any user since all the plot functions, and subvariants of those plot functions, are templated.

I don't mind splitting out LibCImPlot from ImPlot.jl, but I would request that LibCImGui.jl partitions each extension library into a separate namespace (module), and that each plugin have it's own generator.jl script that's responsible for the corresponding headers. For instance, LibCImPlot becomes a child module of LibCImGui or something similar. Alternatively, we register LibCImXXX.jl in the JuliaImGui organization for each extension and those packages all depend on LibCImGui.jl

When I find another chunk of time, I intend to use a combination of the metadata output from cimplot and ExprTools.jl to craft a more robust version of the extra pass that I currently do during wrapper generation. The metadata output by the cimplot generator is the same form for cimgui and other extensions. Therefore, if I write this well enough it could be useful to all.

At least with LibCImPlot, the goal is to reconstruct all overloads and default argument values as they are in the original C++ library. Then LibCImPlot would have function calls that map (nearly) 1:1 to those defined in implot.h and ImPlot.jl is only a thin layer responsible for better integration with Julia data types/interfaces (e.g. kwarg syntax, automatic dimensions from arrays, type promotion, etc)

[Gnimuc]

To me, those plot functions can also be generated as:

function PlotLine(label_id, values::Union{AbstractArray{Cfloat}, Ref{Cfloat}, Ptr{Cfloat}}, count::Integer, xscale::Real, x0::Real, offset::Integer, stride::Integer)
    ImPlot_PlotLineFloatPtrInt(label_id, values, count, xscale, x0, offset, stride)
end

where ImPlot_PlotLineFloatPtrInt is from LibCImGui.jl.

The point here is to make the maintenance process easier for new users/contributors. If some users would like to try something new that is not currently supported and the main maintainers don't have time at the moment, those users can quickly update upstream packages 2., 3., 4. by themselves and may add their manually written wrappers to get things to work. In the end, they may submit a PR and become a contributor.

I think it's OK to separate each extension library into an isolated module with its own generator.jl script, but this generator script should be simple, simple enough that the new users should not get stuck in this step. Especially, when something goes wrong, they can figure out a fix on their own. However, generator scripts for generating high-level wrappers are generally not easy to maintain. Even for the package author, it takes a chunk of time to make everything right.
Furthermore, depending on the abstraction level the of generated results, this script may grow rapidly and no one except the author knows the details(e.g. the one in Vulkan.jl). So, these generator scripts should live in high-level packages instead of low-level packages like LibXXX. Anyway, that's my 50 cents.

[PinkMushroom]

I would also like to thank you for all of your work on CImGui. However, I've just recently started using it, and so some of what you talked about doesn't make sense, lol.

Breaking changes are fine with me because i have almost no code other than simple examples written so far.

This package solves a lot of potential problems that I see involving Julia and graphics and gui's and I very much agree with @sairus7 that it is very underestimated as a solution for gui applications . Gtk is so much work and far too heavyweight for what i want to do. I need something that interfaces to OpenGL easily and cleanly. CImGui seems to really fit well for what i want to do.

I do find Dear ImGui to be really unintuitive in some situations therefore more examples are always welcome and I am happy to contribute examples.

[Gnimuc]

Gtk is so much work and far too heavyweight for what i want to do. I need something that interfaces to OpenGL easily and cleanly. CImGui seems to really fit well for what i want to do.

Indeed. Another reason why I prefer to use ImGui is that I don't like those fancy things like reactive programming and my brain hurts when doing the signal-slot pattern with observables. I guess the naive way documented in #39 can cover 80% of the use cases in practice.

[PinkMushroom]

Oh, I should also add that i can't contribute to helping with the actual CImGui project at this time but only because i'm not very familiar with the library. As i become more familiar with it i believe i will be able to help.

[doppioandante]

Hi @Gnimuc , what is the status of this transition?
Should I be using CImGui.jl (this repo) when starting out a new project, or should I be using one of the packages over JuliaImGui?

By the way, it would be cool if you could tag a new release that supported the docking branch.

[pxl-th]

I've been using master branch for my projects a lot and haven't encountered any issues.
It'd be great if we can make a progress and tag a release for CImGUI, since then I can specify compat bounds and register new packages that rely in 1.82.

Do tell if you need some help!

[Gnimuc]

@pxl-th I have invited you as a collaborator. Feel free to make any changes you needed to tag 1.82.

[pxl-th]

Actually for my use cases it all works fine as is, so I'd just go and tag a release if you are fine with that?

[Gnimuc]

Yes. But before tagging a new version, we should at least update the README.

[pxl-th]

Maybe we should also start using semantic version for CImGui.jl?
This will unblock auto-merging for package registration.
Right now we are stuck in a limbo: JuliaRegistries/General#78184

[JamesWrigley]

Hi everyone :) I recently bit the bullet and started updating things for the latest versions of ImGui and ImPlot. I've already opened a bunch of PRs, I'll list them here for completeness (in roughly the order they ought to be merged):

• Fix cycle removal bugs JuliaInterop/Clang.jl#441: Needed fix for generating bindings for the later versions of ImPlot
• v1.89.4 update JuliaImGui/cimgui-pack#1: Update the meta-repo to ImGui v1.89.4, ImPlot v0.14 (and a couple of later commits), and latest master of imnodes
• Update CImGuiPack JuliaPackaging/Yggdrasil#7197: Update CImGuiPack_jll
• Bindings update for v1.89.4 JuliaImGui/LibCImGui.jl#3: Regenerate the bindings for all packages
• Fix an enum to use the new name from ImGui JuliaImGui/ImGuiGLFWBackend.jl#4: Update for the latest bindings
• Update wrapper for v1.89.4 #87: Update the CImGui.jl wrappers
• Implot update wsphillips/ImPlot.jl#27: Update ImPlot.jl for ImPlot v0.14

I've tested all of these locally and the demos seem to work fine with no regressions. I have absolutely no idea how to handle versioning/compat bounds for all of them 🙈

[JamesWrigley]

Thanks @Gnimuc for bumping the CImGuiPack.jll version 😅 Am I correct in thinking that the plan should now be:

• Merge Fix an enum to use the new name from ImGui JuliaImGui/ImGuiGLFWBackend.jl#4 and make a v1 release (because it's breaking and we can follow semver for it).
• Make a 1.89.4 release for LibCImGui.jl
• Bump the CImGui.jl compat bounds for LibCImGui.jl, merge Update wrapper for v1.89.4 #87, and make a new release
• Bump the ImPlot.jl compat bounds for CImGui.jl, merge Implot update wsphillips/ImPlot.jl#27, and make a new release

I must say the lack of semver is really biting us here 😬 Does it make sense to have strict compat bounds?

[JamesWrigley]

Uhh I'm dumb, I forgot I already made a 1.89.4 release for LibCImGui.jl. Should we yank that and make a new one with JuliaImGui/LibCImGui.jl#6?

[Gnimuc]

@JamesWrigley is there any caveat to tag a new version 1.89.5?

[Gnimuc]

I suppose the new patch version will always be upgraded, so finally the buggy 1.89.4 will be "yanked" automatically.

[JamesWrigley]

I think the only reason not to would be to stay in sync with imgui upstream. I'm not sure how important that is to us, but if the intention is to keep LibCImGui.jl as the 'base' package that others build off of then I'm inclined to stick with upstream.

But that could be annoying. Maybe we could only commit to keeping the major/minor versions in sync with upstream and keep the patch number for ourselves? (possibly confusing)

[Gnimuc]

But that could be annoying. Maybe we could only commit to keeping the major/minor versions in sync with upstream and keep the patch number for ourselves? (possibly confusing)

I guess it's ok to not sync the patch number because Dear Imgui rarely introduces breaking changes between patch versions.

[JamesWrigley]

Ok, that sounds good to me 👍 I'll prepare some PRs for the new release.

[JamesWrigley]

Alrighty, opened a bunch of new PRs. These ones bump package versions to work with new LibCImGui.jl versions:

• Release v1.89.5 JuliaImGui/LibCImGui.jl#7
• Bump version to 0.2 JuliaImGui/ImGuiGLFWBackend.jl#6
• Bump version to 0.2 JuliaImGui/ImGuiOpenGLBackend.jl#6

And these ones restrict compat bounds to the old versions of the above packages so we don't break things too much (in hindsight this is probably the first thing I should've done):

• Restrict LibCImGui.jl compat bounds #90
• Restrict LibCImGui.jl compat bounds wsphillips/ImPlot.jl#28

Does that look right? Not an expert with this stuff 😅

[Gnimuc]

I don't think this package has many users, so as long as there are no more new compatibility issues, I suppose we are not breaking things. 😅

[JamesWrigley]

Ok, all the dependencies have new versions 👍 I think CImGui.jl and ImPlot.jl should have a minor release with those PRs I made to make sure they pull the right versions. Apart from that, I think #87 and wsphillips/ImPlot.jl#27 are ready to be merged.

[JamesWrigley]

At last, all PRs merged 🎉 Thanks everyone for the help ❤️

[JamesWrigley]

Are there any objections to me merging the cimgui-pack and LibCImGui repos into this one, similar to how Makie.jl has sub-projects for GLMakie/CairoMakie? The reason is because I find switching between the repos very annoying and I think it's easier to have them all in one place because they're all quite tightly related to each other.

Also, how do we feel about dropping the adherence to ImGui's versioning? Managing breaking changes is kinda a pain, and I think it would end up being better for downstream users if we adopted semantic versioning.

[JamesWrigley]

Lol, I guess cimgui-pack must be resurrected 😆 Turns out that one can't register a package with a git submodule: JuliaLang/Pkg.jl#708

[sairus7]

BinaryBuilder doesn't support taking source code from different repos? https://github.com/JuliaPackaging/Yggdrasil/blob/master/C/CImGuiPack/build_tarballs.jl

[JamesWrigley]

It's not BinaryBuilder, it's Pkg and the general registry: JuliaRegistries/General#109914

[sairus7]

I mean, if you can manually list cimgui, cimnodes and cimplot repos with commit hashes in build_tarballs.jl sources list and compile them all at once, then you don't need cimgui-pack. But then you would need to update recipe with each new imgui release: https://github.com/JuliaPackaging/Yggdrasil?tab=readme-ov-file#updating-the-version-of-an-existing-builder

[JamesWrigley]

Yeah but it's not just those anymore, it's also all the test engine stuff which is quite a few files. I think it's easier to have it in a separate repo.

[JamesWrigley]

People! I'm attempting to deprecate our custom GLFW/OpenGL backends in favour of the official backends in #122. It works on my Linux system, but I would very much appreciate it if other folks could follow the instructions in the PR to test it locally on your systems :) In particular OSX and Windows. Note that only demo/demo.jl will work right now, I haven't updated the rest of the wrappers (but luckily that should be enough for testing the backends).

Also, who's using the opengl 2 backend? @jpsamaroo /@IanButterworth?

[JamesWrigley]

If there's no objections, I'll merge LibCImGui under CImGui.lib tomorrow and make new releases of everything.

[sairus7]

I don't have any objections, if they lead to simpler structure. Maybe @Gnimuc has?
In he first post are the reasons to keep LibCImGui separate, so here are some questions to think about:

1. Track exact imgui version. As I can see, CImGuiPack_jll has its own versioning, then how should user know which imgui version he is using (and refer to the corresponding API)? Maybe have a separate function for this?
2. LibCImGui package is fully auto-generated using Clang.jl with generator script (Requirements for maintaining: know how to install Julia package and run Julia script.). I think we should at least keep auto-generated part in a separate subfolder / subproject, so we can update it easily just by running build script with no manual copy-paste.

[sairus7]

From my experience, there are many symbols that are not exported from LibCImGui into CImGui, so user would often write CImGui.LibCImGui.<function_name>. So from user perspective LibCImGui looks redundant. How should that code change for newer version?

[sairus7]

Oh, and another consequence from having separate LibCImGui - ImPlot package depends only on LibCImGui, but not CImGui. Those two packages (CImGui and ImPlot) are treated as separate wrappers around LibCImGui, with the potential to make someone's own wrapper. It seems to me that nobody will do that, as long as the wrapper remains quite straightforward (types and function signatures are preserved). So maybe even ImPlot can be merged here?..

[JamesWrigley]

1. Track exact imgui version. As I can see, CImGuiPack_jll has its own versioning, then how should user know which imgui version he is using (and refer to the corresponding API)? Maybe have a separate function for this?

Agreed, I added a imgui_version() function in c069d63 to get the current version. But in general my hope is that this package will never to be too many versions behind upstream so folks don't have to worry too much about the versioning :) I think the test engine will make that simpler since we can now write tests for CImGui. I've already written some but CImGui and ImGuiTestEngine are in a bit of chicken-and-egg situation at the moment so I'm going to release CImGui first, and then ImGuiTestEngine, and then add the tests to CImGui 😅

2. LibCImGui package is fully auto-generated using Clang.jl with generator script (Requirements for maintaining: know how to install Julia package and run Julia script.). I think we should at least keep auto-generated part in a separate subfolder / subproject, so we can update it easily just by running build script with no manual copy-paste.

Agreed, that's how I merged it in 72d4ca7.

From my experience, there are many symbols that are not exported from LibCImGui into CImGui, so user would often write CImGui.LibCImGui.<function_name>. So from user perspective LibCImGui looks redundant. How should that code change for newer version?

That shouldn't change much :) It'll be CImGui.lib.<function_name>, or they can run using CImGui.lib and import everything.

Oh, and another consequence from having separate LibCImGui - ImPlot package depends only on LibCImGui, but not CImGui. Those two packages (CImGui and ImPlot) are treated as separate wrappers around LibCImGui, with the potential to make someone's own wrapper. It seems to me that nobody will do that, as long as the wrapper remains quite straightforward (types and function signatures are preserved). So maybe even ImPlot can be merged here?..

Mmmm, we could but I don't think that's necessary. ImPlot.jl is kinda a lot of code to add to the package, and I imagine many users won't need it. I think it's fine for ImPlot.jl to depend on CImGui and use the CImGui.lib module, like ImGuiTestEngine.jl is doing.