feat(menu): primera versió del menú de servei

source/core/rendering/canvas.cpp

@@ -1,9 +1,24 @@
 #include "core/rendering/canvas.hpp"
 
+#include <algorithm>
+#include <vector>
+
 #include "core/rendering/screen.hpp"
 
 namespace Rendering {
 
+    namespace {
+
+        // Pila de clips en un namespace anònim perquè no siga accessible des
+        // de fora. L'app és single-threaded; si algun dia hi ha threads de
+        // render, s'ha de fer thread_local o passar-la explícitament.
+        auto clipStack() -> std::vector<Clip>& {
+            static std::vector<Clip> stack_;
+            return stack_;
+        }
+
+    }  // namespace
+
     auto activeCanvas() -> Canvas {
         auto& screen = Screen::get();
         return {
@@ -13,4 +28,32 @@ namespace Rendering {
         };
     }
 
+    auto activeClip() -> Clip {
+        const auto& stack = clipStack();
+        if (!stack.empty()) { return stack.back(); }
+        const auto CANVAS = activeCanvas();
+        return {.x = 0, .y = 0, .w = CANVAS.width, .h = CANVAS.height};
+    }
+
+    void pushClip(Clip rect) {
+        // Retall contra el canvas per garantir que els blitters no s'han
+        // de preocupar de coordenades negatives o més grans que el canvas.
+        const auto CANVAS = activeCanvas();
+        const int X0 = std::max(rect.x, 0);
+        const int Y0 = std::max(rect.y, 0);
+        const int X1 = std::min(rect.x + rect.w, CANVAS.width);
+        const int Y1 = std::min(rect.y + rect.h, CANVAS.height);
+        clipStack().push_back({
+            .x = X0,
+            .y = Y0,
+            .w = std::max(0, X1 - X0),
+            .h = std::max(0, Y1 - Y0),
+        });
+    }
+
+    void popClip() {
+        auto& stack = clipStack();
+        if (!stack.empty()) { stack.pop_back(); }
+    }
+
 }  // namespace Rendering

source/core/rendering/canvas.hpp

@@ -20,9 +20,33 @@ namespace Rendering {
         int height{0};
     };
 
+    // Rectangle de clip (en píxels de canvas). Els blitters han de comprovar
+    // `clip` abans d'escriure cada píxel; fora del rectangle no es dibuixa.
+    // `push/pop` permet niar clips (tot i que de moment només en tenim un
+    // nivell d'ús, el menú). Si la pila és buida, `activeClip` retorna el
+    // canvas complet — comportament "sense clip".
+    struct Clip {
+        int x{0};
+        int y{0};
+        int w{0};
+        int h{0};
+    };
+
     // Retorna el canvas actiu del joc. En aquesta fase del projecte n'hi ha
     // sempre un i només un (el de Screen); en el futur, si cal renderitzar
     // off-screen (miniatures, efectes), es podrà pushejar/popar per ací.
     [[nodiscard]] auto activeCanvas() -> Canvas;
 
+    // Clip actiu. Si ningú ha fet push, és tot el canvas.
+    [[nodiscard]] auto activeClip() -> Clip;
+
+    // Restringeix el dibuix al rectangle donat fins al proper popClip().
+    // El rectangle es retalla contra el canvas (cap clip pot excedir els
+    // seus límits, així els blitters poden assumir-los sans).
+    void pushClip(Clip rect);
+
+    // Desapila el clip actiu i restaura l'anterior. Si no hi havia cap
+    // push previ, l'operació és idempotent i queda a "canvas complet".
+    void popClip();
+
 }  // namespace Rendering

source/core/rendering/screen.cpp

@@ -220,17 +220,61 @@ void Screen::clear(std::uint8_t r, std::uint8_t g, std::uint8_t b) {
 }
 
 void Screen::fillRect(int x, int y, int w, int h, std::uint32_t argb) {
-    const int X0 = std::max(x, 0);
-    const int Y0 = std::max(y, 0);
-    const int X1 = std::min(x + w, canvas_width_);
-    const int Y1 = std::min(y + h, canvas_height_);
+    const auto CLIP = Rendering::activeClip();
+    const int X0 = std::max(x, CLIP.x);
+    const int Y0 = std::max(y, CLIP.y);
+    const int X1 = std::min(x + w, CLIP.x + CLIP.w);
+    const int Y1 = std::min(y + h, CLIP.y + CLIP.h);
     for (int iy = Y0; iy < Y1; ++iy) {
         std::uint32_t* row = canvas_.data() + (static_cast<std::ptrdiff_t>(iy) * canvas_width_);
         std::fill(row + X0, row + X1, argb);
     }
 }
 
