Lightweight command console renderer for mxvk::VK_Window. More...

#include <mxvk/include/mxvk/mxvk_console.hpp>

Public Types
using	CommandCallback = std::function<bool(VK_Window &window, const std::vector<std::string> &args, std::ostream &output)>

Public Member Functions
void	attach (VK_Window &window, const std::string &fontPath, int fontSize=18)
	Attach this console to a window and configure console font rendering.
void	clear ()
	Clear all buffered output lines.
void	draw ()
	Draw the current console overlay.
void	handleEvent (const SDL_Event &event)
	Handle keyboard/text events for the console.
void	hide () noexcept
	Hide console.
const std::string &	inputBuffer () const noexcept
void	invalidateLayoutCache ()
	Recompute cached line wrapping after font or layout metrics change.
bool	isVisible () const noexcept
void	printLine (const std::string &line, SDL_Color color=SDL_Color{255, 255, 255, 255})
	Append one line to console output.
void	setCommandCallback (CommandCallback callback)
	Register a command callback.
void	setFont (const std::string &fontPath, int fontSize)
	Change only the console font, leaving the window default font unchanged.
void	setMaxLines (std::size_t maxLines)
	Set max number of retained output lines.
void	setMaxVisibleLines (std::size_t maxVisibleLines)
	Set max number of lines rendered on screen.
void	setPrompt (const std::string &prompt)
	Set the input prompt text.
void	setSpriteYOriginTopLeft (bool enabled) noexcept
	Select whether console sprite elements use top-left Y coordinates.
void	setVisible (bool value) noexcept
	Show or hide the console.
void	show () noexcept
	Show console.
void	toggle () noexcept
	Toggle console visibility.
	VK_Console ()=default

Detailed Description

Lightweight command console renderer for mxvk::VK_Window.

The console captures keyboard input, keeps command history, renders buffered lines via VK_Window::printText, and allows applications to register a command callback.

Definition at line 32 of file mxvk_console.hpp.

Member Typedef Documentation

◆ CommandCallback

using mxvk::VK_Console::CommandCallback = std::function<bool(VK_Window &window, const std::vector<std::string> &args, std::ostream &output)>

Definition at line 34 of file mxvk_console.hpp.

Constructor & Destructor Documentation

◆ VK_Console()

mxvk::VK_Console::VK_Console ( )

default

Member Function Documentation

◆ attach()

void mxvk::VK_Console::attach	(	VK_Window &	window,
		const std::string &	fontPath,
		int	fontSize = 18 )

Attach this console to a window and configure console font rendering.

Definition at line 18 of file mxvk_console.cpp.

                                                                                            {
        windowPtr = &window;
        setFont(fontPath, fontSize);
        panel_sprite = nullptr;
        cursor_sprite = nullptr;
        scroll_track_sprite = nullptr;
        scroll_thumb_sprite = nullptr;
        visible = false;
        fade_active = false;
        fade_alpha = 0.0f;
        fade_start_alpha = 0.0f;
        fade_target_alpha = 0.0f;
        fade_start_ns = 0;
        history_index = -1;
        cursor_pos = 0;
        input.clear();
        scroll_offset = 0;
        follow_tail = true;
        scrollbar_dragging = false;
        scrollbar_drag_offset = 0;
    }

◆ clear()

void mxvk::VK_Console::clear ( )

Clear all buffered output lines.

Definition at line 136 of file mxvk_console.cpp.

                           {
        total_line_chars = 0;
        lines.clear();
        invalidateWrappedCache();
        input.clear();
        cursor_pos = 0;
        scroll_offset = 0;
        follow_tail = true;
        history_index = -1;
    }

◆ draw()

void mxvk::VK_Console::draw ( )

Draw the current console overlay.

Call once per frame from proc().

