Crate three [−] [src]

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.

#[macro_use]
extern crate three;

use three::Object;

struct MyObject {
    group: three::Group,
}

impl AsRef<three::object::Base> for MyObject {
    fn as_ref(&self) -> &three::object::Base {
        self.group.as_ref()
    }
}


impl Object for MyObject {}

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

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.
window	Primitives for creating and controlling `Window`.

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 scene `Node`.
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 horizontal alignment preference for positioning & bounds. See `gfx_glyph::HorizontalAlign` for more.
Background	Background type.
Button	Keyboard or mouse button.
CursorState	Describes how winit handles the cursor.
FilterMethod	How to filter the texture when sampling. They correspond to increasing levels of quality, but also cost. They "layer" on top of each other: it is not possible to have bilinear filtering without mipmapping, for example.
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.
WrapMode	Specifies how texture coordinates outside the range `[0, 1]` are handled.

Constants

AXIS_DOWN_UP	Axis for up and down arrow keys.
AXIS_LEFT_RIGHT	Axis for left and right arrow keys.
KEY_ESCAPE	`Escape` keyboard button.
KEY_SPACE	`Space` keyboard button.
MOUSE_LEFT	Left mouse button.
MOUSE_RIGHT	Right mouse button.

Traits

Object

Marks data structures that are able to added to the scene graph.

Type Definitions

Color

sRGB color represented by a 4-byte hexadecimal number.

Crate three [−] [src]

Getting Started

Creating a window

The four key structs

Creating a basic mesh

Managing the scene

Creating the game loop

Putting it all together

Highlighted features

Scene management

Multiple graphics pipelines

3D format loading

glTF 2.0

Wavefront OBJ

Procedurally generated geometry

Modules

Structs

Enums

Constants

Traits

Type Definitions