From 1640e201e931021da56a6a5d21d722daf7c62b52 Mon Sep 17 00:00:00 2001 From: Andrea Ciliberti Date: Fri, 28 Jul 2023 18:02:17 +0200 Subject: [PATCH] Finishing touches after complete revision --- ctru-rs/src/console.rs | 2 +- ctru-rs/src/lib.rs | 6 +++--- ctru-rs/src/linear.rs | 4 ++-- ctru-rs/src/services/apt.rs | 2 +- ctru-rs/src/services/cam.rs | 11 +++++------ ctru-rs/src/services/cfgu.rs | 2 +- ctru-rs/src/services/fs.rs | 12 +++++------ ctru-rs/src/services/gfx.rs | 33 +++++++++++++++++++++---------- ctru-rs/src/services/hid.rs | 2 +- ctru-rs/src/services/ndsp/mod.rs | 22 ++++++++++----------- ctru-rs/src/services/ndsp/wave.rs | 16 +++++++-------- 11 files changed, 62 insertions(+), 50 deletions(-) diff --git a/ctru-rs/src/console.rs b/ctru-rs/src/console.rs index 32fbe10..ca3681d 100644 --- a/ctru-rs/src/console.rs +++ b/ctru-rs/src/console.rs @@ -127,7 +127,7 @@ impl<'screen> Console<'screen> { /// /// Any previously selected console will be unhooked and will not show the `stdout` output. /// - /// # Example + /// # Example /// /// ```no_run /// # use std::error::Error; diff --git a/ctru-rs/src/lib.rs b/ctru-rs/src/lib.rs index 3686578..ecc7dd9 100644 --- a/ctru-rs/src/lib.rs +++ b/ctru-rs/src/lib.rs @@ -3,7 +3,7 @@ //! # About //! //! This crate behaves as the main tool to access system-specific functionality on the Nintendo 3DS when developing homebrew software in Rust. -//! Thanks to it, developers can access the underlying system services and the console's hardware to develop userland applications +//! Thanks to it, developers can develop userland applications by accessing access the underlying system services and the console's hardware //! (such as [HID devices](crate::services::hid), [network capabilities](crate::services::soc), [graphics](crate::services::gfx), [built-in cameras](crate::services::cam), etc.). //! //! Among these features, [`ctru-rs`](crate) also automatically includes functionality to properly integrate the Rust `std` with the console's operating system, @@ -13,7 +13,7 @@ //! //! Thoroughly read the official [`ctru-rs` wiki](https://github.com/rust3ds/ctru-rs/wiki) which guides you through the setup needed to install the required toolchain and helpful tools. //! After following the guide and understanding the many quirks of the Nintendo 3DS homebrew development environment, you can create a new project by including this crate as a dependency -//! of your project in your `Cargo.toml` manifest and build your binaries either manually (for the `armv6k-nintendo-3ds` target) or via [`cargo-3ds`](https://github.com/rust3ds/cargo-3ds). +//! in your `Cargo.toml` manifest and build your binaries either manually (for the `armv6k-nintendo-3ds` target) or via [`cargo-3ds`](https://github.com/rust3ds/cargo-3ds). #![crate_type = "rlib"] #![crate_name = "ctru"] @@ -60,7 +60,7 @@ macro_rules! from_impl { /// /// # Notes /// -/// When ´test´ is enabled, this function will not do anything, as it should be overridden by the ´test´ environment. +/// When `test` is enabled, this function will not do anything, as its behaviour should be overridden by the `test` environment. pub fn use_panic_handler() { #[cfg(not(test))] panic_hook_setup(); diff --git a/ctru-rs/src/linear.rs b/ctru-rs/src/linear.rs index 8c0639a..269e5dd 100644 --- a/ctru-rs/src/linear.rs +++ b/ctru-rs/src/linear.rs @@ -1,11 +1,11 @@ //! LINEAR memory allocator. //! //! LINEAR memory is a sector of the 3DS' RAM that binds virtual addresses exactly to the physical address. -//! As such, it is used for fast and safe memory sharing between hardware processors (such as the GPU and the DSP). +//! As such, it is used for fast and safe memory sharing between different hardware components (such as the GPU and the DSP processor). //! //! # Additional Resources //! -//! -
+//! - //! - use std::alloc::{AllocError, Allocator, Layout}; diff --git a/ctru-rs/src/services/apt.rs b/ctru-rs/src/services/apt.rs index 1fba0e5..b30be85 100644 --- a/ctru-rs/src/services/apt.rs +++ b/ctru-rs/src/services/apt.rs @@ -67,7 +67,7 @@ impl Apt { unsafe { ctru_sys::aptMainLoop() } } - /// Sets (in percentage) the amount of time to lend to the application thread spawned on the syscore (core #1). + /// Set (in percentage) the amount of time to lend to the application thread spawned on the syscore (core #1). /// /// # Notes /// diff --git a/ctru-rs/src/services/cam.rs b/ctru-rs/src/services/cam.rs index dd4437b..23316c1 100644 --- a/ctru-rs/src/services/cam.rs +++ b/ctru-rs/src/services/cam.rs @@ -302,8 +302,7 @@ impl Camera for OutwardLeftCam { pub struct BothOutwardCam; impl BothOutwardCam { - /// Sets whether to enable or disable synchronization - /// of brightness for both left and right cameras + /// Set whether to enable or disable brightness synchronization between the two cameras. #[doc(alias = "CAMU_SetBrightnessSynchronization")] pub fn set_brightness_synchronization( &mut self, @@ -560,7 +559,7 @@ pub trait Camera { } } - /// Sets whether auto white balance is enabled or disabled for the camera + /// Set whether auto white balance is enabled or disabled for the camera. #[doc(alias = "CAMU_SetAutoWhiteBalance")] fn set_auto_white_balance(&mut self, enabled: bool) -> crate::Result<()> { unsafe { @@ -659,7 +658,7 @@ pub trait Camera { } } - /// Sets the photo mode of the camera. + /// Set the photo mode of the camera. #[doc(alias = "CAMU_SetPhotoMode")] fn set_photo_mode(&mut self, photo_mode: PhotoMode) -> crate::Result<()> { unsafe { @@ -671,7 +670,7 @@ pub trait Camera { } } - /// Sets the effect of the camera. + /// Set the effect of the camera. /// /// # Notes /// @@ -975,7 +974,7 @@ impl Cam { } } - /// Plays the specified sound based on the [`ShutterSound`] argument + /// Play the specified sound based on the [`ShutterSound`] argument /// /// # Notes /// diff --git a/ctru-rs/src/services/cfgu.rs b/ctru-rs/src/services/cfgu.rs index 252b11f..d63f227 100644 --- a/ctru-rs/src/services/cfgu.rs +++ b/ctru-rs/src/services/cfgu.rs @@ -1,6 +1,6 @@ //! System Configuration service. //! -//! This module contains basic methods to retrieve and change configuration from the console. +//! This module contains basic methods to retrieve the console's system configuration. use crate::error::ResultCode; diff --git a/ctru-rs/src/services/fs.rs b/ctru-rs/src/services/fs.rs index b7636eb..f168e32 100644 --- a/ctru-rs/src/services/fs.rs +++ b/ctru-rs/src/services/fs.rs @@ -542,7 +542,7 @@ impl OpenOptions { Self::default() } - /// Sets the option for read access. + /// Set the option for read access. /// /// This option, when true, will indicate that the file should be /// `read`-able if opened. @@ -551,7 +551,7 @@ impl OpenOptions { self } - /// Sets the option for write access. + /// Set the option for write access. /// /// This option, when true, will indicate that the file should be /// `write`-able if opened. @@ -563,7 +563,7 @@ impl OpenOptions { self } - /// Sets the option for the append mode. + /// Set the option for the append mode. /// /// This option, when true, means that writes will append to a file instead /// of overwriting previous contents. Note that setting .write(true).append(true) @@ -575,7 +575,7 @@ impl OpenOptions { self } - /// Sets the option for truncating a previous file. + /// Set the option for truncating a previous file. /// /// If a file is successfully opened with this option set it will truncate /// the file to 0 length if it already exists. @@ -586,7 +586,7 @@ impl OpenOptions { self } - /// Sets the option for creating a new file. + /// Set the option for creating a new file. /// /// This option indicates whether a new file will be created /// if the file does not yet already @@ -598,7 +598,7 @@ impl OpenOptions { self } - /// Sets which archive the file is to be opened in. + /// Set which archive the file is to be opened in. /// /// Failing to pass in an archive will result in the file failing to open. pub fn archive(&mut self, archive: &Archive) -> &mut OpenOptions { diff --git a/ctru-rs/src/services/gfx.rs b/ctru-rs/src/services/gfx.rs index 0769b81..e1b27c7 100644 --- a/ctru-rs/src/services/gfx.rs +++ b/ctru-rs/src/services/gfx.rs @@ -55,15 +55,6 @@ pub trait Screen: private::Sealed { } } - /// Sets whether to use double buffering. Enabled by default. - /// - /// [`Swap::swap_buffers`] must be called after this function for the configuration - /// change to take effect. - #[doc(alias = "gfxSetDoubleBuffering")] - fn set_double_buffering(&mut self, enabled: bool) { - unsafe { ctru_sys::gfxSetDoubleBuffering(self.as_raw(), enabled) } - } - /// Gets the framebuffer format. #[doc(alias = "gfxGetScreenFormat")] fn framebuffer_format(&self) -> FramebufferFormat { @@ -106,11 +97,21 @@ pub trait Swap: private::Sealed { /// /// Even if double buffering is disabled, "swapping" the buffers has the side effect /// of committing any configuration changes to the buffers (e.g. [`TopScreen::set_wide_mode()`], - /// [`Screen::set_framebuffer_format()`], [`Screen::set_double_buffering()`]), so it should still be used. + /// [`Screen::set_framebuffer_format()`], [`Swap::set_double_buffering()`]), so it should still be used. /// /// This should be called once per frame at most. #[doc(alias = "gfxScreenSwapBuffers")] fn swap_buffers(&mut self); + + /// Set whether to use double buffering. + /// + /// # Notes + /// + /// Double buffering is enabled by default. + /// [`Swap::swap_buffers`] must be called after this function for the configuration + /// change to take effect. + #[doc(alias = "gfxSetDoubleBuffering")] + fn set_double_buffering(&mut self, enabled: bool); } impl Swap for TopScreen3D<'_> { @@ -119,6 +120,10 @@ impl Swap for TopScreen3D<'_> { ctru_sys::gfxScreenSwapBuffers(ctru_sys::GFX_TOP, true); } } + + fn set_double_buffering(&mut self, enabled: bool) { + unsafe { ctru_sys::gfxSetDoubleBuffering(ctru_sys::GFX_TOP, enabled) } + } } impl Swap for TopScreen { @@ -127,6 +132,10 @@ impl Swap for TopScreen { ctru_sys::gfxScreenSwapBuffers(ctru_sys::GFX_TOP, false); } } + + fn set_double_buffering(&mut self, enabled: bool) { + unsafe { ctru_sys::gfxSetDoubleBuffering(ctru_sys::GFX_TOP, enabled) } + } } impl Swap for BottomScreen { @@ -135,6 +144,10 @@ impl Swap for BottomScreen { ctru_sys::gfxScreenSwapBuffers(ctru_sys::GFX_BOTTOM, false); } } + + fn set_double_buffering(&mut self, enabled: bool) { + unsafe { ctru_sys::gfxSetDoubleBuffering(ctru_sys::GFX_BOTTOM, enabled) } + } } /// A screen with buffers that can be flushed. diff --git a/ctru-rs/src/services/hid.rs b/ctru-rs/src/services/hid.rs index fc73612..c790131 100644 --- a/ctru-rs/src/services/hid.rs +++ b/ctru-rs/src/services/hid.rs @@ -142,7 +142,7 @@ impl Hid { /// hid.scan_input(); /// /// if hid.keys_down().contains(KeyPad::A) { - /// println!("You just pressed the A button!") + /// println!("You have pressed the A button!") /// } /// # /// # Ok(()) diff --git a/ctru-rs/src/services/ndsp/mod.rs b/ctru-rs/src/services/ndsp/mod.rs index fc76584..eb9328d 100644 --- a/ctru-rs/src/services/ndsp/mod.rs +++ b/ctru-rs/src/services/ndsp/mod.rs @@ -540,7 +540,7 @@ impl Channel<'_> { unsafe { ctru_sys::ndspChnIirMonoSetEnable(self.id.into(), enable) }; } - /// Sets the monopole to be a high pass filter. + /// Set the monopole to be a high pass filter. /// /// # Notes /// @@ -550,7 +550,7 @@ impl Channel<'_> { unsafe { ctru_sys::ndspChnIirMonoSetParamsHighPassFilter(self.id.into(), cut_off_freq) }; } - /// Sets the monopole to be a low pass filter. + /// Set the monopole to be a low pass filter. /// /// # Notes /// @@ -566,7 +566,7 @@ impl Channel<'_> { unsafe { ctru_sys::ndspChnIirBiquadSetEnable(self.id.into(), enable) }; } - /// Sets the biquad to be a high pass filter. + /// Set the biquad to be a high pass filter. #[doc(alias = "ndspChnIirBiquadSetParamsHighPassFilter")] pub fn iir_biquad_set_params_high_pass_filter(&mut self, cut_off_freq: f32, quality: f32) { unsafe { @@ -574,7 +574,7 @@ impl Channel<'_> { }; } - /// Sets the biquad to be a low pass filter. + /// Set the biquad to be a low pass filter. #[doc(alias = "ndspChnIirBiquadSetParamsLowPassFilter")] pub fn iir_biquad_set_params_low_pass_filter(&mut self, cut_off_freq: f32, quality: f32) { unsafe { @@ -582,7 +582,7 @@ impl Channel<'_> { }; } - /// Sets the biquad to be a notch filter. + /// Set the biquad to be a notch filter. #[doc(alias = "ndspChnIirBiquadSetParamsNotchFilter")] pub fn iir_biquad_set_params_notch_filter(&mut self, notch_freq: f32, quality: f32) { unsafe { @@ -590,7 +590,7 @@ impl Channel<'_> { }; } - /// Sets the biquad to be a band pass filter. + /// Set the biquad to be a band pass filter. #[doc(alias = "ndspChnIirBiquadSetParamsBandPassFilter")] pub fn iir_biquad_set_params_band_pass_filter(&mut self, mid_freq: f32, quality: f32) { unsafe { @@ -598,7 +598,7 @@ impl Channel<'_> { }; } - /// Sets the biquad to be a peaking equalizer. + /// Set the biquad to be a peaking equalizer. #[doc(alias = "ndspChnIirBiquadSetParamsPeakingEqualizer")] pub fn iir_biquad_set_params_peaking_equalizer( &mut self, @@ -681,7 +681,7 @@ impl AudioMix { (self.raw[index], self.raw[index + 1]) } - /// Sets the values for the "front" volume mix (left and right channel). + /// Set the values for the "front" volume mix (left and right channel). /// /// # Notes /// @@ -692,7 +692,7 @@ impl AudioMix { self.raw[1] = right; } - /// Sets the values for the "back" volume mix (left and right channel). + /// Set the values for the "back" volume mix (left and right channel). /// /// # Notes /// @@ -703,7 +703,7 @@ impl AudioMix { self.raw[3] = right; } - /// Sets the values for the "front" volume mix (left and right channel) for the specified auxiliary output device (either 0 or 1). + /// Set the values for the "front" volume mix (left and right channel) for the specified auxiliary output device (either 0 or 1). /// /// # Notes /// @@ -720,7 +720,7 @@ impl AudioMix { self.raw[index + 1] = right; } - /// Sets the values for the "back" volume mix (left and right channel) for the specified auxiliary output device (either 0 or 1). + /// Set the values for the "back" volume mix (left and right channel) for the specified auxiliary output device (either 0 or 1). /// /// # Notes /// diff --git a/ctru-rs/src/services/ndsp/wave.rs b/ctru-rs/src/services/ndsp/wave.rs index 72cee96..9171278 100644 --- a/ctru-rs/src/services/ndsp/wave.rs +++ b/ctru-rs/src/services/ndsp/wave.rs @@ -32,7 +32,7 @@ pub enum Status { } impl Wave { - /// Build a new playable wave object from a raw buffer on [LINEAR memory](`crate::linear`) and a some info. + /// Build a new playable wave object from a raw buffer on [LINEAR memory](`crate::linear`) and some info. /// /// # Example /// @@ -86,12 +86,12 @@ impl Wave { } } - /// Return a slice to the audio data (on the LINEAR memory). + /// Returns a slice to the audio data (on the LINEAR memory). pub fn get_buffer(&self) -> &[u8] { &self.buffer } - /// Return a mutable slice to the audio data (on the LINEAR memory). + /// Returns a mutable slice to the audio data (on the LINEAR memory). /// /// # Errors /// @@ -106,7 +106,7 @@ impl Wave { } } - /// Return this wave's playback status. + /// Returns this wave's playback status. /// /// # Example /// @@ -130,7 +130,7 @@ impl Wave { self.raw_data.status.try_into().unwrap() } - /// Get the amounts of samples *read* by the NDSP process. + /// Returns the amount of samples *read* by the NDSP process. /// /// # Notes /// @@ -139,7 +139,7 @@ impl Wave { self.raw_data.nsamples as usize } - /// Get the format of the audio data. + /// Returns the format of the audio data. pub fn format(&self) -> AudioFormat { self.audio_format } @@ -152,11 +152,11 @@ impl Wave { } /// Set the amount of samples to be read. - /// This function doesn't resize the internal buffer. /// /// # Note + /// /// - /// Operations of this kind are particularly useful to allocate memory pools + /// This function doesn't resize the internal buffer. Operations of this kind are particularly useful to allocate memory pools /// for VBR (Variable BitRate) formats, like OGG Vorbis. /// /// # Errors