Match3 on Jendrik Illner - 3D Programmer

Rust Game Series - Part 15 - Texture Pipeline and Pixel Perfect Rendering

Thu, 12 Nov 2020 04:00:00 +0000

In the last part of this series, I have discussed the DDS loader implementation. Now it’s time to build on this and actually start drawing some textures onto the screen.

Overview

In this part, I am going to discuss the following:

Asset pipeline setup
Texture loading integration
Debugging advice for Pixel-Perfect rendering
Game screen drawing

All assets for this game are from the kawaii cookie match 3 asset pack. I am very thankful that the author has given me permission to include parts of this art pack for the series.

Texture Pipeline

The Asset pack provides the source data SVGs, and the game will need to load them as DDS files.

The conversion could be done manually but I always want all my assets to be stored in source format and fully automate the pipeline of making the data game ready.

The Git repository only contains the game ready data and not the source data. The pipeline is fully included in GIT so the asset pack can be used as-is.

Pipeline Architecture

For my asset pipeline setup, I am using Ninja. It’s my favorite build system. It’s small, quick, and straightforward to use.

This texture pipeline is implemented as a 2-step process:

Export SVG to PNG
Compress PNG to DDS

Export PNG from SVG

Exporting PNG from the source SVG files is done using Inkscape

When opening the source SVG files, you will see the pieces laid out like this:

Each piece has a unique ID. This ID can be specified when doing an export, and inkspace will export that piece individually. Since the source data is resolution independent, we need to define the resolution we want to bake the results into a texture.

The export can be expressed in a straightforward form:


rule export_svg
  command = C:\Program Files\Inkscape\inkscape.com --export-dpi="48" --without-gui $in --export-png=$out --export-id="$export_id"

build tmp_data/textures/KawaiiCookieAssetPack/gameplay_background_tall.png: export_svg src_data/textures/KawaiiCookieAssetPack/SVGs/hud-pieces.svg
    export_id = g86363

build tmp_data/textures/KawaiiCookieAssetPack/gameplay_bottom_border.png: export_svg src_data/textures/KawaiiCookieAssetPack/SVGs/hud-pieces.svg
    export_id = g36017

First the export_svg rule is defined. A rule defines a command, which is what executable and the arguments that should be passed to execute the build step. Ninja contains support for build-in variables such as $in, $out, and custom variables such as $export_id.

The build line defines the output file on the left ($out), the rule in the middle, and the input file ($in) on the right. Additional arguments can be defined for each build step.

With this setup, Ninja can execute the build. The steps will run in parallel if possible and use incremental compilation.

Compress PNG to DDS

The resulting PNG file are compressed to DDS. For this the compression I use TexConv.

I have a slightly modified version that adds an additional -of command line option. It’s a small code change that allows exporting to a specified output file. This way the tool fits better into the Ninja design.

The small code change can be found in my fork.

For the Ninja setup the dds compression follows the same pattern.

rule convert_to_dds_bc1
  command = ../build_environment/directxtex/texconv.exe -f BC1_UNORM -m 1 -y -of $out $in

rule convert_to_dds_rgba8
  command = ../build_environment/directxtex/texconv.exe -f R8G8B8A8_UNORM_SRGB -m 1 -y -of $out $in 

build target_data/textures/KawaiiCookieAssetPack/gameplay_background_tall.dds: convert_to_dds_bc1   tmp_data/textures/KawaiiCookieAssetPack/gameplay_background_tall.png
build target_data/textures/KawaiiCookieAssetPack/gameplay_bottom_border.dds:   convert_to_dds_rgba8 tmp_data/textures/KawaiiCookieAssetPack/gameplay_bottom_border.png

Dependency tracking

With this setup, Ninja will detect that DDS compression input files are the SVG export output and will schedule them in the correct order. Next time the SVG file is changed, Ninja will detect the change, re-export the PNG, and recompress DDS’s output.

Rust Texture Setup

With all the textures exported into a game-ready format a few more steps are required to actually draw the textures as part of the game.

load the texture from the disk
create a D3D11 texture object
update shader to allow sampling from a shader
bind the texture view to the pipeline
issue the draw calls

Loading Textures

The first step is to load the texture data from the disk. In the previous part, I described my DDS parser design that accepts a slice of the data. The same process for loading data as described in part 6 for shader loading applies here as well.

The following helper function will read the file, parse the DDS header, and create the texture. No real error handling. If a texture is missing, this will panic and crash the process.

pub fn load_dds_from_file<'a>(
    filename: &str,
    device: &'a GraphicsDevice,
) -> Result<Texture<'a>, ()> {
    // load the texture data
    let data = std::fs::read(filename).unwrap();

    // parse the header
    let texture_load_result = dds_parser::parse_dds_header(&data).unwrap();

    create_texture(
        device,
        texture_load_result.desc,
        texture_load_result.subresources_data,
    )
}

Texture Interface

Each texture has an ID3D11Texture2D and a Shader Resource View (SRV) that allows it to be bound to the pipeline. Both the texture and the ShaderResourceView have lifetime annotations so that the lifetimes can be validated.


pub struct ShaderResourceView<'a> {
    pub native_view: &'a mut winapi::um::d3d11::ID3D11ShaderResourceView,
}

impl Drop for ShaderResourceView<'_> {
    fn drop(&mut self) {
        leak_check_release(self.native_view, 0, None);
    }
}

pub struct Texture<'a> {
    pub native_texture: &'a mut winapi::um::d3d11::ID3D11Texture2D,
    pub srv: ShaderResourceView<'a>,
}

impl Drop for Texture<'_> {
    fn drop(&mut self) {
        leak_check_release(self.native_texture, 0, None);
    }

Texture creation

Texture creation is shown below. It’s only calling the necessary D3D11 API calls. Same Rust patterns as discussed in previous parts apply here as well.


pub fn create_texture<'a>(
    device: &GraphicsDevice,
    texture_desc: D3D11_TEXTURE2D_DESC,
    subresources_data: Vec<D3D11_SUBRESOURCE_DATA>,
) -> Result<Texture<'a>, ()> {
    let mut texture: *mut winapi::um::d3d11::ID3D11Texture2D = std::ptr::null_mut();
    let mut texture_view: *mut winapi::um::d3d11::ID3D11ShaderResourceView = std::ptr::null_mut();

    unsafe {
        let hr =
            device
                .native
                .CreateTexture2D(&texture_desc, subresources_data.as_ptr(), &mut texture);

        if hr != S_OK {
            return Err(());
        }

        // create a resource view
        let hr = device.native.CreateShaderResourceView(
            texture as *mut winapi::um::d3d11::ID3D11Resource,
            std::ptr::null_mut(),
            &mut texture_view,
        );

        if hr != S_OK {
            return Err(());
        }
    }

    Ok(Texture {
        native_texture: unsafe { texture.as_mut().unwrap() },
        srv: ShaderResourceView {
            native_view: unsafe { texture_view.as_mut().unwrap() },
        },
    })
}

Drawing Pixel Perfect Textures

Now that we have the necessary functionality to load, we still need to draw the textures.

Coordinate system

I defined my “Game-Space,” aka World Space as

X-Axis: To the right Y-Axis: Going up

I want my sprites to be pixel-perfect and always be drawn aligned to the pixel grid. Therefore I decided to use pixels as my units.

There are a few articles on how to archive pixel perfect sprite rendering with Unity and UE4 but I could not find one if you are writing your own rendering logic.

The core of the solution is this. Each vertex needs to be aligned to a pixel on the output grid. For me, the solution is simple:


float4 TransformWorldToScreen(int2 world_space_pos)
{
    float2 screen_space_pos = float2(
        (world_space_pos.x / ScreenWidth) * 2 - 1,
        (world_space_pos.y / ScreenHeight) * 2 - 1);

    return float4(screen_space_pos, 0, 1);
}

world_space_pos is in pixels and, therefore, always aligned to the grid. If another unit is used, it’s essential to make sure that screen_space_pos always refers to positions aligned to the screen’s pixel grid.

Here are a few pointers on how to make sure your rendering is correct.

Debugging advice

Create a 64x64 black and white checkerboard.

Such as this:

Draw this texture onto a quad of the same size and use linear texture sampler.

With linear sampling, blending will occur between neighboring pixels if they are not perfectly aligned to the pixel grid. Doing this will highlight any errors that might occur in the calculation.

The result on screen should show the checkerboard pattern.

If you take a magnifying glass or enlarge this image, you should still see the checkerboard. Without any repeating or skipped pixels anywhere on your quads.

If the pattern turns into anything else, such as a gray quads. Something went wrong along the drawing pipeline

There can be a lot of reasons, you might be applying half a pixel offset, rounding incorrectly, projecion doesn’t match the windows size etc

Drawing the game

Now we have all the ingredients to draw the base of the game:

The state of the item grid is stored as a 2-dimensional array of booleans right now. 6 rows, each with 5 entries for each row


pub struct GameplayStateFrameData {
    // the state of the grid
    grid: [[bool; 5]; 6],
}

We can then use Rust iterators to iterate over the whole grid. With .enumerate() we get access to both the index and the value.

This is useful in a case like these where both the value and the index are required for the logic. In this example, the index is used to calculate the position. The boolean values decide the color of the quad.


for (y, row) in frame_params.grid.iter().enumerate() {
    for (x, column) in row.iter().enumerate() {
        let x_offset_in_pixels = (x * 91) as i32;
        let y_offset_in_pixels = (y * 91) as i32;

        // allocate the constants for this draw call
        let obj_alloc = HeapAlloc::new(
            GameSpaceQuadData {
                color: if !column {
                    Float4 {
                        x: 1.0,
                        y: 1.0,
                        z: 1.0,
                        a: 1.0,
                    }
                } else {
                    Float4 {
                        x: 0.0,
                        y: 1.0,
                        z: 0.0,
                        a: 1.0,
                    }
                },
                size_pixels: Int2 { x: 90, y: 90 },
                position_bottom_left: Int2 {
                    x: 45 + x_offset_in_pixels,
                    y: 960 - 330 + 45 - y_offset_in_pixels,
                },
            },
            gpu_heap_data,
            gpu_heap_state,
        );

        bind_constant(command_list, 0, &obj_alloc);

        draw_vertices(command_list, 4);
    }
}

With all this put together, we now have the drawing logic setup for the game. The game flow is in-place. We can swap between different game screens, react to player input, and draw the game world.

Next Part

The next part will be all about implementing the actual Match 3 mechanics.

The code is available on GitHub

Rust Game Series - Part 14 - DDS Parser

Tue, 15 Sep 2020 04:00:00 +0000

This is the first part about the texture loading implementation for the Match 3 game.

In this part, I am going to cover

Error Handling
Unit testing
Integration Testing
Development Only Dependencies
Parsing binary files

Lots to talk about, so let us get started.

Overview

Textures formats such as png and jpg are aimed at reducing size on disk. But GPUs cannot read these directly, and therefore texture data needs to be decompressed before they can be read.

Block compressed formats allow texture data to remain compressed at all times. This reduces memory usage and reduces memory bandwidth when accessing the textures; an example of a block compressed format is .dds

The process for loading DDS files can be broken down into 4 high-level steps.

Parse the DDS file and unpack the texture data
Create a D3D11 texture from the data parsed information
Update the shaders to enable reading from textures
Bind the texture to the pipeline

This blog post will only cover step 1 and 2

The .dds format is fundamentally quite simple, but the number of variations and exceptions makes it a tricky format to parse in practice.

For this example parser implementation, I will restrict myself to only what is required for the time being.

2D Textures only
BC1 to BC7 + uncompressed RGBA8

To learn more about the different BC formats, I recommend this article Understanding BCn Texture Compression Formats

Architecture

