Kiss3d - Keep it simple, stupid 3d graphics engine for Rust.

Sébastien Crozet

Last update: Dec 26, 2022

Related tags

Graphics kiss3d

Overview

Kiss3d

Keep It Simple, Stupid 3d graphics engine.

This library is born from the frustration that today’s 3D graphics library are either:

Too low level: you have to write your own shaders and opening a window takes 8 hours, 300 lines of code and 10L of coffee.
High level, but too hard to understand/use: these libraries are made to create beautiful photoreal (or close to it) animations or games. They have many features; too many, in fact, if you just want to draw a few objects on the screen with as little friction as possible.

kiss3d is not designed to be feature-complete or fast. It is designed to let you draw simple geometric figures and play with them with as little friction as possible.

An online version of this documentation is available here.

Features

WASM compatible.
Out of the box, open a window with a default arc-ball camera and a point light.
First-person camera available as well, and user-defined cameras are possible.
Render boxes, spheres, cones, cylinders, quads and lines simply
Change an object's color or texture.
Change an object's transform (we use nalgebra to do that).
Create basic post-processing effects.

As an example, creating a scene with a red, rotating cube with a light attached to the camera is as simple as (NOTE: this will not compile when targeting WASM):

extern crate kiss3d;
extern crate nalgebra as na;

use na::{Vector3, UnitQuaternion};
use kiss3d::window::Window;
use kiss3d::light::Light;

fn main() {
    let mut window = Window::new("Kiss3d: cube");
    let mut c      = window.add_cube(1.0, 1.0, 1.0);

    c.set_color(1.0, 0.0, 0.0);

    window.set_light(Light::StickToCamera);

    let rot = UnitQuaternion::from_axis_angle(&Vector3::y_axis(), 0.014);

    while window.render() {
        c.prepend_to_local_rotation(&rot);
    }
}

Making the same example compatible with both WASM and native platforms is slightly more complicated because kiss3d must control the render loop:

extern crate kiss3d;
extern crate nalgebra as na;

use kiss3d::light::Light;
use kiss3d::scene::SceneNode;
use kiss3d::window::{State, Window};
use na::{UnitQuaternion, Vector3};

struct AppState {
    c: SceneNode,
    rot: UnitQuaternion<f32>,
}

impl State for AppState {
    fn step(&mut self, _: &mut Window) {
        self.c.prepend_to_local_rotation(&self.rot)
    }
}

fn main() {
    let mut window = Window::new("Kiss3d: wasm example");
    let mut c = window.add_cube(1.0, 1.0, 1.0);

    c.set_color(1.0, 0.0, 0.0);

    window.set_light(Light::StickToCamera);

    let rot = UnitQuaternion::from_axis_angle(&Vector3::y_axis(), 0.014);
    let state = AppState { c, rot };

    window.render_loop(state)
}

Some controls are handled by default by the engine (they can be overridden by the user):

scroll: zoom in / zoom out.
left click + drag: look around.
right click + drag: translate the view point.
enter: look at the origin (0.0, 0.0, 0.0).

Compilation

You will need the last stable build of the rust compiler and the official package manager: cargo.

Simply add the following to your Cargo.toml file:

[dependencies]
kiss3d = "0.29"

Contributions

I’d love to see people improving this library for their own needs. However, keep in mind that kiss3d is KISS. One-liner features (from the user point of view) are preferred.

Acknowledgements

Thanks to all the Rustaceans for their help, and their OpenGL bindings.

Comments

Can't build with rust 0.10

Hi, I'm using the last stable rust release and getting this error after make:

> make
mkdir -p lib
rustc src/lib.rs --opt-level 3 --out-dir lib -Llib/glfw-rs/lib -Llib/gl-rs -Llib/nalgebra/lib -Llib/rust-stb-image/ -Llib/rust-freetype/
src/lib.rs:103:1: 103:19 error: can't find crate for `libc`
src/lib.rs:103 extern crate libc;
               ^~~~~~~~~~~~~~~~~~
error: aborting due to previous error
make: *** [all] Error 101

