fgof-screen Public

Watch 0 Fork 0 Star 0
markdown · 4515 bytes Raw Blame History

fgof-screen

Virtual screen buffers and diff rendering helpers for modern Fortran.

fgof-screen is intended to be a small, standalone library for virtual screen state, styled cells, and render-diff workflows that terminal apps keep rebuilding from scratch.

It is part of the FortranGoingOnForty lib-modules catalog, but it is intended to stand on its own as a normal fpm package.

Current v1 target:

  • stable screen style, cell, size, and buffer types
  • predictable virtual-grid allocation and fill helpers
  • diffable screen-state model with damage tracking for future ANSI-first rendering
  • room for a higher-level renderer without making ncurses the package identity

Future scope:

  • optional adapter layers for alternate backends later
  • examples and higher-level paint helpers

Status

Sprint 04 is in place.

Tracked today:

  • package layout, CI, and standalone repo setup
  • foundational screen types for styles, cells, sizes, and buffers
  • virtual-grid allocation, resize, fill, and clear helpers
  • explicit cell writes and cursor clamping helpers
  • frame diff computation with changed-cell counts and damage bounds
  • explicit size, cursor, and cursor-visibility change reporting
  • ANSI full-frame rendering
  • ANSI diff rendering driven by the damage model
  • explicit cursor-state ANSI output
  • tracked example programs for full-frame and diff rendering
  • render-edge coverage for empty screens and cursor-only diffs
  • full-frame ANSI output with explicit row addressing
  • render-time sanitization for non-printable control glyphs
  • CI on macOS and Ubuntu, including direct example execution
  • row-first, column-second grid semantics pinned down in tests
  • focused scaffold coverage in fpm test

Public API Shape

Primary modules:

  • fgof_screen
  • fgof_screen_types

Public types:

  • screen_style
  • screen_cell
  • screen_size
  • screen_buffer
  • screen_damage
  • screen_diff

Current public procedures:

  • clear_screen_style
  • clear_screen_cell
  • clear_screen_damage
  • clear_screen_diff
  • clear_screen_size
  • clear_screen_buffer
  • allocate_screen
  • resize_screen
  • fill_screen
  • clear_screen
  • diff_screen
  • put_cell
  • put_glyph
  • render_cursor_ansi
  • render_screen_ansi
  • render_screen_diff_ansi
  • set_cursor

Current semantics:

  • screen_buffer%cells(row, col) is the current virtual-grid layout
  • allocate_screen(width, height) allocates a blank grid for positive sizes
  • newly allocated cells start as blank-space cells with default style
  • resize_screen() preserves overlapping content, blanks newly grown cells, and clamps the cursor into bounds
  • fill_screen() applies a glyph and optional style across the whole allocated buffer
  • clear_screen() is the whole-buffer blank fill helper
  • put_cell() and put_glyph() update a specific (row, col) location without transposing the grid model
  • out-of-bounds cell writes are ignored rather than clamped to another location
  • set_cursor() keeps cursor position within the allocated grid, or resets it to (1, 1) when the buffer is empty
  • diff_screen(previous, current) compares two virtual frames and reports cell damage separately from size or cursor changes
  • screen_diff%damage uses one bounding rectangle plus a changed_cells count for the changed frame area
  • newly added or removed visible cells from resizes count as changed damage even when their glyphs are blank
  • render_screen_ansi() emits a whole-frame ANSI repaint with clear/home semantics, explicit row addressing, and final cursor restoration
  • render_screen_diff_ansi() emits a damage-scoped ANSI repaint and uses blank cells to erase removed content after shrinks
  • render_cursor_ansi() emits the final cursor move plus visibility state for a screen buffer
  • ANSI row rendering tracks style transitions explicitly and resets back to default style when needed
  • ANSI renderers replace ASCII control glyphs with ? so screen cells cannot inject raw control bytes into the output stream

Build And Test

fpm test

Tracked examples:

Supported Platforms

  • macOS
  • Linux

Boundaries

  • intended to stay independently versioned and releasable
  • focused on virtual screen state first, not full terminal control yet
  • should stay useful on its own even if future prompt or TUI packages build on top

License

MIT

