Move Imgui integration

[Squareys]

Hi all!

This is the WIP PR for my efforts to move various magnum-imgui projects (by @lecopivo https://github.com/lecopivo/magnum-imgui and @denesik and forks by @nnarain, @williamjcm and @ShaddyDC) into the official repository.

Cheers, Jonathan

TODOs:

• Add code from other repos
• CMake setup
• Add to find module
• Migrate example => ImGuiIntegration example magnum-examples#51
  • Fix duplicate symbols issue with current find method
• Add a test
• Build on CI
• Adapt Code Style
• Add documentation
• Re-check mentions in the license headers

[codecov-io]

Codecov Report

Merging #33 into master will increase coverage by 13.37%.
The diff coverage is 100%.

@@             Coverage Diff             @@
##           master      #33       +/-   ##
===========================================
+ Coverage   58.34%   71.72%   +13.37%     
===========================================
  Files          16       11        -5     
  Lines         557      244      -313     
===========================================
- Hits          325      175      -150     
+ Misses        232       69      -163

Impacted Files	Coverage Δ
src/Magnum/ImGuiIntegration/Conversion.h	100% <100%> (ø)
src/Magnum/BulletIntegration/MotionState.cpp	78.94% <0%> (-6.77%)	⬇️
src/Magnum/BulletIntegration/DebugDraw.cpp	12.82% <0%> (-3.09%)	⬇️
src/Magnum/GlmIntegration/GtcIntegration.h	100% <0%> (ø)	⬆️
src/Magnum/DartIntegration/ConvertShapeNode.cpp
src/Magnum/DartIntegration/Object.h
src/Magnum/DartIntegration/World.h
src/Magnum/DartIntegration/World.cpp
src/Magnum/DartIntegration/Object.cpp
src/Magnum/DartIntegration/ConvertShapeNode.h
... and 1 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 4746753...8f0b416. Read the comment docs.

[mosra]

FYI, just found this: https://gitlab.com/caleb-vincent/MagnumImGui so maybe that has also some changes worth integrating (if you would open an issue there notifying the author about this merge, that would be great 👍)

[Squareys]

@mosra Issues are not open on that project. Found a change, though, that I will integrate 👍

* Edit: A similiar change was already present in the other repo.

[Squareys]

@mosra The code would be ready for some initial rough review pass. The documentation is not done yet, though.

(There is currently a pending issue with the example still, though, so really, just rough review... or wait another two days)

[mosra]

This looks pretty much finished to me already :) Great work, looking forward for the final thing.

[mosra]

Not sure about the REQUIRED here -- if find_package(MagnumIntegration OPTIONAL) would be used, this will break. (But OTOH I also don't know what's the proper way of doing this, I'm only saying find_package(Name) everywhere.)

[Squareys]

Ah, right, now I remember why we had a discussion about this once :D

[Squareys]

Documentation says "REQUIRED stops processing on error message", hence manually outputting an error message would make it stop if find_package(MagnumIntegration REQUIRED ImGui) whereas OPTIONAL would print the error message but continue processing...?

[Squareys]

OTOH, the error message will be output by find_package(ImGui) already... right? So it will stop processing there, I'd expect...

[mosra]

Not sure, probably not. We need to revisit this later, maybe we need to add REQUIRED based on value of MagnumIntegration_FIND_REQUIRED_ImGui ... but that then needs to be done for everything.

[mosra]

Can you remove the REQUIRED, then?

[mosra]

Thinking out loud: we depend on particular version and since imgui backwards compatibility is broken quite often (at least by looking at changes in bgfx) it should be probably mentioned in the docs what version this integration supports.

[Squareys]

In this case it would almost make sense to just bundle it in external 🙈 (As submodule would be best, but that's non-trivial to use as non-git user... but if well documented...)

[mosra]

Well, I hope the changes are not so drastic (and I assume it will get more stable and better backward-compatible with upcoming versions). This is similar to OVR integration, no? There it was also recommending a version but it usually worked with newer ones as well.

[mosra]

No need for this here ;)

[mosra]

Still not fixed ;)

[Squareys]

@mosra Ready for review!

Open questions (/for follow up):

• vcpkg requires support for linking imgui as lib rather than compiling in the code
• Supported imgui version is mentioned nowhere
• REQUIRED in FindMagnumIntegration

[mosra]

There are still 2 unresolved comments (collapsed by GitHub) from before, one for the code snippet and one for minor code formatting. Besides that:

• there's some dllexport/dllimport issue on MinGW. Not sure why is that?
• the Emscripten (at least WebGL 2) build should be working too (it was working in the original repos)
• same for iOS ES3 I think
• there's lots of compiler warnings due to our very strict warning levels, not sure how to disable these for the interface sources (todo for myself)
• doc/namespaces.dox is missing the license info (i'm sure i mentioned this before somewhere, but can't find where)
• the comments below :)

I need to hurry up with the CI updates to make Travis working. I also need to test this locally before merging (+ do the "note to self" things).

[mosra]

I have a feeling that the two lines above are also wrapped in some if() for the builtin shaders. I'll look into this.

[Squareys]

So after looking into this, what do you say? (I am not sure whether I understand what this is about, btw...)

[mosra]

Oh! I'll look into this during the merge, I meant.

[mosra]

For the CI failures, it looks like you forgot to add the file in doc/snippets ;)

[Squareys]

