fix: warnings and bump version

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "phobos"
-version = "0.7.3"
+version = "0.8.0"
 edition = "2021"
 license = "Apache-2.0"
 description = "Fast, powerful Vulkan abstraction library"

examples/04_fsr2/main.rs

@@ -1,4 +1,4 @@
-use std::time::{Duration, Instant};
+use std::time::Instant;
 
 use anyhow::Result;
 use ash::vk;
@@ -7,7 +7,7 @@ use glam::{Mat4, Vec3};
 use winit::event::{Event, WindowEvent};
 
 use phobos::{
-    DeletionQueue, GraphicsCmdBuffer, image, Image, ImageView, IncompleteCmdBuffer, InFlightContext, Pass, PassBuilder, PassGraph, PhysicalResourceBindings,
+    DeletionQueue, GraphicsCmdBuffer, image, Image, ImageView, IncompleteCmdBuffer, InFlightContext, PassBuilder, PassGraph, PhysicalResourceBindings,
     PipelineBuilder, PipelineStage, RecordGraphToCommandBuffer, Sampler,
 };
 use phobos::domain::All;
@@ -20,6 +20,7 @@ use crate::example_runner::{Camera, Context, create_shader, ExampleApp, ExampleR
 #[path = "../example_runner/lib.rs"]
 mod example_runner;
 
+#[allow(dead_code)]
 struct Attachment {
     pub image: Image,
     pub view: ImageView,
@@ -246,7 +247,7 @@ impl ExampleApp for Fsr2Sample {
         let near = 0.1f32;
         let fov = 90.0f32.to_radians();
 
-        let (jitter_x, jitter_y) = ctx.device.fsr2_context().jitter_offset(self.render_width, self.display_width)?;
+        let (jitter_x, jitter_y) = ctx.device.fsr2_context().jitter_offset(self.render_width)?;
 
         let transform = Mat4::IDENTITY;
         let view = self.camera.matrix();

examples/example_runner/lib.rs

@@ -281,7 +281,7 @@ pub trait ExampleApp {
         bail!("run() not implemented for headless example app");
     }
 
-    fn handle_event(&mut self, event: &Event<()>) -> Result<()> {
+    fn handle_event(&mut self, _event: &Event<()>) -> Result<()> {
         Ok(())
     }
 }

src/core/app_info.rs

@@ -89,11 +89,17 @@ pub struct GPURequirements {
     pub device_extensions: Vec<String>,
 }
 
+/// Holds context settings for the FSR2 library
 #[cfg(feature = "fsr2")]
 #[derive(Debug)]
 pub struct Fsr2Settings {
+    /// The initial display size
     pub display_size: (u32, u32),
+    /// The initial maximum render size. If left to None, this is assumed to be equal to `display_size`.
+    /// Prefer setting this as low as possible to save memory.
     pub max_render_size: Option<(u32, u32)>,
+    /// Flags for FSR2 initialization. For more information on each possible value, see
+    /// <https://github.com/GPUOpen-Effects/FidelityFX-FSR2>
     pub flags: FfxFsr2InitializationFlagBits,
 }
 
@@ -143,6 +149,7 @@ pub struct AppSettings<'a, Window: WindowInterface> {
     pub scratch_ssbo_size: vk::DeviceSize,
     /// Whether to enable raytracing extensions.
     pub raytracing: bool,
+    /// FSR2 context settings.
     #[cfg(feature = "fsr2")]
     pub fsr2_settings: Fsr2Settings,
 }
@@ -271,18 +278,21 @@ impl<'a, Window: WindowInterface> AppBuilder<'a, Window> {
         self
     }
 
+    /// Set the initial FSR2 display size
     #[cfg(feature = "fsr2")]
     pub fn fsr2_display_size(mut self, width: u32, height: u32) -> Self {
         self.inner.fsr2_settings.display_size = (width, height);
         self
     }
 
+    /// Set the initial FSR2 maximum render size
     #[cfg(feature = "fsr2")]
     pub fn fsr2_max_render_size(mut self, width: u32, height: u32) -> Self {
         self.inner.fsr2_settings.max_render_size = Some((width, height));
         self
     }
 
+    /// Set the FSR2 context flags
     #[cfg(feature = "fsr2")]
     pub fn fsr2_flags(mut self, flags: FfxFsr2InitializationFlagBits) -> Self {
         self.inner.fsr2_settings.flags = flags;

src/core/device.rs

@@ -11,7 +11,7 @@ use anyhow::Result;
 use ash::extensions::{ext, khr};
 use ash::vk;
 #[cfg(feature = "fsr2")]
-use fsr2_sys::{FfxDimensions2D, FfxFsr2InitializationFlagBits};
+use fsr2_sys::FfxDimensions2D;
 
 use crate::{AppSettings, Error, PhysicalDevice, VkInstance, WindowInterface};
 #[cfg(feature = "fsr2")]
@@ -521,6 +521,7 @@ impl Device {
         self.inner.queue_families.len() == 1
     }
 
+    /// Get access to the FSR2 context. See [`Fsr2Context`](crate::fsr2::Fsr2Context)
     #[cfg(feature = "fsr2")]
     pub fn fsr2_context(&self) -> MutexGuard<ManuallyDrop<Fsr2Context>> {
         self.inner.fsr2_context.lock().unwrap()

src/fsr2/mod.rs

@@ -1,4 +1,5 @@
-use std::cmp::max;
+//! Exposes wrappers around the FSR2 library for supersampling, integrated with the phobos library.
+
 use std::ffi::c_void;
 use std::fmt::{Display, Formatter};
 use std::mem::MaybeUninit;
@@ -11,20 +12,23 @@ use fsr2_sys::{
     FfxDimensions2D, FfxErrorCode, FfxFloatCoords2D, FfxFsr2Context, ffxFsr2ContextCreate, FfxFsr2ContextDescription,
     ffxFsr2ContextDestroy, ffxFsr2ContextDispatch, FfxFsr2DispatchDescription, ffxFsr2GetInterfaceVK, ffxFsr2GetJitterOffset, ffxFsr2GetJitterPhaseCount,
     ffxFsr2GetRenderResolutionFromQualityMode, ffxFsr2GetScratchMemorySizeVK, FfxFsr2InitializationFlagBits, FfxFsr2InstanceFunctionPointerTableVk, FfxFsr2Interface, FfxFsr2MsgType,
-    FfxFsr2QualityMode, ffxGetCommandListVK, ffxGetDeviceVK, ffxGetTextureResourceVK, FfxResource, FfxResourceState, VkDevice,
-    VkGetDeviceProcAddrFunc, VkPhysicalDevice,
+    FfxFsr2QualityMode, ffxGetCommandListVK, ffxGetDeviceVK, ffxGetTextureResourceVK, FfxResource, FfxResourceState, VkDevice, VkPhysicalDevice,
 };
 use thiserror::Error;
 use widestring::{WideChar as wchar_t, WideCStr};
 
-use crate::{Allocator, ComputeSupport, DeletionQueue, ImageView, IncompleteCommandBuffer, VirtualResource};
+use crate::{Allocator, ComputeSupport, DeletionQueue, ImageView, IncompleteCommandBuffer};
 use crate::domain::ExecutionDomain;
 
+/// FSR2 API error, stores an error code that describes the cause of the error
 #[derive(Debug, Error)]
 pub struct Fsr2Error {
+    /// Error code with the cause of the FSR2 error.
     pub code: FfxErrorCode,
 }
 
+/// Check the FSR2 error code for an Ok status, and return Ok(()) in that case,
+/// or an error result instead.
 fn check_fsr2_error(code: FfxErrorCode) -> Result<()> {
     if code == FfxErrorCode::Ok {
         Ok(())
@@ -93,6 +97,7 @@ impl Display for Fsr2Error {
     }
 }
 
+/// Represents the initialized FSR2 context with its backend data.
 #[derive(Derivative)]
 #[derivative(Debug)]
 pub struct Fsr2Context {
@@ -128,6 +133,7 @@ pub struct Fsr2AutoReactiveDescription {
     pub auto_reactive_max: f32,
 }
 
+/// Stores resources needed to execute an FSR2 dispatch.
 #[derive(Debug, Clone)]
 pub struct Fsr2DispatchResources {
     /// Color buffer for the current frame, at render resolution.
@@ -146,6 +152,7 @@ pub struct Fsr2DispatchResources {
     pub output: ImageView,
 }
 
+/// Holds all settings for an FSR2 dispatch.
 #[derive(Debug, Clone)]
 pub struct Fsr2DispatchDescription {
     /// Subpixel jitter offset applied to the camera
@@ -186,7 +193,7 @@ extern "system" fn fsr2_message_callback(ty: FfxFsr2MsgType, message: *const wch
     }
 }
 
-pub struct Fsr2ContextCreateInfo<'a> {
+pub(crate) struct Fsr2ContextCreateInfo<'a> {
     pub instance: &'a ash::Instance,
     pub physical_device: vk::PhysicalDevice,
     pub device: vk::Device,
@@ -195,6 +202,7 @@ pub struct Fsr2ContextCreateInfo<'a> {
     pub display_size: FfxDimensions2D,
 }
 
+#[allow(dead_code)]
 struct ReleasedFsr2Context {
     pub context: Box<FfxFsr2Context>,
     pub backend: FfxFsr2Interface,
@@ -405,12 +413,14 @@ impl Fsr2Context {
         Ok(())
     }
 
-    pub fn jitter_phase_count(&mut self, render_width: u32, display_width: u32) -> i32 {
-        unsafe { ffxFsr2GetJitterPhaseCount(render_width, display_width) }
+    /// Get the number of jitter phases. Must be supplied with the current render width.
+    pub fn jitter_phase_count(&mut self, render_width: u32) -> i32 {
+        unsafe { ffxFsr2GetJitterPhaseCount(render_width, self.display_size.width) }
     }
 
-    pub fn jitter_offset(&mut self, render_width: u32, display_width: u32) -> Result<(f32, f32)> {
-        let phase_count = self.jitter_phase_count(render_width, display_width);
+    /// Get the jitter offset values for this frame, given the current render width.
+    pub fn jitter_offset(&mut self, render_width: u32) -> Result<(f32, f32)> {
+        let phase_count = self.jitter_phase_count(render_width);
         let index = self.current_frame % phase_count as usize;
         let mut jitter_x = 0.0;
         let mut jitter_y = 0.0;
@@ -419,6 +429,7 @@ impl Fsr2Context {
         Ok((jitter_x, jitter_y))
     }
 
+    /// Get the recommended render resolution based on a quality setting and the current display resolution.
     pub fn get_render_resolution(&mut self, quality_mode: FfxFsr2QualityMode) -> Result<FfxDimensions2D> {
         let mut render_width = 0;
         let mut render_height = 0;
@@ -438,6 +449,11 @@ impl Fsr2Context {
         })
     }
 
+    /// Set the display resolution to a new resolution. After doing this, you should also recreate the relevant
+    /// attachments with a new size based on the display size. This new size may not be greater than `max_render_size`.
+    /// If `max_render_size` is set to `None`, it is assumed to be equal to `display_size`.
+    /// Prefer setting `max_render_size` as low as possible to save memory.
+    /// If the new display size and max render size are the same as the old values, this function is a no-op.
     pub fn set_display_resolution(&mut self, display_size: FfxDimensions2D, max_render_size: Option<FfxDimensions2D>) -> Result<()> {
         // Create new context if something changed
         let max_render_size = max_render_size.unwrap_or(display_size);

src/graph/pass.rs

@@ -421,7 +421,7 @@ impl<'cb, D: ExecutionDomain, U, A: Allocator> PassBuilder<'cb, D, U, A> {
         self
     }
 
-    fn sample_optional_image(mut self, resource: &Option<VirtualResource>, stage: PipelineStage) -> Self {
+    fn sample_optional_image(self, resource: &Option<VirtualResource>, stage: PipelineStage) -> Self {
         match resource {
             None => self,
             Some(resource) => self.sample_image(resource, stage),
@@ -449,6 +449,7 @@ impl<'cb, D: ExecutionDomain, U, A: Allocator> PassBuilder<'cb, D, U, A> {
     }
 }
 
+/// Holds virtual resources needed to declare a FSR2 dispatch.
 #[cfg(feature = "fsr2")]
 #[derive(Debug, Clone)]
 pub struct Fsr2DispatchVirtualResources {
@@ -488,6 +489,8 @@ impl Fsr2DispatchVirtualResources {
         }
     }
 
+    /// Resolve all resources to their respective physical resources.
+    /// Fails if any resource resolve fails.
     pub fn resolve(&self, bindings: &PhysicalResourceBindings) -> Result<Fsr2DispatchResources> {
         Ok(Fsr2DispatchResources {
             color: Self::resolve_image_resource(&self.color, bindings)?,

src/pipeline/raytracing.rs

@@ -68,6 +68,7 @@ pub struct SBTEntry {
 }
 
 /// A ShaderBindingTable resource. This can be derived from the ray tracing pipeline.
+#[allow(dead_code)]
 #[derive(Debug)]
 pub struct ShaderBindingTable<A: Allocator> {
     pub(crate) buffer: Buffer<A>,