Merge pull request #20 from harukasan/text-zoom

Add a 2x scaled text console mode (320x240)

Author: harukasan

doc/dvi.md

@@ -19,8 +19,9 @@ Class: `DVI` (provided by picoruby-dvi mrbgem)
 - [DVI.wait_vsync](#dviwait_vsync)
 
 `DVI` provides display output control. Two display modes are available:
-`DVI::TEXT_MODE` (106x37 text grid at 640x480) and `DVI::GRAPHICS_MODE`
-(640x480 RGB332 framebuffer).
+`DVI::TEXT_MODE` (text grid, 640x480 native or 320x240 scaled 2x) and
+`DVI::GRAPHICS_MODE` (RGB332 framebuffer, 640x480 or 320x240). Both
+modes select their source resolution at runtime with `set_resolution`.
 
 ```ruby
 DVI.set_mode(DVI::TEXT_MODE)
@@ -50,6 +51,9 @@ Block until the next VBlank. See
 
 Class: `DVI::Text` (provided by picoruby-dvi mrbgem)
 
+- [DVI::Text.cols](#dvitextcols---integer)
+- [DVI::Text.rows](#dvitextrows---integer)
+- [DVI::Text.set_resolution](#dvitextset_resolutionwidth-height)
 - [DVI::Text.put_char](#dvitextput_charcol-row-ch-attr)
 - [DVI::Text.put_string](#dvitextput_stringcol-row-str-attr)
 - [DVI::Text.clear](#dvitextclearattr)
@@ -62,13 +66,33 @@ Class: `DVI::Text` (provided by picoruby-dvi mrbgem)
 - [DVI::Text.commit](#dvitextcommit)
 
 `DVI::Text` provides text mode rendering with double-buffered VRAM.
-Characters are placed on a 106-column, 37-row grid. The `attr` byte
-encodes foreground (bits 7-4) and background (bits 3-0) palette indices.
+Characters are placed on a runtime-sized grid: 106 columns by 37 rows at
+the native 640x480 resolution, or 53 columns by 18 rows at 320x240 (each
+pixel doubled to the 640x480 DVI output). The `attr` byte encodes
+foreground (bits 7-4) and background (bits 3-0) palette indices.
 
 All write operations modify the back buffer. Call `commit` to swap the
 back buffer to the front buffer at VBlank, preventing tearing.
 
-Constants: `DVI::Text::COLS` (106), `DVI::Text::ROWS` (37).
+Constants: `DVI::Text::COLS` (106) and `DVI::Text::ROWS` (37) are the
+maximum grid, equal to the 640x480 grid. Use `cols` and `rows` for the
+current grid.
+
+#### DVI::Text.cols -> Integer
+
+Return the current grid width (106 at 640x480, 53 at 320x240).
+
+#### DVI::Text.rows -> Integer
+
+Return the current grid height (37 at 640x480, 18 at 320x240).
+
+#### DVI::Text.set_resolution(width, height)
+
+Switch the text mode source resolution. Accepts 640x480 (native) or
+320x240 (scaled 2x to the DVI output, for demo readability). Blocks
+until the change is applied at VSync, so `cols` and `rows` read the new
+grid immediately after. Screen contents are not converted; callers
+should clear and redraw (the console does this via `Console#reset`).
 
 #### DVI::Text.put_char(col, row, ch, attr)
 

doc/dvi/batch-rendering.md

@@ -13,6 +13,11 @@ providing ~24,500 cycles of headroom.
 remain single (45 IRQs: 10 VFP + 2 VSYNC + 33 VBP).  Total: 165 IRQs
 per frame.
 
+In 2x scaled text mode a batch covers 2 source lines instead of 4: each
+rendered line buffer is referenced by two consecutive DVI scanline
+descriptors, consuming 2 line buffers per batch.  See
+[text-mode-rendering.md](text-mode-rendering.md).
+
 ## Design
 
 ### Line buffers: 2N = 8

doc/dvi/text-mode-rendering.md

@@ -1,8 +1,11 @@
 # Text Mode Rendering
 
-Text mode renders a 106x37 character grid at native 640x480 resolution.
-Each scanline is rendered by the DMA IRQ handler on Core 1, converting
-text VRAM cells into 640 RGB332 pixels via inline ARM Thumb-2 assembly.
+Text mode renders a character grid at two runtime-selectable source
+resolutions: 106x37 at native 640x480, or 53x18 at 320x240 scaled 2x to
+the DVI output (see [Scaled text mode](#scaled-text-mode-2x)). Each
+scanline is rendered by the DMA IRQ handler on Core 1, converting text
+VRAM cells into RGB332 pixels via inline ARM Thumb-2 assembly (native)
+or plain C (scaled).
 
 ## Text VRAM
 
@@ -21,6 +24,12 @@ for bold (mapping into the 256-511 bold region of the narrow cache).
 For wide characters, `ch` holds the linear JIS index directly (used by
 `write_line` for glyph re-rendering from scrollback).
 
+Physical rows always use the fixed `TEXT_VRAM_STRIDE` (106 cells), so
+cell addressing is independent of the active column count. The active
+grid (`text_cols` x `text_rows`) bounds writes, string wrapping, and the
+scroll ring modulus; in scaled mode only the first 53 cells of each of
+the first 18 physical rows are active.
+
 16-color palette maps 4-bit indices to RGB332 values (VGA-compatible
 defaults).
 
@@ -110,3 +119,42 @@ Key render-loop optimizations:
 
 The render function and IRQ handler are placed in SCRATCH_X to avoid
 flash instruction fetch during rendering.
+
+## Scaled Text Mode (2x)
+
+`dvi_set_text_scale(2)` (Ruby: `DVI::Text.set_resolution(320, 240)`)
+switches text mode to a 320x240 source resolution scaled 2x to the
+640x480 DVI output. The grid becomes 53x18: 53 cells cover 318 pixels
+with 2 black padding pixels on the right, and 18 rows cover 234 source
+lines with the remaining 6 source lines (12 DVI lines) black at the
+bottom.
+
+The scale change is requested from Core 0 and applied by the DMA IRQ in
+the same VSync window as the HSTX reconfiguration, mirroring the
+graphics scale mechanism. On application, both ring scroll offsets are
+clamped below the new row count (the render side by the IRQ, the write
+side by the blocked Core 0 caller) so the single-subtraction ring wrap
+stays in bounds when the grid shrinks from 37 to 18 rows.
+
+Scaling reuses the 320x240 graphics mode mechanics:
+
+- **Horizontal**: pixel groups transfer 320 bytes with `DMA_SIZE_8` and
+  the HSTX expander is configured with `ENC_N_SHIFTS = 2`, so each byte
+  is TMDS-encoded twice (byte-lane replication).
+- **Vertical**: a batch of 4 DVI lines covers 2 source lines; each
+  rendered line buffer is referenced by two consecutive DVI scanline
+  descriptors.
+
+`render_text_scanline_12wide_scaled()` renders one 320 pixel source
+line. It is plain C in main SRAM (`.time_critical`), not SCRATCH_X asm:
+at half the width and half the line rate it has roughly 4x the cycle
+budget of the native renderer. It handles narrow and wide cells in a
+single loop (no narrow-only pair path, so the odd column count needs no
+special casing) and reads the same narrow row cache, per-position glyph
+bitmap, and font-byte-mask LUT as the native renderer.
+
+`prepare_batch_dma_text_scaled()` builds the batch descriptors. It is
+also RAM-resident because it runs during flash-write blanking, where
+every source switches to `blank_line_buf` with the scale 2 transfer
+count (the native blanking branch would feed the wrong count for the
+scale 2 HSTX configuration).

mrbgems/picoruby-dvi/include/dvi.h

@@ -38,7 +38,7 @@ typedef struct {
 
 typedef enum {
   DVI_MODE_GRAPHICS, // RGB332 framebuffer (resolution set by DVI_GRAPHICS_SCALE)
-  DVI_MODE_TEXT,     // text VRAM, native 640x480
+  DVI_MODE_TEXT,     // text VRAM, 640x480 native or 320x240 (2x scaled)
 } dvi_mode_t;
 
 // Font data structure (defined in dvi_font.h)
@@ -76,6 +76,10 @@ void dvi_graphics_commit(void);
 dvi_text_cell_t *dvi_get_text_vram(void);
 int dvi_text_get_cols(void);
 int dvi_text_get_rows(void);
+// Runtime text resolution. Scale 1 = 640x480 native (106x37 grid with the
+// 12px font), scale 2 = 320x240 scaled 2x to the DVI output (53x18 grid).
+// Blocks until the VSync IRQ applies the change.
+void dvi_set_text_scale(int scale);
 void dvi_text_set_font(const dvi_font_t *font);
 void dvi_text_set_wide_font(const dvi_font_t *font);
 void dvi_text_set_bold_font(const dvi_font_t *font);