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 <stddef.h>
  25 #include "qtypes.h"
  26 #include "qdefs.h"
  27 struct mempool_s;
  28 struct sfx_s;
  29
  30 typedef struct snd_format_s
  31 {
  32         unsigned int    speed;
  33         unsigned short  width;
  34         unsigned short  channels;
  35 } snd_format_t;
  36
  37 typedef struct snd_buffer_s
  38 {
  39         snd_format_t            format;
  40         unsigned int            nbframes;       // current size, in sample frames
  41         unsigned int            maxframes;      // max size (buffer size), in sample frames
  42         unsigned char           samples[4];     // variable sized
  43 } snd_buffer_t;
  44
  45 typedef struct snd_ringbuffer_s
  46 {
  47         snd_format_t            format;
  48         unsigned char*          ring;
  49         unsigned int            maxframes;      // max size (buffer size), in sample frames
  50         unsigned int            startframe;     // index of the first frame in the buffer
  51                                                                         // if startframe == endframe, the bufffer is empty
  52         unsigned int            endframe;       // index of the first EMPTY frame in the "ring" buffer
  53                                                                         // may be smaller than startframe if the "ring" buffer has wrapped
  54 } snd_ringbuffer_t;
  55
  56 // struct sfx_s flags
  57 #define SFXFLAG_NONE                    0
  58 #define SFXFLAG_FILEMISSING             (1 << 0) // wasn't able to load the associated sound file
  59 #define SFXFLAG_LEVELSOUND              (1 << 1) // the sfx is part of the server or client precache list for this level
  60 #define SFXFLAG_STREAMED                (1 << 2) // informative only. You shouldn't need to know that
  61 #define SFXFLAG_MENUSOUND               (1 << 3) // not freed during level change (menu sounds, music, etc)
  62
  63 typedef struct snd_fetcher_s snd_fetcher_t;
  64 struct sfx_s
  65 {
  66         char                            name[MAX_QPATH];
  67         struct sfx_s                            *next;
  68         size_t                          memsize;                // total memory used (including struct sfx_s and fetcher data)
  69
  70         snd_format_t            format;                 // format describing the audio data that fetcher->getsamplesfloat will return
  71         unsigned int            flags;                  // cf SFXFLAG_* defines
  72         unsigned int            loopstart;              // in sample frames. equals total_length if not looped
  73         unsigned int            total_length;   // in sample frames
  74         const snd_fetcher_t     *fetcher;
  75         void                            *fetcher_data;  // Per-sfx data for the sound fetching functions
  76
  77         float                           volume_mult;    // for replay gain (multiplier to apply)
  78         float                           volume_peak;    // for replay gain (highest peak); if set to 0, ReplayGain isn't supported
  79 };
  80
  81 // maximum supported speakers constant
  82 #define SND_LISTENERS 8
  83
  84 typedef struct channel_s
  85 {
  86         // provided sound information
  87         struct sfx_s                    *sfx;                   // pointer to sound sample being used
  88         float                   basevolume;             // 0-1 master volume
  89         unsigned int    flags;                  // cf CHANNELFLAG_* defines
  90         int                             entnum;                 // makes sound follow entity origin (allows replacing interrupting existing sound on same id)
  91         int                             entchannel;             // which channel id on the entity
  92         vec3_t                  origin;                 // origin of sound effect
  93         vec_t                   distfade;               // distance multiplier (attenuation/clipK)
  94         void                    *fetcher_data;  // Per-channel data for the sound fetching function
  95         int                             prologic_invert;// whether a sound is played on the surround channels in prologic
  96         float                   basespeed;              // playback rate multiplier for pitch variation
  97
  98         // these are often updated while mixer is running, glitching should be minimized (mismatched channel volumes from spatialization is okay)
  99         // spatialized playback speed (speed * doppler ratio)
 100         float                   mixspeed;
 101         // spatialized volume per speaker (mastervol * distanceattenuation * channelvolume cvars)
 102         float                   volume[SND_LISTENERS];
 103
 104         // updated ONLY by mixer
 105         // position in sfx, starts at 0, loops or stops at sfx->total_length
 106         double                  position;
 107 } channel_t;
 108
 109 // Sound fetching functions
 110 // "start" is both an input and output parameter: it returns the actual start time of the sound buffer
 111 typedef void (*snd_fetcher_getsamplesfloat_t) (channel_t *ch, struct sfx_s *sfx, int firstsampleframe, int numsampleframes, float *outsamplesfloat);
 112 typedef void (*snd_fetcher_stopchannel_t) (channel_t *ch);
 113 typedef void (*snd_fetcher_freesfx_t) (struct sfx_s *sfx);
 114 struct snd_fetcher_s
 115 {
 116         snd_fetcher_getsamplesfloat_t           getsamplesfloat;
 117         snd_fetcher_stopchannel_t               stopchannel;
 118         snd_fetcher_freesfx_t           freesfx;
 119 };
 120
 121 extern unsigned int total_channels;
 122 extern channel_t channels[MAX_CHANNELS];
 123
 124 extern snd_ringbuffer_t *snd_renderbuffer;
 125 extern qbool snd_threaded; // enables use of snd_usethreadedmixing, provided that no sound hacks are in effect (like timedemo)
 126 extern qbool 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
 127
 128 extern struct cvar_s _snd_mixahead;
 129 extern struct cvar_s snd_swapstereo;
 130 extern struct cvar_s snd_streaming;
 131 extern struct cvar_s snd_streaming_length;
 132
 133 #define SND_CHANNELLAYOUT_AUTO          0
 134 #define SND_CHANNELLAYOUT_STANDARD      1
 135 #define SND_CHANNELLAYOUT_ALSA          2
 136 extern struct cvar_s snd_channellayout;
 137
 138 extern int snd_blocked;         // counter. When > 0, we stop submitting sound to the audio device
 139
 140 extern struct mempool_s *snd_mempool;
 141
 142 // If simsound is true, the sound card is not initialized and no sound is submitted to it.
 143 // More generally, all arch-dependent operations are skipped or emulated.
 144 // Used for isolating performance in the renderer.
 145 extern qbool simsound;
 146
 147
 148 #define STREAM_BUFFERSIZE 16384 // in sampleframes
 149
 150
 151 // ====================================================================
 152 //         Architecture-independent functions
 153 // ====================================================================
 154
 155 void S_MixToBuffer(void *stream, unsigned int frames);
 156
 157 qbool S_LoadSound (struct sfx_s *sfx, qbool complain);
 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", attempting to use the chosen sound format, but accepting if the driver wants to change it (e.g. 7.1 to stereo or lowering the speed)
 169 // Note: SDL automatically converts all formats, so this only fails if there is no audio
 170 qbool SndSys_Init (snd_format_t* fmt);
 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 qbool 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