Main SDL Mixer encapsulation class.
class MIX
| AllocateChannels() | Sets or read the number of mixing channels. |
| ChannelFinished() | Requests onChannelFinished callbacks to be called when a channel finishes playing. |
| CloseAudio() | Turn off the MIX module. |
| Compiled_Version() | Determine the version used to compile this SDL mixer module. |
| ExpireChannel() | Requests to the playback on a channel after some time. |
| FadeOutChannel() | Requests to the playback on a channel after some, fading out in the meanwhile. |
| FadeOutMusic() | Fades out the music channel. |
| FadingChannel() | Returns the number of channels currently fading out. |
| GetSynchroValue() | Returns Syncro value for MICMOD library (Mod, STM, IT, etc.). |
| HaltChannel() | Stops the playback on channel. |
| HaltMusic() | Immediately halts the music. |
| HookMusicFinished() | Requests onMusicFinished callbacks to be called when the music finishes playing. |
| Linked_Version() | Determine the version of the library that is currently linked. |
| LoadMUS() | Loads a music file. |
| LoadWAV() | Loads an audio file. |
| OpenAudio() | Initialize the MIX module. |
| Pause() | Pauses a channel. |
| PauseMusic() | Pause the music. |
| Paused() | Returns the number of paused channels. |
| PausedMusic() | Determines if the music is currently playing but paused. |
| Playing() | Returns the number of playing channels. |
| PlayingMusic() | Checks if the music is playing or not. |
| QuerySpec() | Queries the settings that have been used to open the SDL mixer system. |
| Resume() | Resumes a paused a channel. |
| ResumeMusic() | Resumes a paused music. |
| RewindMusic() | Reposition music stream at the start of the currently played music. |
| SetMusicCMD() | Sets the command used to load some kind of music. |
| SetMusicPosition() | Changes the position in the music stream. |
| SetSynchroValue() | Changes the Synchro value for MICMOD library (Mod, STM, IT, etc.). |
| Volume() | Sets or read current volume setting for given channel. |
| VolumeMusic() | Sets or read the global music volume. |
Main SDL Mixer encapsulation class.
This class is the namespace for MIX functions of the SDL module. It contains the extensions provided by Falcon on the sdlmix module.
Sets or read the number of mixing channels.
MIX.AllocateChannels( [channels] )
| channels | Number the number of channels to be set, or nil to get current channel count. |
| Returns: | Current channel count (before eventually changing it). |
This method sets up mixing sound effect channels. Channels can be independently pre-processed and mixed at different volumes on the background music.
This method can be called multiple times, even with sounds playing. If numchans is less than the current number of channels, then the higher channels will be stopped, freed, and therefore not mixed any longer. It's probably not a good idea to change the size 1000 times a second though.
Note: Passing in zero WILL free all mixing channels, however music will still play.
Channels are also the place where MixChunk instances can be played.
Requests onChannelFinished callbacks to be called when a channel finishes playing.
MIX.ChannelFinished( active )
| active | Set to true to generate messages, false to prevent it. |
This method works differently with respect to SDL_Mixer C API counterpart. If activated, all channels terminating will generate a callback request on the SDL message queue. This will cause a waiting Falcon SDLEventHandler class to receive an onChannelFinished( chnum ) callback (where chnum is the number of the channel that has finished playing).
Turn off the MIX module.
MIX.CloseAudio( )
This method turns off he mixing facility. It must becalled the same number of times MIX.OpenAudio has been called.
After the mix system has been effectively turned off, it is possible to re-init it.
Also, the MIX module doesn't require MIX.CloseAudio() to be called before the SDL system is exited.
Determine the version used to compile this SDL mixer module.
MIX.Compiled_Version( )
| Returns: | a three element array containing the major, minor and fix versions. |
Requests to the playback on a channel after some time.
MIX.ExpireChannel( channel, time )
| channel | The channel to be stopped (-1 for all). |
| time | Number of seconds and fractions after which the timeout expires. |
| Returns: | Number of channels scheduled for stopping. |
Note: The time parameter is in Falcon sleep format (i.e. 1.2 is 1.2 seconds).
Requests to the playback on a channel after some, fading out in the meanwhile.
MIX.FadeOutChannel( channel, time )
| channel | The channel to be faded (-1 for all). |
| time | Number of seconds and fractions after which the timeout expires. |
| Returns: | Number of channel fading out. |
Note: The time parameter is in Falcon sleep format (i.e. 1.2 is 1.2 seconds).
Fades out the music channel.
MIX.FadeOutMusic( fadeOut )
| fadeOut | Duration of the fadeout time in seconds and fractions. |
Returns the number of channels currently fading out.
MIX.FadingChannel( channel )
| channel | Channel ID that is to be queried (-1 for all). |
| Returns: | One of the MIX.FADING_IN, MIX.FADING_OUT or MIX.NO_FADING values |
Channel to test whether it is faiding out or not.
Returns Syncro value for MICMOD library (Mod, STM, IT, etc.).
MIX.GetSynchroValue( )
| Returns: | Current Synchro value. |
See the SDL_mixer API description.
Stops the playback on channel.
MIX.HaltChannel( channel )
| channel | The channel to be stopped (-1 for all). |
You can resume an already playing channel, and no error is raised for resuming an unexisting channel.
Immediately halts the music.
MIX.HaltMusic( )
(If it's playing...)
Requests onMusicFinished callbacks to be called when the music finishes playing.
MIX.HookMusicFinished( active )
| active | Set to true to generate messages, false to prevent it. |
This method works differently with respect to SDL_Mixer C API counterpart. If activated, the music terminating or being terminated will generate a callback request on the SDL message queue. This will cause a waiting Falcon SDLEventHandler class to receive an onMusicFinished() callback.
Determine the version of the library that is currently linked.
MIX.Linked_Version( )
| Returns: | a three element array containing the major, minor and fix versions. |
This function determines the version of the SDL_mixer library that is running on the system. As long as the interface is the same, it may be different from the version used to compile this module.
Loads a music file.
MIX.LoadMUS( file )
| file | A file name or a stream to be loaded. | ||
| Returns: | On success, an instance of MixMusic class. | ||
| Raises: |
|
The file parameter may be either a stream pointing to the beginning of a valid SDL_mixer supported file, or it may be a filename.
If it's a string, the file parameter is not parsed through the Falcon I/O system; it's directly sent to the underlying SDL function, so a valid locally available file specification must be provided.
Note: This may change in future (we may use Falcon metafile services also to resolve file names).
Loads an audio file.
MIX.LoadWAV( file )
| file | A file name or a stream to be loaded. | ||
| Returns: | On success, an instance of MixChunk class. | ||
| Raises: |
|
The file parameter may be either a stream pointing to the beginning of a valid SDL_mixer supported file, or it may be a filename.
If it's a string, the file parameter is not parsed through the Falcon I/O system; it's directly sent to the underlying SDL function, so a valid locally available file specification must be provided.
Note: This may change in future (we may use Falcon metafile services also to resolve file names).
Initialize the MIX module.
MIX.OpenAudio( frequency, format, channels, chunksize )
| frequency | Output sampling frequency in samples per second (Hz). you might use MIX.DEFAULT_FREQUENCY(22050) since that is a good value for most games. | ||
| format | Output sample format; it's one of the AUDIO enums. | ||
| channels | Number of sound channels in output. Set to 2 for stereo, 1 for mono. This has nothing to do with mixing channels. | ||
| chunksize | Bytes used per output sample. | ||
| Raises: |
|
It is necessary to call SDL.Init with SDL.INIT_AUDIO option.
Pauses a channel.
MIX.Pause( channel )
| channel | The channel to be paused (-1 for all). |
You can pause an already paused channel, and no error is raised for pausing an unexisting channel.
Pause the music.
MIX.PauseMusic( )
The music can later be resumed from the current position though MIX.ResumeMusic.
Returns the number of paused channels.
MIX.Paused( [channel] )
| channel | Channel ID that is to be queried (-1 for all). |
| Returns: | 1 if the desired channel is paused, or the number of paused channels channel is not passed or -1. |
Channel to test whether it is paused or not. Passing -1 in the channel parameter, or not passing it at all, will tell you how many channels are paused.
Determines if the music is currently playing but paused.
MIX.PausedMusic( )
| Returns: | True if the music is paused. |
Returns the number of playing channels.
MIX.Playing( [channel] )
| channel | Channel ID that is to be queried (-1 for all). |
| Returns: | 1 if the desired channel is playing, or the number of playing channels channel is not passed or -1. |
Channel to test whether it is playing or not. Passing -1 in the channel parameter, or not passing it at all, will tell you how many channels are playing. Note: Does not check if the channel has been paused.
Checks if the music is playing or not.
MIX.PlayingMusic( )
| Returns: | True if it's playing, false otherwhise. |
Returns true also if the music is paused.
Queries the settings that have been used to open the SDL mixer system.
MIX.QuerySpec( )
| Returns: | A vector with three numeric values representing the frequency, the audio format and the channel numbers that were set on init. | ||
| Raises: |
|
Resumes a paused a channel.
MIX.Resume( channel )
| channel | The channel to be resumed (-1 for all). |
You can resume an already playing channel, and no error is raised for resuming an unexisting channel.
Resumes a paused music.
MIX.ResumeMusic( )
Reposition music stream at the start of the currently played music.
MIX.RewindMusic( )
Sets the command used to load some kind of music.
MIX.SetMusicCMD( )
| Raises: |
|
See the SDL_mixer api description.
Changes the position in the music stream.
MIX.SetMusicPosition( position )
| position | The relative position (0 to 1). | ||
| Raises: |
|
Changes the Synchro value for MICMOD library (Mod, STM, IT, etc.).
MIX.SetSynchroValue( value )
| value | New synchro value. |
See the SDL_mixer API description.
Sets or read current volume setting for given channel.
MIX.Volume( channel, [volume] )
| channel | Target channel ID |
| volume | The new volume to be set (pass nothing, nil or < 0 to read). |
| Returns: | Current volume level (prior to setting). |
This method convigure the overall volume setting mixing sound effect channels.
Pass -1 as channel to set the volume in all the channels.
Sets or read the global music volume.
MIX.VolumeMusic( [volume] )
| volume | The new volume setting. |
| Returns: | Previous volume value. |
The volume setting goes from 0 to 127. If the volume parameter is not given, nil or -1, the setting is just read without being changed.