play_sample(3)

📦 version 4.4.3.1, in fedora 43, fedora 44

💖 play_sample(3) — the Allegro manual's own little bop 💖

okay bestie, sit down, we're learning how to make Allegro go beep — and this one comes straight out of the Allegro manual, so you know it's the real deal 🎀

🌸 NAME 🌸

play_sample — plays a sample. Literally that's the whole job. It lives in the Allegro game programming library, and it's the function you call when you want a sound to happen right now 🦋

✨ SYNOPSIS ✨

#include <allegro.h>

int play_sample(const SAMPLE *spl, int vol, int pan, int freq, int loop);

like. five arguments. that's it. she's not complicated 💅

🎧 DESCRIPTION 🎧

So what this does: it triggers a sample at the volume, pan position, and frequency you tell it. Main character energy, no cap 🔥

  • vol and pan both range from 0 (which is min / left) all the way up to 255 (which is max / right) ⭐
  • freq is relative, not absolute — and this is the part that trips people up, so listen up bestie: 1000 represents the frequency that the sample was recorded at, 2000 is twice this, etc. It's giving pitch-shift math, iykyk 🧚
  • loop — if it's not zero, the sample will repeat until you call stop_sample(), and you can also mess with it while it's still playing by calling adjust_sample() 👑

Example time, because vibes:

/* Scream from the left speaker, twice the freq. */
int sound = play_sample(scream, 255, 0, 2000, 0);

look at that. 255 volume, 0 pan (all the way left), 2000 freq (double speed, screaming), 0 loop (she does her thing and leaves). iconic 🫶

💀 RETURN VALUE 💀

Returns the voice number that was allocated for the sample — or a negative value if no voices were available 😭 (yes that's a real thing that happens, don't @ me)

fr fr, check this return value. If it's negative, your sound did not play, and no amount of manifesting will bring it back 🍓

🌈 SEE ALSO 🌈

and that's the page, bestie!! this was Allegro version 4.4.3, signing off with the biggest play_sample(3) energy imaginable 💜✨ go make some noise 🎀

📦 where this page comes from