Setup API Proposal

[epezent]

SEEKING FEEDBACK! IF YOU ARE TAGGED BELOW OR STUMBLED UPON THIS, PLEASE SHARE YOUR THOUGHTS :)

@ocornut , @rokups , @marcizhu, @bear24rw, @PeterJohnson , @hoffstadt. @ozlb, @sergeyn, @mindv0rtex, @JoelLinn, @sonoro1234. @jpieper, @JaapSuter , @ChiefyChief23, @leeoniya

The State of Things

ImPlot continues to evolve, but it has become increasingly apparent that the current API is not flexible enough to accommodate many features that have been requested (#82,#173,#235,#246,#248,#251,#165,#197,#245,#56,#98) or things that I would like to eventually do (e.g. mutli x-axis). Our main culprit is of course BeginPlot, which is now a Frankenstein monster of what it started out as:

bool BeginPlot(const char* title_id,
               const char* x_label      = NULL,
               const char* y_label      = NULL,
               const ImVec2& size       = ImVec2(-1,0),
               ImPlotFlags flags        = ImPlotFlags_None,
               ImPlotAxisFlags x_flags  = ImPlotAxisFlags_None,
               ImPlotAxisFlags y_flags  = ImPlotAxisFlags_None,
               ImPlotAxisFlags y2_flags = ImPlotAxisFlags_NoGridLines,
               ImPlotAxisFlags y3_flags = ImPlotAxisFlags_NoGridLines,
               const char* y2_label     = NULL,
               const char* y3_label     = NULL);

Ugh, it pains me to look at this! Here are the biggest issues:

• comically awful signature with too many arguments
• plot- and axis-centric flags, labels etc., in same function call
• out of order args that were conveniently tacked on as default args
• Y2 and Y3 related args only used if ImPlotFlags_YAxis2/3 set (should just be automatic)
• would need even more args to support multiple X axes

Our second issue is the assortment of SetNextPlotX functions that we have, e.g.:

void SetNextPlotLimits(double xmin, double xmax, double ymin, double ymax, ImGuiCond cond = ImGuiCond_Once);

I started this pattern because I felt it was analogous to ImGui::SetNextWindowSize() and because we need to know such details during the call to BeginPlot, which sets up the plot render layout and transformations. We now have about a dozen similar functions for setting up various plot/axis parameters. In hindsight, this was a bad decision because 1) we end up with a confusing assortment of API calls that must happen before BeginPlot or after BeginPlot, and 2) the pattern does not scale well because each new feature requires managing the lifetime of more state up until the next call to BeginPlot (i.e. NextPlotData gets bigger).

These two things have bugged me for quite a while, and I have been slow to move on adding new features because both have been somewhat restrictive. Continuing to either add more args to BeginPlot or more SetNextPlotX functions always seemed like dead ends to me.

New Setup API Proposal

Taking a page out of ImGui Tables' book, I am proposing that we reduce the number of arguments required for BeginPlot, and provide a variety of optional SetupX functions that can be called immediately after. The latter would replace the current SetNextPlotX API. Here's what this new API may look like:

// simpler BeginPlot
bool BeginPlot(const char* title_id, const ImVec2& size, ImPlotFlags flags);
void EndPlot();
// existing functionality
void SetupAxis(ImAxis axis, const char* label, ImPlotAxisFlags flags);
void SetupAxisLimits(ImAxis axis, double min_lim, double max_lim, ImGuiCond cond);
void SetupAxisLinks(ImAxis axis, double* min_lnk, double* max_lnk);
void SetupAxisFormat(ImAxis axis, const char* fmt);
void SetupAxisTicks(ImAxis axis, const double* values, int n_ticks, const char* const labels[]);
// new functionality
void SetupAxisFormat(ImAxis axis, void (*formatter)(double value, char* buff, int size));
void SetupLegend(...);
void SetupInput(...);
void SetupContextMenu(...);
// ... so on and so forth
void FinishSetup(); // optional 

And a few examples:

