.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "al_lock_sample_id" "3alleg5" "" "Allegro reference manual" ""
.hy
.SH NAME
.PP
al_lock_sample_id - Allegro 5 API
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <allegro5/allegro_audio.h>

ALLEGRO_SAMPLE_INSTANCE* al_lock_sample_id(ALLEGRO_SAMPLE_ID *spl_id)
\f[R]
.fi
.SH DESCRIPTION
.PP
Locks a ALLEGRO_SAMPLE_ID(3alleg5), returning the underlying
ALLEGRO_SAMPLE_INSTANCE(3alleg5).
This allows you to adjust the various properties of the instance (such
as volume, pan, etc) while the sound is playing.
.PP
This function will return \f[V]NULL\f[R] if the sound corresponding to
the id is no longer playing.
.PP
While locked, \f[V]ALLEGRO_SAMPLE_ID\f[R] will be unavailable to
additional calls to al_play_sample(3alleg5), even if the sound stops
while locked.
To put the \f[V]ALLEGRO_SAMPLE_ID\f[R] back into the pool for reuse,
make sure to call \f[V]al_unlock_sample_id\f[R] when you\[cq]re done
with the instance.
.SH SEE ALSO
.PP
al_play_sample(3alleg5), al_unlock_sample_id(3alleg5)
.SH SINCE
.PP
5.2.3
.RS
.PP
\f[I][Unstable API]:\f[R] New API.
.RE