dietrich/turtle
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

improve README

Browse Source
This commit is contained in:
Franz Dietrich 2026-05-21 22:51:19 +02:00
parent 89c778289c
commit 106dd79677
1 changed files with 22 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
README.md
View File

@ -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. 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 ## Features
- 🎨 **Simple Builder API**: Chain commands like `forward(100).right(90)` - 🎨 **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 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: The `turtle_main` macro sets up the Macroquad window, turtle initialization, and main loop for you. It expands to code similar to this:
@ -50,7 +47,7 @@ use turtle_lib::*;
#[macroquad::main("Turtle")] #[macroquad::main("Turtle")]
async fn main() { async fn main() {
// Create a turtle plan // Create a turtle plan
let mut plan = create_turtle(); let mut plan = create_turtle_plan();
// Set speed (part of the plan) // Set speed (part of the plan)
plan.set_speed(100); plan.set_speed(100);
@ -77,7 +74,7 @@ async fn main() {
### Creating Plans ### Creating Plans
```rust ```rust
let mut plan = create_turtle(); let mut plan = create_turtle_plan();
// Movement // Movement
plan.forward(100); plan.forward(100);
@ -134,7 +131,7 @@ plan.forward(100).right(90).forward(50);
Speed controlled via commands, allowing dynamic switching during execution: Speed controlled via commands, allowing dynamic switching during execution:
```rust ```rust
let mut plan = create_turtle(); let mut plan = create_turtle_plan();
// Fast initial positioning (instant mode) // Fast initial positioning (instant mode)
plan.set_speed(1000); plan.set_speed(1000);
@ -152,8 +149,9 @@ let app = TurtleApp::new().with_commands(plan.build());
``` ```
**Speed Modes:** **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 - Default speed is 100.0 if not specified
## Debugging and Logging ## Debugging and Logging
@ -208,16 +206,11 @@ cargo run --example hello_turtle --features svg -- --export-svg square.svg
``` ```
This will: This will:
- Execute all drawing commands instantly (no animation) - Execute all drawing commands instantly (no animation)
- Export the result to an SVG file - Export the result to an SVG file
- Exit immediately without opening a window - 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 ### Programmatic SVG Export
You can also export SVG programmatically from your code: 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 ## Examples
Run examples with: Run examples with:
```bash ```bash
cargo run --example square cargo run --example square
cargo run --example koch cargo run --example koch
@ -276,6 +270,7 @@ RUST_LOG=turtle_lib=debug cargo run --example logging_example
### Available Examples ### Available Examples
#### Basic Drawing #### Basic Drawing
- **square.rs**: Basic square drawing - **square.rs**: Basic square drawing
- **koch.rs**: Koch snowflake fractal - **koch.rs**: Koch snowflake fractal
- **shapes.rs**: Demonstrates different turtle shapes - **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 - **nikolaus.rs**: Nikolaus (Santa) drawing
#### Fill Examples #### Fill Examples
- **yinyang.rs**: Yin-yang symbol with automatic hole detection - **yinyang.rs**: Yin-yang symbol with automatic hole detection
- **fill_demo.rs**: Donut shape with hole - **fill_demo.rs**: Donut shape with hole
- **fill_requirements.rs**: Circle with red fill - **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 - **fill_instant_test.rs**: Quick fill test in instant mode
#### Export #### Export
- **export_svg.rs**: Demonstrates SVG export functionality (requires `--features svg`) - **export_svg.rs**: Demonstrates SVG export functionality (requires `--features svg`)
#### Debugging #### Debugging
- **logging_example.rs**: Demonstrates how to enable and use tracing/logging output - **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 ### Basic Fill
```rust ```rust
let mut plan = create_turtle(); let mut plan = create_turtle();
plan.set_fill_color(RED); plan.set_fill_color(RED);
@ -319,6 +311,7 @@ plan.end_fill(); // Auto-closes and fills
``` ```
### Fill with Holes (Multi-Contour) ### Fill with Holes (Multi-Contour)
```rust ```rust
plan.set_fill_color(BLUE); plan.set_fill_color(BLUE);
plan.begin_fill(); plan.begin_fill();
@ -339,14 +332,6 @@ plan.circle_left(30.0, 360.0, 36);
plan.end_fill(); // Auto-detects holes and fills correctly 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 ## Architecture
### Module Structure ### Module Structure
@ -396,12 +381,13 @@ cargo build --features svg
## Development Status ## Development Status
### ✅ Completed ### ✅ Completed
- **Turtle movement** and rotation (consolidated Move/Turn commands) - **Turtle movement** and rotation (consolidated Move/Turn commands)
- **Pen control** (up/down) with contour management - **Pen control** (up/down) with contour management
- **Color** and **pen width** - **Color** and **pen width**
- **Circle arcs** (left/right with unified Circle command) - **Circle arcs** (left/right with unified Circle command)
- **Dynamic speed control** via SetSpeed commands - **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 - **Multi-contour fill** system with automatic hole detection
- **Lyon integration** for all drawing primitives - **Lyon integration** for all drawing primitives
- **Multiple turtle shapes** with custom shape support - **Multiple turtle shapes** with custom shape support
@ -409,30 +395,8 @@ cargo build --features svg
- **EvenOdd fill rule** for complex self-intersecting paths - **EvenOdd fill rule** for complex self-intersecting paths
- **Live fill preview** during animation with progressive rendering - **Live fill preview** during animation with progressive rendering
- **Multi-contour support** - pen_up/pen_down manage contours - **Multi-contour support** - pen_up/pen_down manage contours
- **Command consolidation**
- **SVG Export** - Export drawings to SVG with viewBox and padding (feature-gated) - **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
## License ## License
MIT OR Apache-2.0 MIT OR Apache-2.0