Module gemini_engine::elements3d

Gemini’s implementation of 3D rendering. Capable of rendering full 3D meshes as wireframes, solid colours or with lighting

A Simple 3D Scene

Let’s write a simple example program to print a spinning cube:

use gemini_engine::elements::{
    view::{View, ColChar, Wrapping},
    Vec2D,
};
use gemini_engine::elements3d::{DisplayMode, Mesh3D, Vec3D, Viewport, Transform3D};
use gemini_engine::gameloop;

const FPS: f32 = 20.0;
const FOV: f64 = 95.0;

fn main() {
    let mut frame_skip = false;
    let mut view = View::new(350, 90, ColChar::BACKGROUND);

    let mut viewport = Viewport::new(
        Transform3D::new_tr(
            Vec3D::new(0.0, 0.0, 5.0),
            Vec3D::new(-0.5, 0.0, 0.0)
        ),
        FOV,
        view.center(),
    );

    let cube = Mesh3D::default_cube();

    loop {
        let now = gameloop::Instant::now();
        view.clear();

        viewport.transform.rotation.y -= 0.05;

        match frame_skip {
            true => frame_skip = false,
            false => {
                view.blit(
                    &viewport.render(vec![&cube], DisplayMode::Solid),
                    Wrapping::Ignore
                );
                view.display_render().unwrap();
            }
        }

        let elapsed = now.elapsed();
        println!(
            "Elapsed: {:.2?}µs | Frame skip: {}",
            elapsed.as_micros(),
            frame_skip
        );

        frame_skip = gameloop::sleep_fps(FPS, Some(elapsed));
    }
}

There is a lot of code here, but since the main loop is based off of the gameloop principle (Go to the gameloop documentation page to learn more), we’ll only focus on the parts that are different from the gameloop example:

Initialisation

let mut view = View::new(350, 90, ColChar::BACKGROUND);

let mut viewport = Viewport::new(
    Transform3D::DEFAULT,
    FOV,
    view.size(),
);

let cube = Mesh3D::default_cube();

main() begins with the creation of all the necessary objects to render 3D images:

1. View to handle the canvas and printing to the screen
2. Viewport to handle converting 3d objects to 2d images, as well as acting like the scene’s camera
3. The actual objects you intend to use in the scene, as Mesh3D

In this scenario, we create a View of width 350 and height 90 (you may have to zoom out and expand your terminal to fit the whole image), a Viewport with a transform of rotation 0.5 radians and translation 5 units away from the centre, our desired FOV and origin point (the centre of the view we’re printing to) in the middle of the View and a single default cube, which is 2 units tall, wide and long and is placed directly in the middle of the scene.

Gameloop process logic

viewport.transform.rotation.y -= 0.05;

This part of the code is where we would put all our physics, collisions, events etc. code, but in this case the only thing we do is rotate the cube 0.05 radians anticlockwise.

Blitting/Rendering

view.blit(&viewport.render(vec![&cube], DisplayMode::Solid), Wrapping::Ignore);
view.display_render().unwrap();

This part of the code renders all the 3d stuff to the View and blits it to the view before rendering as usual. Viewport.render() takes a list of all the objects we want to render and a DisplayMode enum (more info in the DisplayMode documentation).

Re-exports

• pub use view3d::DisplayMode;
• pub use view3d::Face;
• pub use view3d::Light;
• pub use view3d::Transform3D;
• pub use view3d::Vec3D;
• pub use view3d::Viewport;

Modules

• view3d
  This module is home to the Viewport, which handles the projecting of Mesh3Ds to a format then displayable by a View

Structs

• Mesh3D
  The struct for a Mesh3D object, containing a position, rotation, collection of vertices and collection of Faces with indices to the vertex collection.