Add SDL_RenderDebugTextF & SDL_RenderDebugTextV

[williamistGitHub]

Description

SDL_RenderDebugText is a useful function to quickly put debug text on the screen, but provides no easy way to display other data useful for debugging such as numbers. In an attempt to rectify that, I've added SDL_RenderDebugTextF as well as SDL_RenderDebugTextV. These functions allow you to pass in a format string as well as the formatting arguments (either variadicly or as a va_list respectively) and will run them through SDL_vsnprintf before itself calling SDL_RenderDebugText to do the actual rendering. This should hopefully make it easier to quickly put useful data such as framerate, particle count, or whatever else is needed onto the screen without having to format them into a string manually.

I'm not too sure if I've done everything correctly here (mainly I wasn't sure what to put in the \since documentation tags, I just used 3.1.7 as that's what was in CMakeLists.txt), but hopefully it's not too bad :)

Existing Issue(s)

No issue.

[slouken]

@icculus, is this something we want?

[icculus]

Mmmm...I don't think we should add this. It's trivial enough to use SDL_snprintf() directly.

[williamistGitHub]

Potentially, but I feel using a single function over two is cleaner and less verbose, especially if you're repeatedly formatting and rendering debug text to display multiple lines of data. If you feel like it isn't worth the extra functions though, that's understandable.

[slouken]

I think the F variant is worth adding, but I don't think this is something people should generally be wrapping other format print functions around, so let's drop the V variant.

@icculus, technically it's an ABI break, but can we just switch the existing function to take format params instead of a single text pointer? 99.99% of uses will not contain '%', and should be safe as-is.

[icculus]

I was thinking it would be better if the one function just accepted format args, had we thought of that before shipping a prerelease. We can just add a second function, and reduce it in SDL4. :)

[icculus]

Okay, we did some experimentation, and we think that just changing the existing function to take a format string is binary compatible across a bunch of architectures, and the risk overall of changing this is small at this point, as it's only in one prerelease, so we're going to take a shot at it.

This is totally pushing the boundaries on ABI stability, but we think it's the correct technical decision.

I'm going to merge this PR so you get credit for the work, then make the changes on top of that.

[icculus]

Okay, this is rebased and updated to just have the original function offer printf-style formatting.

Let the builders and @slouken check it, then go ahead and merge!

[slouken]

I'm looking at these changes, wondering if maybe we should just have a separate function. Having to add "%s" to all the existing call sites seems clunky.

[icculus]

This brings me back to "they can just call snprintf and hand us a string" then. :/

[slouken]

This brings me back to "they can just call snprintf and hand us a string" then. :/

Fair enough. :)

[williamistGitHub]

Just saw this, ah well, too bad I suppose. Maybe next time :)

[icculus]

Your patch was well-constructed, to be clear, we just decided against adding the API here.

[slouken]

It also doesn’t mean we won’t add it later, we are just trying to keep things lean and focused for release.

[icculus]

Okay, I force-pushed to dump my changes and get us sync'd up to main; I think we'll take the RenderDebugTextF function (but not the V version).

So as not to confuse the naming with floating point things that end in 'F', can I rename this SDL_RenderDebugTextFormat (or Fmt, or something else?)

[slouken]

SDL_RenderDebugTextFormat

[madebr]

Is this the first fixme for SDL4? :sweat_smile:

[slouken]

Probably not, both functions are useful, like puts() vs printf()

[icculus]

Okay, changes are ready; if the builders like it, we can merge.