1/****n* PawnLibs/sound/SND_getAssetId
2 * Summary
3 *   Get a sound ID by the filename.
4 * Synopsis
5 */
6native SND_getAssetId(const name[]);
7/*
8 * Description
9 *   Usually an application uses sound IDs to start playback. TBD: SDK should
10 *   have way to specify ID for sound/image. But sometimes IDs are unknown, e.g.
11 *   in common libraries, or they change rapidly during development. This
12 *   interface can be used to get an ID of the sound by its filename in the
13 *   runtime. Recommended way is to use this function in initialization code.
14 *   Maximum asset name length is 15 characters remaining symbols are truncated
15 *   during lookup.
16 * Inputs
17 *   * name - sound filename for which ID is requested
18 * Return value
19 *   The ID of sound with a given filename or -1 in case of error.
20 * See also
21 *   * SND_play()
22 *   * ON_Init()
23 * History
24 *   * v5.0 - renamed from SND_getId() to SND_getAssetId()
25 *   * v6.0 - truncate asset name in WASM API
26 ******/
27 
28/****n* PawnLibs/sound/SND_play
29 * Summary
30 *   Play sound by ID.
31 * Synopsis
32 */
33native SND_play(const id, const volume);
34/*
35 * Description
36 *   Play any sound by its ID. Platform does not support audio mixing, so
37 *   previously playing sound will be stopped if it has not yet finished.
38 *   Supported audio formats:
39 *   * WAV
40 *   * MP3
41 *   * MIDI
42 * Inputs
43 *   * id - an ID of sound to play
44 *   * volume - volume of sound in percents to play, range 0..100
45 * See also
46 *   * SND_getAssetId()
47 ******/
48 
49/****n* PawnLibs/sound/SND_cacheSounds
50 * Summary
51 *   Force platform to cache application sounds.
52 * Synopsis
53 */
54native SND_cacheSounds(soundList[], size = sizeof(soundList));
55/*
56 * Description
57 *   Platform automatically reads and caches sounds from flash when the
58 *   application plays a sound. Flash operations are synchronous and may cause
59 *   delays especially when reading large portions of data. To prevent the
60 *   application from lags it is possible to cache sound data in advance.
61 *   However if application requests to play a non-cached sound and there is not
62 *   enough memory then oldest accessed sounds will be removed from cache. Also
63 *   there is a limit of 256 for a total number of cached sounds.
64 * Inputs
65 *   * soundList - array with IDs of sounds to cache
66 *   * size - size of soundList array
67 * Return value
68 *   Number of cached sounds or negative value if an error happened. Error
69 *   codes:
70 *   * -1 invalid function arguments count
71 *   * -2 invalid soundList array
72 * History
73 *   * v5.0 - moved from appCtrl module to sound
74 ******/
75 
76/****n* PawnLibs/sound/SND_isPlaying
77 * Summary
78 *   Check if audio is playing.
79 * Synopsis
80 */
81native bool:SND_isPlaying();
82/*
83 * Return value
84 *   True if audio is playing, false otherwise.
85 * History
86 *   * v6.0 - added
87 ******/
88 
89/****n* PawnLibs/sound/SND_stop
90 * Summary
91 *   Stop playing sound if any.
92 * Synopsis
93 */
94native SND_stop();
95/*
96 * See also
97 *   * SND_play()
98 * History
99 *   * v6.0 - added
100 ******/
101 
102/****n* PawnLibs/sound/SND_getAssetsCount
103 * Summary
104 *   Get the total count of sound assets.
105 * Synopsis
106 */
107native SND_getAssetsCount();
108/*
109 * Return value
110 *   Number of sound assets.
111 * History
112 *   * v6.0 - added
113 ******/
114 
115 /****f* PawnLibs/sound/PlayRandomSound
116 * Summary
117 *   Play random sound from an array.
118 * Synopsis
119 */
120stock bool:PlayRandomSound(const snd[], const volume, const bool: stopPlaying = true, size = sizeof(snd))
121/*
122 * Description
123 *   Play random sound from an array.
124 * Inputs
125 *   * snd - the array of sounds from which the sound will be selected
126 *   * volume - sound volume
127 *   * stopPlaying - stop sound playback if it is being played
128 *   * size - size of the array snd
129 * Return value
130 * See also
131 *   * PlayLoopRandomSound()
132 * Source
133 */
134{
135    if (SND_isPlaying()) {
136        if (stopPlaying) {
137            SND_stop();
138        } else {
139            return false;
140        }
141    }
142 
143    SND_play(snd[random(0, size - 1)], volume);
144    return true;
145}
146/******/
147 
148/****f* PawnLibs/sound/PlayLoopRandomSound
149 * Summary
150 *   Play random sound from an array in a loop with a specified delay range.
151 * Synopsis
152 */
153stock PlayLoopRandomSound(const snd[], const volume, const delayMin, const delayMax, dt, size = sizeof(snd))
154/*
155 * Description
156 *   Play random sound from an array in a loop with a specified delay range.
157 * Inputs
158 *   * snd - the array of sounds from which the sound will be selected
159 *   * volume - sound volume
160 *   * delayMin - minimum delay
161 *   * delayMax - maximum delay
162 *   * dt - delta time
163 *   * size - size of the array snd
164 * Return value
165 * See also
166 *   * PlayRandomSound()
167 * Source
168 */
169{
170    static delay = 0;
171 
172    if (SND_isPlaying())
173        return;
174 
175    if (delay <= 0) {
176        delay = random(delayMin, delayMax);
177    } else {
178        delay -= dt;
179    }
180 
181    SND_play(snd[random(0, size - 1)], volume);
182}
183/******/
184