From f7a7b48c2ca23f0f3cfaf0824e8d76e74e5d354e Mon Sep 17 00:00:00 2001
From: reugenio <yo@reugenio.com>
Date: Wed, 10 Dec 2025 01:37:00 +0100
Subject: [PATCH] docs: Documentar soporte UTF-8 en renderizado de texto
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- REFERENCE.md: Nueva sección "UTF-8 Text Rendering" explicando:
  - Cómo funciona la decodificación UTF-8 → Latin-1
  - Caracteres soportados (ASCII + Latin-1 Supplement)
  - Por qué UTF-8 es el estándar correcto para BD/archivos
  - Ejemplo de uso con texto español

- software.zig: Doc comments explicando el sistema UTF-8

El renderer ahora maneja texto UTF-8 automáticamente,
permitiendo mostrar correctamente: ñ, á, é, í, ó, ú, ¿, ¡, €, etc.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 REFERENCE.md            | 30 ++++++++++++++++++++++++++++++
 src/render/software.zig | 19 +++++++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/REFERENCE.md b/REFERENCE.md
index 451f6c2..036dfcc 100644
--- a/REFERENCE.md
+++ b/REFERENCE.md
@@ -660,6 +660,36 @@ ttf.textWidth("Hello");
 > (bezier curve rendering) is planned for future releases. For production use,
 > prefer the bitmap fonts which have complete glyph rendering.
 
+### UTF-8 Text Rendering
+
+The software renderer automatically decodes UTF-8 text and maps codepoints to the font's character set.
+
+**How it works:**
+1. Text strings (from SQLite, files, user input) are typically UTF-8 encoded
+2. The renderer decodes UTF-8 sequences (1-4 bytes per character)
+3. Codepoints are mapped to Latin-1 (0x00-0xFF) for bitmap font rendering
+4. Characters outside Latin-1 are displayed as '?' (placeholder)
+
+**Supported characters with Latin-1 fonts:**
+- ASCII (0x00-0x7F): A-Z, a-z, 0-9, punctuation
+- Latin-1 Supplement (0x80-0xFF): ñ, Ñ, á, é, í, ó, ú, ü, ¿, ¡, ç, ß, €, £, ¥, etc.
+
+**Example - Spanish text:**
+```zig
+// UTF-8 string from database or source code
+const text = "¿Cómo está? Número: 100€";
+
+// Renderer automatically handles UTF-8 decoding
+ctx.pushCommand(Command.text(x, y, text, color));
+// Displays correctly: ¿Cómo está? Número: 100€
+```
+
+**Why UTF-8 in databases/files?**
+- SQLite uses UTF-8 natively
+- Universal standard (Linux, Web, JSON, APIs)
+- ASCII-compatible (English text = same size)
+- Overhead minimal: "Razón Social" = 2 extra bytes vs pure ASCII
+
 ---
 
 ## Animation & Effects
diff --git a/src/render/software.zig b/src/render/software.zig
index 6215fc6..1b2ac9a 100644
--- a/src/render/software.zig
+++ b/src/render/software.zig
@@ -2,6 +2,25 @@
 //!
 //! This is the core of our rendering system.
 //! It takes DrawCommands and turns them into pixels.
+//!
+//! ## UTF-8 Text Rendering
+//!
+//! The `drawText` function automatically decodes UTF-8 encoded strings and maps
+//! the resulting Unicode codepoints to the font's character set (typically Latin-1).
+//!
+//! This allows seamless handling of text from various sources:
+//! - SQLite databases (UTF-8 by default)
+//! - Source code string literals (UTF-8 in Zig)
+//! - User input (typically UTF-8 on modern systems)
+//! - JSON/API responses (UTF-8 standard)
+//!
+//! Characters outside the font's range (Latin-1: 0x00-0xFF) are displayed as '?'.
+//!
+//! ## Example
+//! ```zig
+//! // Spanish text with accents - works automatically
+//! ctx.pushCommand(Command.text(x, y, "¿Hola, España!", color));
+//! ```
 
 const std = @import("std");