A Single Sprite

Awesome! Now we have an image rendering! That's not bad for very little code. Now let's try to render just a single sprite from our spritesheet instead of the entire thing.

The key line we're going to modify is this line in the render function:

canvas.copy(texture, None, None)?;

Let's look at the documentation of the copy() method to see what each of its arguments mean. It looks like in addition to a texture to copy, the functions takes two other arguments: src and dst. Both of these arguments take any type that implements Into<Option<Rect>>.

Aside: Parameters that implement Into<Option<Rect>>

If you haven't seen this pattern before, you should know that while this type looks complicated, it is actually designed to make your life a little easier.

The Option type implements From<T> for Option<T>. That means that instead of writing Some(value), you can write Option::from(value) or value.into() to convert a standalone value into an Option value.

This on its own isn't always useful, but when you use it in a function parameter's type, it can be very ergonomic:
fn foo<T>(x: T) where T: Into<Option<i32>> {}

// Both of these are equivalent:
foo(32);
foo(Some(32));

// And yet this also works because any type can be
// converted into itself (`None` is already `Option<i32>`):
foo(None);
This works because the implementation linked above lets 32 implement Into<Option<i32>> since 32.into() would give us an Option<i32> value.

Don't worry if this is a bit confusing! You don't need to understand all of this immediately. Just remember that 32, Some(32), and None can all be passed into a function whose type implements Into<Option<i32>>.

For our purposes, since we're looking at types that implement Into<Option<Rect>>, all that means is that we can pass a value of type Rect directly into these functions or pass None if we don't want to provide a value.

This pattern is a relatively easy way to implement optional/default arguments in Rust.

The src and dst parameters control where on the texture we copy from (the "source") and where in the window that part of the texture is copied to (the "destination"). We can use this to control what we draw and only copy a single sprite from the spritesheet.

The Rect type represents a rectangle. It has x and y fields that represent its top left corner and width and height fields that represent its dimensions. See its documentation for more information about its methods.

Let's use the Rect type to draw a single sprite in a fixed position. Replace the call to copy() in the render function with the following:

canvas.copy(texture, Rect::new(0, 0, 26, 36), Rect::new(0, 0, 26, 36))?;

You'll also need to add the import on line 5 to get Rect into scope.

Aside: Measuring rectangles in spritesheets

You may be wondering how we figured out the numbers to use in this call. Here are two different methods you can use:

A paint program (GIMP, Paint.NET, Photoshop, etc.)

Math!

A paint program Open the image and draw a rectangle with the rectangle select tool. This will usually bring up the dimensions and position of the rectangle in a toolbar somewhere. This usually works, but can be inaccurate because each sprite is not a rectangle. You have to guess some of the dimensions in order to get them right.

Math! With spritesheets, we know that they are usually organized in some kind of grid. That means we can use some simple multiplication and division to figure out the size and position of each sprite.

Our assets/bardo.png image is 312px by 288px. If we count the number of sprites in the rows and columns, we can see that the image fits approximately 12 columns and 8 rows. Dividing the dimensions by these numbers, we can see that each sprite fits into a 26px by 36px rectangle.
The top left sprite is in the box:
(x=0, y=0, width=26, height=36)
The second sprite in the top row is in the box:
(x=26, y=0, width=26, height=36)
The second sprite in the second row is in the box:
(x=26, y=36, width=26, height=36)
If we index the rows and columns starting at 0, the sprite in the ith column and jth row is in the box:
(x=i*26, y=j*36, width=26, height=36)

Trying this out should produce the following image:

Notice that we successfully rendered only a single sprite, but our sprite is stuck in the top-left corner. The reason for this is because in the screen coordinate system, (0,0) is the top-left corner of the window.

Key Concept: Screen coordinate system

The coordinate system on your screen is a little bit different than the Cartesian coordinate system you probably learned in school.

To start, the origin of the coordinate system (0, 0) is at the top-left corner of the screen/window. Given that, it doesn't really make sense to have the positive y-axis go up since pretty much all coordinates would be negative. Instead, the y-axis goes down the screen.

It's sometimes helpful to imagine this as a 2D array instead of a coordinate system. (0, 0) is the 0th row and the 0th column the 2D array of pixels on your screen. By that logic, the positive y-axis going downwards actually makes sense since we're talking about the row of a 2D array.

This diagram summarizes this concept:

Let's fix this by generalizing our code a bit to actually keep track of the current position and the current sprite that we want to render.

Tip: The copy_ex() method is an even more powerful version of copy(). It has more parameters for extra things you might want to do when you copy the image (e.g. flip horizontal, flip vertical, rotate, etc.). Our spritesheets are simple enough that we don't need to do this, but you should be aware of this function in case you ever need it.

The World Coordinate System