Definition at line 721 of file mxvk_console.cpp.

                          {
        if (windowPtr == nullptr) {
            return;
        }
 
        if (fade_active) {
            const Uint64 now = SDL_GetTicksNS();
            const double elapsed = static_cast<double>(now - fade_start_ns);
            const double duration = static_cast<double>(fade_duration_ns);
            const float t = static_cast<float>(std::clamp(elapsed / std::max(1.0, duration), 0.0, 1.0));
            fade_alpha = fade_start_alpha + ((fade_target_alpha - fade_start_alpha) * t);
            if (t >= 1.0f) {
                fade_alpha = fade_target_alpha;
                fade_active = false;
            }
        }
 
        if (!(visible || fade_alpha > 0.0f)) {
            return;
        }
 
        const float alpha = std::clamp(fade_alpha, 0.0f, 1.0f);
        if (alpha <= 0.0f) {
            return;
        }
 
        const auto scaledColor = [alpha](const SDL_Color &src) {
            SDL_Color out = src;
            const int scaled = static_cast<int>(std::lround(static_cast<double>(src.a) * alpha));
            out.a = static_cast<Uint8>(std::clamp(scaled, 0, 255));
            return out;
        };
 
        updatePanelLayout();
        ensurePanelSprite();
        ensureCursorSprite();
        ensureScrollSprites();
        const auto consoleSpriteY = [this](const int y, const int h) {
            if (sprite_y_origin_top_left) {
                return std::max(0, y);
            }
 
            const int screen_h = static_cast<int>(windowPtr->getSwapchainExtent().height);
            return std::max(0, screen_h - y - h);
        };
 
        if (panel_sprite != nullptr) {
            SDL_Surface *surface = SDL_CreateSurface(2, 2, SDL_PIXELFORMAT_RGBA32);
            if (surface != nullptr) {
                const SDL_PixelFormatDetails *const fmt = SDL_GetPixelFormatDetails(SDL_PIXELFORMAT_RGBA32);
                const int panel_alpha = static_cast<int>(std::lround(170.0 * alpha));
                SDL_FillSurfaceRect(surface, nullptr, SDL_MapRGBA(fmt, nullptr, 0, 0, 0, static_cast<Uint8>(std::clamp(panel_alpha, 0, 255))));
                panel_sprite->updateTexture(surface);
                SDL_DestroySurface(surface);
            }
 
            panel_sprite->drawSpriteRect(panel_x, consoleSpriteY(panel_y, panel_h), panel_w, panel_h);
        }
 
        int glyph_w = 8;
        int glyph_h = 18;
        if (!windowPtr->getTextDimensions("M", glyph_w, glyph_h, console_font)) {
            glyph_h = 18;
        }
 
        const int line_height = std::max(1, glyph_h + 2);
        const int padding = 10;
        const int text_width = usableTextWidth();
        ensureWrappedCache(text_width);
 
        int y = panel_y + padding;
        windowPtr->printText("MXVK Console (F3 to toggle)", panel_x + padding, y, scaledColor(info_color), console_font);
        y += line_height;
 
        const int input_y = panel_y + panel_h - padding - line_height;
        const int available_height = std::max(line_height, input_y - y - 6);
        content_top_y = y;
        content_bottom_y = y + available_height;
        last_visible_line_count = std::max<std::size_t>(1, static_cast<std::size_t>(available_height / line_height));
        if (follow_tail) {
            scroll_offset = 0;
        }
 
        const std::size_t max_offset = maxScrollOffset();
        scroll_offset = std::min(scroll_offset, max_offset);
        updateScrollbarGeometry();
 
        const std::size_t visible_lines = std::min(effectiveVisibleLineCount(), wrapped_cache.size());
        const std::size_t start = (wrapped_cache.size() > visible_lines) ? (wrapped_cache.size() - visible_lines - scroll_offset) : 0;
        const std::size_t end = std::min(wrapped_cache.size(), start + visible_lines);
        for (std::size_t i = start; i < end; ++i) {
            windowPtr->printText(wrapped_cache[i].text, panel_x + padding, y, scaledColor(wrapped_cache[i].color), console_font);
            y += line_height;
        }
 
        if (scroll_track_sprite != nullptr && scrollbar_h > 0) {
            SDL_Surface *surface = SDL_CreateSurface(2, 2, SDL_PIXELFORMAT_RGBA32);
            if (surface != nullptr) {
                const SDL_PixelFormatDetails *const fmt = SDL_GetPixelFormatDetails(SDL_PIXELFORMAT_RGBA32);
                const int track_alpha = static_cast<int>(std::lround(96.0 * alpha));
                SDL_FillSurfaceRect(surface, nullptr, SDL_MapRGBA(fmt, nullptr, 255, 255, 255, static_cast<Uint8>(std::clamp(track_alpha, 0, 255))));
                scroll_track_sprite->updateTexture(surface);
                SDL_DestroySurface(surface);
            }
 
            scroll_track_sprite->drawSpriteRect(scrollbar_x, consoleSpriteY(scrollbar_y, scrollbar_h), scrollbar_w, scrollbar_h);
        }
 
        if (scroll_thumb_sprite != nullptr && scrollbar_thumb_h > 0) {
            SDL_Surface *surface = SDL_CreateSurface(2, 2, SDL_PIXELFORMAT_RGBA32);
            if (surface != nullptr) {
                const SDL_PixelFormatDetails *const fmt = SDL_GetPixelFormatDetails(SDL_PIXELFORMAT_RGBA32);
                const int base_alpha = scrollbar_dragging ? 240 : 190;
                const int thumb_alpha = static_cast<int>(std::lround(static_cast<double>(base_alpha) * alpha));
                SDL_FillSurfaceRect(surface, nullptr, SDL_MapRGBA(fmt, nullptr, 190, 225, 255, static_cast<Uint8>(std::clamp(thumb_alpha, 0, 255))));
                scroll_thumb_sprite->updateTexture(surface);
                SDL_DestroySurface(surface);
            }
 
            scroll_thumb_sprite->drawSpriteRect(scrollbar_x, consoleSpriteY(scrollbar_thumb_y, scrollbar_thumb_h), scrollbar_w, scrollbar_thumb_h);
        }
 
        if (scroll_offset > 0) {
            windowPtr->printText(std::format("^ {} line(s) newer below", scroll_offset), panel_x + padding, input_y - line_height, scaledColor(info_color), console_font);
        }
 
        const Uint64 now = SDL_GetTicksNS();
        if (now - last_cursor_toggle_ns > 500000000ULL) {
            cursor_visible = !cursor_visible;
            last_cursor_toggle_ns = now;
        }
 
        cursor_pos = std::min(cursor_pos, input.size());
 
        const std::string line = promptText + input;
        windowPtr->printText(line, panel_x + padding, input_y, scaledColor(prompt_color), console_font);
 
        if (cursor_visible && cursor_sprite != nullptr) {
            int prefix_width = 0;
            int prefix_height = 0;
            const std::string prefix = promptText + input.substr(0, cursor_pos);
            if (!windowPtr->getTextDimensions(prefix, prefix_width, prefix_height, console_font)) {
                prefix_width = static_cast<int>((promptText.size() + cursor_pos) * static_cast<std::size_t>(glyph_w));
            }
 
            // Draw a VS Code-like thin insertion caret at the text boundary.
            const int cursor_w = 2;
            const int cursor_x = std::max(panel_x + padding, panel_x + padding + prefix_width - 1);
            const int cursor_y = input_y + 2;
            const int cursor_h = std::max(4, line_height - 4);
 
            SDL_Surface *surface = SDL_CreateSurface(2, 2, SDL_PIXELFORMAT_RGBA32);
            if (surface != nullptr) {
                const SDL_PixelFormatDetails *const fmt = SDL_GetPixelFormatDetails(SDL_PIXELFORMAT_RGBA32);
                const int cursor_alpha = static_cast<int>(std::lround(220.0 * alpha));
                SDL_FillSurfaceRect(surface, nullptr, SDL_MapRGBA(fmt, nullptr, 210, 255, 220, static_cast<Uint8>(std::clamp(cursor_alpha, 0, 255))));
                cursor_sprite->updateTexture(surface);
                SDL_DestroySurface(surface);
            }
 
            cursor_sprite->drawSpriteRect(cursor_x, consoleSpriteY(cursor_y, cursor_h), cursor_w, cursor_h);
        }
    }

