Added helpers for GetWindowPos/GetWindowSize/GetWindowFramebufferScale/GetWindowWorkAreaInsets (#92)

Author: ShironekoBen

dear_bindings.py

@@ -1,4 +1,4 @@
-# Dear Bindings Version v0.12 WIP
+# Dear Bindings Version v0.12
 # Generates C-language headers for Dear ImGui
 # Developed by Ben Carter (e-mail: ben AT shironekolabs.com, github: @ShironekoBen)
 
@@ -112,6 +112,12 @@ def convert_header(
     main_src_root = parse_single_header(src_file, context)
     dom_root.add_child(main_src_root)
 
+    # Check if the version of ImGui we are dealing with has docking support
+    have_docking_support = False
+    for define in dom_root.list_all_children_of_type(code_dom.DOMDefine):
+        if define.name == 'IMGUI_HAS_DOCK':
+            have_docking_support = True
+
     # Assign a destination filename based on the output file
     dest_file_name_only = os.path.basename(dest_file_no_ext)
     _, main_src_root.dest_filename = os.path.split(dest_file_no_ext)
@@ -221,6 +227,37 @@ def convert_header(
                                    "(ImVector_Construct()/ImVector_Destruct() can be used to safely "
                                    "construct out_ranges)")
 
+    # If we have docking support, add some functions to allow overriding platform IO functions that return structures
+    if have_docking_support:
+        # Implementation for these is in templates/imgui-header-template.cpp
+        mod_add_manual_helper_functions.apply(dom_root,
+                                              [
+                                                  "void ImGuiPlatformIO_SetPlatform_GetWindowPos(void(*getWindowPosFunc)(ImGuiViewport* vp, ImVec2* result)); "
+                                                  "// Set ImGuiPlatformIO::Platform_GetWindowPos in a C-compatible mannner",
+                                                  "void ImGuiPlatformIO_SetPlatform_GetWindowSize(void(*getWindowPosFunc)(ImGuiViewport* vp, ImVec2* result)); "
+                                                  "// Set ImGuiPlatformIO::Platform_GetWindowSize in a C-compatible mannner",
+                                                  "void ImGuiPlatformIO_SetPlatform_GetWindowFramebufferScale(void(*getWindowPosFunc)(ImGuiViewport* vp, ImVec2* result)); "
+                                                  "// Set ImGuiPlatformIO::Platform_GetWindowFramebufferScale in a C-compatible mannner",
+                                                  "void ImGuiPlatformIO_SetPlatform_GetWindowWorkAreaInsets(void(*getWindowPosFunc)(ImGuiViewport* vp, ImVec4* result)); "
+                                                  "// Set ImGuiPlatformIO::Platform_GetWindowWorkAreaInsets in a C-compatible mannner"
+                                              ])
+        # Add comments to try and point people at the helpers
+        mod_add_field_comment.apply(dom_root,
+                                   "ImGuiPlatformIO::Platform_GetWindowPos",
+                                   "(Use ImGuiPlatformIO_SetPlatform_GetWindowPos() to set this from C)")
+
+        mod_add_field_comment.apply(dom_root,
+                                    "ImGuiPlatformIO::Platform_GetWindowSize",
+                                    "(Use ImGuiPlatformIO_SetPlatform_GetWindowSize() to set this from C)")
+
+        mod_add_field_comment.apply(dom_root,
+                                    "ImGuiPlatformIO::Platform_GetWindowFramebufferScale",
+                                    "(Use ImGuiPlatformIO_SetPlatform_GetWindowFramebufferScale() to set this from C)")
+
+        mod_add_field_comment.apply(dom_root,
+                                    "ImGuiPlatformIO::Platform_GetWindowWorkAreaInsets",
+                                    "(Use ImGuiPlatformIO_SetPlatform_GetWindowWorkAreaInsets() to set this from C)")
+
     mod_set_arguments_as_nullable.apply(dom_root, ["fmt"], False)  # All arguments called "fmt" are non-nullable
     mod_remove_operators.apply(dom_root)
     mod_remove_heap_constructors_and_destructors.apply(dom_root)

docs/Changelog.txt

@@ -1,6 +1,9 @@
---- v0.12 WIP
+--- v0.12
 
 * Copy the returned value to a temporary variable when the stub function needs to call to va_end (thanks to tanoxyz)
+* Added helpers for GetWindowPos/GetWindowSize/GetWindowFramebufferScale/GetWindowWorkAreaInsets in PlatformIO
+  (in the Docking branch) so that a C function can be set as a callback despite the return value being a structure
+  (#92)
 
 --- v0.11
 

docs/Readme.md

@@ -28,14 +28,15 @@ intended for easy integration with automated build pipelines.
 
 # Recent changes
 
+* v0.12 adds support for setting certain `PlatformIO` callbacks in the docking branch that were previously not usable from C due to their return types. See the `PlatformIO callbacks` section below for full details. 
 * v0.11 introduces a small-but-significant breaking change as the output file names are now `dcimgui` instead of `cimgui` (to disambiguate in cases where people are using multiple binding generators) 
 * v0.10 adds (somewhat experimental) support for comverting `imgui_internal.h`.
 * v0.08 adds structure default values to metadata, and fixes a few bugs.
 * v0.07 adds some new metadata elements, new examples and fixes a number of bugs (especially around metadata and backends).
 * v0.06 fixes a small issue with ImGui v1.90.0 WIP where `ListBox()` and `ComboBox()` have deprecated variants that cause name clashes. Those variants are now renamed to `ImGui_ListBoxObsolete()` and `ImGui_ComboBoxObsolete()` respectively.
-* v0.05 introduced significantly enhanced type information in the JSON output, and experimental support for generating bindings for ImGui backends
-  * Note that there are a number of small changes in the JSON format related to this that will require modification to code that consumes the JSON files - search [Changelog.txt](Changelog.txt) for `BREAKING CHANGE` for full details
-* v0.04 introduced a number of bugfixes and other tweaks
+* v0.05 introduced significantly enhanced type information in the JSON output, and experimental support for generating bindings for ImGui backends.
+  * Note that there are a number of small changes in the JSON format related to this that will require modification to code that consumes the JSON files - search [Changelog.txt](Changelog.txt) for `BREAKING CHANGE` for full details.
+* v0.04 introduced a number of bugfixes and other tweaks.
 
 You can see a full list of recent changes [here](Changelog.txt).
 
@@ -284,6 +285,30 @@ Templates are expanded into their concrete instantiations, so for example `ImVec
 
 > See the note above about `ImVector_Construct` for an exception to this rule.
 
+### PlatformIO callbacks
+
+Some of the PlatformIO callbacks (at present only in the Docking branch of Dear ImGui) return structures, which means that they cannot be directly set to C functions - notably these four:
+
+```cpp
+ImVec2  (*Platform_GetWindowPos)(ImGuiViewport* vp);
+ImVec2  (*Platform_GetWindowSize)(ImGuiViewport* vp);
+ImVec2  (*Platform_GetWindowFramebufferScale)(ImGuiViewport* vp);
+ImVec4  (*Platform_GetWindowWorkAreaInsets)(ImGuiViewport* vp);
+```
+
+To avoid this issue, Dear Bindings provides corresponding setter functions that take a C function and automatically insert a C++ thunk that converts the return value appropriately.
+
+```cpp
+void ImGuiPlatformIO_SetPlatform_GetWindowPos(void (*getWindowPosFunc)(ImGuiViewport* vp, ImVec2* result));
+void ImGuiPlatformIO_SetPlatform_GetWindowSize(void (*getWindowPosFunc)(ImGuiViewport* vp, ImVec2* result));
+void ImGuiPlatformIO_SetPlatform_GetWindowFramebufferScale(void (*getWindowPosFunc)(ImGuiViewport* vp, ImVec2* result));
+void ImGuiPlatformIO_SetPlatform_GetWindowWorkAreaInsets(void (*getWindowPosFunc)(ImGuiViewport* vp, ImVec4* result));
+```
+
+Note that internally these functions have to allocate a small structure to store the thunk information. This gets stored in the `BackendLanguageUserData` member of `ImGuiIO`, so if you application is using that for other purposes you will not be able to use these functions (in that case, you'll need to either implement your own thunk with the data stored elsewhere, or get in touch to see if we can find another place to store this data).
+
+Also, there is a (small) dynamic allocation associated with this, so if you need to ensure absolutely all memory is freed then when you finish with the ImGui context you should use the helper functions to set the callbacks to `null` - once all the callbacks are removed the allocated memory will be freed.  
+
 ### Removed functionality
 
 These minor features are removed, mostly because they either rely on C++ language features to function correctly or are helpers that don't make sense as part of the bindings.

src/modifiers/__init__.py

@@ -62,4 +62,5 @@
 from . import mod_replace_typedef_with_opaque_buffer
 from . import mod_change_class_field_type
 from . import mod_rename_prefix
-from . import mod_mark_structs_as_single_line_definition
+from . import mod_mark_structs_as_single_line_definition
+from . import mod_add_field_comment

src/modifiers/mod_add_field_comment.py

@@ -0,0 +1,10 @@
+from src import code_dom
+from src import utils
+
+
+# This modifier adds a comment to the field with the fully-qualified name given
+# If a comment already exists the comment text will be appended to it with a space
+def apply(dom_root, field_name, comment):
+    for function in dom_root.list_all_children_of_type(code_dom.DOMFieldDeclaration):
+        if function.get_fully_qualified_name() == field_name:
+            utils.append_comment_text(function, comment)

src/templates/imgui-header-template.cpp

@@ -51,3 +51,152 @@ static inline ::ImStr MarshalToCPP_ImStr_FromCharStr(const char* b)
 }
 #endif // IMGUI_HAS_IMSTR
 #endif // defined(IMGUI_HAS_IMSTR)
+
+// Helpers for setting callbacks that return complex structures in PlatformIO
+// These require a thunk in C++-land to work correctly, which is implemented here
+
+#if defined(IMGUI_HAS_DOCK)
+
+namespace
+{
+    // Data we use in the thunk to convert these from C++-style callbacks to C-style callbacks
+    struct ImGui_DearBindingsThunkData
+    {
+        void(*PlatformIO_GetWindowPos_ThunkTarget)(cimgui::ImGuiViewport* vp, cimgui::ImVec2* result);
+        void(*PlatformIO_GetWindowSize_ThunkTarget)(cimgui::ImGuiViewport* vp, cimgui::ImVec2* result);
+        void(*PlatformIO_GetWindowFramebufferScale_ThunkTarget)(cimgui::ImGuiViewport* vp, cimgui::ImVec2* result);
+        void(*PlatformIO_GetWindowWorkAreaInsets_ThunkTarget)(cimgui::ImGuiViewport* vp, cimgui::ImVec4* result);
+    };
+
+    // Get our thunk data for the current ImGui context, creating it if necessary
+    ImGui_DearBindingsThunkData* ImGui_GetDearBindingsThunkData()
+    {
+        ImGuiIO& io = ImGui::GetIO();
+        if (!io.BackendLanguageUserData)
+        {
+            io.BackendLanguageUserData = IM_NEW(ImGui_DearBindingsThunkData);
+            memset(io.BackendLanguageUserData, 0, sizeof(ImGui_DearBindingsThunkData));
+        }
+        return reinterpret_cast<ImGui_DearBindingsThunkData*>(io.BackendLanguageUserData);
+    }
+
+    // Tidy up our thunk data, deleting it if all the target pointers are null (i.e. it is unused)
+    void ImGui_TidyDearBindingsThunkData()
+    {
+        ImGuiIO& io = ImGui::GetIO();
+        if (io.BackendLanguageUserData)
+        {
+            ImGui_DearBindingsThunkData* thunkData = reinterpret_cast<ImGui_DearBindingsThunkData*>(io.BackendLanguageUserData);
+            if ((!thunkData->PlatformIO_GetWindowPos_ThunkTarget) &&
+                (!thunkData->PlatformIO_GetWindowSize_ThunkTarget) &&
+                (!thunkData->PlatformIO_GetWindowFramebufferScale_ThunkTarget) &&
+                (!thunkData->PlatformIO_GetWindowWorkAreaInsets_ThunkTarget))
+            {
+                // Thunk data is unused and can be freed
+                io.BackendLanguageUserData = nullptr;
+                IM_DELETE(thunkData);
+            }
+        }
+    }
+
+    // Copies of the conversion stubs in order to deal with the fact that they are declared later in the file
+    // Fixme: This is a little messy, but reordering things is also fiddly to do
+
+    static inline ::ImVec2 ConvertToCPP_ImVec2_ForThunks(const cimgui::ImVec2& src)
+    {
+        ::ImVec2 dest;
+        dest.x = src.x;
+        dest.y = src.y;
+        return dest;
+    }
+
+    static inline ::ImVec4 ConvertToCPP_ImVec4_ForThunks(const cimgui::ImVec4& src)
+    {
+        ::ImVec4 dest;
+        dest.x = src.x;
+        dest.y = src.y;
+        dest.z = src.z;
+        dest.w = src.w;
+        return dest;
+    }
+
+    // Thunks for callbacks that need them
+
+    ImVec2 ImGuiPlatformIO_GetWindowPos_Thunk(ImGuiViewport* vp)
+    {
+        ImGui_DearBindingsThunkData* thunkData = ImGui_GetDearBindingsThunkData();
+        cimgui::ImVec2 result;
+        thunkData->PlatformIO_GetWindowPos_ThunkTarget(reinterpret_cast<cimgui::ImGuiViewport*>(vp), &result);
+        return ConvertToCPP_ImVec2_ForThunks(result);
+    }
+
+    ImVec2 ImGuiPlatformIO_GetWindowSize_Thunk(ImGuiViewport* vp)
+    {
+        ImGui_DearBindingsThunkData* thunkData = ImGui_GetDearBindingsThunkData();
+        cimgui::ImVec2 result;
+        thunkData->PlatformIO_GetWindowSize_ThunkTarget(reinterpret_cast<cimgui::ImGuiViewport*>(vp), &result);
+        return ConvertToCPP_ImVec2_ForThunks(result);
+    }
+
+    ImVec2 ImGuiPlatformIO_GetWindowFramebufferScale_Thunk(ImGuiViewport* vp)
+    {
+        ImGui_DearBindingsThunkData* thunkData = ImGui_GetDearBindingsThunkData();
+        cimgui::ImVec2 result;
+        thunkData->PlatformIO_GetWindowFramebufferScale_ThunkTarget(reinterpret_cast<cimgui::ImGuiViewport*>(vp), &result);
+        return ConvertToCPP_ImVec2_ForThunks(result);
+    }
+
+    ImVec4 ImGuiPlatformIO_GetWindowWorkAreaInsets_Thunk(ImGuiViewport* vp)
+    {
+        ImGui_DearBindingsThunkData* thunkData = ImGui_GetDearBindingsThunkData();
+        cimgui::ImVec4 result;
+        thunkData->PlatformIO_GetWindowWorkAreaInsets_ThunkTarget(reinterpret_cast<cimgui::ImGuiViewport*>(vp), &result);
+        return ConvertToCPP_ImVec4_ForThunks(result);
+    }
+} // Anonymous namespace
+
+CIMGUI_API void cimgui::ImGuiPlatformIO_SetPlatform_GetWindowPos(void(*func)(cimgui::ImGuiViewport* vp, cimgui::ImVec2* result))
+{
+    ImGui_DearBindingsThunkData* thunkData = ImGui_GetDearBindingsThunkData();
+    thunkData->PlatformIO_GetWindowPos_ThunkTarget = func;
+    ::ImGui::GetPlatformIO().Platform_GetWindowPos = (func != nullptr) ? ImGuiPlatformIO_GetWindowPos_Thunk : nullptr;
+    if (!func)
+    {
+        ImGui_TidyDearBindingsThunkData(); // Try to release thunk data if no longer required
+    }
+}
+
+CIMGUI_API void cimgui::ImGuiPlatformIO_SetPlatform_GetWindowSize(void(*func)(cimgui::ImGuiViewport* vp, cimgui::ImVec2* result))
+{
+    ImGui_DearBindingsThunkData* thunkData = ImGui_GetDearBindingsThunkData();
+    thunkData->PlatformIO_GetWindowSize_ThunkTarget = func;
+    ::ImGui::GetPlatformIO().Platform_GetWindowSize = (func != nullptr) ? ImGuiPlatformIO_GetWindowSize_Thunk : nullptr;
+    if (!func)
+    {
+        ImGui_TidyDearBindingsThunkData(); // Try to release thunk data if no longer required
+    }
+}
+
+CIMGUI_API void cimgui::ImGuiPlatformIO_SetPlatform_GetWindowFramebufferScale(void(*func)(cimgui::ImGuiViewport* vp, cimgui::ImVec2* result))
+{
+    ImGui_DearBindingsThunkData* thunkData = ImGui_GetDearBindingsThunkData();
+    thunkData->PlatformIO_GetWindowFramebufferScale_ThunkTarget = func;
+    ::ImGui::GetPlatformIO().Platform_GetWindowFramebufferScale = (func != nullptr) ? ImGuiPlatformIO_GetWindowFramebufferScale_Thunk : nullptr;
+    if (!func)
+    {
+        ImGui_TidyDearBindingsThunkData(); // Try to release thunk data if no longer required
+    }
+}
+
+CIMGUI_API void cimgui::ImGuiPlatformIO_SetPlatform_GetWindowWorkAreaInsets(void(*func)(cimgui::ImGuiViewport* vp, cimgui::ImVec4* result))
+{
+    ImGui_DearBindingsThunkData* thunkData = ImGui_GetDearBindingsThunkData();
+    thunkData->PlatformIO_GetWindowWorkAreaInsets_ThunkTarget = func;
+    ::ImGui::GetPlatformIO().Platform_GetWindowWorkAreaInsets = (func != nullptr) ? ImGuiPlatformIO_GetWindowWorkAreaInsets_Thunk : nullptr;
+    if (!func)
+    {
+        ImGui_TidyDearBindingsThunkData(); // Try to release thunk data if no longer required
+    }
+}
+
+#endif // defined(IMGUI_HAS_DOCK)