Merge pull request #32 from rust3ds/docs/alias-and-examples

Add a bunch of doc aliases for unsafe APIs

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,

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],

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<Self> {
         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
+                citro3d_sys::C3D_FRAME_SYNCDRAW.try_into().unwrap(),
-                    .try_into()
-                    .expect("const is valid u8"),
             );
         }
 
@@ -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<buffer::Info> {
         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<attrib::Info> {
         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();

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<const N: usize>(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) })
     }

citro3d/src/math/matrix.rs

@@ -109,31 +109,37 @@ impl<const M: usize, const N: usize> Matrix<M, N> {
 
     /// 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,

citro3d/src/math/ops.rs

@@ -129,6 +129,7 @@ impl<const N: usize> AbsDiffEq for FVec<N> {
 impl<Rhs: Borrow<Self>, const M: usize, const N: usize> Add<Rhs> for &Matrix<M, N> {
     type Output = <Self as Deref>::Target;
 
+    #[doc(alias = "Mtx_Add")]
     fn add(self, rhs: Rhs) -> Self::Output {
         let mut out = MaybeUninit::uninit();
         unsafe {
@@ -141,6 +142,7 @@ impl<Rhs: Borrow<Self>, const M: usize, const N: usize> Add<Rhs> for &Matrix<M,
 impl<Rhs: Borrow<Self>, const M: usize, const N: usize> Sub<Rhs> for &Matrix<M, N> {
     type Output = <Self as Deref>::Target;
 
+    #[doc(alias = "Mtx_Subtract")]
     fn sub(self, rhs: Rhs) -> Self::Output {
         let mut out = MaybeUninit::uninit();
         unsafe {
@@ -153,6 +155,7 @@ impl<Rhs: Borrow<Self>, const M: usize, const N: usize> Sub<Rhs> for &Matrix<M,
 impl<const M: usize, const N: usize, const P: usize> Mul<&Matrix<N, P>> for &Matrix<M, N> {
     type Output = Matrix<M, P>;
 
+    #[doc(alias = "Mtx_Multiply")]
     fn mul(self, rhs: &Matrix<N, P>) -> Self::Output {
         let mut out = MaybeUninit::uninit();
         unsafe {
@@ -173,6 +176,7 @@ impl<const M: usize, const N: usize, const P: usize> Mul<Matrix<N, P>> for &Matr
 impl Mul<FVec3> 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<FVec3> for &Matrix3 {
 impl Mul<FVec4> 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<FVec4> for &Matrix4 {
 impl Mul<FVec3> 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) })
     }

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")]

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<FramebufferFormat> 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,

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,

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<Self, ctru::Error> {
         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<uniform::Index> {
         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<Type> 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<Self, Box<dyn Error>> {
         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());