Loading custom images

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, bool bFiltered = true) noexcept;
    
    /**
     * @brief Equivalent to calling the constructor
     * @note Event Safety - Post-begin
     */
    void init(String file, bool bFiltered = true) 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]] uintptr_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:

Texture texture("image.png");

This will only set the image file location.

You can also override the default argument of bFiltered for both the init function and the constructor to control whether the texture should be filtered, or should be left as is.

Caution

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

Warning

Texture filtering is currently not supported in WebGPU

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:

get
size

The following are flagged as Post-begin:

Single-argument explicit constructor
init
load
loadImGui

The following are flagged as All initiated:

clear
Destructor

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", true);
... // 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.