improve README
This commit is contained in:
parent
89c778289c
commit
106dd79677
80
README.md
80
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
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user