Merge pull request #142 from Lectem/documentation

Some documentation

libctru/include/3ds.h

@@ -53,12 +53,52 @@ extern "C" {
  * @example app_launch/source/main.c
  * @example audio/mic/source/main.c
  * @example get_system_language/source/main.c
- * @example gpu/source/main.c
  * @example graphics/bitmap/24bit-color/source/main.c
  * @example graphics/printing/hello-world/source/main.c
  * @example graphics/printing/both-screen-text/source/main.c
  * @example graphics/printing/colored-text/source/main.c
  * @example graphics/printing/multiple-windows-text/source/main.c
+
+ * @example graphics/gpu/geoshader/source/main.c
+   graphics/gpu/geoshader/source/gpu.h
+   @include graphics/gpu/geoshader/source/gpu.h
+   graphics/gpu/geoshader/source/gpu.c
+   @include graphics/gpu/geoshader/source/gpu.c
+   graphics/gpu/geoshader/source/3dmath.h
+   @include graphics/gpu/geoshader/source/3dmath.h
+   graphics/gpu/geoshader/source/3dmath.c
+   @include graphics/gpu/geoshader/source/3dmath.c
+   graphics/gpu/geoshader/source/vshader.pica
+   @include graphics/gpu/geoshader/source/vshader.pica
+   graphics/gpu/geoshader/source/gshader.pica
+   @include graphics/gpu/geoshader/source/gshader.pica
+
+   
+ * @example graphics/gpu/simple_tri/source/main.c
+   graphics/gpu/simple_tri/source/gpu.h
+   @include graphics/gpu/simple_tri/source/gpu.h
+   graphics/gpu/simple_tri/source/gpu.c
+   @include graphics/gpu/simple_tri/source/gpu.c
+   graphics/gpu/simple_tri/source/3dmath.h
+   @include graphics/gpu/simple_tri/source/3dmath.h
+   graphics/gpu/simple_tri/source/3dmath.c
+   @include graphics/gpu/simple_tri/source/3dmath.c
+   graphics/gpu/simple_tri/source/vshader.pica
+   @include graphics/gpu/simple_tri/source/vshader.pica
+
+   
+ * @example graphics/gpu/textured_cube/source/main.c
+   graphics/gpu/textured_cube/source/gpu.h
+   @include graphics/gpu/textured_cube/source/gpu.h
+   graphics/gpu/textured_cube/source/gpu.c
+   @include graphics/gpu/textured_cube/source/gpu.c
+   graphics/gpu/textured_cube/source/3dmath.h
+   @include graphics/gpu/textured_cube/source/3dmath.h
+   graphics/gpu/textured_cube/source/3dmath.c
+   @include graphics/gpu/textured_cube/source/3dmath.c
+   graphics/gpu/textured_cube/source/vshader.pica
+   @include graphics/gpu/textured_cube/source/vshader.pica
+
  * @example http/source/main.c
  * @example input/read-controls/source/main.c
  * @example input/touch-screen/source/main.c

libctru/include/3ds/gpu/gx.h

@@ -1,7 +1,15 @@
+/**
+ * @file gx.h
+ */
+
 #pragma once
 
 #define GX_BUFFER_DIM(w, h) (((h)<<16)|((w)&0xFFFF))
 
+/**
+ * @brief Pixel formats
+ * @sa GSP_FramebufferFormats
+ */
 typedef enum
 {
 	GX_TRANSFER_FMT_RGBA8  = 0,
@@ -11,20 +19,29 @@ typedef enum
 	GX_TRANSFER_FMT_RGBA4  = 4
 } GX_TRANSFER_FORMAT;
 
+/**
+ * @brief Anti-aliasing modes
+ *
+ * Please remember that the framebuffer is sideways.
+ * Hence if you activate 2x1 anti-aliasing the destination dimensions are w = 240*2 and h = 400
+ */
 typedef enum
 {
-	GX_TRANSFER_SCALE_NO = 0,
-	GX_TRANSFER_SCALE_X  = 1,
-	GX_TRANSFER_SCALE_Y  = 2
+	GX_TRANSFER_SCALE_NO = 0, ///< No anti-aliasing
+	GX_TRANSFER_SCALE_X  = 1, ///< 2x1 anti-aliasing
+	GX_TRANSFER_SCALE_XY = 2, ///< 2x2 anti-aliasing
 } GX_TRANSFER_SCALE;
 
+/**
+ * @brief GX transfer control flags
+ */
 typedef enum
 {
-	GX_FILL_TRIGGER     = 0x001,
-	GX_FILL_FINISHED    = 0x002,
-	GX_FILL_16BIT_DEPTH = 0x000,
-	GX_FILL_24BIT_DEPTH = 0x100,
-	GX_FILL_32BIT_DEPTH = 0x200,
+	GX_FILL_TRIGGER     = 0x001, ///< Trigger the PPF event
+	GX_FILL_FINISHED    = 0x002, ///< Indicates if the memory fill is complete. You should not use it when requesting a transfer.
+	GX_FILL_16BIT_DEPTH = 0x000, ///< The buffer has a 16 bit per pixel depth
+	GX_FILL_24BIT_DEPTH = 0x100, ///< The buffer has a 24 bit per pixel depth
+	GX_FILL_32BIT_DEPTH = 0x200, ///< The buffer has a 32 bit per pixel depth
 } GX_FILL_CONTROL;
 
 #define GX_TRANSFER_FLIP_VERT(x)  ((x)<<0)

libctru/include/3ds/services/csnd.h

@@ -147,6 +147,10 @@ void CSND_SetCapRegs(u32 capUnit, u32 flags, u32 addr, u32 size);
 Result CSND_SetDspFlags(bool waitDone);
 Result CSND_UpdateInfo(bool waitDone);
 
+/**
+ * @param vol The volume, ranges from 0.0 to 1.0 included
+ * @param pan The pan, ranges from -1.0 to 1.0 included
+ */
 Result csndPlaySound(int chn, u32 flags, u32 sampleRate, float vol, float pan, void* data0, void* data1, u32 size);
 
 void csndGetDspFlags(u32* outSemFlags, u32* outIrqFlags); // Requires previous CSND_UpdateInfo()

libctru/include/3ds/services/y2r.h

@@ -233,7 +233,7 @@ Result Y2RU_GetTransferEndEvent(Handle* end_event);
  * @param src_buf A pointer to the beginning of your Y data buffer.
  * @param image_size The total size of the data buffer.
  * @param transfer_unit Specifies the size of 1 DMA transfer. Usually set to 1 line. This has to be a divisor of image_size.
- * @param transfer_unit Specifies the gap (offset) to be added after each transfer. Can be used to convert images with stride or only a part of it.
+ * @param transfer_gap Specifies the gap (offset) to be added after each transfer. Can be used to convert images with stride or only a part of it.
  *
  * This specifies the Y data buffer for the planar input formats (INPUT_YUV42*_INDIV_*).
  * The actual transfer will only happen after calling @ref Y2RU_StartConversion.
@@ -245,7 +245,7 @@ Result Y2RU_SetSendingY(const void* src_buf, u32 image_size, u16 transfer_unit,
  * @param src_buf A pointer to the beginning of your Y data buffer.
  * @param image_size The total size of the data buffer.
  * @param transfer_unit Specifies the size of 1 DMA transfer. Usually set to 1 line. This has to be a divisor of image_size.
- * @param transfer_unit Specifies the gap (offset) to be added after each transfer. Can be used to convert images with stride or only a part of it.
+ * @param transfer_gap Specifies the gap (offset) to be added after each transfer. Can be used to convert images with stride or only a part of it.
  *
  * This specifies the U data buffer for the planar input formats (INPUT_YUV42*_INDIV_*).
  * The actual transfer will only happen after calling @ref Y2RU_StartConversion.