• there's some dllexport/dllimport issue on MinGW. Not sure why is that?
  - Fixed seven days ago in imgui (not released yet)
• the Emscripten (at least WebGL 2) build should be working too (it was working in the original repos)
• same for iOS ES3 I think
• doc/namespaces.dox is missing the license info (i'm sure i mentioned this before somewhere, but can't find where)
• the comments below

[mosra]

Last comments from me before merge. The rest (such as ES2 / WebGL 1 shader compat) I'll do post-merge.

[mosra]

Maybe also enable blending only for the draw call?

[Squareys]

I assume you mean disabling it again after

[mosra]

Can you remove the REQUIRED, then?

[mosra]

Still not fixed ;)

[williamjcm]

Would it be possible for the official integration to have a way to load custom fonts ?

I currently have a customised version of nnarain's integration, and I had to edit it to add code to load my own fonts.

I went to this line, and added the following before it:

io.Fonts->AddFontFromFileTTF("aller.ttf",
                             16.0f,
                             nullptr,
                             ranges.Data);
io.Fonts->AddFontFromFileTTF("aller.ttf",
                             18.0f,
                             nullptr,
                             ranges.Data);
io.Fonts->AddFontFromFileTTF("aller.ttf",
                             20.0f,
                             nullptr,
                             ranges.Data);
io.Fonts->AddFontFromFileTTF("aller.ttf",
                             22.0f,
                             nullptr,
                             ranges.Data);

As you can see, I load the same font multiple times at different sizes (to fit users' needs).

I don't specify a custom font config (hence the nullptr as the third parameter), but I use a custom character range (the ranges variable) to add support for all the glyphs in the font. Therefore, having both as optional parameters in the integration could be a possibility.

Here's the ImGui documentation about fonts: https://github.com/ocornut/imgui/blob/67775448556d8dba304657719829f1ab768b3c97/imgui.cpp#L764-L838 and https://github.com/ocornut/imgui/blob/master/misc/fonts/README.txt

[Squareys]

@williamjcm You can still add those lines after calling the Magnum::ImGuiIntegration::Context constructor in your user code. If you use ImGui::GetIO(), you will retrieve the same IO struct that is being used by Magnum.

Otherwise a more magnum-like solution (? @mosra ) would probably be to allow ImGui to use Magnum::Text::AbstractFont somehow, but since this is likely quite a bit of work, it will definitely not be part of this PR.

[williamjcm]

The code that generates the font texture data is in the integration, however.

Link to nnarain's version of the integration: https://github.com/nnarain/magnum-imgui/blob/256968783121306c65ddfb5c28906140f2ccf947/src/MagnumImGui.cpp#L76-L84

[Squareys]

Oh! True, sorry, thanks for the hint!

@mosra Maybe it would be best to add a dependency on AbstractFont here then and let that generate the glyph texture instead? I wouldn't expect the textures to be compatible, though, so maybe a "generateFonts" or something as a second step after Context initialization. I wonder how we could make that "unforgetible", i.e. an optional second step if no custom font needs to be loaded 🤔

[williamjcm]

Maybe two constructors, with one asking for a file name among its parameter ?

And once the object is constructed, a method could allow generating even more fonts as needed, maybe with optional arguments like ImGui font config and character ranges.

[mosra]

Shower thoughts: I finally can see a bit into how this whole thing works, so if I understand correctly, all you need is to be able to do some stuff between ImGui::CreateContext() and io.Fonts->GetTexDataAsRGBA32(), right?

So let's no overdo this. Could the following new constructor cover your case? (the parameter is just to distinguish the intention, otherwise not really needed)

[williamjcm]

I like that idea.

It would give more control to the integration's users who want it, while still giving a "I don't care" option to those who just want to get ImGui up and running.

[mosra]

I merged the PR with the following changes:

• The headers are renamed to Context.h for the Context class and Integration.h for the math integration, to be more in-line with the naming elsewhere
• The above proposal for custom fonts is integrated
• The API had to be changed for DPI awareness, so instead of nextFrame() taking window / framebuffer size, a tuple of UI size, window size and framebuffer size is passed to the constructor and there's a new relayout() function to handle window size or pixel density changes. This is basically equivalent to how it's done in the Ui library, so you can just reuse the logic from there. The docs (which I'll be uploading later) explain the interactions of DPI awareness with custom fonts.
• The singleton and get() is no more, instead you are expected to handle a singleton yourself, if needed -- when working on the example I realized that the singleton was not needed at all, since the only place where the nextFrame() / drawFrame() and event functions were called was in the main app code, which also is the owner of the Context instance. This allowed me to make it move-aware, have a NoCreate constructor and support multiple contexts, and also removing all restrictive singleton-related assertions from the internals.
• The image() widget now has the UV range represented as Range2D instead of a pair of vectors.
• There's also conversion between Color3 and ImColor, to allow things like ImColor(0xff3366_rgbf) (and avoid crazy implicit-conversion-caused bugs, more in the docs)
• Mouse position is registered also for mouse move / scroll events, for some reason it was done only for mouse move event, which would cause issues on touchscreens (which have no move events reported)
• The Context class is now marked as experimental, since I'm not really sure how to implement a Vulkan backend yet and it might involve some renaming, so better safe than sorry ;)

I did not bother with port to ES2 / WebGL 1 yet since that would delay the merge by another year, will do that later. I'm now working on the example, will upload the docs once I have the example updated and merged as well.

Feedback and bugreports very appreciated :)