◆ handleEvent()

void mxvk::VK_Console::handleEvent ( const SDL_Event & event )

Handle keyboard/text events for the console.

Definition at line 606 of file mxvk_console.cpp.

                                                       {
        if (event.type == SDL_EVENT_KEY_DOWN && (event.key.key == SDLK_F3)) {
            toggle();
            return;
        }
 
        if (!visible) {
            return;
        }
 
        refreshVisibleLineCount();
 
        if (event.type == SDL_EVENT_MOUSE_WHEEL) {
            if (event.wheel.y > 0) {
                scrollUp(static_cast<std::size_t>(event.wheel.y));
            } else if (event.wheel.y < 0) {
                scrollDown(static_cast<std::size_t>(-event.wheel.y));
            }
            return;
        }
 
        if (event.type == SDL_EVENT_MOUSE_BUTTON_DOWN && event.button.button == SDL_BUTTON_LEFT) {
            const int mx = event.button.x;
            const int my = event.button.y;
            if (isPointInScrollbarThumb(mx, my)) {
                scrollbar_dragging = true;
                scrollbar_drag_offset = my - scrollbar_thumb_y;
                return;
            }
 
            if (isPointInScrollbar(mx, my)) {
                const std::size_t page = std::max<std::size_t>(1, effectiveVisibleLineCount() - 1);
                if (my < scrollbar_thumb_y) {
                    scrollUp(page);
                } else if (my >= (scrollbar_thumb_y + scrollbar_thumb_h)) {
                    scrollDown(page);
                }
                return;
            }
        }
 
        if (event.type == SDL_EVENT_MOUSE_BUTTON_UP && event.button.button == SDL_BUTTON_LEFT) {
            scrollbar_dragging = false;
            return;
        }
 
        if (event.type == SDL_EVENT_MOUSE_MOTION && scrollbar_dragging) {
            updateScrollFromThumbY(event.motion.y - scrollbar_drag_offset);
            return;
        }
 
        if (event.type == SDL_EVENT_KEY_DOWN) {
            switch (event.key.key) {
            case SDLK_RETURN:
            case SDLK_KP_ENTER:
                submitInput();
                return;
            case SDLK_BACKSPACE:
                if (cursor_pos > 0 && cursor_pos <= input.size()) {
                    input.erase(cursor_pos - 1, 1);
                    --cursor_pos;
                }
                return;
            case SDLK_DELETE:
                if (cursor_pos < input.size()) {
                    input.erase(cursor_pos, 1);
                }
                return;
            case SDLK_LEFT:
                if (cursor_pos > 0) {
                    --cursor_pos;
                }
                return;
            case SDLK_RIGHT:
                if (cursor_pos < input.size()) {
                    ++cursor_pos;
                }
                return;
            case SDLK_HOME:
                cursor_pos = 0;
                return;
            case SDLK_END:
                follow_tail = true;
                scroll_offset = 0;
                cursor_pos = input.size();
                return;
            case SDLK_UP:
                historyUp();
                return;
            case SDLK_DOWN:
                historyDown();
                return;
            case SDLK_PAGEUP:
                scrollUp(std::max<std::size_t>(1, effectiveVisibleLineCount() - 1));
                return;
            case SDLK_PAGEDOWN:
                scrollDown(std::max<std::size_t>(1, effectiveVisibleLineCount() - 1));
                return;
            case SDLK_ESCAPE:
                hide();
                return;
            default:
                break;
            }
            return;
        }
 
        if (event.type == SDL_EVENT_TEXT_INPUT) {
            if (event.text.text[0] != '\0') {
                input.insert(cursor_pos, event.text.text);
                cursor_pos += SDL_strlen(event.text.text);
            }
        }
    }

