1.92.0: Constructor wrapper for ImTextureRef from ImTextureID currently missing?

[floooh]

I'm currently porting my backend and code over to 1.92.0 and it seems like there's a constructor wrapper missing for building an ImTextureRef from a ImTextureID.

Currently I need to do something like this (using an ig prefix):

igImage((ImTextureRef){ ._TexID = tex_id}, ...);

...or maybe (not sure if it makes sense, but would be convenient):

Since the C++ API is backward compatible and can continue to be called with a ImTextureID (which will then automatically construct a ImTextureRef... maybe it makes sense to keep the C shim backward compatible by taking a ImTextureID since this seems to be the most common usage, and have a separate igImage_ImTextureRef(...) function which takes an ImTextureRef (since this seems to be a special case)?

[ShironekoBen]

Thanks for letting me know, and sorry for the delay - I somehow missed the notification for this and only spotted it now. That is a bit messy, certainly - I'll have a poke and see if I can add something to make it bit less painful to use.

[ShironekoBen]

So having looked at this in a bit more detail, it feels like it's a little complicated.

If we're considering C as the use-case, then as you suggest generating function variants for anything that accepts an ImTextureRef to take ImTextureID instead seems to be the most logical (and backwards-compatible) way of doing things.

However, for bindings from other languages (particularly those that support implicit conversion and thus can do the same trickery C++ does here), that introduces a discrepancy between the API as exposed to the bindings and the regular C++ API, which isn't greatly desirable.

So I think there's three reasonable courses of action here (using ImGui::Image() as an example but with the intent that this applies to all functions using ImTextureRef):

1. Have Dear Bindings modify ImGui::Image(ImTextureRef tex_ref) to become ImGui::Image(ImTextureID tex_ref) and add ImGui::ImageRef(ImTextureRef tex_ref) to handle the texture reference case.
2. Leave ImGui::Image(ImTextureRef tex_ref) alone but add an additional ImGui::ImageID(ImTextureID tex_ref) variant that takes a texture ID and converts internally.
3. Don't touch the functions at all, but just provide a standalone ImTextureIDToImTextureRef() helper to do the conversion (so at least people don't need to remember how to do it and/or risk getting it wrong).

1 maintains backwards compatibility for plain C usage, but my general feeling is that 2 is potentially a better balance of the needs of C and other languages. 3 minimises unexpected surprises for people looking at the C++ API (although quite possibly not for people using the C++ API, as they may just be using the implicit conversion and not actually notice that ImTextureID is not directly accepted as an argument).

@ocornut - I'd be interested to hear your take on this, particularly if you see passing ImTextureID to the main API as a backwards-compatibility feature that will gradually get phased out (turning ImTextureID into solely an "internal" type that is used to communicate between ImGui and backends) or if the plan long-term is that ImTextureID and ImTextureRef will continue to co-exist in the user-facing API?

[ocornut]

Basically ImTextureID is likely to be the type that app/user code will want to create at it maps to lower level texture type.

ImTextureRef are when textures are created by the backend itself. So although that is down the line the only type ImGui codebase itself would store, it doesn’t mean ImTextureID would be phased out.

I feel like (3) is the natural solution which, although initially appearing more intrusive, convey naturally what’s happening without magic. And avoid generating function names that don’t exist in the main api. At the end of the day, it would incitate app/engine code to create/store the ImTextureRef, so it’s not like end-user code would be cluttered by a ImTextureIDToImTextureRef() function.

Name wise: ImTextureRefFromTextureID() would map better to the existing c++ helper, and also convey better that Ref is the type we want to most focus on.

The “ideal” situation for high level languages like C#, Lua, Go etc, would be that dear bindings provide enough info so that an auto-generated binding can generate functions overload with same name that accept both types, or a same function for language with dynamic type checking. But it’s not even that important tbh.

[ShironekoBen]

OK, 3 sounds good then. Interestingly the work for #79 actually results in ImTextureRef ImTextureRef_InitImTextureID(ImTextureID tex_id); getting auto-generated from the C++ side constructor, so I think the simplest/neatest path to implementing this is probably to get that PR merged in and then add a rename override that turns ImTextureRef_InitImTextureID into ImTextureRefFromTextureID.

Thanks!

[floooh]

FWIW, so far I have a helper like this in some of my code that I ported to 1.92.0:

static ImTextureRef imtexref(ImTextureID tex_id) {
    return (ImTextureRef){ ._TexID = tex_id };
}

...and an igImageEx() call looks like this:

igImageEx(imtexref(texid0), size, uv0, uv1);

...If the name for the 'official' helper function becomes too long, I'd probably still wrap a call with a shorter-named macro but that's up the user-side code :)

[ocornut]

Note that, again, in principle, you could aim to replace

igImageEx(imtexref(texid0), size, uv0, uv1);

With

igImageEx(texref0, size, uv0, uv1);

Aka convert earlier in your pipe.

Sorry everyone for the trouble this has been causing but it’s really the way forward and it seemed like the least problematic approach to go this way.