Custom user types (STL/math primitives)

[rokups]

The Problem

I am experimenting with integrating RmlUI into my project. Since it uses EASTL instead of standard library i am in a position where types of both libraries are interchangeable and yet a conversion has to be made each time i would like to pass a eastl::string to RmlUi. Similarly RmlUi vector types are incompatible with whatever math primitive types user's application is using, which creates an inconvenient requirement of manually converting these types in some cases where it does not make sense to only use RmlUi math types.

What can we do

std types

Actually RmlUi is some way there already. RMLUI_NO_THIRDPARTY_CONTAINERS and type aliases exist to facilitate use of different container types in some places. We could expand use of these aliases and provide means for user to inject their own aliases and includes to Types.h. Not only this would allow using alternate container types, it would also bring in a little more code style consistency into RmlUi.

Math primitive types

I do not have a full answer for this one yet. One thing we could do is provide some preprocessor defines that user could set in config header, implementing conversion between RmlUi math primitive types and user-defined types. This is what Dear ImGui does. It gets us half-way as this change would allow user to pass their own math primitives and compiler would do a conversion for us. I do not have an answer for output parameters (non-const references) however.

---

Do you think this is something that RmlUi should have? I have a working proof of concept conversion done already. RmlUi builds with EASTL. Aside from replacing std::T with custom aliases, only few minor modifications were needed to make RmlUi compatible with EASTL. If you find these ideas acceptable i can submit a PR.

[mikke89]

I like the idea. Of course, the library types would have to be compatible with their std counterparts, at least to a large extent. The feature should be clearly labeled with a "no-guarantees" given warning. I think it's great even if you just want to replace std::string with std::u8string, or use custom allocators in the containers.

For vector and color types we could do the same as the example in Dear ImGui you link to. Output parameters should work the same, right? It should automatically handle the implicit conversion when assigning from the user type. On a related note, we should really pass these types by value instead of reference through the API (for input parameters).

Matrices are a bit heavier though, I'm not sure if users really want implicit conversions? I guess it would be up to the user to decide anyway.

I also wonder a bit regards to how it should work with the CMake integration?

If this change can be done with minimal changes to the source code, ie. mostly header file changes, then I'd like to see this implemented :) A PR would be nice.

[rokups]

Output parameters should work the same, right? It should automatically handle the implicit conversion when assigning from the user type.

I dont think we can do

Rml::SomeApi(Rml::Vector3& out);
MyVector3 out;
Rml::SomeApi(out);

I would be very surprised if that worked with implicit typecast operators 👀

I also wonder a bit regards to how it should work with the CMake integration?

Depends.. We might not need anything at all on CMake's side. If we have something like RmlUserConfig.h then user could define all preprocessor defines in there, put into some known location and call it a day. Maybe we could use a CMake option for providing a custom path to RmlUserConfig.h. Any includes should be relative, that would avoid RmlUi lib having to link to whatever stdlib target. Thats it.

If this change can be done with minimal changes to the source code, ie. mostly header file changes, then I'd like to see this implemented :)

I threw my WIP changes into a git repo. Its still early so some things are missing. I did not add new aliases for stdlib, also i did not touch any of lua support as i am not using it myself. Main meat and bones is in Types.h. I had to introduce wrapper functions MakeShared(), MakeUnique() and MakeMoveIterator(). Also had to remove final from Releaser class as it somehow did not work with EASTL. I did not touch std::pair<> because for some reason it broke a lot of things, fixing which turned into cascade of weird changes, including making wrappers for sorting functions. Just for the sake of completeness I should still add an alias to std::pair<> even if i wont be using it myself.

[rokups]

Hey @mikke89 i see there is using Matrix4f = ColumnMajorMatrix4f;. Can we simply switch to row-major matrices by modifying that? If so, seems like it would make sense to include that into config header as well.

[uniquejack]

That's a very good suggestion, I also use custom containers in my engine, it would be cool to overwrite Vector and String containers, don't care that much about the other math types, I can simply convert them.

[mikke89]

Looks like a good start @rokups !

I would be very surprised if that worked with implicit typecast operators 👀

I see what you mean now, yes, this wouldn't work. I guess the user will either have to live with it, or we could go crazy and start replacing all the member functions with non-member functions that the user can customize. I'm not really a fan unless somebody has better suggestions.

Depends.. We might not need anything at all on CMake's side. If we have something like RmlUserConfig.h then user could define all preprocessor defines in there, put into some known location and call it a day. Maybe we could use a CMake option for providing a custom path to RmlUserConfig.h. Any includes should be relative, that would avoid RmlUi lib having to link to whatever stdlib target. Thats it.

I like the config file suggestion. Proposed CMake changes:

Add a new configuration option CUSTOM_CONFIG_FILE which the user can point to a file of their choice, and which sets a macro to replace the default configuration. Maybe a bool option to enable this first?

We could replace the NO_THIRDPARTY_CONTAINERS option with a selection between eg. "mixed std and internal containers" (current default), "std only", and "custom containers".

The latter option should require a custom config file, and enable a new option, eg:

• CUSTOM_CONTAINERS_INCLUDE_DIRS. Adds the provided include directory to all targets.
• Maybe also an option to include libraries, then again I guess most of these libraries are headers only?

Of course this is just some initial thoughts. Names and configurations are open for suggestions.

Maybe I'm overthinking this, but it would be nice to select between std only, current default (included containers), and custom. Maybe just add the std vs internal containers as two different configuration files that the user can point to, or select their own path?

I threw my WIP changes into a git repo. Its still early so some things are missing. I did not add new aliases for stdlib, also i did not touch any of lua support as i am not using it myself. Main meat and bones is in Types.h. I had to introduce wrapper functions MakeShared(), MakeUnique() and MakeMoveIterator(). Also had to remove final from Releaser class as it somehow did not work with EASTL. I did not touch std::pair<> because for some reason it broke a lot of things, fixing which turned into cascade of weird changes, including making wrappers for sorting functions. Just for the sake of completeness I should still add an alias to std::pair<> even if i wont be using it myself.

This is a great start. I don't see any big issues with these changes. Although we would need to change all the samples and Lua bindings as well.

Hey @mikke89 i see there is using Matrix4f = ColumnMajorMatrix4f;. Can we simply switch to row-major matrices by modifying that? If so, seems like it would make sense to include that into config header as well.

Yup, this would be great to add to the configuration file :)