gfx/gfx.h: Fix doxygen formatting

MrKcyre · Feb 10, 2018 · 7a07d2c · 7a07d2c
1 parent 9559264
commit 7a07d2c
Showing 1 changed file with 41 additions and 19 deletions.
diff --git a/nx/include/switch/gfx/gfx.h b/nx/include/switch/gfx/gfx.h
@@ -1,56 +1,79 @@
+/**
+ * @file gfx.h
+ * @brief High-level graphics API.
+ * This API exposes a framebuffer (technically speaking, a windowbuffer) to be used for drawing graphics.
+ * @author yellows8
+ * @copyright libnx Authors
+ */
 #pragma once
 #include "../types.h"
 
 /// Converts red, green, blue, and alpha components to packed RGBA8.
 #define RGBA8(r,g,b,a)  (((r)&0xff)|(((g)&0xff)<<8)|(((b)&0xff)<<16)|(((a)&0xff)<<24))
 
-/// Same as RGBA8 except with alpha=0xff.
+/// Same as \ref RGBA8 except with alpha=0xff.
 #define RGBA8_MAXALPHA(r,g,b) RGBA8(r,g,b,0xff)
 
-/// Do not use viInitialize/viExit when using these.
+/**
+ * @brief Initializes the graphics subsystem.
+ * @warning Do not use \ref viInitialize when using this function.
+ */
 void gfxInitDefault(void);
-void gfxExit(void);
-
-/// Note that "framebuffer" here is technically windowbuffer.
 
-/// The default resolution is 720p, however you should use gfxGetFramebuffer() to get the current width/height.
+/**
+ * @brief Uninitializes the graphics subsystem.
+ * @warning Do not use \ref viExit when using this function.
+ */
+void gfxExit(void);
 
-/// This can only be used before calling gfxInitDefault(), this will use fatalSimple() otherwise. If the input is 0, the default resolution will be used during gfxInitDefault(). This sets the maximum resolution for the framebuffer, used during gfxInitDefault(). This is also used as the current resolution when crop isn't set. The width/height are reset to the default when gfxExit() is used.
-/// Normally you should only use this when you need a maximum resolution larger than the default, see above.
+/**
+ * @brief Sets the resolution to be used when initializing the graphics subsystem.
+ * @param[in] width Horizontal resolution, in pixels.
+ * @param[in] height Vertical resolution, in pixels.
+ * @note The default resolution is 720p, however you should use \ref gfxGetFramebuffer to get the current width/height.
+ * @note This can only be used before calling \ref gfxInitDefault, this will use \ref fatalSimple otherwise. If the input is 0, the default resolution will be used during \ref gfxInitDefault. This sets the maximum resolution for the framebuffer, used during \ref gfxInitDefault. This is also used as the current resolution when crop isn't set. The width/height are reset to the default when \ref gfxExit is used.
+ * @note Normally you should only use this when you need a maximum resolution larger than the default, see above.
+ */
 void gfxInitResolution(u32 width, u32 height);
 
-/// Wrapper for gfxInitResolution() with resolution=1080p. Use this if you want to support 1080p or >720p in docked-mode.
+/// Wrapper for \ref gfxInitResolution with resolution=1080p. Use this if you want to support 1080p or >720p in docked-mode.
 void gfxInitResolutionDefault(void);
 
-/// Configure framebuffer crop, by default crop is all-zero. Use all-zero input to reset to default. gfxExit() resets this to the default.
+/// Configure framebuffer crop, by default crop is all-zero. Use all-zero input to reset to default. \ref gfxExit resets this to the default.
 /// When the input is invalid this returns without changing the crop data, this includes the input values being larger than the framebuf width/height.
-/// This will update the display width/height returned by gfxGetFramebuffer(), with that width/height being reset to the default when required.
-/// gfxGetFramebufferDisplayOffset() uses absolute x/y, it will not adjust for non-zero crop left/top.
-/// The new crop config will not take affect with double-buffering disabled. When used during frame-drawing, this should be called before gfxGetFramebuffer().
+/// This will update the display width/height returned by \ref gfxGetFramebuffer, with that width/height being reset to the default when required.
+/// \ref gfxGetFramebufferDisplayOffset uses absolute x/y, it will not adjust for non-zero crop left/top.
+/// The new crop config will not take affect with double-buffering disabled. When used during frame-drawing, this should be called before \ref gfxGetFramebuffer.
 void gfxConfigureCrop(s32 left, s32 top, s32 right, s32 bottom);
 
-/// Wrapper for gfxConfigureCrop(). Use this to set the resolution, within the bounds of the maximum resolution. Use all-zero input to reset to default.
+/// Wrapper for \ref gfxConfigureCrop. Use this to set the resolution, within the bounds of the maximum resolution. Use all-zero input to reset to default.
 void gfxConfigureResolution(s32 width, s32 height);
 
-/// If enabled, gfxConfigureResolution() will be used with the input resolution for the current OperationMode. Then gfxConfigureResolution() will automatically be used with the specified resolution each time OperationMode changes.
+/// If enabled, \ref gfxConfigureResolution will be used with the input resolution for the current OperationMode. Then \ref gfxConfigureResolution will automatically be used with the specified resolution each time OperationMode changes.
 void gfxConfigureAutoResolution(bool enable, s32 handheld_width, s32 handheld_height, s32 docked_width, s32 docked_height);
 
-/// Wrapper for gfxConfigureAutoResolution(). handheld_resolution=720p, docked_resolution={all-zero for using current maximum resolution}.
+/// Wrapper for \ref gfxConfigureAutoResolution. handheld_resolution=720p, docked_resolution={all-zero for using current maximum resolution}.
 void gfxConfigureAutoResolutionDefault(bool enable);
 
+/// Waits for vertical sync.
 void gfxWaitForVsync(void);
+
+/// Swaps the framebuffers (for double-buffering).
 void gfxSwapBuffers(void);
 
-/// Get the current framebuffer address, with optional output ptrs for the display width/height. The display width/height is adjusted by gfxConfigureCrop()/gfxConfigureResolution().
+/// Get the current framebuffer address, with optional output ptrs for the display width/height. The display width/height is adjusted by \ref gfxConfigureCrop and \ref gfxConfigureResolution.
 u8* gfxGetFramebuffer(u32* width, u32* height);
 
 /// Get the original framebuffer width/height without crop.
 void gfxGetFramebufferResolution(u32* width, u32* height);
 
-/// Use this to get the actual byte-size of the buffer for use with memset/etc, do not calculate the byte-size manually with the width and height from gfxGetFramebuffer/gfxGetFramebufferResolution.
+/// Use this to get the actual byte-size of the buffer for use with memset/etc, do not calculate the byte-size manually with the width and height from \ref gfxGetFramebuffer or \ref gfxGetFramebufferResolution.
 size_t gfxGetFramebufferSize(void);
 
+/// Enables or disables double-buffering.
 void gfxSetDoubleBuffering(bool doubleBuffering);
+
+/// Flushes the framebuffer in the data cache.
 void gfxFlushBuffers(void);
 
 /// Use this to get the pixel-offset in the framebuffer. Returned value is in pixels, not bytes.
@@ -72,4 +95,3 @@ static inline u32 gfxGetFramebufferDisplayOffset(u32 x, u32 y) {
 
     return tmp_pos / 4;
 }
-