audio.h

Go to the documentation of this file.

/*
** Jo Sega Saturn Engine
** Copyright (c) 2012-2026, Johannes Fetz (johannesfetz@gmail.com)
** All rights reserved.
**
** Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions are met:
**     * Redistributions of source code must retain the above copyright
**       notice, this list of conditions and the following disclaimer.
**     * Redistributions in binary form must reproduce the above copyright
**       notice, this list of conditions and the following disclaimer in the
**       documentation and/or other materials provided with the distribution.
**     * Neither the name of the Johannes Fetz nor the
**       names of its contributors may be used to endorse or promote products
**       derived from this software without specific prior written permission.
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
** ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
** WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
** DISCLAIMED. IN NO EVENT SHALL Johannes Fetz BE LIABLE FOR ANY
** DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
** (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
** LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
** ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
** SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
 
#ifndef __JO_AUDIO_H__
# define __JO_AUDIO_H__
 
#ifdef JO_COMPILE_WITH_AUDIO_SUPPORT

# define JO_SOUND_MAX_CHANNEL       (14)
 
typedef enum
{
    JoSoundMono8Bit = (0x00 | 0x10),
    JoSoundMono16Bit = (0x00 | 0x00),
    JoSoundStereo8Bit = (0x80 | 0x10),
    JoSoundStereo16Bit = (0x80 | 0x00)
}                   jo_sound_mode;
 
typedef struct
{
    char            *data;
    unsigned int    data_length;
    jo_sound_mode   mode;
    unsigned char   current_playing_channel;
    unsigned short  sample_rate; // Set sampling rate from 8000 to 44100 kHz
    unsigned char   volume; // Change volume: 0 (JO_MIN_AUDIO_VOLUME) -> 127 (JO_MAX_AUDIO_VOLUME)
    char            pan; // Adjust stereo: -128 (left speaker) -> 127 (right speaker)
    unsigned int    resident; // Kept in the sound RAM (jo_audio_make_resident()): its offset there + 1, 0: not resident
    unsigned char   reverb; // Its send to the reverberation (JO_COMPILE_WITH_AUDIO_DSP_MODULE): 0 (none), 1 to 7 (-36 to 0 dB, 6 dB steps)
}                   jo_sound;

# define JO_DEFAULT_AUDIO_VOLUME    (127)
# define JO_MAX_AUDIO_VOLUME        (127)
# define JO_MIN_AUDIO_VOLUME        (0)
 
#ifdef JO_COMPILE_WITH_FS_SUPPORT

void    jo_audio_play_cd_track(const int from_track, const int to_track, const bool repeat_infinitely);

void    jo_audio_stop_cd(void);

void    jo_audio_pause_cd(void);

void    jo_audio_resume_cd(void);

bool    jo_audio_is_cd_paused(void);

bool    jo_audio_is_cd_playing(void);
 
#endif

void    jo_audio_set_volume(const unsigned char vol);

# define JO_AUDIO_CD_VOLUME_MAX     (7)

void    jo_audio_set_cd_volume(const unsigned char level);

bool    jo_audio_is_channel_playing(const unsigned char channel);

void    jo_audio_play_sound_on_channel(jo_sound * const sound, const unsigned char channel);

void    jo_audio_play_sound_loop_on_channel(jo_sound * const sound, const unsigned char channel);

void    jo_audio_set_channel_sample_rate(const unsigned char channel, const unsigned short sample_rate);

void    jo_audio_set_channel_volume(const unsigned char channel, const unsigned char volume);

void    jo_audio_set_channel_reverb(const unsigned char channel, const unsigned char level);
 
#ifdef JO_COMPILE_WITH_AUDIO_DSP_SUPPORT

typedef struct
{
    unsigned short  decay_ms;   // The tail falls by 60 dB in this time (the low frequencies): 50 to 10000 ms
    unsigned char   damping;    // The high frequencies die faster: 0 (as the low ones) to 127 (much faster: a soft room)
    unsigned char   early;      // The level of the early reflections (the walls: 9 to 23 ms): 0 to 127
    unsigned char   tail;       // The level of the tail: 0 to 127
}                   jo_audio_reverb;

void    jo_audio_set_reverb(const jo_audio_reverb * const reverb);
 
#endif
 
#ifdef JO_COMPILE_WITH_AUDIO_DRIVER_SUPPORT

typedef enum
{
    JoToneSine = 0,
    JoToneNoise = 1
}                   jo_tone_waveform;

typedef struct
{
    unsigned short      frequency;          // Hz (20 to 8000)
    unsigned short      end_frequency;      // The pitch glides to this frequency (Hz, 0: no glide)
    unsigned short      glide_ms;           // The time of the glide: 63 % of the way in this time
    unsigned short      decay_ms;           // The tone falls by 60 dB in this time (0: it plays until the channel is stopped)
    unsigned char       volume;             // 0 (JO_MIN_AUDIO_VOLUME) -> 127 (JO_MAX_AUDIO_VOLUME)
    char                pan;                // -128 (left speaker) -> 127 (right speaker)
    unsigned char       reverb;             // Send to the reverberation (JO_COMPILE_WITH_AUDIO_DSP_MODULE): 0 to 7
    unsigned char       modulation;         // FM: the index x 16 (16: 1 radian, 0: no FM); the second slot of the channel is the modulator
    unsigned char       modulator_ratio;    // FM: the frequency of the modulator / the frequency x 4 (4: the same frequency, 8: twice)
    unsigned char       tremolo;            // The depth of the tremolo (the amplitude LFO): 0 (none) to 7
    unsigned char       tremolo_rate;       // Its frequency: 0 to 31 (LFOF of the SCSP: 0.17 Hz to 96 Hz; 28: 38 Hz)
    jo_tone_waveform    waveform;
}                       jo_audio_tone;

void    jo_audio_play_tone(const jo_audio_tone * const tone, const unsigned char channel);
 
#endif

void    jo_audio_play_sound(jo_sound * const sound);

void    jo_audio_stop_sound(const jo_sound * const sound);

void    jo_audio_stop_channel(const unsigned char channel);
 
#ifdef JO_COMPILE_WITH_FS_SUPPORT

bool     jo_audio_load_pcm(const char * const filename, const jo_sound_mode mode, jo_sound *sound);

bool     jo_audio_load_pcm_async(const char * const filename, const jo_sound_mode mode, jo_sound *sound);

bool     jo_audio_load_wav(const char * const filename, jo_sound *sound);
 
#endif

bool     jo_audio_make_resident(jo_sound *sound);

void     jo_audio_free_resident(void);

void     jo_audio_free_pcm(jo_sound *sound);

int                         jo_audio_usage_percent(void);
 
#endif /* !JO_COMPILE_WITH_AUDIO_SUPPORT */
 
#endif /* !__JO_AUDIO_H__ */
 
/*
** END OF FILE
*/