set_volume_per_voice(3alleg4)

💖 set_volume_per_voice 💖

okay bestie, so this is a page from the Allegro manual — the Allegro game programming library, version 4.4.3 — and it's all about setting the volume of a voice. yes, one single function, but the lore runs deep. let's get into it 🎀

✨ SYNOPSIS ✨

#include <allegro.h>

void set_volume_per_voice(int scale);

like. that's it. that's the whole function signature. int scale in, vibes out. 💅

🌸 DESCRIPTION 🌸

so by default, Allegro plays a centred sample at half volume on both the left and right channel. but a sample panned allll the way to the far right or far left? that one gets played at maximum volume on that channel only. why tho? so you can play a single panned sample without distortion, periodt. 🫶

but here's the tea: if you play multiple samples at full volume, the mixing process can result in clipping, which is a very noticeable form of distortion. and the more samples you stack, the more likely clipping is to happen — and the more clipping there is, the worse your output is gonna sound. it's giving crunchy. it's giving not cute. 😭

so if clipping is a problem — or honestly if the output is just too quiet — this function is your girl. she adjusts the volume of each voice. but before you go touching anything, bestie, do the checklist first:

1. check that your speakers are at a reasonable volume
2. check that Allegro's global volume is at maximum (peep set_volume() below 👀)
3. check any other mixers, like the Windows Volume Control, are set reasonably

once you're sure Allegro's output level is genuinely unsuitable for your application, then you use this function to adjust it. no skipping steps, i'm serious. 🙈

the math: every time you increase the parameter by one, the volume of each voice halves. so like, if you pass 4, you can play up to 16 centred samples at maximum volume without distortion. slay.

if you pass 0: each centred sample will play at the maximum volume possible without distortion, and so will all samples played through a mono driver. but — samples at the extreme left and right will distort if played at full volume. so watch out. 💀

if you wanna play panned samples at full volume without distortion: pass 1. that's the move. ✨

⚠️ Note: this is different from the function's behaviour in WIPs 3.9.34, 3.9.35 and 3.9.36. if you used this function under one of these WIPs, you'll have to increase your parameter by one to get the same volume. yes really. not me finding out the hard way.

⚠️ Note: the default behaviour has changed as of Allegro 4.1.15. if you want the behaviour of earlier versions of Allegro, pass -1 to this function. Allegro will choose a value dependent on the number of voices, so that if you reserve n voices, you can play up to n/2 normalised samples with centre panning without risking distortion. the exception is when you have fewer than 8 voices — then the volume remains the same as for 8 voices. here are the values, dependent on the number of voices:

• 1-8 voices — set_volume_per_voice(2)
• 16 voices — set_volume_per_voice(3)
• 32 voices — set_volume_per_voice(4)
• 64 voices — set_volume_per_voice(5)

and no, this function does not override the volume you specify with play_sample() or voice_set_volume(). it simply alters the overall output of the program. and if you play samples at lower volumes, or if they're not normalised, then you can play more of them without distortion. the more you know 🌈

hot tip: it is recommended that you hard-code the parameter into your program, rather than offering it to the user. the user can alter the volume with the configuration file instead, or you can provide for this with set_volume(). don't make your users do your job, bestie, main character energy means handling your own defaults. 👑

and finally: to restore volume per voice to its default behaviour, pass 1. that's the reset button. you're welcome. 🎀

🦋 SEE ALSO 🦋

• reserve_voices(3alleg4)
• set_volume(3alleg4)
• install_sound(3alleg4)
• detect_digi_driver(3alleg4)
• detect_midi_driver(3alleg4)

okay that's the whole page, you ate it, go make some non-clipping bangers 🔥 this was Allegro, version 4.4.3, the set_volume_per_voice(3alleg4) manual page — mwah, love u, bye 💜