On line 51 and line 53 we define two new variables to keep track of the current position and sprite. We represent the position using the sdl2 Point type and the sprite as its rectangle on the spritesheet.

We can then pass these new variables into the render function and use them to figure out what to render.

This is where we get to decide on our world coordinate system. This is a game development term that refers to the coordinate system we want our position variable to reside in.

Why is this important? Well we could just start by using screen coordinates. Then, to position the sprite in the center of the window, we would need to put it at the point (window width / 2, window height / 2). This is fine initially, but what happens if the window is resized? Also, how do you represent coordinates outside the window boundaries? You also have to consider how your choice will affect any math you want to do later.

The reason we define a "world" coordinate system is because it's useful to decouple the coordinates of our sprites from the window. We can then translate the coordinates we store in our game into screen coordinates when we render.

For our game: we're going to keep the axes of our world coordinate system the same as the screen coordinate system. The positive x-axis will go to the right, and the positive y-axis will go down. The only adjustment we'll make is that we'll define the origin coordinate (0,0) as being the center of the window, regardless of the window's size. That means that our coordinates will stay consistent and predictable for any window dimensions.

World Coordinates to Screen Coordinates

Given the way we defined this coordinate system, it's very easy to convert from world coordinates to screen coordinates. We still need to get the size of the window as shown on line 20. We can then add half of each dimension to the position passed to render. If the position is (0,0), adding half of each dimension will make that position the center of the window. This is exactly what we want.

Another decision we've made in this code is that the player's position should represent the center of their sprite. Recall that the x and y fields of Rect represent its top-left corner. We can use the special Rect::from_center constructor to use the point we've calculated as the center of the destination rectangle.

When we copy the sprite to this destination rectangle, we finish drawing just the single sprite we wanted on the screen:

Exercise: Try playing with the value of the position variable and the sprite variable to see how their values affect the sprite that gets drawn on the screen.

File Changes
.gitignore
Cargo.toml
assets/bardo.png
assets/darkdimension.png
assets/reaper.png
src/main.rs

assets
src
- main.rs
.gitignore
Cargo.toml

+19 -3 src/main.rs

use sdl2::pixels::Color;
use sdl2::event::Event;
use sdl2::keyboard::Keycode;
use sdl2::render::{WindowCanvas, Texture};
use sdl2::rect::{Point, Rect};
// "self" imports the "image" module itself as well as everything else we listed
use sdl2::image::{self, LoadTexture, InitFlag};
use std::time::Duration;

fn render(canvas: &mut WindowCanvas, color: Color, texture: &Texture) -> Result<(), String> {
fn render(
    canvas: &mut WindowCanvas,
    color: Color,
    texture: &Texture,
    position: Point,
    sprite: Rect,
) -> Result<(), String> {
    canvas.set_draw_color(color);
    canvas.clear();

    canvas.copy(texture, None, None)?;
    let (width, height) = canvas.output_size()?;

    // Treat the center of the screen as the (0, 0) coordinate
    let screen_position = position + Point::new(width as i32 / 2, height as i32 / 2);
    let screen_rect = Rect::from_center(screen_position, sprite.width(), sprite.height());
    canvas.copy(texture, sprite, screen_rect)?;

    canvas.present();

    Ok(())
}

fn main() -> Result<(), String> {
    let sdl_context = sdl2::init()?;
    let video_subsystem = sdl_context.video()?;
    // Leading "_" tells Rust that this is an unused variable that we don't care about. It has to
    // stay unused because if we don't have any variable at all then Rust will treat it as a
    // temporary value and drop it right away!
    let _image_context = image::init(InitFlag::PNG | InitFlag::JPG)?;

    let window = video_subsystem.window("game tutorial", 800, 600)
        .position_centered()
        .build()
        .expect("could not initialize video subsystem");

    let mut canvas = window.into_canvas().build()
        .expect("could not make a canvas");

    let texture_creator = canvas.texture_creator();
    let texture = texture_creator.load_texture("assets/bardo.png")?;

    let position = Point::new(0, 0);
    // src position in the spritesheet
    let sprite = Rect::new(0, 0, 26, 36);

    let mut event_pump = sdl_context.event_pump()?;
    let mut i = 0;
    'running: loop {
        // Handle events
        for event in event_pump.poll_iter() {
            match event {
                Event::Quit {..} |
                Event::KeyDown { keycode: Some(Keycode::Escape), .. } => {
                    break 'running;
                },
                _ => {}
            }
        }

        // Update
        i = (i + 1) % 255;

        // Render
        render(&mut canvas, Color::RGB(i, 64, 255 - i), &texture)?;
        render(&mut canvas, Color::RGB(i, 64, 255 - i), &texture, position, sprite)?;

        // Time management!
        ::std::thread::sleep(Duration::new(0, 1_000_000_000u32 / 60));
    }

    Ok(())
}

