luau_imgui

Luau binding generator for Dear ImGui. ImGui initialization and resource management is expected to happen on the host side, and only some GUI calls from Luau side.

• Create a json generator config, you can start from the one provided
• Generate with ./generator.py generator_config.json output.cpp output.md

The goal of this project was to generate easy to read, well commented Luau wrapper functions for ImGui. The generator code is implemented Python3. It uses the regex module for recursive regexes, parsing the C++ headers. Adding some heuristics on top and we have generated wrapper functions.

The generator script will filter out functions that can not be implemented in Luau (for example function pointer arguments), you will get a warning about every C++ function skipped. The generator will analyze the enums used in the final set of functions and will only provide the used ones as globals.

Generated C++ host code

The code generates 2 C++ functions.

One to add the Lua globals to the Lua state: int luaopen_libimgui(lua_State* L)

One to fix unbalanced Begin-End or Push-Pop function calls: void lua_imgui_guard()

Generated Lua code

Check out the generated code. Also check out the small lua test program.

Lua does not have pointers or references, but has multiple return values. Input/output pointers become arguments and returns. ImGui flags are single numbers or table of numbers.

C++: IMGUI_API bool ColorEdit3(const char* label, float col[3], ImGuiColorEditFlags flags = 0)
Lua: col : table of 3 numbers, cpp_ret : boolean = ImGui.ColorEdit3(label : string, col : table of 3 numbers, flags : optional flag (number or table of numbers))

color1 = ImGui.ColorEdit3("color1", color1, ImGuiColorEditFlags_NoAlpha)
color2, color2_changed = ImGui.ColorEdit3("color2", color2, {ImGuiColorEditFlags_NoAlpha, ImGuiColorEditFlags_NoSmallPreview})

Optional pointer arguments return nil if not used.

C++: IMGUI_API void ShowDemoWindow(bool* p_open = NULL)
Lua: p_open : optional boolean = ImGui.ShowDemoWindow(p_open : optional boolean)

ImGui.ShowDemoWindow()                -- returns nil
p_open = ImGui.ShowDemoWindow(p_open) -- you get the modified p_open back

Pointers, references starting with out_ are return only.

C++: IMGUI_API void ColorConvertRGBtoHSV(float r, float g, float b, float& out_h, float& out_s, float& out_v)
Lua: out_h : number, out_s : number, out_v : number = ImGui.ColorConvertRGBtoHSV(r : number, g : number, b : number)

h, s, v = ImGui.ColorConvertRGBtoHSV(r, g, b)

ImVec2 and ImVec4 are tables with 2 or 4 numbers.

C++: IMGUI_API void SetNextWindowPos(const ImVec2& pos, ImGuiCond cond = 0, const ImVec2& pivot = ImVec2(0, 0))
Lua: ImGui.SetNextWindowPos(pos : table of 2 numbers, cond : optional flag (number or table of numbers), pivot : optional table of 2 numbers)

ImGui.SetNextWindowPos({146,486}, ImGuiCond_Once)

Config json structure

• List of header files to process
  • Each header file is a dict
    • "header_path": ImGui header file to process
    • "namespace": ImGui namespace to process
    • "gen_list": List of function names to generate a wrapper for. Optional, if missing or an empty list a wrapper will be generated for all viable functions.
    • "array bounds": Dict of lists of dicts. Variables like const char* labels[] (unsized array) or const T* xs (type is pointer and variable name ends with "s") are expected to be arrays. Luau bindings will only generate for array arguments if size is know. If an obvious bound found in the function argument list (for example int count) that will be used. If that can not be found the generator tries to look it up in this list.
      • key: Name of the function
        • list: Each list member is an argument which we define the array size of, defined by a dict
          • cpp_type: Type of the argument in the ImGui header
          • cpp_name: Name of the argument in the ImGui header
          • cpp_size: Here we define the array size of the argument specified by the previous two keys. Argument is not an array if this is set to null.
    • "types": Dict of dicts defining types in the header. Enums are not needed to be defined and handled automatically. Function pointers are not supported.
      • key: Name of the type being described
        • cpp_type: Which C++ type should be used for this type in the defined bindings. Optional, defaults to the dict key.
        • lua_type: Which Lua type should be used for this type. Optional, defaults to "number"
        • lua_table: Should it be handled as a table of lua_type values from lua side or as a standalone lua_value? If it is a table this should be an integer, if it is not this should be null. Optional, defaults to null.
        • cpp_fields: Access to the field members of the type, if lua_table is not null. Should list exactly as many members as the lua_table field describes. Optional, defaults to null.
    • "force_default_values": Dict of lists of dicts. Some ImGui functions allow reading out of bounds memory if the user is given full control of input arguments. With these entries some arguments can be hidden from the Lua side, and will always be provided a default value defined here.
      • key: Name of the function. Special value "*" in which case this default value will be forced in all functions within the header
        • list: Each list member is an argument which we define the default value of, defined by a dict
          • cpp_type: Type of the argument in the ImGui header
          • cpp_name: Name of the argument in the ImGui header
          • cpp_dval: Here we define the default value of the argument specified by the previous two keys