◆ hide()

void mxvk::VK_Console::hide ( )

noexcept

Hide console.

Definition at line 80 of file mxvk_console.cpp.

80{ setVisible(false); }

mxvk::VK_Console::setVisible

void setVisible(bool value) noexcept

Show or hide the console.

Definition mxvk_console.cpp:54

◆ inputBuffer()

const std::string & mxvk::VK_Console::inputBuffer ( ) const

nodiscardnoexcept

Returns: Current input buffer.

Definition at line 106 of file mxvk_console.cpp.

106{ return input; }

◆ invalidateLayoutCache()

void mxvk::VK_Console::invalidateLayoutCache ( )

Recompute cached line wrapping after font or layout metrics change.

Definition at line 101 of file mxvk_console.cpp.

                                           {
        invalidateWrappedCache();
        scroll_offset = std::min(scroll_offset, maxScrollOffset());
    }

◆ isVisible()

bool mxvk::VK_Console::isVisible ( ) const

nodiscardnoexcept

Returns: true when the console is visible.

Definition at line 90 of file mxvk_console.cpp.

90{ return visible || fade_alpha > 0.0f || fade_active; }

◆ printLine()

void mxvk::VK_Console::printLine	(	const std::string &	line,
		SDL_Color	color = SDL_Color{255, 255, 255, 255} )

Append one line to console output.

Parameters

line	Text to append. Embedded newlines are split into separate lines.
color	Optional text color for this output line. Defaults to white.

Definition at line 108 of file mxvk_console.cpp.

                                                                           {
        std::size_t start = 0;
        while (start <= line.size()) {
            const std::size_t nl = line.find('\n', start);
            if (nl == std::string::npos) {
                pushOutputLine(line.substr(start), color);
                break;
            }
 
            pushOutputLine(line.substr(start, nl - start), color);
            start = nl + 1;
 
            // Preserve a trailing newline as an empty visual line.
            if (start == line.size()) {
                pushOutputLine(std::string{}, color);
                break;
            }
        }
 
        trimOutputToLimits();
        invalidateWrappedCache();
        if (follow_tail) {
            scroll_offset = 0;
        } else {
            scroll_offset = std::min(scroll_offset, maxScrollOffset());
        }
    }