// no frills
if (ImPlot::BeginPlot("Example 1")) {
    ImPlot::PlotLine("data",x_data,y_data,2);
    ImPlot::EndPlot();
}

// the basics
if (ImPlot::BeginPlot("Example 2")) {
    ImPlot::SetupAxis(ImAxis_X1, "My X-Axis", ImPlotAxisFlags_Time);
    ImPlot::SetupAxis(ImAxis_Y1, "My Y-Axis", ImPlotAxisFlags_Invert);
    ImPlot::PlotLine("data",x_data,y_data,2);
    ImPlot::EndPlot();
}

// multi-axis crazy plot
if (ImPlot::BeginPlot("Example 3",ImVec2(-1,-1),ImPlotFlags_NoTitle)) {
    ImPlot::SetupAxis(ImAxis_X1, "My X-Axis 1");
    ImPlot::SetupAxisLimits(ImAxis_X1, -10, 10);
    ImPlot::SetupAxisFormat(ImAxis_X1, "%g V");
    ImPlot::SetupAxis(ImAxis_X2, "My X-Axis 2");
    ImPlot::SetupAxisTicks(ImAxis_X2, 0,1,5);
    ImPlot::SetupAxisFormat(ImAxis_X2, "%.3f mA");
    ImPlot::SetupAxis(ImAxis_Y1, "My Y-Axis 1");
    ImPlot::SetupAxis(ImAxis_Y2, "My Y-Axis 2", ImPlotAxisFlags_Opposite);
    ImPlot::SetupAxisLimits(ImAxis_Y2, 0, 10000);
    ImPlot::SetupAxisFormat(ImAxis_Y2, MyFormatCallback);
    ImPlot::SetupLegend(ImPlotLocation_North, ImPlotLegendFlags_Outside|ImPlotLegendFlags_Horizontal);
    ImPlot::PlotLine("data11",x_data,y_data,2);
    ImPlot::SetAxes(ImAxis_X2, ImAxis_Y2);
    ImPlot::PlotLine("data22",x_data,y_data,2);    
    ImPlot::EndPlot();
}

A Few Gotchas

While I feel pretty strongly that this is the path forward, there are a few things I haven't yet worked out:

The Order of Setup Calls

Previously, BeginPlot would do all plot render layout (e.g. calculate padding sizes based on axis ranges, labels, titles, etc) so that the bounding rect for the plot region and coordinate transformations were know before we entered any PlotX functions. Because we had adopted the SetNextPlotX pattern, BeginPlot had all the information it needed to do its job. That's not true with the proposed API, since some calls to SetupX may necessitate an adjustment to the layout.

My current strategy is something similar to ImGui Tables:

• user calls BeginPlot
• user makes as many SetupX calls as they like
• [optional] user explicitly completes setup with FinishSetup
  • FinishSetup calculates layout and padding, and locks the plot from anymore SetupX calls (runtime assert), essentially doing most of the work BeginPlot previously did
• user makes calls to PlotX
  • IF the user DID NOT explicitly call FinishSetup, then the first call to ANY function that requires the layout to be complete (e.g. PlotX , but also util functions such as PlotToPixels) will call it automatically
• user calls EndPlot

@ocornut , your feedback here would be super appreciated. This seems like the best option, but you may have a more clever idea! FWIW, another option might be to delay all render until EndPlot, but this would require caching an enormous amount of data including the user's plot data. Maybe this is something that could be resolved with ImDrawListSplitter? I don't know...

Breaking User Code

Changing BeginPlot of course is going to break a lot of people's existing code. Although I have been saying for sometime that anything goes until v1.0, I want to make sure that this transition wouldn't be TOO bad for folks. Therefore, we could keep the current version of BeginPlot around as a wrapper of the new API, and hang on to SetNextPlotX API for a while. I would likely place these under #infdef IMPLOT_DISABLE_OBSOLETE_FUNCTIONS, and remove them when we hit v1.0.

Prototype

A really early and quite buggy prototype of this API can found on the features/setup branch. Working on this will be my main priority for the next few weeks, and other work such as backends GPU rendering will go on hold until this is done.