The DDS parser receives a binary blob of data, parses the necessary information, and fills out the D3D11 descriptors.

In Rust function terms, it looks like this:

pub struct ParsedTextureData {
    pub desc: D3D11_TEXTURE2D_DESC,
    pub subresources_data: Vec<D3D11_SUBRESOURCE_DATA>,
}

pub fn parse_dds_header(src_data: &[u8]) -> Result<ParsedTextureData, DdsParserError>

The function returns a Result<ParsedTextureData, DdsParserError>

Error handling

I tend to think about error handling in two distinct categories.

Unexpected Failure
Expected Failure

I prefer the program to panic and abandon the application for unexpected failure. These kinds of failures happen if the application enters a state that was never expected to happen.

I prefer to panic early so that the application crashes as soon as an invalid state is detected instead of causing more subtle and hard to debug problems.

For expected failure cases, Rust offers an excellent method build around Result. This type is used to represent a return value that can either contain a success or failure value.

parse_dds_header will return a DdsParserError in case of failure, and only if parsing was successful, the ParsedTextureData is returned.

Currently, the parser returns the following error codes.

pub enum DdsParserError {
    InvalidHeader(& 'static str),
    InvalidFlags(& 'static str),
    FormatNotSupported,
    ImageSizeNotMultipleOf4,
}

In my opinion, each function that can fail should return a unique error enum that lists all possible failure cases. This way, it’s apparent to the caller what kind of failures can be expected and can decide how to handle each possibility.

If you would like to learn more about Error Handling in Rust, look at this talk RustConf 2020 - Error handling Isn’t All About Errors by Jane Lusby.

Great talk; I disagree with Jane on the use of non_exhaustive however.

Rust enums need to be exhaustively matched by default (meaning all possible cases need to be handled). Therefore each addition of a new valie will also be a breaking API change.

If you have a custom error enum for each function, then introducing a new error value means the function has a new Expected Failure case that didn’t exist before.

This is a breaking API change and should force all users to think about how to handle the new failure case.

non_exhaustive hides the introduction of a new failure from the user. And a user might only detect that a new error was introduced when the error happens at runtime instead of seeing the new unhandled error case at compile time.

I don’t think that’s the right decision but decide that for yourself.

Testing

We had a look at the API and how to handle different failure cases. The API surface is minimal and makes for a great candidate to show two types of testing supported by Cargo.

Unit Testing
Integration Testing

Unit testing is a testing level where individual components of an application are tested in isolation with optimally no dependencies on other components.

Integration tests verify that the interactions of two or more components achieve the expected goal.

For this parser, the tests are as follows:

Unit Test: validate that the expected information is returned
Integration test: validate that the returned information also creates valid D3D11 texture

Unit Testing

Adding a Unit Tests to a Rust project is simple.

Just add the following code to any rust file, and you got yourself a Unit Test.

pub fn add_two(a: i32) -> i32 {
    a + 2
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_adds_two() {
        assert_eq!(4, add_two(2));
    }
}

Running cargo test will run all unit tests found in the current project.

The same concept in a more complete example from the parser is below.

#[test]
fn validate_texture_header_black_4x4_bc1() {
    let texture_header_ref = D3D11_TEXTURE2D_DESC {
        ...
    };

    let texture_data_desc = D3D11_SUBRESOURCE_DATA {
        pSysMem: std::ptr::null_mut(), // can't validate this, will be pointing into the dynamic memory adresse
        SysMemPitch: 8,                // 4x4 texture = 1 BC1 block = 8 bytes
        SysMemSlicePitch: 8,           // 1 block
    };

    let texture_load_result = parse_dds_header(paintnet::BLACK_4X4_BC1);

    assert_eq!(texture_load_result.is_ok(), true);

    let texture_header = texture_load_result.unwrap();

    validate_texture_header(&texture_header_ref, &texture_header.desc);

    // should contain one subresource
    assert_eq!(texture_header.subresources_data.len(), 1);

    assert_eq!(
        texture_data_desc.SysMemPitch,
        texture_header.subresources_data[0].SysMemPitch
    );
    assert_eq!(
        texture_data_desc.SysMemSlicePitch,
        texture_header.subresources_data[0].SysMemSlicePitch
    );
}

Firstly we define what values the D3D11 header is supposed to contain. We then use several assert_eq to validate that the parser’s values are what we expected.

One part that stands out is how the texture parsing is called.

let texture_load_result = parse_dds_header(paintnet::BLACK_4X4_BC1);

You might remember that the function accepts a slice to binary data as a parameter. But how do we get access to the data that contains the texture?

One option would be to load the file from disk. However, loading from disk can fail for several reasons. Instead of introducing opportunities for random failures, I am embedding the file directly into the unit test executable.

Rust provides a very convenient macro for this. This macro takes any file (path is relative to the current file) and will embed the binary data directly into the executable.

// embed the data we will be testing against
mod paintnet {
    pub static BLACK_4X4_BC1: &'static [u8; 136] =
        include_bytes!("../tests/data/paintnet/black_4x4_bc1.dds");
    pub static BLACK_4X4_MIPS_BC1: &'static [u8; 152] =
        include_bytes!("../tests/data/paintnet/black_4x4_mips_bc1.dds");
}

This is ideal for small binary files, such as the texture data used for the unit tests.

For the parser, I only used a unit test to get the first parsing logic verified but did all other testing using integration testing.

Integration Testing

The integration tests will verify that parsed texture information will create a valid texture. Valid in this context means that the D3D11 debug layer will not generate any warnings or errors.

It does not mean that the texture actually looks like we expect it. For example, if we are expecting all pixels to be black, but for some reason, they are red, these integration tests will not fail.

From a code perspective, integration tests look the same:

#[test]
fn load_and_create_black_4x4_bc1() {
    test_texture_load_and_creation2( paintnet::BLACK_4X4_BC1 );
}

#[test]
fn load_and_create_black_4x4_mips_bc1() {
    test_texture_load_and_creation2( paintnet::BLACK_4X4_MIPS_BC1 );
}

Integration tests are located in a separate directory from the code they are testing.

dds_parser
    - src/
        dds_parser_lib.lib // Unit tests
    - tests/
        dds_parser_integration_tests.lib // Integration tests

This also means integration tests are located in a separate module and are only allowed to call the public interface.

All integration tests for the parser call a single function with different binary data, as you saw above. The function implementation looks like below:

fn test_texture_load_and_creation(data: &[u8]) {
    let debug_device = true;
    let graphics_layer: GraphicsDeviceLayer =
        graphics_device::create_device_graphics_layer_headless(debug_device).unwrap();

    // parse the header
    let texture_load_result = dds_parser::parse_dds_header(&data).unwrap();

    let (_texture, _texture_view) = graphics_device::create_texture(
        &graphics_layer.device,
        texture_load_result.desc,
        texture_load_result.subresources_data,
    )
    .unwrap();
}

It’s a 3 step process.

Create the Graphics layer
Parse the DDS header information
pass the parsed data into the create_texture function

Every step is followed by an unwrap() call; this will ensure that if any of the steps fails, the integration test will also fail.

One beneficial aspect of the Rust testing framework is that we can also test for expected failures:

#[test]
#[should_panic(expected = r#"called `Result::unwrap()` on an `Err` value: InvalidDimensions"#)]
fn load_and_create_black_5x4_bc1() {
    test_texture_load_and_creation("paintnet/white_5x4_bc1.dds");
}

Here I tell Cargo that this test is expected to panic and that the panic message should contain a specified text. This is very useful to make sure that invalid data triggers the Expected Failure case you expected to happen.

I am verifying that the parser correctly detects textures that are not a multiple of the block size.

You might have noticed one problem with the integration test setup in terms of library dependencies. The integration tests are part of the dds_parser crate, and we are using the graphics_device crate for the integration tests.

I don’t really want to introduce a dependency on the graphics_device crate just to use it for integration tests.

But Cargo has a trick up its sleeve to deal with this situation.

Development Only Dependencies

These kinds of dependencies are used to specify dependencies that are only required for tests or benchmarks.

These are added to the cargo.toml, just like other dependencies.

[dev-dependencies]
graphics_device = { path = "../graphics_device" }

The difference is that these dependencies are not propagated to users of a crate.

In this case, using the dds_parser will not create a dependency on graphics_device. But all tests still have full access to all functionality of the graphics_device crate just as if it would be a regular dependency.

Reading binary files

After looking at testing, error handling strategy, and testing dependencies, we miss one crucial part. How to actually parse a .dds file.

This process is quite long; please have a look at dds_parser\src\dds_parser_lib.rs in the code provided on GitHub to see all the details.

I will provide an introduction to how I decided to approach parsing binary files using Rust without crates.

The DDS format is broken into distinct parts.

DWORD with value “DDS ” 0x20534444
DDS_HEADER
optionally: DDS_HEADER_DXT10
BYTES (main surface data)

The file starts with a DWORD that contains a “magic value”. This concept can be found in many file formats and is an easy way to detect if the data provided could be a valid DDS file.

A DWORD refers to a double word, or also known as 32-bit unsigned integer.

This is the start of the parser:

pub fn parse_dds_header(src_data: &[u8]) -> Result<ParsedTextureData, DdsParserError> {

    // a valid DDS file needs at least 128 bytes to store the DDS dword and DDS_HEADER
    // if the file is smaller it cannot be a valid file
    if src_data.len() < 128 {
        return Err(DdsParserError::InvalidHeader("smaller than 128 bytes"));
    }

    let mut file_cursor = 0;

    // DDS files are expected to start with "DDS " = 0x20534444
    // if this is not the case the file is not a valid DDS file
    // try_into could panic if src_data is too short
    // but we checked the data length before
    let dw_magic: u32 =
        u32::from_le_bytes(src_data[file_cursor..(file_cursor + 4)].try_into().unwrap());
    file_cursor += 4;

    if dw_magic != 0x2053_4444 {
        return Err(DdsParserError::InvalidHeader(
            "file is missing DDS DWORD at start of the file",
        ));
    }

First, we validate that the file is large enough to store the minimum information required. If the file is smaller, it cannot be a valid DDS file, and we return an error code to indicate this.

Then we parse the magic dword that is expected to be at the start of the file. Rust provides a few functions to enable parsing for primitive types such as u32.

from_le_bytes(bytes: [u8; 4]) -> u32

This function accepts a slice of 4 bytes and returns a u32. The _le refers to little-endian byte order as opposed to big-endian. Refer to for the difference

But how do we convert a slice of unknown length into a fixed-length slice? The way to achieve this might not be immediately apparent.

The solution is this:

let u32slice : [u8;4] = src_data[0..4].try_into().unwrap()

But how did I end up with this?

The first apparent thing to try would be

let u32slice : [u8;4] = src_data[0..4]

I did this and expected it to work because clearly, we know these are 4 entries, and the compiler should figure this out too.

So let us try this and see what the compiler thinks:

1>49 | let u32slice : [u8;4] = src_data[0..4];
1>   |                ------   ^^^^^^^^^^^^^^ expected array `[u8; 4]`, found slice `[u8]`

But it’s not so easy. This will only work if we are 100% sure that the slice is at least 4 u8 entries long. We cannot guarantee this since src_data: &[u8] is of unknown length.

So what can we do instead?

1>49 | let u32slice : [u8;4] = src_data[0..4].try_into();
1>   |                ------   ^^^^^^^^^^^^^^^^^^^^^^^^^ expected array `[u8; 4]`, found enum `std::result::Result`

Ok, we are getting closer. TryInto is a trait that allows types to be converted into another type. These support conversions that might fail or could be expensive.

As you can see above, try_into returns a Result. So we should handle the failure condition.

let u32slice : [u8;4] = src_data[0..4].try_into().unwrap()

In the parser, I use unwrap() on the result. This call could fail if the slice doesn’t contain enough bytes for the requested range. But we covered this case with an earlier if that validates that we have at least 128 bytes of data.

With this slice, we can now parse the data.

let dw_magic: u32 =
        u32::from_le_bytes(u32slice);

if dw_magic != 0x2053_4444 {
        return Err(DdsParserError::InvalidHeader);
    }

And with that, we have done all the necessary parsing steps to parse a u32 value from a binary file.

If you had a look at the code on GitHub, you would see the line looks slightly different.

src_data[file_cursor..(file_cursor + 4)].try_into().unwrap()

What is file_cursor?

I tend to use a single variable to store how many bytes have been parsed and make all parsing operations relative to the file’s progress.

This makes the parser easier to read, and it also makes it possible to do a quick sanity check at the end of the parser.

// all data needs to be used, otherwise therer was a problem with parsing
assert!(file_cursor == src_data.len());

If we reached the parsing logic’s end, we should have parsed each byte in the file. If not, there might be a bug in the parsing logic, or the file contains sections that we didn’t process.

This is an unexpected failure case, better to fail early, and let us know we have a problem with the parser logic. If you expect your parser to be used on untrusted data, you might want to make this an expected failure case instead.

With this, we have seen the core of the parsing logic; the same idea is applied to many more entries in the DDS file.

If you are interested in the DDS specifics, look at the Github code, and if you have any questions, feel free to comment below or send me a message.

Next Part

It’s all good, we seem to be able to load D3D11 textures, but we will not be sure that they actually work until we have seen them.

So how do we render the textures on the screen?

That’s a topic for the next post :)

The code is available on GitHub

Rust Game Series - Part 13 - Modules

Wed, 20 May 2020 04:00:00 +0000

Goal

At the end of this post, the game state management will be separated into multiple files. The Rust module system is taken advantage of to further separate public interfaces from implementation details.

Overview

Right now, the functionality for both supported game states (Pause and Gameplay) is contained in main.rs and caused this file to grow to an unwieldy 500+ lines.

It’s time to split this file up. The two options are modules in separate files or crates. For this purpose, I think crates are overkill, and I will be moving it into a hierarchy of modules.

Hierarchy of modules

In Rust, each file implicitly defines a module of the same name as the file. Adding a file called pause.rs, for example, will create a pause module. Files structured in a hierarchy will also define a hierarchical module structure.

With this in mind the file structure I decided on:

src/
  main.rs
  gamestates.rs
  gamestates/
    pause.rs
    gameplay.rs

Therefore the pause state functionality will be found in gamestates::pause

and the gameplay in gamestates::gameplay

The gamestates.rs and the folder gamestates belong together. This is one of the two option to define the root of a module.

There is another option using a file called mod.rs such as this:

src/
  main.rs
  gamestates/
    pause.rs
    gameplay.rs
    mod.rs

This was the only way until Rust 2018, but I prefer the new way because it makes it easier to search for a file by name.

Imaging your project grows, and you might have a lot of modules and therefore, a lot of files called mod.rs. This sounds like a nightmare to find to me.

But what is the purpose of mod.rs or gamestates.rs?

For a module to be included in the compilation, it needs to be referenced. This is done using the mod keyword. I like to put these at the top of the files, so it’s easy to see.

// these make sure we compile the modules
mod gamestates;

This statement will cause the gamestates module to be compiled for the current compilation unit. gamestates.rs then list all the modules that will be included in the compilation if gamestates is requested.

// compile all the game states
mod gameplay;
mod pause;

Additionally, you might include functionality in this file that connects the pieces of the child modules together. I am doing that, more on that later.

For now, we only have created the file structure but not moved any code around.

Moving code into modules

With the file structure created we can copy all the PauseState related functionality into pause.rs. Only doing that is, of course, not enough. A lot of errors along these lines are greeting me.

error[E0425]: cannot find function `create_pso` in this scope
--> match3_game\src\gamestates\pause.rs:13:66
|
|         let screen_space_quad_blended_pso: PipelineStateObject = create_pso(
|                                                                  ^^^^^^^^^^ not found in this scope
| help: possible candidate is found in another module, you can import it into scope
|
| use graphics_device::create_pso;

The compiler is very helpful and tells you quite detailed what the problem is. By default, we can only access functions, structs, … that are defined in the same module.

If we want to access these elements, we need to explicitly opt-in. And the compiler error shows one of the possible ways to resolve it.

If you are using the Rust extension for Visual Studio it will provide you a quick fix for this error:

There are multiple ways to achieve this, see the rust book for more details.

But the TLDR version is:

If we have multiple imports from the same module, we can group them

// instead of listing them individually
use graphics_device::create_pso;
use graphics_device::create_texture;

// grouped imports from graphics_device module
use graphics_device::{create_pso, create_texture};

To reference something one level above us in the hierarchy use

use super::GameStateType

To reference something defined in the root of the crate use

use crate::Float2;

Having fixed up all the missing references, we are greeted with a new error from main.rs

use crate::pause::PauseStateStaticData;
                   ^^^^^^^^^^^^^^^^^^^^ this struct is private

The reason for this is that by default, all types in Rust are private. They can only be accessed from the current module. We need explicitly annotate all types and functions that we would like to access from outside the module.

This can be done like below:

pub struct PauseStateFrameData {
    fade_in_status: f32,
}

impl PauseState<'_> {
    pub fn new<'a>(device_layer: &GraphicsDeviceLayer) -> PauseState<'a> { ... }
}

pub fn draw_pause_state( ... )

Small gotcha, the impl cannot have a pub modifier.

We will need to expose all public types that are used directly or are used in a public interface. If we don’t we get errors like these:

error[E0446]: private type `UpdateBehaviourDesc` in public interface
   --> match3_game\src\pause.rs:68:1
    |
68  | / pub fn update_pause_state(
69  | |     prev_frame_params: &PauseStateFrameData,
70  | |     frame_params: &mut PauseStateFrameData,
71  | |     messages: &Vec<WindowMessages>,
...   |
93  | |     }
94  | | }
    | |_^ can't leak private type

The error message is, once again, very clear about the problem. update_pause_state has been made public but it uses the private type UpdateBehaviourDesc in the public interface (return type in this case)

Therefore we need to make that type public too. This only makes the type public but not the members themselves. So you don’t need to worry about outside code modifying members directly.

Once all these errors are fixed, the game should still run and look exactly the same. Just the code is easier to manage :)

