kiss3d/
lib.rs

1/*!
2# Kiss3d
3
4Keep It Simple, Stupid 3d graphics engine.
5
6This library is born from the frustration in front of the fact that today's 3D
7graphics library are:
8
9* either too low level: you have to write your own shaders and opening a
10  window steals you 8 hours, 300 lines of code and 10L of coffee.
11* or high level but too hard to understand/use: those are libraries made to
12  write beautiful animations or games. They have a lot of feature; too much
13  feature if you only want to draw a few geometries on the screen.
14
15**kiss3d** is not designed to be feature-complete or fast.
16It is designed to be able to draw simple geometric figures and play with them
17with one-liners.
18
19An on-line version of this documentation is available [here](http://kiss3d.rs).
20
21## Features
22Most features are one-liners.
23
24* WASM compatibility.
25* open a window with a default arc-ball camera and a point light.
26* a first-person camera is available too and user-defined cameras are possible.
27* display boxes, spheres, cones, cylinders, quads and lines.
28* change an object color or texture.
29* change an object transform (we use the [glam](https://docs.rs/glam/) library
30  for math operations).
31* create basic post-processing effects.
32
33As an example, having a red, rotating cube with the light attached to the camera is as simple as:
34
35```no_run
36use kiss3d::prelude::*;
37
38#[kiss3d::main]
39async fn main() {
40    let mut window = Window::new("Kiss3d: cube").await;
41    let mut camera = OrbitCamera3d::default();
42    let mut scene = SceneNode3d::empty();
43
44    let mut c = scene.add_cube(1.0, 1.0, 1.0);
45    c.set_color(RED);
46
47    let rot = Quat::from_axis_angle(Vec3::Y, 0.014);
48
49    while window.render_3d(&mut scene, &mut camera).await {
50        c.rotate(rot);
51    }
52}
53```
54
55This code works on **both native platforms and WASM** without any changes! The `#[kiss3d::main]`
56macro and `async` rendering API handle the platform differences automatically:
57
58* **On native**: The async runtime is managed with `pollster::block_on`
59* **On WASM**: The async function integrates with the browser's event loop via `requestAnimationFrame`
60
61This approach eliminates the need for platform-specific code or managing different entry points,
62making it simple to write truly cross-platform 3D applications.
63
64Some controls are handled by default by the engine (they can be overridden by the user):
65
66* `scroll`: zoom in / zoom out.
67* `left click + drag`: look around.
68* `right click + drag`: translate the view point.
69* `enter`: look at the origin (0.0, 0.0, 0.0).
70
71## Compilation
72You will need the last stable build of the [rust compiler](http://www.rust-lang.org)
73and the official package manager: [cargo](https://github.com/rust-lang/cargo).
74
75Simply add the following to your `Cargo.toml` file:
76
77```text
78[dependencies]
79kiss3d = "0.36"
80```
81
82## Contributions
83I'd love to see people improving this library for their own needs. However, keep in mind that
84**kiss3d** is KISS. One-liner features (from the user point of view) are preferred.
85
86## Acknowledgements
87
88Thanks to all the Rustaceans for their help, and their OpenGL bindings.
89*/
90#![allow(non_upper_case_globals)]
91#![allow(unused_unsafe)] // TODO: should be denied
92#![allow(missing_copy_implementations)]
93#![doc(html_root_url = "http://kiss3d.rs/doc")]
94#![allow(clippy::module_inception)]
95#![allow(clippy::too_many_arguments)]
96#![allow(clippy::type_complexity)]
97
98#[macro_use]
99extern crate bitflags;
100extern crate num_traits as num;
101extern crate rusttype;
102#[cfg(feature = "serde")]
103extern crate serde;
104
105#[cfg(feature = "egui")]
106pub extern crate egui;
107
108pub use glamx;
109#[cfg(feature = "parry")]
110pub use parry3d;
111
112// Re-export the procedural macro and its runtime dependencies
113pub use kiss3d_macro::main;
114
115#[cfg(not(target_arch = "wasm32"))]
116#[doc(hidden)]
117pub use pollster;
118
119#[cfg(target_arch = "wasm32")]
120#[doc(hidden)]
121pub use wasm_bindgen_futures;
122
123#[deprecated(note = "Use the `renderer` module instead.")]
124pub use crate::renderer::point_renderer3d;
125
126pub mod builtin;
127pub mod camera;
128pub mod color;
129pub mod context;
130pub mod event;
131pub mod light;
132pub mod loader;
133pub mod post_processing;
134pub mod procedural;
135pub mod renderer;
136pub mod resource;
137pub mod scene;
138pub mod text;
139pub mod window;
140
141pub mod prelude {
142    pub use crate::builtin::*;
143    pub use crate::camera::*;
144    pub use crate::color::*;
145    pub use crate::context::*;
146    pub use crate::event::*;
147    pub use crate::light::*;
148    pub use crate::loader::*;
149    pub use crate::renderer::*;
150    pub use crate::resource::*;
151    pub use crate::scene::*;
152    pub use crate::text::*;
153    pub use crate::window::*;
154    pub use glamx::{
155        Mat2, Mat3, Pose2, Pose3, Quat, Rot2, Rot3, Vec2, Vec2Swizzles, Vec3, Vec3Swizzles,
156    };
157    pub use std::cell::RefCell;
158    pub use std::rc::Rc;
159}
kiss3d/lib.rs

kiss3d/
lib.rs
