Commit | Line | Data |
d49f81db |
1 | <div class="pod"> |
2 | <!-- INDEX START --> |
3 | <h3 id="TOP">Index</h3> |
4 | |
5 | <ul><li><a href="#NAME">NAME</a></li> |
b5d537cc |
6 | <li><a href="#CATEGORY">CATEGORY</a></li> |
b5d537cc |
7 | <li><a href="#METHODS">METHODS</a> |
2d13cef7 |
8 | <ul><li><a href="#load_MUS">load_MUS</a></li> |
b5d537cc |
9 | <li><a href="#hook_music">hook_music</a></li> |
10 | <li><a href="#hook_music_finished">hook_music_finished</a></li> |
11 | <li><a href="#get_music_hook_data">get_music_hook_data</a></li> |
12 | <li><a href="#play_music">play_music</a></li> |
13 | <li><a href="#fade_in_music">fade_in_music</a></li> |
b5d537cc |
14 | <li><a href="#fade_out_music">fade_out_music</a></li> |
15 | <li><a href="#fading_music">fading_music</a></li> |
e37eb258 |
16 | <li><a href="#volume_music">volume_music</a></li> |
17 | <li><a href="#halt_music">halt_music</a></li> |
b5d537cc |
18 | <li><a href="#pause_music">pause_music</a></li> |
19 | <li><a href="#resume_music">resume_music</a></li> |
20 | <li><a href="#rewind_music">rewind_music</a></li> |
e37eb258 |
21 | <li><a href="#set_music_position">set_music_position</a></li> |
b5d537cc |
22 | <li><a href="#paused_music">paused_music</a></li> |
2d13cef7 |
23 | <li><a href="#playing_music">playing_music</a></li> |
b5d537cc |
24 | </ul> |
d49f81db |
25 | </li> |
2d13cef7 |
26 | <li><a href="#AUTHOR">AUTHOR</a> |
27 | </li> |
d49f81db |
28 | </ul><hr /> |
29 | <!-- INDEX END --> |
30 | |
31 | <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p> |
32 | <div id="NAME_CONTENT"> |
2d13cef7 |
33 | <p>SDL::Mixer::Music - functions for music</p> |
d49f81db |
34 | |
35 | </div> |
36 | <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p> |
37 | <div id="CATEGORY_CONTENT"> |
b5d537cc |
38 | <p>Mixer</p> |
39 | |
40 | </div> |
b5d537cc |
41 | <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
42 | <div id="METHODS_CONTENT"> |
43 | |
44 | </div> |
b5d537cc |
45 | <h2 id="load_MUS">load_MUS</h2> |
46 | <div id="load_MUS_CONTENT"> |
071b4b10 |
47 | <pre> my $music = SDL::Mixer::Music::load_MUS( $file ); |
48 | |
49 | </pre> |
195e87cb |
50 | <p><code>load_MUS</code> loads a music file into a <code>SDL::Mixer::MixMusic</code> structure. This can be passed to <a href="/SDL-Mixer-Music.html#play_music">SDL::Mixer::Music::play_music</a>.</p> |
b5d537cc |
51 | |
52 | </div> |
b5d537cc |
53 | <h2 id="hook_music">hook_music</h2> |
54 | <div id="hook_music_CONTENT"> |
2d13cef7 |
55 | <pre> SDL::Mixer::Music::hook_music( $callback, $position ); |
56 | |
57 | or |
58 | |
59 | SDL::Mixer::Music::hook_music( &callback, $position ); |
60 | |
61 | </pre> |
62 | <p>This sets up a custom music player function, so you can pass your own audio stream data into the SDL::Mixer. |
63 | The function will be called with <code>position</code> passed into the first parameter when the <code>callback</code> is called. |
64 | The audio stream buffer has to be filled with length bytes of music (2nd parameter). |
65 | The music player will then be called automatically when the mixer needs it. Music playing will start as soon as this is called. |
66 | All the music playing and stopping functions have no effect on music after this. Pause and resume will work. |
67 | Using a custom music player and the internal music player is not possible, the custom music player takes priority. </p> |
68 | <p>To stop the custom music player call <code>hook_music()</code> without arguments.</p> |
92e293d6 |
69 | <p><strong>Note</strong>: NEVER call <code>SDL::Mixer</code> functions, nor <a href="/SDL-Audio.html#lock">SDL::Audio::lock</a>, from a callback function.</p> |
2d13cef7 |
70 | <p><strong>Note</strong>: At program termination also call <code>SDL::Mixer::Music::hook_music()</code> to stop this callback.</p> |
71 | <p>Example:</p> |
72 | <pre> my $callback = sub |
73 | { |
74 | my $position = shift; # position (first time its 0, on each call $length is added) |
75 | my $length = shift; # length of bytes we have to put in stream |
76 | my @stream = ''; |
77 | |
78 | printf("position=%8d, stream length=%6d\n", $position, $length); |
79 | |
80 | for(my $i = 0; $i < $length; $i++) |
81 | { |
82 | push(@stream, (($i + $position) & 0xFF)); |
83 | } |
84 | |
85 | return @stream; |
86 | }; |
87 | |
88 | SDL::Mixer::Music::hook_music( $callback, 0 ); |
89 | |
90 | </pre> |
b5d537cc |
91 | |
92 | </div> |
93 | <h2 id="hook_music_finished">hook_music_finished</h2> |
94 | <div id="hook_music_finished_CONTENT"> |
2d13cef7 |
95 | <pre> SDL::Mixer::Music::hook_music_finished( $callback ); |
96 | |
97 | </pre> |
195e87cb |
98 | <p>This callback is called when music called by e.g. <a href="/SDL-Mixer-Music.html#play_music">SDL::Mixer::Music::play_music</a> or <a href="/SDL-Mixer-Music.html#fade_in_music">SDL::Mixer::Music::fade_in_music</a> stops naturally. |
99 | This happens when the music is over or is fading out.</p> |
100 | <p><strong>Note</strong>: If you play music via <a href="/SDL-Mixer-Music.html#hook_music">SDL::Mixer::Music::hook_music</a>, this callback will never be called.</p> |
2d13cef7 |
101 | <p>Example:</p> |
102 | <pre> my $music_is_playing = 0; |
103 | my @music = qw(first.mp3 next.mp3 other.mp3 last.mp3); |
104 | my $callback = sub{ $music_is_playing = 0; }; |
105 | SDL::Mixer::Music::hook_music_finished( $callback ); |
106 | |
107 | foreach my $this_song ( @music ) |
108 | { |
109 | SDL::Mixer::Music::play_music( $this_song, 0 ); |
110 | $music_is_playing = 1; |
111 | |
112 | SDL::delay( 100 ) while( $music_is_playing ); |
113 | } |
114 | |
115 | SDL::Mixer::Music::hook_music_finished(); # cleanup |
116 | |
117 | </pre> |
b5d537cc |
118 | |
119 | </div> |
120 | <h2 id="get_music_hook_data">get_music_hook_data</h2> |
121 | <div id="get_music_hook_data_CONTENT"> |
2d13cef7 |
122 | <pre> my $position = SDL::Mixer::Music::get_music_hook_data(); |
123 | |
124 | </pre> |
195e87cb |
125 | <p>Returns the <code>position</code> (first) parameter that will be passed to <a href="/SDL-Mixer-Music.html#hook_music">SDL::Mixer::Music::hook_music</a>'s callback.</p> |
b5d537cc |
126 | |
127 | </div> |
128 | <h2 id="play_music">play_music</h2> |
129 | <div id="play_music_CONTENT"> |
e37eb258 |
130 | <pre> my $play_music = SDL::Mixer::Music::play_music( $mix_music, $loops ); |
071b4b10 |
131 | |
132 | </pre> |
133 | <p><code>play_music</code> plays a given <code>SDL::Mixer::MixMusic</code>. |
e37eb258 |
134 | Passing -1 to <code>$loops</code> will loop the music infinitely. </p> |
071b4b10 |
135 | <p>Example:</p> |
136 | <pre> my $music = SDL::Mixer::Music::load_MUS( 'music.mp3' ); |
137 | |
138 | unless(SDL::Mixer::Music::play_music($sample_music, -1)) |
139 | { |
140 | print("Something went wrong!\n"); |
141 | } |
142 | |
071b4b10 |
143 | </pre> |
b5d537cc |
144 | |
145 | </div> |
146 | <h2 id="fade_in_music">fade_in_music</h2> |
147 | <div id="fade_in_music_CONTENT"> |
e37eb258 |
148 | <pre> my $music = SDL::Mixer::Music::fade_in_music( $mix_music, $loops, $ms ); |
071b4b10 |
149 | |
150 | </pre> |
195e87cb |
151 | <p>Same as <a href="/SDL-Mixer-Music.html#play_music">SDL::Mixer::Music::play_music</a> but you can specify the fade-in time by <code>$ms</code>.</p> |
b5d537cc |
152 | |
153 | </div> |
154 | <h2 id="fade_out_music">fade_out_music</h2> |
155 | <div id="fade_out_music_CONTENT"> |
e37eb258 |
156 | <pre> my $fading_music = SDL::Mixer::Music::fade_out_music( $ms ); |
157 | |
158 | </pre> |
159 | <p><code>fade_out_music</code> fades out the music with a duration specified in <code>ms</code> in milliseconds.</p> |
160 | <p>Returns the the number of channels that will be faded out.</p> |
b5d537cc |
161 | |
162 | </div> |
163 | <h2 id="fading_music">fading_music</h2> |
164 | <div id="fading_music_CONTENT"> |
e37eb258 |
165 | <pre> my $fading_music = SDL::Mixer::Music::fading_music(); |
071b4b10 |
166 | |
167 | </pre> |
168 | <p>Returns one of the following:</p> |
169 | <ul> |
170 | <li>MIX_NO_FADING </li> |
171 | <li>MIX_FADING_OUT </li> |
172 | <li>MIX_FADING_IN</li> |
173 | </ul> |
174 | |
b5d537cc |
175 | |
176 | </div> |
e37eb258 |
177 | <h2 id="volume_music">volume_music</h2> |
178 | <div id="volume_music_CONTENT"> |
2d13cef7 |
179 | <pre> my $volume_before = SDL::Mixer::Music::volume_music( $new_volume ); |
180 | |
181 | </pre> |
182 | <p><code>volume_music</code> set the volume in <code>$new_volume</code> and returns the volume that was set before. |
183 | Passing <code>-1</code> as argument causes only to return the current volume.</p> |
184 | <p>Volume is between <code>0</code> (silence) and <code>MIX_MAX_VOLUME = 128</code>.</p> |
185 | <p>Example:</p> |
186 | <pre> # set the music volume to 1/2 maximum, and then check it |
187 | printf( "volume was : %d\n", SDL::Mixer::Music::volume_music( MIX_MAX_VOLUME / 2 ) ); |
188 | printf( "volume is now : %d\n", SDL::Mixer::Music::volume_music( -1 ) ); |
189 | |
190 | </pre> |
e37eb258 |
191 | |
192 | </div> |
193 | <h2 id="halt_music">halt_music</h2> |
194 | <div id="halt_music_CONTENT"> |
195 | <pre> SDL::Mixer::Music::halt_music(); |
196 | |
197 | </pre> |
198 | <p>Halts the music.</p> |
199 | |
200 | </div> |
b5d537cc |
201 | <h2 id="pause_music">pause_music</h2> |
202 | <div id="pause_music_CONTENT"> |
071b4b10 |
203 | <pre> SDL::Mixer::Music::pause_music(); |
204 | |
205 | </pre> |
206 | <p>Pauses the music.</p> |
b5d537cc |
207 | |
208 | </div> |
209 | <h2 id="resume_music">resume_music</h2> |
210 | <div id="resume_music_CONTENT"> |
e37eb258 |
211 | <pre> SDL::Mixer::Music::resume_music(); |
071b4b10 |
212 | |
213 | </pre> |
214 | <p>Resumes the music.</p> |
b5d537cc |
215 | |
216 | </div> |
217 | <h2 id="rewind_music">rewind_music</h2> |
218 | <div id="rewind_music_CONTENT"> |
e37eb258 |
219 | <pre> SDL::Mixer::Music::rewind_music(); |
071b4b10 |
220 | |
e37eb258 |
221 | </pre> |
222 | <p>Rewinds the music.</p> |
071b4b10 |
223 | |
e37eb258 |
224 | </div> |
225 | <h2 id="set_music_position">set_music_position</h2> |
226 | <div id="set_music_position_CONTENT"> |
227 | <pre> SDL::Mixer::Music::set_music_position( $position ); |
071b4b10 |
228 | |
229 | </pre> |
e37eb258 |
230 | <p>Set the position of the currently playing music. The position takes different meanings for different music sources. It only works on the |
231 | music sources listed below.</p> |
232 | <dl> |
233 | <dt>MOD</dt> |
234 | <dd> |
235 | <p>The double is cast to Uint16 and used for a pattern number in the module. |
236 | Passing zero is similar to rewinding the song. </p> |
237 | </dd> |
238 | <dt>OGG</dt> |
239 | <dd> |
240 | <p>Jumps to position seconds from the beginning of the song. </p> |
241 | </dd> |
242 | <dt>MP3</dt> |
243 | <dd> |
244 | <p>Jumps to position seconds from the current position in the stream. |
195e87cb |
245 | So you may want to call <a href="/SDL-Mixer-Music.html#rewind_music">SDL::Mixer::Music::rewind_music</a> before this. |
e37eb258 |
246 | Does not go in reverse... negative values do nothing. </p> |
247 | <p>Returns: <code>0</code> on success, or <code>-1</code> if the codec doesn't support this function. </p> |
b5d537cc |
248 | |
249 | </div> |
250 | <h2 id="paused_music">paused_music</h2> |
251 | <div id="paused_music_CONTENT"> |
071b4b10 |
252 | <pre> my $paused = SDL::Mixer::Music::paused_music(); |
253 | |
254 | </pre> |
e37eb258 |
255 | <p>Returns <code>1</code> if the music is paused, otherwise <code>0</code>.</p> |
b5d537cc |
256 | |
257 | </div> |
258 | <h2 id="playing_music">playing_music</h2> |
259 | <div id="playing_music_CONTENT"> |
071b4b10 |
260 | <pre> my $playing_music = SDL::Mixer::Music::playing_music(); |
261 | |
262 | </pre> |
e37eb258 |
263 | <p>Returns <code>1</code> if the music is playing sound, otherwise <code>0</code>. It does'nt check if the music is paused.</p> |
d49f81db |
264 | |
265 | </div> |
2d13cef7 |
266 | <h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p> |
267 | <div id="AUTHOR_CONTENT"> |
268 | <p>Tobias Leich [FROGGS]</p> |
269 | |
270 | </div> |
d49f81db |
271 | </div> |