1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
|
.TH al_create_audio_stream 3 "" "Allegro reference manual"
.SH NAME
.PP
al_create_audio_stream \- Allegro 5 API
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <allegro5/allegro_audio.h>
ALLEGRO_AUDIO_STREAM\ *al_create_audio_stream(size_t\ fragment_count,
\ \ \ unsigned\ int\ frag_samples,\ unsigned\ int\ freq,\ ALLEGRO_AUDIO_DEPTH\ depth,
\ \ \ ALLEGRO_CHANNEL_CONF\ chan_conf)
\f[]
.fi
.SH DESCRIPTION
.PP
Creates an ALLEGRO_AUDIO_STREAM(3).
The stream will be set to play by default.
It will feed audio data from a buffer, which is split into a number of
fragments.
.PP
Parameters:
.IP \[bu] 2
fragment_count \- How many fragments to use for the audio stream.
Usually only two fragments are required \- splitting the audio buffer in
two halves.
But it means that the only time when new data can be supplied is
whenever one half has finished playing.
When using many fragments, you usually will use fewer samples for one,
so there always will be (small) fragments available to be filled with
new data.
.IP \[bu] 2
frag_samples \- The size of a fragment in samples.
See note below.
.IP \[bu] 2
freq \- The frequency, in Hertz.
.IP \[bu] 2
depth \- Must be one of the values listed for ALLEGRO_AUDIO_DEPTH(3).
.IP \[bu] 2
chan_conf \- Must be one of the values listed for
ALLEGRO_CHANNEL_CONF(3).
.PP
The choice of \f[I]fragment_count\f[], \f[I]frag_samples\f[] and
\f[I]freq\f[] directly influences the audio delay.
The delay in seconds can be expressed as:
.IP
.nf
\f[C]
delay\ =\ fragment_count\ *\ frag_samples\ /\ freq
\f[]
.fi
.PP
This is only the delay due to Allegro\[aq]s streaming, there may be
additional delay caused by sound drivers and/or hardware.
.RS
.PP
\f[I]Note:\f[] If you know the fragment size in bytes, you can get the
size in samples like this:
.IP
.nf
\f[C]
sample_size\ =\ al_get_channel_count(chan_conf)\ *\ al_get_audio_depth_size(depth);
samples\ =\ bytes_per_fragment\ /\ sample_size;
\f[]
.fi
.PP
The size of the complete buffer is:
.IP
.nf
\f[C]
buffer_size\ =\ bytes_per_fragment\ *\ fragment_count
\f[]
.fi
.RE
.RS
.PP
\f[I]Note:\f[] unlike many Allegro objects, audio streams are not
implicitly destroyed when Allegro is shut down.
You must destroy them manually with al_destroy_audio_stream(3) before
the audio system is shut down.
.RE
|
