Format and document utility files (#246)

* Format and document utility files * Add Doxyfile * small updates for cleanup * Final touches for util docs * Replace `_` with `s_` for static functions * update for clang-format changes * Update include/audio_utils.h Co-authored-by: MeirGavish <meir.gavish@gmail.com> * Apply suggestions from code review Co-authored-by: MeirGavish <meir.gavish@gmail.com> * Update include/audio_utils.h Co-authored-by: MeirGavish <meir.gavish@gmail.com> * Update include/graphic_utils.h Co-authored-by: MeirGavish <meir.gavish@gmail.com> * Make clang-format happy :) * Update gitignore for doxygen * restor graphic_utils.c to main * update graphics utils * tmp * tmp * get it to compile * fix some bad merge mistakes * Fix clang format * Apply suggestions from code review Co-authored-by: MeirGavish <meir.gavish@gmail.com> * make clang-format happy --------- Co-authored-by: MeirGavish <meir.gavish@gmail.com>
2025-12-07 12:56:39 -08:00
parent 7bd510ee5f
commit 35ecbf33ae
14 changed files with 3765 additions and 317 deletions
@@ -1,16 +1,51 @@
-#ifndef AUDIO_UTILS_H
-#define AUDIO_UTILS_H
-
-#include <mm_types.h>
-
-#define MM_FULL_VOLUME      255
-#define MM_PAN_CENTER       128
-#define MM_BASE_PITCH_RATE  1024
-
-#define SFX_DEFAULT_VOLUME  MM_FULL_VOLUME
-#define SFX_DEFAULT_PAN     MM_PAN_CENTER
-#define SFX_DEFAULT_HANDLE  0
-
-void play_sfx(mm_word id, mm_word rate);
-
-#endif
+/**
+ * @file audio_utils.h
+ *
+ * @brief Utilities for using maxmod to play sound effects
+ */
+#ifndef AUDIO_UTILS_H
+#define AUDIO_UTILS_H
+
+#include <mm_types.h>
+
+/**
+ * @def MM_FULL_VOLUME
+ * @brief The maximum volume for maxmod mm_sound_effect.volume
+ */
+#define MM_FULL_VOLUME 255
+
+/**
+ * @def MM_PAN_CENTER
+ * @brief The center pan of stereo audio for maxmod
+ */
+#define MM_PAN_CENTER 128
+
+/**
+ * @def MM_BASE_PITCH_RATE
+ * @brief The default pitch rate for the sound effect played.
+ *
+ * Increasing the rate increases the pitch, while decreasing lowers the pitch.
+ */
+#define MM_BASE_PITCH_RATE 1024
+
+/**
+ * @def SFX_DEFAULT_VOLUME
+ * @brief Default volume for sound effects
+ */
+#define SFX_DEFAULT_VOLUME MM_FULL_VOLUME
+
+/**
+ * @def SFX_DEFAULT_PAN
+ * @brief The default stereo pan, will always be center pan.
+ */
+#define SFX_DEFAULT_PAN MM_PAN_CENTER
+
+/**
+ * @brief Play a sound effect, wrapper for mmEffectEx()
+ *
+ * @param id the sound id to play, from maxmod compiled soundbank.h header
+ * @param rate the pitch rate, the default value is @ref MM_BASE_PTCH_RATE
+ */
+void play_sfx(mm_word id, mm_word rate);
+
+#endif