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