Jérôme Bousquié
d81743481b
- Wrap in backticks every bare type in rustdoc comments (vertex.rs, frame.rs, pipeline_cache.rs, material.rs, mesh.rs, scene.rs, error.rs) so rustdoc no longer misreads them as intra-doc links or HTML tags. - Add a missing doc comment on the public Frame struct. - Add #![warn(missing_docs)] to the crate root so unevidenced public items are surfaced going forward. cargo doc --no-deps now generates with zero warnings.
91 lines
4.8 KiB
Rust
91 lines
4.8 KiB
Rust
//! # Frame Module — Per-Frame RAII Wrapper (Surface Texture + View)
|
|
//!
|
|
//! Defines `Frame`, a per-frame RAII wrapper around the surface texture and its TextureView.
|
|
//! A Frame exists only for the duration of a single rendering pass — it is acquired at the start
|
|
//! of each frame loop iteration via Context::begin_frame() or Frame::try_new(), used by Renderer
|
|
//! to write draw commands into the TextureView, then dropped after Renderer::present() submits it.
|
|
//!
|
|
//! ## Interaction with Other Modules
|
|
//! - **context**: provides the Surface from which Frame acquires the current texture.
|
|
//! - **renderer**: passes Frame's TextureView to render() as the color attachment target.
|
|
//! - **error**: does not use errors directly; Frame::new() panics on acquisition failure while
|
|
//! Frame::try_new() returns `Option<Self>` for graceful recovery.
|
|
//!
|
|
//! ## Architecture Notes (per ARCHI_APP.md)
|
|
//! - **Phase d'Exécution**: Frame is acquired at the start of each render loop iteration and released after rendering.
|
|
//! - **Ergonomie**: Users interact with frames through Renderer::render() + Renderer::present(), not directly with wgpu handles.
|
|
|
|
/// A per-frame RAII wrapper around the surface texture and its `TextureView`.
|
|
/// Owned for the duration of a single render pass: acquired via `Frame::new()`/`try_new()` at the
|
|
/// start of each frame loop iteration, used by `Renderer` as the color attachment target, then
|
|
/// dropped after `present()` submits it to the GPU queue.
|
|
pub struct Frame {
|
|
/// The GPU surface texture representing the current display buffer to be presented.
|
|
pub surface_texture: wgpu::SurfaceTexture,
|
|
/// A read-only view into surface_texture, used as the RenderPass color attachment during rendering.
|
|
pub view: wgpu::TextureView,
|
|
}
|
|
|
|
impl Frame {
|
|
/// Acquires the next surface texture and creates a TextureView over it.
|
|
/// Inputs: surface (borrowed reference to wgpu Surface providing access to display buffers).
|
|
/// Returns a new Frame instance. Panics if the surface cannot be acquired (e.g., lost, occluded).
|
|
/// Called by the orchestrator (App::run) at the start of each frame loop iteration.
|
|
/// Internal steps: 1) get_current_texture() → 2) match Success/Suboptimal variants →
|
|
/// 3) create_view on texture → 4) construct Frame with both fields.
|
|
pub fn new(surface: &wgpu::Surface) -> Self {
|
|
// In wgpu 30, get_current_texture() returns CurrentSurfaceTexture enum directly (not Result).
|
|
// All variants are matched to provide explicit error handling instead of panicking —
|
|
// see Context::begin_frame() for the detailed variant mapping.
|
|
match surface.get_current_texture() {
|
|
// On Success or Suboptimal, we acquire the SurfaceTexture and create its TextureView
|
|
wgpu::CurrentSurfaceTexture::Success(frame)
|
|
| wgpu::CurrentSurfaceTexture::Suboptimal(frame) => {
|
|
let view = frame
|
|
.texture
|
|
.create_view(&wgpu::TextureViewDescriptor::default());
|
|
Self {
|
|
surface_texture: frame,
|
|
view,
|
|
}
|
|
}
|
|
// Panicking on failure here is intentional — Frame must exist for rendering to proceed.
|
|
// Callers should use try_new() if they prefer Option-based error recovery.
|
|
other => panic!("Failed to acquire texture: {:?}", other),
|
|
}
|
|
}
|
|
|
|
/// Presents the rendered frame by submitting the acquired surface texture to the GPU queue.
|
|
/// The frame must have been obtained via new() or try_new(); calling present() twice on the same
|
|
/// texture is undefined behavior. Called after Renderer::render().
|
|
pub fn present(self, queue: &wgpu::Queue) {
|
|
queue.present(self.surface_texture);
|
|
}
|
|
|
|
/// Attempts to acquire the next surface texture without panicking.
|
|
/// Inputs: surface (borrowed reference to wgpu Surface providing access to display buffers).
|
|
/// Returns Some(Frame) on success (Success/Suboptimal) or None on any error variant.
|
|
/// Called when graceful frame skipping is preferred over crashing.
|
|
pub fn try_new(surface: &wgpu::Surface) -> Option<Self> {
|
|
match surface.get_current_texture() {
|
|
wgpu::CurrentSurfaceTexture::Success(frame)
|
|
| wgpu::CurrentSurfaceTexture::Suboptimal(frame) => {
|
|
let view = frame
|
|
.texture
|
|
.create_view(&wgpu::TextureViewDescriptor::default());
|
|
Some(Self {
|
|
surface_texture: frame,
|
|
view,
|
|
})
|
|
}
|
|
_ => None,
|
|
}
|
|
}
|
|
|
|
/// Returns a reference to the TextureView used as the RenderPass color attachment.
|
|
/// Called by Renderer::render() to pass the view into begin_render_pass().
|
|
pub fn view(&self) -> &wgpu::TextureView {
|
|
&self.view
|
|
}
|
|
}
|