Please share your thoughts and concerns. I'm all ears and would be happy to discuss alternative solutions. Thank you!

[AdrianoParisi23]

Heyo, thanks for the inclusion in the original list!

Have you considered instead of having individual functions to set up everything just pass the data is via structs? So instead of

bool BeginPlot(const char* title_id,
               const char* x_label      = NULL,
               const char* y_label      = NULL,
               const ImVec2& size       = ImVec2(-1,0),
               ImPlotFlags flags        = ImPlotFlags_None,
               ImPlotAxisFlags x_flags  = ImPlotAxisFlags_None,
               ImPlotAxisFlags y_flags  = ImPlotAxisFlags_None,
               ImPlotAxisFlags y2_flags = ImPlotAxisFlags_NoGridLines,
               ImPlotAxisFlags y3_flags = ImPlotAxisFlags_NoGridLines,
               const char* y2_label     = NULL,
               const char* y3_label     = NULL);

we could have an API like

bool BeginPlot(const char* title_id,
               const ImVec2& size = ImVec2(-1,0),
               ImPlotLabelStruct labels = ImPlotLabels(),
               ImPlotFlags flags = ImPlotFlags_None,
               ImPlotAxisFlagsStruct axis_flags  = ImPlotAxisFlagsStruct());

with

struct ImPlotLabelStruct
{
    const char* x_label = NULL,
    const char* y_label = NULL,
    const char* y2_label = NULL,
    const char* y3_label = NULL,
}

struct ImPlotAxisFlagsStruct
{
    ImPlotAxisFlags x_flags  = ImPlotAxisFlags_None;
    ImPlotAxisFlags y_flags  = ImPlotAxisFlags_None;
    ImPlotAxisFlags y2_flags = ImPlotAxisFlags_NoGridLines;
    ImPlotAxisFlags y3_flags = ImPlotAxisFlags_NoGridLines;
}

Obviously, the names can be changed to what ever is needed, but it is an additional option to not make any massive changes and reduce the size of the Begin API. Or I may have missed the main issue of the discussion!

[epezent]

This is also a valid idea, and one I completely overlooked because, as @ocornut mentioned below, it's not a common pattern in ImGui proper (aside from say, ImFontConfig and AddFont...). I do like that this makes features easy to add without breaking the signature of any functions, though the same could be said for just adding more SetupAxisX() functions as they are needed. From the user's perspective though, I do feel that this would be a bit awkward to work with.

I'm curious what others think of this approach.

[marcizhu]

I think this would simplify a lot the public API of ImPlot, and even simplify/organize how data is stored internally, but from the user's perspective I believe it's a bit difficult to work with. For example, to set the plot labels one might have to do something like this:

ImPlotLabelStruct labels;
labels.x_label = "My X Label";
labels.y1_label = "My Y1 Label";
labels.y2_label = "My Y2 Label";

if (ImPlot::BeginPlot("Title", ImVec2(-1, 0), &labels)) {
    ...
}

Instead of just:

if (ImPlot::BeginPlot("Title")) {
    ImPlot::SetupAxis(ImAxis_X1, "My X Label");
    ImPlot::SetupAxis(ImAxis_Y1, "My Y1 Label");
    ImPlot::SetupAxis(ImAxis_Y2, "My Y2 Label");
    ...
}

I personally believe the latter is easier to use, more expressive and it's what an ImGui user would expect and be used to.

[epezent]

@marcizhu more or less summarized my thinking on the matter. Still not saying no though, and curious to hear from others.

[rokups]

Struct is a bit less verbose, but more importantly whenever order of option application is important - implot would have explicit control over that. Also it probably would be easier to migrate to struct. There may be some setup elements that could depend on running before some code at the end of BeginPlot() for example. I am also not really familiar with ImPlot codebase, but struct does seem like it would be easiest to implement.

[epezent]

Thanks @rokups!

Struct is a bit less verbose

