15 releases (4 breaking)

0.5.5 Oct 21, 2024
0.5.4 Oct 17, 2024
0.4.2 Oct 11, 2024
0.3.4 Sep 23, 2024
0.1.0 Aug 31, 2024

#36 in Graphics APIs

Download history 399/week @ 2024-08-31 30/week @ 2024-09-07 118/week @ 2024-09-14 289/week @ 2024-09-21 32/week @ 2024-09-28 403/week @ 2024-10-05 850/week @ 2024-10-12 249/week @ 2024-10-19 12/week @ 2024-10-26 35/week @ 2024-11-02 1/week @ 2024-11-09

52 downloads per month

MIT license

40KB
767 lines

cube3d

A 3D cube renderer with per-pixel lighting using Rust and the Druid GUI framework.

Overview

cube3d is a Rust application that renders a rotating 3D cube with per-pixel lighting for accurate shading effects. It demonstrates fundamental 3D graphics concepts such as transformation matrices, rasterization, depth buffering, and lighting calculations without relying on a dedicated graphics library like OpenGL or Vulkan.

Features

  • Per-Pixel Lighting: Implements per-pixel lighting for realistic shading across the cube's surface.
  • World Space Lighting: Displays the light position in world space.
  • Wireframe Mode: Renders the cube in wireframe mode.
  • Rotating 3D Cube: Continuously rotates a 3D cube around its axis.
  • Debug Mode: Displays frames per second (FPS), rotation angle, light position, and program information.
  • Mouse Zoom: Zoom the cube in and out using the mouse wheel.
  • Mouse Rotation: Rotate the cube around its axis using the mouse.
  • Mouse Translation: Translate the cube using the mouse.

Prerequisites

  • Rust: Make sure you have Rust installed. You can download it from rust-lang.org.
  • Cargo: Comes bundled with Rust for package management and building.

Building

Clone the repository and navigate to the project directory:

git clone https://github.com/drewwalton19216801/cube3d.git
cd cube3d

Build the project using Cargo:

cargo build --release

This will compile the project in release mode for optimal performance.

Running

Run the application with Cargo:

cargo run --release

Enabling Debug Mode

To enable debug mode and display additional information, press the d key during program operation.

Pausing/Resuming

To pause/resume the program, press the p key during program operation.

Resetting Zoom and Translation

To reset the cube's position and zoom level to their defaults, press the r key during program operation.

Quitting

To quit the program, press the q key during program operation.

How It Works

  • 3D Transformations: Applies rotation matrices to simulate cube rotation around the X and Y axes.
  • Rasterization: Converts 3D triangles into pixels on the 2D screen.
  • Depth Buffering: Implements a Z-buffer to handle occlusion of faces.
  • Per-Pixel Lighting: Calculates lighting at each pixel by interpolating normals and positions, providing smooth shading.

Dependencies

The project uses the following crates:

  • druid: A data-first Rust-native UI design toolkit.

These dependencies are specified in Cargo.toml and will be automatically fetched when you build the project.

Learning Resources

Contributing

Contributions are welcome! Feel free to submit a pull request or open an issue for suggestions and improvements.

License

This project is licensed under the MIT License. See the License file for details.

Acknowledgements

  • Inspired by basic 3D rendering techniques.
  • Special thanks to the Rust community for their excellent resources.
  • Claude 3.5 Sonnet for the initial implementations.
  • GPT o1-preview for further improvements.

Dependencies

~7–11MB
~205K SLoC