From 640f07df6c7ece5387a2bbc5d1840dc4c43a57db Mon Sep 17 00:00:00 2001
From: bones_was_here <bones_was_here@xonotic.au>
Date: Thu, 5 Sep 2024 03:40:05 +1000
Subject: [PATCH] snd: doxygen compat and related whitespace
IDEs also support these comment formats.
Signed-off-by: bones_was_here <bones_was_here@xonotic.au>
---
snd_main.h | 142 +++++++++++++++++++++++++++--------------------------
sound.h | 2 +-
2 files changed, 73 insertions(+), 71 deletions(-)
diff --git a/snd_main.h b/snd_main.h
index bb05f580..6eb7b8ea 100644
--- a/snd_main.h
+++ b/snd_main.h
@@ -36,46 +36,48 @@ typedef struct snd_format_s
typedef struct snd_buffer_s
{
- snd_format_t format;
- unsigned int nbframes; // current size, in sample frames
- unsigned int maxframes; // max size (buffer size), in sample frames
- unsigned char samples[4]; // variable sized
+ snd_format_t format;
+ unsigned int nbframes; ///< current size, in sample frames
+ unsigned int maxframes; ///< max size (buffer size), in sample frames
+ unsigned char samples[4]; ///< variable sized
} snd_buffer_t;
typedef struct snd_ringbuffer_s
{
- snd_format_t format;
- unsigned char* ring;
- unsigned int maxframes; // max size (buffer size), in sample frames
- unsigned int startframe; // index of the first frame in the buffer
- // if startframe == endframe, the bufffer is empty
- unsigned int endframe; // index of the first EMPTY frame in the "ring" buffer
- // may be smaller than startframe if the "ring" buffer has wrapped
+ snd_format_t format;
+ unsigned char *ring;
+ unsigned int maxframes; ///< max size (buffer size), in sample frames
+ /// index of the first frame in the buffer
+ /// if startframe == endframe, the bufffer is empty
+ unsigned int startframe;
+ /// index of the first EMPTY frame in the "ring" buffer
+ /// may be smaller than startframe if the "ring" buffer has wrapped
+ unsigned int endframe;
} snd_ringbuffer_t;
// struct sfx_s flags
-#define SFXFLAG_NONE 0
-#define SFXFLAG_FILEMISSING (1 << 0) // wasn't able to load the associated sound file
-#define SFXFLAG_LEVELSOUND (1 << 1) // the sfx is part of the server or client precache list for this level
-#define SFXFLAG_STREAMED (1 << 2) // informative only. You shouldn't need to know that
-#define SFXFLAG_MENUSOUND (1 << 3) // not freed during level change (menu sounds, music, etc)
+#define SFXFLAG_NONE 0
+#define SFXFLAG_FILEMISSING (1 << 0) ///< wasn't able to load the associated sound file
+#define SFXFLAG_LEVELSOUND (1 << 1) ///< the sfx is part of the server or client precache list for this level
+#define SFXFLAG_STREAMED (1 << 2) ///< informative only. You shouldn't need to know that
+#define SFXFLAG_MENUSOUND (1 << 3) ///< not freed during level change (menu sounds, music, etc)
typedef struct snd_fetcher_s snd_fetcher_t;
struct sfx_s
{
- char name[MAX_QPATH];
- struct sfx_s *next;
- size_t memsize; // total memory used (including struct sfx_s and fetcher data)
-
- snd_format_t format; // format describing the audio data that fetcher->getsamplesfloat will return
- unsigned int flags; // cf SFXFLAG_* defines
- unsigned int loopstart; // in sample frames. equals total_length if not looped
- unsigned int total_length; // in sample frames
- const snd_fetcher_t *fetcher;
- void *fetcher_data; // Per-sfx data for the sound fetching functions
-
- float volume_mult; // for replay gain (multiplier to apply)
- float volume_peak; // for replay gain (highest peak); if set to 0, ReplayGain isn't supported
+ char name[MAX_QPATH];
+ struct sfx_s *next;
+ size_t memsize; ///< total memory used (including struct sfx_s and fetcher data)
+
+ snd_format_t format; ///< format describing the audio data that fetcher->getsamplesfloat will return
+ unsigned int flags; ///< cf SFXFLAG_* defines
+ unsigned int loopstart; ///< in sample frames. equals total_length if not looped
+ unsigned int total_length; ///< in sample frames
+ const snd_fetcher_t *fetcher;
+ void *fetcher_data; ///< Per-sfx data for the sound fetching functions
+
+ float volume_mult; ///< for replay gain (multiplier to apply)
+ float volume_peak; ///< for replay gain (highest peak); if set to 0, ReplayGain isn't supported
};
// maximum supported speakers constant
@@ -84,26 +86,26 @@ struct sfx_s
typedef struct channel_s
{
// provided sound information
- struct sfx_s *sfx; // pointer to sound sample being used
- float basevolume; // 0-1 master volume
- unsigned int flags; // cf CHANNELFLAG_* defines
- int entnum; // makes sound follow entity origin (allows replacing interrupting existing sound on same id)
- int entchannel; // which channel id on the entity
- vec3_t origin; // origin of sound effect
- vec_t distfade; // distance multiplier (attenuation/clipK)
- void *fetcher_data; // Per-channel data for the sound fetching function
- int prologic_invert;// whether a sound is played on the surround channels in prologic
- float basespeed; // playback rate multiplier for pitch variation
-
- // these are often updated while mixer is running, glitching should be minimized (mismatched channel volumes from spatialization is okay)
- // spatialized playback speed (speed * doppler ratio)
- float mixspeed;
- // spatialized volume per speaker (mastervol * distanceattenuation * channelvolume cvars)
- float volume[SND_LISTENERS];
-
- // updated ONLY by mixer
- // position in sfx, starts at 0, loops or stops at sfx->total_length
- double position;
+ struct sfx_s *sfx; ///< pointer to sound sample being used
+ float basevolume; ///< 0-1 master volume
+ unsigned int flags; ///< cf CHANNELFLAG_* defines
+ int entnum; ///< makes sound follow entity origin (allows replacing interrupting existing sound on same id)
+ int entchannel; ///< which channel id on the entity
+ vec3_t origin; ///< origin of sound effect
+ vec_t distfade; ///< distance multiplier (attenuation/clipK)
+ void *fetcher_data; ///< Per-channel data for the sound fetching function
+ int prologic_invert; ///< whether a sound is played on the surround channels in prologic
+ float basespeed; ///< playback rate multiplier for pitch variation
+
+ /// these are often updated while mixer is running, glitching should be minimized (mismatched channel volumes from spatialization is okay)
+ /// spatialized playback speed (speed * doppler ratio)
+ float mixspeed;
+ /// spatialized volume per speaker (mastervol * distanceattenuation * channelvolume cvars)
+ float volume[SND_LISTENERS];
+
+ /// updated ONLY by mixer
+ /// position in sfx, starts at 0, loops or stops at sfx->total_length
+ double position;
} channel_t;
// Sound fetching functions
@@ -113,17 +115,17 @@ typedef void (*snd_fetcher_stopchannel_t) (channel_t *ch);
typedef void (*snd_fetcher_freesfx_t) (struct sfx_s *sfx);
struct snd_fetcher_s
{
- snd_fetcher_getsamplesfloat_t getsamplesfloat;
- snd_fetcher_stopchannel_t stopchannel;
- snd_fetcher_freesfx_t freesfx;
+ snd_fetcher_getsamplesfloat_t getsamplesfloat;
+ snd_fetcher_stopchannel_t stopchannel;
+ snd_fetcher_freesfx_t freesfx;
};
extern unsigned int total_channels;
extern channel_t channels[MAX_CHANNELS];
extern snd_ringbuffer_t *snd_renderbuffer;
-extern qbool snd_threaded; // enables use of snd_usethreadedmixing, provided that no sound hacks are in effect (like timedemo)
-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
+extern qbool snd_threaded; ///< enables use of snd_usethreadedmixing, provided that no sound hacks are in effect (like timedemo)
+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
extern cvar_t snd_mutewhenidle;
extern cvar_t snd_waterfx;
@@ -139,13 +141,13 @@ extern int snd_blocked; // counter. When > 0, we stop submitting sound to the a
extern struct mempool_s *snd_mempool;
-// If simsound is true, the sound card is not initialized and no sound is submitted to it.
-// More generally, all arch-dependent operations are skipped or emulated.
-// Used for isolating performance in the renderer.
+/// If simsound is true, the sound card is not initialized and no sound is submitted to it.
+/// More generally, all arch-dependent operations are skipped or emulated.
+/// Used for isolating performance in the renderer.
extern qbool simsound;
-#define STREAM_BUFFERSIZE 16384 // in sampleframes
+#define STREAM_BUFFERSIZE 16384 ///< in sampleframes
// ====================================================================
@@ -158,8 +160,8 @@ void S_MixToBuffer(void *stream, unsigned int frames);
qbool S_LoadSound (struct sfx_s *sfx, qbool complain);
-// If "buffer" is NULL, the function allocates one buffer of "sampleframes" sample frames itself
-// (if "sampleframes" is 0, the function chooses the size).
+/// If "buffer" is NULL, the function allocates one buffer of "sampleframes" sample frames itself
+/// (if "sampleframes" is 0, the function chooses the size).
snd_ringbuffer_t *Snd_CreateRingBuffer (const snd_format_t* format, unsigned int sampleframes, void* buffer);
@@ -167,29 +169,29 @@ snd_ringbuffer_t *Snd_CreateRingBuffer (const snd_format_t* format, unsigned int
// Architecture-dependent functions
// ====================================================================
-// 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)
-// Note: SDL automatically converts all formats, so this only fails if there is no audio
+/// 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)
+/// Note: SDL automatically converts all formats, so this only fails if there is no audio
qbool SndSys_Init (snd_format_t* fmt);
-// Stop the sound card, delete "snd_renderbuffer" and free its other resources
+/// Stop the sound card, delete "snd_renderbuffer" and free its other resources
void SndSys_Shutdown (void);
-// Submit the contents of "snd_renderbuffer" to the sound card
+/// Submit the contents of "snd_renderbuffer" to the sound card
void SndSys_Submit (void);
-// Returns the number of sample frames consumed since the sound started
+/// Returns the number of sample frames consumed since the sound started
unsigned int SndSys_GetSoundTime (void);
-// Get the exclusive lock on "snd_renderbuffer"
+/// Get the exclusive lock on "snd_renderbuffer"
qbool SndSys_LockRenderBuffer (void);
-// Release the exclusive lock on "snd_renderbuffer"
+/// Release the exclusive lock on "snd_renderbuffer"
void SndSys_UnlockRenderBuffer (void);
-// if the sound system can generate events, send them
+/// if the sound system can generate events, send them
void SndSys_SendKeyEvents(void);
-// exported for capturevideo so ogg can see all channels
+/// exported for capturevideo so ogg can see all channels
typedef struct portable_samplepair_s
{
float sample[SND_LISTENERS];
@@ -197,7 +199,7 @@ typedef struct portable_samplepair_s
typedef struct listener_s
{
- int channel_unswapped; // for un-swapping
+ int channel_unswapped; ///< for un-swapping
float yawangle;
float dotscale;
float dotbias;
diff --git a/sound.h b/sound.h
index f231fc98..58a14fc3 100644
--- a/sound.h
+++ b/sound.h
@@ -91,7 +91,7 @@ sfx_t *S_FindName(const char *name);
#define CHAN_ENGINE2USER(c) (c)
#define CHAN_ENGINE2CVAR(c) (abs(c))
-// S_StartSound returns the channel index, or -1 if an error occurred
+/// S_StartSound returns the channel index, or -1 if an error occurred
int S_StartSound (int entnum, int entchannel, sfx_t *sfx, vec3_t origin, float fvol, float attenuation);
int S_StartSound_StartPosition_Flags (int entnum, int entchannel, sfx_t *sfx, vec3_t origin, float fvol, float attenuation, float startposition, int flags, float fspeed);
qbool S_LocalSoundEx (const char *s, int chan, float fvol);
--
2.39.5