That depends on what your definition of verbose is. Funny enough, the examples above are both 184 characters long! Either could be made shorter or less verbose at the expense of decreasing clarity, so I wouldn't say that's a strong justification at this point. One thing the struct code above isn't addressing is how auxiliary axes are enabled. So, something like this would be required.

ImPlotEnableStruct {
    bool X, Y1, Y2, Y3;
}

ImPlotLabelStruct labels;
labels.x_label = "My X Label";
labels.y1_label = "My Y1 Label";
labels.y2_label = "My Y2 Label";

ImPlotEnableStruct enable;
enable.X = enable.Y1 = enable.Y2 = true;

if (ImPlot::BeginPlot("Title", ImVec2(-1, 0), &enable, &labels)) {
    ...
}

Sure, you could lump those enable flags in with one of the other structs (actually, there should just be one struct), but it doesn't save the fact that you need to explicitly enable the axis. Whereas with the Setup approach, the Y2 axis is implicitly enabled when SetupAxis(ImAxis_Y2, "My Y2 Label") is called.

The main thing that turns me away from struct approach is that it doesn't feel very "ImGui". By that, I mean the API is suggesting to me that I'm responsible for holding state in the form of ImPlotLabelStruct and/or ImPlotAxisFlagsStruct. I think the inevitable outcome is that users would manage the lifetime of these structs external to their ImGui code (e.g. as a class member variable), which really gravitates away from the ImGui philosophy in my humble opinion. This is my gut reaction to it.

but more importantly whenever order of option application is important - implot would have explicit control over that

Great point! You are exactly right, and order could matter in a few cases. Setup functions could be designed to address this too (indeed my implementation already does so by, you guessed it, using a POD struct under the hood that is lazy evaluated when the time is right).

// user code

if (ImPlot::BeginPlot("Title")) {
    ImPlot::SetupAxis(ImAxis_X1, "My X Label");
    ImPlot::SetupAxisLimits(ImAxis_X1, -10, 10);
    ImPlot::PlotLine(...);
    ImPlot::EndPlot();
}

// implot_internal.h

struct ImPlotAxis {
    bool Enabled;
    double Min, Max;
    const char* Label;
    ... 
}

// implot.cpp

bool BeginPlot(...) {
    ...
    ImPlotAxis& ax; // reference to an axis on current plot
    ResetAxis(ax);  // stage for incoming calls to Setup*
    ...
}

void SetupAxis(ImAxis idx, const char* label) {
    assert(!GImPlot->SetupLocked);
    ImPlotAxis& ax = GImPlot->CurrentPlot->Axes[idx];
    ax.Enabled = true;
    ax.Label = label;
}

void SetupAxisLimits(ImAxis idx, double min, double max) {
    assert(!GImPlot->SetupLocked);
    ImPlotAxis& ax = GImPlot->CurrentPlot->Axes[idx];
    ax.Min = min; ax.Max = max;
}

void FinishSetup() {
    ...
    ImPlotAxis& ax;
    ProcessAxis(ax);
    ...
    GImPlot->SetupLocked = true;
}

void PlotLine(...) {
    if (!GImPlot->SetupLocked)
        FinishSetup();
    // do plotting
}

As I type this out, it becomes apparent that we could very easily add the following as a concession to struct fans:

SetupAxis(ImAxis idx, ImPlotAxis axis) {
    assert(!GImPlot->SetupLocked);
    ImPlotAxis& ax = GImPlot->CurrentPlot->Axes[idx];
    ax = axis;
}

So maybe the answer is "just offer both struct and Setup APIs"!

[ocornut]

I don't know ImPlot intimately enough to have a worthy opinion, but it looks like you've explored this enough so my gut feeling is that the SetupXXX systems like Tables API would be good. It is also nice that it mimics an existing API.

Note that a byproduct of having more function calls is you can consider stacking more arguments to them, so if you feel there are strong "common use" contenders for a SetupAxis() with a little more parameters it may be worth it. But yeah designing any API in Dear ImGui has always been a walking on that tightrope (and the core lib has its share of inconsistencies now).

The other advantage of those multiple Setup functions is if some API needs to change/break again in the future, it'll probably easier to work on that transition for one specific function than for a big BeginXXX function.

