Important internal classes

Here, we will document important internal classes.

Core/Defines.hpp

The Defines.hpp header contains the following definitions:

1. Defines the std_filesystem macro, to make working with older compilers that support std::filesystem as part of std::experimental::filesystem possible
2. Defines the IMGUI_START macro that is called as the first thing in the entry point.
3. Defines the CAST macro that does a static_cast to go around some linter warnings.
4. Defines the FCAST macro that does a C-style cast to go around some linter and compiler warning. The F stands for "force".
5. Creates C++ type definitions for ComponentType and ComponentState.

The C alternative, CDefines.h, defines the following:

1. Defines __declspec(dllimport)/__declspec(dllexport) when compiling for Windows
2. The UNUSED macro that can be used to remove UNUSED warnings for functions whose return types are marked as [[nodiscard]]
3. The CARRAY_SIZE macro that returns the size of a static C-style array
4. The C implementation of UImGui_ComponentType and UImGui_ComponentState.

It also defines the following strings that can be used to set the semantic type of window in X11(more info on the Window Interface page). They look like this:

#define X11_WINDOW_TYPE_DESKTOP "_NET_WM_WINDOW_TYPE_DESKTOP"
#define X11_WINDOW_TYPE_DOCK "_NET_WM_WINDOW_TYPE_DOCK"
#define X11_WINDOW_TYPE_TOOLBAR "_NET_WM_WINDOW_TYPE_TOOLBAR"
#define X11_WINDOW_TYPE_MENU "_NET_WM_WINDOW_TYPE_MENU"
#define X11_WINDOW_TYPE_UTILITY "_NET_WM_WINDOW_TYPE_UTILITY"
#define X11_WINDOW_TYPE_SPLASH "_NET_WM_WINDOW_TYPE_SPLASH"
#define X11_WINDOW_TYPE_DIALOG "_NET_WM_WINDOW_TYPE_DIALOG"
#define X11_WINDOW_TYPE_NORMAL "_NET_WM_WINDOW_TYPE_NORMAL"

Core/Global

This class defines the Global class, which stores global data used internally. It has the following members:

1. Pointer to the current Instance
2. Pointer to the current RendererInternal class, which represents the renderer
3. A single instance of WindowInternal
4. A single instance of ModulesManager
5. A single instance of the CDeallocationStruct - More information here

It also has the init member function, which is equivalent to the Begin event listed on the Internal Event Safety page.

Core/Types.hpp

It defines the following types:

// Redefine for C++
typedef UImGui_FVector2 FVector2;
typedef UImGui_FVector FVector;
typedef UImGui_FVector4 FVector4;
typedef UImGui_String String;
typedef std::string FString;

YAML::Emitter& operator<<(YAML::Emitter& out, const FVector4& vect) noexcept;
YAML::Emitter& operator<<(YAML::Emitter& out, const FVector& vect) noexcept;
YAML::Emitter& operator<<(YAML::Emitter& out, const FVector2& vect) noexcept;

and also calls using namespace UVKLog; to remove the UVKLog namespace when logging.

The above type definitions are imported from the C API at CTypes.h, which looks like this:

struct UIMGUI_PUBLIC_API UImGui_FVector2_I
{
    float x;
    float y;
};

struct UIMGUI_PUBLIC_API UImGui_FVector_I
{
    float x;
    float y;
    float z;
};

struct UIMGUI_PUBLIC_API UImGui_FVector4_I
{
    float x;
    float y;
    float z;
    float w;
};

typedef const char* UImGui_String;

typedef struct UImGui_FVector2_I UImGui_FVector2;
typedef struct UImGui_FVector_I UImGui_FVector;
typedef struct UImGui_FVector4_I UImGui_FVector4;

The 3 operator<< overrides allow our vector types to easily be output to YAML. Additionally, the following class definitions allow us to easily load YAML into those types:

namespace YAML
{
    template<>
    struct convert<UImGui::FVector4>
    {
        static Node encode(const UImGui::FVector4& rhs) noexcept
        {
            Node node;
            node.push_back(rhs.x);
            node.push_back(rhs.y);
            node.push_back(rhs.z);
            node.push_back(rhs.w);
            node.SetStyle(EmitterStyle::Flow);
            return node;
        }

        static bool decode(const Node& node, UImGui::FVector4& rhs) noexcept
        {
            if (!node.IsSequence() || node.size() != 4)
                return false;

            rhs.x = node[0].as<float>();
            rhs.y = node[1].as<float>();
            rhs.z = node[2].as<float>();
            rhs.w = node[3].as<float>();
            return true;
        }
    };