> rustc -v
rustc 0.10 (46867cc 2014-04-02 16:59:39 -0700)
host: i686-apple-darwin

opened by shirokoff 12

Bump nalgebra to a safe version

Hey,

This bumps version of nalgebra to new version which should be safe from https://github.com/dimforge/nalgebra/issues/883

I noticed issue mentioning that you don't have time to actively maintain this crate anymore so I figured I might save you some by just creating this PR myself even when it's a simple one.

I also saw that https://github.com/sebcrozet/kiss3d/pull/280 exists but it seems that it missed updating the dev-dependencies

Testing

Since this crate doesn't have many tests I tested it by running the examples to make sure they work. I did this on a linux machine but I think it's pretty safe to assume that it doesn't break anything on other platforms.

opened by dmweis 11
Improve webgl_canvas mouse event handling and fix mouse coordinates

A previous version of this PR narrowed the event listeners target, introduced the use of pointer events to enable pointer capturing via setPointerCapture and added some cleanup code. Following the comments, part of this PR was split into another PR #219. The current PR focuses on improving the mouse event handling without using pointer event.

opened by alvinhochun 8

0.28.0 broken on macOS

   Compiling kiss3d v0.28.0
error[E0432]: unresolved import `glutin::platform::unix`
  --> /Users/moritz/.cargo/registry/src/github.com-1ecc6299db9ec823/kiss3d-0.28.0/src/window/gl_canvas.rs:40:35
   |
40 |             use glutin::platform::unix::EventLoopExtUnix;
   |                                   ^^^^ could not find `unix` in `platform`

error[E0599]: no function or associated item named `new_any_thread` found for struct `EventLoop<_>` in the current scope
  --> /Users/moritz/.cargo/registry/src/github.com-1ecc6299db9ec823/kiss3d-0.28.0/src/window/gl_canvas.rs:41:24
   |
41 |             EventLoop::new_any_thread()
   |                        ^^^^^^^^^^^^^^ function or associated item not found in `EventLoop<_>`

error[E0308]: mismatched types
  --> /Users/moritz/.cargo/registry/src/github.com-1ecc6299db9ec823/kiss3d-0.28.0/src/window/gl_canvas.rs:79:13
   |
79 |             events,
   |             ^^^^^^ expected struct `EventLoop`, found struct `EventLoopWindowTarget`
   |
   = note: expected struct `EventLoop<()>`
              found struct `EventLoopWindowTarget<_>`

error: aborting due to 3 previous errors

opened by virtualritz 7

Switch to web-sys instead of stdweb.
It appears that stdweb is mostly dead so I would like to switch to web-sys/wasm-bindgen instead. This is a breaking change because:

This completely removes the stdweb dependency in favor of web-sys.

This uses glow instead of our generated webgl/opengl bindings.
opened by sebcrozet 7
Proof-of-concept of splitting Conrod UI into separate crate
I tried adding hooks for GUI support and splitting the Conrod UI integration code into a separate crate. The idea is that it might allow integration with other UI libraries to be written and that they can be conveniently plugged in. Here is a proof-of-concept.

I added a trait window::UiContext which replaces the existing ConrodContext struct inside kiss3d.

The actual Conrod code (including the ConrodContext struct and conrod_renderer) are moved to a separate crate kiss3d_conrod

This has the same name as the previously-vendored conrod_core crate. I figured that since it is no longer needed, perhaps the name can be reused?

In the non-generic version the UI as a field in Window has the type Option<Rc<RefCell<dyn UiContext>>>. ~~I have tried to make it the UiContext a generic parameter of Window (with a dummy context as default), but the generic parameter would leak into window::State~~ This is what it would look like if a generic parameter is used and I am not sure if it is really a good idea. What is your opinion @sebcrozet?

Run cargo run -p kiss3d_conrod --example ui to run the example.

(I might want to try implementing a UI integration with iced using this as a basis.)
opened by alvinhochun 7

window.rs:327:38: 327:67 error: mismatched types: expected `const std::os::raw::c_void`, found `const libc::c_void`

When attempting to build the readme sample (and installing opengl freeglut3-dev, and randr xorg-dev libglu1-mesa-dev) I'm getting this:

