render: Add SDL_RenderDebugText().

Fixes #11201.

examples/CMakeLists.txt

@@ -134,6 +134,7 @@ add_sdl_example_executable(renderer-color-mods SOURCES renderer/11-color-mods/co
 add_sdl_example_executable(renderer-viewport SOURCES renderer/14-viewport/viewport.c DATAFILES ${CMAKE_CURRENT_SOURCE_DIR}/../test/sample.bmp)
 add_sdl_example_executable(renderer-cliprect SOURCES renderer/15-cliprect/cliprect.c DATAFILES ${CMAKE_CURRENT_SOURCE_DIR}/../test/sample.bmp)
 add_sdl_example_executable(renderer-read-pixels SOURCES renderer/17-read-pixels/read-pixels.c DATAFILES ${CMAKE_CURRENT_SOURCE_DIR}/../test/sample.bmp)
+add_sdl_example_executable(renderer-debug-text SOURCES renderer/18-debug-text/debug-text.c)
 add_sdl_example_executable(audio-simple-playback SOURCES audio/01-simple-playback/simple-playback.c)
 add_sdl_example_executable(audio-simple-playback-callback SOURCES audio/02-simple-playback-callback/simple-playback-callback.c)
 add_sdl_example_executable(audio-load-wav SOURCES audio/03-load-wav/load-wav.c DATAFILES ${CMAKE_CURRENT_SOURCE_DIR}/../test/sample.wav)

examples/renderer/18-debug-text/README.txt

@@ -0,0 +1,4 @@
+This example creates an SDL window and renderer, and draws some text
+using SDL_RenderDebugText(). This is not quality text rendering, but it can
+be helpful for simple apps, debugging, or showing something in a pinch.
+

examples/renderer/18-debug-text/debug-text.c

@@ -0,0 +1,75 @@
+/*
+ * This example creates an SDL window and renderer, and then draws some text
+ * using SDL_RenderDebugText() every frame.
+ *
+ * This code is public domain. Feel free to use it for any purpose!
+ */
+
+#define SDL_MAIN_USE_CALLBACKS 1  /* use the callbacks instead of main() */
+#include <SDL3/SDL.h>
+#include <SDL3/SDL_main.h>
+
+/* We will use this renderer to draw into this window every frame. */
+static SDL_Window *window = NULL;
+static SDL_Renderer *renderer = NULL;
+
+#define WINDOW_WIDTH 640
+#define WINDOW_HEIGHT 480
+
+/* This function runs once at startup. */
+SDL_AppResult SDL_AppInit(void **appstate, int argc, char *argv[])
+{
+    SDL_SetAppMetadata("Example Renderer Debug Texture", "1.0", "com.example.renderer-debug-text");
+
+    if (!SDL_Init(SDL_INIT_VIDEO)) {
+        SDL_Log("Couldn't initialize SDL: %s", SDL_GetError());
+        return SDL_APP_FAILURE;
+    }
+
+    if (!SDL_CreateWindowAndRenderer("examples/renderer/debug-text", WINDOW_WIDTH, WINDOW_HEIGHT, 0, &window, &renderer)) {
+        SDL_Log("Couldn't create window/renderer: %s", SDL_GetError());
+        return SDL_APP_FAILURE;
+    }
+
+    return SDL_APP_CONTINUE;  /* carry on with the program! */
+}
+
+/* This function runs when a new event (mouse input, keypresses, etc) occurs. */
+SDL_AppResult SDL_AppEvent(void *appstate, SDL_Event *event)
+{
+    if (event->type == SDL_EVENT_QUIT) {
+        return SDL_APP_SUCCESS;  /* end the program, reporting success to the OS. */
+    }
+    return SDL_APP_CONTINUE;  /* carry on with the program! */
+}
+
+/* This function runs once per frame, and is the heart of the program. */
+SDL_AppResult SDL_AppIterate(void *appstate)
+{
+    /* as you can see from this, rendering draws over whatever was drawn before it. */
+    SDL_SetRenderDrawColor(renderer, 0, 0, 0, 255);  /* black, full alpha */
+    SDL_RenderClear(renderer);  /* start with a blank canvas. */
+
+    SDL_SetRenderDrawColor(renderer, 255, 255, 255, 255);  /* white, full alpha */
+    SDL_RenderDebugText(renderer, 272, 100, "Hello world!");
+    SDL_RenderDebugText(renderer, 224, 150, "This is some debug text.");
+
+    SDL_SetRenderDrawColor(renderer, 51, 102, 255, 255);  /* light blue, full alpha */
+    SDL_RenderDebugText(renderer, 184, 200, "You can do it in different colors.");
+    SDL_SetRenderDrawColor(renderer, 255, 255, 255, 255);  /* white, full alpha */
+
+    SDL_SetRenderScale(renderer, 4.0f, 4.0f);
+    SDL_RenderDebugText(renderer, 14, 65, "It can be scaled.");
+    SDL_SetRenderScale(renderer, 1.0f, 1.0f);
+    SDL_RenderDebugText(renderer, 64, 350, "This only does ASCII chars. So this laughing emoji won't draw: 🤣");
+    SDL_RenderPresent(renderer);  /* put it all on the screen! */
+
+    return SDL_APP_CONTINUE;  /* carry on with the program! */
+}
+
+/* This function runs once at shutdown. */
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
+{
+    /* SDL will clean up the window/renderer for us. */
+}
+

include/SDL3/SDL_render.h

@@ -2464,6 +2464,57 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int
  */
 extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync);
 