+void Screen::blendRect(int x, int y, int w, int h, std::uint32_t argb, std::uint8_t alpha) {
+    if (alpha == 0) { return; }
+    if (alpha == 0xFF) {
+        fillRect(x, y, w, h, argb);
+        return;
+    }
+    // Mescla linealment src (argb, alpha) sobre dst (el canvas). El canvas
+    // és ARGB amb R/G/B als bytes baixos i A fix a 0xFF; fem la mescla per
+    // canal i deixem A intacte perquè el backend espera opacitat total.
+    const std::uint8_t SA = alpha;
+    const std::uint8_t INV = 255 - alpha;
+    const std::uint8_t SR = (argb >> 16) & 0xFF;
+    const std::uint8_t SG = (argb >> 8) & 0xFF;
+    const std::uint8_t SB = argb & 0xFF;
+    const auto CLIP = Rendering::activeClip();
+    const int X0 = std::max(x, CLIP.x);
+    const int Y0 = std::max(y, CLIP.y);
+    const int X1 = std::min(x + w, CLIP.x + CLIP.w);
+    const int Y1 = std::min(y + h, CLIP.y + CLIP.h);
+    for (int iy = Y0; iy < Y1; ++iy) {
+        std::uint32_t* row = canvas_.data() + (static_cast<std::ptrdiff_t>(iy) * canvas_width_);
+        for (int ix = X0; ix < X1; ++ix) {
+            const std::uint32_t DST = row[ix];
+            const std::uint8_t DR = (DST >> 16) & 0xFF;
+            const std::uint8_t DG = (DST >> 8) & 0xFF;
+            const std::uint8_t DB = DST & 0xFF;
+            const std::uint8_t R = ((SR * SA) + (DR * INV)) / 255;
+            const std::uint8_t G = ((SG * SA) + (DG * INV)) / 255;
+            const std::uint8_t B = ((SB * SA) + (DB * INV)) / 255;
+            row[ix] = 0xFF000000U | (static_cast<std::uint32_t>(R) << 16) | (static_cast<std::uint32_t>(G) << 8) | static_cast<std::uint32_t>(B);
+        }
+    }
+}
+
+void Screen::setOverlayRenderer(std::function<void()> callback) {
+    overlay_renderer_ = std::move(callback);
+}
+
 void Screen::present() {
+    // Overlays (menú de servei, etc.) s'han de pintar al canvas ABANS que
+    // shader_backend llegisca els píxels per pujar-los a GPU; si no, queden
+    // per sota del postprocés o no apareixen al frame presentat.
+    if (overlay_renderer_) { overlay_renderer_(); }
+
     fps_.increment();
     fps_.calculate(SDL_GetTicks());
 

source/core/rendering/screen.hpp

@@ -3,6 +3,7 @@
 #include <SDL3/SDL.h>
 
 #include <cstdint>
+#include <functional>
 #include <memory>
 #include <string>
 #include <vector>
@@ -68,6 +69,16 @@ class Screen {
     // Pinta un rectangle opac al canvas ARGB del joc. Pensat per a HUDs
     // simples (caixes de notificacions, barres d'estat); no gasta paleta.
     void fillRect(int x, int y, int w, int h, std::uint32_t argb);
+    // Alpha-blend sobre el canvas: `alpha=0` no fa res, `alpha=255` equival
+    // a fillRect. El color entra com a ARGB little-endian; `alpha` és el
+    // factor de mescla amb el que ja hi ha al canvas. Pensat per a overlays
+    // (menú, pauses) que volen veure's a través el joc atenuat.
+    void blendRect(int x, int y, int w, int h, std::uint32_t argb, std::uint8_t alpha);
+    // Hook invocat al principi de `present()`, abans de pujar els píxels al
+    // backend. Serveix per a pintar overlays que han de quedar per damunt
+    // de qualsevol escena (p.ex. el menú de servei). El Director el registra
+    // un sol cop; Screen no coneix el tipus concret del callback.
+    void setOverlayRenderer(std::function<void()> callback);
     void present();
 
     [[nodiscard]] auto getRenderer() const -> SDL_Renderer* { return renderer_; }
@@ -123,4 +134,10 @@ class Screen {
 
     FPS fps_{};
     std::string gpu_driver_;
+
+    // Callback cridat al principi de present() per pintar overlays per
+    // damunt de l'escena. Viu en Screen perquè la seqüència correcta
+    // (dibuix al canvas → overlay → upload al backend → present) queda
+    // centralitzada en un sol lloc, siga quina siga l'escena activa.
+    std::function<void()> overlay_renderer_;
 };

source/core/rendering/surface.cpp

@@ -90,9 +90,13 @@ void Surface::render(int x, int y, const SDL_FRect* src_rect, SDL_FlipMode flip)
 
 void Surface::renderWithColorReplace(int x, int y, Uint8 source_color, Uint8 target_color, const SDL_FRect* src_rect, SDL_FlipMode flip) const {
     const auto CANVAS = Rendering::activeCanvas();
+    const auto CLIP = Rendering::activeClip();
     Uint32* dst = CANVAS.pixels;
     const int DST_W = CANVAS.width;
-    const int DST_H = CANVAS.height;
+    const int CLIP_X0 = CLIP.x;
+    const int CLIP_Y0 = CLIP.y;
+    const int CLIP_X1 = CLIP.x + CLIP.w;
+    const int CLIP_Y1 = CLIP.y + CLIP.h;
 
     const int SX = (src_rect != nullptr) ? static_cast<int>(src_rect->x) : 0;
     const int SY = (src_rect != nullptr) ? static_cast<int>(src_rect->y) : 0;
@@ -109,7 +113,7 @@ void Surface::renderWithColorReplace(int x, int y, Uint8 source_color, Uint8 tar
             const int SRC_Y = (flip == SDL_FLIP_VERTICAL) ? (SY + sh - 1 - iy) : (SY + iy);
             const int DST_X = x + ix;
             const int DST_Y = y + iy;
-            if (DST_X < 0 || DST_X >= DST_W || DST_Y < 0 || DST_Y >= DST_H) { continue; }
+            if (DST_X < CLIP_X0 || DST_X >= CLIP_X1 || DST_Y < CLIP_Y0 || DST_Y >= CLIP_Y1) { continue; }
 
             const Uint8 COLOR = src[SRC_X + (SRC_Y * surface_data_->width)];
             if (COLOR == transparent_color_) { continue; }

source/core/rendering/text.hpp

@@ -47,6 +47,14 @@ class Text {
     Text(const std::shared_ptr<Surface>& surface, const std::shared_ptr<File>& text_file);
     ~Text() = default;
 
+    // Kerning per defecte de la font (separació entre glifs en píxels, sumat
+    // a l'amplada natural). Els callers poden passar un kerning explícit a
+    // write/length, o llegir aquest valor i reenviar-lo; així cada font pot
+    // tenir un kerning pròpi (p. ex. negatiu per a displays amb sidebearings
+    // amples) sense obligar els callers a saber-ho.
+    void setDefaultKerning(int kerning) { default_kerning_ = kerning; }
+    [[nodiscard]] auto getDefaultKerning() const -> int { return default_kerning_; }
+
     Text(const Text&) = delete;
     Text(Text&&) = delete;
     auto operator=(const Text&) -> Text& = delete;
@@ -64,6 +72,7 @@ class Text {
     [[nodiscard]] auto length(const std::string& text, int kerning = 1) const -> int;
     [[nodiscard]] auto lengthMonoDigits(const std::string& text, int digit_cell_w, int kerning = 1) const -> int;
     [[nodiscard]] auto getCharacterSize() const -> int { return box_width_; }
+    [[nodiscard]] auto getLineHeight() const -> int { return box_height_; }
 
     static auto loadTextFile(const std::string& file_path) -> std::shared_ptr<File>;
     static auto nextCodepoint(const std::string& s, std::size_t& pos) -> std::uint32_t;
@@ -76,5 +85,6 @@ class Text {
     std::unique_ptr<Sprite> sprite_;
     int box_width_{0};
     int box_height_{0};
+    int default_kerning_{1};
     std::unordered_map<std::uint32_t, Offset> offset_;
 };