Crate rin[][src]

Introduction

Installation

In order to use rin you'll need to install rust first: https://www.rust-lang.org

Once installed you can install rin's project generator running:

cargo install rinpg

To update to a new version later you can run:

cargo install --force rinpg

You can now create new rin projects by running from a console:

rin new project_path

Which will create a default empty project. Run rin with --help for more options.

Further install

Rust provides autocomplete and static analisys through the Rust Language Server https://github.com/rust-lang-nursery/rls

To install rls:

rustup update
rustup component add rls-preview rust-analysis rust-src

Now you can install any IDE with support for rls (usually through extensions) I've mostly tested rin with visual code and atom.

Basic example

After creating a new project with the rin tool you'll end up with something that should look like:

struct App{

}

impl App{
    pub fn new(_gl: &gl::Renderer, _window: &mut window::Window) -> App{
        App{}
    }
}

impl ApplicationCallbacks for App{
    fn update(&mut self, _delta: f64, _gl: &gl::Renderer, _window: &window::WindowT){

    }

    fn draw(&mut self, gl: &gl::Renderer, window: &window::WindowT){
        gl.clear_color(&BLACK);
        gl.clear_depth();
        let _gl = gl.with(Mvp::ortho_top_left(window.viewport()));

    }

    fn key_pressed(&mut self, _key: window::Key, _mods: window::KeyModifiers, _repeat: bool){

    }
    ...
}

If you've used other creative frameworks the above should result familiar with some differences mostly comming from rust's own syntax.

The most important parts in this template are:

gl.draw(&self.geometry);

Alternative template

Sometimes types in rust can be quite long and when using the above template you'll need to specify every type of variables that are created inside the App struct. For variables created inside functions you usually just use let as in:

let radius = 10.;
let resolution = 30;
let circle = graphics::circle(radius, resolution);

Also because rin tries not to have any global object or function call you'll need a reference to a renderer in order to draw or to a window in order to check things like it's size. Because of that some of the callbacks in the above template are sometimes not so useful.

Another way to use rin is to use the loop template by creating a new project with the following call:

rin new --loop project_path

Which will create an empty project that looks like:

fn main() {
    let events = window::EventsPoll::new().unwrap();
    let mut window = window::Builder::new(events.clone())
        .create()
        .unwrap();

    let gl = gl::Renderer::new(&mut window).unwrap();

    while !window.should_close(){
        let _delta = window.curr_frame_time_s();
        window.make_current();
        gl.clear_color(&BLACK);
        gl.clear_depth();
        let _gl = gl.with(Mvp::ortho_top_left(window.viewport()));

        // Your code goes here

        window.swap_buffers();
        events.poll_events();
        window.update();
    }
}

In this case the window and gl variables are always available and you can listen to whatever events you need by using the facilities in the events module. You can access window events by using Window::event_stream().

There's several ways to use events in rin but the most common is to get an iterator that we can later query for new events inside the application loop. As in:

let mouse_pressed = window.event_stream()
    .mouse()
    .pressed()
    .iter_async();

while !window.should_close(){
...

    for (pos, button, mods) in mouse_pressed.by_ref(){
        println!("pos {}", pos);
    }
}

Which prints every mouse press position that happened during the current frame.

Or for example:

let mouse_pressed = window.event_stream()
    .mouse()
    .moved()
    .iter_async();

while !window.should_close(){
...

    if let Some(pos) = mouse_pressed.by_ref().last(){
        println!("pos {}", pos);
    }
}

Which only prints the last position of the mouse during the current frame

This way of using rin also allows more control over the default loop by not hiding it away from the user and might become the default template in the future.

Learning rust

For more information on using rust, you can check the rust book https://doc.rust-lang.org/book/second-edition/

Examples

You can find examples on how to use rin at: https://...

API reference

Re-exports

pub extern crate seitan as events;
pub extern crate color;

Modules

app
gl
graphics
math
prelude

Prelude mod to make it easier to use rin, on applications import preamble like:

util
window

Macros

dont_time
from_c_str
geometry_cache
geometry_cache_per_vertex_type
image_cache
program_cache
time
time_ns
to_c_str

Structs

Error

Type Definitions

Result