Crate three

Expand description

Three.js inspired 3D engine.

Getting Started

Creating a window

Every three application begins with a Window. We create it as follows.

let title = "Getting started with three-rs";
let mut window = three::Window::new(title);

The four key structs

Every Window comes equipped with four structures, namely Factory, Renderer, Input, and Scene.

The Factory instantiates game objects such as Mesh and Camera.
The Input handles window events at a high-level.
The Scene is the root node of the component-graph system.
The Renderer renders the Scene from the view of a Camera object.

Renderable 3D objects are represented by the Mesh struct. A mesh is a combination of Geometry, describing the shape of the object, paired with a Material, describing the appearance of the object.

let geometry = three::Geometry::with_vertices(vec![
    [-0.5, -0.5, -0.5].into(),
    [ 0.5, -0.5, -0.5].into(),
    [ 0.0,  0.5, -0.5].into(),
]);
let material = three::material::Basic {
    color: 0xFFFF00,
    .. Default::default()
};
let mut mesh = window.factory.mesh(geometry, material);

Managing the scene

In order to be rendered by the Renderer, meshes must be placed in the Scene within the viewable region. Any marked with the Object trait may be placed into the scene heirarchy, including user-defined structs.

window.scene.add(&mesh);

We can set the initial scene background using the Scene::background field. The default background is solid black. Let’s set the background to a sky blue color instead.

window.scene.background = three::Background::Color(0xC6F0FF);

Creating the game loop

All is left to do to render our triangle is to create a camera and to write the main game loop.

let center = [0.0, 0.0];
let yextent = 1.0;
let zrange = -1.0 .. 1.0;
let camera = window.factory.orthographic_camera(center, yextent, zrange);
while window.update() {
    window.render(&camera);
}

Putting it all together

You should have the following code which renders a single yellow triangle upon a sky blue background.

extern crate three;

use three::Object;

fn main() {
    let title = "Getting started with three-rs";
    let mut window = three::Window::new(title);

    let vertices = vec![
        [-0.5, -0.5, -0.5].into(),
        [ 0.5, -0.5, -0.5].into(),
        [ 0.0,  0.5, -0.5].into(),
    ];
    let geometry = three::Geometry::with_vertices(vertices);
    let material = three::material::Basic {
        color: 0xFFFF00,
        .. Default::default()
    };
    let mesh = window.factory.mesh(geometry, material);
    window.scene.add(&mesh);

    let center = [0.0, 0.0];
    let yextent = 1.0;
    let zrange = -1.0 .. 1.0;
    let camera = window.factory.orthographic_camera(center, yextent, zrange);

    while window.update() {
        window.render(&camera);
    }
}

Highlighted features

Scene management

We use froggy to manage the scene heirarchy. three takes a slightly different approach to regular scene graphs whereby child objects keep their parents alive, opposed to parents keeping their children alive.

At the heart of the scene heirarchy is the object::Base type, which is a member of all three objects that are placeable in the scene.

All three objects are marked by the Object trait which provides the library with the object::Base type. Users may implement this trait in order to add their own structs into the scene heirarchy. Three-rs provides a helper macro three_object which provides a convenient way to implement Object for your types:

#[macro_use]
extern crate three;

use three::Object;

struct MyObject {
    group: three::Group,
}

three_object!(MyObject::group);

fn main() {
    // Initialization code omitted.
    let my_object = MyObject { group: window.factory.group() };
    window.scene.add(&my_object);
}

Multiple graphics pipelines

Graphics pipeline management is handled implicitly by three. The pipeline used to render a Mesh is chosen by its Material properties and the available vertex attributes from its Geometry.

The range of graphics pipelines available range from simple sprite rendering to physically based rendering.

3D format loading

glTF 2.0

three comes equipped with support for rendering and animating glTF scenes.

See Factory::load_gltf to get started.

Wavefront OBJ

For less complex meshes, three supports loading models in OBJ format.

See Factory::load_obj for more information.

Procedurally generated geometry

The Geometry struct leverages the genmesh crate to provide procedurally generated primtives such as cuboids, spheres, and cylinders. See the documentation on the Geometry struct for more information.

Modules

animation

Animation system.

audio

Primitives for audio playback.

camera

Cameras are used to view scenes from any point in the world.

color

sRGB colors.

controls

High-level input handling.

custom

Contains re-exports for custom pipeline state.

light

Contains different types of light sources.

material

Material parameters for mesh rendering.

object

Items in the scene heirarchy.

render

The renderer.

scene

Scene and SyncGuard structures.

skeleton

Mesh skinning.

template

Utilites for creating reusable templates for scene objects.

window

Primitives for creating and controlling Window.

Macros

three_object

Implements the following traits:

Structs

CubeMap

Cubemap is six textures useful for Cubemapping.

CubeMapPath

Represents paths to cube map texture, useful for loading CubeMap.

DynamicMesh

A dynamic version of a mesh allows changing the geometry on CPU side in order to animate the mesh.

Factory

Factory is used to instantiate game objects.

Font

Smart pointer containing a font to draw text.

Geometry

A collection of vertices, their normals, and faces that defines the shape of a polyhedral object.

Group

Groups are used to combine several other objects or groups to work with them as with a single entity.

Input

Controls user and system input from keyboard, mouse and system clock.

Joints

Properties for vertex skinning.

Mesh

Geometry with some Material.

Node

General information about an object in a scene.

Renderer

Renders Scene by Camera.

Sampler

The sampling properties for a Texture.

Scene

The root node of a tree of game objects that may be rendered by a Camera.

Shape

A geometry shape.

Sprite

Two-dimensional bitmap that is integrated into a larger scene.

Text

UI (on-screen) text. To use, create the new one using Factory::ui_text and add it to the scene using Scene::add.

Texture

An image applied (mapped) to the surface of a shape or polygon.

Timer

Timer can be used to find the time difference between the moment of timer creation and the moment of calling elapsed.

Transform

Position, rotation, and scale of the scene node.

Window

Window is the core entity of every three-rs application.

Enums

Align

Describes the horizontal alignment preference for positioning & bounds. See gfx_glyph::HorizontalAlign for more.

Background

Background type.

Button

Keyboard or mouse button.

FilterMethod

How to filter the texture when sampling. They correspond to increasing levels of quality, but also cost. Mipmap, trilinear and anisotropic filtering require mipmapping, but the other filtering methods do not.

Key

Symbolic name for a keyboard key.

Layout

Describes text alignment & wrapping. See gfx_glyph::Layout.

Local

Local space, defined relative to the parent node.

Material

Specifies the appearance of a Mesh.

MouseButton

Describes a button of a mouse controller.

World

World space, defined relative to the scene root.