Structure Changes

Furthermore, I decided to move all the game state related logic out of the main game loop. The logic for switching states, updating and drawing states makes it more challenging to see the core of the main game loop.

Gamestates.rs is the root of the module and is, therefore, the perfect place to implement such functionality. It provides the interface between the game and the game states.

It contains the types:

pub enum GameStateType {
    Pause,
    Gameplay,
}

pub enum GameStateTransitionState {
    Unchanged,
    TransitionToNewState(GameStateType),
    ReturnToPreviousState,
}

...

And functions such as these:

pub fn execute_possible_state_transition(
    state_transition: GameStateTransitionState,
    game_state_stack: &mut Vec<GameStateData>,
    graphics_layer: &GraphicsDeviceLayer,
) {

One part to point out for this function is that the ownership of state_transition is moved into execute_possible_state_transition and not passed as a reference like all other arguments.

GameStateTransitionState is used to track how the game states should be updated. Either we can keep the state unchanged, add a new state, or remove game states.

Since execute_possible_state_transition will do this transition internally the state_transition we pass in will not be valid after the function returns. Moving ownership into the function makes the original variable unusable, and Rust will throw an error if we forget to reset it afterward

115 |     let mut next_game_state: GameStateTransitionState =
    |         ------------------- move occurs because `next_game_state` has type `gamestates::GameStateTransitionState`, which does not implement the `Copy` trait
...
142 |         execute_possible_state_transition( next_game_state, &mut game_state_stack, &graphics_layer );
    |                                            ^^^^^^^^^^^^^^^ value moved here, in previous iteration of loop

This error is not super clear to read at first, but the simplified logic is below.

let mut next_game_state: GameStateTransitionState =
        GameStateTransitionState::TransitionToNewState(GameStateType::Gameplay);

while !should_game_close {
  execute_possible_state_transition(next_game_state, &mut game_state_stack, &graphics_layer);

  // from now on next_game_state is invalid and cannot be acessed
}

next_game_state is defined before we enter the main loop. Inside of the loop we move the next_game_state ownership into the execute_possible_state_transition function.

Once this function returns, the original variable cannot be accessed anymore. Since it lost the ownership of the value.

The fix for this is quite simple:

execute_possible_state_transition(next_game_state, &mut game_state_stack, &graphics_layer);
// assign a new value to next_game_state
// therefore we can access it again in the next iteration of the loop
next_game_state = GameStateTransitionState::Unchanged;

I like code being explicit and straightforward, and this clearly shows while scanning the code that the state transition state will be reset after execute_possible_state_transition returns.

If we passed it by reference, Rust compiler would not warn, and we might forget to reset the variable. Causing a run-time logic error instead of a compile-time error.

And that’s it for now. Main.rs is back to ~200 lines of code. There is more that could be moved around, but I will do that another time when I have a better idea of how the design will evolve.

Next Part

It seems like it’s time for some more exciting visuals. Going to implement texture loading support next.

The code is available on GitHub

Rust Game Series - Part 12 - Game States

Mon, 11 May 2020 04:00:00 +0000

Goal

At the end of this part, I will have a small prototype. This prototype contains the general game state flow between Gameplay and Pause State. The gameplay state is rendering a grid and reacting to mouse clicks.

Overview

I like to keep the states of the game to be independent of each other. Therefore I am going to focus on the foundation of the state management system before adding actual gameplay functionality.

All states are managed as a stack. This allows states like the Pause screen to be used for multiple use-cases. Only the pause state needs to be removed from the stack to return to the previous state.

Game State Data Model

Each Game State has 2 lifetimes: Static and Frame

[StaticData]

[FrameData][FrameData]

There is a single copy of static data for each GameState. And two copies of FrameData since I am using a double buffering scheme.

Static Data

Static data is created once and cannot be modified after. This stores information such as PSOs, textures, and other read-only data.

Frame Data

The frame data stores all dynamic information about the state. This includes information like player score, state of the game world, etc.

The update logic will get a read-only view of the previous frame state. It’s expected to read the last state frame as input and generate a new data into the output frame data.

For this game, I am trying not to in-place modify the game state. Let’s see how this goes :)

Game State API

The core of the API are two enums:

pub enum GameStateType {
    //MainMenu,
    Pause,
    Gameplay,
}