View source
1 # fgof-screen
2
3 Virtual screen buffers and diff rendering helpers for modern Fortran.
4
5 `fgof-screen` is intended to be a small, standalone library for virtual screen
6 state, styled cells, and render-diff workflows that terminal apps keep
7 rebuilding from scratch.
8
9 It is part of the [FortranGoingOnForty lib-modules](https://github.com/FortranGoingOnForty/lib-modules)
10 catalog, but it is intended to stand on its own as a normal `fpm` package.
11
12 Current v1 target:
13
14 - stable screen style, cell, size, and buffer types
15 - predictable virtual-grid allocation and fill helpers
16 - diffable screen-state model with damage tracking for future ANSI-first rendering
17 - room for a higher-level renderer without making ncurses the package identity
18
19 Future scope:
20
21 - optional adapter layers for alternate backends later
22 - examples and higher-level paint helpers
23
24 ## Status
25
26 Sprint 04 is in place.
27
28 Tracked today:
29
30 - package layout, CI, and standalone repo setup
31 - foundational screen types for styles, cells, sizes, and buffers
32 - virtual-grid allocation, resize, fill, and clear helpers
33 - explicit cell writes and cursor clamping helpers
34 - frame diff computation with changed-cell counts and damage bounds
35 - explicit size, cursor, and cursor-visibility change reporting
36 - ANSI full-frame rendering
37 - ANSI diff rendering driven by the damage model
38 - explicit cursor-state ANSI output
39 - tracked example programs for full-frame and diff rendering
40 - render-edge coverage for empty screens and cursor-only diffs
41 - full-frame ANSI output with explicit row addressing
42 - render-time sanitization for non-printable control glyphs
43 - CI on macOS and Ubuntu, including direct example execution
44 - row-first, column-second grid semantics pinned down in tests
45 - focused scaffold coverage in `fpm test`
46
47 ## Public API Shape
48
49 Primary modules:
50
51 - `fgof_screen`
52 - `fgof_screen_types`
53
54 Public types:
55
56 - `screen_style`
57 - `screen_cell`
58 - `screen_size`
59 - `screen_buffer`
60 - `screen_damage`
61 - `screen_diff`
62
63 Current public procedures:
64
65 - `clear_screen_style`
66 - `clear_screen_cell`
67 - `clear_screen_damage`
68 - `clear_screen_diff`
69 - `clear_screen_size`
70 - `clear_screen_buffer`
71 - `allocate_screen`
72 - `resize_screen`
73 - `fill_screen`
74 - `clear_screen`
75 - `diff_screen`
76 - `put_cell`
77 - `put_glyph`
78 - `render_cursor_ansi`
79 - `render_screen_ansi`
80 - `render_screen_diff_ansi`
81 - `set_cursor`
82
83 Current semantics:
84
85 - `screen_buffer%cells(row, col)` is the current virtual-grid layout
86 - `allocate_screen(width, height)` allocates a blank grid for positive sizes
87 - newly allocated cells start as blank-space cells with default style
88 - `resize_screen()` preserves overlapping content, blanks newly grown cells, and clamps the cursor into bounds
89 - `fill_screen()` applies a glyph and optional style across the whole allocated buffer
90 - `clear_screen()` is the whole-buffer blank fill helper
91 - `put_cell()` and `put_glyph()` update a specific `(row, col)` location without transposing the grid model
92 - out-of-bounds cell writes are ignored rather than clamped to another location
93 - `set_cursor()` keeps cursor position within the allocated grid, or resets it to `(1, 1)` when the buffer is empty
94 - `diff_screen(previous, current)` compares two virtual frames and reports cell damage separately from size or cursor changes
95 - `screen_diff%damage` uses one bounding rectangle plus a `changed_cells` count for the changed frame area
96 - newly added or removed visible cells from resizes count as changed damage even when their glyphs are blank
97 - `render_screen_ansi()` emits a whole-frame ANSI repaint with clear/home semantics, explicit row addressing, and final cursor restoration
98 - `render_screen_diff_ansi()` emits a damage-scoped ANSI repaint and uses blank cells to erase removed content after shrinks
99 - `render_cursor_ansi()` emits the final cursor move plus visibility state for a screen buffer
100 - ANSI row rendering tracks style transitions explicitly and resets back to default style when needed
101 - ANSI renderers replace ASCII control glyphs with `?` so screen cells cannot inject raw control bytes into the output stream
102
103 ## Build And Test
104
105 ```bash
106 fpm test
107 ```
108
109 Tracked examples:
110
111 - [full_render_demo.f90](example/full_render_demo.f90)
112 - [diff_render_demo.f90](example/diff_render_demo.f90)
113
114 ## Supported Platforms
115
116 - macOS
117 - Linux
118
119 ## Boundaries
120
121 - intended to stay independently versioned and releasable
122 - focused on virtual screen state first, not full terminal control yet
123 - should stay useful on its own even if future prompt or TUI packages build on top
124
125 ## License
126
127 MIT