    template<>
    struct convert<UImGui::FVector>
    {
        static Node encode(const UImGui::FVector& rhs) noexcept
        {
            Node node;
            node.push_back(rhs.x);
            node.push_back(rhs.y);
            node.push_back(rhs.z);
            node.SetStyle(EmitterStyle::Flow);
            return node;
        }

        static bool decode(const Node& node, UImGui::FVector& rhs) noexcept
        {
            if (!node.IsSequence() || node.size() != 3)
                return false;

            rhs.x = node[0].as<float>();
            rhs.y = node[1].as<float>();
            rhs.z = node[2].as<float>();
            return true;
        }
    };

    template<>
    struct convert<UImGui::FVector2>
    {
        static Node encode(const UImGui::FVector2& rhs) noexcept
        {
            Node node;
            node.push_back(rhs.x);
            node.push_back(rhs.y);
            node.SetStyle(EmitterStyle::Flow);
            return node;
        }

        static bool decode(const Node& node, UImGui::FVector2& rhs) noexcept
        {
            if (!node.IsSequence() || node.size() != 2)
                return false;

            rhs.x = node[0].as<float>();
            rhs.y = node[1].as<float>();
            return true;
        }
    };
}

Core/CDeallocation.hpp

This file contains a struct that stores some intermediate data for the C API. The max memory complexity is estimated at somewhere below 100% more memory. THe struct currently looks like this:

struct UIMGUI_PUBLIC_API CDeallocationStruct
{
    std::vector<FString> keyStrings; // Stores temporary strings
    std::vector<UImGui_CMonitorData> monitors; // Stores temporary C monitor structs
};

Modules/Manager/ModulesManager

This file defines the internal ModulesManager class, the Modules interface and the ModuleSettings struct.

The ModulesManager class manages module settings, which module is enabled at runtime and at compile time, and managing the modules' lifetime.

It looks like this:

class ModulesManager
{
private:
    ModuleSettings settings;
#ifdef UIMGUI_LOCALE_MODULE_ENABLED
    LocaleManager localeManager{};
#endif

#ifdef UIMGUI_UNDO_MODULE_ENABLED
    StateTracker stateTracker{};
#endif

    void init(const FString& configDir);
    void initModules(const FString& projectDir);
    void save(const FString& configDir) const noexcept;
};

Reference:

1. init - Loads module settings
2. initModules - Initializes modules with the settings
3. save - saves settings to Modules.yaml

Renderer/GenericRenderer

The GenericRenderer folder implements generic base classes that our different renderer abstractions implement. It currently contains the following:

1. GenericRenderer - Implements interfaces for interfacing with both the graphics API, and with the rendering layer of dear imgui
2. GenericTexture - Implements a generic texture interface

The GenericRenderer class

The GenericRenderer class looks like this:

class GenericInternalRenderer
{
public:
    GenericInternalRenderer() noexcept = default;

    virtual void init(RendererInternal& renderer) noexcept = 0;
    virtual void renderStart(double deltaTime) noexcept = 0;
    virtual void renderEnd(double deltaTime) noexcept = 0;
    virtual void destroy() noexcept = 0;

    virtual void ImGuiNewFrame() noexcept = 0;
    virtual void ImGuiShutdown() noexcept = 0;
    virtual void ImGuiInit() noexcept = 0;
    virtual void ImGuiRenderData() noexcept = 0;

    virtual void waitOnGPU() noexcept = 0; // This is only used for Vulkan, because there we have to wait on everything to render before freeing resources

    virtual ~GenericInternalRenderer() noexcept = default;
};

The GenericTexture class

The GenericTexture class looks like this:

class GenericTexture
{
public:
    GenericTexture() noexcept = default;

    virtual void init(String location, bool bFiltered) noexcept = 0;

    virtual void* get() noexcept = 0;
    virtual void load(void* data, FVector2 size, uint32_t depth, bool bFreeImageData,
                            const std::function<void(void*)>& freeFunc) noexcept = 0;

    template<TextureFormat format>
    bool saveToFile(const String location, const TextureFormat fmt = format, const uint8_t jpegQuality = 100) noexcept;

    // Set a function for saving custom image file formats
    // Event Safety - All initiated
    void setCustomSaveFunction(CustomSaveFunction f) noexcept;

    // Returns the size of the image
    // Event Safety - Any time
    [[nodiscard]] const FVector2& size() const noexcept;

    // Cleans up the image data
    // Event Safety - All initiated
    virtual void clear() noexcept = 0;
    virtual ~GenericTexture() noexcept = default;
protected:
    void beginLoad(void** data, FVector2& size) noexcept;
    void endLoad(void* data, FVector2 size, bool bFreeImageData, const std::function<void(void*)>& freeFunc) noexcept;
    void defaultInit(String location) noexcept;
    void defaultClear() noexcept;