enum GameStateData<'a> {
    Gameplay(GameplayState<'a>),
    Pause(PauseState<'a>),
}

And the types being defined like this

struct GameplayState {
    static_data: GameplayStateStaticData,
    frame_data0: GameplayStateFrameData,
    frame_data1: GameplayStateFrameData,
}

I would have liked to store the GameplayStateFrameData as an array, but sadly Rust doesn’t allow borrowing of individual array entries in a natural way.

There are ways of doing it using iterators and/or slices. But for this use case, two variables will work just fine.

These GameStateData blocks are stored in a simple Vec to form a stack:

 let mut game_state_stack: Vec<GameStateData> = Vec::new();

The state transition are yet another enum, you see I love Rust enums :P This controls which state to switch and how that state switch should happen


pub enum GameStateTransitionState {
    Unchanged,
    TransitionToNewState(GameStateType),
    ReturnToPreviousState,
}

let mut next_game_state: GameStateTransitionState =
    GameStateTransitionState::TransitionToNewState(GameStateType::Gameplay);

Game state transitions always happen at the beginning of a CPU frame, and the GameState update returns a value specifying if and how state transitions should be done.

match next_game_state {
    GameStateTransitionState::TransitionToNewState(x) => {
        match x {
            GameStateType::Gameplay => {
                game_state_stack.push(GameStateData::Gameplay(GameplayState::new(&graphics_layer)));
            }

            GameStateType::Pause => {
                game_state_stack.push(GameStateData::Pause(PauseState::new(&graphics_layer)));
            }
        }

        // make sure to reset the state
        next_game_state = GameStateTransitionState::Unchanged;
    }

    GameStateTransitionState::ReturnToPreviousState => {
        // remove the top most state from the stack
        game_state_stack.pop();

        // close the game once all game states have been deleted
        if game_state_stack.len() == 0 {
            should_game_close = true;
            continue;
        }

        // make sure to reset the transition state
        next_game_state = GameStateTransitionState::Unchanged;
    }

    GameStateTransitionState::Unchanged => { }
}

With this, we have the main transition logic in-place and only miss the logic to draw and update the game states.

Updating is done in reverse order, this allows higher-level states to block input from reaching lower levels. Each state atm returns if a state transition is required and if the input should be blocked from reaching lower levels.

for state in game_state_stack.iter_mut().rev() {
    let state_status = match state {
        GameStateData::Gameplay(game_state) => {
            let (prev_frame_params, frame_params) = if update_frame_number % 2 == 0 {
                (&game_state.frame_data0, &mut game_state.frame_data1)
            } else {
                (&game_state.frame_data1, &mut game_state.frame_data0)
            };

            update_gameplay_state(prev_frame_params, frame_params, &messages, dt)
        }

        GameStateData::Pause(game_state) => {
            let (prev_frame_params, frame_params) = if update_frame_number % 2 == 0 {
                (&game_state.frame_data0, &mut game_state.frame_data1)
            } else {
                (&game_state.frame_data1, &mut game_state.frame_data0)
            };

            update_pause_state(prev_frame_params, frame_params, &messages, dt)
        }
    };

    if state_status.block_input {
        messages.clear();
    }

    match state_status.transition_state {
        GameStateTransitionState::Unchanged => {}
        _ => match next_game_state {
            GameStateTransitionState::Unchanged => {
                next_game_state = state_status.transition_state;
            }
            _ => {
                panic!("logic error, only one state transition per frame is allowed");
            }
        },
    }
}

The drawing follows the same logic, but the drawing order is from back to front. This allows higher-level states, such as the pause state, to be drawn on top of the lower states.

Rendering Update

A few updates on the rendering side:

The PSO state has been extended to contain the blend state, this is required so that the pause state can draw a partially transparent overlay
The grid is using the same shader as before. Drawing a quad for each tile. Good enough for now
The Window API was updated so that the output size of the Window can be specified when creating the Window

Next Part

Time to focus a little on code structure again. With all this logic, we are back >600 lines of Rust code in a single file.

Time to split it into multiple modules across different files.

The code is available on GitHub

Rust Game Series - Part 11 - Mouse Input

Wed, 22 Apr 2020 04:00:00 +0000

Goal

At the end of this part, we will have the necessary support to receive mouse input in the Game.

Overview

The task can be split into three parts:

Receive Mouse input from Win32
Convert mouse input into a Rust format and pass this to the Game
React to the mouse input in the Game code

Implementation

Processing mouse input on Windows is fundamentally quite simple. They use the same windows message loop I am already using to process window messages.

For Mouse input, I am going to handle these three events: WM_MOUSEMOVE, WM_LBUTTONDOWN, WM_LBUTTONUP

Each time the mouse will be moved over the window a WM_MOUSEMOVE is sent. We unpack the arguments and send them to the game layer for further processing.

if msg == WM_MOUSEMOVE {
    // retrieve the window state
    let window_state_ptr = GetWindowLongPtrW(h_wnd, GWLP_USERDATA) as *mut WindowThreadState;
    let window_state: &mut WindowThreadState = window_state_ptr.as_mut().unwrap();

    // unpack the arguments of the event
    // the position is stored in l_param
    let x = winapi::shared::windowsx::GET_X_LPARAM(l_param);
    let y = winapi::shared::windowsx::GET_Y_LPARAM(l_param);

    // and send a message to the Rust message processor
    window_state
        .message_sender
        .send(WindowMessages::MousePositionChanged(
            MousePositionChangedData { x, y },
        ))
        .unwrap();
}

The functionality for WM_LBUTTONDOWN and WM_LBUTTONUP is even more straightforward as there are no arguments to unpack, and we only need to send a message.

To make this all work, we need to extend the WindowMessages enum. I really love the flexibility of Rust enums btw :)

pub struct MousePositionChangedData {
    pub x: i32,
    pub y: i32,
}

pub enum WindowMessages {
    // mouse related messages
    MousePositionChanged(MousePositionChangedData),
    MouseLeftButtonDown,
    MouseLeftButtonUp,

    // window related messages
    WindowCreated(WindowCreatedData),
    WindowClosed,
}

With this functionalliy added we will be greeted with a new compiler error:

error[E0004]: non-exhaustive patterns: `MousePositionChanged(_)`, `MouseLeftButtonDown` and `MouseLeftButtonUp` not covered

All enum handling by default needs to be exhaustive. Meaning all possible cases need to be handled.

This is really useful as each time a new enum is added, the compiler will emit an error until we investigated each use case of the events.

For now, I will just print the information to the console. Responding to the input will be done in a later part.

 match x {
    WindowMessages::MousePositionChanged(pos) => {
        println!("cursor position changed: x {0}, y {1}", pos.x, pos.y);
    }

    WindowMessages::MouseLeftButtonDown => {
        println!("mouse:left down");
    }

    WindowMessages::MouseLeftButtonUp => {
        println!("mouse:left up");
    }

This is all we need to implement input processing. Well, there is one more small part to deal with. Testing the application like this, we will notice an issue.

Messages are only sent while the mouse is hovering over the window, and that can be a problem.

For example, if the user presses the left mouse button while insider the window, moves the mouse out of the window and releases the mouse. We will never receive a WM_LBUTTONUP event, and the Game might think the mouse button is still pressed.

To deal with this, I am extending the messages with two more cases: MouseFocusGained and MouseFocusLost When the mouse is moved outside of the window, I will send a MouseFocusLost to the Game, and the Game can react to it appropriatly.

To enable this, I will be using the win32 function TrackMouseEvent The following code needs to be added to the WM_MOUSEMOVE event. Telling windows, we would like to receive additional mouse tracking events.

Additionally, I am also sending a MouseFocusGained to make the API symmetrical with MouseFocusLost

if !window_state.is_tracking {
    let mut tme = TRACKMOUSEEVENT {
        dwFlags: TME_LEAVE,
        hwndTrack: h_wnd,
        dwHoverTime: 0,
        cbSize: core::mem::size_of::<TRACKMOUSEEVENT>() as u32,
    };

    TrackMouseEvent(&mut tme);

    window_state.is_tracking = true;

    window_state
        .message_sender
        .send(WindowMessages::MouseFocusGained)
        .unwrap();
}

if msg == WM_MOUSELEAVE {
    let window_state_ptr = GetWindowLongPtrW(h_wnd, GWLP_USERDATA) as *mut WindowThreadState;
    let window_state: &mut WindowThreadState = window_state_ptr.as_mut().unwrap();

    if window_state.is_tracking {
        window_state.is_tracking = false;

        window_state
            .message_sender
            .send(WindowMessages::MouseFocusLost)
            .unwrap();
    }
}

Of course, the two new events will need to be added to the WindowMessages enum. Rust will thankfully throw an error again, and we can update the appropriate receiver logic in the Game.

And that’s it, we receive the necessary mouse input information in the Game.

Next Part

Next time I will connect these individual features into a first small prototype.

The code is available on GitHub

Rust Game Series - Part 10 - API cleanup and resource lifetime management

Wed, 15 Apr 2020 04:00:00 +0000

After last week’s post, the code is split into multiple crates, but the game code is still full of direct D3D11 functionality that requires unsafe code.

I would like the game code to be free of unsafe code. Unsafe code is required, but it should be hidden from the game in the abstraction layers.

Main API components

After a cleanup pass of the API, only a few concepts are left. I am following a very simplified D3D12 design.

GraphicsDeviceLayer
- Handles d3d11 creation, resources, and swap chain related functionality
Constant Buffer
- buffer creation and allocator
Pipeline State Object
- groups vertex/pixel shader. This will later be extended to hold other required state
Render Pass
- bind render targets and handles color/depth clear
Command Lists
- contains all rendering related functionality

The implementation of this is relatively straight forward. Most Rust structs are mostly wrapper objects around the native D3D11 objects at this point.

The API example is below:

let mut graphics_layer: GraphicsDeviceLayer =
    create_device_graphics_layer(main_window.hwnd, args.enable_debug_device).unwrap();

let pso_desc = PipelineStateObjectDesc {
    shader_name: "target_data/shaders/screen_space_quad",
};

let screenspace_quad_pso: PipelineStateObject = create_pso(&graphics_layer.device, pso_desc);

begin_render_pass(
    &mut graphics_layer.graphics_command_list,
    color,
    &graphics_layer.backbuffer_rtv,
);

let obj1_alloc = HeapAlloc::new(
    ScreenSpaceQuadData {
        color,
        padding: 0.0,
        scale: Float2 { x: 0.5, y: 0.5 },
        position: Float2 { x: 0.0, y: 0.0 },
    },
    &gpu_heap.gpu_data,
    &mut gpu_heap.state,
);

bind_pso(
    &mut graphics_layer.graphics_command_list,
    &screenspace_quad_pso,
);

bind_constant(&mut graphics_layer.graphics_command_list, 0, &obj1_alloc);

draw_vertices(&mut graphics_layer.graphics_command_list, 4);

unmap_gpu_buffer(gpu_heap.gpu_data, &graphics_layer);

execute_command_list(&graphics_layer, &graphics_layer.graphics_command_list);

present_swapchain(&graphics_layer);

The more interesting parts from a Rust perspective is the way to handle D3D11 resource management.

D3D11 memory management

In D3D11, each object is reference counted, and resources are only released once the reference count reaches 0. Each object implements the IUnknown interface that provides the necessary functionality.

D3D11 will internally increment ref counts, but it’s the developers’ responsibility to release these.

In Rust, generally, all resources are released once they reach the end of their lifetime. And I would like to keep these semantics for my API.

This can be achieved through the implementation of the Drop trait.

Drop Trait

A trait object defines the notion of an Interface. It allows us to express what types of functionality are supported by a type.

This can be used for static dispatching for the use in generics/templates (in C++) or dynamic dispatching.

A struct can implement any number of traits. Some, like the drop trait, are provided by the compiler unless we specify a customized implementation.

And that’s what we are doing for our wrapper types to enable the D3D resources to be released in a way that matches Rust semantics.

The core type of the graphics layer is the GraphicsDeviceLayer struct. The implementation looks like this:

pub struct GraphicsDeviceLayer<'a> {
    pub immediate_context: *mut ID3D11DeviceContext,
    pub swapchain: *mut IDXGISwapChain1,
    pub backbuffer_texture: *mut ID3D11Texture2D,

    pub backbuffer_rtv: RenderTargetView<'a>,
    pub graphics_command_list: GraphicsCommandList<'a>,

    pub device: GraphicsDevice<'a>,
}

impl Drop for GraphicsDeviceLayer<'_> {
    fn drop(&mut self) {
        unsafe {
            leak_check_release( self.backbuffer_texture.as_ref().unwrap(), 0, self.device.debug_device);
            leak_check_release( self.immediate_context.as_ref().unwrap(), 0, self.device.debug_device);
            leak_check_release( self.swapchain.as_ref().unwrap(), 0, self.device.debug_device);
        }
    }
}

