snd_main.h

   1 /*
   2 Copyright (C) 1996-1997 Id Software, Inc.
   3
   4 This program is free software; you can redistribute it and/or
   5 modify it under the terms of the GNU General Public License
   6 as published by the Free Software Foundation; either version 2
   7 of the License, or (at your option) any later version.
   8
   9 This program is distributed in the hope that it will be useful,
  10 but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  12
  13 See the GNU General Public License for more details.
  14
  15 You should have received a copy of the GNU General Public License
  16 along with this program; if not, write to the Free Software
  17 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  18
  19 */
  20
  21 #ifndef SND_MAIN_H
  22 #define SND_MAIN_H
  23
  24 #include "sound.h"
  25
  26
  27 typedef struct snd_format_s
  28 {
  29         unsigned int    speed;
  30         unsigned short  width;
  31         unsigned short  channels;
  32 } snd_format_t;
  33
  34 typedef struct snd_buffer_s
  35 {
  36         snd_format_t            format;
  37         unsigned int            nbframes;       // current size, in sample frames
  38         unsigned int            maxframes;      // max size (buffer size), in sample frames
  39         unsigned char           samples[4];     // variable sized
  40 } snd_buffer_t;
  41
  42 typedef struct snd_ringbuffer_s
  43 {
  44         snd_format_t            format;
  45         unsigned char*          ring;
  46         unsigned int            maxframes;      // max size (buffer size), in sample frames
  47         unsigned int            startframe;     // index of the first frame in the buffer
  48                                                                         // if startframe == endframe, the bufffer is empty
  49         unsigned int            endframe;       // index of the first EMPTY frame in the "ring" buffer
  50                                                                         // may be smaller than startframe if the "ring" buffer has wrapped
  51 } snd_ringbuffer_t;
  52
  53 // sfx_t flags
  54 #define SFXFLAG_NONE                    0
  55 #define SFXFLAG_FILEMISSING             (1 << 0) // wasn't able to load the associated sound file
  56 #define SFXFLAG_LEVELSOUND              (1 << 1) // the sfx is part of the server or client precache list for this level
  57 #define SFXFLAG_STREAMED                (1 << 2) // informative only. You shouldn't need to know that
  58 #define SFXFLAG_MENUSOUND               (1 << 3) // not freed during level change (menu sounds, music, etc)
  59
  60 typedef struct snd_fetcher_s snd_fetcher_t;
  61 struct sfx_s
  62 {
  63         char                            name[MAX_QPATH];
  64         sfx_t                           *next;
  65         size_t                          memsize;                // total memory used (including sfx_t and fetcher data)
  66
  67         snd_format_t            format;                 // format describing the audio data that fetcher->getsamplesfloat will return
  68         unsigned int            flags;                  // cf SFXFLAG_* defines
  69         unsigned int            loopstart;              // in sample frames. equals total_length if not looped
  70         unsigned int            total_length;   // in sample frames
  71         const snd_fetcher_t     *fetcher;
  72         void                            *fetcher_data;  // Per-sfx data for the sound fetching functions
  73
  74         float                           volume_mult;    // for replay gain (multiplier to apply)
  75         float                           volume_peak;    // for replay gain (highest peak); if set to 0, ReplayGain isn't supported
  76 };
  77
  78 // maximum supported speakers constant
  79 #define SND_LISTENERS 8
  80
  81 typedef struct channel_s
  82 {
  83         // provided sound information
  84         sfx_t                   *sfx;                   // pointer to sound sample being used
  85         float                   basevolume;             // 0-1 master volume
  86         unsigned int    flags;                  // cf CHANNELFLAG_* defines
  87         int                             entnum;                 // makes sound follow entity origin (allows replacing interrupting existing sound on same id)
  88         int                             entchannel;             // which channel id on the entity
  89         vec3_t                  origin;                 // origin of sound effect
  90         vec_t                   distfade;               // distance multiplier (attenuation/clipK)
  91         void                    *fetcher_data;  // Per-channel data for the sound fetching function
  92         int                             prologic_invert;// whether a sound is played on the surround channels in prologic
  93         float                   basespeed;              // playback rate multiplier for pitch variation
  94
  95         // these are often updated while mixer is running, glitching should be minimized (mismatched channel volumes from spatialization is okay)
  96         // spatialized playback speed (speed * doppler ratio)
  97         float                   mixspeed;
  98         // spatialized volume per speaker (mastervol * distanceattenuation * channelvolume cvars)
  99         float                   volume[SND_LISTENERS];
 100
 101         // updated ONLY by mixer
 102         // position in sfx, starts at 0, loops or stops at sfx->total_length
 103         double                  position;
 104 } channel_t;
 105
 106 // Sound fetching functions
 107 // "start" is both an input and output parameter: it returns the actual start time of the sound buffer
 108 typedef void (*snd_fetcher_getsamplesfloat_t) (channel_t *ch, sfx_t *sfx, int firstsampleframe, int numsampleframes, float *outsamplesfloat);
 109 typedef void (*snd_fetcher_stopchannel_t) (channel_t *ch);
 110 typedef void (*snd_fetcher_freesfx_t) (sfx_t *sfx);
 111 struct snd_fetcher_s
 112 {
 113         snd_fetcher_getsamplesfloat_t           getsamplesfloat;
 114         snd_fetcher_stopchannel_t               stopchannel;
 115         snd_fetcher_freesfx_t           freesfx;
 116 };
 117
 118 extern unsigned int total_channels;
 119 extern channel_t channels[MAX_CHANNELS];
 120
 121 extern snd_ringbuffer_t *snd_renderbuffer;
 122 extern qboolean snd_threaded; // enables use of snd_usethreadedmixing, provided that no sound hacks are in effect (like timedemo)
 123 extern qboolean snd_usethreadedmixing; // if true, the main thread does not mix sound, soundtime does not advance, and neither does snd_renderbuffer->endframe, instead the audio thread will call S_MixToBuffer as needed
 124
 125 extern cvar_t _snd_mixahead;
 126 extern cvar_t snd_swapstereo;
 127 extern cvar_t snd_streaming;
 128 extern cvar_t snd_streaming_length;
 129
 130 #define SND_CHANNELLAYOUT_AUTO          0
 131 #define SND_CHANNELLAYOUT_STANDARD      1
 132 #define SND_CHANNELLAYOUT_ALSA          2
 133 extern cvar_t snd_channellayout;
 134
 135 extern int snd_blocked;         // counter. When > 0, we stop submitting sound to the audio device
 136
 137 extern mempool_t *snd_mempool;
 138
 139 // If simsound is true, the sound card is not initialized and no sound is submitted to it.
 140 // More generally, all arch-dependent operations are skipped or emulated.
 141 // Used for isolating performance in the renderer.
 142 extern qboolean simsound;
 143
 144
 145 #define STREAM_BUFFERSIZE 16384 // in sampleframes
 146
 147
 148 // ====================================================================
 149 //         Architecture-independent functions
 150 // ====================================================================
 151
 152 void S_MixToBuffer(void *stream, unsigned int frames);
 153
 154 qboolean S_LoadSound (sfx_t *sfx, qboolean complain);
 155
 156 snd_buffer_t *Snd_CreateSndBuffer (const unsigned char *samples, unsigned int sampleframes, const snd_format_t* in_format, unsigned int sb_speed);
 157 qboolean Snd_AppendToSndBuffer (snd_buffer_t* sb, const unsigned char *samples, unsigned int sampleframes, const snd_format_t* format);
 158
 159 // If "buffer" is NULL, the function allocates one buffer of "sampleframes" sample frames itself
 160 // (if "sampleframes" is 0, the function chooses the size).
 161 snd_ringbuffer_t *Snd_CreateRingBuffer (const snd_format_t* format, unsigned int sampleframes, void* buffer);
 162
 163
 164 // ====================================================================
 165 //         Architecture-dependent functions
 166 // ====================================================================
 167
 168 // Create "snd_renderbuffer" with the proper sound format if the call is successful
 169 // May return a suggested format if the requested format isn't available
 170 qboolean SndSys_Init (const snd_format_t* requested, snd_format_t* suggested);
 171
 172 // Stop the sound card, delete "snd_renderbuffer" and free its other resources
 173 void SndSys_Shutdown (void);
 174
 175 // Submit the contents of "snd_renderbuffer" to the sound card
 176 void SndSys_Submit (void);
 177
 178 // Returns the number of sample frames consumed since the sound started
 179 unsigned int SndSys_GetSoundTime (void);
 180
 181 // Get the exclusive lock on "snd_renderbuffer"
 182 qboolean SndSys_LockRenderBuffer (void);
 183
 184 // Release the exclusive lock on "snd_renderbuffer"
 185 void SndSys_UnlockRenderBuffer (void);
 186
 187 // if the sound system can generate events, send them
 188 void SndSys_SendKeyEvents(void);
 189
 190 // exported for capturevideo so ogg can see all channels
 191 typedef struct portable_samplepair_s
 192 {
 193         float sample[SND_LISTENERS];
 194 } portable_sampleframe_t;
 195
 196 typedef struct listener_s
 197 {
 198         int channel_unswapped; // for un-swapping
 199         float yawangle;
 200         float dotscale;
 201         float dotbias;
 202         float ambientvolume;
 203 }
 204 listener_t;
 205 typedef struct speakerlayout_s
 206 {
 207         const char *name;
 208         unsigned int channels;
 209         listener_t listeners[SND_LISTENERS];
 210 }
 211 speakerlayout_t;
 212
 213 #endif