1This is mikmod.info, produced by makeinfo version 4.13 from mikmod.texi. 2 3Copyright (C) 1998-2014 Miodrag Vallat and others -- see file AUTHORS 4for complete list. 5 6 This library is free software; you can redistribute it and/or modify 7it under the terms of the GNU Library General Public License as 8published by the Free Software Foundation; either version 2 of the 9License, or (at your option) any later version. 10 11 This program is distributed in the hope that it will be useful, but 12WITHOUT ANY WARRANTY; without even the implied warranty of 13MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14Library General Public License for more details. 15 16 You should have received a copy of the GNU Library General Public 17License along with this library; if not, write to the Free Software 18Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, 19USA. 20 21INFO-DIR-SECTION Programming 22START-INFO-DIR-ENTRY 23* MikMod: (mikmod). MikMod Sound Library. 24END-INFO-DIR-ENTRY 25 26 27File: mikmod.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) 28 29MikMod Sound Library 30******************** 31 32This manual documents the MikMod Sound Library, version 3.3.11. 33 34* Menu: 35 36* Introduction:: What is MikMod ? 37* Tutorial:: Your first steps with MikMod. 38* Using the Library:: A thematic presentation of the library. 39* Library Reference:: Detailed description of the functions and variables. 40* Index:: 41 42 43File: mikmod.info, Node: Introduction, Next: Tutorial, Prev: Top, Up: Top 44 451 Introduction 46************** 47 48The MikMod sound library is an excellent way for a programmer to add 49music and sound effects to an application. It is a powerful and 50flexible library, with a simple and easy-to-learn API. 51 52 Besides, the library is very portable and runs under a lot of 53Unices, as well as under OS/2, MacOS and Windows. Third party 54individuals also maintain ports on other systems, including MS-DOS, and 55BeOS. 56 57 MikMod is able to play a wide range of module formats, as well as 58digital sound files. It can take advantage of particular features of 59your system, such as sound redirection over the network. And due to its 60modular nature, the library can be extended to support more sound or 61module formats, as well as new hardware or other sound output 62capabilities, as they appear. 63 64 65File: mikmod.info, Node: Tutorial, Next: Using the Library, Prev: Introduction, Up: Top 66 672 Tutorial 68********** 69 70This chapter will describe how to quickly incorporate MikMod's power 71into your programs. It doesn't cover everything, but that's a start and 72I hope it will help you understand the library philosophy. 73 74 If you have a real tutorial to put here, you're welcome ! Please 75send it to me... 76 77* Menu: 78 79* MikMod Concepts:: A few things you'll need to know. 80* A Skeleton Program:: The shortest MikMod program. 81* Playing Modules:: How to create a simple module player. 82* Playing Sound Effects:: How to play simple sound effects. 83* More Sound Effects:: How to play more complex sound effects. 84 85 86File: mikmod.info, Node: MikMod Concepts, Next: A Skeleton Program, Prev: Tutorial, Up: Tutorial 87 882.1 MikMod Concepts 89=================== 90 91MikMod's sound output is composed of several sound _voices_ which are 92mixed, either in software or in hardware, depending of your hardware 93configuration. Simple sounds, like sound effects, use only one voice, 94whereas sound modules, which are complex arrangements of sound effects, 95use several voices. 96 97 MikMod's functions operate either globally, or at the voice level. 98Differences in the handling of sound effects and modules are kept 99minimal, at least for the programmer. 100 101 The sound playback is done by a _sound driver_. MikMod provides 102several sound drivers: different hardware drivers, and some software 103drivers to redirect sound in a file, or over the network. You can even 104add your own driver, register it to make it known by the library, and 105select it (this is exactly what the module plugin of xmms does). 106 107 108File: mikmod.info, Node: A Skeleton Program, Next: Playing Modules, Prev: MikMod Concepts, Up: Tutorial 109 1102.2 A Skeleton Program 111====================== 112 113To use MikMod in your program, there are a few steps required: 114 115 * Include `mikmod.h' in your program. 116 117 * Register the MikMod drivers you need. 118 119 * Initialize the library with MikMod_Init() before using any other 120 MikMod function. 121 122 * Give up resources with MikMod_Exit() at the end of your program, 123 or before when MikMod is not needed anymore. 124 125 * Link your application with the MikMod sound library. 126 127 Here's a program which meets all those conditions: 128 129 /* MikMod Sound Library example program: a skeleton */ 130 131 #include <mikmod.h> 132 133 main() 134 { 135 /* register all the drivers */ 136 MikMod_RegisterAllDrivers(); 137 138 /* initialize the library */ 139 MikMod_Init(""); 140 141 /* we could play some sound here... */ 142 143 /* give up */ 144 MikMod_Exit(); 145 } 146 147 This program would be compiled with the following command line: `cc 148-o example example.c `libmikmod-config --cflags` `libmikmod-config 149--libs`' 150 151 Although this programs produces no useful result, many things happen 152when you run it. The call to `MikMod_RegisterAllDrivers' registers all 153the drivers embedded in the MikMod library. Then, `MikMod_Init' chooses 154the more adequate driver and initializes it. The program is now ready 155to produce sound. When sound is not needed any more, `MikMod_Exit' is 156used to relinquish memory and let other programs have access to the 157sound hardware. 158 159 160File: mikmod.info, Node: Playing Modules, Next: Playing Sound Effects, Prev: A Skeleton Program, Up: Tutorial 161 1622.3 Playing Modules 163=================== 164 165Our program is not really useful if it doesn't produce sound. Let's 166suppose you've got this good old module, "Beyond music", in the file 167`beyond music.mod'. How about playing it ? 168 169 To do this, we'll use the following code: 170 171 /* MikMod Sound Library example program: a simple module player */ 172 173 #include <unistd.h> 174 #include <mikmod.h> 175 176 main() 177 { 178 MODULE *module; 179 180 /* register all the drivers */ 181 MikMod_RegisterAllDrivers(); 182 183 /* register all the module loaders */ 184 MikMod_RegisterAllLoaders(); 185 186 /* initialize the library */ 187 md_mode |= DMODE_SOFT_MUSIC; 188 if (MikMod_Init("")) { 189 fprintf(stderr, "Could not initialize sound, reason: %s\n", 190 MikMod_strerror(MikMod_errno)); 191 return; 192 } 193 194 /* load module */ 195 module = Player_Load("beyond music.mod", 64, 0); 196 if (module) { 197 /* start module */ 198 Player_Start(module); 199 200 while (Player_Active()) { 201 /* we're playing */ 202 usleep(10000); 203 MikMod_Update(); 204 } 205 206 Player_Stop(); 207 Player_Free(module); 208 } else 209 fprintf(stderr, "Could not load module, reason: %s\n", 210 MikMod_strerror(MikMod_errno)); 211 212 /* give up */ 213 MikMod_Exit(); 214 } 215 216 What's new here ? First, we've not only registered MikMod's device 217driver, but also the module loaders. MikMod comes with a large choice 218of module loaders, each one for a different module type. Since _every_ 219loader is called to determine the type of the module when we try to 220load them, you may want to register only a few of them to save time. In 221our case, we don't matter, so we happily register every module loader. 222 223 Then, there's an extra line before calling `MikMod_Init'. We change 224the value of MikMod's variable `md_mode' to tell the library that we 225want the module to be processed by the software. If you're the happy 226owner of a GUS-type card, you could use the specific hardware driver 227for this card, but in this case you should not set the 228`DMODE_SOFT_MUSIC' flag. 229 230 We'll ensure that `MikMod_Init' was successful. Note that, in case of 231error, MikMod provides the variable `MikMod_errno', an equivalent of 232the C library `errno' for MikMod errors, and the function 233`MikMod_strerror', an equivalent to `strerror'. 234 235 Now onto serious business ! The module is loaded with the 236`Player_Load' function, which takes the name of the module file, and 237the number of voices afforded to the module. In this case, the module 238has only 4 channels, so 4 voices, but complex Impulse Tracker modules 239can have a lot of voices (as they can have as many as 256 virtual 240channels with so-called "new note actions"). Since empty voices don't 241cost time to be processed, it is safe to use a big value, such as 64 or 242128. The third parameter is the "curiosity" of the loader: if nonzero, 243the loader will search for hidden parts in the module. However, only a 244few module formats can embed hidden or non played parts, so we'll use 0 245here. 246 247 Now that the module is ready to play, let's play it. We inform the 248player that the current module is `module' with `Player_Start'. 249Playback starts, but we have to update it on a regular basis. So 250there's a loop on the result of the `Player_Active' function, which 251will tell us if the module has finished. To update the sound, we simply 252call `MikMod_Update'. 253 254 After the module has finished, we tell the player its job is done 255with `Player_Stop', and we free the module with `Player_Free'. 256 257 258File: mikmod.info, Node: Playing Sound Effects, Next: More Sound Effects, Prev: Playing Modules, Up: Tutorial 259 2602.4 Playing Sound Effects 261========================= 262 263MikMod is not limited to playing modules, it can also play sound 264effects, that is, module samples. It's a bit more complex than playing 265a module, because the module player does a lot of things for us, but 266here we'll get more control over what is actually played by the 267program. Let's look at an example: 268 269 /* MikMod Sound Library example program: sound effects */ 270 271 #include <unistd.h> 272 #include <mikmod.h> 273 274 main() 275 { 276 int i; 277 /* sound effects */ 278 SAMPLE *sfx1, *sfx2; 279 /* voices */ 280 int v1, v2; 281 282 /* register all the drivers */ 283 MikMod_RegisterAllDrivers(); 284 285 /* initialize the library */ 286 md_mode |= DMODE_SOFT_SNDFX; 287 if (MikMod_Init("")) { 288 fprintf(stderr, "Could not initialize sound, reason: %s\n", 289 MikMod_strerror(MikMod_errno)); 290 return; 291 } 292 293 /* load samples */ 294 sfx1 = Sample_Load("first.wav"); 295 if (!sfx1) { 296 MikMod_Exit(); 297 fprintf(stderr, "Could not load the first sound, reason: %s\n", 298 MikMod_strerror(MikMod_errno)); 299 return; 300 } 301 sfx2 = Sample_Load("second.wav"); 302 if (!sfx2) { 303 Sample_Free(sfx1); 304 MikMod_Exit(); 305 fprintf(stderr, "Could not load the second sound, reason: %s\n", 306 MikMod_strerror(MikMod_errno)); 307 return; 308 } 309 310 /* reserve 2 voices for sound effects */ 311 MikMod_SetNumVoices(-1, 2); 312 313 /* get ready to play */ 314 MikMod_EnableOutput(); 315 316 /* play first sample */ 317 v1 = Sample_Play(sfx1, 0, 0); 318 for(i = 0; i < 5; i++) { 319 MikMod_Update(); 320 usleep(100000); 321 } 322 323 /* half a second later, play second sample */ 324 v2 = Sample_Play(sfx2, 0, 0); 325 do { 326 MikMod_Update(); 327 usleep(100000); 328 } while (!Voice_Stopped(v2)); 329 330 MikMod_DisableOutput(); 331 332 Sample_Free(sfx2); 333 Sample_Free(sfx1); 334 335 MikMod_Exit(); 336 } 337 338 As in the previous example, we begin by registering the sound 339drivers and initializing the library. We also ask for software mixing 340by modifying the variable `md_mode'. 341 342 It's time to load our files, with the `Sample_Load' function. Don't 343forget to test the return value -- it looks ugly here on such a small 344example, but it's a good practice... 345 346 Since we want to play two samples, we have to use at least two 347voices for this, so we reserve them with a `MikMod_SetNumVoices' call. 348The first parameter sets the number of module voices, and the second 349parameter the number of sound effect voices. We don't want to set the 350number of module voices here (it's part of the module player's duty), 351so we use the value `-1' to keep the current value, and we reserve two 352sound effect voices. 353 354 Now we're ready to play, so we call `MikMod_EnableOutput' to make the 355driver ready. Sound effects are played by the `Sample_Play' function. 356You just have to specify which sample you want to play, the offset from 357which you want to start, and the playback flags. More on this later. 358The function returns the number of the voice associated to the sample. 359 360 We play the first sample for half a second, then we start to play 361the second sample. Since we've reserved two channels, both samples play 362simultaneously. We use the `Voice_Stopped' function to stop the 363playback: it returns the current status of the voice argument, which is 364zero when the sample plays and nonzero when it has finished. So the 365`do' loop will stop exactly when the second sample is finished, 366regardless of the length of the first sample. 367 368 To finish, we get rid of the samples with `Sample_Free'. 369 370 371File: mikmod.info, Node: More Sound Effects, Prev: Playing Sound Effects, Up: Tutorial 372 3732.5 More Sound Effects 374====================== 375 376Sound effects have some attributes that can be affected to control the 377playback. These are speed, panning, and volume. Given a voice number, 378you can affect these attributes with the `Voice_SetFrequency', 379`Voice_SetPanning' and `Voice_SetVolume' functions. 380 381 In the previous example, we'll replace the actual sound code, 382located between the calls to `MikMod_EnableOutput' and 383`MikMod_DisableOutput', with the following code: 384 385 Sample_Play(sfx1, 0, 0); 386 for(i = 0; i < 5; i++) { 387 MikMod_Update(); 388 usleep(100000); 389 } 390 v2 = Sample_Play(sfx2, 0, SFX_CRITICAL); 391 i = 0; 392 do { 393 MikMod_Update(); 394 usleep(100000); 395 v1 = Sample_Play(sfx1, 0, 0); 396 Voice_SetVolume(v1, 160); 397 Voice_SetFrequency(v1, (sfx1->speed * (100 + i)) / 100); 398 Voice_SetPanning(v2, (i++ & 1) ? PAN_LEFT : PAN_RIGHT); 399 } while (!Voice_Stopped(v2)); 400 401 The first thing you'll notice, is the `SFX_CRITICAL' flag used to 402play the second sample. Since the `do' loop will add another sample 403every 100 milliseconds, and we reserved only two voices, the oldest 404voice will be cut each time this is necessary. Doing this would cut the 405second sample in the second iteration of the loop. However, since we 406flagged this sound as "critical", it won't be cut until it is finished 407or we stop it with a `Voice_Stop' call. So the second sample will play 408fine, whereas the first sample will be stopped every loop iteration. 409 410 Then, we choose to play the first sample a bit lower, with 411`Voice_SetVolume'. Volume voices range from 0 (silence) to 256. In this 412case we play the sample at 160. To make the sound look weird, we also 413change its frequency with `Voice_SetFrequency'. The computation in the 414example code makes the frequency more and more high (starting from the 415sample frequency and then increasing from 1% each iteration). 416 417 And to demonstrate the `Voice_SetPanning' function, we change the 418panning of the second sample at each iteration from the left to the 419right. The argument can be one of the standard panning `PAN_LEFT', 420`PAN_RIGHT', `PAN_CENTER' and `PAN_SURROUND'(1), or a numeric value 421between 0 (`PAN_LEFT') and 255 (`PAN_RIGHT'). 422 423 ---------- Footnotes ---------- 424 425 (1) `PAN_SURROUND' will be mapped to `PAN_CENTER' if the library is 426initialized without surround sound, that is, if the variable `md_mode' 427doesn't have the bit `DMODE_SURROUND' set. 428 429 430File: mikmod.info, Node: Using the Library, Next: Library Reference, Prev: Tutorial, Up: Top 431 4323 Using the Library 433******************* 434 435This chapter describes the various parts of the library and their uses. 436 437* Menu: 438 439* Library Version:: 440* Type Definitions:: 441* Error Handling:: 442* Library Initialization:: 443* Samples and Voice Control:: 444* Modules and Player Control:: 445* Loading Data from Memory:: 446 447 448File: mikmod.info, Node: Library Version, Next: Type Definitions, Prev: Using the Library, Up: Using the Library 449 4503.1 Library Version 451=================== 452 453If your program is dynamically linked with the MikMod library, you 454should check which version of the library you're working with. To do 455this, the library defines a few constants and a function to help you 456determine if the current library is adequate for your needs or if it 457has to be upgraded. 458 459 When your program includes `mikmod.h', the following constants are 460defined: 461 * `LIBMIKMOD_VERSION_MAJOR' is equal to the major version number of 462 the library. 463 464 * `LIBMIKMOD_VERSION_MINOR' is equal to the minor version number of 465 the library. 466 467 * `LIBMIKMOD_REVISION' is equal to the revision number of the 468 library. 469 470 * `LIBMIKMOD_VERSION' is the sum of `LIBMIKMOD_VERSION_MAJOR' 471 shifted 16 times, `LIBMIKMOD_VERSION_MINOR' shifted 8 times, and 472 `LIBMIKMOD_REVISION'. 473 474 So your program can tell with which version of the library it has 475been compiled this way: 476 printf("Compiled with MikMod Sound Library version %ld.%ld.%ld\n", 477 LIBMIKMOD_VERSION_MAJOR, 478 LIBMIKMOD_VERSION_MINOR, 479 LIBMIKMOD_REVISION); 480 481 The library defines the function `MikMod_GetVersion' which returns 482the value of LIBMIKMOD_VERSION for the library. If this value is 483greater than or equal to the value of LIBMIKMOD_VERSION for your 484program, your program will work; otherwise, you'll have to inform the 485user that he has to upgrade the library: 486 487 { 488 long engineversion = MikMod_GetVersion(); 489 490 if (engineversion < LIBMIKMOD_VERSION) { 491 printf("MikMod library version (%ld.%ld.%ld) is too old.\n", 492 (engineversion >> 16) & 255, 493 (engineversion >> 8) & 255, 494 (engineversion) & 255); 495 printf("This programs requires at least version %ld.%ld.%ld\n", 496 LIBMIKMOD_VERSION_MAJOR, 497 LIBMIKMOD_VERSION_MINOR, 498 LIBMIKMOD_REVISION); 499 puts("Please upgrade your MikMod library."); 500 exit(1); 501 } 502 } 503 504 505File: mikmod.info, Node: Type Definitions, Next: Error Handling, Prev: Library Version, Up: Using the Library 506 5073.2 Type Definitions 508==================== 509 510MikMod defines several data types to deal with modules and sample data. 511These types have the same memory size on every platform MikMod has been 512ported to. 513 514 These types are: 515 * `CHAR' is a printable character. For now it is the same as the 516 `char' type, but in the future it may be wide char (Unicode) on 517 some platforms. 518 519 * `SBYTE' is a signed 8 bit number (can range from -128 to 127). 520 521 * `UBYTE' is an unsigned 8 bit number (can range from 0 to 255). 522 523 * `SWORD' is a signed 16 bit number (can range from -32768 to 32767). 524 525 * `UWORD' is an unsigned 16 bit number (can range from 0 to 65535). 526 527 * `SLONG' is a signed 32 bit number (can range from -2.147.483.648 to 528 2.147.483.647). 529 530 * `ULONG' is an unsigned 32 bit number (can range from 0 to 531 4.294.967.296). 532 533 * `BOOL' is a boolean value. A value of 0 means false, any other 534 value means true. 535 536 537File: mikmod.info, Node: Error Handling, Next: Library Initialization, Prev: Type Definitions, Up: Using the Library 538 5393.3 Error Handling 540================== 541 542Although MikMod does its best to do its work, there are times where it 543can't. For example, if you're trying to play a corrupted file, well, 544it can't. 545 546 A lot of MikMod functions return pointers or `BOOL' values. If the 547pointer is `NULL' or the `BOOL' is 0 (false), an error has occurred. 548 549 MikMod errors are returned in the variable `MikMod_errno'. Each 550possible error has a symbolic error code, beginning with `MMERR_'. For 551example, if MikMod can't open a file, `MikMod_errno' will receive the 552value `MMERR_OPENING_FILE'. 553 554 You can get an appropriate error message to display from the function 555`MikMod_strerror'. 556 557 There is a second error variable named `MikMod_critical'. As its name 558suggests, it is only set if the error lets the library in an unstable 559state. This variable can only be set by the functions `MikMod_Init', 560`MikMod_SetNumVoices' and `MikMod_EnableOutput'. If one of these 561functions return an error and `MikMod_critical' is set, the library is 562left in the uninitialized state (i.e. it was not initialized, or 563`MikMod_Exit' was called). 564 565 If you prefer, you can use a callback function to get notified of 566errors. This function must be prototyped as `void MyFunction(void)'. 567Then, call `MikMod_RegisterHandler' with your function as argument to 568have it notified when an error occurs. There can only be one callback 569function registered, but `MikMod_RegisterHandler' will return you the 570previous handler, so you can chain handlers if you want to. 571 572 573File: mikmod.info, Node: Library Initialization, Next: Samples and Voice Control, Prev: Error Handling, Up: Using the Library 574 5753.4 Library Initialization and Core Functions 576============================================= 577 578To initialize the library, you must register some sound drivers first. 579You can either register all the drivers embedded in the library for 580your platform with `MikMod_RegisterAllDrivers', or register only some 581of them with `MikMod_RegisterDriver'. If you choose to register the 582drivers manually, you must be careful in their order, since 583`MikMod_Init' will try them in the order you registered them. The 584`MikMod_RegisterAllDrivers' function registers the network drivers 585first (for playing sound over the network), then the hardware drivers, 586then the disk writers, and in last resort, the nosound driver. 587Registering the nosound driver first would not be a very good idea... 588 589 You can get some printable information regarding the registered 590drivers with `MikMod_InfoDriver'; don't forget to call `MikMod_free' on 591the returned string when you don't need it anymore. 592 593 After you've registered your drivers, you can initialize the sound 594playback with `MikMod_Init', passing specific information to the driver 595if necessary. If you set the variable `md_device' to zero, which is its 596default value, the driver will be autodetected, that is, the first 597driver in the list that is available on the system will be used; 598otherwise only the driver whose order in the list of the registered 599drivers is equal to `md_device' will be tried. If your playback 600settings, in the variables `md_mixfreq' and `md_mode', are not 601supported by the device, `MikMod_Init' will fail. 602 603 You can then choose the number of voices you need with 604`MikMod_SetNumVoices', and activate the playback with 605`MikMod_EnableOutput'. 606 607 Don't forget to call `MikMod_Update' as often as possible to process 608the sound mixing. If necessary, fork a dedicated process to do this, or 609if the library is thread-safe on your system, use a dedicated thread. 610 611 If you want to change playback settings, most of them can't be 612changed on the fly. You'll need to stop the playback and reinitialize 613the driver. Use `MikMod_Active' to check if there is still sound 614playing; in this case, call `MikMod_DisableOutput' to end playback. 615Then, change your settings and call `MikMod_Reset'. You're now ready to 616select your number of voices and restart playback. 617 618 When your program ends, don't forget to stop playback and call 619`MikMod_Exit' to leave the sound hardware in a coherent state. 620 621 On systems that have pthreads, libmikmod is thread-safe(1). You can 622check this in your programs with the `MikMod_InitThreads' function. If 623this function returns 1, the library is thread-safe. 624 625 The main benefit of thread-safety is that `MikMod_Update' can be 626called from a separate thread, which often makes application design 627easier. However, several libmikmod global variables are accessible from 628all your threads, so when more than one thread need to access libmikmod 629variables, you'll have to protect these access with the `MikMod_Lock' 630and `MikMod_Unlock' functions. If libmikmod is not thread-safe, these 631functions are no-ops. 632 633 ---------- Footnotes ---------- 634 635 (1) Unless you explicitely choose to create a non thread-safe 636version of libmikmod at compile-time. 637 638 639File: mikmod.info, Node: Samples and Voice Control, Next: Modules and Player Control, Prev: Library Initialization, Up: Using the Library 640 6413.5 Samples and Voice Control 642============================= 643 644Currently, MikMod only supports uncompressed mono WAV files as samples. 645You can load a sample by calling `Sample_Load' with a filename, or by 646calling `Sample_LoadFP' with an open `FILE*' pointer. These functions 647return a pointer to a `SAMPLE' structure, or `NULL' in case of error. 648 649 The `SAMPLE' structure has a few interesting fields: 650 - `speed' contains the default frequency of the sample. 651 652 - `volume' contains the default volume of the sample, ranging from 0 653 (silence) to 64. 654 655 - `panning' contains the default panning position of the sample. 656 657 Altering one of those fields will affect all voices currently 658playing the sample. You can achieve the same result on a single voice 659with the functions `Voice_SetFrequency', `Voice_SetVolume' and 660`Voice_SetPanning'. Since the same sample can be played with different 661frequency, volume and panning parameters on each voice, you can get 662voice specific information with `Voice_GetFrequency', `Voice_GetVolume' 663and `Voice_GetPanning'. 664 665 You can also make your sample loop by setting the fields `loopstart' 666and `loopend' and or'ing `flags' with `SF_LOOP'. To compute your loop 667values, the field `length' will be useful. However, you must know that 668all the sample length are expressed in samples, i.e. 8 bits for an 8 669bit sample, and 16 bit for a 16 bit sample... Test `flags' for the value 670`SF_16BITS' to know this. 671 672 Speaking of flags, if you're curious and want to know the original 673format of the sample on disk (since libmikmod does some work on the 674sample data internally), refer to the `inflags' field. 675 676 If the common forward loop isn't enough, you can play with some 677other flags: `SF_BIDI' will make your sample loop "ping pong" (back and 678forth), and `SF_REVERSE' will make it play backwards. 679 680 To play your sample, use the `Sample_Play' function. This function 681will return a voice number which enable you to use the `Voice_xx' 682functions. 683 684 The sample will play until another sample takes over its voice (when 685you play more samples than you reserved sound effect voices), unless it 686has been flagged as `SFX_CRITICAL'. You can force it to stop with 687`Voice_Stop', or you can force another sample to take over this voice 688with `Voice_Play'; however `Voice_Play' doesn't let you flag the new 689sample as critical. 690 691 Non looping samples will free their voice channel as soon as they 692are finished; you can know the current playback position of your sample 693with `Voice_GetPosition'. If it is zero, either the sample has finished 694playing or it is just beginning; use `Voice_Stopped' to know. 695 696 When you don't need a sample anymore, don't forget to free its 697memory with `Sample_Free'. 698 699 700File: mikmod.info, Node: Modules and Player Control, Next: Loading Data from Memory, Prev: Samples and Voice Control, Up: Using the Library 701 7023.6 Modules and Player Control 703============================== 704 705As for the sound drivers, you have to register the module loaders you 706want to use for MikMod to be able to load modules. You can either 707register all the module loaders with `MikMod_RegisterAllLoaders', or 708only a few of them with `MikMod_RegisterLoader'. Be careful if you 709choose this solution, as the 15 instrument MOD loader has to be 710registered last, since loaders are called in the order they were 711register to identify modules, and the detection of this format is not 712fully reliable, so other modules might be mistaken as 15 instrument MOD 713files. 714 715 You can get some printable information regarding the registered 716loaders with `MikMod_InfoLoader'; don't forget to call `MikMod_free' on 717the returned string when you don't need it anymore. 718 719 Note that, contrary to the sound drivers, you can register module 720loaders at any time, it doesn't matter. 721 722 For playlists, you might be interested in knowing the module title 723first, and `Player_LoadTitle' will give you this information. Don't 724forget to call `MikMod_free' on the returned text when you don't need 725it anymore. 726 727 You can load a module either with `Player_Load' and the name of the 728module, or with `Player_LoadFP' and an open `FILE*' pointer. These 729functions also expect a maximal number of voices, and a curiosity flag. 730Unless you have excellent reasons not to do so, choose a big limit, 731such as 64 or even 128 for complex Impulse Tracker modules. Both 732functions return a pointer to an `MODULE' structure, or `NULL' if an 733error occurs. 734 735 You'll find some useful information in this structure: 736 - `numchn' contains the number of module "real" channels. 737 738 - `numvoices' contains the number of voices reserved by the player 739 for the real channels and the virtual channels (NNA). 740 741 - `numpas' and `numpat' contain the number of song positions and 742 song patterns. 743 744 - `numins' and `numsmp' contain the number of instruments and 745 samples. 746 747 - `songname' contains the song title. 748 749 - `modtype' contains the name of the tracker used to create the song. 750 751 - `comment' contains the song comment, if it has one. 752 753 - `sngtime' contains the time elapsed in the module, in 2^-10 754 seconds (not exactly a millisecond). 755 756 - `sngspd' and `bpm' contain the song speed and tempo. 757 758 - `realchn' contains the actual number of active channels. 759 760 - `totalchn' contains the actual number of active virtual channels, 761 i.e. the sum of `realchn' and the number of NNA virtual channels. 762 763 Now that the module is loaded, you need to tell the module player 764that you want to play this particular module with `Player_Start' (the 765player can only play one module, but you can have several modules in 766memory). The playback begins. Should you forget which module is 767playing, `Player_GetModule' will return it to you. 768 769 You can change the current song position with the functions 770`Player_NextPosition', `Player_PrevPosition' and `Player_SetPosition', 771the speed with `Player_SetSpeed' and `Player_SetTempo', and the volume 772(ranging from 0 to 128) with `Player_SetVolume'. 773 774 Playback can be paused or resumed with `Player_TogglePause'. Be sure 775to check with `Player_Paused' that it isn't already in the state you 776want ! 777 778 Fine player control is achieved by the functions `Player_Mute', 779`Player_UnMute' and `Player_ToggleMute' which can silence or resume a 780set of module channels. The function `Player_Muted' will return the 781state of a given channel. And if you want even more control, you can 782get the voice corresponding to a module channel with 783`Player_GetChannelVoice' and act directly on the voice. 784 785 Modules play only once, but can loop indefinitely if they are 786designed to do so. You can change this behavior with the `wrap' and 787`loop' of the `MODULE' structure; the first one, if set, will make the 788module restart when it's finished, and the second one, if set, will 789prevent the module from jumping backwards. 790 791 You can test if the module is still playing with `Player_Active', 792and you can stop it at any time with `Player_Stop'. When the module 793isn't needed anymore, get rid of it with `Player_Free'. 794 795 796File: mikmod.info, Node: Loading Data from Memory, Prev: Modules and Player Control, Up: Using the Library 797 7983.7 Loading Data from Memory 799============================ 800 801If you need to load modules or sound effects from other places than 802plain files, you can use the `MREADER' and `MWRITER' objects to achieve 803this. 804 805 The `MREADER' and `MWRITER' structures contain a list of function 806pointers, which emulate the behaviour of a regular `FILE *' object. In 807fact, all functions which take filenames or `FILE *' as arguments are 808only wrappers to a real function which takes an `MREADER' or an 809`MWRITER' argument. 810 811 So, if you need to load a module from memory, or for a multi-file 812archive, for example, all you need is to build an adequate `MREADER' 813object, and use `Player_LoadGeneric' instead of `Player_Load' or 814`Player_LoadFP'. For samples, use `Sample_LoadGeneric' instead of 815`Sample_Load' or `Sample_LoadFP'. 816 817 818File: mikmod.info, Node: Library Reference, Next: Index, Prev: Using the Library, Up: Top 819 8204 Library Reference 821******************* 822 823This chapter describes in more detail all the functions and variables 824provided by the library. *Note Type Definitions::, for the basic type 825reference. 826 827* Menu: 828 829* Variable Reference:: 830* Structure Reference:: 831* Error Reference:: 832* Function Reference:: 833* Loader Reference:: 834* Driver Reference:: 835 836 837File: mikmod.info, Node: Variable Reference, Next: Structure Reference, Prev: Library Reference, Up: Library Reference 838 8394.1 Variable Reference 840====================== 841 8424.1.1 Error Variables 843--------------------- 844 845The following variables are set by the library to return error 846information. 847 848`int MikMod_errno' 849 When an error occurs, this variable contains the error code. 850 *Note Error Reference::, for more information. 851 852`BOOL MikMod_critical' 853 When an error occurs, this variable informs of the severity of the 854 error. Its value has sense only if the value of `MikMod_errno' is 855 different from zero. If the value of `MikMod_critical' is zero, 856 the error wasn't fatal and the library is in a stable state. 857 However, if it is nonzero, then the library can't be used and has 858 reseted itself to the uninitialized state. This often means that 859 the mixing parameters you choose were not supported by the driver, 860 or that it doesn't has enough voices for your needs if you called 861 `MikMod_SetNumVoices'. 862 8634.1.2 Sound Settings 864-------------------- 865 866The following variables control the sound output parameters and their 867changes take effect immediately. 868 869`UBYTE md_musicvolume' 870 Volume of the module. Allowed values range from 0 to 128. The 871 default value is 128. 872 873`UBYTE md_pansep' 874 Stereo channels separation. Allowed values range from 0 (no 875 separation, thus mono sound) to 128 (full channel separation). The 876 default value is 128. 877 878`UBYTE md_reverb' 879 Amount of sound reverberation. Allowed values range from 0 (no 880 reverberation) to 15 (a rough estimate for chaos...). The default 881 value is 0. 882 883`UBYTE md_sndfxvolume' 884 Volume of the sound effects. Allowed values range from 0 to 128. 885 The default value is 128. 886 887`UBYTE md_volume' 888 Overall sound volume. Allowed values range from 0 to 128. The 889 default value is 128. 890 8914.1.3 Driver Settings 892--------------------- 893 894The following variables control more in-depth sound output parameters. 895Except for some `md_mode' flags, their changes do not have any effect 896until you call `MikMod_Init' or `MikMod_Reset'. 897 898`UWORD md_device' 899 This variable contains the order, in the list of the registered 900 drivers, of the sound driver which will be used for sound 901 playback. This order is one-based; if this variable is set to 902 zero, the driver is autodetected, which means the list is tested 903 until a driver is present on the system. The default value is 0, 904 thus driver is autodetected. 905 906`MDRIVER* md_driver' 907 This variable points to the driver which is being used for sound 908 playback, and is undefined when the library is uninitialized 909 (before `MikMod_Init' and after `MikMod_Exit'). This variable is 910 for information only, you should never attempt to change its 911 value. Use `md_driver' and `MikMod_Init' (or `MikMod_Reset') 912 instead. 913 914`UWORD md_mixfreq' 915 Sound playback frequency, in hertz. High values yield high sound 916 quality, but need more computing power than lower values. The 917 default value is 44100 Hz, which is compact disc quality. Other 918 common values are 22100 Hz (radio quality), 11025 Hz (phone 919 quality), and 8000 Hz (mu-law quality). 920 921`UWORD md_mode' 922 This variable is a combination of several flags, to select which 923 output mode to select. The following flags have a direct action 924 to the sound output (i.e. changes take effect immediately): 925 `DMODE_INTERP' 926 This flag, if set, enables the interpolated mixers. 927 Interpolated mixing gives better sound but takes a bit more 928 time than standard mixing. If the library is built with the 929 high quality mixer, interpolated mixing is always enabled, 930 regardless of this flag. 931 932 `DMODE_REVERSE' 933 This flag, if set, exchanges the left and right stereo 934 channels. 935 936 `DMODE_SURROUND' 937 This flag, if set, enables the surround mixers. Since 938 surround mixing works only for stereo sound, this flag has no 939 effect if the sound playback is in mono. 940 941 The following flags aren't taken in account until the sound driver 942 is changed or reset: 943 `DMODE_16BIT' 944 This flag, if set, selects 16 bit sound mode. This mode 945 yields better sound quality, but needs twice more mixing time. 946 947 `DMODE_HQMIXER' 948 This flag, if set, selects the high-quality software mixer. 949 This mode yields better sound quality, but needs more mixing 950 time. Of course, this flag has no effect if no 951 `DMODE_SOFT_xx' flag is set. 952 953 `DMODE_SOFT_MUSIC' 954 This flag, if set, selects software mixing of the module. 955 956 `DMODE_SOFT_SNDFX' 957 This flag, if set, selects software mixing of the sound 958 effects. 959 960 `DMODE_STEREO' 961 This flag, if set, selects stereo sound. 962 963 The default value of this variable is `DMODE_STEREO | 964 DMODE_SURROUND | DMODE_16BITS | DMODE_SOFT_MUSIC | 965 DMODE_SOFT_SNDFX'. 966 967 968File: mikmod.info, Node: Structure Reference, Next: Error Reference, Prev: Variable Reference, Up: Library Reference 969 9704.2 Structure Reference 971======================= 972 973Only the useful fields are described here; if a structure field is not 974described, you must assume that it's an internal field which must not be 975modified. 976 9774.2.1 Drivers 978------------- 979 980The `MDRIVER' structure is not meant to be used by anything else than 981the core of the library, but its first four fields contain useful 982information for your programs: 983`const CHAR* Name' 984 Name of the driver, usually never more than 20 characters. 985 986`const CHAR* Description' 987 Description of the driver, usually never more than 50 characters. 988 989`UBYTE HardVoiceLimit' 990 Maximum number of hardware voices for this driver, 0 if the driver 991 has no hardware mixing support. 992 993`UBYTE SoftVoiceLimit' 994 Maximum number of software voices for this driver, 0 if the driver 995 has no software mixing support. 996 997`const CHAR* Alias' 998 A short name for the driver, without spaces, usually never more 999 than 10 characters. 1000 10014.2.2 Modules 1002------------- 1003 1004The `MODULE' structure gathers all the necessary information needed to 1005play a module file, regardless of its initial format. 1006 10074.2.2.1 General Module Information 1008.................................. 1009 1010The fields described in this section contain general information about 1011the module and should not be modified. 1012 1013`CHAR* songname' 1014 Name of the module. 1015 1016`CHAR* modtype' 1017 Type of the module (which tracker format). 1018 1019`CHAR* comment' 1020 Either the module comments, or NULL if the module doesn't have 1021 comments. 1022 1023`UWORD flags' 1024 Several module flags or'ed together. 1025 `UF_ARPMEM' 1026 If set, arpeggio effects have memory. 1027 1028 `UF_BGSLIDES' 1029 If set, volume slide effects continue until a new note or a 1030 new effect is played. 1031 1032 `UF_HIGHBPM' 1033 If set, the module is allowed to have its tempo value (bpm) 1034 over 255. 1035 1036 `UF_INST' 1037 If set, the module has instruments and samples; otherwise, the 1038 module has only samples. 1039 1040 `UF_LINEAR' 1041 If set, slide periods are linear; otherwise, they are 1042 logarithmic. 1043 1044 `UF_NNA' 1045 If set, module uses new note actions (NNA) and the 1046 `numvoices' field is valid. 1047 1048 `UF_NOWRAP' 1049 If set, pattern break on the last pattern does not continue 1050 to the first pattern. 1051 1052 `UF_S3MSLIDES' 1053 If set, module uses old-S3M style volume slides (slides 1054 processed every tick); otherwise, it uses the standard style 1055 (slides processed every tick except the first). 1056 1057 `UF_XMPERIODS' 1058 If set, module uses XM-type periods; otherwise, it uses Amiga 1059 periods. 1060 1061 `UF_FT2QUIRKS' 1062 If set, module player will reproduce some FastTracker 2 1063 quirks during playback. 1064 1065 `UF_PANNING' 1066 If set, module use panning commands. 1067 1068`UBYTE numchn' 1069 The number of channels in the module. 1070 1071`UBYTE numvoices' 1072 If the module uses NNA, and this variable is not zero, it contains 1073 the limit of module voices; otherwise, the limit is set to the 1074 `maxchan' parameter of the `Player_Loadxx' functions. 1075 1076`UWORD numpos' 1077 The number of sound positions in the module. 1078 1079`UWORD numpat' 1080 The number of patterns. 1081 1082`UWORD numins' 1083 The number of instruments. 1084 1085`UWORD numsmp' 1086 The number of samples. 1087 1088`INSTRUMENT* instruments' 1089 Points to an array of instrument structures. 1090 1091`SAMPLE* samples' 1092 Points to an array of sample structures. 1093 1094`UBYTE realchn' 1095 During playback, this variable contains the number of active 1096 channels (not counting NNA channels). 1097 1098`UBYTE totalchn' 1099 During playback, this variable contains the total number of 1100 channels (including NNA channels). 1101 1102`ULONG sngtime' 1103 Elapsed song time, in 2^-10 seconds units (not exactly a 1104 millisecond). To convert this value to seconds, divide by 1024, 1105 not 1000 ! 1106 11074.2.2.2 Playback Settings 1108......................... 1109 1110The fields described here control the module playback and can be 1111modified at any time, unless otherwise specified. 1112 1113`UBYTE initspeed' 1114 The initial speed of the module (Protracker compatible). Valid 1115 range is 1-32. 1116 1117`UBYTE inittempo' 1118 The initial tempo of the module (Protracker compatible). Valid 1119 range is 32-255. 1120 1121`UBYTE initvolume' 1122 The initial overall volume of the module. Valid range is 0-128. 1123 1124`UWORD panning[]' 1125 The current channel panning positions. Only the first `numchn' 1126 values are defined. 1127 1128`UBYTE chanvol[]' 1129 The current channel volumes. Only the first `numchn' values are 1130 defined. 1131 1132`UWORD bpm' 1133 The current tempo of the module. Use `Player_SetTempo' to change 1134 its value. 1135 1136`UBYTE sngspd' 1137 The current speed of the module. Use `Player_SetSpeed' to change 1138 its value. 1139 1140`UBYTE volume' 1141 The current overall volume of the module, in range 0-128. Use 1142 `Player_SetVolume' to change its value. 1143 1144`BOOL extspd' 1145 If zero, Protracker extended speed effect (in-module tempo 1146 modification) is not processed. The default value is 1, which 1147 causes this effect to be processed. However, some old modules 1148 might not play correctly if this effect is not neutralized. 1149 1150`BOOL panflag' 1151 If zero, panning effects are not processed. The default value is 1152 1, which cause all panning effects to be processed. However, some 1153 old modules might not play correctly if panning is not neutralized. 1154 1155`BOOL wrap' 1156 If nonzero, module wraps to its restart position when it is 1157 finished, to play continuously. Default value is zero (play only 1158 once). 1159 1160`UBYTE reppos' 1161 The restart position of the module, when it wraps. 1162 1163`BOOL loop' 1164 If nonzero, all in-module loops are processed; otherwise, backward 1165 loops which decrease the current position are not processed (i.e. 1166 only forward loops, and backward loops in the same pattern, are 1167 processed). This ensures that the module never loops endlessly. 1168 The default value is 1 (all loops are processed). 1169 1170`BOOL fadeout' 1171 If nonzero, volume fades out during when last position of the 1172 module is being played. Default value us zero (no fadeout). 1173 1174`UWORD patpos' 1175 Current position (row) in the pattern being played. Must not be 1176 changed. 1177 1178`SWORD sngpos' 1179 Current song position. Do not change this variable directly, use 1180 `Player_NextPosition', `Player_PrevPosition' or 1181 `Player_SetPosition' instead. 1182 1183`SWORD relspd' 1184 Relative playback speed. The value of this variable is added to 1185 the module tempo to define the actual playback speed. The default 1186 value is 0, which make modules play at their intended speed. 1187 11884.2.3 Module Instruments 1189------------------------ 1190 1191Although the `INSTRUMENT' structure is intended for internal use, you 1192might need to know its name: 1193 1194`CHAR* insname' 1195 The instrument text, theoretically its name, but often a message 1196 line. 1197 11984.2.4 Samples 1199------------- 1200 1201The `SAMPLE' structure is used for sound effects and module samples as 1202well. You can play with the following fields: 1203 1204`SWORD panning' 1205 Panning value of the sample. Valid values range from PAN_LEFT (0) 1206 to PAN_RIGHT (255), or PAN_SURROUND. 1207 1208`ULONG speed' 1209 Playing frequency of the sample, it hertz. 1210 1211`UBYTE volume' 1212 Sample volume. Valid range is 0-64. 1213 1214`UWORD flags' 1215 Several format flags or'ed together describing the format of the 1216 sample in memory. 1217 1218 Format flags: 1219 `SF_16BITS' 1220 If set, sample data is 16 bit wide; otherwise, it is 8 bit 1221 wide. 1222 1223 `SF_BIG_ENDIAN' 1224 If set, sample data is in big-endian (Motorola) format; 1225 otherwise, it is in little-endian (Intel) format. 1226 1227 `SF_DELTA' 1228 If set, sample is stored as delta values (differences between 1229 two consecutive samples); otherwise, sample is stored as 1230 sample values. 1231 1232 `SF_ITPACKED' 1233 If set, sample data is packed with Impulse Tracker's 1234 compression method; otherwise, sample is not packed. 1235 1236 `SF_SIGNED' 1237 If set, sample data is made of signed values; otherwise, it 1238 is made of unsigned values. 1239 1240 `SF_STEREO' 1241 If set, sample data is stereo (two channels); otherwise, it 1242 is mono. 1243 1244 Playback flags: 1245 `SF_BIDI' 1246 If set, sample loops "ping pong" (back and forth). 1247 1248 `SF_LOOP' 1249 If set, sample loops forward. 1250 1251 `SF_REVERSE' 1252 If set, sample plays backwards. 1253 1254`UWORD inflags' 1255 Same as "flags", but describing the format of the sample on disk. 1256 1257`ULONG length' 1258 Length of the sample, in _samples_. The length of a sample is 8 1259 bits (1 byte) for a 8 bit sample, and 16 bits (2 bytes) for a 16 1260 bit sample. 1261 1262`ULONG loopstart' 1263 Loop starting position, relative to the start of the sample, in 1264 samples. 1265 1266`ULONG loopend' 1267 Loop ending position, relative to the start of the sample, in 1268 samples. 1269 12704.2.5 MREADER 1271------------- 1272 1273The `MREADER' contains the following function pointers: 1274 1275`int (*Seek)(struct MREADER*, long offset, int whence)' 1276 This function should have the same behaviour as `fseek', with 1277 offset 0 meaning the start of the object (module, sample) being 1278 loaded. 1279 1280`long (*Tell)(struct MREADER*)' 1281 This function should have the same behaviour as `ftell', with 1282 offset 0 meaning the start of the object being loaded. 1283 1284`BOOL (*Read)(struct MREADER*, void *dest, size_t length)' 1285 This function should copy `length' bytes of data into `dest', and 1286 return zero if an error occured, and any nonzero value otherwise. 1287 Note that an end-of-file condition will not be considered as an 1288 error in this case. 1289 1290`int (*Get)(struct MREADER*)' 1291 This function should have the same behaviour as `fgetc'. 1292 1293`BOOL (*Eof)(struct MREADER*)' 1294 This function should have the same behaviour as `feof'. 1295 1296`long iobase' 1297 Data start base offset. Managed by libmikmod, do not manipulate. 1298 1299`long prev_iobase' 1300 Data start base offset, previous value. Managed by libmikmod, do 1301 not manipulate. 1302 1303 For an example of how to build an `MREADER' object, please refer to 1304the `MFILEREADER' and `MMEMREADER' objects in file `mmio/mmio.c' in the 1305library source, as well as the `splayMEM' example application. 1306 13074.2.6 MWRITER 1308------------- 1309 1310The `MWRITER' contains the following function pointers: 1311 1312`int (*Seek)(struct MWRITER*, long offset, int whence);' 1313 This function should have the same behaviour as `fseek', with 1314 offset 0 meaning the start of the object being written. 1315 1316`long (*Tell)(struct MWRITER*);' 1317 This function should have the same behaviour as `ftell', with 1318 offset 0 meaning the start of the object being written. 1319 1320`BOOL (*Write)(struct MWRITER*, const void *src, size_t length);' 1321 This function should copy `length' bytes of data from `src', and 1322 return zero if an error occured, and any nonzero value otherwise. 1323 1324`int (*Put)(struct MWRITER*, int data);' 1325 This function should have the same behaviour as `fputc'. 1326 1327 For an example of how to build an `MWRITER' object, please refer to 1328the `MFILEWRITER' object in file `mmio/mmio.c' in the library sources. 1329 1330 1331File: mikmod.info, Node: Error Reference, Next: Function Reference, Prev: Structure Reference, Up: Library Reference 1332 13334.3 Error Reference 1334=================== 1335 1336The following errors are currently defined: 1337 13384.3.1 General Errors 1339-------------------- 1340 1341`MMERR_DYNAMIC_LINKING' 1342 This error occurs when a specific driver was requested, but the 1343 support shared library couldn't be loaded. Currently, the only 1344 drivers which can yield this error are the ALSA, EsounD and Ultra 1345 drivers. 1346 1347`MMERR_OPENING_FILE' 1348 This error occurs when a file can not be opened, either for read 1349 access from a `xx_Loadxx' function, or for write access from the 1350 disk writer drivers. 1351 1352`MMERR_OUT_OF_MEMORY' 1353 This error occurs when there is not enough virtual memory 1354 available to complete the operation, or there is enough memory but 1355 the calling process would exceed its memory limit. MikMod does not 1356 do any resource tuning, your program has to use the `setrlimit' 1357 function to do this if it needs to load very huge samples. 1358 13594.3.2 Sample Errors 1360------------------- 1361 1362`MMERR_SAMPLE_TOO_BIG' 1363 This error occurs when the memory allocation of the sample data 1364 yields the error `MMERR_OUT_OF_MEMORY'. 1365 1366`MMERR_OUT_OF_HANDLES' 1367 This error occurs when your program reaches the limit of loaded 1368 samples, currently defined as 384, which should be sufficient for 1369 most cases. 1370 1371`MMERR_UNKNOWN_WAVE_TYPE' 1372 This error occurs when you're trying to load a sample which format 1373 is not recognized. 1374 13754.3.3 Module Errors 1376------------------- 1377 1378`MMERR_ITPACK_INVALID_DATA' 1379 This error occurs when a compressed module sample is corrupt. 1380 1381`MMERR_LOADING_HEADER' 1382 This error occurs when you're trying to load a module which has a 1383 corrupted header, or is truncated. 1384 1385`MMERR_LOADING_PATTERN' 1386 This error occurs when you're trying to load a module which has 1387 corrupted pattern data, or is truncated. 1388 1389`MMERR_LOADING_SAMPLEINFO' 1390 This error occurs when you're trying to load a module which has 1391 corrupted sample information, or is truncated. 1392 1393`MMERR_LOADING_TRACK' 1394 This error occurs when you're trying to load a module which has 1395 corrupted track data, or is truncated. 1396 1397`MMERR_MED_SYNTHSAMPLES' 1398 This error occurs when you're trying to load a MED module which 1399 has synthsounds samples, which are currently not supported.(1) 1400 1401`MMERR_NOT_A_MODULE' 1402 This error occurs when you're trying to load a module which format 1403 is not recognized. 1404 1405`MMERR_NOT_A_STREAM' 1406 This error occurs when you're trying to load a sample with a 1407 sample which format is not recognized. 1408 14094.3.4 Driver Errors 1410------------------- 1411 14124.3.4.1 Generic Driver Errors 1413............................. 1414 1415`MMERR_16BIT_ONLY' 1416 This error occurs when the sound device doesn't support non-16 bit 1417 linear sound output, which are the requested settings. 1418 1419`MMERR_8BIT_ONLY' 1420 This error occurs when the sound device doesn't support non-8 bit 1421 linear sound output, which are the requested settings. 1422 1423`MMERR_DETECTING_DEVICE' 1424 This error occurs when the driver's sound device has not been 1425 detected. 1426 1427`MMERR_INITIALIZING_MIXER' 1428 This error occurs when MikMod's internal software mixer could not 1429 be initialized properly. 1430 1431`MMERR_INVALID_DEVICE' 1432 This error occurs when the driver number (in `md_device') is out 1433 of range. 1434 1435`MMERR_NON_BLOCK' 1436 This error occurs when the driver is unable to set the audio 1437 device in non blocking mode. 1438 1439`MMERR_OPENING_AUDIO' 1440 This error occurs when the driver can not open sound device. 1441 1442`MMERR_STEREO_ONLY' 1443 This error occurs when the sound device doesn't support mono sound 1444 output, which is the requested setting. 1445 1446`MMERR_ULAW' 1447 This error occurs when the sound device only supports uLaw output 1448 (which implies mono, 8 bit, and 8000 Hz sampling rate), which 1449 isn't the requested setting. 1450 1451`MMERR_NO_FLOAT32' 1452 This error occurs when the sound device doesn't support 32 bit 1453 float sound output, which is the requested setting. 1454 14554.3.4.2 AudioFile Driver Specific Error 1456....................................... 1457 1458`MMERR_AF_AUDIO_PORT' 1459 This error occurs when the AudioFile driver can not find a 1460 suitable AudioFile port. 1461 14624.3.4.3 AIX Driver Specific Errors 1463.................................. 1464 1465`MMERR_AIX_CONFIG_CONTROL' 1466 This error occurs when the "Control" step of the device 1467 configuration has failed. 1468 1469`MMERR_AIX_CONFIG_INIT' 1470 This error occurs when the "Init" step of the device configuration 1471 has failed. 1472 1473`MMERR_AIX_CONFIG_START' 1474 This error occurs when the "Start" step of the device 1475 configuration has failed. 1476 14774.3.4.4 Ultra Driver Specific Errors 1478.................................... 1479 1480`MMERR_GUS_RESET' 1481 This error occurs when the sound device couldn't be reset. 1482 1483`MMERR_GUS_SETTINGS' 1484 This error occurs because the sound device only works in 16 bit 1485 linear stereo sound at 44100 Hz, which is not the requested 1486 settings. 1487 1488`MMERR_GUS_TIMER' 1489 This error occurs when the ultra driver could not setup the 1490 playback timer. 1491 14924.3.4.5 HP-UX Driver Specific Errors 1493.................................... 1494 1495`MMERR_HP_AUDIO_DESC' 1496 This error occurs when the HP driver can not get the audio 1497 hardware description. 1498 1499`MMERR_HP_AUDIO_OUTPUT' 1500 This error occurs when the HP driver can not select the audio 1501 output. 1502 1503`MMERR_HP_BUFFERSIZE' 1504 This error occurs when the HP driver can not set the transmission 1505 buffer size. 1506 1507`MMERR_HP_CHANNELS' 1508 This error occurs when the HP driver can not set the requested 1509 number of channels. 1510 1511`MMERR_HP_SETSAMPLESIZE' 1512 This error occurs when the HP driver can not set the requested 1513 sample size. 1514 1515`MMERR_HP_SETSPEED' 1516 This error occurs when the HP driver can not set the requested 1517 sample rate. 1518 15194.3.4.6 ALSA Driver Specific Errors 1520................................... 1521 1522`MMERR_ALSA_NOCONFIG' 1523 This error occurs when no ALSA playback configuration is available. 1524 1525`MMERR_ALSA_SETPARAMS' 1526 This error occurs when the ALSA driver can not set the requested 1527 sample format, sample rate, number of channels, access type, or 1528 latency values. 1529 1530`MMERR_ALSA_SETFORMAT' 1531 This error occurs when the ALSA driver can not set the requested 1532 sample format. 1533 1534`MMERR_ALSA_SETRATE' 1535 This error occurs when the ALSA driver does not support the 1536 requested sample rate. 1537 1538`MMERR_ALSA_SETCHANNELS' 1539 This error occurs when the ALSA driver does not support the 1540 requested number of channels. 1541 1542`MMERR_ALSA_BUFFERSIZE' 1543 This error occurs when the ALSA driver can not retrieve the buffer 1544 or period size. 1545 1546`MMERR_ALSA_PCM_START' 1547 This error occurs when the ALSA driver can not start the pcm 1548 playback. 1549 1550`MMERR_ALSA_PCM_WRITE' 1551 This error occurs when the ALSA driver encounters a write error. 1552 1553`MMERR_ALSA_PCM_RECOVER' 1554 This error occurs when the ALSA driver encounters an error 1555 recovery failure. 1556 15574.3.4.7 Open Sound System Driver Specific Errors 1558................................................ 1559 1560`MMERR_OSS_SETFRAGMENT' 1561 This error occurs when the OSS driver can not set audio fragment 1562 size. 1563 1564`MMERR_OSS_SETSAMPLESIZE' 1565 This error occurs when the OSS driver can not set the requested 1566 sample size. 1567 1568`MMERR_OSS_SETSPEED' 1569 This error occurs when the OSS driver can not set the requested 1570 sample rate. 1571 1572`MMERR_OSS_SETSTEREO' 1573 This error occurs when the OSS driver can not set the requested 1574 number of channels. 1575 15764.3.4.8 SGI Driver Specific Errors 1577.................................. 1578 1579`MMERR_SGI_MONO' 1580 This error occurs when the hardware only supports stereo sound. 1581 1582`MMERR_SGI_SPEED' 1583 This error occurs when the hardware does not support the requested 1584 sample rate. 1585 1586`MMERR_SGI_STEREO' 1587 This error occurs when the hardware only supports mono sound. 1588 1589`MMERR_SGI_16BIT' 1590 This error occurs when the hardware only supports 16 bit sound. 1591 1592`MMERR_SGI_8BIT' 1593 This error occurs when the hardware only supports 8 bit sound. 1594 15954.3.4.9 Sun Driver Specific Error 1596................................. 1597 1598`MMERR_SUN_INIT' 1599 This error occurs when the sound device initialization failed. 1600 16014.3.4.10 OS/2 Driver Specific Errors 1602.................................... 1603 1604`MMERR_OS2_MIXSETUP' 1605 This error occurs when the DART driver can not set the mixing 1606 parameters. 1607 1608`MMERR_OS2_SEMAPHORE' 1609 This error occurs when the MMPM/2 driver can not create the 1610 semaphores needed for playback. 1611 1612`MMERR_OS2_THREAD' 1613 This error occurs when the MMPM/2 driver can not create the thread 1614 needed for playback. 1615 1616`MMERR_OS2_TIMER' 1617 This error occurs when the MMPM/2 driver can not create the timer 1618 needed for playback. 1619 16204.3.4.11 DirectX Driver Specific Errors 1621....................................... 1622 1623`MMERR_DS_BUFFER' 1624 This error occurs when the DirectX driver can not allocate the 1625 playback buffers. 1626 1627`MMERR_DS_EVENT' 1628 This error occurs when the DirectX driver can not register the 1629 playback event. 1630 1631`MMERR_DS_FORMAT' 1632 This error occurs when the DirectX driver can not set the playback 1633 format. 1634 1635`MMERR_DS_NOTIFY' 1636 This error occurs when the DirectX driver can not register the 1637 playback callback. 1638 1639`MMERR_DS_PRIORITY' 1640 This error occurs when the DirectX driver can not set the playback 1641 priority. 1642 1643`MMERR_DS_THREAD' 1644 This error occurs when the DirectX driver can not create the 1645 playback thread. 1646 1647`MMERR_DS_UPDATE' 1648 This error occurs when the DirectX driver can not initialize the 1649 playback thread. 1650 16514.3.4.12 Windows Multimedia API Driver Specific Errors 1652...................................................... 1653 1654`MMERR_WINMM_ALLOCATED' 1655 This error occurs when the playback resource is already allocated 1656 by another application. 1657 1658`MMERR_WINMM_DEVICEID' 1659 This error occurs when the Multimedia API Driver is given an 1660 invalid audio device identificator. 1661 1662`MMERR_WINMM_FORMAT' 1663 This error occurs when the playback output format is not supported 1664 by the audio device. 1665 1666`MMERR_WINMM_HANDLE' 1667 This error occurs when the Multimedia API Driver is given an 1668 invalid handle. 1669 1670`MMERR_WINMM_UNKNOWN' 1671 This error should not occur ! If you get this error, please 1672 contact the libmikmod development mailing list. 1673 16744.3.4.13 MacOS Driver Specific Errors 1675..................................... 1676 1677`MMERR_MAC_SPEED' 1678 This error occurs when the playback speed is not supported by the 1679 audio device. 1680 1681`MMERR_MAC_START' 1682 This error occurs when the MacOS driver can not start playback. 1683 16844.3.5 MaxOS X Driver Specific Errors 1685------------------------------------ 1686 1687`MMERR_OSX_UNKNOWN_DEVICE' 1688 This error occurs if the default audio output device is not an 1689 audio device! If this happens, please contact the maintainer. 1690 1691`MMERR_OSX_BAD_PROPERTY' 1692 This error occurs when the driver encounters a bad parameter when 1693 setting device the properties. 1694 1695`MMERR_OSX_UNSUPPORTED_FORMAT' 1696 This error occurs when the detected audio device does not support 1697 the required format (Linear PCM). 1698 1699`MMERR_OSX_SET_STEREO' 1700 This error occurs when the driver does not support the requested 1701 channels setting. 1702 1703`MMERR_OSX_BUFFER_ALLOC' 1704 This error occurs if the driver fails to allocate the audio 1705 buffers. 1706 1707`MMERR_OSX_ADD_IO_PROC' 1708 This error occurs if the driver fails to add its Audio IO Proc. 1709 1710`MMERR_OSX_DEVICE_START' 1711 This error occurs if the driver fails to start the audio IO Proc. 1712 1713`MMERR_OSX_PTHREAD' 1714 This error occurs if the initialization of the mutex fails. 1715 17164.3.6 Dos "Windows Sound System" Driver Specific Errors 1717------------------------------------------------------- 1718 1719`MMERR_DOSWSS_STARTDMA' 1720 This error occurs if the driver failed to start the cyclic DMA 1721 transfer. 1722 17234.3.7 Dos "SoundBlaster" Driver Specific Errors 1724----------------------------------------------- 1725 1726`MMERR_DOSSB_STARTDMA' 1727 This error occurs if the driver failed to start the cyclic DMA 1728 transfer. 1729 17304.3.8 OpenAL Driver Specific Errors 1731----------------------------------- 1732 1733`MMERR_OPENAL_CREATECTX' 1734 This error occurs if OpenAL fails to create a context during 1735 initialization. 1736 1737`MMERR_OPENAL_CTXCURRENT' 1738 This error occurs if OpenAL fails to set current context during 1739 initialization. 1740 1741`MMERR_OPENAL_GENBUFFERS' 1742 This error occurs if OpenAL fails to generate buffers during 1743 initialization. 1744 1745`MMERR_OPENAL_GENSOURCES' 1746 This error occurs if OpenAL fails to generate a source during 1747 initialization. 1748 1749`MMERR_OPENAL_SOURCE' 1750 This error occurs if OpenAL fails to set source parameters during 1751 initialization. 1752 1753`MMERR_OPENAL_QUEUEBUFFERS' 1754 This error occurs if OpenAL fails to queue buffers on a source. 1755 1756`MMERR_OPENAL_UNQUEUEBUFFERS' 1757 This error occurs if OpenAL fails to remove buffers from the queue. 1758 1759`MMERR_OPENAL_BUFFERDATA' 1760 This error occurs if OpenAL fails to fill a buffer with audio data. 1761 1762`MMERR_OPENAL_GETSOURCE' 1763 This error occurs if OpenAL fails to get source parameters. 1764 1765`MMERR_OPENAL_SOURCEPLAY' 1766 This error occurs if OpenAL fails to play the source. 1767 1768`MMERR_OPENAL_SOURCESTOP' 1769 This error occurs if OpenAL fails to stop the source. 1770 1771 ---------- Footnotes ---------- 1772 1773 (1) You can force libmikmod to load the module (without the 1774synthsounds, of course) by setting the `curious' parameter to `1' when 1775invoking `Player_Loadxx'. 1776 1777 1778File: mikmod.info, Node: Function Reference, Next: Library Core Functions, Prev: Error Reference, Up: Library Reference 1779 17804.4 Function Reference 1781====================== 1782 1783* Menu: 1784 1785* Library Core Functions:: MikMod_xx functions. 1786* Module Player Functions:: Player_xx functions. 1787* Sample Functions:: Sample_xx functions. 1788* Voice Functions:: Voice_xx functions. 1789 1790 1791File: mikmod.info, Node: Library Core Functions, Next: Module Player Functions, Prev: Function Reference, Up: Function Reference 1792 17934.4.1 Library Core Functions 1794---------------------------- 1795 17964.4.1.1 MikMod_Active 1797..................... 1798 1799`BOOL MikMod_Active(void)' 1800Description 1801 This function returns whether sound output is enabled or not. 1802 1803Result 18040 1805 Sound output is disabled. 1806 18071 1808 Sound output is enabled. 1809 1810Notes 1811 Calls to `MikMod_Update' will be ignored when sound output is 1812 disabled. 1813 1814See also 1815 `MikMod_DisableOutput', `MikMod_EnableOutput'. 1816 18174.4.1.2 MikMod_DisableOutput 1818............................ 1819 1820 `void MikMod_DisableOutput(void)' 1821Description 1822 This function stops the sound mixing. 1823 1824Notes 1825 Calls to `MikMod_Update' will be ignored when sound output is 1826 disabled. 1827 1828See also 1829 `MikMod_Active', `MikMod_EnableOutput'. 1830 18314.4.1.3 MikMod_EnableOutput 1832........................... 1833 1834 `int MikMod_EnableOutput(void)' 1835Description 1836 This function starts the sound mixing. 1837 1838Result 18390 1840 Sound mixing is ready. 1841 1842nonzero 1843 An error occurred during the operation. 1844 1845Notes 1846 Calls to `MikMod_Update' will be ignored when sound output is 1847 disabled. 1848 1849See also 1850 `MikMod_Active', `MikMod_DisableOutput'. 1851 18524.4.1.4 MikMod_Exit 1853................... 1854 1855 `void MikMod_Exit(void)' 1856Description 1857 This function deinitializes the sound hardware and frees all the 1858 memory and resources used by MikMod. 1859 1860See also 1861 `MikMod_Init', `MikMod_Reset'. 1862 18634.4.1.5 MikMod_GetVersion 1864......................... 1865 1866 `long MikMod_GetVersion(void)' 1867Description 1868 This function returns the version number of the library. 1869 1870Result 1871 The version number, encoded as follows: `(maj<<16)|(min<<8)|(rev)', 1872 where `maj' is the major version number, `min' is the minor version 1873 number, and `rev' is the revision number. 1874 18754.4.1.6 MikMod_InfoDriver 1876......................... 1877 1878 `CHAR* MikMod_InfoDriver(void)' 1879Description 1880 This function returns a formatted list of the registered drivers 1881 in a buffer. 1882 1883Result 1884 A pointer to a text buffer, or `NULL' if no drivers are registered. 1885 1886Notes 1887 The buffer is created with `MikMod_malloc'; the caller must free it 1888 with `MikMod_free' when it is no longer necessary. 1889 1890See also 1891 `MikMod_RegisterDriver', `MikMod_RegisterAllDrivers'. 1892 18934.4.1.7 MikMod_InfoLoader 1894......................... 1895 1896 `CHAR* MikMod_InfoLoader(void)' 1897Description 1898 This function returns a formatted list of the registered module 1899 loaders in a buffer. 1900 1901Result 1902 A pointer to a text buffer, or `NULL' if no loaders are registered. 1903 1904Notes 1905 The buffer is created with `MikMod_malloc'; the caller must free it 1906 with `MikMod_free' when it is no longer necessary. 1907 1908See also 1909 `MikMod_RegisterLoader', `MikMod_RegisterAllLoaders'. 1910 19114.4.1.8 MikMod_Init 1912................... 1913 1914 `int MikMod_Init(const CHAR *parameters)' 1915Description 1916 This function performs the library initialization, including the 1917 sound driver choice and configuration, and all the necessary 1918 memory allocations. 1919 1920Parameters 1921parameters 1922 Optional parameters given to the sound driver. These parameters 1923 are ignored if the value of `md_device' is zero (autodetection). 1924 1925Result 19260 1927 Initialization was successful. 1928 1929nonzero 1930 An error occurred during initialization. 1931 1932Notes 1933 When the initialization fails, the library uses the nosound sound 1934 driver to let other the other MikMod functions work without 1935 crashing the application. 1936 1937See also 1938 `MikMod_Exit', `MikMod_InitThreads', `MikMod_Reset'. 1939 19404.4.1.9 MikMod_InitThreads 1941.......................... 1942 1943 `BOOL MikMod_InitThreads(void)' 1944Description 1945 This function returns whether libmikmod is thread-safe. 1946 1947Result 19480 1949 The library is not thread-safe. 1950 19511 1952 The library is thread-safe. 1953 1954Notes 1955 This function should be called before any call to `MikMod_Lock' or 1956 `MikMod_Unlock' is made. 1957 1958See also 1959 `MikMod_Lock', `MikMod_Unlock'. 1960 19614.4.1.10 MikMod_Lock 1962.................... 1963 1964 `void MikMod_Lock(void)' 1965Description 1966 This function obtains exclusive access to libmikmod's variables. 1967 1968Notes 1969 This function locks an internal mutex. If the mutex is already 1970 locked, it will block the calling thread until the mutex is 1971 unlocked. 1972 Every `MikMod_Unlock' call should be associated to a `MikMod_Lock' 1973 call. To be sure this is the case, we advise you to define and use 1974 the following macros: 1975 `#define MIKMOD_LOCK MikMod_Lock();{' 1976 `#define MIKMOD_UNLOCK }MikMod_Unlock();' 1977 The function `MikMod_InitThreads' must have been invoked before 1978 any call to `MikMod_Lock' in made. 1979See also 1980 `MikMod_InitThreads', `MikMod_Unlock'. 1981 19824.4.1.11 MikMod_RegisterAllDrivers 1983.................................. 1984 1985 `void MikMod_RegisterAllDrivers(void)' 1986Description 1987 This function registers all the available drivers. 1988 1989See also 1990 `MikMod_InfoDriver', `MikMod_RegisterDriver'. 1991 19924.4.1.12 MikMod_RegisterAllLoaders 1993.................................. 1994 1995 `void MikMod_RegisterAllLoaders(void)' 1996Description 1997 This function registers all the available module loaders. 1998 1999See also 2000 `MikMod_InfoLoader', `MikMod_RegisterLoader'. 2001 20024.4.1.13 MikMod_RegisterDriver 2003.............................. 2004 2005 `void MikMod_RegisterDriver(struct MDRIVER* newdriver)' 2006Description 2007 This function adds the specified driver to the internal list of 2008 usable drivers. 2009 2010Parameters 2011newdriver 2012 A pointer to the `MDRIVER' structure identifying the driver. 2013 2014Notes 2015 It is safe to register the same driver several times, although it 2016 will not be duplicated in the list. 2017 You should register all the drivers you need before calling 2018 `MikMod_Init'. If you want to register all the available drivers, 2019 use `MikMod_RegisterAllDrivers' instead. 2020 2021See also 2022 `MikMod_InfoDriver', `MikMod_RegisterAllDrivers'. 2023 20244.4.1.14 MikMod_RegisterErrorHandler 2025.................................... 2026 2027 `MikMod_handler_t MikMod_RegisterErrorHandler(MikMod_handler_t 2028newhandler)' 2029Description 2030 This function selects the function which should be called in case 2031 of error. 2032 2033Parameters 2034newhandler 2035 The new error callback function. 2036 2037Result 2038 The previous error callback function, or `NULL' if there was none. 2039 2040Notes 2041 `MikMod_handler_t' is defined as `void(*function)(void)', this 2042 means your error function has the following prototype: `void 2043 MyErrorHandler(void)' 2044 The error callback function is called when errors are detected, 2045 but not always immediately (the library has to resume to a stable 2046 state before calling your callback). 2047 20484.4.1.15 MikMod_RegisterLoader 2049.............................. 2050 2051 `void MikMod_RegisterLoader(struct MLOADER* newloader)' 2052Description 2053 This function adds the specified module loader to the internal 2054 list of usable module loaders. 2055 2056Parameters 2057newloader 2058 A pointer to the `MLOADER' structure identifying the loader. 2059 2060Notes 2061 It is safe to register the same loader several times, although it 2062 will not be duplicated in the list. 2063 You should register all the loaders you need before calling 2064 `Player_Load' or `Player_LoadFP'. If you want to register all the 2065 available module loaders, use `MikMod_RegisterAllLoaders' instead. 2066 The 15 instrument module loader (`load_m15') should always be 2067 registered last. 2068 2069See also 2070 `MikMod_InfoLoader', `MikMod_RegisterAllLoaders'. 2071 20724.4.1.16 MikMod_RegisterPlayer 2073.............................. 2074 2075 `MikMod_player_t MikMod_RegisterPlayer(MikMod_player_t newplayer)' 2076Description 2077 This function selects the function which should be used to process 2078 module playback. 2079 2080Parameters 2081newplayer 2082 The new playback function 2083 2084Result 2085 The previous playback function. 2086 2087Notes 2088 `MikMod_player_t' is defined as `void(*function)(void)', this means 2089 your player function has the following prototype: `void 2090 MyPlayer(void)' 2091 The player function is called every module tick to process module 2092 playback. The rate at which the player function is called is 2093 controlled by the sound driver, and is computed by the following 2094 equation: 2095 (bpm*50)/125 calls per second, which means every 125000/(bpm*50) 2096 milliseconds. The `bpm' value is the tempo of the module and can 2097 change from its initial value when requested by the module. 2098 When changing the playback function, you should make sure that you 2099 chain to the default MikMod playback function, otherwise you won't 2100 get module sound anymore... 2101 2102Example 2103 MikMod_player_t oldroutine; 2104 2105 void MyPlayer(void) 2106 { 2107 oldroutine(); 2108 /* your stuff here */ 2109 ... 2110 } 2111 2112 main() 2113 { 2114 ... 2115 /* Register our player */ 2116 oldroutine = MikMod_RegisterPlayer(MyPlayer); 2117 ... 2118 } 2119 21204.4.1.17 MikMod_Reset 2121..................... 2122 2123 `int MikMod_Reset(const CHAR *parameters)' 2124Description 2125 This function resets MikMod and reinitialize the sound hardware. 2126 2127Parameters 2128parameters 2129 Optional parameters given to the sound driver. If you set the 2130 value of `md_device' to zero (autodetect), these parameters are 2131 ignored. 2132 2133Result 21340 2135 Reinitialization was successful. 2136 2137nonzero 2138 An error occurred during reinitialization. 2139 2140Notes 2141 Use this function when you have changed the global configuration 2142 variables: `md_device' and `md_mixfreq', or one of the `md_mode' 2143 flags which require sound reinitialization. Sound playback will 2144 continue as soon as the driver is ready. 2145 2146See also 2147 `MikMod_Exit', `MikMod_Init'. 2148 21494.4.1.18 MikMod_SetNumVoices 2150............................ 2151 2152 `int MikMod_SetNumVoices(int musicvoices, int samplevoices)' 2153Description 2154 This function sets the number of mixed voices which can be used 2155 for music and sound effects playback. 2156 2157Parameters 2158musicvoices 2159 The number of voices to reserve for music playback. 2160 2161samplevoices 2162 The number of voices to reserve for sound effects. 2163 2164Result 21650 2166 Initialization was successful. 2167 2168nonzero 2169 An error occurred during initialization. 2170 2171Notes 2172 A value of `-1' for any of the parameters will retain the current 2173 number of reserved voices. 2174 The maximum number of voices vary from driver to driver (hardware 2175 drivers often have a limit of 32 to 64 voices, whereas the 2176 software drivers handle 255 voices). If your settings exceed the 2177 driver's limit, they will be truncated. 2178 2179See also 2180 `MikMod_Init', `MikMod_Reset'. 2181 21824.4.1.19 MikMod_Unlock 2183...................... 2184 2185 `void MikMod_Unlock(void)' 2186Description 2187 This function relinquishes exclusive access to libmikmod's 2188 variables. 2189 2190Notes 2191 This function unlocks an internal mutex, so that other threads 2192 waiting for the lock can be resumed. 2193 Every `MikMod_Unlock' call should be associated to a `MikMod_Lock' 2194 call. To be sure this is the case, we advise you to define and use 2195 the following macros: 2196 `#define MIKMOD_LOCK MikMod_Lock();{' 2197 `#define MIKMOD_UNLOCK }MikMod_Unlock();' 2198 The function `MikMod_InitThreads' must have been invoked before 2199 any call to `MikMod_Unlock' in made. 2200See also 2201 `MikMod_InitThreads', `MikMod_Lock'. 2202 22034.4.1.20 MikMod_Update 2204...................... 2205 2206 `void MikMod_Update(void)' 2207Description 2208 This routine should be called on a regular basis to update the 2209 sound. 2210 2211Notes 2212 The sound output buffer is filled each time this function is 2213 called; if you use a large buffer, you don't need to call this 2214 routine as frequently as with a smaller buffer, but you get a 2215 bigger shift between the sound being played and the reported state 2216 of the player, since the player is always a buffer ahead of the 2217 playback. 2218 If you play low quality sound (for example, mono 8 bit 11kHz 2219 sound), you only need to call this routine a few times per second. 2220 However, for high quality sound (stereo 16 bit 44kHz), this rate 2221 increases to a few hundred times per second, but never more, due 2222 to the minimal buffer size constraint imposed to the sound drivers. 2223 If you plan on modifying voice information with the `Voice_xx' 2224 functions, you should do this before calling `MikMod_Update'. 2225 22264.4.1.21 MikMod_strerror 2227........................ 2228 2229 `const char* MikMod_strerror(int errnum)' 2230Description 2231 This function associates a descriptive message to an error code. 2232 2233Parameters 2234errnum 2235 The MikMod error code. 2236 2237Result 2238 A pointer to a string describing the error. 2239 2240 2241File: mikmod.info, Node: Module Player Functions, Next: Sample Functions, Prev: Library Core Functions, Up: Function Reference 2242 22434.4.2 Module Player Functions 2244----------------------------- 2245 22464.4.2.1 Player_Active 2247..................... 2248 2249`BOOL Player_Active(void)' 2250Description 2251 This function returns whether the module player is active or not. 2252 2253Result 22540 2255 No module is playing. 2256 2257nonzero 2258 A module is currently playing. 2259 2260Notes 2261 This function will still report that the player is active if the 2262 playing module is paused. 2263 2264See also 2265 `Player_Paused', `Player_TogglePause', `Player_Start', 2266 `Player_Stop' 2267 22684.4.2.2 Player_Free 2269................... 2270 2271 `void Player_Free(MODULE* module)' 2272Description 2273 This function stops the module if it is playing and unloads it 2274 from memory. 2275 2276Parameters 2277module 2278 The module to free. 2279 2280See also 2281 `Player_Load', `Player_LoadFP'. 2282 22834.4.2.3 Player_GetChannelVoice 2284.............................. 2285 2286 `int Player_GetChannelVoice(UBYTE channel)' 2287Description 2288 This function determines the voice corresponding to the specified 2289 module channel. 2290 2291Parameters 2292channel 2293 The module channel to use. 2294 2295Result 2296 The number of the voice corresponding to the module channel. 2297 2298Notes 2299 If the module channel has NNAs, the number will correspond to the 2300 main channel voice. 2301 2302See also 2303 `Voice_SetPanning', `Voice_SetVolume', `Player_Mute', 2304 `Player_ToggleMute', `Player_Unmute'. 2305 23064.4.2.4 Player_GetModule 2307........................ 2308 2309 `MODULE* Player_GetModule(void)' 2310Description 2311 This function returns the module currently being played. 2312 2313Result 2314 A pointer to the `MODULE' being played, or `NULL' if no module is 2315 playing. 2316 2317See also 2318 `Player_Stop', `Player_Start'. 2319 23204.4.2.5 Player_Load 2321................... 2322 2323 `MODULE* Player_Load(const CHAR* filename, int maxchan, BOOL 2324curious)' 2325Description 2326 This function loads a music module. 2327 2328Parameters 2329filename 2330 The name of the module file. 2331 2332maxchan 2333 The maximum number of channels the song is allowed to request from 2334 the mixer. 2335 2336curious 2337 The curiosity level to use. 2338 2339Result 2340 A pointer to a `MODULE' structure, or `NULL' if an error occurs. 2341 2342Notes 2343 If the curiosity level is set to zero, the module will be loaded 2344 normally. However, if it is nonzero, the following things occur: 2345 * pattern positions occurring after the "end of song" marker in 2346 S3M and IT modules are loaded, and the end of song is set to 2347 the last position. 2348 2349 * hidden extra patterns are searched in MOD modules, and if 2350 found, played after the last "official" pattern. 2351 2352 * MED modules with synthsounds are loaded without causing the 2353 `MMERR_MED_SYNTHSAMPLES', and synthsounds are mapped to an 2354 empty sample. 2355 2356See also 2357 `Player_Free', `Player_LoadFP', `Player_LoadTitle', 2358 `Player_LoadTitleFP', `Player_Start'. 2359 23604.4.2.6 Player_LoadFP 2361..................... 2362 2363 `MODULE* Player_LoadFP(FILE* file, int maxchan, BOOL curious)' 2364Description 2365 This function loads a music module. 2366 2367Parameters 2368file 2369 An open file, at the position where the module starts. 2370 2371maxchan 2372 The maximum number of channels the song is allowed to request from 2373 the mixer. 2374 2375curious 2376 The curiosity level to use. 2377 2378Result 2379 A pointer to a `MODULE' structure, or `NULL' if an error occurs. 2380 2381Notes 2382 The file is left open, at the same position as before the function 2383 call. 2384 If the curiosity level is set to zero, the module will be loaded 2385 normally. However, if it is nonzero, the following things occur: 2386 * pattern positions occurring after the "end of song" marker in 2387 S3M and IT modules are loaded, and the end of song is set to 2388 the last position. 2389 2390 * hidden extra patterns are searched in MOD modules, and if 2391 found, played after the last "official" pattern. 2392 2393 * MED modules with synthsounds are loaded without causing the 2394 `MMERR_MED_SYNTHSAMPLES', and synthsounds are mapped to an 2395 empty sample. 2396 2397See also 2398 `Player_Free', `Player_Load', `Player_LoadTitle', 2399 `Player_LoadTitleFP', `Player_Start'. 2400 24014.4.2.7 Player_LoadTitle 2402........................ 2403 2404 `MODULE* Player_LoadTitle(const CHAR* filename)' 2405Description 2406 This function retrieves the title of a module file. 2407 2408Parameters 2409filename 2410 The name of the module file. 2411 2412Result 2413 A pointer to the song title, or `NULL' if either the module has no 2414 title or an error has occurred. 2415 2416Notes 2417 The title buffer is created with `MikMod_malloc'; the caller must 2418 free it with `MikMod_free' when it is no longer necessary. 2419 2420See also 2421 `Player_Load', `Player_LoadFP', `Player_LoadTitleFP'. 2422 24234.4.2.8 Player_LoadTitleFP 2424.......................... 2425 2426 `MODULE* Player_LoadTitleFP(FILE* file)' 2427Description 2428 This function retrieves the title of a module file. 2429 2430Parameters 2431file 2432 An open file, at the position where the module starts. 2433 2434Result 2435 A pointer to the song title, or `NULL' if either the module has no 2436 title or an error has occurred. 2437 2438Notes 2439 The title buffer is created with `MikMod_malloc'; the caller must 2440 free it with `MikMod_free' when it is no longer necessary. 2441 2442See also 2443 `Player_Load', `Player_LoadFP', `Player_LoadTitle'. 2444 24454.4.2.9 Player_Mute 2446................... 2447 2448 `void Player_Mute(SLONG operation, ...)' 2449Description 2450 This function mutes a single module channel, or a range of module 2451 channels. 2452 2453Parameters 2454operation 2455 Either the number of a module channel to mute (starting from 2456 zero), or an operation code. In the latter case, two extra 2457 parameters are needed to determine the range of channels. 2458 2459Notes 2460 If the operation is `MUTE_INCLUSIVE', the two channel numbers 2461 delimit the range and are part of the range ; otherwise, if the 2462 operation is `MUTE_EXCLUSIVE', they are outside of the range. 2463 2464Example 2465 /* mute channel 10 */ 2466 Player_Mute(10); 2467 /* mute channels 2 to 5 */ 2468 Player_Mute(MUTE_INCLUSIVE, 2, 5); 2469 /* mute channels 7 to 9 */ 2470 Player_Mute(MUTE_EXCLUSIVE, 6, 10); 2471 2472See also 2473 `Player_Muted', `Player_ToggleMute', `Player_Unmute'. 2474 24754.4.2.10 Player_Muted 2476..................... 2477 2478 `BOOL Player_Muted(UBYTE channel)' 2479Description 2480 This function determines whether a module channel is muted or not. 2481 2482Parameters 2483channel 2484 The module channel to test (starting from zero). 2485 2486Result 24870 2488 The channel is not muted. 2489 24901 2491 The channel is muted. 2492 2493See also 2494 `Player_Mute', `Player_ToggleMute', `Player_Unmute'. 2495 24964.4.2.11 Player_NextPosition 2497............................ 2498 2499 `void Player_NextPosition(void)' 2500Description 2501 This function jumps to the next position in the module. 2502 2503Notes 2504 All playing samples and active song voices are cut to avoid 2505 hanging notes. 2506 2507See also 2508 `Player_PrevPosition', `Player_SetPosition'. 2509 25104.4.2.12 Player_Paused 2511...................... 2512 2513 `BOOL Player_Paused(void)' 2514Description 2515 This function determines whether the module is paused or not. 2516 2517Result 25180 2519 The module is not paused. 2520 25211 2522 The module is paused. 2523 2524See also 2525 `Player_TogglePause'. 2526 25274.4.2.13 Player_PrevPosition 2528............................ 2529 2530 `void Player_PrevPosition(void)' 2531Description 2532 This function jumps to the previous position in the module. 2533 2534Notes 2535 All playing samples and active song voices are cut to avoid 2536 hanging notes. 2537 2538See also 2539 `Player_NextPosition', `Player_SetPosition'. 2540 25414.4.2.14 Player_SetPosition 2542........................... 2543 2544 `void Player_SetPosition(UWORD position)' 2545Description 2546 This function jumps to the specified position in the module. 2547 2548Parameters 2549position 2550 The pattern position to jump to. 2551 2552Notes 2553 All playing samples and active song voices are cut to avoid 2554 hanging notes. 2555 2556See also 2557 `Player_NextPosition', `Player_PrevPosition'. 2558 25594.4.2.15 Player_SetSpeed 2560........................ 2561 2562 `void Player_SetSpeed(UWORD speed)' 2563Description 2564 This function sets the module speed. 2565 2566Parameters 2567speed 2568 The new module speed, in the range 1-32. 2569 2570See also 2571 `Player_SetTempo'. 2572 25734.4.2.16 Player_SetTempo 2574........................ 2575 2576 `void Player_SetTempo(UWORD tempo)' 2577Description 2578 This function sets the module tempo. 2579 2580Parameters 2581tempo 2582 The new module tempo, in the range 32-255. 2583 2584See also 2585 `Player_SetSpeed'. 2586 25874.4.2.17 Player_SetVolume 2588......................... 2589 2590 `void Player_SetVolume(SWORD volume)' 2591Description 2592 This function sets the module volume. 2593 2594Parameters 2595volume 2596 The new overall module playback volume, in the range 0-128. 2597 25984.4.2.18 Player_Start 2599..................... 2600 2601 `void Player_Start(MODULE* module)' 2602Description 2603 This function starts the specified module playback. 2604 2605Parameters 2606module 2607 The module to play. 2608 2609Notes 2610 If another module is playing, it will be stopped and the new 2611 module will play. 2612 2613See also 2614 `Player_Stop'. 2615 26164.4.2.19 Player_Stop 2617.................... 2618 2619 `void Player_Stop(void)' 2620Description 2621 This function stops the currently playing module. 2622 2623See also 2624 `Player_Start'. 2625 26264.4.2.20 Player_ToggleMute 2627.......................... 2628 2629 `void Player_ToggleMute(SLONG operation, ...)' 2630Description 2631 This function changes the muted status of a single module channel, 2632 or a range of module channels. 2633 2634Parameters 2635operation 2636 Either the number of a module channel to work on (starting from 2637 zero), or an operation code. In the latter case, two extra 2638 parameters are needed to determine the range of channels. 2639 2640Notes 2641 If the operation is `MUTE_INCLUSIVE', the two channel numbers 2642 delimit the range and are part of the range ; otherwise, if the 2643 operation is `MUTE_EXCLUSIVE', they are outside of the range. 2644 2645Example 2646 /* toggle mute on channel 10 */ 2647 Player_ToggleMute(10); 2648 /* toggle mute on channels 2 to 5 */ 2649 Player_ToggleMute(MUTE_INCLUSIVE, 2, 5); 2650 /* toggle mute on channels 7 to 9 */ 2651 Player_ToggleMute(MUTE_EXCLUSIVE, 6, 10); 2652 2653See also 2654 `Player_Mute', `Player_Muted', `Player_Unmute'. 2655 26564.4.2.21 Player_TogglePause 2657........................... 2658 2659 `void Player_TogglePause(void)' 2660Description 2661 This function toggles the playing/paused status of the module. 2662 2663Notes 2664 Calls to `Player_xx' functions still have effect when the module 2665 is paused. 2666 2667See also 2668 `Player_Paused', `Player_Start', `Player_Stop'. 2669 26704.4.2.22 Player_Unmute 2671...................... 2672 2673 `void Player_Unmute(SLONG operation, ...)' 2674Description 2675 This function unmutes a single module channel, or a range of 2676 module channels. 2677 2678Parameters 2679operation 2680 Either the number of a module channel to unmute (starting from 2681 zero), or an operation code. In the latter case, two extra 2682 parameters are needed to determine the range of channels. 2683 2684Notes 2685 If the operation is `MUTE_INCLUSIVE', the two channel numbers 2686 delimit the range and are part of the range ; otherwise, if the 2687 operation is `MUTE_EXCLUSIVE', they are outside of the range. 2688 2689Example 2690 /* unmute channel 10 */ 2691 Player_Unmute(10); 2692 /* unmute channels 2 to 5 */ 2693 Player_Unmute(MUTE_INCLUSIVE, 2, 5); 2694 /* unmute channels 7 to 9 */ 2695 Player_Unmute(MUTE_EXCLUSIVE, 6, 10); 2696 2697See also 2698 `Player_Mute', `Player_Muted', `Player_ToggleMute'. 2699 2700 2701File: mikmod.info, Node: Sample Functions, Next: Voice Functions, Prev: Module Player Functions, Up: Function Reference 2702 27034.4.3 Sample Functions 2704---------------------- 2705 27064.4.3.1 Sample_Free 2707................... 2708 2709`void Sample_Free(SAMPLE* sample)' 2710Description 2711 This function unloads a sample from memory. 2712 2713Parameters 2714sample 2715 The sample to free. 2716 2717See also 2718 `Sample_Load', `Sample_LoadFP'. 2719 27204.4.3.2 Sample_Load 2721................... 2722 2723 `SAMPLE* Sample_Load(const CHAR* filename)' 2724Description 2725 This function loads a sample. 2726 2727Parameters 2728filename 2729 The sample filename. 2730 2731Result 2732 A pointer to a `SAMPLE' structure, or `NULL' if an error has 2733 occurred. 2734 2735See also 2736 `Sample_Free', `Sample_LoadFP'. 2737 27384.4.3.3 Sample_LoadFP 2739..................... 2740 2741 `SAMPLE* Sample_LoadFP(FILE* file)' 2742Description 2743 This function loads a sample. 2744 2745Parameters 2746file 2747 An open file, at the position where the sample starts. 2748 2749Result 2750 A pointer to a `SAMPLE' structure, or `NULL' if an error has 2751 occurred. 2752 2753Notes 2754 The file is left open, at the same position as before the function 2755 call. 2756 2757See also 2758 `Sample_Free', `Sample_Load'. 2759 27604.4.3.4 Sample_Play 2761................... 2762 2763 `SBYTE Sample_Play(SAMPLE* sample, ULONG start, UBYTE flags)' 2764Description 2765 This function plays a sample as a sound effect. 2766 2767Parameters 2768sample 2769 The sample to play. 2770 2771start 2772 The starting position (in samples). 2773 2774flags 2775 Either zero, for normal sound effects, or `SFX_CRITICAL', for 2776 critical sound effects which must not be interrupted. 2777 2778Result 2779 The voice number corresponding to the voice which will play the 2780 sample. 2781 2782Notes 2783 Each new sound effect is played on a new voice. When all voices 2784 are taken, the oldest sample which was not marked as critical is 2785 cut and its voice is used for the new sample. Critical samples are 2786 not cut unless all the voices are taken with critical samples and 2787 you attempt to play yet another critical sample. Use `Voice_Stop' 2788 to force the end of a critical sample. 2789 2790See also 2791 `MikMod_SetNumVoices', `Voice_Play', `Voice_SetFrequency', 2792 `Voice_SetPanning', `Voice_SetVolume', `Voice_Stop'. 2793 2794 2795File: mikmod.info, Node: Voice Functions, Next: Loader Reference, Prev: Sample Functions, Up: Function Reference 2796 27974.4.4 Voice Functions 2798--------------------- 2799 28004.4.4.1 Voice_GetFrequency 2801.......................... 2802 2803`ULONG Voice_GetFrequency(SBYTE voice)' 2804Description 2805 This function returns the frequency of the sample currently 2806 playing on the specified voice. 2807 2808Parameters 2809voice 2810 The number of the voice to get frequency. 2811 2812Result 2813 The current frequency of the sample playing on the specified 2814 voice, or zero if no sample is currently playing on the voice. 2815 2816See also 2817 `Voice_SetFrequency'. 2818 28194.4.4.2 Voice_GetPanning 2820........................ 2821 2822 `ULONG Voice_GetPanning(SBYTE voice)' 2823Description 2824 This function returns the panning position of the sample currently 2825 playing on the specified voice. 2826 2827Parameters 2828voice 2829 The number of the voice to get panning position. 2830 2831Result 2832 The current panning position of the sample playing on the 2833 specified voice, or `PAN_CENTER' if no sample is currently playing 2834 on the voice. 2835 2836See also 2837 `Voice_SetPanning'. 2838 28394.4.4.3 Voice_GetPosition 2840......................... 2841 2842 `SLONG Voice_GetPosition(SBYTE voice)' 2843Description 2844 This function returns the sample position (in samples) of the 2845 sample currently playing on the specified voice. 2846 2847Parameters 2848voice 2849 The number of the voice to get sample position (starting from 2850 zero). 2851 2852Result 2853 The current play location of the sample playing on the specified 2854 voice, or zero if the position can not be determined or if no 2855 sample is currently playing on the voice. 2856 2857Notes 2858 This function may not work with some drivers (especially for 2859 hardware mixed voices). In this case, it returns always `-1'. 2860 2861See also 2862 `Sample_Play', `Voice_Play'. 2863 28644.4.4.4 Voice_GetVolume 2865....................... 2866 2867 `UWORD Voice_GetVolume(SBYTE voice)' 2868Description 2869 This function returns the volume of the sample currently playing 2870 on the specified voice. 2871 2872Parameters 2873voice 2874 The number of the voice to get volume. 2875 2876Result 2877 The current volume of the sample playing on the specified voice, 2878 or zero if no sample is currently playing on the voice. 2879 2880See also 2881 `Voice_RealVolume', `Voice_SetVolume'. 2882 28834.4.4.5 Voice_Play 2884.................. 2885 2886 `void Voice_Play(SBYTE voice, SAMPLE* sample, ULONG start)' 2887Description 2888 Start a new sample in the specified voice. 2889 2890Parameters 2891voice 2892 The number of the voice to be processed (starting from zero). 2893 2894sample 2895 The sample to play. 2896 2897start 2898 The starting position (in samples). 2899 2900Notes 2901 The sample will be played at the volume, panning and frequency 2902 settings of the voice, regardless or the sample characteristics. 2903 The sample played this way gets the same "critical" status as the 2904 sample which was previously played on this voice. 2905 2906See also 2907 `Sample_Play', `Voice_SetFrequency', `Voice_SetPanning', 2908 `Voice_SetVolume'. 2909 29104.4.4.6 Voice_RealVolume 2911........................ 2912 2913 `ULONG Voice_RealVolume(SBYTE voice)' 2914Description 2915 This function returns the actual playing volume of the specified 2916 voice. 2917 2918Parameters 2919voice 2920 The number of the voice to analyze (starting from zero). 2921 2922Result 2923 The real volume of the voice when the function was called, in the 2924 range 0-65535, not related to the volume constraint specified with 2925 `Voice_SetVolume'. 2926 2927Notes 2928 This function may not work with some drivers (especially for 2929 hardware mixed voices). In this case, it always returns zero. 2930 Also note that the real volume computation is not a trivial 2931 process and takes some CPU time. 2932 2933See also 2934 `Sample_Play', `Voice_GetVolume', `Voice_Play', `Voice_SetVolume'. 2935 29364.4.4.7 Voice_SetFrequency 2937.......................... 2938 2939 `void Voice_SetFrequency(SBYTE voice, ULONG frequency)' 2940Description 2941 This function sets the frequency (pitch) of the specified voice. 2942 2943Parameters 2944voice 2945 The number of the voice to be processed (starting from zero). 2946 2947frequency 2948 The new frequency of the voice, in hertz. 2949 2950See also 2951 `Sample_Play', `Voice_GetFrequency', `Voice_Play', 2952 `Voice_SetPanning', `Voice_SetVolume', `Voice_Stop'. 2953 29544.4.4.8 Voice_SetPanning 2955........................ 2956 2957 `void Voice_SetPanning(SBYTE voice, ULONG panning)' 2958Description 2959 This function sets the panning position of the specified voice. 2960 2961Parameters 2962voice 2963 The number of the voice to be processed (starting from zero). 2964 2965panning 2966 The new panning position of the voice. 2967 2968Notes 2969 Panning can vary between 0 (`PAN_LEFT') and 255 (`PAN_RIGHT'). 2970 Center is 127 (`PAN_CENTER'. Surround sound can be enabled by 2971 specifying the special value `PAN_SURROUND'. 2972 2973See also 2974 `Sample_Play', `Voice_GetPanning', `Voice_Play', 2975 `Voice_SetFrequency', `Voice_SetVolume', `Voice_Stop'. 2976 29774.4.4.9 Voice_SetVolume 2978....................... 2979 2980 `void Voice_SetVolume(SBYTE voice, UWORD volume)' 2981Description 2982 This function sets the volume of the specified voice. 2983 2984Parameters 2985voice 2986 The number of the voice to be processed (starting from zero). 2987 2988volume 2989 The new volume of the voice, in the range 0-256. 2990 2991See also 2992 `Sample_Play', `Voice_GetVolume', `Voice_Play', 2993 `Voice_SetFrequency', `Voice_SetPanning', `Voice_Stop'. 2994 29954.4.4.10 Voice_Stop 2996................... 2997 2998 `void Voice_Stop(SBYTE voice)' 2999Description 3000 This function stops the playing sample of the specified voice. 3001 3002Parameters 3003voice 3004 The number of the voice to be processed (starting from zero). 3005 3006Notes 3007 After the call to `Voice_Stop', the function `Voice_Stopped' will 3008 return nonzero (true) for the voice. If you want to silence the 3009 voice without stopping the playback, use `Voice_SetVolume(voice, 3010 0)' instead. 3011 3012See also 3013 `Sample_Play', `Voice_Play', `Voice_SetFrequency', 3014 `Voice_SetPanning', `Voice_SetVolume'. 3015 30164.4.4.11 Voice_Stopped 3017...................... 3018 3019 `BOOL Voice_Stopped(SBYTE voice)' 3020Description 3021 This function returns whether the voice is active or not. 3022 3023Parameters 3024voice 3025 The number of the voice to be checked (starting from zero). 3026 3027Result 30280 3029 The voice is stopped or has no sample assigned. 3030 3031nonzero 3032 The voice is playing a sample. 3033 3034Notes 3035 This function may not work with some drivers (especially for 3036 hardware mixed voices). In this case, its return value is 3037 undefined. 3038 3039See also 3040 `Voice_Stop'. 3041 3042 3043File: mikmod.info, Node: Loader Reference, Next: Module Loaders, Prev: Voice Functions, Up: Library Reference 3044 30454.5 Loader Reference 3046==================== 3047 3048* Menu: 3049 3050* Module Loaders:: 3051* Sample Loaders:: 3052 3053 3054File: mikmod.info, Node: Module Loaders, Next: Sample Loaders, Prev: Loader Reference, Up: Loader Reference 3055 30564.5.1 Module Loaders 3057-------------------- 3058 3059MikMod presents a large choice of module loaders, for the most common 3060formats as well as for some less-known exotic formats. 3061 3062`load_669' 3063 This loader recognizes "Composer 669" and "Unis 669" modules. The 3064 669 and "Extended 669" formats were among the first PC module 3065 formats. They do not have a wide range of effects, but support up 3066 to 32 channels. 3067 "Composer 669" was written by Tran of Renaissance, a.k.a. Tomasz 3068 Pytel and released in 1992. "Unis 669 Composer" was written by 3069 Jason Nunn and released in 1994. 3070 3071`load_amf' 3072 This loader recognizes the "Advanced Module Format", which is the 3073 internal module format of the "DOS Sound and Music Interface" 3074 (DSMI) library. This format has the same limitations as the S3M 3075 format. The most famous DSMI application was DMP, the Dual Module 3076 Player. 3077 DMP and the DSMI library were written by Otto Chrons. DSMI was 3078 first released in 1993. 3079 3080`load_asy' 3081 This loader recognize the "ASYLUM Music Format", which was used in 3082 Crusader series of games by Origin. This format uses the .amf 3083 extension, but is very similar to a 8 Channel Mod file. 3084 3085`load_dsm' 3086 This loader recognizes the internal DSIK format, which is the 3087 internal module format of the "Digital Sound Interface Kit" (DSIK) 3088 library, the ancester of the SEAL library. This format has the 3089 same limitations as the S3M format. 3090 The DSIK library was written by Carlos Hasan and released in 1994. 3091 3092`load_far' 3093 This loader recognizes "Farandole" modules. These modules can be 3094 up to 16 channels and have Protracker comparable effects. 3095 The Farandole composer was written by Daniel Potter and released 3096 in 1994. 3097 3098`load_gdm' 3099 This loader recognizes the "General DigiMusic" format, which is 3100 the internal format of the "Bells, Whistles and Sound Boards" 3101 library. This format has the same limitations as the S3M format. 3102 The BWSB library was written by Edward Schlunder and first 3103 released in 1993. 3104 3105`load_imf' 3106 This loader recognizes "Imago Orpheus" modules. This format is 3107 roughly equivalent to the XM format, but with two effects columns 3108 instead of a volume column and an effect column. 3109 Imago Orpheus was written by Lutz Roeder and released in 1994. 3110 3111`load_it' 3112 This loader recognizes "Impulse Tracker" modules, currently the 3113 most powerful format. These modules support up to 64 real 3114 channels, and up to 256 virtual channels with the "New Note 3115 Action" feature. Besides, it has the widest range of effects, and 3116 supports 16 bit samples as well as surround sound. 3117 "Impulse Tracker" was written by Jeffrey Lim and released in 1996. 3118 3119`load_med' 3120 This loader recognizes "OctaMED" modules. These modules are 3121 comparable to Protracker modules, but can embed "synthsounds", 3122 which are midi-like instruments. 3123 "MED" and later "OctaMED" were written by Teijo Kinnunen. "MED" was 3124 released in 1989, and "OctaMED" was released in 1992. 3125 3126`load_m15' 3127 This loader recognizes the old 15 instrument modules, created by 3128 "Ultimate Soundtracker", "Soundtracker" and the first versions of 3129 "Protracker". 3130 Since this format was one of the first module formats, developed 3131 in 1987, it does not have any signature field, which makes it hard 3132 to detect reliably, because of its similarities with later module 3133 formats. 3134 3135`load_mod' 3136 This loader recognizes the standard 31 instrument modules, created 3137 by "Protracker" or Protracker-compatible programs. The original 3138 Protracker format was limited to 4 channels, but other trackers 3139 like "TakeTracker", "StarTracker" or "Oktalyzer" afforded more 3140 channels. 3141 Although it is now technically obsolete, this format is still 3142 widely used, due to its playback simplicity (on the adequate 3143 hardware, the Amiga). 3144 3145`load_mtm' 3146 This loader recognizes the "MultiTracker Module Editor" modules. 3147 The MTM format has up to 32 channels, and protracker comparable 3148 effects. It was intended to replace "Composer 669". The 3149 "MultiTracker Module Editor" was written by Starscream of 3150 Renaissance, a.k.a. Daniel Goldstein and released in late 1993. 3151 3152`load_okt' 3153 This loader recognizes the "Amiga Oktalyzer" modules. The OKT 3154 format has up to 8 channels, and a few protracker compatible 3155 effects, as well as other OKT-specific effects, of which only a 3156 few are currently supported by libmikmod. "Oktalyzer" was written 3157 by Armin Sander and released in 1990. 3158 3159`load_stm' 3160 This loader recognizes "ScreamTracker" modules. "ScreamTracker" 3161 was the first PC tracker, as well as the first PC module format. 3162 Loosely inspired by the "SoundTracker" format, it does not have as 3163 many effects as Protracker, although it supports 31 instruments 3164 and 4 channels. 3165 "ScreamTracker" was written by PSI of Future Crew, a.k.a. Sami 3166 Tammilehto. 3167 3168`load_stx' 3169 This loader recognizes "STMIK 0.2" modules. "STMIK" (the Scream 3170 Tracker Music Interface Kit) was a module playing library 3171 distributed by Future Crew to play Scream Tracker module in games 3172 and demos. It uses an intermediate format between STM and S3M and 3173 comes with a tool converting STM modules to STX. 3174 "STMIK" was written by PSI of Future Crew, a.k.a. Sami Tammilehto. 3175 3176`load_s3m' 3177 This loader recognizes "ScreamTracker 3" modules. This version was 3178 a huge improvement over the original "ScreamTracker". It supported 3179 32 channels, up to 99 instruments, and a large choice of effects. 3180 "ScreamTracker 3" was written by PSI of Future Crew, a.k.a. Sami 3181 Tammilehto, and released in 1994. 3182 3183`load_ult' 3184 This loader recognizes "UltraTracker" modules. They are mostly 3185 similar to Protracker modules, but support two effects per channel. 3186 "UltraTracker" was written by MAS of Prophecy, a.k.a. Marc Andre 3187 Schallehn, and released in 1993. 3188 3189`load_umx' 3190 This loader recognizes the modules in "umx" files from games like 3191 "Unreal", "DeusEx", etc. To libmikmod, UMX is just a container and 3192 the real music format may be one of "ScreamTracker 3", "Impulse 3193 Tracker", "FastTracker 2", or possibly a "Protracker" compatible 3194 one. 3195 3196`load_uni' 3197 This loader recognizes "UNIMOD" modules. This is the internal 3198 format used by MikMod and APlayer. Use of this format is 3199 discouraged, this loader being provided for completeness. 3200 3201`load_xm' 3202 This loader recognizes "FastTracker 2" modules. This format was 3203 designed from scratch, instead of creating yet another Protracker 3204 variation. It was the first format using instruments as well as 3205 samples, and envelopes for finer effects. 3206 FastTracker 2 was written by Fredrik Huss and Magnus Hogdahl, and 3207 released in 1994. 3208 3209 3210File: mikmod.info, Node: Sample Loaders, Next: Driver Reference, Prev: Module Loaders, Up: Loader Reference 3211 32124.5.2 Sample Loaders 3213-------------------- 3214 3215Currently, the only file type than can be loaded as a sample is the RIFF 3216WAVE file. Stereo or compressed WAVE files are not supported yet. 3217 3218 3219File: mikmod.info, Node: Driver Reference, Next: Network Drivers, Prev: Sample Loaders, Up: Library Reference 3220 32214.6 Driver Reference 3222==================== 3223 3224* Menu: 3225 3226* Network Drivers:: 3227* Hardware Drivers:: 3228* Disk Writer Drivers:: 3229* Other Drivers:: 3230 3231 3232File: mikmod.info, Node: Network Drivers, Next: Hardware Drivers, Prev: Driver Reference, Up: Driver Reference 3233 32344.6.1 Network Drivers 3235--------------------- 3236 3237These drivers send the generated sound over the network to a server 3238program, which sends the sound to the real sound hardware. The server 3239program can be on the same machine than your program, but MikMod does 3240not have access to the hardware. Network drivers only support software 3241mixing. 3242 3243`drv_AF' 3244 This driver works with the "Digital AudioFile" library. 3245 Start the server on the machine you want, set its hostname in the 3246 `AUDIOFILE' environment variable, and MikMod is ready to send it 3247 sound. 3248 3249`drv_esd' 3250 This driver works with the "Enlightened Sound Daemon". 3251 Start the esd daemon on the machine you want, set its hostname in 3252 the `ESPEAKER' environment variable, and MikMod is ready to send 3253 it sound. 3254 3255`drv_nas' 3256 This driver works with the "Network Audio System". 3257 Start the nas server on the machine you want, and set its hostname 3258 with the `server' driver command line argument. 3259 3260`drv_pulseaudio' 3261 This driver works with the "PulseAudio" server. 3262 Start the pulseaudio server on the machine you want, set the 3263 server name with `server' and the device name with `sink' driver 3264 command line arguments. Without the optional `server' and `sink' 3265 arguments, the driver leaves the server:device decision to the 3266 pulseaudio library defaults. 3267 3268 3269File: mikmod.info, Node: Hardware Drivers, Next: Disk Writer Drivers, Prev: Network Drivers, Up: Driver Reference 3270 32714.6.2 Hardware Drivers 3272---------------------- 3273 3274These drivers access to the sound hardware of the machine they run on. 3275Depending on your Unix flavor, you'll end with one or more drivers from 3276this list: 3277 3278`drv_ahi' 3279 This driver is only available under AmigaOS and its variants like 3280 MorphOS and AROS, and it outputs to native Amiga AHI device. 3281 This driver only supports software mixing. 3282 3283`drv_aix' 3284 This driver is only available under AIX, and access its audio 3285 device. 3286 This driver only supports software mixing. 3287 3288`drv_alsa' 3289 This driver is only available under Linux, and requires the ALSA 3290 driver to be compiled for your current kernel. 3291 This driver only supports software mixing, but a future version of 3292 the driver might be able to use the hardware capabilities of some 3293 sound cards. 3294 3295`drv_dart' 3296 This driver is only available under OS/2 version 3 and higher 3297 (Warp), and uses the "Direct Audio Real-Time" interface. 3298 This driver only supports software mixing. 3299 3300`drv_dc' 3301 This driver is only for the Dreamcast platform, and outputs a 3302 stream to the AICA SPU of a Dreamcast. 3303 This driver only supports software mixing. This driver is not 3304 tested yet. 3305 3306`drv_ds' 3307 This driver is only available under WIN32, and uses the 3308 "DirectSound" api. 3309 This driver only supports software mixing. 3310 3311`drv_gp32' 3312 This driver is only for the GP32 platform, and uses the "GP32" api. 3313 This driver only supports software mixing. This driver is not 3314 tested yet. 3315 3316`drv_hp' 3317 This driver is only available under HP-UX, and access its audio 3318 device. 3319 This driver only supports software mixing. 3320 3321`drv_mac' 3322 This driver is only available under MacOS, and uses the "Sound 3323 Manager". 3324 This driver supports the Classic and Carbon environments, and does 3325 only software mixing. 3326 3327`drv_openal' 3328 This driver is available for all platforms where "OpenAL" is 3329 supported, and uses the "OpenAL" api. 3330 This driver only supports software mixing. 3331 3332`drv_os2' 3333 This driver is only available under OS/2 version 3 and higher 3334 (Warp), and OS/2 2.x with MMPM/2. 3335 This driver only supports software mixing. 3336 3337`drv_osles' 3338 This driver is only available under Android and uses OpenSL ES. 3339 This driver only supports software mixing. 3340 3341`drv_oss' 3342 This driver is available under any Unix with the Open Sound System 3343 drivers installed. Linux and FreeBSD also come with the OSS/Lite 3344 driver (the non-commercial version of OSS) and can make use of 3345 this driver. 3346 This driver only supports software mixing. 3347 3348`drv_osx' 3349 This driver is available under MacOS X and Darwin, and uses the 3350 "CoreAudio" interface. 3351 This driver only supports software mixing. 3352 3353`drv_psp' 3354 This driver is only for the Playstation Portable platform, and is 3355 not tested yet. 3356 This driver only supports software mixing. 3357 3358`drv_sam9407' 3359 This driver is only available under Linux, and requires the Linux 3360 sam9407 driver to be compiled for your current kernel. 3361 This driver only supports hardware mixing. 3362 3363`drv_sb' 3364 This driver is only available under DOS, and supports the 3365 SoundBlaster/Pro/16/AWE32. 3366 This driver only supports hardware mixing. This driver needs to be 3367 tested. 3368 3369`drv_sdl' 3370 This driver is available for all platforms where "SDL" is 3371 supported, and uses the "Simple DirectMedia Layer" apis. 3372 This driver only supports software mixing. 3373 3374`drv_sgi' 3375 This driver is only available under IRIX, and uses the SGI audio 3376 library. 3377 This driver only supports software mixing. 3378 3379`drv_sndio' 3380 This driver is only available under OpenBSD and uses the "sndio" 3381 interface. 3382 This driver only supports software mixing. 3383 3384`drv_sun' 3385 This driver is only available under Unices which implement 3386 SunOS-like audio device interfaces, that is, SunOS, Solaris, 3387 NetBSD and OpenBSD. 3388 This driver only supports software mixing. 3389 3390`drv_ultra' 3391 This driver is available under Linux, and requires the Linux 3392 Ultrasound driver (the ancestor of ALSA) to be compiled for your 3393 current kernel. This driver is also available under DOS/DJGPP and 3394 OS/2. 3395 This driver only supports hardware mixing. The DOS/DJGPP and OS/2 3396 parts needs to be tested. 3397 3398`drv_win' 3399 This driver is only available under WIN32, and uses the 3400 "multimedia API". 3401 This driver only supports software mixing. 3402 3403`drv_wss' 3404 This driver is only available under DOS, and supports Windows 3405 Sound System compatible sound cards. 3406 This driver only supports software mixing. This driver needs to be 3407 tested. 3408 3409`drv_xaudio2' 3410 This driver is only available under Windows XP and newer Windows 3411 versions and uses the "XAudio2" 2.7 or 2.8 apis. 3412 This driver only supports software mixing. 3413 3414 3415File: mikmod.info, Node: Disk Writer Drivers, Next: Other Drivers, Prev: Hardware Drivers, Up: Driver Reference 3416 34174.6.3 Disk Writer Drivers 3418------------------------- 3419 3420These drivers work on any machine, since the generated sound is not 3421sent to hardware, but written in a file. Disk writer drivers only 3422support software mixing. 3423 3424`drv_aiff' 3425 This driver outputs the sound data in a AIFF (Audio Interchange 3426 File Format) file by default named `music.aiff' or `music.aif' on 3427 win32/dos in the current directory. 3428 3429`drv_raw' 3430 This driver outputs the sound data in a file by default named 3431 `music.raw' in the current directory. The file has no header and 3432 only contains the sound output. 3433 3434`drv_wav' 3435 This driver outputs the sound data in a RIFF WAVE file by default 3436 named `music.wav' in the current directory. 3437 3438 3439File: mikmod.info, Node: Other Drivers, Prev: Disk Writer Drivers, Up: Driver Reference 3440 34414.6.4 Other Drivers 3442------------------- 3443 3444These drivers are of little interest, but are handy sometimes. 3445 3446`drv_stdout' 3447 This driver outputs the sound data to the program's standard 3448 output. To avoid inconvenience, the data will not be output if the 3449 standard output is a terminal, thus you have to pipe it through 3450 another command or to redirect it to a file. Using this driver 3451 and redirecting to a file is equivalent to using the `drv_raw' 3452 disk writer. 3453 This driver only supports software mixing. 3454 3455`drv_pipe' 3456 This driver pipes the sound data to a command (which must be given 3457 in the driver commandline, via `MikMod_Init'). 3458 This driver only supports software mixing. 3459 3460`drv_nos' 3461 This driver doesn't produce sound at all, and will work on any 3462 machine. 3463 Since it does not have to produce sound, it supports both hardware 3464 and software mixing, with as many hardware voices as you like. 3465 3466 3467File: mikmod.info, Node: Index, Next: Function Index, Prev: Library Reference, Up: Top 3468 34695 Index 3470******* 3471 3472* Menu: 3473 3474* Function Index:: 3475* Type and Variable Index:: 3476 3477 3478File: mikmod.info, Node: Function Index, Next: Type and Variable Index, Prev: Index, Up: Index 3479 3480Function Index 3481************** 3482 3483�[index�] 3484* Menu: 3485 3486* MikMod_Active: Library Core Functions. 3487 (line 9) 3488* MikMod_DisableOutput: Library Core Functions. 3489 (line 30) 3490* MikMod_EnableOutput: Library Core Functions. 3491 (line 44) 3492* MikMod_Exit: Library Core Functions. 3493 (line 65) 3494* MikMod_GetVersion: Library Core Functions. 3495 (line 76) 3496* MikMod_InfoDriver: Library Core Functions. 3497 (line 88) 3498* MikMod_InfoLoader: Library Core Functions. 3499 (line 106) 3500* MikMod_Init: Library Core Functions. 3501 (line 124) 3502* MikMod_InitThreads: Library Core Functions. 3503 (line 153) 3504* MikMod_Lock: Library Core Functions. 3505 (line 174) 3506* MikMod_RegisterAllDrivers: Library Core Functions. 3507 (line 195) 3508* MikMod_RegisterAllLoaders: Library Core Functions. 3509 (line 205) 3510* MikMod_RegisterDriver: Library Core Functions. 3511 (line 215) 3512* MikMod_RegisterErrorHandler: Library Core Functions. 3513 (line 237) 3514* MikMod_RegisterLoader: Library Core Functions. 3515 (line 261) 3516* MikMod_RegisterPlayer: Library Core Functions. 3517 (line 285) 3518* MikMod_Reset: Library Core Functions. 3519 (line 333) 3520* MikMod_SetNumVoices: Library Core Functions. 3521 (line 362) 3522* MikMod_strerror: Library Core Functions. 3523 (line 439) 3524* MikMod_Unlock: Library Core Functions. 3525 (line 395) 3526* MikMod_Update: Library Core Functions. 3527 (line 416) 3528* Player_Active: Module Player Functions. 3529 (line 9) 3530* Player_Free: Module Player Functions. 3531 (line 31) 3532* Player_GetChannelVoice: Module Player Functions. 3533 (line 46) 3534* Player_GetModule: Module Player Functions. 3535 (line 69) 3536* Player_Load: Module Player Functions. 3537 (line 83) 3538* Player_LoadFP: Module Player Functions. 3539 (line 123) 3540* Player_LoadTitle: Module Player Functions. 3541 (line 164) 3542* Player_LoadTitleFP: Module Player Functions. 3543 (line 186) 3544* Player_Mute: Module Player Functions. 3545 (line 208) 3546* Player_Muted: Module Player Functions. 3547 (line 238) 3548* Player_NextPosition: Module Player Functions. 3549 (line 259) 3550* Player_Paused: Module Player Functions. 3551 (line 273) 3552* Player_PrevPosition: Module Player Functions. 3553 (line 290) 3554* Player_SetPosition: Module Player Functions. 3555 (line 304) 3556* Player_SetSpeed: Module Player Functions. 3557 (line 322) 3558* Player_SetTempo: Module Player Functions. 3559 (line 336) 3560* Player_SetVolume: Module Player Functions. 3561 (line 350) 3562* Player_Start: Module Player Functions. 3563 (line 361) 3564* Player_Stop: Module Player Functions. 3565 (line 379) 3566* Player_ToggleMute: Module Player Functions. 3567 (line 389) 3568* Player_TogglePause: Module Player Functions. 3569 (line 419) 3570* Player_Unmute: Module Player Functions. 3571 (line 433) 3572* Sample_Free: Sample Functions. (line 9) 3573* Sample_Load: Sample Functions. (line 23) 3574* Sample_LoadFP: Sample Functions. (line 41) 3575* Sample_Play: Sample Functions. (line 63) 3576* Voice_GetFrequency: Voice Functions. (line 9) 3577* Voice_GetPanning: Voice Functions. (line 28) 3578* Voice_GetPosition: Voice Functions. (line 48) 3579* Voice_GetVolume: Voice Functions. (line 73) 3580* Voice_Play: Voice Functions. (line 92) 3581* Voice_RealVolume: Voice Functions. (line 119) 3582* Voice_SetFrequency: Voice Functions. (line 145) 3583* Voice_SetPanning: Voice Functions. (line 163) 3584* Voice_SetVolume: Voice Functions. (line 186) 3585* Voice_Stop: Voice Functions. (line 204) 3586* Voice_Stopped: Voice Functions. (line 225) 3587 3588 3589File: mikmod.info, Node: Type and Variable Index, Prev: Function Index, Up: Index 3590 3591Type and Variable Index 3592*********************** 3593 3594�[index�] 3595* Menu: 3596 3597* INSTRUMENT: Structure Reference. (line 224) 3598* md_device: Variable Reference. (line 62) 3599* md_driver: Variable Reference. (line 68) 3600* md_mixfreq: Variable Reference. (line 76) 3601* md_mode: Variable Reference. (line 83) 3602* md_musicvolume: Variable Reference. (line 33) 3603* md_pansep: Variable Reference. (line 35) 3604* md_reverb: Variable Reference. (line 40) 3605* md_sndfxvolume: Variable Reference. (line 45) 3606* md_volume: Variable Reference. (line 49) 3607* MDRIVER: Structure Reference. (line 13) 3608* MikMod_critical: Variable Reference. (line 14) 3609* MikMod_errno: Variable Reference. (line 12) 3610* MODULE: Structure Reference. (line 37) 3611* MREADER: Structure Reference. (line 306) 3612* MWRITER: Structure Reference. (line 343) 3613* SAMPLE: Structure Reference. (line 234) 3614 3615 3616 3617Tag Table: 3618Node: Top998 3619Node: Introduction1450 3620Node: Tutorial2329 3621Node: MikMod Concepts3059 3622Node: A Skeleton Program4024 3623Node: Playing Modules5582 3624Node: Playing Sound Effects9384 3625Node: More Sound Effects13354 3626Ref: More Sound Effects-Footnote-115782 3627Node: Using the Library15968 3628Node: Library Version16369 3629Node: Type Definitions18544 3630Node: Error Handling19595 3631Node: Library Initialization21231 3632Ref: Library Initialization-Footnote-124466 3633Node: Samples and Voice Control24570 3634Node: Modules and Player Control27432 3635Node: Loading Data from Memory31732 3636Node: Library Reference32650 3637Node: Variable Reference33082 3638Node: Structure Reference38132 3639Node: Error Reference49345 3640Ref: Error Reference-Footnote-162649 3641Node: Function Reference62810 3642Node: Library Core Functions63205 3643Node: Module Player Functions75845 3644Node: Sample Functions87298 3645Node: Voice Functions89476 3646Node: Loader Reference95868 3647Node: Module Loaders96076 3648Node: Sample Loaders103065 3649Node: Driver Reference103363 3650Node: Network Drivers103616 3651Node: Hardware Drivers105089 3652Node: Disk Writer Drivers110081 3653Node: Other Drivers110922 3654Node: Index111962 3655Node: Function Index112130 3656Node: Type and Variable Index119336 3657 3658End Tag Table 3659