You can see that the impl Drop only contains the explicit release logic for the native D3D11 objects stored as part of the object itself.

leak_check_release will assert if the reference count has not reached 0 and print additional information using the D3D11 debug device if available.

All other objects are Rust types, and I implemented the Drop trait for all of them. They are responsible for deleting the objects they contain.

The order in which drop is called might be surprising.

First, the drop function for the root object is called. At the end of the root drop functions, all drop functions of the child items are called. This is done in the order in which they are defined in the struct.

If those objects have children themselves, those will be called before moving on to the next item in the parent struct.

For this class structure it will be in this order:

GraphicsDeviceLayer > RenderTargetView > GraphicsCommandList > (possible child types) > GraphicsDevice

Implementing the drop trait for all wrapper objects enables us to remove all manual Release calls from the game code. The borrow checker and the lifetime specifiers make sure that all objects will be released in the correct order.

Externally owned objects will be released first. For example, Constant Buffer. The lifetime specifier defines that the references are not allowed to outlive the GraphicsDeviceLayer. Therefore the object has to be dropped before dropping the GraphicsDeviceLayer.

Next Part

With this work completed, we have a foundation to build upon. And it’s time to start implementing a first gameplay prototype. What’s missing for that?

Drawing multiple quads and input handling. I will be looking at these topics next.

The code is available on GitHub

Rust Game Series - Part 9 - Rust compilation structure

Mon, 06 Apr 2020 04:00:00 +0000

The project structure is often neglected when starting on a new project, especially for small projects, but I feel it’s essential. Rust provides two main building blocks:

Crate
Module

A Crate is the highest level, and each Crate contains one or more modules. The details are well explained in the Rust Book

Looking at the current state of the game code, we have a few logical blocks:

Game code
Window creation logic
Graphics foundation layer
Memory management
Shader interface
A few extensions to the Rust standard library

The first idea might be to keep everything inside a single rustmatch3 Crate and move the other functionality into modules. This is what I would do for a C++ project of this complexity.

In Rust, I am going to follow a different design and split this code into multiple Crates. The reason for this is the difference in the compilation unit size between Rust and C++.

In C++ each .cpp file is a compilation unit. In Rust, the compilation unit is a Crate.

The compiler is invoked once for each compilation unit. Therefore scaling to multiple cores is trivial for C++ as there are typically more files then there are cores.

The Rust compiler (Rustc) will only be invoked once per Crate. Therefore scaling to multiple cores for a single crate can only be achieved through multithreading within the compiler itself.

To understand how good the Rustc compiler is at using available CPU resources, I ran some tests.

Rust Compilation - Test Case - Image Rescaler

The following example is taken from one of my smaller Rust based tools. It is a simple tool that rescales images to a resolution suited for publishing on the web.

The upper half of this capture shows a timeline of which crates are being compiled. The lower half shows the status of the compilation units and the CPU usage over time.

From these graphs, we can see that the system is fully saturated at the start. Not surprising as the number of active units is always at the maximum value for my machine.

As the number of active units drops, however, so does the system utilization.

Especially insightful is the image crate. It takes around 16s to compile. Out of these, 7 seconds are spent on phase 1 of the compilation, and the rest is spent on phase 2.

The Rust compilation is split into two high-level phases:

Phase 1: generates metadata (list of types, dependencies, exports)
Phase 2: code generation

As can be seen from the CPU usage, phase 1 is unable to thoroughly saturate my system. Phase 2, on the other hand, can use my systems resources a lot better.

(the full graph can be found here)

Rust Compilation - Test Case - Rustc

The same behavior can be found in the rustc compiler itself. The capture was published in Visualizing Rust compilation.

It’s a very extreme example as there are more than 20 seconds of compilation where the CPU is pretty much idle! This is caused because the dependent Creates are only able to start compiling after the completion of phase 1.

Crate heavy architecture

Therefore I am suggesting to prefer a project structure that leans more towards crates with a shallow tree of dependencies. Having dependencies in the middle of the dependency chain can introduce large bubbles, as can be seen in Rustc

The aim should be to allow as many crates as possible to be compiled independently.

Should each file be a separate crate, mimicking the C++ compilation model? No, I don’t think so. There is an overhead to each Crate. There has to be a balance.

The best way is to keep checking the timings to detect if a single crate is starting to become a bottleneck. Once this happens, it’s time to start splitting a single Crate into multiple Crates.

Visualizing Rust compilation explains the necessary commands. Sadly these are only available on nightly :(

Game structure

So given all this information, how did I structure this project? For now, I split it into 3 creates

Window Creation
Graphics foundation layer + Memory management
Game + Shader interface

Below is a timing capture of a full rebuild:

As you can see most time is actually spend generation the native wrapper to call into Win32 API (Winapi crate) Sadly both the graphics and window creation require Winapi. Is it really needed to take 6 seconds in phase 1 to compile a win32 wrapper? Probably not.

Doing a minimal build with only changes to the game code takes 0.4 seconds. That is good to enough for now :)

Next Part

In the next part, I will be doing some graphics code again. Time to clean up the rendering interface so that the game doesn’t have to use any unsafe code, and all interactions with D3D11 are hidden inside the Graphics foundation layer.

The code is available on GitHub

Rust Game Series - Part 8 - Using Visual Studio

Tue, 24 Mar 2020 04:00:00 +0000

There are articles on how to use Visual Studio Code with Rust already, but I prefer to use Visual Studio.

This article presents my setup on how to use Visual Studio with Rust. It’s not a perfect setup, but it is good enough for me.

Extension

There exists a Visual Studio extension for Rust. I have it installed, but mostly using it to get syntax highlighting, it’s not essential to use it.

Project Setup

To use Rust with Visual Studio, I am using a Makefile Project.

After creating the project, my first step is to delete the Win32 configuration. Since I am not interested in developing x86 applications. Other platforms could be added as required.

Next I create a few extra configurations:

The names should be mostly self-explanatory what the purposes are

Run Clippy
Build the game
Run unit tests

These configurations allow the common operation to be accessed right from within Visual Studio. Configuration management is mostly done with property sheets.

RustBase provides the default settings, such as OutputDirectory and IntermidiateDirectory. And the more specific property sheets provide the necessary Cargo commands to be executed via nmake.

With all the setup, I am now able to compile the game, debug the game using the Visual Studio debugger, run Clippy as well as Unit Tests.

Debug Unit Test executables

Debugging Unit Tests is a bit more tricky because Cargo doesn’t generate deterministic file names for Unit Test executables. There is an open issue for it. It doesn’t seem to have gained much traction, though.

The solution that I am using is very primitive. When the Unit Tests are compiled, it will print the name of the generated executable. I then manually copy this name into the debug command.

This name seems to be deterministic for the same version of Rust, but after a version update, the name changes, and I need to copy it again. Not a great solution, but it works.

If you know a better way, please let me know :)

Rustfmt integration

Cargo formatting is a handy command to have easy access to. I suggest creating an External Tool in Visual Studio to enable one-click access to the tool.

The setup is shown below

And with the external tool entry created, it is now accessible from the Tools category. With a single click, the source code will be formatted with the specified guidelines.

Rust Debugging Advice

A few extra recommendations to make your Rust debugging experience better.

Debug Panics

Rust panics will generally try to unwind the stack or abort the application execution. But when a debugger is attached, I generally want to halt the debugger at the point when a panic occurs to inspect the program state.

Rust provides the possibility to do this, but it’s not very well documented. The rust panic handler is internally always calling the unmangled function rust_panic, that also never gets inlined.

It is possible to set a function breakpoint on this function.

With this breakpoint set each time a panic occurs, you will get a breakpoint in the debugger.

The function is sadly only called with a deep call stack. We will need to go a few levels up the stack until you find the user code.

Rust source code

As you might notice in the previous screenshot, I have symbols as well as source code for the Rust implementation itself. When you hit the panic breakpoint from Visual Studio the first time, it will not be able to resolve symbols but instead, ask for the source code location.

The Rust installations ships with full source code. It can be found in the rustup installation folder, for me it’s located in this location:

C:\Users\jendr\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib\rustlib\src\rust\src

Pointing Visual Studio at the correct location will resolve the symbols and show you the Rust code for the position. It also will allow you to step through the Rust implementations. Really useful to learn about how Rust library functionality is internally implemented.

That’s it for today.

Next time I m going to improve the Rust code organization a little bit before continuing the programming of the game.

The code is available on GitHub

Rust Game Series - Part 7 - Rust lifetimes and GPU Constant Allocator

Wed, 11 Mar 2020 04:00:00 +0000

In this part, I will be talking about how to write a custom memory allocator using Rust and D3D11. The concepts are applicable for general-purpose memory allocations but designed for the requirements of constant buffer management.

I am going to try to explain Rust lifetimes in the process and show how it can help to eliminate some classes of bugs.

Constant Buffer Overview

There are different ways to approach constant buffer management, I will implement it as follows:

Allocate one large constant buffer for each frame
Define a linear bump allocator that uses this buffer as backing storage
Use PSSetConstantBuffers1 to record the offset into this buffer for each draw call

Extend the screen space quad

Before we can start looking at the memory management, we need to update the shader so that constant data is used. The updated shader below allows the size, position, and final quad-color to be read from the constant buffer.

cbuffer ScreenSpaceQuadData : register(b0)
{
    float3 color;
    float2 scale;
    float2 position;
};

VertexToPixelShader VS_main(uint vertex_id: SV_VertexID)
{
    VertexToPixelShader output;

    switch (vertex_id) {
    case 0: output.position_clip = float4(-1,  1, 0, 1); break; // top-left
    case 1: output.position_clip = float4( 1,  1, 0, 1); break; // top-right
    case 2: output.position_clip = float4(-1, -1, 0, 1); break; // bottom-left
    case 3: output.position_clip = float4( 1, -1, 0, 1); break; // bottom-right
    }

    output.position_clip.xy *= scale;
    output.position_clip.xy += position;

    return output;
}

float3 PS_main(VertexToPixelShader input) : SV_TARGET
{
    return color;
}

To interface with this structure from Rust, we need to define a few helper classes.

#[repr(C)]
struct Float3 {
    x: f32,
    y: f32,
    z: f32,
}

#[repr(C)]
struct Float2 {
    x: f32,
    y: f32,
}

#[repr(C)]
struct ScreenSpaceQuadData {
    color: Float3,
    padding: f32,
    scale: Float2,
    position: Float2,
}

The one thing to call out is repr(C).

This instructs the compiler to follow the C alignment rules. The Rust and C alignment rules are very similar, but the significant difference is that the Rust compiler is free to reorder fields. At the time of writing, the compiler doesn’t seem to be doing that, however.

One problem is that HLSL doesn’t follow the C alignment rules and instead packs on float4 boundaries.

That’s why you see a padding: f32 inside of the ScreenSpaceQuadData definition. This is required because following the C alignment rules, scale would directly follow color. To follow the HLSL rules, we need one padding float to fill the float4.

The following two float2 types are packed into a single float4, so no padding is required for those variables.

With this, we have a Rust layout that matches the HLSL constant buffer layout. Time to look at the API result of the constant buffer system, and then I will present the thoughts and reasons behind the design.

let frame_constant_buffer = create_constant_buffer(
    graphics_device_layer.native.device,
    1024 * 8, // size of the buffer
),

let mut gpu_heap = LinearAllocator {
    gpu_data: map_gpu_buffer(buff, graphics_device_layer.native.context),
    state: LinearAllocatorState { used_bytes: 0 },
};

let obj1_alloc: HeapAlloc<ScreenSpaceQuadData> = HeapAlloc::new(
    ScreenSpaceQuadData { color, padding: 0.0,
        scale: Float2 { x: 1.0, y: 1.0 },
        position: Float2 { x: 0.0, y: 0.0 },
    },
    &gpu_heap.gpu_data,
    &mut gpu_heap.state,
);

