Description Lib2DHD is a high-performance framework built on top of Macroquad for creating HD-2D, Diorama, and 2.5D games. It provides a unified camera system, virtual resolution management, post-processing effects (Depth of Field, Vignette), and an optimized batch rendering pipeline for mixed 2D/3D development.

Installation

Add the library to your Cargo.toml:

[dependencies]
lib2dhd = { path = "path/to/lib2dhd" } # Or git repository
macroquad = "0.4"

Quick Start

The following example initializes the engine, sets up a game loop, and renders a simple scene.

use lib2dhd::prelude::*;

#[macroquad::main("Lib2DHD Project")]
async fn main() {
    // Initialize the engine with reliable defaults
    let mut engine = Diorama::builder()
        .with_resolution(320, 180)
        .with_mode(CameraMode::Hd2d)
        .with_post_processing(true)
        .build()
        .expect("Failed to initialize engine");

    loop {
        // Update engine state (camera, inputs)
        // target_pos is the point the camera should follow (e.g. player position)
        let target_pos = Vec3::ZERO;
        engine.update(get_frame_time(), target_pos);

        // Render the 3D scene
        engine.draw_scene(|| {
            draw_cube(Vec3::ZERO, Vec3::ONE, None, RED);
        });

        // End frame
        next_frame().await;
    }
}

Core Features

• Diorama Facade: A single entry point (Diorama struct) managing camera, viewport, effects, and rendering context.
• Pixel-Perfect Scaling: Renders to a fixed low resolution (e.g., 320x180) and upscales to fit the window, preserving the pixel-art aesthetic.
• Optimized Rendering:
  • Billboard Batching: BillboardBatcher renders thousands of sprites in a single draw call.
  • Vector Math: Trig-free billboard calculations for maximum performance.
  • Double Buffering: Prevents tearing and prepares for temporal effects.
• Post-Processing:
  • Depth of Field: High-quality 2-pass Gaussian blur for the "miniature" look.
  • Vignette: Cinematic lens darkening (optional).
  • Color Grading: Saturation and brightness control.

Camera Modes

The engine provides five distinct camera projections:

1. Free3D: Standard perspective projection with free rotation.
2. Scroll2D: Orthographic side view (zero pitch) for platformers.
3. TopDown: Orthographic top-down view (90-degree pitch).
4. DioramaIso: Orthographic isometric view, creating a "dollhouse" effect.
5. Hd2d: Orthographic projection with a specific angle, mimicking modern JRPG styles.

Performance & Batching

For optimal performance with many sprites, use the BillboardBatcher:

// Create a batcher (reusable)
let mut batcher = BillboardBatcher::new(1000);

engine.draw_scene(|| {
    // Queue multiple sprites
    for sprite in &sprites {
        batcher.queue(sprite, position, engine.camera_right());
    }
    // Draw all at once
    batcher.flush();
});

Building & Running Examples

Run the provided examples to see the engine in action:

# Main demo with camera cycling
cargo run --example demo

# Post-processing showcase (DoF, Vignette controls)
cargo run --example post_fx

# Example using the Scene trait architecture
cargo run --example scene_demo