Additional features

This page showcases a bunch of small features that are really useful.

Logging

We use the UntitledLog library, to facilitate logging. The library also includes a small timer class and an imgui widget for that displays the messages in the console. Documentation can be found on the UntitledLog GitHub repository.

ImGui and rendering

While dear imgui provides a lot of features, we decided to add some additional features on top of it to improve the development experience.

Texture class

The Texture class is an abstraction that allows easy loading of textures in the graphics API. It looks like this:

class UIMGUI_PUBLIC_API Texture
{
public:
    /**
     * @brief Saves the name of a file for the texture to load
     * @param file - The name of the image file to be loaded
     * @note Event Safety - Post-begin
     */
    Texture(String file) noexcept;
    
    /**
     * @brief Equivalent to calling the constructor
     * @note Event Safety - Post-begin
     */
    void init(String file) noexcept;

    // Event Safety - Post-begin
    void load(void* data = nullptr, uint32_t x = 0, uint32_t y = 0, uint32_t depth = 0, bool bFreeImageData = true,
              const std::function<void(void*)>& freeFunc = defaultFreeFunc) noexcept;

    // Returns the image buffer
    [[nodiscard]] const uint32_t& get() const noexcept;

    // Returns the size of the image
    [[nodiscard]] const FVector2& size() const noexcept;

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

    // Cleans up the image data
    void clear() noexcept;

    // Same as calling clear
    ~Texture() noexcept;
};

to use the Texture class to load images into dear imgui simply initialise the class like this:

Texture texture;
texture.init("image.png");

or simply like this:r

Texture texture("image.png");

This will only set the image file location.

Caution

Calls to the init function or the explicit single-argument constructor should be done after the renderer is started, preferably in any events like begin and after

Next, to load the image, call load without any arguments.

Finally, when destroying the image, call the clear function or the destructor.

To get the size of the image as a FVector2 call size, to get the image ID, call get.

Loading custom images

To load custom images, simply call load by overriding the default arguments, like this:

void* data = nullptr;
uint32_t x = 0;
uint32_t y = 0;
uint32_t depth = 0;

Texture texture;
... // Load data here
texture.load(data, x, y, depth, false)
... // Free image data here

When the bFreeImageData argument is set to false we will not call the free function on the data in the load and loadImGui functions. If set to true, it calls the default free function, which simply calls the C free function. Alternatively, you can overload the freeFunc argument to include a custom free function.

Saving an image to a file

The saveToFile function can be used to save an image to a file. To save an image, make sure that you load your image with bFreeImageData being set to false. Next, call the saveToFile function.

The function takes a file location as a string, a format of the texture and a uint8_t representing the JPEG quality. By default, JPEGs are saved with maximum quality of 100, the lowest quality is 0.

The TextureFormat struct looks like this:

enum UImGui_TextureFormat
{
    UIMGUI_TEXTURE_FORMAT_PNG,
    UIMGUI_TEXTURE_FORMAT_BMP,
    UIMGUI_TEXTURE_FORMAT_TGA,
    UIMGUI_TEXTURE_FORMAT_JPEG,
    UIMGUI_TEXTURE_FORMAT_OTHER
};

When the template parameter is set to UIMGUI_TEXTURE_FORMAT_OTHER a check of the fmt variable will be run. Since the fmt variable defaults to the value of the template parameter, UIMGUI_TEXTURE_FORMAT_OTHER will run the custom save function. You can also override the fmt default argument to another value for setting the format at runtime.

To set the custom save function, call the setCustomSaveFunction function. It takes an argument of type CustomSaveFunction, which is simply a C function pointer of type bool(UImGui_TextureData* data, UImGui_String location).

Event safety

The following functions are flagged as Any time:

1. get
2. size

The following are flagged as Post-begin:

1. Single-argument explicit constructor
2. init
3. load
4. loadImGui

The following are flagged as All initiated:

1. clear
2. Destructor

Texture C API

The C API for the texture uses the standard conventions for the C API, as defined here. It uses the same function names as the C++ ones, but they are prefixed with UImGui_Texture_.

Additionally, because the C API uses functions instead of a class with members, the data for the texture must be managed by the user. This is why, all functions part of the Texture C API take UImGui_CTexture* as their first argument. Therefore, to create a texture in the C API, you need the following code:

UImGui_CTexture* texture = UImGui_Texture_init("your-texture-here.png");
... // load texture here

When you're done with using the texture, call UImGui_Texture_release, like this:

UImGui_Texture_release(texture);

Warning

Calling UImGui_Texture_clear will not call UImGui_Texture_release!

Note

The UImGui_Texture_release function simply releases the handle. When your application closes, all handles are released automatically, so in most cases, you won't have to use this function frequently.

Overrides for functions with bool* p_open

Each UI component has a ComponentState enum member that looks like this:

enum UImGui_ComponentState
{
    UIMGUI_COMPONENT_STATE_PAUSED,
    UIMGUI_COMPONENT_STATE_RUNNING,
    UIMGUI_COMPONENT_STATE_OFF,
};

When set to RUNNING(the default mode) it's shown to the screen. If set to PAUSED it's not shown but is expected to be rendered at some point. If set to OFF it's not supposed to be active.

---

Since UI components have this state enum, we can use it to enable/disable rendering of components. Because it's an enum, however, we cannot pass it directly as p_open since dear imgui requires p_open to be a bool*.

To fix this, we have added additional overrides that take a void* to enable you to use the state enum directly without casting the pointer. The functions can be seen on our dear imgui fork here.

UTF-8 support

The framework bundles the utfcpp library for simple UTF-8 support. You can check out its readme for documentation.