@AdrianoParisi23 is right that using structures with a default constructor is also good. I don't use this pattern in Dear ImGui show, but I've not nothing against it. It's more future proof but makes basic usage more verbose.

might be to delay all render until EndPlot

Sounds very much out of question! The more you have to hold on the more code and maintenance it'll be, and it's also likely going to be slower.

[epezent]

Thanks for the feedback Omar!

It is also nice that it mimics an existing API.

This was the big one. ImGui Tables to me feels like the most evolved API pattern.

Note that a byproduct of having more function calls is you can consider stacking more arguments to them, so if you feel there are strong "common use" contenders for a SetupAxis() with a little more parameters it may be worth it.

Absolutely, some of the things I listed above could be collapsed. It will take a bit of experimentation.

Sounds very much out of question! The more you have to hold on the more code and maintenance it'll be, and it's also likely going to be slower.

Totally agree.

[marcizhu]

First of all thanks for taking my opinion into consideration! 😄

Let me start by saying that I love this proposal for a few reasons. The main reason is that as a user of ImPlot I often found myself having to constantly look up the function signature of BeginPlot() because of the amount of parameters of that function. Sometimes I've even copied & pasted the function declaration into my current file so that I could be more productive. This new API looks a lot simpler, easy to use and memorize and more intuitive. Also, I feel like this API is much more expressive: if I see somewhere in the code ImPlot::SetupAxisLimits(ImAxis_Y2, 100, 100); I know for sure what that line does. On the other hand if I see ImVec2(100, 100) in the middle of BeginPlot() I'm not so sure. It might be the axis limits, but it also might be the plot size, and to be 100% sure I'd have to (once again) look up the function declaration/documentation.

Finally, another reason why I love this is performance: C and C++ do not have a limit on function parameters, so a function can have as many as you like, but there's a catch: after a certain amount of parameters (basically when you run out of registers), parameters will be passed through the stack, which means there will be lots of pushing and poping things onto the stack, as well as unnecessary memory accesses. The newer API doesn't have this issue, and as @ocornut stated, this allows us to add more parameters to any function should the need arise.

The Order of Setup Calls

The order of Setup*() calls looks good to me and shouldn't be hard to implement. I think this is good and I don't have much else to say in that regard.

Breaking User Compatibility

It is clear that breaking compatibility with 99.999% of users in a single commit is totally undesirable, and I agree that deprecating the current BeginPlot() function (possibly with a compilation warning) and turning it into a wrapper for the new API is the way to go. For users, this would mean that updating to the latest ImPlot version generates tons of compilation warnings, but that's it. Everything still works as it used to and the warnings contain some info on how to update to the new API. Then, after some time, the old API is disabled by default, but can still be enabled using a macro (for example #define IMPLOT_ENABLE_OBSOLETE_FUNCTIONS as you suggested). This would mean that new users won't rely on the old API, and would force users to gradually move to the new Setup API. Finally, after some time we remove the old API (possibly on v1.0) altogether.

Once again, thanks for asking for feedback on this matter. If you need help implementing some features, just ask me and I'll do it as soon as possible 😄

[epezent]

Let me start by saying that I love this proposal

:)

. This new API looks a lot simpler, easy to use and memorize and more intuitive. Also, I feel like this API is much more expressive.

Excellent point! Expressiveness was not a part of my initial motivation, but is certainly an important byproduct.

possibly with a compilation warning

Yea, that seems like a good idea. C++14 has [[deprecated]], but I think there are compiler specific methods we could fallback to.

If you need help implementing some features, just ask me and I'll do it as soon as possible

Will do! It may take a week or so to get the branch into a presentable state. After that, the biggest help would be in testing the new API and updating the demo. I will keep this thread posted on progress, and request help when I need it. Of course, please post any ideas or asks that you have -- I'm sure you'll have some, as this approach opens up a lot of new possibilities. Thanks again Marc!

[yan-zaretskiy]