let first_constant: u32 = obj1_alloc.first_constant_offset;
let num_constants: u32 = obj1_alloc.num_constants;

 command_context1.as_ref().unwrap().PSSetConstantBuffers1(
    0, // which slot to bind to
    1, // the number of buffers to bind
    &frame_data.frame_constant_buffer.native_buffer, // the buffer to bind
    &first_constant, // the first constant offset
    &num_constants, // number of constants to bind
);

command_context.as_ref().unwrap().Draw(4, 0);

unmap_gpu_buffer(gpu_heap.gpu_data, graphics_device_layer.native.context);

Implementation

The underlying memory is provided from a constant buffer. This buffer is located in GPU accessible memory and needs to be mapped so that the CPU can access it.

The function interface looks like this:

fn map_gpu_buffer<'a>(
    buffer: &'a mut ID3D11Buffer,
    context: &ID3D11DeviceContext,
) -> MappedGpuData<'a>

The one thing that will immediately stick out is the use <'a> and 'a on the types.

These are lifetime annotations. Every reference in Rust has a lifetime, but in many situations, lifetime-elision makes it possible to omit the annotations. But there are many situations in which the lifetime is unclear and needs to be provided explicitly.

An Important point to stress, the borrow checker only looks at the function definition for lifetime tracking. It doesn’t inspect the code inside a function.

In this case, the lifetime annotations can be read as follows:

The function accepts a reference to an ID3D11Buffer. This buffer object has lifetime 'a. The function returns a MappedGpuData, which has the same lifetime annotation 'a. This means that MappedGpuData internally contains a reference to data based on ID3D11Buffer.

Therefore this requires the return value to have the same or shorter lifetime then the buffer it was derived from.

The struct needs explicit lifetime annotations to make this visible to the compiler.

pub struct MappedGpuData<'a> {
    data: &'a [u8], // reference to slice of cpu accessible gpu memory
    buffer: &'a mut ID3D11Buffer, // reference to the d3d11 buffer the data comes from
}

Now we have the building blocks required for the implementation of map_gpu_buffer

fn map_gpu_buffer<'a>(
    buffer: &'a mut ID3D11Buffer,
    context: &ID3D11DeviceContext,
) -> MappedGpuData<'a> {
    let mut mapped_resource = D3D11_MAPPED_SUBRESOURCE {
        pData: std::ptr::null_mut(),
        RowPitch: 0,
        DepthPitch: 0,
    };

    // map the buffer
    let result: HRESULT = unsafe {
        context.Map(
            buffer as *mut ID3D11Buffer as *mut winapi::um::d3d11::ID3D11Resource,
            0, D3D11_MAP_WRITE_NO_OVERWRITE, 0,
            &mut mapped_resource,
        )
    };

    MappedGpuData {
        data: unsafe {
            std::slice::from_raw_parts_mut(
                mapped_resource.pData as *mut u8,
                mapped_resource.RowPitch as usize,
            )
        },
        buffer,
    }
}

Most of these are just D3D11 function calls, but the construction of the MappedGpuData requires a bit of description. The structure contains a slice to CPU accessible GPU memory. D3D11 provides us with a pointer and a size, we can combine this information using the unsafe from_raw_parts_mut to build a slice which can be used as a “normal” rust slice afterward.

The mutability of the borrow is forwarded to the returned type. This is independent of how the struct is defined. Since the buffer is a mutable borrow also the returned MappedGpuData will be a mutable borrow. This means we cannot map the same buffer twice unless we release the returned borrow.

Unmapping the buffer is quite straightforward. No lifetime annotations are required as MappedGpuData is passed in by moving ownership. This means after unmap_gpu_buffer returns, the mapped_data will not be valid anymore and cannot be accessed.

fn unmap_gpu_buffer(mapped_data: MappedGpuData, context: &ID3D11DeviceContext) {
    unsafe {
        context.Unmap(
            mapped_data.buffer as *mut ID3D11Buffer as *mut winapi::um::d3d11::ID3D11Resource,
            0,
        );
    }
}

With this functionality in place, we are now able to map and unmap GPU constant memory.

Time to implement an allocator that uses this memory buffer as backing storage.

pub struct LinearAllocatorState {
    used_bytes: usize,
}

pub struct LinearAllocator<'a> {
    gpu_data: MappedGpuData<'a>,
    state: LinearAllocatorState,
}

The allocator is a simple linear allocator called LinearAllocator. Here the state is split into two separate structs to separate mutable and immutable state.

Why this split? It’s related to the forwarding of borrow mutability. Let us look at how it’s used:

let obj1_alloc: HeapAlloc<ScreenSpaceQuadData> = HeapAlloc::new(
    ScreenSpaceQuadData { color, padding: 0.0,
        scale: Float2 { x: 1.0, y: 1.0 },
        position: Float2 { x: 0.0, y: 0.0 },
    },
    &gpu_heap.gpu_data,
    &mut gpu_heap.state,
);

The implementation of this look as follows:

pub struct HeapAlloc<'a, T> {
    ptr: &'a mut T,
    first_constant_offset: u32,
    num_constants: u32,
}

impl<'a, T> HeapAlloc<'a, T> {
    pub fn new(
        x: T,
        gpu_data: &'a MappedGpuData,
        state: &mut LinearAllocatorState,
    ) -> HeapAlloc<'a, T>

HeapAlloc is following the design of Box but adjusted for the requirements of D3D11 constant buffer binding. It contains a mutable borrow of generic Type T with an explicit lifetime annotation.

The HeapAlloc::new function has an explicit lifetime annotation too, and the return type lifetime matches the lifetime of the MappedGpuData passed into the function.

As I mentioned earlier, the borrow type is forwarded to the reference. Since we want multiple allocations to be done into the same buffer, we cannot use a mutable reference. Otherwise, a second allocation would also return a mutable reference. But only a single mutable borrow is allowed to be active at the same time.

We still need to modify the state of the LinearAllocator to increment the allocation offset. Therefore we split the state from the buffer and pass the LinearAllocatorState as mutable borrow.

The full implementation is below:

impl<'a, T> HeapAlloc<'a, T> {
    pub fn new(
        x: T,
        gpu_data: &'a MappedGpuData,
        state: &mut LinearAllocatorState,
    ) -> HeapAlloc<'a, T> {
        let allocation_size: usize = round_up_to_multiple(std::mem::size_of::<T>(), 256);

        let data_slice = gpu_data.data;
        let start_offset_in_bytes = state.used_bytes;

        let data_ptr =
            data_slice[state.used_bytes..(state.used_bytes + allocation_size)].as_ptr() as *mut T;

        state.used_bytes += allocation_size;

        unsafe {
            // write data into target destination
            std::ptr::write(data_ptr, x);

            HeapAlloc {
                ptr: data_ptr.as_mut().unwrap(),
                first_constant_offset: (start_offset_in_bytes / 16) as u32,
                num_constants: (allocation_size / 16) as u32,
            }
        }
    }
}

The core of the alloc construction is based on slices. The allocator uses the base slice for data and sub-divides this slice into smaller sub-slices. This operation internally performs range checks to validate that constant allocations don’t overflow the source buffer and will cause a Panic if an overflow would be happening.

With all these pieces in place, we have a working allocator system for constants.

If you would like to use a HeapAlloc to read/write values, the following traits need to be implemented too:

impl<T> std::ops::Deref for HeapAlloc<'_, T> {
    type Target = T;

    fn deref(&self) -> &T {
        self.ptr
    }
}

impl<T> std::ops::DerefMut for HeapAlloc<'_, T> {
    fn deref_mut(&mut self) -> &mut T {
        self.ptr
    }
}

A few D3D11behaviour worth mentioning related to PSSetConstantBuffers1:

First of all, this doesn’t work on Windows 7 and requires extended interface access (ID3D11DeviceContext1)

To get to the extented interface query it afer creating the base interface:

command_context.as_ref().unwrap().QueryInterface(
    &ID3D11DeviceContext1::uuidof(),
    &mut command_context1 as *mut *mut ID3D11DeviceContext1
        as *mut *mut winapi::ctypes::c_void,
);

Additionally, Cargo.toml will need to be adjusted to list d3d11_1

winapi = { version = "0.3", features = ["winuser", "d3d11", "d3d11_1", "winerror", "dxgi1_2"] }

There is also a bug when this feature is not supported by the driver, as described in MSDN - Calling PSSetConstantBuffers1 with command list emulation but a workaround is provided.