+/**
+ * The size, in pixels, of a single SDL_RenderDebugText() character.
+ *
+ * The font is monospaced and square, so this applies to all characters.
+ *
+ * \since This macro is available since SDL 3.1.5.
+ *
+ * \sa SDL_RenderDebugText
+ */
+#define SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE 8
+
+/**
+ * Draw debug text to an SDL_Renderer.
+ *
+ * This function will render a string of text to an SDL_Renderer. Note that
+ * this is a convenience function for debugging, with severe limitations, and
+ * not intended to be used for production apps and games.
+ *
+ * Among these limitations:
+ *
+ * - It accepts UTF-8 strings, but will only renders ASCII characters.
+ * - It has a single, tiny size (8x8 pixels). One can use logical
+ *   presentation or scaling to adjust it, but it will be blurry.
+ * - It uses a simple, hardcoded bitmap font. It does not allow different
+ *   font selections and it does not support truetype, for proper scaling.
+ * - It does no word-wrapping and does not treat newline characters as a line
+ *   break. If the text goes out of the window, it's gone.
+ *
+ * For serious text rendering, there are several good options, such as
+ * SDL_ttf, stb_truetype, or other external libraries.
+ *
+ * On first use, this will create an internal texture for rendering glyphs.
+ * This texture will live until the renderer is destroyed.
+ *
+ * The text is drawn in the color specified by SDL_SetRenderDrawColor().
+ *
+ * \param renderer the renderer which should draw a line of text.
+ * \param x the x coordinate where the top-left corner of the text will draw.
+ * \param y the y coordinate where the top-left corner of the text will draw.
+ * \param str the string to render.
+ * \returns true on success or false on failure; call SDL_GetError() for more
+ *          information.
+ *
+ * \threadsafety You may only call this function from the main thread.
+ *
+ * \since This function is available since SDL 3.1.5.
+ *
+ * \sa SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE
+ */
+extern SDL_DECLSPEC bool SDLCALL SDL_RenderDebugText(SDL_Renderer *renderer, float x, float y, const char *str);
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }

src/dynapi/SDL_dynapi.sym

@@ -1181,6 +1181,7 @@ SDL3_0.0.0 {
     SDL_CalculateGPUTextureFormatSize;
     SDL_SetErrorV;
     SDL_GetDefaultLogOutputFunction;
+    SDL_RenderDebugText;
     # extra symbols go here (don't modify this line)
   local: *;
 };