To me, this problem looks like a perfect fit for the builder pattern. You'd make a separate type responsible for accumulating various configuration options, and when you are ready, you'd call a build method on it (or pass it to BeginPlot). So this

// the basics
if (ImPlot::BeginPlot("Example 2")) {
    ImPlot::SetupAxis(ImAxis_X1, "My X-Axis", ImPlotAxisFlags_Time);
    ImPlot::SetupAxis(ImAxis_Y1, "My Y-Axis", ImPlotAxisFlags_Invert);
    ImPlot::PlotLine("data",x_data,y_data,2);
    ImPlot::EndPlot();
}

would turn into something like

PlotBuilder plot;
plot.Title("Example 2")
    .SetupAxis(ImAxis_X1, "My X-Axis", ImPlotAxisFlags_Time)
    .SetupAxis(ImAxis_Y1, "My Y-Axis", ImPlotAxisFlags_Invert);

if (ImPlot::BeginPlot(plot)) {
    ImPlot::PlotLine("data",x_data,y_data,2);
    ImPlot::EndPlot();
}

The benefit is that the builder just accumulates options via its public API, which you can enrich as you add new features. There's also no order that these calls have to stick to. Calling BeginPlot with the PlotBuilder argument will take care of what has to be done by FinishSetup in your message above.

[epezent]

