al_lock_sample_id(3)

💖 al_lock_sample_id(3) — like, the Allegro 5 API one 💖

okay bestie, so this is a page from the Library Functions Manual and it's about one very specific little function, and honestly? it's a bop. let's get into it ✨

---

🎀 NAME 🎀

al_lock_sample_id — that's the Allegro 5 API, babes 💅

---

🦋 SYNOPSIS 🦋

#include <allegro5/allegro_audio.h>

ALLEGRO_SAMPLE_INSTANCE* al_lock_sample_id(ALLEGRO_SAMPLE_ID *spl_id)

like, that's the whole signature. ALLEGRO_SAMPLE_ID *spl_id goes in, an ALLEGRO_SAMPLE_INSTANCE* comes out. slay 🫶

---

🌸 DESCRIPTION 🌸

so what this does is it locks an ALLEGRO_SAMPLE_ID(3) and hands you back the underlying ALLEGRO_SAMPLE_INSTANCE(3). the way that's genuinely useful? it lets you tweak all the various properties of that instance — think volume, pan, etc. — while the sound is playing. main character energy fr 🔥

now the important bit, no cap: this function will return NULL if the sound corresponding to the id is no longer playing. so vibe check that pointer, bestie 💀

⚠️ while it's locked, the ALLEGRO_SAMPLE_ID is unavailable to additional calls to al_play_sample(3) — and that's even if the sound stops while it's locked. so don't come for it, it's busy 🙈

to put the ALLEGRO_SAMPLE_ID back into the pool for reuse, make sure you call al_unlock_sample_id when you're done with the instance. periodt. that's non-negotiable, iykyk 👑

---

⭐ SEE ALSO ⭐

• al_play_sample(3) — the one that can't have your id while it's locked, remember?
• al_unlock_sample_id(3) — the one you literally must not forget 💜

---

🌈 SINCE 🌈

5.2.3 🎀

💀 [Unstable API]: New API. — yeah she's new, she's unstable, she's iconic. handle with care bestie 💅

---

and that's the whole thing! 🌟 this page came to you from the Allegro reference manual, footer and all, so go forth and lock those sample ids responsibly 🧚💖