As of version 0.10, wgpu require's cargo's [newest feature resolver](https://doc.rust-lang.org/cargo/reference/resolver.html#feature-resolver-version-2). As a result you must include `resolver = 2` in either the `[package]` section of `Cargo.toml` if you are working on a single crate, or the `[workspace]` section of the root `Cargo.toml` in a workspace.
## The code
There's not much going on here yet, so I'm just going to post the code in full. Just paste this into your `main.rs` or equivalent.
For convenience we're going to pack all the fields into a struct, and create some methods on that.
@ -62,7 +62,12 @@ impl State {
).await.unwrap();
```
The `surface` is used to create the `swap_chain`. Our `window` needs to implement [raw-window-handle](https://crates.io/crates/raw-window-handle)'s `HasRawWindowHandle` trait to access the native window implementation for `wgpu` to properly create the graphics backend. Fortunately, winit's `Window` fits the bill. We also need it to request our `adapter`.
### Instance and Adapter
The `instance` is the first thing you create when using wgpu. It's may purpose
is to create `Adapter`s and `Surface`s.
The `adapter` is a handle to our actual graphics card. You can use this get information about the graphics card such as its name and what backend the adapter uses. We use this to create our `Device` and `Queue` later.
<divclass="note">
@ -79,11 +84,19 @@ let adapter = instance
.unwrap()
```
For more fields you can use to refine you're search [check out the docs](https://docs.rs/wgpu/0.9.0/wgpu/struct.Adapter.html).
Another thing to note is that `Adapter`s are locked to a specific backend. If you are on Windows and have 2 graphics cards you'll have at least 4 adapters available to use, 2 Vulkan and 2 DirectX.
For more fields you can use to refine you're search [check out the docs](https://docs.rs/wgpu/0.10.1/wgpu/struct.Adapter.html).
</div>
We need the `adapter` to create the device and queue.
### The Surface
The `surface` is the part of the window that we draw to. We need it to draw directly to the screen. Our `window` needs to implement [raw-window-handle](https://crates.io/crates/raw-window-handle)'s `HasRawWindowHandle` trait to create a surface. Fortunately, winit's `Window` fits the bill. We also need it to request our `adapter`.
### Device and Queue
Let's use the `adapter` to create the device and queue.
```rust
let (device, queue) = adapter.request_device(
@ -100,11 +113,11 @@ The `features` field on `DeviceDescriptor`, allows us to specify what extra feat
<divclass="note">
The device you have limits the features you can use. If you want to use certain features you may need to limit what devices you support, or provide work arounds.
The graphics card you have limits the features you can use. If you want to use certain features you may need to limit what devices you support, or provide work arounds.
You can get a list of features supported by your device using `adapter.features()`, or `device.features()`.
You can view a full list of features [here](https://docs.rs/wgpu/0.7.0/wgpu/struct.Features.html).
You can view a full list of features [here](https://docs.rs/wgpu/0.10.1/wgpu/struct.Features.html).
</div>
@ -120,23 +133,31 @@ The `limits` field describes the limit of certain types of resource we can creat
};
surface.configure(&device, &config);
```
Here we are defining and creating the `swap_chain`. The `usage` field describes how the `swap_chain`'s underlying textures will be used. `RENDER_ATTACHMENT` specifies that the textures will be used to write to the screen (we'll talk about more `TextureUsages`s later).
The `format` defines how the `swap_chain`s textures will be stored on the gpu. Different displays prefer different formats. We use `adapter.get_preferred_format()` to figure out the best format to use.
Here we are defining a config for our surface. This will define how the surface creates it's underlying `SurfaceTexture`s. We will talk about `SurfaceTexture` when we get to the `render` function. For now lets talk about some of the our configs fields.
The `usage` field describes how the `SurfaceTexture`s will be used. `RENDER_ATTACHMENT` specifies that the textures will be used to write to the screen (we'll talk about more `TextureUsages`s later).
The `format` defines how the `SurfaceTexture`s will be stored on the gpu. Different displays prefer different formats. We use `surface.get_preferred_format(&adapter)` to figure out the best format to use based on the display you're using.
`width` and `height`, are the width and height in pixels of the swap chain. This should usually be the width and height of the window.
`width` and `height`, are the width and height in pixels of the `SurfaceTexture`. This should usually be the width and height of the window.
<divclass="warning">
Make sure that the width and height of the `SurfaceTexture` are not 0, as that can cause your app to crash.
</div>
The `present_mode` uses the `wgpu::PresentMode` enum which determines how to sync the swap chain with the display. You can see all the options [in the docs](https://docs.rs/wgpu/0.7.0/wgpu/enum.PresentMode.html)
The `present_mode` uses the `wgpu::PresentMode` enum which determines how to sync the surface with the display. The option we picked `FIFO`, will cap the display rate at the displays framerate. This is essentially VSync. This is also the most optimal mode on mobile. There are other options and you can see all them [in the docs](https://docs.rs/wgpu/0.10.1/wgpu/enum.PresentMode.html)
At the end of the method, we simply return the resulting struct.
Now that we've configured our surface properly we can add these new fields at the end of the method.
```rust
Self {
instance,
adapter,
surface,
device,
queue,
config,
swap_chain,
size,
}
}
@ -147,7 +168,7 @@ At the end of the method, we simply return the resulting struct.
We'll want to call this in our main method before we enter the event loop.
```rust
// Since main can't be async, we're going to need to block
// State::new uses async code, so we're going to wait for it to finish
let mut state = pollster::block_on(State::new(&window));
```
@ -158,7 +179,7 @@ You can use heavier libraries like [async_std](https://docs.rs/async_std) and [t
</div>
## resize()
If we want to support resizing in our application, we're going to need to recreate the `swap_chain` everytime the window's size changes. That's the reason we stored the physical `size` and the `config` used to create the swapchain. With all of these, the resize method is very simple.
If we want to support resizing in our application, we're going to need to reconfigure the `surface` everytime the window's size changes. That's the reason we stored the physical `size` and the `config` used to configure the `surface`. With all of these, the resize method is very simple.
There's nothing really different here from creating the `swap_chain` initially, so I won't get into it.
There's nothing really different here from configurating the `surface` initially, so I won't get into it.
We call this method in `main()` in the event loop for the following events.
@ -253,20 +274,27 @@ fn update(&mut self) {
}
```
We'll add some code here later on to move around objects.
## render()
Here's where the magic happens. First we need to get a frame to render to. This will include a `wgpu::Texture` and `wgpu::TextureView` that will hold the actual image we're drawing to (we'll cover this more when we talk about textures).
Here's where the magic happens. First we need to get a frame to render to.
let output = self.surface.get_current_frame()?.output;
```
The `get_current_frame` function will wait for the `surface` to provide a new `SurfaceTexture` that we will render to. We'll store this in `output` for later.
```rust
let view = output.texture.create_view(&wgpu::TextureViewDescriptor::default());
```
This line creates a `TextureView` with default settings. We need to do this because we want to control how the render code interacts with the texture.
We also need to create a `CommandEncoder` to create the actual commands to send to the gpu. Most modern graphics frameworks expect commands to be stored in a command buffer before being sent to the gpu. The `encoder` builds a command buffer that we can then send to the gpu.
```rust
@ -281,21 +309,19 @@ Now we can actually get to clearing the screen (long time coming). We need to us
{
let _render_pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
@ -360,11 +386,13 @@ Some of you may be able to tell what's going on just by looking at it, but I'd b
}
```
A `RenderPassDescriptor` only has three fields: `label`, `color_attachments` and `depth_stencil_attachment`. The `color_attachements` describe where we are going to draw our color to. We'll use `depth_stencil_attachment` later, but we'll set it to `None` for now.
A `RenderPassDescriptor` only has three fields: `label`, `color_attachments` and `depth_stencil_attachment`. The `color_attachements` describe where we are going to draw our color to. We use the `TextureView` we created earlier to make sure that we render to the screen.
We'll use `depth_stencil_attachment` later, but we'll set it to `None` for now.
The `RenderPassColorAttachment` has the `view` field which informs `wgpu` what texture to save the colors to. In this case we specify `frame.view` that we created using `swap_chain.get_current_frame()`. This means that any colors we draw to this attachment will get drawn to the screen.
The `RenderPassColorAttachment` has the `view` field which informs `wgpu` what texture to save the colors to. In this case we specify `frame.view` that we created using `surface.get_current_frame()`. This means that any colors we draw to this attachment will get drawn to the screen.
The `resolve_target` is the texture that will receive the resolved output. This will be the same as `attachment` unless multisampling is enabled. We don't need to specify this, so we leave it as `None`.
The `ops` field takes a `wpgu::Operations` object. This tells wgpu what to do with the colors on the screen (specified by `frame.view`). The `load` field tells wgpu how to handle colors stored from the previous frame. Currently we are clearing the screen with a bluish color.
The `ops` field takes a `wpgu::Operations` object. This tells wgpu what to do with the colors on the screen (specified by `frame.view`). The `load` field tells wgpu how to handle colors stored from the previous frame. Currently we are clearing the screen with a bluish color. The `store` field tells wgpu with we want to store the rendered results to the `Texture` behind our `TextureView` (in this case it's the `SurfaceTexture`). We use `true` as we do want to store our render results. There are cases when you wouldn't want to but those
Ben Hansen
3 years ago