    TextureData dt{};
};

The functions under the protected visibility label are utility common functions that are used by child classes to reduce code duplication.

Renderer/Renderer

The internal Renderer class looks like this:

class UIMGUI_PUBLIC_API RendererInternal
{
public:
    void start() noexcept;
    void stop() noexcept;
private:
    FString vendorString;
    FString apiVersion;
    FString driverVersion;
    FString gpuName;

    void loadConfig();
    void saveConfig() const noexcept;

    RendererData data{};
};

Reference:

1. start - Initializes and starts the renderer
2. stop - Destroys the renderer and deallocates all renderer data
3. The 4 strings - GPU information that can be fetched using the renderer interface
4. loadConfig - Loads the renderer config file, Renderer.yaml
5. saveConfig - Saves the renderer data stored in the data field to Renderer.yaml

Renderer/ImGui/ImGui

The GUIRenderer class contains internal functions that set up dear imgui through the different stages of the render loop. It looks like this:

class GUIRenderer
{
public:
    static void init(GLFWwindow* glfwwindow, const FString& ini);
    static void beginUI(float deltaTime);
    static void beginFrame();
    static void shutdown(const FString& ini);
};

Reference:

1. init - Creates an imgui context, sets up themes and style, calls the begin events of the components and the instance
2. beginUI - Called at the beginning of every render loop iteration
3. beginFrame - Starts a new imgui frame
4. shutdown - Cleans up imgui resources + save the layout to the specified location in the Window.yaml config file

Renderer/Window

Internal monitor C and C++ API bridge

The Monitor class contains the CInternalGetMonitorClassDoNotTouch member class, which looks like this:

class CInternalGetMonitorClassDoNotTouch
{
public:
    static UImGui_CMonitorData UImGui_Window_getWindowMonitor();
    static void pushGlobalMonitorCallbackFun(UImGui::Monitor& monitor, UImGui::MonitorState state,
                                             UImGui_Window_pushGlobalMonitorCallbackFun f);
    static void UImGui_Monitor_pushEvent(UImGui_CMonitorData* data, UImGui_Monitor_EventsFun f);
    static void UImGui_Monitor_setWindowMonitor(UImGui_CMonitorData* monitor);
    static UImGui_CMonitorData* UImGui_Window_getMonitors(size_t* size);
};

It is here, mostly because of our header file design, which prevents us from using friend functions for accessing the private GLFWmonitor*. This class exists to store these functions, which will have access to the private GLFWmonitor*. These will then be called from the implementation of the C API functions.

Internal window

The internal Window class looks like this:

class WindowInternal
{
public:
    [[nodiscard]] GLFWwindow* data() const noexcept;
    bool& resized() noexcept;
    void close() noexcept;

    // For consumption by the C API
    std::vector<std::function<void(const char**, size_t size)>> dragDropPathCCallbackList;
private:
    void updateKeyState() noexcept;

    FVector2 windowSize = { 800.0f, 600.0f };
    FVector2 windowSizeInScreenCoords;

    std::array<uint16_t, 350> keys{};
    std::vector<InputAction> inputActionList{};

    void saveConfig(bool bSaveKeybindings) noexcept;
    void openConfig();

    void setTitle(String title) noexcept;
    void setIcon(String name) noexcept;

    FVector2 getMousePositionChange() noexcept;
    FVector2 getScroll() noexcept;

    void createWindow() noexcept;
    void destroyWindow() noexcept;

    void configureCallbacks() noexcept;
    static void framebufferSizeCallback(GLFWwindow* window, int width, int height) noexcept;
    static void keyboardInputCallback(GLFWwindow* window, int key, int scanCode, int action, int mods) noexcept;
    static void mouseKeyInputCallback(GLFWwindow* window, int button, int action, int mods) noexcept;
    static void mouseCursorPositionCallback(GLFWwindow* window, double xpos, double ypos) noexcept;
    static void scrollInputCallback(GLFWwindow* window, double xoffset, double yoffset) noexcept;
    static void windowPositionCallback(GLFWwindow* window, int xpos, int ypos) noexcept;

    static void windowSizeCallback(GLFWwindow* window, int width, int height) noexcept;
    static void windowCloseCallback(GLFWwindow* window) noexcept;
    static void windowFocusCallback(GLFWwindow* window, int focused) noexcept;
    static void windowIconifyCallback(GLFWwindow* window, int iconified) noexcept;
    static void windowContentScaleCallback(GLFWwindow* window, float x, float y) noexcept;
    static void windowRefreshCallback(GLFWwindow* window) noexcept;
    static void windowMaximisedCallback(GLFWwindow* window, int maximised) noexcept;

    static void monitorCallback(GLFWmonitor* monitor, int event) noexcept;