+19 -3 src/main.rs

 
      use sdl2::pixels::Color;
 
      use sdl2::event::Event;
 
      use sdl2::keyboard::Keycode;
 
      use sdl2::render::{WindowCanvas, Texture};
+
      use sdl2::rect::{Point, Rect};
 
      // "self" imports the "image" module itself as well as everything else we listed
 
      use sdl2::image::{self, LoadTexture, InitFlag};
 
      use std::time::Duration;
-
      fn render(canvas: &mut WindowCanvas, color: Color, texture: &Texture) -> Result<(), String> {
+
      fn render(
+
          canvas: &mut WindowCanvas,
+
          color: Color,
+
          texture: &Texture,
+
          position: Point,
+
          sprite: Rect,
+
      ) -> Result<(), String> {
 
          canvas.set_draw_color(color);
 
          canvas.clear();
-
          canvas.copy(texture, None, None)?;
+
          let (width, height) = canvas.output_size()?;
+
          // Treat the center of the screen as the (0, 0) coordinate
+
          let screen_position = position + Point::new(width as i32 / 2, height as i32 / 2);
+
          let screen_rect = Rect::from_center(screen_position, sprite.width(), sprite.height());
+
          canvas.copy(texture, sprite, screen_rect)?;
 
          canvas.present();
 
          Ok(())
 
      }
 
      fn main() -> Result<(), String> {
 
          let sdl_context = sdl2::init()?;
 
          let video_subsystem = sdl_context.video()?;
 
          // Leading "_" tells Rust that this is an unused variable that we don't care about. It has to
 
          // stay unused because if we don't have any variable at all then Rust will treat it as a
 
          // temporary value and drop it right away!
 
          let _image_context = image::init(InitFlag::PNG | InitFlag::JPG)?;
 
          let window = video_subsystem.window("game tutorial", 800, 600)
 
              .position_centered()
 
              .build()
 
              .expect("could not initialize video subsystem");
 
          let mut canvas = window.into_canvas().build()
 
              .expect("could not make a canvas");
 
          let texture_creator = canvas.texture_creator();
 
          let texture = texture_creator.load_texture("assets/bardo.png")?;
+
          let position = Point::new(0, 0);
+
          // src position in the spritesheet
+
          let sprite = Rect::new(0, 0, 26, 36);
 
          let mut event_pump = sdl_context.event_pump()?;
 
          let mut i = 0;
 
          'running: loop {
 
              // Handle events
 
              for event in event_pump.poll_iter() {
 
                  match event {
 
                      Event::Quit {..} |
 
                      Event::KeyDown { keycode: Some(Keycode::Escape), .. } => {
 
                          break 'running;
 
                      },
 
                      _ => {}
 
                  }
 
              }
 
              // Update
 
              i = (i + 1) % 255;
 
              // Render
-
              render(&mut canvas, Color::RGB(i, 64, 255 - i), &texture)?;
+
              render(&mut canvas, Color::RGB(i, 64, 255 - i), &texture, position, sprite)?;
 
              // Time management!
 
              ::std::thread::sleep(Duration::new(0, 1_000_000_000u32 / 60));
 
          }
 
          Ok(())
 
      }

