151 lines
6.5 KiB
Markdown
151 lines
6.5 KiB
Markdown
# Troubleshooting
|
|
|
|
## 1. `cargo build` fails with "no matching package"
|
|
|
|
**Symptom:** Build fails with `could not find package` for wgpu or winit.
|
|
|
|
**Cause:** Version typo in `Cargo.toml`. wgpu and winit have specific major versions.
|
|
|
|
**Fix:** Verify your dependency versions:
|
|
```toml
|
|
wgpu = "29"
|
|
winit = "0.30"
|
|
tokio = { version = "1", features = ["rt", "macros"] }
|
|
bytemuck = { version = "1", features = ["derive"] }
|
|
log = "0.4"
|
|
simple_logger = "5"
|
|
```
|
|
|
|
## 2. Window opens but shows black screen
|
|
|
|
**Symptom:** Window appears but is entirely black. No triangle visible.
|
|
|
|
**Cause:** One (or more) of several common rendering misconfigurations:
|
|
- Pipeline not set: `pass.set_pipeline()` not called
|
|
- Vertex buffer not bound: `pass.set_vertex_buffer()` not called
|
|
- Draw call wrong: `draw()` arguments incorrect (must be `draw(0..3, 0..1)` — two ranges)
|
|
- Triangle wound clockwise: `FrontFace::Ccw` requires counter-clockwise vertex order
|
|
- Format mismatch: `ColorTargetState::format` must match `SurfaceConfiguration::format`
|
|
- Present omitted: `surface_texture.present()` must be called to show rendered frame
|
|
|
|
**Fix:** Check each item above. Verify the pipeline is set, buffer is bound, draw uses two `Range<u32>` arguments, vertices are CCW, formats match, and `present()` is called.
|
|
|
|
## 3. Washed-out or wrong colors
|
|
|
|
**Symptom:** Triangle renders but colors look dull or incorrect.
|
|
|
|
**Cause:** `SurfaceConfiguration::view_formats` missing `add_srgb_suffix()`. Without sRGB gamma correction, colors appear washed out.
|
|
|
|
**Fix:** Ensure `view_formats` includes the sRGB variant:
|
|
```rust
|
|
view_formats: vec![format.add_srgb_suffix()],
|
|
```
|
|
|
|
## 4. Panic: "No adapter found"
|
|
|
|
**Symptom:** Program crashes immediately with `No GPU adapter found`.
|
|
|
|
**Cause:** No Vulkan driver installed. wgpu on Linux requires Vulkan.
|
|
|
|
**Fix:**
|
|
```bash
|
|
sudo apt install libvulkan1 mesa-vulkan-drivers
|
|
vulkaninfo # verify installation
|
|
```
|
|
|
|
## 5. Panic: "Surface lost"
|
|
|
|
**Symptom:** Program crashes with a surface lost error during rendering.
|
|
|
|
**Cause:** Display server restarted or GPU context was reset. The [Surface](concepts/GLOSSARY.md#surface) is permanently invalidated.
|
|
|
|
**Fix:** In the tutorial, this means the window needs to be reopened. In production code, handle the `Lost` variant of `CurrentSurfaceTexture` by recreating the surface via `Instance::create_surface()`.
|
|
|
|
## 6. Wayland surface crashes or doesn't render
|
|
|
|
**Symptom:** Program crashes or shows blank window on Wayland.
|
|
|
|
**Cause:** winit's Wayland backend may have compatibility issues with certain compositors.
|
|
|
|
**Fix:** Force X11 backend:
|
|
```bash
|
|
WINIT_UNIX_BACKEND=x11 cargo run
|
|
```
|
|
|
|
## 7. Window won't close
|
|
|
|
**Symptom:** Clicking the X button or pressing Escape doesn't close the window.
|
|
|
|
**Cause:** `ApplicationHandler::exiting()` not implemented, or `event_loop_ctl.exit()` not called.
|
|
|
|
**Fix:** Ensure `exiting()` (note: NOT `closing()`) is implemented:
|
|
```rust
|
|
fn exiting(&mut self, event_loop_ctl: &ActiveEventLoop) {
|
|
event_loop_ctl.exit();
|
|
}
|
|
```
|
|
|
|
## 8. CPU at 100%
|
|
|
|
**Symptom:** One CPU core at 100% usage.
|
|
|
|
**Cause:** `ControlFlow::Poll` drives `RedrawRequested` events continuously. Every frame renders and queues another redraw. This is the expected behavior for a `ControlFlow::Poll` render loop.
|
|
|
|
**Fix:** No fix needed — this is expected for a continuous redraw demo. For production, switch to `ControlFlow::Wait` and call `request_redraw()` only when state changes.
|
|
|
|
## 9. Shader compilation or pipeline creation error
|
|
|
|
**Symptom:** Program panics during `create_render_pipeline` with a shader validation error.
|
|
|
|
**Cause:** `@location` numbers in WGSL don't match `shader_location` numbers in Rust's `VertexAttribute`, or `@builtin(position)` is missing from vertex shader output.
|
|
|
|
**Fix:** Check the log output for validation messages. Verify:
|
|
- WGSL `@location(0)` matches Rust `shader_location: 0`
|
|
- WGSL `@location(1)` matches Rust `shader_location: 1`
|
|
- Vertex shader outputs `@builtin(position) clip_position: vec4<f32>`
|
|
|
|
## 10. Triangle shows one solid color instead of gradient
|
|
|
|
**Symptom:** Triangle renders but is a single uniform color instead of smoothly blending.
|
|
|
|
**Cause:** Fragment shader returns a constant color instead of passing through `input.vertex_color`. The [rasterizer](concepts/GLOSSARY.md#rasterizer) interpolates vertex colors automatically, but only if the fragment shader uses them.
|
|
|
|
**Fix:** Ensure fragment shader returns the interpolated vertex color:
|
|
```wgsl
|
|
@fragment
|
|
fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
|
|
return vec4<f32>(input.vertex_color, 1.0);
|
|
}
|
|
```
|
|
|
|
Not this (which returns a solid color):
|
|
```wgsl
|
|
return vec4<f32>(1.0, 1.0, 1.0, 1.0); // wrong: solid white
|
|
```
|
|
|
|
## 11. WGSL shader compilation errors
|
|
|
|
**Symptom:** Program panics or logs errors during `device.create_shader_module()` or `create_render_pipeline()` with messages referencing WGSL validation failures.
|
|
|
|
**Cause:** wgpu validates WGSL shaders at pipeline creation time, not at runtime. Errors surface immediately when the shader module is created or when the render pipeline references it. Common causes include:
|
|
- Syntax errors: typos in WGSL (missing semicolons, mismatched braces, incorrect keywords)
|
|
- Type mismatches: passing `vec2<f32>` where `vec4<f32>` is expected, or mixing signed/unsigned types
|
|
- Missing `@location` or `@builtin` attributes: vertex/fragment shader I/O without proper decoration
|
|
- Entry point not found: the `@vertex` or `@fragment` function name doesn't match the pipeline descriptor's `entry_point` field
|
|
|
|
**Fix:** Read wgpu's error messages carefully — they include the shader source line and column where the issue was detected. Follow this checklist:
|
|
- Check the reported line/column in your WGSL source for syntax issues
|
|
- Verify all type signatures match between vertex shader output and fragment shader input
|
|
- Ensure every varying uses `@location(N)` and position output uses `@builtin(position)`
|
|
- Confirm the function name in your `@vertex`/`@fragment` declaration matches the string you pass to `ProgrammableStage::entry_point`
|
|
- If the error message is unclear, try compiling the shader in isolation to isolate syntax vs. pipeline-binding issues
|
|
|
|
## Additional Resources
|
|
|
|
- [Glossary](concepts/GLOSSARY.md) — Every term defined
|
|
- [Graphics Pipeline](concepts/graphics-pipeline.md) — Pipeline stage overview
|
|
- [Coordinate Systems](concepts/coordinate-systems.md) — NDC and transformation spaces
|
|
- [Shader Basics](concepts/shader-basics.md) — WGSL and shader concepts
|
|
- [wgpu documentation](https://docs.rs/wgpu/29.0.0/) — Official wgpu 29 API docs
|
|
- [wgpu repository](https://github.com/gfx-rs/wgpu) — Examples and issue tracker
|