Filled init wgpu page, more clarification pending

Author: Bromles

code/guide/getting-started/hello-triangle/src/main.rs

@@ -78,6 +78,7 @@ impl Renderer {
                 .expect("Failed to request device")
         });
 
+        // #region renderer-new-surface-config
         let surface_capabilities = surface.get_capabilities(&adapter);
 
         let surface_format = surface_capabilities
@@ -98,6 +99,7 @@ impl Renderer {
             alpha_mode: CompositeAlphaMode::Auto,
             view_formats: vec![],
         };
+        // #endregion renderer-new-surface-config
 
         let mut renderer = Self {
             device,

code/guide/getting-started/init-wgpu/src/main.rs

@@ -5,11 +5,10 @@ use std::sync::Arc;
 use tokio::runtime;
 use tokio::runtime::Runtime;
 use wgpu::{
-    Backends, Color, CommandEncoderDescriptor, CompositeAlphaMode, Device, DeviceDescriptor,
-    ExperimentalFeatures, Features, Instance, InstanceDescriptor, Limits, LoadOp, MemoryHints,
-    Operations, PowerPreference, PresentMode, Queue, RenderPassColorAttachment,
-    RenderPassDescriptor, RequestAdapterOptions, StoreOp, Surface, SurfaceConfiguration,
-    SurfaceError, TextureFormat, TextureUsages, TextureViewDescriptor,
+    Backends, Color, CommandEncoderDescriptor, Device, DeviceDescriptor, ExperimentalFeatures,
+    Features, Instance, InstanceDescriptor, Limits, LoadOp, MemoryHints, Operations,
+    PowerPreference, Queue, RenderPassColorAttachment, RenderPassDescriptor, RequestAdapterOptions,
+    StoreOp, Surface, SurfaceConfiguration, SurfaceError, TextureViewDescriptor,
 };
 use winit::application::ApplicationHandler;
 use winit::dpi::PhysicalSize;
@@ -23,8 +22,8 @@ enum App {
     Loading,
     Ready {
         window: Arc<Window>,
-        renderer: Box<Renderer>,
-        need_to_resize_surface: bool,
+        renderer: Box<Renderer>,      // [!code ++]
+        need_to_resize_surface: bool, // [!code ++]
     },
 }
 // #endregion appstate
@@ -39,20 +38,27 @@ struct Renderer {
 // #endregion renderer
 
 impl Renderer {
-    // #region renderer-new
+    // #region renderer-new-size
     fn new(window: Arc<Window>, runtime: Arc<Runtime>) -> Self {
         let mut physical_size = window.inner_size();
         physical_size.width = physical_size.width.max(1);
         physical_size.height = physical_size.height.max(1);
+        // #endregion renderer-new-size
 
+        // #region renderer-new-instance
         let instance = Instance::new(&InstanceDescriptor {
             backends: Backends::PRIMARY,
             ..Default::default()
         });
+        // #endregion renderer-new-instance
 
+        // #region renderer-new-surface
         let surface = instance
             .create_surface(window)
             .expect("Failed to create surface");
+        // #endregion renderer-new-surface
+
+        // #region renderer-new-adapter
         let adapter = runtime.block_on(async {
             instance
                 .request_adapter(&RequestAdapterOptions {
@@ -63,11 +69,13 @@ impl Renderer {
                 .await
                 .expect("Failed to request adapter")
         });
+        // #endregion renderer-new-adapter
 
+        // #region renderer-new-device
         let (device, queue) = runtime.block_on(async {
             adapter
                 .request_device(&DeviceDescriptor {
-                    label: None,
+                    label: Some("Main device"),
                     required_features: adapter.features() & Features::default(),
                     required_limits: Limits::default().using_resolution(adapter.limits()),
                     memory_hints: MemoryHints::Performance,
@@ -77,40 +85,25 @@ impl Renderer {
                 .await
                 .expect("Failed to request device")
         });
+        // #endregion renderer-new-device
 
-        let surface_capabilities = surface.get_capabilities(&adapter);
-
-        let surface_format = surface_capabilities
-            .formats
-            .iter()
-            .copied()
-            .find(TextureFormat::is_srgb)
-            .or_else(|| surface_capabilities.formats.first().copied())
-            .expect("Failed to get surface format");
-
-        let surface_config = SurfaceConfiguration {
-            usage: TextureUsages::RENDER_ATTACHMENT,
-            format: surface_format,
-            width: physical_size.width,
-            height: physical_size.height,
-            present_mode: PresentMode::AutoNoVsync,
-            desired_maximum_frame_latency: 2,
-            alpha_mode: CompositeAlphaMode::Auto,
-            view_formats: vec![],
-        };
+        // #region renderer-new-surface-config
+        let surface_config = surface
+            .get_default_config(&adapter, physical_size.width, physical_size.height)
+            .expect("Failed to get default surface config");
+        // #endregion renderer-new-surface-config
 
-        let renderer = Self {
+        // #region renderer-new-return
+        surface.configure(&device, &surface_config);
+
+        Self {
             device,
             queue,
             surface,
             surface_config,
-        };
-
-        renderer.resize_surface(physical_size);
-
-        renderer
+        }
     }
-    // #endregion renderer-new
+    // #endregion renderer-new-return
 
     // #region renderer-resize
     fn resize_surface(&self, size: PhysicalSize<u32>) {
@@ -128,18 +121,26 @@ impl Renderer {
     }
     // #endregion renderer-resize
 
-    // #region renderer-render
+    // #region renderer-render-texture
     fn render(&mut self, window: Arc<Window>) {
         match self.surface.get_current_texture() {
             Ok(frame) => {
+                // #endregion renderer-render-texture
+                // #region renderer-render-encoder
                 let mut encoder = self
                     .device
-                    .create_command_encoder(&CommandEncoderDescriptor { label: None });
+                    .create_command_encoder(&CommandEncoderDescriptor {
+                        label: Some("Main command encoder"),
+                    });
+                // #endregion renderer-render-encoder
 
+                // #region renderer-render-view
                 let view = frame.texture.create_view(&TextureViewDescriptor::default());
+                // #endregion renderer-render-view
 
+                // #region renderer-render-pass
                 encoder.begin_render_pass(&RenderPassDescriptor {
-                    label: None,
+                    label: Some("Clear render pass"),
                     color_attachments: &[Some(RenderPassColorAttachment {
                         view: &view,
                         resolve_target: None,
@@ -153,10 +154,14 @@ impl Renderer {
                     timestamp_writes: None,
                     occlusion_query_set: None,
                 });
+                // #endregion renderer-render-pass
 
+                // #region renderer-render-finish
                 self.queue.submit([encoder.finish()]);
                 window.pre_present_notify();
                 frame.present();
+                // #endregion renderer-render-finish
+                // #region renderer-render-error
             }
             Err(error) => match error {
                 SurfaceError::OutOfMemory => {
@@ -168,22 +173,24 @@ impl Renderer {
             },
         };
     }
+    // #endregion renderer-render-error
     // #endregion renderer-render
 }
 
 impl ApplicationHandler for App {
     // #region appsetup
     fn resumed(&mut self, event_loop: &ActiveEventLoop) {
         if let Self::Loading = self {
+            // [!code ++]
             let runtime = Arc::new(
-                runtime::Builder::new_current_thread()
-                    .build()
-                    .expect("Failed to create tokio runtime"),
-            );
+                runtime::Builder::new_current_thread() // [!code ++]
+                    .build() // [!code ++]
+                    .expect("Failed to create tokio runtime"), // [!code ++]
+            ); // [!code ++]
 
             let window_attributes = WindowAttributes::default()
                 .with_title("WGPU Tutorial")
-                .with_visible(false);
+                .with_visible(false); // [!code ++]
 
             let window = Arc::new(
                 event_loop
@@ -193,27 +200,27 @@ impl ApplicationHandler for App {
 
             center_window(window.clone());
 
-            event_loop.set_control_flow(ControlFlow::Wait);
+            event_loop.set_control_flow(ControlFlow::Wait); // [!code ++]
 
-            let renderer = Renderer::new(window.clone(), runtime.clone());
+            let renderer = Renderer::new(window.clone(), runtime.clone()); // [!code ++]
 
             *self = Self::Ready {
                 window,
-                renderer: Box::new(renderer),
-                need_to_resize_surface: false,
+                renderer: Box::new(renderer),  // [!code ++]
+                need_to_resize_surface: false, // [!code ++]
             }
         }
 
-        let Self::Ready {
-            window, renderer, ..
-        } = self
-        else {
-            return;
-        };
+        let Self::Ready {  // [!code ++]
+            window, renderer, .. // [!code ++]
+        } = self // [!code ++]
+        else { // [!code ++]
+            return; // [!code ++]
+        }; // [!code ++]
 
-        renderer.render(window.clone());
+        renderer.render(window.clone()); // [!code ++]
 
-        window.set_visible(true);
+        window.set_visible(true); // [!code ++]
     }
     // #endregion appsetup
 
@@ -226,8 +233,8 @@ impl ApplicationHandler for App {
     ) {
         let Self::Ready {
             window,
-            renderer,
-            need_to_resize_surface,
+            renderer,               // [!code ++]
+            need_to_resize_surface, // [!code ++]
             ..
         } = self
         else {
@@ -236,20 +243,21 @@ impl ApplicationHandler for App {
 
         match event {
             WindowEvent::RedrawRequested => {
+                // [!code ++]
                 if *need_to_resize_surface {
-                    let size = window.inner_size();
+                    let size = window.inner_size(); // [!code ++]
 
-                    renderer.resize_surface(size);
+                    renderer.resize_surface(size); // [!code ++]
 
-                    *need_to_resize_surface = false;
-                }
+                    *need_to_resize_surface = false; // [!code ++]
+                } // [!code ++]
 
-                renderer.render(window.clone());
+                renderer.render(window.clone()); // [!code ++]
 
                 window.request_redraw();
             }
             WindowEvent::Resized(_) => {
-                *need_to_resize_surface = true;
+                *need_to_resize_surface = true; // [!code ++]
                 window.request_redraw();
             }
             WindowEvent::CloseRequested => {

docs/guide/getting-started/creating-window/index.md

@@ -82,7 +82,7 @@ wgpu требует resolver 2 в Cargo.toml для корректной раб
 
 Трейт `ApplicationHandler` имеет следующие обязательные для реализации методы, наравне с множеством опциональных:
 
-```rust
+```rs
 trait ApplicationHandler {
     fn resumed(&mut self, event_loop: &ActiveEventLoop);
     fn window_event(&mut self, event_loop: &ActiveEventLoop, window_id: WindowId, event: WindowEvent);
@@ -102,7 +102,7 @@ trait ApplicationHandler {
 
 Реализация выглядит стандартно:
 
-```rust
+```rs
 impl ApplicationHandler for App {
     fn resumed(&mut self, event_loop: &ActiveEventLoop) {
         // ...
@@ -210,7 +210,7 @@ winit сначала вызовет наш обработчик события `
 
 ## Результаты работы
 
-В результате выполнения данного кода мы должны увидеть в центре экрана пустое окно. Содержимое и внешний вид будет
+В результате выполнения данного кода мы должны увидеть в центре экрана пустое окно. Содержимое и внешний вид будут
 различаться в зависимости от операционной системы, ниже приведен скриншот с Windows 11:
 
 ![Window](./window.png)

docs/guide/getting-started/hello-triangle/index.md

@@ -8,3 +8,23 @@ next:
 ---
 
 # Первый треугольник
+
+
+<<< @/../code/guide/getting-started/hello-triangle/src/main.rs#renderer-new-surface-config
+
+Получаем доступные возможности нашей поверхности, которые исходят из возможностей переданного адаптера
+
+Далее нам нужно определиться с форматом кадров, которые мы будем выводить на поверхность, то есть в окно. На данный момент мы просто можем взять поддерживаемый список форматов поверхности, попытаться выбрать формат с поддержкой `SRGB`, и взять первый попавшийся, если такого не нашлось.
+
+В реальном приложении вы, скорее всего, захотите организовать здесь более сложную логику выбора формата.
+
+Теперь, получив подходящий формат поверхности, мы можем создать объект ее конфигурации `SurfaceConfiguration`:
+
+- `usage` - как мы будем использовать эту поверхность. На самом деле это параметр текстуры, поскольку отрисовку мы производим именно в нее. Но эта текстура находится в поверхности, поэтому данный параметр задается здесь. Выбираем `RENDER_ATTACHMENT`, то есть указываем, что данная текстура в поверхности будет использоваться как цель рендера, в нее будет выводиться полученная картинка.э
+- `format` - полученный нами формат поверхности
+- `width` - ширина поверхности. Передаем вычисленное ранее значение
+- `height` - высота поверхности. Передаем вычисленное ранее значение
+- `present_mode` - режим отображения кадров на поверхности. Режимов достаточно много, и разные устройства поддерживают разные режимы. Но wgpu сильно облегчает нам здесь жизнь, предоставляя опции `AutoVsync` и `AutoNoVsync`. Эти опции будут перебирать разные режимы отображения, пока не наткнутся на первый поддерживаемый нашим устройством. Различие между ними, соответственно, в наличии или отсутствии вертикальной синхронизации, то есть ограничения частоты вывода кадров частотой монитора.
+- `desired_maximum_frame_latency` - число кадров, которое может одновременно ожидать вывода на экран. Обычно указывается от 1 до 3, но может быть и больше. Не может быть меньше 1. Слишком низкое значение может привести к простою GPU, которой просто некуда будет отдавать готовый кадр, если поверхность не успевает их отрисовывать. По-умолчанию принято ставить 2, как оптимальное значение для большинства случаев.
+- `alpha_mode` - режим альфа-канала, отвечающего за прозрачность цветов. В данном случае выбираем автоматическое определение на основании поддерживаемого
+- `view_formats` - форматы представлений текстур, которые будут поддерживаться данной поверхностью для рендера. Собственный формат поверхности поддерживается всегда, поэтому нет нужды что-либо туда передавать.