turtle-lib

The main turtle graphics library built on Macroquad with Lyon tessellation.

See the main README for complete documentation.

Features

✅ Complete Lyon Integration - All drawing operations use GPU-optimized tessellation

Unified rendering pipeline for lines, arcs, circles, and fills
~410 lines of code eliminated through architectural simplification
Consistent high-quality rendering across all primitives

✅ Multi-Contour Fill System - Advanced fill capabilities with automatic hole detection

EvenOdd fill rule for complex shapes with holes (like cheese or yin-yang symbols)
pen_up() closes current contour, pen_down() opens next contour
Progressive fill preview during animations
Support for self-intersecting paths

✅ Smooth Animation - Tweening system with live rendering

Configurable speed control
Frame-rate independent animation
Live fill preview during circle/arc drawing

Quick Start

Using the `turtle_main` Macro (Recommended for Beginners)

The easiest way to create turtle programs is with the turtle_main macro:

use macroquad::prelude::*;
use turtle_lib::*;

#[turtle_main("My First Drawing")]
fn my_drawing(turtle: &mut TurtlePlan) {
    turtle.set_pen_color(RED);
    turtle.forward(100.0);
    turtle.right(90.0);
    turtle.forward(100.0);
}

The macro automatically handles:

Window creation and setup
Turtle initialization
Rendering loop
Quit handling (ESC or Q keys)

Manual Setup (For Advanced Use)

For more control over the application loop:

use macroquad::prelude::*;
use turtle_lib::*;

#[macroquad::main("Turtle")]
async fn main() {
    let mut turtle = create_turtle();
    turtle.forward(100.0).right(90.0);
    
    let mut app = TurtleApp::new().with_commands(turtle.build());
    
    loop {
        clear_background(WHITE);
        app.update();
        app.render();
        next_frame().await;
    }
}

Quick Examples

All examples now use the turtle_main macro for simplicity:

# Run from this directory
cargo run --example hello_turtle      # Minimal 10-line example
cargo run --example macro_demo        # Simple square with macro
cargo run --example square            # Basic square drawing
cargo run --example shapes            # Different turtle shapes
cargo run --example yinyang           # Multi-contour fills with holes
cargo run --example koch              # Recursive fractals
cargo run --example fill_demo         # Fill with holes (donut)
cargo run --example cheese_macro      # Cheese example using macro
cargo run --example fill_advanced     # Complex shapes (manual setup)

Most examples use turtle_main for simplicity. A few keep manual setup for custom UI or logging.

Architecture Highlights

Rendering Pipeline

All drawing operations → Lyon tessellation → GPU mesh rendering

DrawCommand Enum

Simplified from 5 variants to 1:

Mesh(MeshData) - unified variant for all drawing operations

Fill System

FillState tracks multiple contours (completed + current)
Pen state management automatically handles contour creation
EvenOdd tessellation provides automatic hole detection

See LYON_COMPLETE.md and MULTI_CONTOUR_FILLS.md for implementation details.

Status

✅ Stable - Lyon integration complete, multi-contour fills working, all examples passing.

See ../README.md for full API documentation and project status.

3.4 KiB Raw Blame History