#ifndef _SOUND_H
#define _SOUND_H

#include <tonc.h>

#include "soundbank.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef void* PTGBSFXHandle;

/**
 * @brief The API's defined here are a thin abstraction layer over the sound engine functions.
 * This allows the underlying sound engine to be swapped out without affecting the rest of the codebase.
 */

/**
 * @brief This function initializes the sound engine and sets up a VBLANK handler
 * to process audio every frame. It should be called during the initialization phase of the program.
 */
bool sound_init(void);

/**
 * @brief This function starts playing the song at the given index. 
 * If loop is true, the song will loop indefinitely until stopped or another song is played.
 * 
 * @param song_index The index of the song to play.
 * @param loop Whether the song should loop indefinitely.
 */
void play_song(u32 song_index, bool loop);

/**
 * @brief This function checks if a song is currently playing.
 * 
 * @return true if a song is playing, false otherwise.
 */
bool is_song_playing(void);

/**
 * @brief This function stops the currently playing song.
 */
void stop_song(void);

/**
 * @brief This function plays the sound effect at the given index. 
 * Sound effects are typically short audio clips that play in response to specific events in the game, 
 * such as button presses or character actions.
 * These are usually raw PCM samples (e.g., WAV files)
 * 
 * To play a MOD- S3M- XM- or IT format based sound effect,
 * use the play_jingle function instead.
 */
PTGBSFXHandle play_sound_effect(u32 sound_effect_index);

/**
 * @brief This function stops the given sound effect from playing and invalidates the handle
 */
void stop_sound_effect(PTGBSFXHandle handle);

/**
 * @brief This function stops all currently playing sound effects and resets 
 */
void stop_all_sound_effects(void);

/**
 * @brief This function marks the sound effect as unimportant,
 * allowing the sound engine to stop it if it needs to free up channels for new sound effects.
 * 
 * It also invalidates the handle, so it should not be used after calling this function.
 */
void release_sound_effect(PTGBSFXHandle handle);

/**
 * @brief This function plays a jingle at the given index.
 * A jingle is a sound effect that is based on a tracker format like MOD, S3M, XM, or IT.
 * They can be played simultaneously with songs.
 * If you want to play PCM-based sound effects (e.g., WAV files), use the play_sound_effect function instead.
 * 
 * Note that jingles must be limited to 4 channels only. (https://blocksds.skylyrac.net/maxmod/group__gba__jingle__playback.html)
 */
void play_jingle(u32 jingle_index);

/**
 * @brief Checks if a jingle is actively playing.
 */
bool is_jingle_playing(void);

#ifdef __cplusplus
}
#endif

#endif