adi_screen tutorial 1: Open A Window

adi_screen 0.1.0

adi_screen allows you to render onto a screen ( Computer Monitor, Phone Screen, etc. ). This tutorial will go over everything you need to know to use adi_screen.

Tutorial #1: Open A Window

If you're on Windows, open Git Bash ( A Terminal ). If you're on Linux, open a terminal.

Create a project

In your terminal type, replacing project_name with the name of your project:

cargo new --bin project_name
cd project_name

Add adi_screen as a dependency

Edit the file Cargo.toml inside the folder titled project_name. It should look like this:

[package]
name = "project_name"
version = "0.1.0"
authors = ["Jeron Aldaron Lau <[email protected]>"]

[dependencies]

Add a line at the end of the file:

adi_screen = "0.1.0"

Now your file should look like this:

[package]
name = "project_name"
version = "0.1.0"
authors = ["Jeron Aldaron Lau <[email protected]>"]

[dependencies]
adi_screen = "0.1.0"

Simplest adi_screen program

You will need a window icon to create the window. Download an example from http://plopgrizzly.tech/en/create/logo.ppm. Make a folder titled res inside of src, and move logo.ppm into src/res/.

In the folder project_name, there is a folder titled src, and in src there is a file titled main.rs. Open project_name/src/main.rs in your favorite text editor. You will see:

fn main() {
     println!("Hello, world!");
}

Change the contents of the file to match the following:

extern crate adi_screen;

use adi_screen::{ Window, Input };

fn main() {
	let mut window = Window::create("project_name",
		include_bytes!("res/logo.ppm"), &[]);

	loop {
		match window.update() {
			Input::Back => break,
			_ => {},
		}
	}
}

Now, I will explain what it all means.

extern crate adi_screen;

In Rust, extern crate allows you to use functions and types from a specific crate, in this instance, we are using the crate adi_screen.

use adi_screen::{ Window, Input };

In Rust, use tells the compiler which functions and types you want to use from a specific crate. In this case, we want to use the types Window and Input from crate adi_screen.

fn main() {

Functions in Rust are declared with the fn keyword. The main function is a special one that automatically runs when the program starts.

	let mut window = Window::create("project_name",
		include_bytes!("res/logo.ppm"), &[]);

A lot of stuff is going on here! Firstly, let is a keyword in Rust that defines a variable. The mut that follows it declares the variable mutable ( that means you can change it's value in the future, it's the opposite of a constant ). So, let mut window declares a mutable variable named window.

The = or equals operator, sets a variable to a specific value. In this case, the value we're using is returned by a function call. The function create is implemented by the type Window. So, in order to create a window, we call Window::create(). Window::create() has 3 parameters: the first one is the title the window should have, the second one is the icon, and the third one is extra shaders.

The name must be enclosed in double quotes because "project_name" is a &str.

The logo is included using the include_bytes macro, which takes a file as a parameter and turns it into an array of bytes. The specified file is then included in the resulting binary executable file.

&[] is a reference to an empty array. The & specifies that it's a reference, and [] specifies an array, and since there is nothing in the brackets, it is an empty array.

	loop {

The loop keyword in Rust is equivalent to while true. Everything inside the curly brackets ({}) is executed in an infinite loop, until a break is called.

		match window.update() {

Two things are happening here. A match is a special keyword in Rust. The value following the keyword is compared with different possible values inside the curly brackets ({}). For whichever possibility matches the value, a specific code segment runs.

The value we are matching is the return value from window.update(). update is a function that is implemented by the type window. It's different from Window::create() because it requires a self parameter. If you know Java you can think of it as static versus non-static methods. The window.update() function redraws the window and has a built-in delay so that the program runs at 60 fps. It returns any user input or window event.

			Input::Back => break,
			_ => {},

This is the syntax for the inside of a match block. Input::Back represents an attempt to quit the program or "go back". window.update() will return Input::Back when the user hits the Escape Key or the X button on a window. The => separates the value we're matching to from the code segment. We have a very simple code segment for Input::Back events: break. This will break from the infinite loop and terminate the program.

The second line, instead of having a type of input has an underscore (_). In Rust, this represents all of the possible values that we have not covered ( which is a lot ). In such a case, we do nothing. Doing nothing is represented by an empty pair of curly brackets ({}).

Run the program!

Go back to your open terminal ( hopefully you didn't close it - if you did, type cd project_name and press enter). Now type the following command ( and memorize it - because you're going to need it ... a lot ):

cargo run

This will run your first adi_screen program!