summaryrefslogtreecommitdiff
path: root/chapter32/src/main/smp/sys/draw/README.md
blob: c1b91ac19e59b56307c4e6a2b607072c396bae00 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
# Drawing in Simple

[Chapter 31](../../../../../../chapter31/README.md#graphics-and-sound) introduces the library.
The implementation is in [Canvas.smp](Canvas.smp), [Button.smp](Button.smp),
and the [draw module](../draw.smp).

`sys.draw` draws into an ordinary `u32[]`. It has no native dependencies and
does not open a window. `sys.gfx` presents the resulting pixels using the
optional [MiniFB backend](../gfx.md).

```simple
val canvas = new sys.draw.Canvas(600,780);
u32 orange = 0xe47b57;
canvas.clear(sys.draw.WHITE);
canvas.fillRect(20,20,180,80,orange);
canvas.rect(20,20,180,80,3,sys.draw.BLACK);
canvas.circle(300,200,48,8,sys.draw.BLUE);
canvas.fillCircle(420,200,20,sys.draw.GREEN);
canvas.line(40,320,250,440,12,orange);
canvas.text(40,500,"YOUR TURN",4,sys.draw.BLACK);
// After sys.gfx.open succeeds:
sys.gfx.presentSize(canvas.pixels,canvas.width,canvas.height);
```

## Small raster API

Coordinates start at the upper left; x increases rightward and y downward.
Drawing methods return the canvas for chaining. Everything is opaque RGB;
there is no blending, antialiasing, transform stack, or native drawing state.
Coordinates accept `i64` so ordinary widened arithmetic can be passed directly.
Circle radii and circle stroke widths are `int`. Use screen-sized coordinates,
extents, and stroke widths.

| Operation | Behavior |
| --- | --- |
| `rgb(r,g,b)` | Clamp components to 0–255 and pack RGB. `BLACK`, `WHITE`, `RED`, `GREEN`, and `BLUE` are available too. |
| `new Canvas(width,height)` | Allocate a zero-filled pixel array. Dimensions must be positive and their product must fit a signed 32-bit index; invalid sizes exit with status 1. Allocation can still fail for lack of memory. |
| `resize(width,height)` | Fit the original layout into new drawable dimensions; return whether they changed. Ignore zero dimensions. |
| `localX(x)`, `localY(y)` | Convert drawable pixels to base coordinates for input; return -1 in the margins. |
| `clear(color)` | Fill the entire canvas. |
| `pixel(x,y,color)` | Set one pixel; ignore points outside the canvas. |
| `fillRect(x,y,w,h,color)` | Fill a half-open rectangle: x through x+w-1, y through y+h-1. |
| `rect(x,y,w,h,thickness,color)` | Draw an inward outline. A sufficiently wide outline fills the rectangle. |
| `fillCircle(cx,cy,radius,color)` | Fill a circle; radius zero draws its center pixel. |
| `circle(cx,cy,radius,thickness,color)` | Draw an inward circular outline. |
| `line(x0,y0,x1,y1,thickness,color)` | Draw a round-ended segment. A zero-length segment draws a round dot. Thickness is its geometric diameter, sampled at integer pixel centers. |
| `text(x,y,string,scale,color)` | Draw a 3×5 bitmap font, with one column between characters. Upper/lowercase ASCII letters, digits, spaces, and basic punctuation are supported. Newline advances six scaled pixels. Unknown characters use `?`. |

Shapes clip to the canvas. Nonpositive rectangle extents, stroke widths, or
text scale do nothing; negative circle radii do nothing. Line and circle
coverage scans only the clipped bounding box, which is sufficient for small
turn-based games. This is a starting raster library rather than a fast animated
renderer. The pixel array remains available for direct drawing and inspection.

The constructor sets the layout's `baseWidth` and `baseHeight`. Resizing uses
`scale = min(width/baseWidth, height/baseHeight)` in floating point and centers
the result with `offsetX` and `offsetY`. Sizes, offsets, glyph cells, and stroke
widths all use this transform; circles stay circular. Positive line and circle
strokes retain at least one drawable pixel. Existing drawing coordinates remain
in base units, while `width`, `height`, and direct pixel indexing use the actual
framebuffer dimensions. `clear` fills the whole framebuffer, including margins.
At very small sizes, details smaller than a pixel naturally disappear.

Canvas reuses its pixel storage and grows its capacity geometrically when needed.
Only the first `width*height` elements are active; use `gfx.presentSize` after
resizing. This avoids allocating on every drag event, including repeated shrink
and grow cycles. Use `localX`/`localY` before button or game hit tests so drawing
and input share the same scale and centering.

Packed colors use hexadecimal literals (`0xRRGGBB`); `rgb(r,g,b)` remains handy
for computed components. The font masks use leading-zero octal, with five
digits after the prefix: each digit is one three-pixel row, top to bottom.
For example, `A` is `025755`: rows `010`, `101`, `111`, `101`, `101`.
The font includes all printable ASCII punctuation except `@`, `&`, and `$`,
which use the question-mark fallback. Colons and slashes support clock and date
labels; quotes, brackets, arithmetic signs, and other small symbols fit in 3×5.

## Button widget

`new sys.draw.Button(x,y,width,height,label)` creates a rectangular software
button. It owns no window or native resources. Feed pointer coordinates and
the held mouse-button state to `update(x,y,down)` once per event-loop iteration.
It returns true once on release inside, provided the press began inside.
Dragging in from outside does not activate it; releasing outside cancels.

`hovered` and `pressed` expose visual state. Set `enabled=false` to cancel a
pending press and disable activation; `label` can be changed at any time.
`contains(x,y)` uses half-open bounds. `draw(canvas,scale,foreground,background,active)`
paints the button and centers its 3x5 label when it fits. Colors belong to the
caller. Keyboard shortcuts belong to the application; this small widget has
no focus system. The [clock example](../../../../../docs/examples/Clock.smp) shows mouse activation
and a Space shortcut in the same single-threaded loop.

## Graphical tic-tac-toe

From `chapter32`:

```sh
make run-graphical-tictactoe
```

Click an empty square or press **1–9**, numbered left-to-right, top-to-bottom.
You are X; the CPU is O. It wins when possible, blocks your immediate win,
then prefers the center, corners, and edges. The result stays visible with
the winning line highlighted. Press **R** or **Space** to start a new game,
or **Q**/**Escape** to quit. Restart is also available during a game.

Held buttons and keys do not take repeated turns. Moving the pointer highlights
empty cells. The canvas is redrawn after a move, restart, hover change, or resize;
polling still processes window events and waits between polls.

`make graphical-tictactoe` builds without opening a window or requiring
MiniFB. Its output is `build/examples/x86_64_v2_win64/TicTacToeGraphical.exe`
on Windows or `build/examples/x86_64_v2_SystemV/TicTacToeGraphical` on Linux.
Backend discovery and explicit overrides follow [the pixel-window instructions](../gfx.md).
Passing any argument performs a five-poll, self-closing smoke test.

The original `make tictactoe` still builds the terminal game.
The graphical game also uses optional [background audio](../audio.md): a soft
boop for accepted moves, rising tones for a player win, and falling tones for
a CPU win. Bad input is silent. The run target builds/configures both backends.
`make test CLASS=DrawTest` checks raster pixels and complete game turns
without a display. `make tests_nographics` runs the ordinary suite with
the backend disabled.