libakgl/include/akgl/assets.h

/**
 * @file assets.h
 * @brief Loads the game's startup assets into the global mixer and track table.
 */

#ifndef _AKGL_ASSETS_H_
#define _AKGL_ASSETS_H_

#include <akerror.h>

/**
 * @brief Load a music file, bind it to the background-music track, and start it playing.
 *
 * Loads @p fname through `akgl_mixer`, creates a track for it, stores that track
 * in `akgl_tracks[AKGL_GAME_AUDIO_TRACK_BGM]`, and starts playback. The loaded
 * audio is also published as the global `bgm`. This is a *startup* helper: it
 * assumes the mixer already exists, so `akgl_game_init` (or a bare
 * `akgl_audio_init`) has to have run first, and it overwrites whatever the BGM
 * track slot held without releasing it.
 *
 * Loading is deferred inside SDL_mixer (`MIX_LoadAudio(..., true)` predecodes),
 * so a large file costs its decode time here rather than at first play.
 *
 * On any failure after the audio loads, the audio is destroyed again before the
 * error is returned; the track, if one was created, is not.
 *
 * @param fname Path to a music file in any format SDL_mixer can open. Required.
 *              Used verbatim -- it is not resolved against `SDL_GetBasePath()`,
 *              so a relative path is relative to the process working directory.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER If @p fname is `NULL`, if SDL_mixer cannot load the
 *         file (missing, unreadable, or an unsupported format), or if it cannot
 *         allocate a track for it. The message carries `SDL_GetError()`.
 * @throws AKGL_ERR_SDL If the loaded audio cannot be bound to the new track, or
 *         if playback fails to start.
 *
 * @note The infinite-loop request does not currently take effect:
 *       `MIX_PROP_PLAY_LOOPS_NUMBER` is set on property set 0, which is the
 *       "no properties" sentinel rather than a set this function owns, so the
 *       call is rejected and the music plays once.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_load_start_bgm(char *fname);

#endif //_AKGL_ASSETS_H_