From c080e62637489139ed20d9781c231b691189dad5 Mon Sep 17 00:00:00 2001 From: hkc Date: Sun, 25 Feb 2024 14:21:39 +0300 Subject: [PATCH] Documentation and BREAKING CHANGES - REMOVED play_rs in favor of play:rs - REMOVED setpitchrange in favor of set:pitch - REMOVED volume in favor of set:volume - RENAMED dump to dbg:dump --- sfxd.5 | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ sfxd.5.scd | 54 +++++++++++++++++++++++++++++++++++ src/sfxd.c | 14 ++++----- 3 files changed, 144 insertions(+), 7 deletions(-) create mode 100644 sfxd.5 create mode 100644 sfxd.5.scd diff --git a/sfxd.5 b/sfxd.5 new file mode 100644 index 0000000..4dd4da2 --- /dev/null +++ b/sfxd.5 @@ -0,0 +1,83 @@ +.\" Generated by scdoc 1.11.3 +.\" Complete documentation for this program is not available as a GNU info page +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.nh +.ad l +.\" Begin generated content: +.TH "sfxd" "5" "2024-02-25" +.PP +.SH NAME +.PP +sfxd - configuration file and client commands list +.PP +.SH DESCRIPTION +.PP +Both configuration file and sfxc(1) commands use the same set of instructions.\& +.PP +Configuration file is \fBnot\fR loaded automatically, unless specified with `-C [path]` flag, but it can be loaded at a run-time via \fBsource\fR command.\& +.PP +.SH COMMANDS LIST +.PP +\fBload NAME FILE\fR Loads specified sound file and stores it under given key.\& +.br + When given key is already in use, it SHOULD be replaced with the new sound file.\& +.br + \fB\fRNAME\fB\fR is a string with no spaces, does not support escaping and used as a primary key for accessing loaded sound later.\& +.br + \fB\fRFILE\fB\fR is an absolute path to a sound file to be loaded.\& Only WAV and MP3 files are supported.\& +.PP +\fBplay NAME\fR Plays the sound with default pitch and volume.\& +.br + \fB\fRNAME\fB\fR is a key, used when \fBload\fRing a file.\& +.PP +\fBplay:rs NAME\fR Plays the sound with randomized pitch.\& +.br + Pitch range is specified with \fBset:pitch\fR command.\& +.br + \fB\fRNAME\fB\fR is a key, used when \fBload\fRing a file.\& +.PP +\fBset:pitch NAME MIN MAX\fR Sets the pitch range for \fBplay:rs\fR +.br + \fB\fRNAME\fB\fR is a key, used when \fBload\fRing a file.\& +.br + \fB\fRMIN\fB\fR is the minimum pitch.\& Can'\&t be less than 0.\& +.br + \fB\fRMAX\fB\fR is the maximum pitch.\& Can'\&t be less than 0.\& +.br + NOTE: if MAX is smaller than MIN, they are swapped.\& +.PP +\fBset:volume NAME VOLUME\fR Changes loudness for \fBplay\fR and \fBplay:rs\fR commands.\& +.br + \fB\fRNAME\fB\fR is a key, used when \fBload\fRing a file.\& +.br + \fB\fRVOLUME\fB\fR is the volume to be set.\& Can'\&t be outside of 0.\&.\&1 range +.PP +\fBsource PATH\fR Loads instructions from the configuration file.\& +.br + \fB\fRPATH\fB\fR is the file path for the configuration file.\& +.br + NOTE: there is a limit on how deep inclusion can go.\& By default it'\&s set to 32.\& +.PP +.SH DEBUG COMMANDS +.PP +\fBdbg:dump\fR Dumps contents of the hashmap.\& +.br + Prints each position of allocated hashmap and corresponding contents.\& +.br + Empty areas are shown as `(unused)`, while used ones contain volume, pitch range, calculated hash, key and file path.\& +.PP +\fBdbg:counters\fR Shows internal counters.\& Can be disabled at the compile-time.\& +.br + - `.\&pool_read` - number of reads +.br + - `.\&pool_write` - number of writes +.br + - `.\&hash_misses_read` - number of missed reads due to collision +.br + - `.\&hash_misses_write` - number of collisions in the map +.br + - `.\&pool.\&use` - number of used cells +.br + - `.\&pool.\&cap` - hashmap capacity +.PP diff --git a/sfxd.5.scd b/sfxd.5.scd new file mode 100644 index 0000000..efa0e11 --- /dev/null +++ b/sfxd.5.scd @@ -0,0 +1,54 @@ +sfxd(5) + +# NAME + +sfxd - configuration file and client commands list + +# DESCRIPTION + +Both configuration file and sfxc(1) commands use the same set of instructions. + +Configuration file is *not* loaded automatically, unless specified with `-C [path]` flag, but it can be loaded at a run-time via *source* command. + +# COMMANDS LIST + +*load NAME FILE* Loads specified sound file and stores it under given key. ++ + When given key is already in use, it SHOULD be replaced with the new sound file. ++ + **NAME** is a string with no spaces, does not support escaping and used as a primary key for accessing loaded sound later. ++ + **FILE** is an absolute path to a sound file to be loaded. Only WAV and MP3 files are supported. + +*play NAME* Plays the sound with default pitch and volume. ++ + **NAME** is a key, used when *load*ing a file. + +*play:rs NAME* Plays the sound with randomized pitch. ++ + Pitch range is specified with *set:pitch* command. ++ + **NAME** is a key, used when *load*ing a file. + +*set:pitch NAME MIN MAX* Sets the pitch range for *play:rs* ++ + **NAME** is a key, used when *load*ing a file. ++ + **MIN** is the minimum pitch. Can't be less than 0. ++ + **MAX** is the maximum pitch. Can't be less than 0. ++ + NOTE: if MAX is smaller than MIN, they are swapped. + +*set:volume NAME VOLUME* Changes loudness for *play* and *play:rs* commands. ++ + **NAME** is a key, used when *load*ing a file. ++ + **VOLUME** is the volume to be set. Can't be outside of 0..1 range + +*source PATH* Loads instructions from the configuration file. ++ + **PATH** is the file path for the configuration file. ++ + NOTE: there is a limit on how deep inclusion can go. By default it's set to 32. + +# DEBUG COMMANDS + +*dbg:dump* Dumps contents of the hashmap. ++ + Prints each position of allocated hashmap and corresponding contents. ++ + Empty areas are shown as `(unused)`, while used ones contain volume, pitch range, calculated hash, key and file path. + +*dbg:counters* Shows internal counters. Can be disabled at the compile-time. ++ + - `.pool_read` - number of reads ++ + - `.pool_write` - number of writes ++ + - `.hash_misses_read` - number of missed reads due to collision ++ + - `.hash_misses_write` - number of collisions in the map ++ + - `.pool.use` - number of used cells ++ + - `.pool.cap` - hashmap capacity + diff --git a/src/sfxd.c b/src/sfxd.c index 1f8395e..73334a8 100644 --- a/src/sfxd.c +++ b/src/sfxd.c @@ -225,7 +225,7 @@ void execute_command(struct msg_target tgt, const char *command, const char *par ma_sound_set_pitch(sfx, sound->pitch_min); ma_sound_set_volume(sfx, sound->volume); ma_sound_start(sfx); - } else if (0 == strcmp(command, "play:rs") || 0 == strcmp(command, "play_rs")) { + } else if (0 == strcmp(command, "play:rs")) { struct sfx_pool_item *sound = sfx_pool_lookup(params); if (!sound) { send_txt(tgt, "ERR: No such sound: '%s'\n", params); @@ -239,7 +239,7 @@ void execute_command(struct msg_target tgt, const char *command, const char *par ma_sound_set_pitch(sfx, pitch); ma_sound_set_volume(sfx, sound->volume); ma_sound_start(sfx); - } else if (0 == strcmp(command, "set:pitch") || 0 == strcmp(command, "setpitchrange")) { + } else if (0 == strcmp(command, "set:pitch")) { float min, max; char *key; sscanf(params, "%ms %f %f", &key, &min, &max); @@ -265,7 +265,7 @@ void execute_command(struct msg_target tgt, const char *command, const char *par sound->pitch_min = min; sound->pitch_max = max; - } else if (0 == strcmp(command, "set:volume") || 0 == strcmp(command, "volume")) { + } else if (0 == strcmp(command, "set:volume")) { float vol; char *key; sscanf(params, "%ms %f", &key, &vol); @@ -277,11 +277,13 @@ void execute_command(struct msg_target tgt, const char *command, const char *par } if (vol < 0 || vol > 1) { - send_txt(tgt, "ERR: Volume out of range: 0 <= %f < 1\n", vol); + send_txt(tgt, "ERR: Volume out of range: 0 <= %f <= 1\n", vol); } sound->volume = vol; - } else if (0 == strcmp(command, "dump")) { + } else if (0 == strcmp(command, "source")) { + execute_file(tgt, params, 0); + } else if (0 == strcmp(command, "dbg:dump")) { for (int i = 0; i < sounds_pool.cap; i++) { struct sfx_pool_item item = sounds_pool.sounds[i]; if (item.key[0] == '\0') { @@ -291,8 +293,6 @@ void execute_command(struct msg_target tgt, const char *command, const char *par i, item.volume, item.pitch_min, item.pitch_max, adler32(item.key, strlen(item.key)), item.key, item.path); } } - } else if (0 == strcmp(command, "source")) { - execute_file(tgt, params, 0); } else if (0 == strcmp(command, "dbg:counters")) { #ifdef NO_COUNTERS send_txt(tgt, "ERR: counters are disabled at compile-time with NO_COUNTERS feature flag.");