TLDR when runtime emulation doesn’t always update the offsets, need to first unbind constant buffers explicitly :(

The full implementation is on GitHub, and the previously constant color quad is now animated with a cyclic color change between Red and Black.

Please let me know if I got something wrong or explained it in an unclear way.

Before continuing with the game, I am going to provide an overview of how I am using Rust with Visual Studio on Windows in the next post.

The code is available on GitHub

Rust Game Series - Part 6 - Drawing a procedural quad

Wed, 11 Dec 2019 04:00:00 +0000

With a working swap chain, nothing will stop us from rendering a quad.

We will be looking at the following topics:

generating vertex data in a shader
compile shaders
load shaders
record draw commands
executing command lists

procedural quad shaders

What is a procedural quad? This means we don’t use any data from vertex buffers, but instead, the system provided SV_VertexID is used to generate the vertex positions inside of the vertex shader itself.

This makes drawing a quad easier since no buffer needs to created, filled from the CPU, and bound to the pipeline. The vertex shader is below:

VertexToPixelShader VS_main(uint vertex_id: SV_VertexID)
{
    VertexToPixelShader output;

    switch (vertex_id) {
    case 0: output.position_clip = float4(-1,  1, 0, 1); break; // top-left
    case 1: output.position_clip = float4( 1,  1, 0, 1); break; // top-right
    case 2: output.position_clip = float4(-1, -1, 0, 1); break; // bottom-left
    case 3: output.position_clip = float4( 1, -1, 0, 1); break; // bottom-right
    }

    output.position_clip.xy *= 0.5f; // change the size of the quad a bit

    return output;
}

compile shader

Given a shader, we need to compile it; for now, a batch file is all that is required. Shaders are compiled using the Microsoft FXC compiler, which gets distributed in the Windows SDK.

:: compile VS shader
..\build_environment\microsoft\fxc\fxc.exe /T vs_4_0 src_data\shaders\screen_space_quad.hlsl /EVS_main /Fo target_data\shaders\screen_space_quad.vsb
..\build_environment\microsoft\fxc\fxc.exe /T ps_4_0 src_data\shaders\screen_space_quad.hlsl /EPS_main /Fo target_data\shaders\screen_space_quad.psb

shader loading

Loading and creation shaders are straightforward from Rust. The std filesystem provides the functionality to load binary files into memory. With the data loaded into memory, a pointer and length are passed to CreateVertexShader/CreatePixelShader, and the shaders are ready to use afterward

// load a shader
let vertex_shader_memory = std::fs::read("target_data/shaders/screen_space_quad.vsb").unwrap();
let pixel_shader_memory  = std::fs::read("target_data/shaders/screen_space_quad.psb").unwrap();

let error: HRESULT = d3d11_device.CreateVertexShader(
    vertex_shader_memory.as_ptr() as *const winapi::ctypes::c_void,
    vertex_shader_memory.len(),
    std::ptr::null_mut(),
    &mut vertex_shader as *mut *mut ID3D11VertexShader,
);

let error: HRESULT = d3d11_device.CreatePixelShader(
    pixel_shader_memory.as_ptr() as *const winapi::ctypes::c_void,
    pixel_shader_memory.len(),
    std::ptr::null_mut(),
    &mut pixel_shader as *mut *mut ID3D11PixelShader,
);

record draw commands

Normally most D3D11 code would now directly execute its work on the immediate context. I prefer to use DeferredContext instead.

A deferred context allows commands to be recorded into a command list that can later be executed using the immediate context. I prefer this way because it makes more logical sense to me.

GPU execution from the immediate context is under the control of the driver, and there are no guarantees when work might be executed. With an explicit command list execution steps, it’s apparent when CPU work is being done to record commands compared to when the GPU is allowed to execute those commands.

To be able to record a command list, a deferred context needs to be created.

let mut command_context: *mut ID3D11DeviceContext = std::ptr::null_mut();
let error = graphics_device.CreateDeferredContext(0, &mut command_context);

Given this context, we can now set up the state for our quad. The code is very compact, all the work is done in the vertex shader without requiring any buffers or shader resource bindings.

// set viewport for the output render target
command_context.RSSetViewports(1, &viewport);

// bind backbuffer as render target
let rtvs: [*mut winapi::um::d3d11::ID3D11RenderTargetView; 1] = [graphics_layer.backbuffer_rtv];
command_context.OMSetRenderTargets( 1, rtvs.as_ptr(), std::ptr::null_mut() );

// bind the shaders
command_context.VSSetShader(vertex_shader, std::ptr::null_mut(), 0);
command_context.PSSetShader(pixel_shader, std::ptr::null_mut(), 0);

// we are drawing 4 vertices using a triangle strip topology
command_context.IASetPrimitiveTopology(D3D11_PRIMITIVE_TOPOLOGY_TRIANGLESTRIP);
command_context.Draw(4, 0);

This recorded all the commands. And are now waiting to be executed by the GPU. For this, we need access to the recorded command list and execute it using the immediate context.

let mut command_list: *mut ID3D11CommandList = std::ptr::null_mut();
command_context.FinishCommandList(0, &mut command_list);
immediate_context.ExecuteCommandList(command_list, 1);

Given all this, and a pixel shader that writes a yellow color. We get to see this:

Next, I am going to dive deeper into Rust and use lifetimes to write a custom allocator for safe, constant buffer management.

The code is available on GitHub

Rust Game Series - Part 5 - D3D11 Device and Swap Chain creation

Thu, 05 Dec 2019 04:00:00 +0000

With the window creation in place, we have the necessary foundation to create a D3D11 device and a Swap Chain.

To start using it, add the necessary dependencies into Cargo.toml.

[dependencies]
winapi = { version = "0.3", features = ["winuser", "d3d11", "winerror", "dxgi1_2"] }

Creating the swap chain is done in the following steps

Create a D3D11 device
Get access to the DXGI interface
Create the swap chain

Let’s look at each step:

Create a D3D11 device

unsafe {
    // use default adapter
    let adapter: *mut IDXGIAdapter = std::ptr::null_mut();
    let flags: UINT = 0;

    let feature_levels: D3D_FEATURE_LEVEL = D3D_FEATURE_LEVEL_11_0;
    let num_feature_levels: UINT = 1;

    let mut d3d11_device: *mut ID3D11Device = std::ptr::null_mut();
    let mut d3d11_immediate_context: *mut ID3D11DeviceContext = std::ptr::null_mut();

    let result: HRESULT = D3D11CreateDevice(
        adapter,
        D3D_DRIVER_TYPE_HARDWARE,
        std::ptr::null_mut(),
        flags,
        &feature_levels,
        num_feature_levels,
        D3D11_SDK_VERSION,
        &mut d3d11_device,
        std::ptr::null_mut(),
        &mut d3d11_immediate_context,
    );

    assert!(result != winapi::shared::winerror::S_OK, "d3d11 device creation failed");
}

This is really close to what you would write in C++ too. Two things stand out:

let adapter: *mut IDXGIAdapter = std::ptr::null_mut();

Pointers need to be defined as mutable and therefore need to be initialized with a mutable null pointer.

D3D11CreateDevice returns the outputs as an output parameter.

Therefore we need to provide a pointer to the location where the pointer to the created d3d11_device should be stored.

In Rust, we can pass in a mutable reference to the *mut ID3D11Device, and it will do the implicit conversion to a pointer type.

Get access to the DXGI interface

Next, we need to get the underlying DXGI interface that was used internally when the d3d11 device was created.

let mut dxgi_device: *mut IDXGIDevice = std::ptr::null_mut();

// get dxgi device
let result = d3d11_device.as_ref().unwrap().QueryInterface(
    &IDXGIDevice::uuidof(),
    &mut dxgi_device as *mut *mut IDXGIDevice as *mut *mut winapi::ctypes::c_void,
);

Relatively little code, but what is that cast?!?

Looking at the QueryInterface documentation, the parameter is defined as *mut *mut c_void and our object is of type *mut IDXGIDevice

Let me break down the cast into its steps:

// taking a mutable reference to dxgi device
let mut_ref: &mut *mut IDXGIDevice = &mut dxgi_device;

// next we need to convert the reference to a pointer
let raw_ptr: *mut *mut IDXGIDevice = mut_ref as *mut *mut IDXGIDevice;

// and the pointer type we can cast to the c_void type required by QueryInterface
let void_cast: *mut *mut winapi::ctypes::c_void = raw_ptr as *mut *mut winapi::ctypes::c_void;

// all steps expressed in a single line :)
&mut dxgi_device as *mut *mut IDXGIDevice as *mut *mut winapi::ctypes::c_void

Afterward, we apply the same idea a few more times until we have access to the IDXGIFactory2 interface that is required to create the swap chain.

let mut dxgi_adapter: *mut IDXGIAdapter = std::ptr::null_mut();
let result = dxgi_device.as_ref().unwrap().GetAdapter(&mut dxgi_adapter);

let mut dxgi_factory: *mut IDXGIFactory1 = std::ptr::null_mut();

let result = dxgi_adapter
    .as_ref()
    .unwrap()
    .GetParent(&IDXGIFactory1::uuidof(), &mut dxgi_factory as * mut *mut IDXGIFactory1 as * mut * mut winapi::ctypes::c_void  );

let mut dxgi_factory_2: *mut IDXGIFactory2 = std::ptr::null_mut();

let result = dxgi_factory
    .as_ref()
    .unwrap()
    .QueryInterface(&IDXGIFactory2::uuidof(), &mut dxgi_factory_2 as * mut * mut IDXGIFactory2 as * mut *mut winapi::ctypes::c_void );

With all those interfaces we can finally create the swap chain


let sd = DXGI_SWAP_CHAIN_DESC1 {
    Width: 0,
    Height: 0,
    Format: DXGI_FORMAT_R8G8B8A8_UNORM,
    SampleDesc: DXGI_SAMPLE_DESC {
        Count: 1,
        Quality: 0,
    },
    BufferUsage: DXGI_USAGE_RENDER_TARGET_OUTPUT,
    BufferCount: 2,
    AlphaMode: DXGI_ALPHA_MODE_UNSPECIFIED,
    Flags: 0,
    Scaling: DXGI_SCALING_STRETCH,
    SwapEffect: DXGI_SWAP_EFFECT_DISCARD,
    Stereo: 0,
};

let mut swapchain: *mut IDXGISwapChain1 = std::ptr::null_mut();

let result = dxgi_factory_2.as_ref().unwrap().CreateSwapChainForHwnd(
    d3d11_device as *mut winapi::um::unknwnbase::IUnknown,
    hwnd,
    &sd,
    std::ptr::null_mut(),
    std::ptr::null_mut(),
    &mut swapchain,
);

We are currently missing one piece of fundamental data to be able to create the swap chain, and that’s the HWND from the window we want to create the swap chain for.

We need to make some modifications to get access to this. Firstly the WindowMessages enum needs to be updated. When the window is created, we need to pass the HWND along.

struct WindowCreatedData {
    hwnd: HWND,
}

enum WindowMessages {
    WindowCreated(WindowCreatedData),
    WindowClosed,
}

Then we adjust the sender location to pass the HWND into the WindowCreated message.

window_state
    .message_sender
    .send(WindowMessages::WindowCreated(WindowCreatedData {
        hwnd: h_wnd,
    }))
    .unwrap();

When trying to build the code, a new error is encountered now:

std::thread::spawn(move || {
^^^^^^^^^^^^^^^^^^ `*mut winapi::shared::windef::HWND__` cannot be sent between threads safely

The Rust compiler can determine if Rust types can be transferred across thread boundaries safely. When it determines that it’s safe, the std::marker::Send trait will automatically be implemented by the compiler.

Because of the way HWND is expressed as pointer type in Winapi, the compiler regards the type as unsafe. But HWND is not really a pointer, but a pointer sized handle. Therefore it’s still ok to pass it between threads, and the trait can be implemented manually.

unsafe impl std::marker::Send for WindowCreatedData {}

Implementing the trait, we promise to the Rust compiler that passing WindowCreatedData between threads is safe.

With this, we can send the window handle between threads and create the swap chain. Once the swap chain is created, Present can be called from our rendering loop, and we will see the window is cleared to black.

swapchain.as_ref().unwrap().Present(1, 0);

With the successfully created swap chain, we can start looking into actually rendering something next week.

The code is available on GitHub

Rust Game Series - Part 4 - removing global state

Sat, 30 Nov 2019 04:00:00 +0000

The current state of the message loop is below, and the problem left to solve is the global state.

static mut IS_WINDOW_CLOSED: bool = false;

unsafe extern "system" fn window_proc(
    h_wnd: HWND,
    msg: UINT,
    w_param: WPARAM,
    l_param: LPARAM,
) -> LRESULT {
    if msg == WM_DESTROY {
        IS_WINDOW_CLOSED = true;

        PostQuitMessage(0);
    }

    DefWindowProcW(h_wnd, msg, w_param, l_param)
}

IS_WINDOW_CLOSED is required to communicate between the window proc and the main game loop. Ideally, I would like to pass an object to the message handler and only rely on that state.

Luckily Windows provides a method for this. This can be achieved in 3 steps:

pass a custom struct into CreateWindowExW
when WM_CREATE is received, store this custom struct into the window user data
obtain the custom user data in the window handler

The following struct will be used:

struct WindowThreadState {
    message_sender: std::sync::mpsc::Sender<WindowMessages>,
    is_window_closed : bool
}

This struct can be created as usual and passed into CreateWindowExW as the last parameter.

let mut window_state = WindowThreadState { 
            message_sender : channel_sender, 
            is_window_closed : true 
            };

let h_wnd_window = CreateWindowExW(
                ...
                & mut window_state as * mut WindowThreadState as * mut winapi::ctypes::c_void,
            );

Pretty simple besides the cast, let me break that one down

    // taking a mutable reference
    let mut_ref: &mut WindowThreadState = &mut window_state;

    // next we need to convert the reference to a pointer
    let raw_ptr: *mut WindowThreadState = mut_ref as *mut WindowThreadState;

    // and the pointer type we can cast to the c_void type required by CreateWindowEx
    let void_ptr: *mut winapi::ctypes::c_void = raw_ptr as *mut winapi::ctypes::c_void;

    // all steps expressed in a single line
    &mut window_state as *mut WindowThreadState as *mut winapi::ctypes::c_void

With the state passed into CreateWindowEx, it’s time to update the message handler and remove the use of the global state.


unsafe extern "system" fn window_proc(
    h_wnd: HWND,    
    msg: UINT,
    w_param: WPARAM,
    l_param: LPARAM,
) -> LRESULT {

    if msg == WM_CREATE {
        // retrieve the message struct that contains the creation parameters
        let create_struct = l_param as * mut winapi::um::winuser::CREATESTRUCTW;
    
        // retrieve the rust window state
        let window_state_ptr = create_struct.as_ref().unwrap().lpCreateParams as * mut WindowThreadState;
        let window_state : & mut WindowThreadState = window_state_ptr.as_mut().unwrap();

        // the pointer we can store inside of the USERDATA of the window being created
        SetWindowLongPtrW(h_wnd, GWLP_USERDATA, window_state_ptr as isize );

        // sent a message that the window has been created
        window_state.message_sender.send(WindowMessages::WindowCreated).unwrap();
    }

    if msg == WM_DESTROY {
        // request the state from the window USERDATA
        let window_state_ptr = GetWindowLongPtrW(h_wnd, GWLP_USERDATA) as * mut WindowThreadState;
        let window_state : & mut WindowThreadState = window_state_ptr.as_mut().unwrap();

        // send a message that the window has been closed
        window_state.message_sender.send(WindowMessages::WindowClosed).unwrap();
        window_state.is_window_closed = true;

        PostQuitMessage(0);
    }

    DefWindowProcW(h_wnd, msg, w_param, l_param)
}

After adjusting the message-loop, a Clippy warning needs to be disabled too.

    #[allow(clippy::while_immutable_condition)] 
    while !window_state.is_window_closed {
        if PeekMessageA(&mut msg, h_wnd_window, 0, 0, PM_REMOVE) > 0 {
            TranslateMessage(&msg);
            DispatchMessageA(&msg);
        }
    }

This needs to be done because the Rust compiler can’t see that is_window_closed will ever be changed. This variable is only changed in the window message proc, and Rust is unaware that this function is ever called during TranslateMessage by the windows runtime.

Therefore we need to disable the Clippy warning for this location only.

Update

Turns out, there is a better way to exit the message loop. Thanks to Michal Ziulek for pointing this out.

PostQuitMessage(0) pushes WM_QUIT message to the queue so you can break the main loop like this:
{
TranslateMessage(&msg);
DispatchMessageA(&msg);
if (msg.message == WM_QUIT) break;
}
— Michal Ziulek (@MichalZiulek) November 30, 2019

The updated code looks like this:

loop {
    if PeekMessageA(&mut msg, h_wnd_window, 0, 0, PM_REMOVE) > 0 {
        TranslateMessage(&msg);
        DispatchMessageA(&msg);

        // once the window has been closed we can exit the message loop
        if msg.message == WM_QUIT {
            break;
        }
    }
}

This is a lot better, I can remove is_window_closed, and no Clippy warning need to be disabled.

With the foundation created I will focus on creating a D3D11 device next week.

The code is available on GitHub

Rust Game - Part 3 - Unlock the Message Loop

Fri, 22 Nov 2019 04:00:00 +0000

With the implementation from the previous post, the game loop stops updating when dragging the window.

This happens because the windows message loop is continuously receiving new messages. This causes process_window_messages to enter an endless loop until the user stops dragging the window.

I personally like to keep my game updating at all times; therefore, I move my windows message loop processing into a background thread.

The following two steps are required to make sure that game loop updates at all times:

Create a window in a thread and run the message pump in the window thread
Setup thread-safe communication between game thread and message loop thread

Creating window in a thread

Creating the window in a thread requires very few changes to the code shown in the previous post.

Moving the code from create_window into a std::thread::spawn closure

std::thread::spawn(move || { 
    let mut window_class_name: Vec<u16> =
                OsStr::new("Match3WindowClass").encode_wide().collect();

            window_class_name.push(0);

            let window_class = WNDCLASSW {
                style: 0,
                lpfnWndProc: Some(window_proc),
                ........

            let h_wnd_window = CreateWindowExW(
                ........

This will make sure the window is created in a new thread.

The message loop needs to run in the same thread as the window was created. Therefore the ‘process_window_messages’ logic needs to be moved into the thread closure as well.

    ShowWindow(h_wnd_window, SW_SHOW);

    while !IS_WINDOW_CLOSED {
        if PeekMessageA(&mut msg, h_wnd_window, 0, 0, PM_REMOVE) > 0 {
            TranslateMessage(&msg);
            DispatchMessageA(&msg);
        }
    }

With this in place, the new thread will be receiving and processing all messages that are sent to the window.

When specific messages (window closed, key pressed, …), are received, they need to be sent to the game so it can react to it.

Setup thread-safe communication between game and message loop thread

One common communication primitive between threads provided by Rust is std::sync::mpsc::channel This is a “multi-producer, single-consumer FIFO queue.”

My communication strategy is:

The window is the producer of messages, the game is the receiver
All messages will be expressed as enum WindowMessages to be sent between threads

If I remember it correctly, some transitions, such as fullscreen, also require the game thread to be able to send messages to the window thread, but I will implement that if necessary in the future.

For now, I am going to define two messages.

WindowCreated
WindowClosed

enum WindowMessages {
    WindowCreated,
    WindowClosed,
}

A channel needs to be created so that communication between the two threads is possible.

The channel is created on the main thread, and the move at the closure level means that ownership for variables accessed from the thread will be moved onto the spawned thread.

fn create_window() -> Result<Window, ()> {
    let (channel_sender, channel_receiver) = std::sync::mpsc::channel();

    std::thread::spawn(move || {
                       ----

After the window has been created and show the ‘WindowCreated’ message will be sent from the window thread.

ShowWindow(h_wnd_window, SW_SHOW);

channel_sender.send(WindowMessages::WindowCreated)

Because channel_sender is used inside of the closure, ownership will be moved to the window thread. channel_receiver is not used, and therefore ownership stays with the game thread.

Before create_window returns, the window creation on the separate thread has to be completed, therefor we wait until the window creation on the separate thread has been completed.

This is done as below, channel_receiver.recv() will block until a message has been received.

fn create_window() -> Result<Window, ()> {
    let (channel_sender, channel_receiver) = std::sync::mpsc::channel();

    std::thread::spawn(move || { ...... } );

    // wait for window created before returning
    if let WindowMessages::WindowCreated = channel_receiver.recv().unwrap() {
        return Ok(Window {
            message_receiver: channel_receiver,
        });
    }

    Err(())
}

process_window_messages needs to be adjusted so that it checks for the arrival of new messages from the window channel.

fn process_window_messages(window: &Window) -> Option<WindowMessages> {
    if let Ok(x) = window.message_receiver.try_recv() {
        return Some(x);
    }

    None
}

try_recv will not block and returns an Optional to indicate if a new message has been received or not.

The one message to be handled for now is WindowClosed. For this, to work, the message pump on the window thread needs to send a WindowClosed event when a WM_DESTROY message has been received.

while !IS_WINDOW_CLOSED {
    if PeekMessageA(&mut msg, h_wnd_window, 0, 0, PM_REMOVE) > 0 {
        TranslateMessage(&msg);
        DispatchMessageA(&msg);

        if IS_WINDOW_CLOSED {
            channel_sender.send(WindowMessages::WindowClosed).unwrap();
        }
    }

With all this in place, we can now drag the window, and the game loop continues to update. When the user closes the window, the game loop will close as expected.

One thing that is still problematic is the global state (IS_WINDOW_CLOSED) that is used for communication between the window_proc and the message loop on the message loop thread.

Next, I will try to solve this and see if it’s possible to attach Rust objects to native objects.

The code is available on GitHub

Rust Game - Part 2 - Win32 Window

Thu, 14 Nov 2019 04:00:00 +0000

Creating a window from Rust requires interfacing with the Win32 API.

I started out using the Foreign Function Interface(FFI) to call the Win32 APIs directly. Even though I got it working it takes a tremendous amount of effort;

Thankfully, there is the winapi crate. Happy to support Peter Atashian on patreon for maintaining this project.

To start using it, add the necessary dependency into Cargo.toml.

[dependencies]
winapi = { version = "0.3", features = ["winuser"] }

The features list defines what win32 APIs are required and should be imported.

To detect which features are required to be compiled, search the documentation for the function you want to call. It will show which module it is defined in.

For example, in this case, winuser needs to be imported.

winapi::um::winuser::CreateWindowExW
            ------

Creating a Win32 window is broken down into 3 steps:

register a window class
create a window
start processing the message loop

Let’s look at each step:

register a window class

unsafe {
    let mut window_class_name: Vec<u16> =
        OsStr::new("Match3WindowClass").encode_wide().collect();

    // encode_wide does NOT add a null terminator
    window_class_name.push(0);

    let window_class = WNDCLASSW {
        style: 0,
        lpfnWndProc: Some(window_proc),
        cbClsExtra: 0,
        cbWndExtra: 0,
        hInstance: 0 as HINSTANCE,
        hIcon: 0 as HICON,
        hCursor: 0 as HICON,
        hbrBackground: 16 as HBRUSH,
        lpszMenuName: 0 as LPCWSTR,
        lpszClassName: window_class_name.as_ptr(),
    };

    let error_code = RegisterClassW(&window_class);

    assert!(error_code != 0, "failed to register the window class");

OS String handling

I am using the wide version of the Win32 API. Therefore I need to convert from the Rust OsStr into a wide-character array.

encode_wide() provides the conversion into UTF16 characters. The conversion is implemented lazily as an iterator and collect() collects all the u16 values into a Vec.

It’s important to remember that encode_wide() does not add null termination, and explicit zero termination is required.

window proc handler

You might have noticed Some(window_proc) in the previous class registration. This defines the function that will be called by Win32 to process the window messages.

The function needs a bit of extra information to be passed across the Rust <-> Win32 boundary.

unsafe extern "system" fn window_proc(
    h_wnd: HWND,
    msg: UINT,
    w_param: WPARAM,
    l_param: LPARAM,
) -> LRESULT {
    if msg == WM_DESTROY {
        IS_WINDOW_CLOSED = true;

        PostQuitMessage(0);
    }

    DefWindowProcW(h_wnd, msg, w_param, l_param)
}

unsafe extern "system" marks the function as unsafe and to use the system ABI. This is the cross-platform string that maps to stdcall on Windows.

Create window


let h_wnd_window = CreateWindowExW(
    0,
    window_class_name.as_ptr(),
    0 as LPCWSTR,
    WS_OVERLAPPED | WS_MINIMIZEBOX | WS_SYSMENU,
    0,
    0,
    400,
    400,
    0 as HWND,
    0 as HMENU,
    0 as HINSTANCE,
    std::ptr::null_mut(),
);

assert!(h_wnd_window != (0 as HWND), "failed to open the window");

ShowWindow(h_wnd_window, SW_SHOW);

Creating the window is pretty straightforward. Passing in the required settings and the name of the class we registered previously.

Message loop


let mut msg: MSG = std::mem::zeroed();

// process messages
while !IS_WINDOW_CLOSED {
    if PeekMessageA(&mut msg, h_wnd_window, 0, 0, PM_REMOVE) > 0 {
        TranslateMessage(&msg);
        DispatchMessageA(&msg);
    }
}

Running the message loop is very close to the native Win32 version. std::mem::zeroed makes sure that MSG is set to an all-zero byte-pattern.

Every message will now call the window_proc function that was registered with the window class.

Running the application will now show a default Win32 window.

When running the application and starting to drag the window, the main game loop stops updating. Next week I am going to change that and look at threading in Rust.

The code is available on GitHub

Rust Game - Part 1 - Overview

Thu, 07 Nov 2019 04:00:00 +0000

This is the start of a series of small posts about my game development endeavors using Rust. I have been using Rust more and more in my free time projects but never used it in a larger project.

This will be my first larger project using Rust, and I will talk about my learnings here. So what I am making?

Going to make a simple “Match 3” game from scratch.

My goals for the final project result are

Implement full game-flow (Menus, Options, Loading, Gameplay, Pause screen, etc.)
Multiple levels
Save game system
Audio (Music and Sound Effects)

Constraints

Windows only
fixed resolution
D3D11 renderer
using no external crates at runtime, besides winapi

Tools might be using some crates, but I want to keep the game itself free from external dependencies as much as possible.