This document was created in 800x600 videomode.
Excuses for our bad English we know it sucks!
---------------------------------------------------------------------------------------------------------------
(2.3 Plans for the next release
(3.1 What files should be where
(3.2 A short description of the three examples
bool CALLBACK InstallSound(int voices)
void CALLBACK RemoveSound(void)
bool CALLBACK MusicIsPlaying(void)
SAMPLE* CALLBACK LoadSample(char* filename)
void CALLBACK UnloadSample(SAMPLE* sample)
int CALLBACK PlaySample(SAMPLE* sample,bool repeat=false)
void CALLBACK StopSample(int voice)
void CALLBACK AdjustSample(SAMPLE* spl,int volume=-1,int pan=-1,int frequency=-1)
AX_MIDI* CALLBACK LoadMidi(char* filename)
void CALLBACK UnloadMusic(AX_MIDI* midi)
void CALLBACK PlayMusic(AX_MIDI* music,int times_to_play=1)
AX_MODULE* CALLBACK LoadMod(char* filename)
void CALLBACK UnloadMusic(AX_MODULE *)
void CALLBACK PlayMusic(AX_MODULE *,int times_to_repeat=1)
char* CALLBACK ModName(AX_MODULE*)
Licensing:
1.) Free license: This software may be used freely for creating software that is free of charge ie. freeware and public domain, as long as its documentation or the software itself includes the text "This software is based on part of the works of Crocopeep Softwares Audio Xtreme library."
2.) Shareware license: This audio library can be registered for royalty free use in sharware. Shareware in this case is software that is distributed without fee but costs money to register. The fee for this is $29 usd (250 SEK for Swedish citizens). This fee gives lifetime rights to create shareware, royalfree applications with the ax library until and including the release of Audio Xtreme v1.0
3) Comercial license: Same as Shareware license but it might be used for applications that is released comercially _and_ shareware applications. This alternative also includes e-mail support. The fee for this is $59
3).Professional license: Same as commercial license + it includes cd-rom with full source code of the library. The fee for this is $149. Contact Crocopeep Software on the email adress on the bottom of this page for further information.
--------------------------------------------------------------------------------------------------------
Audioxtreme is a library for MicroSoft(r) Visual C++ 5.0 or better. It is created to access parts of Microsoft(r) DirectSound and DirectMusic in high level, easy to use functions. With just a few lines of code you can play music of types MOD, XM, S3M and MID where the midi player uses DirectMusic and its software synth so that midi music sounds good and the same on all systems. It also supports loading and playing of Samples of type WAV and AU. It can use up to 32 voices of polyphony at the same time for modules and samples + independent voices for MIDI playback. You need DirectX v6.1 installed on your system for all functions to work properly.
This is the first public release of Audio Xtreme and it probably has some bugs (we do know of some minor bugs, see below).
2.3 Plans for the next release
*The mod effect arpeggios fine-tune bug as described below will be corrected.
*It will load more sample types than WAV & AU and it will support diffrential compressed types of wav and au. Types that might be included is IFF and VOC.
*More functions for altering samples such as echo, chorus etc. If this is implemented to the next version depends on how many bug reports we recive on this beta.
*Music volume functions.
*Loads of optimizations.
*MOD effect 0x00, arpeggio doesnt work well if its finetuned
------------------------------------------------------------------------------------------------
3.1 What files should be where
After unzipping this package copy the axtreme03b.dll to your \windows\system folder. Copy the audioxtreme.h from the include folder to the compiler include folder. If you want to you can copy the axtreme03b.lib import library to your compilers lib folder but you dont have to since you have to add this libfile to your projects and the compiler will find it anyway.3.2 A short description of the three examples
In the samples folder of this distribution there are three samples. The subfolder contains a pre-build executable for each sample if you doesnt want to build them yourself. They are ready to run! If you want to build them yourself there are workspace files for each example included as well.
*example1: shows how to load, play and release a sample
*example 2:shows how to load, play and release a module
*example 3:shows how to use the midi player
Note that all of the functions aviable in this library is not used in the samples but they are quite straightforward.
-----------------------------------------------------------------------------------------------------------------
bool CALLBACK InstallSound(int voices)
This function is the first function to call before trying to play any samples or any module. Voices is the number of voices that can be played at the same time. For example if you want to play a 6-channel module and want 3 voices for sound fx send 9. It returns true on success and false on failure.
void CALLBACK RemoveSound(void)
If installSound() is called the program has to call this function before exiting to release some resources.
bool CALLBACK MusicIsPlaying(void)
This function returns true if any midi or module is currently playing else it returns false.
SAMPLE* CALLBACK LoadSample(char* filename)
SAMPLE is a type declared in audioxtreme.h and is used to hold a sample (hmmm...). This function automatically allocates a sample structure so that it can be used like this: SAMPLE* my_sample=LoadSample("my_wavefile.wav"); The type of the sample can be Standard windows pcm wavefiles and sun/NeXT au files. Diffrential compressed au-files are not accepted in this version of audio xtreme but u-law compressed, a-law compressed and pcm-au:s are supported. This function returns NULL on failure. Note: the loader does NOT accept files by its suffix, it parses the file to accept it.
void CALLBACK UnloadSample(SAMPLE* sample)
For every sample loaded with LoadSample() this function has to be called to release the memory the sample occupies. SAMPLE* is the pointer gotten through the LoadSample function.
int CALLBACK PlaySample(SAMPLE* sample,bool repeat=false)
Just guess what this one does? Yes it plays an sample previously loaded with LoadSample. It automatically finds an unused voice and plays it on that voice. It also chooses voices that do not disturbe module playback. The return value is the voice the sample was played at. You only need to store the return value if you want to be able to stop the sample. Repeat, which is false by default, makes the sound repeat until stoped. If you set this to true I guess you want to store the return value......
void CALLBACK StopSample(int voice)
This stops a sample before it has finished playing. It takes the return value of PlaySample as its only argument.
void CALLBACK AdjustSample(SAMPLE* spl,int volume=-1,int pan=-1,int frequency=-1)
This function adjusts the proporties for a previously loaded sample. It will _not_ affect any samples that already begun playing, only the ones played after this function is called. It can adjust volume, pan and frequency of the sample. Set values that should remain unchanged to -1. spl is a pointer to the sample that should be adjusted. Volume ranges from 0-255 and is a linear volume. Pan ranges from 0-255 where 0 beeing far left, 128 middle and 255 far right. frequency ranges from 100-100.000 and is the playback frequency for the sample.
This has to be called before using the midi player. It returns true on success and false on failure. Initializing the midi player might take a second or two. NOTE: you dont have to call InstallSound() to use the midi player.
If you has called InitMidi() in your application you have to call this to release some resources.
AX_MIDI* CALLBACK LoadMidi(char* filename)
AX_MIDI is a type defined in the audioxtreme.h headerfile. This function automatically allocates an AX_MIDI structure and returns a pointer to it. The filetype loaded has to be a midi file (*.mid) using the general midi standar. If it sounds good in the windows media player it sounds good here. This function returns NULL on failure.
void CALLBACK UnloadMusic(AX_MIDI* midi)
For each sucessfull call to LoadMidi() there has to ba a call to UnloadMusic with a pointer to that AX_MIDI structure to release its resources.
void CALLBACK PlayMusic(AX_MIDI* music,int times_to_play=1)
This function starts playing a midi song loaded with LoadMidi() using the Microsoft(r) Softwaresynthesizer included in DirectMusic. If you send the argumen times_to_play the music will repeat that number of times. Valid values for times_to_play is 1 - 2^30.
This function will stop any module or midi music currently playing.
AX_MODULE* CALLBACK LoadMod(char* filename)
AX_MODULE is a type defined in the audioxtreme.h headerfile. This function automatically allocates an AX_MIDI structure and returns a pointer to it. The filetype loaded has to be a mod file, screamtracker file or fasttracker xtended module (*.mod, *.s3m, *.xm). This function returns NULL on failure. There is no support for the old 15-instrument modules yet. If you want to load such modules just load them into a modern tracker and save them again and they will be converted.
void CALLBACK UnloadMusic(AX_MODULE *)
For each successfull call to LoadModule() this has to be called to release the module. THIS FUNCTION HAS TO BE CALLED BEFORE RemoveSound(). The pointer argument is a pointer to the module.
void CALLBACK PlayMusic(AX_MODULE *,int times_to_repeat=1)
This does the same as PlayMusic for MIDI files (se above) but it takes a valid pointer to a AX_MODULE structure, created throuk LoadModule(); The voices use for module playback will always be 0-(number of module channels-1), which means a 16 channel module will play at voices 0-15. Sample playback will not play on thoose channels when a module is playing.
char* CALLBACK ModName(AX_MODULE*)
This return a char pointer to the name of the module as saved in the module file. Nothing more nothing less.
Can be gotten through rob.p@swipnet.se
Please make the subject ax-license for licensing queries, ax-bugs for bug reports.
PLEASE SUPPORT THE SHAREWARE IDEOLOGY
Snailmail adresses for registration has to be requested through this email. Until the next release of Audio Xtreme, release 04b.