Executing: cargo build 
   Compiling kiss3d v0.1.4 (https://github.com/sebcrozet/kiss3d#98f00870)
~/.cargo/git/checkouts/kiss3d-fdfcc5cc23d2dd9f/master/src/window/window.rs:327:38: 327:67 error: mismatched types:
 expected `*const std::os::raw::c_void`,
    found `*const libc::c_void`
(expected enum `std::os::raw::c_void`,
    found enum `libc::c_void`) [E0308]
~/.cargo/git/checkouts/kiss3d-fdfcc5cc23d2dd9f/master/src/window/window.rs:327         verify!(gl::load_with(|name| window.get_proc_address(name)));
                                                                                                                              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~/.cargo/git/checkouts/kiss3d-fdfcc5cc23d2dd9f/master/src/window/window.rs:327:9: 327:70 note: in this expansion of verify! (defined in ~/.cargo/git/checkouts/kiss3d-fdfcc5cc23d2dd9f/master/src/error.rs)
~/.cargo/git/checkouts/kiss3d-fdfcc5cc23d2dd9f/master/src/window/window.rs:327:38: 327:67 help: run `rustc --explain E0308` to see a detailed explanation
error: aborting due to previous error
Could not compile `kiss3d`.

The readme says that the latest nightlies of rust are required, but that was edited a long time ago so is that still necessary?

opened by MrAndMrsK 7

Changing rotation (i.e. up-vector) of camera?

I cannot for the life of me figure out how to change the rotation of the camera. By rotation I mean rotation with respect to the direction the camera is pointing, i.e. changing the up vector, or, I think, the "roll" of the camera. Am I simply looking in the wrong places?

opened by Andlon 6

canvas: Force correct drop order when render_loop ends

First time contributing to this repo, lemme know if this PR is stylistically okay.

After switching my application to use the State-based setup (see examples/persistent_point_cloud.rs for an example), I would get errors when closing the window:

thread 'main' panicked at 'assertion failed: `(left == right)`
  left: `1282`,
 right: `0`', C:\Users\Henry\.cargo\registry\src\github.com-1ecc6299db9ec823\kiss3d-0.31.0\src\resource\effect.rs:93:12
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
thread 'main' panicked at 'assertion failed: `(left == right)`
  left: `1282`,
 right: `0`', C:\Users\Henry\.cargo\registry\src\github.com-1ecc6299db9ec823\kiss3d-0.31.0\src\resource\effect.rs:93:12
stack backtrace:
   0:     0x7ff64cfe157e - std::backtrace_rs::backtrace::dbghelp::trace
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\std\src\..\..\backtrace\src\backtrace\dbghelp.rs:98
   1:     0x7ff64cfe157e - std::backtrace_rs::backtrace::trace_unsynchronized
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\std\src\..\..\backtrace\src\backtrace\mod.rs:66
   2:     0x7ff64cfe157e - std::sys_common::backtrace::_print_fmt
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\std\src\sys_common\backtrace.rs:67
   3:     0x7ff64cfe157e - std::sys_common::backtrace::_print::{{impl}}::fmt
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\std\src\sys_common\backtrace.rs:46
   4:     0x7ff64cff626c - core::fmt::write
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\core\src\fmt\mod.rs:1092
   5:     0x7ff64cfdf068 - std::io::Write::write_fmt<std::sys::windows::stdio::Stderr>
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\std\src\io\mod.rs:1572
   6:     0x7ff64cfe402d - std::sys_common::backtrace::_print
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\std\src\sys_common\backtrace.rs:49
   7:     0x7ff64cfe402d - std::sys_common::backtrace::print
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\std\src\sys_common\backtrace.rs:36
   8:     0x7ff64cfe402d - std::panicking::default_hook::{{closure}}
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\std\src\panicking.rs:208
   9:     0x7ff64cfe3af9 - std::panicking::default_hook
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\std\src\panicking.rs:225
  10:     0x7ff64cfe46d3 - std::panicking::rust_panic_with_hook
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\std\src\panicking.rs:591
  11:     0x7ff64cfe4281 - std::panicking::begin_panic_handler::{{closure}}
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\std\src\panicking.rs:497
  12:     0x7ff64cfe1e9f - std::sys_common::backtrace::__rust_end_short_backtrace<closure-0,!>
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\std\src\sys_common\backtrace.rs:141
  13:     0x7ff64cfe41d9 - std::panicking::begin_panic_handler
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\std\src\panicking.rs:493
  14:     0x7ff64cffdbe0 - core::panicking::panic_fmt
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\core\src\panicking.rs:92
  15:     0x7ff64cff407a - core::fmt::Arguments::new_v1
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\core\src\fmt\mod.rs:314
  16:     0x7ff64cff407a - core::panicking::assert_failed::inner
                               at /rustc/9bc8c42bb2f19e745a63f3445f1ac248fb015e53\/library\core\src\panicking.rs:135
  17:     0x7ff64ceb84dd - core::panicking::assert_failed<u32,u32>
                               at C:\Users\Henry\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib\rustlib\src\rust\library\core\src\panicking.rs:143
  18:     0x7ff64cdf8782 - kiss3d::resource::effect::{{impl}}::drop
                               at C:\Users\Henry\.cargo\registry\src\github.com-1ecc6299db9ec823\kiss3d-0.31.0\src\resource\effect.rs:93
  19:     0x7ff64cd9ce4e - core::ptr::drop_in_place<kiss3d::resource::effect::Effect>
                               at C:\Users\Henry\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib\rustlib\src\rust\library\core\src\ptr\mod.rs:187
  20:     0x7ff64cd9d743 - core::ptr::drop_in_place<kiss3d::renderer::line_renderer::LineRenderer>

After enabling the logging in the glow crate, I found that the program for the LineRenderer object in my state was suddenly becoming invalid before I could call IsProgram and DeleteProgram on it. (Those are from the Drop impl for Effect.)

The issued turned out to be that we were dropping the window before the state, and since the window holds the OpenGL context, when we tried to drop the state, we got errors.

This diff introduces a new struct that enforces the proper drop order, and hides it behind a trait.

bug

opened by HenrySwanson 5

Add basic cubemap support.
While working on a game prototype using kiss3d, I realized one thing that was missing in the base library was cubemap/skybox support. I think adding support for this is generally useful for 3D prototyping, and if it's possible with a one liner, all the better.

Still TODO:

[ ] WASM support

[x] Make typesafe

[x] Internalize skybox material

[x] Benchmark startup time (not sure where this is coming from)

[x] Add skybox texture to demo (cat pictures are cute, but it really ought to demo how different sides can be shown)

[x] Docs
opened by charles-l 5
`Key::Return` event not getting through on Linux/KDE

I am running my code that works fine on macOS/Windows on a Kubuntu 22.04 under KDE and the Key::Return arm of my match never executes. All other key events in that code work as expected on that platform.

Is this a known issue?
bug

opened by virtualritz 0
Always enable optimizations on image loader

The examples that involve textures show a noticeable delay at start in dev mode; the delay is not there in release mode. I tracked this down to the image library. This commit changes the profile for the image library and the jpg and png decoding libraries to use optimizations and disable debug assertions.

opened by RaduBerinde 3
NormalsMaterial / UvsMaterial not working

I tried switching to NormalsMaterial or UvsMaterial and neither seems to be working (the shapes I apply the material to don't show up). I tried comparing the code to ObjectsMaterial and couldn't find anything materially different in the use of underlying APIs, so I don't know what's not working. Tried messing around with the shaders (eg to always show white) but still nothing shows up. I can create my own material (starting from ObjectsMaterial) and I can make it show normals or UVs and that works fine.

In any case, I think it would be worth it to have an example with all materials just so the code doesn't rot.
bug help wanted

opened by RaduBerinde 0
Document planar coordinate system

It's not very clear what coordinate system that planar coordinates use - i.e. what coordinates represent the corners of the window.

FixedView does not have any configuration parameters while Sidescroll only has a multiplier for zoom.

opened by ColonelThirtyTwo 1