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 asMesh
andCamera
. - The
Input
handles window events at a high-level. - The
Scene
is the root node of the component-graph system. - The
Renderer
renders theScene
from the view of aCamera
object.
Creating a basic mesh
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
Scene
and SyncGuard
structures.Macros
Structs
Cubemapping
.CubeMap
.Factory
is used to instantiate game objects.Texture
.Factory::ui_text
and add it to the scene using Scene::add
.elapsed
.Window
is the core entity of every three-rs
application.Enums
gfx_glyph::HorizontalAlign
for more.gfx_glyph::Layout
.[0, 1]
are handled.Constants
Escape
keyboard button.Space
keyboard button.