diff --git a/Cargo.toml b/Cargo.toml index f4d0c82..ab6c48e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -25,7 +25,6 @@ x11 = ["bytemuck", "nix", "x11rb", "x11-dl"] [dependencies] log = "0.4.17" raw-window-handle = "0.5.0" -thiserror = "1.0.30" [target.'cfg(all(unix, not(any(target_vendor = "apple", target_os = "android", target_os = "redox"))))'.dependencies] bytemuck = { version = "1.12.3", optional = true } diff --git a/src/error.rs b/src/error.rs index 700f87b..866a2db 100644 --- a/src/error.rs +++ b/src/error.rs @@ -2,52 +2,141 @@ use raw_window_handle::{RawDisplayHandle, RawWindowHandle}; use std::error::Error; use std::fmt; use std::num::NonZeroU32; -use thiserror::Error; -#[derive(Error, Debug)] -#[allow(missing_docs)] // TODO +#[derive(Debug)] #[non_exhaustive] +/// A sum type of all of the errors that can occur during the operation of this crate. pub enum SoftBufferError { - #[error( - "The provided display returned an unsupported platform: {human_readable_display_platform_name}." - )] + /// The [`RawDisplayHandle`] passed into [`Context::new`] is not supported by this crate. + /// + /// [`RawDisplayHandle`]: raw_window_handle::RawDisplayHandle + /// [`Context::new`]: crate::Context::new UnsupportedDisplayPlatform { + /// The platform name of the display that was passed into [`Context::new`]. + /// + /// This is a human-readable string that describes the platform of the display that was + /// passed into [`Context::new`]. The value is not guaranteed to be stable and this + /// exists for debugging purposes only. + /// + /// [`Context::new`]: crate::Context::new human_readable_display_platform_name: &'static str, + + /// The [`RawDisplayHandle`] that was passed into [`Context::new`]. + /// + /// [`RawDisplayHandle`]: raw_window_handle::RawDisplayHandle + /// [`Context::new`]: crate::Context::new display_handle: RawDisplayHandle, }, - #[error( - "The provided window returned an unsupported platform: {human_readable_window_platform_name}, {human_readable_display_platform_name}." - )] + + /// The [`RawWindowHandle`] passed into [`Surface::new`] is not supported by this crate. + /// + /// [`RawWindowHandle`]: raw_window_handle::RawWindowHandle + /// [`Surface::new`]: crate::Surface::new UnsupportedWindowPlatform { + /// The platform name of the window that was passed into [`Surface::new`]. + /// + /// This is a human-readable string that describes the platform of the window that was + /// passed into [`Surface::new`]. The value is not guaranteed to be stable and this + /// exists for debugging purposes only. + /// + /// [`Surface::new`]: crate::Surface::new human_readable_window_platform_name: &'static str, + + /// The platform name of the display used by the [`Context`]. + /// + /// It is possible for a window to be created on a different type of display than the + /// display that was passed into [`Context::new`]. This is a human-readable string that + /// describes the platform of the display that was passed into [`Context::new`]. The value + /// is not guaranteed to be stable and this exists for debugging purposes only. + /// + /// [`Context`]: crate::Context + /// [`Context::new`]: crate::Context::new human_readable_display_platform_name: &'static str, + + /// The [`RawWindowHandle`] that was passed into [`Surface::new`]. + /// + /// [`RawWindowHandle`]: raw_window_handle::RawWindowHandle + /// [`Surface::new`]: crate::Surface::new window_handle: RawWindowHandle, }, - #[error("The provided window handle is null.")] + /// The [`RawWindowHandle`] passed into [`Surface::new`] is missing necessary fields. + /// + /// [`RawWindowHandle`]: raw_window_handle::RawWindowHandle + /// [`Surface::new`]: crate::Surface::new IncompleteWindowHandle, - #[error("The provided display handle is null.")] + /// The [`RawDisplayHandle`] passed into [`Context::new`] is missing necessary fields. + /// + /// [`RawDisplayHandle`]: raw_window_handle::RawDisplayHandle + /// [`Context::new`]: crate::Context::new IncompleteDisplayHandle, - #[error("Surface size {width}x{height} out of range for backend.")] + /// The provided size is outside of the range supported by the backend. SizeOutOfRange { + /// The width that was out of range. width: NonZeroU32, + + /// The height that was out of range. height: NonZeroU32, }, - #[error( - "Damage rect {}x{} at ({}, {}) out of range for backend.", .rect.width, .rect.height, .rect.x, .rect.y, - )] - DamageOutOfRange { rect: crate::Rect }, + /// The provided damage rect is outside of the range supported by the backend. + DamageOutOfRange { + /// The damage rect that was out of range. + rect: crate::Rect, + }, - #[error("Platform error")] + /// A platform-specific backend error occurred. + /// + /// The first field provides a human-readable description of the error. The second field + /// provides the actual error that occurred. Note that the second field is, under the hood, + /// a private wrapper around the actual error, preventing the user from downcasting to the + /// actual error type. PlatformError(Option, Option>), - #[error("This function is unimplemented on this platform")] + /// This function is unimplemented on this platform. Unimplemented, } +impl fmt::Display for SoftBufferError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::UnsupportedDisplayPlatform { + human_readable_display_platform_name, + display_handle, + } => write!( + f, + "The provided display returned an unsupported platform: {}.\nDisplay handle: {:?}", + human_readable_display_platform_name, display_handle + ), + Self::UnsupportedWindowPlatform { + human_readable_window_platform_name, + human_readable_display_platform_name, + window_handle, + } => write!( + f, + "The provided window returned an unsupported platform: {}, {}.\nWindow handle: {:?}", + human_readable_window_platform_name, human_readable_display_platform_name, window_handle + ), + Self::IncompleteWindowHandle => write!(f, "The provided window handle is null."), + Self::IncompleteDisplayHandle => write!(f, "The provided display handle is null."), + Self::SizeOutOfRange { width, height } => write!( + f, + "Surface size {width}x{height} out of range for backend.", + ), + Self::PlatformError(msg, None) => write!(f, "Platform error: {msg:?}"), + Self::PlatformError(msg, Some(err)) => write!(f, "Platform error: {msg:?}: {err}"), + Self::DamageOutOfRange { rect } => write!( + f, + "Damage rect {}x{} at ({}, {}) out of range for backend.", + rect.width, rect.height, rect.x, rect.y + ), + Self::Unimplemented => write!(f, "This function is unimplemented on this platform."), + } + } +} + /// Convenient wrapper to cast errors into SoftBufferError. pub(crate) trait SwResultExt { fn swbuf_err(self, msg: impl Into) -> Result;