src/dynapi/SDL_dynapi_overrides.h

@@ -1206,3 +1206,4 @@
 #define SDL_CalculateGPUTextureFormatSize SDL_CalculateGPUTextureFormatSize_REAL
 #define SDL_SetErrorV SDL_SetErrorV_REAL
 #define SDL_GetDefaultLogOutputFunction SDL_GetDefaultLogOutputFunction_REAL
+#define SDL_RenderDebugText SDL_RenderDebugText_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -1212,3 +1212,4 @@ SDL_DYNAPI_PROC(void,SDL_DelayPrecise,(Uint64 a),(a),)
 SDL_DYNAPI_PROC(Uint32,SDL_CalculateGPUTextureFormatSize,(SDL_GPUTextureFormat a, Uint32 b, Uint32 c, Uint32 d),(a,b,c,d),return)
 SDL_DYNAPI_PROC(bool,SDL_SetErrorV,(SDL_PRINTF_FORMAT_STRING const char *a,va_list b),(a,b),return)
 SDL_DYNAPI_PROC(SDL_LogOutputFunction,SDL_GetDefaultLogOutputFunction,(void),(),return)
+SDL_DYNAPI_PROC(bool,SDL_RenderDebugText,(SDL_Renderer *a,float b,float c,const char *d),(a,b,c,d),return)

src/render/SDL_render.c

@@ -23,6 +23,7 @@
 // The SDL 2D rendering system
 
 #include "SDL_sysrender.h"
+#include "SDL_render_debug_font.h"
 #include "software/SDL_render_sw_c.h"
 #include "../video/SDL_pixels_c.h"
 #include "../video/SDL_video_c.h"
@@ -5097,6 +5098,9 @@ void SDL_DestroyRendererWithoutFreeing(SDL_Renderer *renderer)
 
     SDL_DiscardAllCommands(renderer);
 
+    SDL_DestroyTexture(renderer->debug_char_texture_atlas);
+    renderer->debug_char_texture_atlas = NULL;
+
     // Free existing textures for this renderer
     while (renderer->textures) {
         SDL_Texture *tex = renderer->textures;
@@ -5346,3 +5350,119 @@ bool SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync)
     }
     return true;
 }