    static void windowOSDragDropCallback(GLFWwindow* window, int count, const char** paths) noexcept;

    static void windowErrorCallback(int code, const char* description) noexcept;

    void setWindowAlwaysOnTop() noexcept;
    void setWindowAlwaysBelow() noexcept;
    void disableWindowMoving() noexcept;

    void setShowWindowInPager(bool bShowInPagerr) noexcept;
    void setShowWindowOnTaskbar(bool bShowOnTaskbarr) noexcept;

    void setWindowType(const char* type) noexcept;

    size_t getWindowID() noexcept;
    
    bool bShowOnPager = true;
    bool bShowOnTaskbar = true;

    std::vector<std::function<void(int, int)>> windowResizeCallbackList;
    std::vector<std::function<void(int, int)>> windowResizeInScreenCoordCallbackList;
    std::vector<std::function<void(void)>> windowCloseCallbackList;
    std::vector<std::function<void(bool)>> windowFocusCallbackList;
    std::vector<std::function<void(bool)>> windowIconifiedCallbackList;
    std::vector<std::function<void(FVector2)>> windowPositionChangeCallbackList;
    std::vector<std::function<void(FVector2)>> windowContentScaleChangeCallbackList;
    std::vector<std::function<void(void)>> windowRefreshCallbackList;
    std::vector<std::function<void(bool)>> windowMaximisedCallbackList;
    std::vector<std::function<void(Monitor&, MonitorState)>> windowMonitorCallbackList;
    std::vector<std::function<void(std::vector<FString>&)>> dragDropPathCallbackList;
    
    std::vector<std::function<void(int, const char*)>> windowErrorCallbackList;

    std::vector<FString> dragDropPaths;

    std::vector<Monitor> monitors;

    GLFWwindow* windowMain = nullptr;
    WindowData windowData;

    bool bFirstMove = true;
    bool bResized = false;

    FVector2 mousePos = { 0.0f, 0.0f };
    FVector2 mouseLastPos = { 0.0f, 0.0f };
    FVector2 mouseOffset = { 0.0f, 0.0f };

    FVector2 scroll;

    FVector2 windowLastPos = { 0.0f, 0.0f };
    FVector2 windowCurrentPos = { 0.0f, 0.0f };
};

Functions:

1. data - Returns the internal GLFW window context
2. resized - Resized a boolean reference to check if the window was resized
3. close - Close the window
4. updateKeyState - Updates the state of InputActions after all keys' state is known, i.e. after glfwPollEvents
5. saveConfig - Saves window settings
6. openConfig - Loads window settings
7. setTitle - Sets the title of the window
8. setIcon - Sets the window icon
9. getMousePositionChange - Returns the difference between the last and current mouse position
10. getScroll - Returns the current scroll value as a FVector2
11. createWindow, destroyWindow - Creates/destroys the window context
12. configureCallbacks - Sets up the callbacks
13. setWindowAlwaysOnTop - Backend version of the same function in the Window interface. Makes the window appear as the top most window.
14. setWindowAlwaysBelow - Backend version of the same function in the Window interface. Makes the window appear as the root or bottom-most window.
15. disableWindowMoving - Backend version of the same function in the Window interface. Completely disable movement of the window by the user
16. setShowWindowInPager - Backend version of the same function in the Window interface. Toggles display of the window in the pager
17. setShowWindowOnTaskbar - Backend version of the same function in the Window interface. Toggles display of the window in the taskbar
18. setWindowType - Backend version of the same function in the Window interface. Given a C string, sets the given X11 semantic window type as defined by the X11 documentation.
19. getWindowID - Backend version of the same function in the Window interface. Returns the ID of the current Window.
20. The rest - Callbacks for window events.

Variables:

1. windowSize - The size of the window as a FVector2
2. windowSizeInScreenCoords - The size of the window in screen coordinates as an FVector2
3. keys - An array of events on a given key code
4. inputActionList - The internal list of input actions
5. dragDropPaths - A list of all paths that were acquired by the window on OS file drag and drop into it
6. bShowOnPager - The internal bool that is used to check whether the window is shown on the pager
7. bShowOnTaskbar - The internal bool that is used to check whether the window is shown on the taskbar
8. monitors - The internal monitors array
9. windowMain - The internal GLFW window context
10. windowData - The internal instance of the WindowData struct
11. bResized - To check whether the window was resized
12. mousePos, mouseLastPos, mouseOffset - Mouse positions as FVector2
13. scroll - Current scroll value
14. windowCurrentPos, windowLastPos - Window positions as FVector2
15. The rest - std::vector<std::function<void(T)>> style variables which store the callbacks pushed by the Window interface by pushWindow*Callback functions