Thanks for the feedback Yan! I think this offers some advantages over the Setup proposal in that it has less potential to be misused (i.e. user can't call Setup, PlotX, then Setup again). The downsides are similar to those of structs (see my post above), and requires a temporary copy of relevant plot data until the next call to BeginPlot (same problem that currently exists with SetNextPlotX), whereas calling SetupX inside of BeginPlot can just set the data that already exists.

[yan-zaretskiy]

...requires a temporary copy of relevant plot data until the next call to BeginPlot (same problem that currently exists with SetNextPlotX), whereas calling SetupX inside of BeginPlot can just set the data that already exists.

I don't quite follow, but I trust your judgement. If I understood you correctly though, I wouldn't set the data using the builder API, I'd probably have it still set inside the BeginPlot block.

I think the main argument against these alternative approaches are existing API conventions. I think API familiarity is a valid requirement.

[dvj]

I believe the existing non-objective API convention could be kept by simply making them wrapping calls using a global builder object. In this sense, the API would still suffer from the current problems which make the asserts necessary (out of order calls, etc), but it would also allow a user to directly use an OO pattern if desired. This encapsulation is very nice from a larger software engineering perspective, fits in with existing OO code, and as @sergeyn points out below, also allows some degree of parallelization. I also believe the performance issue of copying data can be worked around, but maybe you have a specific case in mind that it wouldn't, @epezent ?

Dear ImGUI may never be able to make this type of switch, but if the existing "familiar" API can be kept behind the scenes, I think a builder/OO approach has a lot of upside for ImPlot.

[hoffstadt]

I also appreciate being tagged in this post.

I like the idea of treating the individual components of the plot as such. I'm not very familiar with implot's internals, so I'm not sure if this is viable but may help with idea generation.

if (ImPlot::BeginPlot("Example 3",ImVec2(-1,-1), ImPlotFlags_NoTitle)) {

    ImPlot::BeginAxis(ImAxis_X, "My X-Axis 1", "%g V");
    ImPlot::SetAxisLimits(-10, 10);
    ImPlot::EndAxis();

    if(ImPlot::BeginAxis(ImAxis_X, "My X-Axis 2", "%.3f mA"))
    {
        // returns "true" if axis is clicked for a custom context menu
    }
    ImPlot::SetAxisTicks(0,1,5);
    ImPlot::EndAxis();

    ImPlot::BeginAxis(ImAxis_Y, "My Y-Axis 1", ImPlotAxisFlags_Opposite);
    ImPlot::EndAxis();

    ImPlot::BeginAxis(ImAxis_Y, "My Y-Axis 2", ImPlotAxisFlags_Opposite, MyFormatCallback);
    ImPlot::SetAxisLimits(0, 10000);
    ImPlot::EndAxis();

    if(ImPlot::BeginLegend(ImPlotLocation_North, ImPlotLegendFlags_Outside|ImPlotLegendFlags_Horizontal))
    {
        // returns "true" if legend is clicked for a custom context menu
    }

    ImPlot::SetAxes(0, 0); // first x and y axes
    if(ImPlot::PlotLine("data22",x_data,y_data,2))
    {
        // returns "true" if legend entry is clicked for a custom context menu
    }

    ImPlot::EndPlot();
}

and the simple case:

if (ImPlot::BeginPlot("Example 2")) {
    ImPlot::BeginAxis(ImAxis_X, "My X-Axis", ImPlotAxisFlags_Time);
    ImPlot::EndAxis();
    ImPlot::BeginAxis(ImAxis_Y, "My Y-Axis", ImPlotAxisFlags_Invert);
    ImPlot::EndAxis();
    ImPlot::PlotLine("data",x_data,y_data,2);
    ImPlot::EndPlot();
}

[epezent]

Extending the Begin/End concept to axes has definitely crossed my mind. Even as far as thinking that perhaps PlotX should happen within that scope. For example:

if (BeginPlot(...)) {
    if (BeginAxis(ImAxis_X1)) {
        if (BeginAxis(ImAxis_Y1)) {
            ImPlot::PlotLine(...);
            ImPlot::EndAxis();
        }    
        ImPlot::EndAxis();
    }
    ImPlot::EndPlot();
}

Mind you this is extremely verbose and gross; we'd never do this. But it's something worth noodling on for sure...

[hoffstadt]

Yeah that would be pretty nasty which is why I liked the ImPlot::SetAxes(...) function you would call before adding series. Either way, I'm sure you will choose the right path and we will use whatever you come up with. Begin/End concept is similar to the direction we went when wrapping implot, so I may not be impartial here ha.

[epezent]

if(ImPlot::PlotLine("data22",x_data,y_data,2))
{
    // returns "true" if legend entry is clicked for a custom context menu
}

Now that's a great idea! Returning bool from PlotX functions isn't something I've considered. I can think of a few other applications too (e.g. true if line or point hovered, then get hovered element index with int HoveredElement() or something like that).

[sergeyn]

Thanks for showing interest in my opinion. My 2 cents:

1. Please keep current interface working for backwards compatibility . Or add a macro to get old interface back.
2. In general more functions is probably nicer than lest functions but each is 50 arguments long.
3. One addition I'd think about - make it objective. With objective interface you can construct multiple plots at once, and it also helps with making plot construction parallel friendly. I know that ImGui is inherently serial now, but I don't think it's it's too difficult to hack around some parallelization for individual case like ImPlot when you need it. Having interface already parallel friendly mostly will make this job much easier.

[ocornut]

Another thing to potentially consider:
The upcoming WIP binding generator ("dear bindings") is designed to parse imgui.h and similar headers and generate C wrapper as well as metadata to automatically generate bindings. An API design that can map to other languages can keep this process automatic and therefore enable users from any languages to use implot.

[epezent]

Thanks for the additional feedback everyone. My gut feeling is to press forward with the original proposal for the public API in implot.h, while exploring if this could be built on top of a more "objective" API that is exposed in implot_internal.h. And, of course, while attempting to keep the changes backward compatible.

Hoping to work more on this soon -- life and work have put a hold on progress lately.

[epezent]

FYI, #294 added the proposed Setup API to the public header (among many other changes -- see #168 (comment)). There is still more work to be done to enable the objective APIs suggested here, but it is much closer than before.

@ocornut , where is the "dear bindings" you mentioned currently located. I'm curious if ImPlot's API is conformal as is, or will need some tweaks.

[ocornut]

@epezent I gave you access to it a while ago, it is currently at https://github.com/dearimgui/dear_bindings (may move)
It hasn't been tested on ImPlot yet, there are some unresolved issue with emitting imgui_internal.h bindings but they should be fixed.
Feel free to open an issue if you find it doesn't work yet for ImPlot (or even a PR if you feel like it)