+
+
+#define SDL_DEBUG_FONT_GLYPHS_PER_ROW 14
+
+static bool CreateDebugTextAtlas(SDL_Renderer *renderer)
+{
+    SDL_assert(renderer->debug_char_texture_atlas == NULL);  // don't double-create it!
+
+    const int charWidth = SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE;
+    const int charHeight = SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE;
+
+    // actually make each glyph two pixels taller/wider, to prevent scaling artifacts.
+    const int rows = (SDL_DEBUG_FONT_NUM_GLYPHS / SDL_DEBUG_FONT_GLYPHS_PER_ROW) + 1;
+    SDL_Surface *atlas = SDL_CreateSurface((charWidth + 2) * SDL_DEBUG_FONT_GLYPHS_PER_ROW, rows * (charHeight + 2), SDL_PIXELFORMAT_RGBA8888);
+    if (!atlas) {
+        return false;
+    }
+
+    const int pitch = atlas->pitch;
+    SDL_memset(atlas->pixels, '\0', atlas->h * atlas->pitch);
+
+    int column = 0;
+    int row = 0;
+    for (int glyph = 0; glyph < SDL_DEBUG_FONT_NUM_GLYPHS; glyph++) {
+        // find top-left of this glyph in destination surface. The +2's account for glyph padding.
+        Uint8 *linepos = (((Uint8 *)atlas->pixels) + ((row * (charHeight + 2) + 1) * pitch)) + ((column * (charWidth + 2) + 1) * sizeof (Uint32));
+        const Uint8 *charpos = SDL_RenderDebugTextFontData + (glyph * 8);
+
+        // Draw the glyph to the surface...
+        for (int iy = 0; iy < charHeight; iy++) {
+            Uint32 *curpos = (Uint32 *)linepos;
+            for (int ix = 0; ix < charWidth; ix++) {
+                if ((*charpos) & (1 << ix)) {
+                    *curpos = 0xffffffff;
+                } else {
+                    *curpos = 0;
+                }
+                ++curpos;
+            }
+            linepos += pitch;
+            ++charpos;
+        }
+
+        // move to next position (and if too far, start the next row).
+        column++;
+        if (column >= SDL_DEBUG_FONT_GLYPHS_PER_ROW) {
+            row++;
+            column = 0;
+        }
+    }
+
+    SDL_assert((row < rows) || ((row == rows) && (column == 0)));  // make sure we didn't overflow the surface.
+
+    // Convert temp surface into texture
+    renderer->debug_char_texture_atlas = SDL_CreateTextureFromSurface(renderer, atlas);
+    SDL_DestroySurface(atlas);
+
+    return (renderer->debug_char_texture_atlas != NULL);
+}
+
+static bool DrawDebugCharacter(SDL_Renderer *renderer, float x, float y, Uint32 c)
+{
+    SDL_assert(renderer->debug_char_texture_atlas != NULL);   // should have been created by now!
+
+    const int charWidth = SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE;
+    const int charHeight = SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE;
+
+    // Character index in cache
+    Uint32 ci = c;
+    if ((ci <= 32) || ((ci >= 127) && (ci <= 160))) {
+        return true;  // these are just completely blank chars, don't bother doing anything.
+    } else if (ci >= SDL_DEBUG_FONT_NUM_GLYPHS) {
+        ci = SDL_DEBUG_FONT_NUM_GLYPHS - 1;  // use our "not a valid/supported character" glyph.
+    } else if (ci < 127) {
+        ci -= 33;     // adjust for the 33 blank glyphs at the start
+    } else {
+        ci -= 67;     // adjust for the 33 blank glyphs at the start AND the 34 gap in the middle.
+    }
+
+    const float src_x = (float) (((ci % SDL_DEBUG_FONT_GLYPHS_PER_ROW) * (charWidth + 2)) + 1);
+    const float src_y = (float) (((ci / SDL_DEBUG_FONT_GLYPHS_PER_ROW) * (charHeight + 2)) + 1);
+
+    // Draw texture onto destination
+    const SDL_FRect srect = { src_x, src_y, (float) charWidth, (float) charHeight };
+    const SDL_FRect drect = { x, y, (float) charWidth, (float) charHeight };
+    return SDL_RenderTexture(renderer, renderer->debug_char_texture_atlas, &srect, &drect);
+}
+
+bool SDL_RenderDebugText(SDL_Renderer *renderer, float x, float y, const char *s)
+{
+    CHECK_RENDERER_MAGIC(renderer, false);
+
+    // Allocate a texture atlas for this renderer if needed.
+    if (!renderer->debug_char_texture_atlas) {
+        if (!CreateDebugTextAtlas(renderer)) {
+            return false;
+        }
+    }
+
+    bool result = true;
+
+    Uint8 r, g, b, a;
+    result &= SDL_GetRenderDrawColor(renderer, &r, &g, &b, &a);
+    result &= SDL_SetTextureColorMod(renderer->debug_char_texture_atlas, r, g, b);
+    result &= SDL_SetTextureAlphaMod(renderer->debug_char_texture_atlas, a);
+
+    float curx = x;
+    Uint32 ch;
+
+    while (result && ((ch = SDL_StepUTF8(&s, NULL)) != 0)) {
+        result &= DrawDebugCharacter(renderer, curx, y, ch);
+        curx += SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE;
+    }
+
+    return result;
+}

src/render/SDL_sysrender.h

@@ -305,6 +305,8 @@ struct SDL_Renderer
 
     SDL_PropertiesID props;
 
+    SDL_Texture *debug_char_texture_atlas;
+
     bool destroyed;   // already destroyed by SDL_DestroyWindow; just free this struct in SDL_DestroyRenderer.
 
     void *internal;