Skip to content

Commit 67b00ff

Browse files
darmiedarmie
committed
docs: Add DSL building guide and update runtime plugins documentation
- Add chapter 15 on building domain-specific languages with Zyntax - Document Graphics & Media Plugins (window, SDL, paint, SVG, image, XML) - Include example DSLs for graphics, data pipelines, HDL, and games - Add step-by-step charting DSL tutorial with grammar and runtime code
1 parent 27b8c71 commit 67b00ff

3 files changed

Lines changed: 748 additions & 0 deletions

File tree

‎book/14-runtime-plugins.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -291,6 +291,166 @@ Process spawning and management.
291291
| `$Process$current_pid` | `() -> u32` | Get current PID |
292292
| `$Process$command_exists` | `(StringPtr) -> i32` | Check if command exists |
293293

294+
## Graphics & Media Plugins
295+
296+
### zrtl_window - Cross-Platform Windowing
297+
298+
High-level windowing API built on SDL2. Auto-initializes when creating windows.
299+
300+
| Symbol | Signature | Description |
301+
|--------|-----------|-------------|
302+
| `$Window$create` | `(StringPtr, i32, i32) -> u64` | Create centered window |
303+
| `$Window$create_at` | `(StringPtr, i32, i32, i32, i32) -> u64` | Create at position |
304+
| `$Window$destroy` | `(u64) -> void` | Destroy window |
305+
| `$Window$is_open` | `(u64) -> i32` | Check if window open |
306+
| `$Window$close` | `(u64) -> void` | Mark window for closing |
307+
| `$Window$set_title` | `(u64, StringPtr) -> i32` | Set window title |
308+
| `$Window$get_size` | `(u64) -> WindowSize` | Get window dimensions |
309+
| `$Window$clear` | `(u64, u32) -> void` | Clear with RGBA color |
310+
| `$Window$present` | `(u64) -> void` | Present frame |
311+
| `$Window$draw_pixel` | `(u64, i32, i32) -> i32` | Draw single pixel |
312+
| `$Window$draw_line` | `(u64, i32, i32, i32, i32) -> i32` | Draw line |
313+
| `$Window$draw_rect` | `(u64, i32, i32, i32, i32) -> i32` | Draw rectangle outline |
314+
| `$Window$fill_rect` | `(u64, i32, i32, i32, i32) -> i32` | Fill rectangle |
315+
| `$Window$fill_rect_color` | `(u64, i32, i32, i32, i32, u32) -> i32` | Fill with color |
316+
| `$Window$blit` | `(u64, *u8, i32, i32, i32, i32, i32) -> i32` | Blit pixel buffer |
317+
| `$Window$blit_scaled` | `(...) -> i32` | Blit with scaling |
318+
| `$Window$poll_event` | `() -> WindowEvent` | Poll events (non-blocking) |
319+
| `$Window$wait_event` | `() -> WindowEvent` | Wait for event |
320+
| `$Window$delay` | `(u32) -> void` | Sleep milliseconds |
321+
322+
**Color format**: RGBA as `0xRRGGBBAA` (e.g., `0xFF0000FF` = red)
323+
324+
**Event types**: `EVENT_QUIT`, `EVENT_KEY_DOWN`, `EVENT_KEY_UP`, `EVENT_MOUSE_MOVE`, `EVENT_MOUSE_DOWN`, `EVENT_MOUSE_UP`, `EVENT_RESIZE`
325+
326+
### zrtl_sdl - Low-Level SDL2 Bindings
327+
328+
Direct SDL2 access for advanced use cases. Requires explicit initialization.
329+
330+
| Symbol | Signature | Description |
331+
|--------|-----------|-------------|
332+
| `$Sdl$init` | `() -> i32` | Initialize SDL |
333+
| `$Sdl$quit` | `() -> void` | Quit SDL |
334+
| `$Sdl$window_create` | `(StringPtr, i32, i32, u32, u32) -> u64` | Create window |
335+
| `$Sdl$window_create_centered` | `(StringPtr, u32, u32) -> u64` | Create centered |
336+
| `$Sdl$set_draw_color` | `(u64, u8, u8, u8, u8) -> void` | Set RGBA color |
337+
| `$Sdl$clear` | `(u64) -> void` | Clear canvas |
338+
| `$Sdl$present` | `(u64) -> void` | Present frame |
339+
| `$Sdl$draw_point` | `(u64, i32, i32) -> i32` | Draw point |
340+
| `$Sdl$draw_line` | `(u64, i32, i32, i32, i32) -> i32` | Draw line |
341+
| `$Sdl$draw_rect` | `(u64, i32, i32, u32, u32) -> i32` | Draw rect outline |
342+
| `$Sdl$fill_rect` | `(u64, i32, i32, u32, u32) -> i32` | Fill rect |
343+
| `$Sdl$blit_rgba` | `(u64, *u8, u32, u32, u32, i32, i32) -> i32` | Blit RGBA buffer |
344+
| `$Sdl$poll_event` | `() -> SdlEvent` | Poll events |
345+
| `$Sdl$wait_event` | `() -> SdlEvent` | Wait for event |
346+
| `$Sdl$get_ticks` | `() -> u32` | Milliseconds since init |
347+
| `$Sdl$delay` | `(u32) -> void` | Sleep milliseconds |
348+
349+
### zrtl_paint - 2D Software Rasterization
350+
351+
High-quality 2D rendering with anti-aliased shapes, paths, and transforms.
352+
353+
| Symbol | Signature | Description |
354+
|--------|-----------|-------------|
355+
| `$Paint$canvas_create` | `(u32, u32) -> u64` | Create canvas |
356+
| `$Paint$canvas_free` | `(u64) -> void` | Free canvas |
357+
| `$Paint$canvas_clear` | `(u64, Color) -> void` | Clear with color |
358+
| `$Paint$canvas_get_buffer` | `(u64) -> CanvasBuffer` | Get pixel buffer info |
359+
| `$Paint$canvas_data_ptr` | `(u64) -> *u8` | Get raw pixel pointer |
360+
| `$Paint$canvas_save_png` | `(u64, StringPtr) -> i32` | Save to PNG file |
361+
| `$Paint$rgb` | `(u8, u8, u8) -> Color` | Create RGB color |
362+
| `$Paint$rgba` | `(u8, u8, u8, u8) -> Color` | Create RGBA color |
363+
| `$Paint$hex` | `(u32) -> Color` | Color from hex |
364+
| `$Paint$fill_rect` | `(u64, f32, f32, f32, f32, Color)` | Fill rectangle |
365+
| `$Paint$stroke_rect` | `(...)` | Stroke rectangle |
366+
| `$Paint$fill_circle` | `(u64, f32, f32, f32, Color)` | Fill circle |
367+
| `$Paint$stroke_circle` | `(...)` | Stroke circle |
368+
| `$Paint$fill_ellipse` | `(u64, f32, f32, f32, f32, Color)` | Fill ellipse |
369+
| `$Paint$fill_rounded_rect` | `(..., f32, Color)` | Fill rounded rect |
370+
| `$Paint$draw_line` | `(u64, f32, f32, f32, f32, Color)` | Draw line |
371+
| `$Paint$path_create` | `() -> u64` | Create path builder |
372+
| `$Paint$path_move_to` | `(u64, f32, f32)` | Move to point |
373+
| `$Paint$path_line_to` | `(u64, f32, f32)` | Line to point |
374+
| `$Paint$path_quad_to` | `(u64, f32, f32, f32, f32)` | Quadratic bezier |
375+
| `$Paint$path_cubic_to` | `(...)` | Cubic bezier |
376+
| `$Paint$path_fill` | `(u64, u64, Color)` | Fill path |
377+
| `$Paint$path_stroke` | `(u64, u64, Color)` | Stroke path |
378+
| `$Paint$transform_translate` | `(u64, f32, f32)` | Apply translation |
379+
| `$Paint$transform_rotate` | `(u64, f32)` | Apply rotation (radians) |
380+
| `$Paint$transform_scale` | `(u64, f32, f32)` | Apply scale |
381+
| `$Paint$set_stroke_width` | `(u64, f32)` | Set stroke width |
382+
383+
**Rendering to Window**: Use `canvas_get_buffer()` to get pixel data, then `$Window$blit()`:
384+
385+
```
386+
let canvas = $Paint$canvas_create(800, 600);
387+
$Paint$fill_circle(canvas, 400, 300, 100, $Paint$rgb(255, 0, 0));
388+
389+
let buffer = $Paint$canvas_get_buffer(canvas);
390+
$Window$blit(win, buffer.data, buffer.width, buffer.height, buffer.pitch, 0, 0);
391+
$Window$present(win);
392+
```
393+
394+
### zrtl_svg - SVG Parsing & Rendering
395+
396+
Parse and render SVG files using resvg/usvg.
397+
398+
| Symbol | Signature | Description |
399+
|--------|-----------|-------------|
400+
| `$Svg$parse` | `(StringPtr) -> u64` | Parse SVG from string |
401+
| `$Svg$parse_file` | `(StringPtr) -> u64` | Parse SVG from file |
402+
| `$Svg$free` | `(u64) -> void` | Free SVG handle |
403+
| `$Svg$get_width` | `(u64) -> f32` | Get SVG width |
404+
| `$Svg$get_height` | `(u64) -> f32` | Get SVG height |
405+
| `$Svg$render` | `(u64) -> RenderResult` | Render at natural size |
406+
| `$Svg$render_scaled` | `(u64, f32) -> RenderResult` | Render with scale |
407+
| `$Svg$pixmap_data` | `(u64) -> *u8` | Get rendered pixel data |
408+
| `$Svg$pixmap_save_png` | `(u64, StringPtr) -> i32` | Save pixmap to PNG |
409+
| `$Svg$pixmap_free` | `(u64) -> void` | Free rendered pixmap |
410+
411+
### zrtl_image - Image Encoding/Decoding
412+
413+
Load and save images in common formats (PNG, JPEG, GIF, WebP, BMP, ICO, TIFF).
414+
415+
| Symbol | Signature | Description |
416+
|--------|-----------|-------------|
417+
| `$Image$load` | `(StringPtr) -> u64` | Load image from file |
418+
| `$Image$load_from_memory` | `(ArrayPtr) -> u64` | Load from bytes |
419+
| `$Image$free` | `(u64) -> void` | Free image |
420+
| `$Image$width` | `(u64) -> u32` | Get width |
421+
| `$Image$height` | `(u64) -> u32` | Get height |
422+
| `$Image$get_pixel` | `(u64, u32, u32) -> u32` | Get RGBA pixel |
423+
| `$Image$set_pixel` | `(u64, u32, u32, u32) -> void` | Set RGBA pixel |
424+
| `$Image$save_png` | `(u64, StringPtr) -> i32` | Save as PNG |
425+
| `$Image$save_jpeg` | `(u64, StringPtr, u8) -> i32` | Save as JPEG (quality) |
426+
| `$Image$resize` | `(u64, u32, u32) -> u64` | Resize image |
427+
| `$Image$crop` | `(u64, u32, u32, u32, u32) -> u64` | Crop region |
428+
| `$Image$flip_horizontal` | `(u64) -> void` | Flip horizontally |
429+
| `$Image$flip_vertical` | `(u64) -> void` | Flip vertically |
430+
| `$Image$rotate90` | `(u64) -> u64` | Rotate 90 degrees |
431+
| `$Image$to_grayscale` | `(u64) -> u64` | Convert to grayscale |
432+
| `$Image$get_data` | `(u64) -> *u8` | Get raw RGBA data |
433+
434+
### zrtl_xml - XML Parsing & Generation
435+
436+
XML document manipulation with quick-xml.
437+
438+
| Symbol | Signature | Description |
439+
|--------|-----------|-------------|
440+
| `$Xml$parse` | `(StringPtr) -> u64` | Parse XML string |
441+
| `$Xml$parse_file` | `(StringPtr) -> u64` | Parse XML file |
442+
| `$Xml$free` | `(u64) -> void` | Free document |
443+
| `$Xml$stringify` | `(u64) -> StringPtr` | Convert to string |
444+
| `$Xml$root` | `(u64) -> u64` | Get root element |
445+
| `$Xml$tag_name` | `(u64) -> StringPtr` | Get element tag name |
446+
| `$Xml$text_content` | `(u64) -> StringPtr` | Get text content |
447+
| `$Xml$get_attribute` | `(u64, StringPtr) -> StringPtr` | Get attribute |
448+
| `$Xml$set_attribute` | `(u64, StringPtr, StringPtr) -> void` | Set attribute |
449+
| `$Xml$children` | `(u64) -> ArrayPtr` | Get child elements |
450+
| `$Xml$find_by_tag` | `(u64, StringPtr) -> ArrayPtr` | Find by tag name |
451+
| `$Xml$create_element` | `(StringPtr) -> u64` | Create element |
452+
| `$Xml$append_child` | `(u64, u64) -> void` | Append child |
453+
294454
## Building Plugins
295455

296456
### Dynamic Libraries (.zrtl)

0 commit comments

Comments
 (0)