/target
**/*.rs.bk

[package]
name = "game-tutorial"
version = "0.1.0"
authors = ["Sunjay Varma <[email protected]>"]
edition = "2018"

[dependencies]

[dependencies.sdl2]
version = "0.32.1"
default-features = false
features = ["image"]

use sdl2::pixels::Color;
use sdl2::event::Event;
use sdl2::keyboard::Keycode;
use sdl2::render::{WindowCanvas, Texture};
use sdl2::rect::{Point, Rect};
// "self" imports the "image" module itself as well as everything else we listed
use sdl2::image::{self, LoadTexture, InitFlag};
use std::time::Duration;

fn render(
    canvas: &mut WindowCanvas,
    color: Color,
    texture: &Texture,
    position: Point,
    sprite: Rect,
) -> Result<(), String> {
    canvas.set_draw_color(color);
    canvas.clear();

    let (width, height) = canvas.output_size()?;

    // Treat the center of the screen as the (0, 0) coordinate
    let screen_position = position + Point::new(width as i32 / 2, height as i32 / 2);
    let screen_rect = Rect::from_center(screen_position, sprite.width(), sprite.height());
    canvas.copy(texture, sprite, screen_rect)?;

    canvas.present();

    Ok(())
}

fn main() -> Result<(), String> {
    let sdl_context = sdl2::init()?;
    let video_subsystem = sdl_context.video()?;
    // Leading "_" tells Rust that this is an unused variable that we don't care about. It has to
    // stay unused because if we don't have any variable at all then Rust will treat it as a
    // temporary value and drop it right away!
    let _image_context = image::init(InitFlag::PNG | InitFlag::JPG)?;

    let window = video_subsystem.window("game tutorial", 800, 600)
        .position_centered()
        .build()
        .expect("could not initialize video subsystem");

    let mut canvas = window.into_canvas().build()
        .expect("could not make a canvas");

    let texture_creator = canvas.texture_creator();
    let texture = texture_creator.load_texture("assets/bardo.png")?;

    let position = Point::new(0, 0);
    // src position in the spritesheet
    let sprite = Rect::new(0, 0, 26, 36);

    let mut event_pump = sdl_context.event_pump()?;
    let mut i = 0;
    'running: loop {
        // Handle events
        for event in event_pump.poll_iter() {
            match event {
                Event::Quit {..} |
                Event::KeyDown { keycode: Some(Keycode::Escape), .. } => {
                    break 'running;
                },
                _ => {}
            }
        }

        // Update
        i = (i + 1) % 255;

        // Render
        render(&mut canvas, Color::RGB(i, 64, 255 - i), &texture, position, sprite)?;

        // Time management!
        ::std::thread::sleep(Duration::new(0, 1_000_000_000u32 / 60));
    }

    Ok(())
}

1	1	`use sdl2::pixels::Color;`
2	2	`use sdl2::event::Event;`
3	3	`use sdl2::keyboard::Keycode;`
4	4	`use sdl2::render::{WindowCanvas, Texture};`
	5	`use sdl2::rect::{Point, Rect};`
5	6	`// "self" imports the "image" module itself as well as everything else we listed`
6	7	`use sdl2::image::{self, LoadTexture, InitFlag};`
7	8	`use std::time::Duration;`
8	9
9		`fn render(canvas: &mut WindowCanvas, color: Color, texture: &Texture) -> Result<(), String> {`
	10	`fn render(`
	11	`canvas: &mut WindowCanvas,`
	12	`color: Color,`
	13	`texture: &Texture,`
	14	`position: Point,`
	15	`sprite: Rect,`
	16	`) -> Result<(), String> {`
10	17	`canvas.set_draw_color(color);`
11	18	`canvas.clear();`
12	19
13		`canvas.copy(texture, None, None)?;`
	20	`let (width, height) = canvas.output_size()?;`
	21
	22	`// Treat the center of the screen as the (0, 0) coordinate`
	23	`let screen_position = position + Point::new(width as i32 / 2, height as i32 / 2);`
	24	`let screen_rect = Rect::from_center(screen_position, sprite.width(), sprite.height());`
	25	`canvas.copy(texture, sprite, screen_rect)?;`
14	26
15	27	`canvas.present();`
16	28
17	29	`Ok(())`
18	30	`}`
19	31
20	32	`fn main() -> Result<(), String> {`
21	33	`let sdl_context = sdl2::init()?;`
22	34	`let video_subsystem = sdl_context.video()?;`
23	35	`// Leading "_" tells Rust that this is an unused variable that we don't care about. It has to`
24	36	`// stay unused because if we don't have any variable at all then Rust will treat it as a`
25	37	`// temporary value and drop it right away!`
26	38	`let _image_context = image::init(InitFlag::PNG \| InitFlag::JPG)?;`
27	39
28	40	`let window = video_subsystem.window("game tutorial", 800, 600)`
29	41	`.position_centered()`
30	42	`.build()`
31	43	`.expect("could not initialize video subsystem");`
32	44
33	45	`let mut canvas = window.into_canvas().build()`
34	46	`.expect("could not make a canvas");`
35	47
36	48	`let texture_creator = canvas.texture_creator();`
37	49	`let texture = texture_creator.load_texture("assets/bardo.png")?;`
38	50
	51	`let position = Point::new(0, 0);`
	52	`// src position in the spritesheet`
	53	`let sprite = Rect::new(0, 0, 26, 36);`
	54
39	55	`let mut event_pump = sdl_context.event_pump()?;`
40	56	`let mut i = 0;`
41	57	`'running: loop {`
42	58	`// Handle events`
43	59	`for event in event_pump.poll_iter() {`
44	60	`match event {`
45	61	`Event::Quit {..} \|`
46	62	`Event::KeyDown { keycode: Some(Keycode::Escape), .. } => {`
47	63	`break 'running;`
48	64	`},`
49	65	`_ => {}`
50	66	`}`
51	67	`}`
52	68
53	69	`// Update`
54	70	`i = (i + 1) % 255;`
55	71
56	72	`// Render`
57		`render(&mut canvas, Color::RGB(i, 64, 255 - i), &texture)?;`
	73	`render(&mut canvas, Color::RGB(i, 64, 255 - i), &texture, position, sprite)?;`
58	74
59	75	`// Time management!`
60	76	`::std::thread::sleep(Duration::new(0, 1_000_000_000u32 / 60));`
61	77	`}`
62	78
63	79	`Ok(())`
64	80	`}`