Pointer metadata

[pdoane]

I am looking at generating bindings for Zig based on the metadata from dear_bindings. While Zig can work directly with C interfaces (and C pointers), its native pointer types are more expressive which helps to catch user errors, e.g.

*T - single-item pointer to exactly one item [*]T - many-item pointer to unknown number of items [N]T - array of N items *[N]T - pointer to N items, same as single-item pointer to an array []T - a slice which contains a pointer of type []T and a length `[:0]T- pointer that has a length determined by a sentinel value (0 in this case) [N:0]T- array which has a sentinel element of value (0 in this case) [:0]T` - a slice which has a runtime-known length and also a sentinel value at the element indexed by the length

There are also optional items ?T which can be combined with pointers.

Current strategy:

• is_nullable maps to Zig optional. The metadata is often missing but there is a path forward
• Arrays with bounds are Zig arrays
• Arrays without bounds are multi-item pointers
• Slices are not generally used, except for const char* which is assumed to be a C string and mapped to [*:0]const u8

This looks like a pretty good start but some many-item scenarios are missed, e.g. ImVector::Data is translated as a single-item pointer so doesn't support indexing.

Would there be interest in providing additional metadata here? It likely would require annotations in imgui.h but it seems like that would provide helpful user documentation.

[pdoane]

Some concrete proposals...

Null pointers could be opt-in or opt-out. I prefer being explicit when it could be null.

IMGUI_API void          PushFont(IM_NULLABLE ImFont* font);

Many-item pointers

    const IM_MANY_ITEMS ImGuiTableColumnSortSpecs* Specs;     // Pointer to sort spec array.

[pdoane]

@ocornut - are you okay to add annotations like this to the public imgui.h? I can get this started for both imgui and dear_bindings if approved.

[ocornut]

Hello Patrick :)

It bothers me a bit to add annotations to imgui.h because it would make things rather noisy. I'm also not sure I know how many annotations would be required (what's the average function to annotation ratio ?).

Not ruling this out but I'm wondering if in the meantime dear bindings could ship with a data table, meaning those annotations would be external?

I do realize in theory it means separate maintenance and the possibility of a missing annotations, but I'd argue in practice a vast majority of API are stable by now, and my gut feeling is that readability of raw imgui.h seems like a more important feature to maintain.

(the slight irony being that those annotations are technically an extra info for the user, but that info is mostly covered by comments/docs/examples/asserts and in practice I worry we reach a certain amount of bulkiness that makes reading the file discouraging)

[pdoane]

Completely understand! Two other ideas to think about:

• Keep auxiliary info in the imgui repository so it is easier to keep in sync?
• Make the metadata file authoritative and generate the C++ header from it. dear_bindings does an impressive job of making cimgui.h look handwritten.

The number of places where IM_MANY_ITEMS is needed is very small. Because of the overall API design, it's rare for applications to work with multiple things at once. It's also not needed for function parameters as the [] syntax can be used, so this only needs to focus on public structure fields.

Nullable is probably the more interesting discussion. It doesn't typically overlap with comments because it's usually easy to guess correctly, but the extra annotation would make it very clear.

Hope things are going well!

[pdoane]

To move this forward, I'll create a data-table in my generator and we can check that out when it's complete.

[ShironekoBen]

Cool, that sounds good to me too. Thanks!

[pdoane]

An update on progress...

• Many item pointer annotations is indeed a small list, as it only needs to focus on structure fields assuming [] syntax is used on function parameters. I believe these are the items:

    .{ "TableSortSpecs", "Specs" },
    .{ "DrawList", "_VtxWritePtr" },
    .{ "DrawList", "_IdxWritePtr" },
    .{ "FontConfig", "GlyphRanges" },
    .{ "FontAtlas", "TexPixelsAlpha8" },
    .{ "FontAtlas", "TexPixelsRGBA32" },

• Nullable is much harder to sort out. ImGui accepts null pointers in many cases where I would not have expected so it isn't really obvious to me when something is required. The good news is that the bindings aren't any worse than C/C++ by just making arguments optional when we don't know.

• There are opportunities for dear_bindings to infer more cases for is_nullable. E.g. I believe all fmt arguments are expected to have is_nullable set to false.

It's too much work to figure out is_nullable manually, but I can update a table when people hit issues.

[pdoane]

I'm going to close this out for now - we can revisit when nullable is better understood.

[ocornut]

FYI i have spotted a Zig backend generated with dear bindings: https://github.com/DarknessFX/zig_workbench/

Added it to https://github.com/dearimgui/dear_bindings/wiki/Software-using-Dear-Bindings