From 1fe11ce5de34f3236aebbeb9ef0ce39f40bda100 Mon Sep 17 00:00:00 2001 From: Ian Chamberlain Date: Sat, 21 Oct 2023 13:57:29 -0400 Subject: [PATCH] Add a bunch of doc aliases for unsafe APIs --- citro3d/src/attrib.rs | 4 ++++ citro3d/src/buffer.rs | 4 ++++ citro3d/src/lib.rs | 16 ++++++++++++---- citro3d/src/math/fvec.rs | 3 ++- citro3d/src/math/matrix.rs | 7 +++++++ citro3d/src/math/ops.rs | 6 ++++++ citro3d/src/math/projection.rs | 2 ++ citro3d/src/render.rs | 9 +++++++++ citro3d/src/render/transfer.rs | 1 + citro3d/src/shader.rs | 10 ++++++++++ 10 files changed, 57 insertions(+), 5 deletions(-) diff --git a/citro3d/src/attrib.rs b/citro3d/src/attrib.rs index 22003df..f96ed44 100644 --- a/citro3d/src/attrib.rs +++ b/citro3d/src/attrib.rs @@ -10,6 +10,7 @@ use std::mem::MaybeUninit; /// Vertex attribute info. This struct describes how vertex buffers are /// layed out and used (i.e. the shape of the vertex data). #[derive(Debug)] +#[doc(alias = "C3D_AttrInfo")] pub struct Info(pub(crate) citro3d_sys::C3D_AttrInfo); /// A shader input register, usually corresponding to a single vertex attribute @@ -43,6 +44,7 @@ pub struct Index(u8); /// The data format of an attribute. #[repr(u32)] #[derive(Debug, Clone, Copy)] +#[doc(alias = "GPU_FORMATS")] pub enum Format { /// A signed byte, i.e. [`i8`]. Byte = ctru_sys::GPU_BYTE, @@ -60,6 +62,7 @@ unsafe impl Sync for Info {} unsafe impl Send for Info {} impl Default for Info { + #[doc(alias = "AttrInfo_Init")] fn default() -> Self { let mut raw = MaybeUninit::zeroed(); let raw = unsafe { @@ -100,6 +103,7 @@ impl Info { /// /// * If `count > 4` /// * If this attribute info already has the maximum number of attributes. + #[doc(alias = "AttrInfo_AddLoader")] pub fn add_loader( &mut self, register: Register, diff --git a/citro3d/src/buffer.rs b/citro3d/src/buffer.rs index b86be01..b959f83 100644 --- a/citro3d/src/buffer.rs +++ b/citro3d/src/buffer.rs @@ -10,6 +10,7 @@ use crate::attrib; /// Vertex buffer info. This struct is used to describe the shape of the buffer /// data to be sent to the GPU for rendering. #[derive(Debug)] +#[doc(alias = "C3D_BufInfo")] pub struct Info(pub(crate) citro3d_sys::C3D_BufInfo); /// A slice of buffer data. This borrows the buffer data and can be thought of @@ -50,6 +51,7 @@ impl Slice<'_> { /// The geometric primitive to draw (i.e. what shapes the buffer data describes). #[repr(u32)] #[derive(Debug, Clone, Copy)] +#[doc(alias = "GPU_Primitive_t")] pub enum Primitive { /// Draw triangles (3 vertices per triangle). Triangles = ctru_sys::GPU_TRIANGLES, @@ -63,6 +65,7 @@ pub enum Primitive { } impl Default for Info { + #[doc(alias = "BufInfo_Init")] fn default() -> Self { let mut info = MaybeUninit::zeroed(); let info = unsafe { @@ -100,6 +103,7 @@ impl Info { /// /// * if `vbo_data` is not allocated with the [`ctru::linear`] allocator /// * if the maximum number (12) of VBOs are already registered + #[doc(alias = "BufInfo_Add")] pub fn add<'this, 'vbo, 'idx, T>( &'this mut self, vbo_data: &'vbo [T], diff --git a/citro3d/src/lib.rs b/citro3d/src/lib.rs index 985db2a..a100e31 100644 --- a/citro3d/src/lib.rs +++ b/citro3d/src/lib.rs @@ -48,6 +48,7 @@ impl Instance { /// # Errors /// /// Fails if `citro3d` cannot be initialized. + #[doc(alias = "C3D_Init")] pub fn with_cmdbuf_size(size: usize) -> Result { if unsafe { citro3d_sys::C3D_Init(size) } { Ok(Self) @@ -61,6 +62,7 @@ impl Instance { /// # Errors /// /// Fails if the given target cannot be used for drawing. + #[doc(alias = "C3D_FrameDrawOn")] pub fn select_render_target(&mut self, target: &render::Target<'_>) -> Result<()> { let _ = self; if unsafe { citro3d_sys::C3D_FrameDrawOn(target.as_raw()) } { @@ -72,13 +74,13 @@ impl Instance { /// Render a frame. The passed in function/closure can mutate the instance, /// such as to [select a render target](Self::select_render_target). + #[doc(alias = "C3D_FrameBegin")] + #[doc(alias = "C3D_FrameEnd")] pub fn render_frame_with(&mut self, f: impl FnOnce(&mut Self)) { unsafe { citro3d_sys::C3D_FrameBegin( // TODO: begin + end flags should be configurable - citro3d_sys::C3D_FRAME_SYNCDRAW - .try_into() - .expect("const is valid u8"), + citro3d_sys::C3D_FRAME_SYNCDRAW.try_into().unwrap(), ); } @@ -91,12 +93,14 @@ impl Instance { /// Get the buffer info being used, if it exists. Note that the resulting /// [`buffer::Info`] is copied from the one currently in use. + #[doc(alias = "C3D_GetBufInfo")] pub fn buffer_info(&self) -> Option { let raw = unsafe { citro3d_sys::C3D_GetBufInfo() }; buffer::Info::copy_from(raw) } /// Set the buffer info to use for any following draw calls. + #[doc(alias = "C3D_SetBufInfo")] pub fn set_buffer_info(&mut self, buffer_info: &buffer::Info) { let raw: *const _ = &buffer_info.0; // SAFETY: C3D_SetBufInfo actually copies the pointee instead of mutating it. @@ -105,19 +109,22 @@ impl Instance { /// Get the attribute info being used, if it exists. Note that the resulting /// [`attrib::Info`] is copied from the one currently in use. + #[doc(alias = "C3D_GetAttrInfo")] pub fn attr_info(&self) -> Option { let raw = unsafe { citro3d_sys::C3D_GetAttrInfo() }; attrib::Info::copy_from(raw) } /// Set the attribute info to use for any following draw calls. + #[doc(alias = "C3D_SetAttrInfo")] pub fn set_attr_info(&mut self, attr_info: &attrib::Info) { let raw: *const _ = &attr_info.0; // SAFETY: C3D_SetAttrInfo actually copies the pointee instead of mutating it. unsafe { citro3d_sys::C3D_SetAttrInfo(raw.cast_mut()) }; } - /// Draw the specified primitivearrays. The + /// Render primitives from the current vertex array buffer. + #[doc(alias = "C3D_DrawArrays")] pub fn draw_arrays(&mut self, primitive: buffer::Primitive, index: buffer::Slice) { self.set_buffer_info(index.info()); @@ -170,6 +177,7 @@ impl Instance { } impl Drop for Instance { + #[doc(alias = "C3D_Fini")] fn drop(&mut self) { unsafe { citro3d_sys::C3D_Fini(); diff --git a/citro3d/src/math/fvec.rs b/citro3d/src/math/fvec.rs index 183f412..37e66c7 100644 --- a/citro3d/src/math/fvec.rs +++ b/citro3d/src/math/fvec.rs @@ -4,6 +4,7 @@ use std::fmt; /// A vector of `f32`s. #[derive(Clone, Copy)] +#[doc(alias = "C3D_FVec")] pub struct FVec(pub(crate) citro3d_sys::C3D_FVec); /// A 3-vector of `f32`s. @@ -130,7 +131,7 @@ impl FVec4 { /// let v = FVec4::new(1.0, 2.0, 2.0, 4.0); /// assert_abs_diff_eq!(v.normalize(), FVec4::new(0.2, 0.4, 0.4, 0.8)); /// ``` - #[doc(alias = "FVec3_Normalize")] + #[doc(alias = "FVec4_Normalize")] pub fn normalize(self) -> Self { Self(unsafe { citro3d_sys::FVec4_Normalize(self.0) }) } diff --git a/citro3d/src/math/matrix.rs b/citro3d/src/math/matrix.rs index 7215611..e07f777 100644 --- a/citro3d/src/math/matrix.rs +++ b/citro3d/src/math/matrix.rs @@ -109,31 +109,37 @@ impl Matrix { /// Translate a transformation matrix by the given amounts in the X, Y, and Z /// directions. + #[doc(alias = "Mtx_Translate")] pub fn translate(&mut self, x: f32, y: f32, z: f32) { unsafe { citro3d_sys::Mtx_Translate(self.as_mut(), x, y, z, false) } } /// Scale a transformation matrix by the given amounts in the X, Y, and Z directions. + #[doc(alias = "Mtx_Scale")] pub fn scale(&mut self, x: f32, y: f32, z: f32) { unsafe { citro3d_sys::Mtx_Scale(self.as_mut(), x, y, z) } } /// Rotate a transformation matrix by the given angle around the given axis. + #[doc(alias = "Mtx_Rotate")] pub fn rotate(&mut self, axis: FVec3, angle: f32) { unsafe { citro3d_sys::Mtx_Rotate(self.as_mut(), axis.0, angle, false) } } /// Rotate a transformation matrix by the given angle around the X axis. + #[doc(alias = "Mtx_RotateX")] pub fn rotate_x(&mut self, angle: f32) { unsafe { citro3d_sys::Mtx_RotateX(self.as_mut(), angle, false) } } /// Rotate a transformation matrix by the given angle around the Y axis. + #[doc(alias = "Mtx_RotateY")] pub fn rotate_y(&mut self, angle: f32) { unsafe { citro3d_sys::Mtx_RotateY(self.as_mut(), angle, false) } } /// Rotate a transformation matrix by the given angle around the Z axis. + #[doc(alias = "Mtx_RotateZ")] pub fn rotate_z(&mut self, angle: f32) { unsafe { citro3d_sys::Mtx_RotateZ(self.as_mut(), angle, false) } } @@ -193,6 +199,7 @@ impl Matrix4 { /// Construct a 3D transformation matrix for a camera, given its position, /// target, and upward direction. + #[doc(alias = "Mtx_LookAt")] pub fn looking_at( camera_position: FVec3, camera_target: FVec3, diff --git a/citro3d/src/math/ops.rs b/citro3d/src/math/ops.rs index 311c473..3d487ea 100644 --- a/citro3d/src/math/ops.rs +++ b/citro3d/src/math/ops.rs @@ -129,6 +129,7 @@ impl AbsDiffEq for FVec { impl, const M: usize, const N: usize> Add for &Matrix { type Output = ::Target; + #[doc(alias = "Mtx_Add")] fn add(self, rhs: Rhs) -> Self::Output { let mut out = MaybeUninit::uninit(); unsafe { @@ -141,6 +142,7 @@ impl, const M: usize, const N: usize> Add for &Matrix, const M: usize, const N: usize> Sub for &Matrix { type Output = ::Target; + #[doc(alias = "Mtx_Subtract")] fn sub(self, rhs: Rhs) -> Self::Output { let mut out = MaybeUninit::uninit(); unsafe { @@ -153,6 +155,7 @@ impl, const M: usize, const N: usize> Sub for &Matrix Mul<&Matrix> for &Matrix { type Output = Matrix; + #[doc(alias = "Mtx_Multiply")] fn mul(self, rhs: &Matrix) -> Self::Output { let mut out = MaybeUninit::uninit(); unsafe { @@ -173,6 +176,7 @@ impl Mul> for &Matr impl Mul for &Matrix3 { type Output = FVec3; + #[doc(alias = "Mtx_MultiplyFVec3")] fn mul(self, rhs: FVec3) -> Self::Output { FVec(unsafe { citro3d_sys::Mtx_MultiplyFVec3(self.as_raw(), rhs.0) }) } @@ -181,6 +185,7 @@ impl Mul for &Matrix3 { impl Mul for &Matrix4 { type Output = FVec4; + #[doc(alias = "Mtx_MultiplyFVec4")] fn mul(self, rhs: FVec4) -> Self::Output { FVec(unsafe { citro3d_sys::Mtx_MultiplyFVec4(self.as_raw(), rhs.0) }) } @@ -189,6 +194,7 @@ impl Mul for &Matrix4 { impl Mul for &Matrix<4, 3> { type Output = FVec4; + #[doc(alias = "Mtx_MultiplyFVecH")] fn mul(self, rhs: FVec3) -> Self::Output { FVec(unsafe { citro3d_sys::Mtx_MultiplyFVecH(self.as_raw(), rhs.0) }) } diff --git a/citro3d/src/math/projection.rs b/citro3d/src/math/projection.rs index 46313b9..0ec72e5 100644 --- a/citro3d/src/math/projection.rs +++ b/citro3d/src/math/projection.rs @@ -370,6 +370,8 @@ pub struct ClipPlanes { /// The aspect ratio of a projection plane. #[derive(Clone, Copy, Debug)] #[non_exhaustive] +#[doc(alias = "C3D_AspectRatioTop")] +#[doc(alias = "C3D_AspectRatioBot")] pub enum AspectRatio { /// The aspect ratio of the 3DS' top screen (per-eye). #[doc(alias = "C3D_AspectRatioTop")] diff --git a/citro3d/src/render.rs b/citro3d/src/render.rs index 517f12f..03d001d 100644 --- a/citro3d/src/render.rs +++ b/citro3d/src/render.rs @@ -16,6 +16,7 @@ mod transfer; /// A render target for `citro3d`. Frame data will be written to this target /// to be rendered on the GPU and displayed on the screen. +#[doc(alias = "C3D_RenderTarget")] pub struct Target<'screen> { raw: *mut citro3d_sys::C3D_RenderTarget, // This is unused after construction, but ensures unique access to the @@ -24,6 +25,7 @@ pub struct Target<'screen> { } impl Drop for Target<'_> { + #[doc(alias = "C3D_RenderTargetDelete")] fn drop(&mut self) { unsafe { C3D_RenderTargetDelete(self.raw); @@ -38,6 +40,8 @@ impl<'screen> Target<'screen> { /// # Errors /// /// Fails if the target could not be created. + #[doc(alias = "C3D_RenderTargetCreate")] + #[doc(alias = "C3D_RenderTargetSetOutput")] pub fn new( width: usize, height: usize, @@ -81,6 +85,7 @@ impl<'screen> Target<'screen> { /// Clear the render target with the given 32-bit RGBA color and depth buffer value. /// Use `flags` to specify whether color and/or depth should be overwritten. + #[doc(alias = "C3D_RenderTargetClear")] pub fn clear(&mut self, flags: ClearFlags, rgba_color: u32, depth: u32) { unsafe { citro3d_sys::C3D_RenderTargetClear(self.raw, flags.bits(), rgba_color, depth); @@ -95,6 +100,7 @@ impl<'screen> Target<'screen> { bitflags::bitflags! { /// Indicate whether color, depth buffer, or both values should be cleared. + #[doc(alias = "C3D_ClearBits")] pub struct ClearFlags: u32 { /// Clear the color of the render target. const COLOR = citro3d_sys::C3D_CLEAR_COLOR; @@ -108,6 +114,7 @@ bitflags::bitflags! { /// The color format to use when rendering on the GPU. #[repr(u32)] #[derive(Clone, Copy, Debug)] +#[doc(alias = "GPU_COLORBUF")] pub enum ColorFormat { /// 8-bit Red + 8-bit Green + 8-bit Blue + 8-bit Alpha. RGBA8 = ctru_sys::GPU_RB_RGBA8, @@ -137,6 +144,8 @@ impl From for ColorFormat { /// The depth buffer format to use when rendering. #[repr(u32)] #[derive(Clone, Copy, Debug)] +#[doc(alias = "GPU_DEPTHBUF")] +#[doc(alias = "C3D_DEPTHTYPE")] pub enum DepthFormat { /// 16-bit depth. Depth16 = ctru_sys::GPU_RB_DEPTH16, diff --git a/citro3d/src/render/transfer.rs b/citro3d/src/render/transfer.rs index 4192547..c2d9dc7 100644 --- a/citro3d/src/render/transfer.rs +++ b/citro3d/src/render/transfer.rs @@ -32,6 +32,7 @@ impl Flags { /// convertible to one another. Use [`From::from`] to get the [`Format`] corresponding /// to a given [`ColorFormat`]. #[repr(u32)] +#[doc(alias = "GX_TRANSFER_FORMAT")] pub enum Format { /// 8-bit Red + 8-bit Green + 8-bit Blue + 8-bit Alpha. RGBA8 = ctru_sys::GX_TRANSFER_FMT_RGBA8, diff --git a/citro3d/src/shader.rs b/citro3d/src/shader.rs index 39b9aa8..c2042bf 100644 --- a/citro3d/src/shader.rs +++ b/citro3d/src/shader.rs @@ -16,6 +16,7 @@ use crate::uniform; /// * A [geometry](Type::Geometry) shader [`Library`] /// /// The PICA200 does not support user-programmable fragment shaders. +#[doc(alias = "shaderProgram_s")] pub struct Program { program: ctru_sys::shaderProgram_s, } @@ -28,6 +29,8 @@ impl Program { /// Returns an error if: /// * the shader program cannot be initialized /// * the input shader is not a vertex shader or is otherwise invalid + #[doc(alias = "shaderProgramInit")] + #[doc(alias = "shaderProgramSetVsh")] pub fn new(vertex_shader: Entrypoint) -> Result { let mut program = unsafe { let mut program = MaybeUninit::uninit(); @@ -53,6 +56,7 @@ impl Program { /// /// Returns an error if the input shader is not a geometry shader or is /// otherwise invalid. + #[doc(alias = "shaderProgramSetGsh")] pub fn set_geometry_shader( &mut self, geometry_shader: Entrypoint, @@ -75,6 +79,7 @@ impl Program { /// /// * If the given `name` contains a null byte /// * If a uniform with the given `name` could not be found + #[doc(alias = "shaderInstanceGetUniformLocation")] pub fn get_uniform(&self, name: &str) -> crate::Result { let vertex_instance = unsafe { (*self.as_raw()).vertexShader }; assert!( @@ -105,6 +110,7 @@ impl Program { } impl Drop for Program { + #[doc(alias = "shaderProgramFree")] fn drop(&mut self) { unsafe { let _ = ctru_sys::shaderProgramFree(self.as_raw_mut()); @@ -133,6 +139,7 @@ impl From for u32 { /// /// This is the result of parsing a shader binary (`.shbin`), and the resulting /// [`Entrypoint`]s can be used as part of a [`Program`]. +#[doc(alias = "DVLB_s")] pub struct Library(*mut ctru_sys::DVLB_s); impl Library { @@ -142,6 +149,7 @@ impl Library { /// /// An error is returned if the input data does not have an alignment of 4 /// (cannot be safely converted to `&[u32]`). + #[doc(alias = "DVLB_ParseFile")] pub fn from_bytes(bytes: &[u8]) -> Result> { let aligned: &[u32] = bytemuck::try_cast_slice(bytes)?; Ok(Self(unsafe { @@ -157,6 +165,7 @@ impl Library { /// Get the number of [`Entrypoint`]s in this shader library. #[must_use] + #[doc(alias = "numDVLE")] pub fn len(&self) -> usize { unsafe { (*self.0).numDVLE as usize } } @@ -186,6 +195,7 @@ impl Library { } impl Drop for Library { + #[doc(alias = "DVLB_Free")] fn drop(&mut self) { unsafe { ctru_sys::DVLB_Free(self.as_raw());