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 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.
#[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); }
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 |
|
skeleton |
Mesh skinning. |
window |
Primitives for creating and controlling |
Structs
CubeMap |
Cubemap is six textures useful for
|
CubeMapPath |
Represents paths to cube map texture, useful for loading
|
DynamicMesh |
A dynamic version of a mesh allows changing the geometry on CPU side in order to animate the mesh. |
Factory |
|
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 | |
Node |
General information about scene |
Renderer | |
Sampler |
The sampling properties for a |
Scene |
The root node of a tree of game objects that may be rendered by a |
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 |
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 |
Transform |
Position, rotation, and scale of the scene node. |
Window |
|
Enums
Align |
Describes horizontal alignment preference for positioning & bounds.
See |
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 |
Local |
Local space, defined relative to the parent node. |
Material |
Specifies the appearance of a |
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 |
Constants
AXIS_DOWN_UP |
Axis for up and down arrow keys. |
AXIS_LEFT_RIGHT |
Axis for left and right arrow keys. |
KEY_ESCAPE |
|
KEY_SPACE |
|
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. |