◆ setCommandCallback()

void mxvk::VK_Console::setCommandCallback ( CommandCallback callback )

Register a command callback.

Return true to indicate the command was handled.

Definition at line 46 of file mxvk_console.cpp.

46{ commandCallback = std::move(callback); }

◆ setFont()

void mxvk::VK_Console::setFont	(	const std::string &	fontPath,
		int	fontSize )

Change only the console font, leaving the window default font unchanged.

Definition at line 40 of file mxvk_console.cpp.

                                                                          {
        console_font.reset(fontPath, fontSize);
        invalidateLayoutCache();
        refreshVisibleLineCount();
    }

◆ setMaxLines()

void mxvk::VK_Console::setMaxLines ( std::size_t maxLines )

Set max number of retained output lines.

Definition at line 92 of file mxvk_console.cpp.

                                                         {
        max_lines = std::max<std::size_t>(1, maxLines);
        trimOutputToLimits();
        invalidateWrappedCache();
        scroll_offset = std::min(scroll_offset, maxScrollOffset());
    }

◆ setMaxVisibleLines()

void mxvk::VK_Console::setMaxVisibleLines ( std::size_t maxVisibleLines )

Set max number of lines rendered on screen.

Definition at line 99 of file mxvk_console.cpp.

99{ max_visible_lines = std::max<std::size_t>(1, maxVisibleLines); }

◆ setPrompt()

void mxvk::VK_Console::setPrompt ( const std::string & prompt )

Set the input prompt text.

Definition at line 48 of file mxvk_console.cpp.

                                                      {
        if (!prompt.empty()) {
            promptText = prompt;
        }
    }

◆ setSpriteYOriginTopLeft()

void mxvk::VK_Console::setSpriteYOriginTopLeft ( bool enabled )

inlinenoexcept

Select whether console sprite elements use top-left Y coordinates.

Definition at line 91 of file mxvk_console.hpp.

91{ sprite_y_origin_top_left = enabled; }

◆ setVisible()

void mxvk::VK_Console::setVisible ( bool value )

noexcept

Show or hide the console.

Definition at line 54 of file mxvk_console.cpp.

                                                         {
        if (value) {
            visible = true;
            fade_start_alpha = fade_alpha;
            fade_target_alpha = 1.0f;
            fade_start_ns = SDL_GetTicksNS();
            fade_active = true;
            if (windowPtr != nullptr) {
                SDL_StartTextInput(windowPtr->getSDLWindow());
            }
            follow_tail = true;
            scroll_offset = 0;
        } else {
            visible = false;
            fade_start_alpha = fade_alpha;
            fade_target_alpha = 0.0f;
            fade_start_ns = SDL_GetTicksNS();
            fade_active = true;
            if (windowPtr != nullptr) {
                SDL_StopTextInput(windowPtr->getSDLWindow());
            }
        }
    }

◆ show()

void mxvk::VK_Console::show ( )

noexcept

Show console.

Definition at line 78 of file mxvk_console.cpp.

78{ setVisible(true); }

◆ toggle()

void mxvk::VK_Console::toggle ( )

noexcept

Toggle console visibility.

Definition at line 82 of file mxvk_console.cpp.

                                     {
        if (visible) {
            hide();
        } else {
            show();
        }
    }

The documentation for this class was generated from the following files:

mxvk/include/mxvk/mxvk_console.hpp
mxvk/src/mxvk_console.cpp

MXVK Vulkan Framework 0.35.0 C++20 Vulkan rendering framework for practical 2D and 3D application development with SDL3.

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ CommandCallback

Constructor & Destructor Documentation

◆ VK_Console()

Member Function Documentation

◆ attach()

◆ clear()

◆ draw()

◆ handleEvent()

◆ hide()

◆ inputBuffer()

◆ invalidateLayoutCache()

◆ isVisible()

◆ printLine()

◆ setCommandCallback()

◆ setFont()

◆ setMaxLines()

◆ setMaxVisibleLines()

◆ setPrompt()

◆ setSpriteYOriginTopLeft()

◆ setVisible()

◆ show()

◆ toggle()