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
This commit is contained in:
Casey 2024-02-25 14:21:39 +03:00
parent 95bc6e7d33
commit c080e62637
Signed by: hkc
GPG Key ID: F0F6CFE11CDB0960
3 changed files with 144 additions and 7 deletions

83
sfxd.5 Normal file
View File

@ -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

54
sfxd.5.scd Normal file
View File

@ -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

View File

@ -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.");