From 106dd7967702afe77d112ee84bcc77016ea08be1 Mon Sep 17 00:00:00 2001 From: Franz Dietrich Date: Thu, 21 May 2026 22:51:19 +0200 Subject: [PATCH] improve README --- README.md | 80 +++++++++++++++---------------------------------------- 1 file changed, 22 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 4658778..b4b5089 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,6 @@ A modern turtle graphics library for Rust built on [Macroquad](https://macroquad.rs/) with [Lyon](https://github.com/nical/lyon) for high-quality GPU-accelerated rendering. -## Project Status - -✅ **Stable** - Complete Lyon integration with multi-contour fill system and live animation preview. - ## Features - 🎨 **Simple Builder API**: Chain commands like `forward(100).right(90)` @@ -39,6 +35,7 @@ fn hello() { } } ``` + The turtle starts at the center of the window, facing right (0 degrees). The above code draws a blue square. The `turtle_main` macro sets up the Macroquad window, turtle initialization, and main loop for you. It expands to code similar to this: @@ -50,19 +47,19 @@ use turtle_lib::*; #[macroquad::main("Turtle")] async fn main() { // Create a turtle plan - let mut plan = create_turtle(); - + let mut plan = create_turtle_plan(); + // Set speed (part of the plan) plan.set_speed(100); - + // Draw a square for _ in 0..4 { plan.forward(100).right(90); } - + // Create app (speed is managed by commands) let mut app = TurtleApp::new().with_commands(plan.build()); - + loop { clear_background(WHITE); app.update(); @@ -77,7 +74,7 @@ async fn main() { ### Creating Plans ```rust -let mut plan = create_turtle(); +let mut plan = create_turtle_plan(); // Movement plan.forward(100); @@ -134,7 +131,7 @@ plan.forward(100).right(90).forward(50); Speed controlled via commands, allowing dynamic switching during execution: ```rust -let mut plan = create_turtle(); +let mut plan = create_turtle_plan(); // Fast initial positioning (instant mode) plan.set_speed(1000); @@ -152,8 +149,9 @@ let app = TurtleApp::new().with_commands(plan.build()); ``` **Speed Modes:** -- **Speed < 999**: Animated mode with smooth tweening -- **Speed >= 999**: Instant mode (no animation) the bigger the number the more segments will be added per frame. + +- **Speed < 1000**: Animated mode with smooth tweening +- **Speed >= 1000**: Instant mode (no animation) the bigger the number the more segments will be added per frame. - Default speed is 100.0 if not specified ## Debugging and Logging @@ -208,16 +206,11 @@ cargo run --example hello_turtle --features svg -- --export-svg square.svg ``` This will: + - Execute all drawing commands instantly (no animation) - Export the result to an SVG file - Exit immediately without opening a window -**Note**: The program still requires a display context to initialize. In headless environments, use `xvfb-run`: - -```bash -xvfb-run -a cargo run --example macro_demo --features svg -- --export-svg output.svg -``` - ### Programmatic SVG Export You can also export SVG programmatically from your code: @@ -253,6 +246,7 @@ The exported SVG can be opened in any web browser or vector graphics application ## Examples Run examples with: + ```bash cargo run --example square cargo run --example koch @@ -276,6 +270,7 @@ RUST_LOG=turtle_lib=debug cargo run --example logging_example ### Available Examples #### Basic Drawing + - **square.rs**: Basic square drawing - **koch.rs**: Koch snowflake fractal - **shapes.rs**: Demonstrates different turtle shapes @@ -283,6 +278,7 @@ RUST_LOG=turtle_lib=debug cargo run --example logging_example - **nikolaus.rs**: Nikolaus (Santa) drawing #### Fill Examples + - **yinyang.rs**: Yin-yang symbol with automatic hole detection - **fill_demo.rs**: Donut shape with hole - **fill_requirements.rs**: Circle with red fill @@ -291,19 +287,15 @@ RUST_LOG=turtle_lib=debug cargo run --example logging_example - **fill_instant_test.rs**: Quick fill test in instant mode #### Export + - **export_svg.rs**: Demonstrates SVG export functionality (requires `--features svg`) #### Debugging + - **logging_example.rs**: Demonstrates how to enable and use tracing/logging output -## Why Lyon? - -- Automatic hole detection via EvenOdd fill rule -- Handles any self-intersecting path -- GPU-accelerated rendering -- Standards-compliant (matches SVG, HTML Canvas) - ### Basic Fill + ```rust let mut plan = create_turtle(); plan.set_fill_color(RED); @@ -319,6 +311,7 @@ plan.end_fill(); // Auto-closes and fills ``` ### Fill with Holes (Multi-Contour) + ```rust plan.set_fill_color(BLUE); plan.begin_fill(); @@ -339,14 +332,6 @@ plan.circle_left(30.0, 360.0, 36); plan.end_fill(); // Auto-detects holes and fills correctly ``` -### Fill Features - -- ✅ **Live Preview** - See fills progressively during animation -- ✅ **Auto-Close** - Automatically connects end point to start on `end_fill()` -- ✅ **Multi-Contour** - `pen_up()` closes contour, `pen_down()` opens next one -- ✅ **Automatic Hole Detection** - EvenOdd fill rule handles any complexity -- ✅ **Self-Intersecting Paths** - Stars and complex shapes work perfectly - ## Architecture ### Module Structure @@ -396,12 +381,13 @@ cargo build --features svg ## Development Status ### ✅ Completed + - **Turtle movement** and rotation (consolidated Move/Turn commands) - **Pen control** (up/down) with contour management - **Color** and **pen width** - **Circle arcs** (left/right with unified Circle command) - **Dynamic speed control** via SetSpeed commands -- **Instant mode** (speed ≥ 999) and animated mode (speed < 999) +- **Instant mode** (speed ≥ 1000) and **animated mode** (speed < 1000) - **Multi-contour fill** system with automatic hole detection - **Lyon integration** for all drawing primitives - **Multiple turtle shapes** with custom shape support @@ -409,29 +395,7 @@ cargo build --features svg - **EvenOdd fill rule** for complex self-intersecting paths - **Live fill preview** during animation with progressive rendering - **Multi-contour support** - pen_up/pen_down manage contours -- **Command consolidation** -- **SVG Export** - Export drawings to SVG with viewBox and padding (feature-gated) - -## What's New - -### Complete Lyon Migration ✨ -All drawing operations now use GPU-accelerated Lyon tessellation: -- **Unified pipeline**: Lines, arcs, circles, and fills - all use the same high-quality rendering -- **Simplified codebase**: ~410 lines of code eliminated -- **Better performance**: GPU tessellation is faster than CPU-based primitives -- **Consistent quality**: No more mixed rendering approaches - -### Multi-Contour Fill System 🕳️ -Advanced fill capabilities with automatic hole detection: -- **EvenOdd fill rule**: Draw shapes with holes - works like SVG and HTML Canvas -- **Pen state management**: `pen_up()` closes contour, `pen_down()` opens next -- **Live preview**: See fills progressively during animations -- **Self-intersecting paths**: Stars, complex shapes - all handled correctly - -### Architectural Improvements 🏗️ -- **Command consolidation**: Unified Move/Turn/Circle commands (~250 lines eliminated) -- **Dynamic speed control**: Change speed during execution via commands -- **Live animation preview**: Progressive fill rendering during circle/arc drawing +- **SVG Export** - Export drawings to SVG with viewBox and padding (feature-gated) ## License