org.lwjgl.fmod3
Class FMusic

java.lang.Object
  extended by org.lwjgl.fmod3.FMusic

public class FMusic
extends java.lang.Object


Version:
$Revision: 2383 $ $Id: FMusic.java 2383 2006-06-23 08:14:49Z matzon $
Author:
Brian Matzon

Field Summary
static int FMUSIC_TYPE_FSB
          FMOD Sample Bank file
static int FMUSIC_TYPE_IT
          Impulse Tracker
static int FMUSIC_TYPE_MIDI
          MIDI file
static int FMUSIC_TYPE_MOD
          Protracker / Fasttracker
static int FMUSIC_TYPE_NONE
          No song being played
static int FMUSIC_TYPE_S3M
          ScreamTracker 3
static int FMUSIC_TYPE_XM
          FastTracker 2
 
Constructor Summary
FMusic()
           
 
Method Summary
static boolean FMUSIC_FreeSong(FMusicModule module)
          Frees memory allocated for a song and removes it from the FMUSIC system
static int FMUSIC_GetBPM(FMusicModule module)
          Returns the song's current BPM.
static int FMUSIC_GetGlobalVolume(FMusicModule module)
          Returns the song's current global volume Remarks GLOBAL volume is not the same as MASTER volume.
static int FMUSIC_GetMasterVolume(FMusicModule module)
          Returns the song's current master volume
static java.lang.String FMUSIC_GetName(FMusicModule module)
          Returns the name of the song set by the composer.
static int FMUSIC_GetNumChannels(FMusicModule module)
          Returns the number of channels within this songs pattern data
static int FMUSIC_GetNumInstruments(FMusicModule module)
          Returns the number of instruments contained in this song.
static int FMUSIC_GetNumOrders(FMusicModule module)
          Returns the number of orders in this song
static int FMUSIC_GetNumPatterns(FMusicModule module)
          Returns the number of patterns contained in this song.
static int FMUSIC_GetNumSamples(FMusicModule module)
          Returns the number of samples contained in this song.
static int FMUSIC_GetOpenState(FMusicModule module)
          If a mod is opened with FSOUND_NONBLOCKING, this function returns the state of the opening mod.
static int FMUSIC_GetOrder(FMusicModule module)
          Returns the song's current order number
static int FMUSIC_GetPattern(FMusicModule module)
          Returns the song's current pattern number
static int FMUSIC_GetPatternLength(FMusicModule module, int orderno)
          Returns the the length in rows of the pattern for the specified order number
static boolean FMUSIC_GetPaused(FMusicModule module)
          Returns whether song is currently paused or not
static int FMUSIC_GetRealChannel(FMusicModule module, int modchannel)
          Returns the real FSOUND channel playing based on the mod's FMUSIC channel Remarks Note FMUSIC mod playback only allocates a real channel on a mod channel the first time an instrument is played.
static int FMUSIC_GetRow(FMusicModule module)
          Returns the song's current row number Remarks This value is latency adjusted by default, and returns the number you are hearing, not the 'mix-time' value.
static FSoundSample FMUSIC_GetSample(FMusicModule module, int sampno)
          Returns a reference to a sample inside a module.
static int FMUSIC_GetSpeed(FMusicModule module)
          Returns the song's current speed.
static int FMUSIC_GetTime(FMusicModule module)
          Returns the time in milliseconds since the song was started.
static int FMUSIC_GetType(FMusicModule module)
          Returns the format type a song
static java.nio.ByteBuffer FMUSIC_GetUserData(FMusicModule module, int capacity)
          Retrieves the data set by FMUSIC_SetUserData
static boolean FMUSIC_IsFinished(FMusicModule module)
          Returns whether the song has completed playing, or when the last order has finished playing.
static boolean FMUSIC_IsPlaying(FMusicModule module)
          Returns whether the song is currently playing or not.
static FMusicModule FMUSIC_LoadSong(java.lang.String name)
          To load a module or bank with a given filename.
static FMusicModule FMUSIC_LoadSongEx(java.nio.ByteBuffer data, int mode, java.nio.IntBuffer sampleList)
          To load a module or bank with a given filename.
static FMusicModule FMUSIC_LoadSongEx(java.lang.String name, int offset, int length, int mode, java.nio.IntBuffer sampleList)
           
static boolean FMUSIC_OptimizeChannels(FMusicModule module, int maxchannels, int minvolume)
          This function helps with channel usage.
static boolean FMUSIC_PlaySong(FMusicModule module)
          Starts a song playing
static boolean FMUSIC_SetInstCallback(FMusicModule module, FMusicCallback callback, int instrument)
          Sets a user callback to occur every time a instrument is played, triggered from a MOD, S3M, XM or IT file.
static boolean FMUSIC_SetLooping(FMusicModule module, boolean looping)
          Sets looping mode for midi and mod files Remarks Defaults to TRUE.
static boolean FMUSIC_SetMasterSpeed(FMusicModule module, float speed)
          Sets a songs master speed scale, so that the song can be sped up or slowed down.
static boolean FMUSIC_SetMasterVolume(FMusicModule module, int volume)
          Sets a songs master volume.
static boolean FMUSIC_SetOrder(FMusicModule module, int order)
          Sets a songs order position / current playing position.
static boolean FMUSIC_SetOrderCallback(FMusicModule module, FMusicCallback callback, int orderstep)
          Sets a user callback to occur on every order divisible by the orderstep parameter, played from a MOD, S3M, XM or IT file Remarks It is important to note that this callback will be called from directly WITHIN the mixer / music update thread, therefore it is imperative that whatever you do from this callback be extremely efficient.
static boolean FMUSIC_SetPanSeperation(FMusicModule module, float pansep)
          Sets the master pan seperation for a module
static boolean FMUSIC_SetPaused(FMusicModule module, boolean pause)
          Pauses a song
static boolean FMUSIC_SetReverb(boolean reverb)
          Turns on reverb for MIDI/RMI files.
static boolean FMUSIC_SetRowCallback(FMusicModule module, FMusicCallback callback, int rowstep)
          Sets a user callback to occur on every row divisible by the rowstep parameter, played from a MOD, S3M, XM or IT file.
static boolean FMUSIC_SetSample(FMusicModule module, int sampno, FSoundSample sptr)
          Replaces a mod's sample with a sample definition specified.
static boolean FMUSIC_SetUserData(FMusicModule module, java.nio.ByteBuffer userdata)
          Sets a user defined value to store with the music file to be retrieved later.
static boolean FMUSIC_SetZxxCallback(FMusicModule module, FMusicCallback callback)
          Sets a user callback for any Zxx commands encountered in an S3M, XM or IT file.
static void FMUSIC_StopAllSongs()
          Stops all songs from playing.
static boolean FMUSIC_StopSong(FMusicModule module)
          Stops a song from playing.
static void music_instcallback(long modulehandle, int param)
          This is the callback rutine called by the native implementation whenever a register callback is notified.
static void music_ordercallback(long modulehandle, int param)
          This is the callback rutine called by the native implementation whenever a register callback is notified.
static void music_rowcallback(long modulehandle, int param)
          This is the callback rutine called by the native implementation whenever a register callback is notified.
static void music_zxxcallback(long modulehandle, int param)
          This is the callback rutine called by the native implementation whenever a register callback is notified.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FMUSIC_TYPE_NONE

public static final int FMUSIC_TYPE_NONE
No song being played

See Also:
Constant Field Values

FMUSIC_TYPE_MOD

public static final int FMUSIC_TYPE_MOD
Protracker / Fasttracker

See Also:
Constant Field Values

FMUSIC_TYPE_S3M

public static final int FMUSIC_TYPE_S3M
ScreamTracker 3

See Also:
Constant Field Values

FMUSIC_TYPE_XM

public static final int FMUSIC_TYPE_XM
FastTracker 2

See Also:
Constant Field Values

FMUSIC_TYPE_IT

public static final int FMUSIC_TYPE_IT
Impulse Tracker

See Also:
Constant Field Values

FMUSIC_TYPE_MIDI

public static final int FMUSIC_TYPE_MIDI
MIDI file

See Also:
Constant Field Values

FMUSIC_TYPE_FSB

public static final int FMUSIC_TYPE_FSB
FMOD Sample Bank file

See Also:
Constant Field Values
Constructor Detail

FMusic

public FMusic()
Method Detail

FMUSIC_LoadSong

public static FMusicModule FMUSIC_LoadSong(java.lang.String name)
To load a module or bank with a given filename. FMUSIC Supports loading of - .MOD (protracker/fasttracker modules) - .S3M (screamtracker 3 modules) - .XM (fasttracker 2 modules) - .IT (impulse tracker modules) - .MID (MIDI files) - .RMI (MIDI files) - .SGT (DirectMusic segment files) - .FSB (FMOD Sample Bank files)

Parameters:
name - Filename of module to load
Returns:
On success, a FMusicModule instance is returned. On failure, Null is returned

FMUSIC_LoadSongEx

public static FMusicModule FMUSIC_LoadSongEx(java.nio.ByteBuffer data,
                                             int mode,
                                             java.nio.IntBuffer sampleList)
To load a module or bank with a given filename. FMUSIC Supports loading of - .MOD (protracker/fasttracker modules) - .S3M (screamtracker 3 modules) - .XM (fasttracker 2 modules) - .IT (impulse tracker modules) - .MID (MIDI files) - .RMI (MIDI files) - .SGT (DirectMusic segment files) - .FSB (FMOD Sample Bank files)

Loading a song from a memory handle is dangerous in one respect, if the data is corrupted or truncated, then FMUSIC could crash internally trying to load it. On PlayStation 2 the data and length pointer must be 16 byte aligned for DMA purposes. The samplelist and samplelistnum parameters are useful for limiting the amount of data fmod loads. This feature is for the FSB format only. It is especially useful if you have a bank of sounds and want to randomize the loading a bit by telling which sounds to load with random values, and consequently which not to load. On PlayStation 2, samplelistnum has a limit of 1536 entries.

Parameters:
data - containing song to load. On PlayStation 2 data must be 16 byte aligned if loading from memory
mode - Mode for opening song. With module files, only FSOUND_LOADMEMORY, FSOUND_NONBLOCKING, FSOUND_LOOP_NORMAL, or FSOUND_LOOP_OFF are supported. For FSB files, FSOUND_2D, FSOUND_HW3D, FSOUND_FORCEMONO also work
sampleList - Optional. Buffer of sample indicies to load. Leave as Null if you want all samples to be loaded (default behaviour). See Remarks for more on this
Returns:
On success, a FMusicModule instance is returned. On failure, Null is returned

FMUSIC_LoadSongEx

public static FMusicModule FMUSIC_LoadSongEx(java.lang.String name,
                                             int offset,
                                             int length,
                                             int mode,
                                             java.nio.IntBuffer sampleList)
Parameters:
name - of song
offset - Optional. 0 by default. If > 0, this value is used to specify an offset in a file, so fmod will seek before opening
length - Optional. 0 by default. If > 0, this value is used to specify the length of a memory block when using FSOUND_LOADMEMORY, or it is the length of a file or file segment if the offset parameter is used. On PlayStation 2 this must be 16 byte aligned for memory loading
mode - Mode for opening song. With module files, only FSOUND_LOADMEMORY, FSOUND_NONBLOCKING, FSOUND_LOOP_NORMAL, or FSOUND_LOOP_OFF are supported. For FSB files, FSOUND_2D, FSOUND_HW3D, FSOUND_FORCEMONO also work
sampleList - Optional. Buffer of sample indicies to load. Leave as Null if you want all samples to be loaded (default behaviour). See Remarks for more on this
Returns:
On success, a FMusicModule instance is returned. On failure, Null is returned
See Also:
#FMUSIC_LoadSongEx(ByteBuffer, int, int, int, IntBuffer)

FMUSIC_GetOpenState

public static int FMUSIC_GetOpenState(FMusicModule module)
If a mod is opened with FSOUND_NONBLOCKING, this function returns the state of the opening mod.

Parameters:
module - Module to get the open state from
Returns:
0 = mod is opened and ready. -1 = mod handle passed in is invalid. -2 = mod is still opening -3 = mod failed to open. (file not found, out of memory or other error).

FMUSIC_FreeSong

public static boolean FMUSIC_FreeSong(FMusicModule module)
Frees memory allocated for a song and removes it from the FMUSIC system

Parameters:
module - Module to be freed
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_PlaySong

public static boolean FMUSIC_PlaySong(FMusicModule module)
Starts a song playing

Parameters:
module - Module to be played
Returns:
true if module succeeded playing. false if module failed playing

FMUSIC_StopSong

public static boolean FMUSIC_StopSong(FMusicModule module)
Stops a song from playing.

Parameters:
module - Module to be stopped
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_StopAllSongs

public static void FMUSIC_StopAllSongs()
Stops all songs from playing. This is useful if you have multiple songs playing at once and want a quick way to stop them


FMUSIC_SetZxxCallback

public static boolean FMUSIC_SetZxxCallback(FMusicModule module,
                                            FMusicCallback callback)
Sets a user callback for any Zxx commands encountered in an S3M, XM or IT file.

Remarks The value passed into the param parameter of the callback is the xx value specified in the Zxx command by the musician ------------ It is important to note that this callback will be called from directly WITHIN the mixer / music update thread, therefore it is imperative that whatever you do from this callback be extremely efficient. If the routine takes too long then breakups in the sound will occur, or it will basically stop mixing until you return from the function. This sort of function is usually best for just setting a flag, or do some simple variable manipulation, and then exiting, letting your main thread do what it needs to based on these flags or variables. ------------ This callback is LATENCY adjusted, so that the callback happens when you HEAR the sound, not when it is mixed, for accurate synchronization. Use FSOUND_INIT_DONTLATENCYADJUST if you want it to be called back at mix time, which is useful if you want to control the music interactively. ------------ Note : This function is not supported with the MIDI format.

Parameters:
module - Module to set the callback for
callback - The callback function you supply to get called upon execution of a Zxx command
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_SetRowCallback

public static boolean FMUSIC_SetRowCallback(FMusicModule module,
                                            FMusicCallback callback,
                                            int rowstep)
Sets a user callback to occur on every row divisible by the rowstep parameter, played from a MOD, S3M, XM or IT file.

Remarks It is important to note that this callback will be called from directly WITHIN the mixer / music update thread, therefore it is imperative that whatever you do from this callback be extremely efficient. If the routine takes too long then breakups in the sound will occur, or it will basically stop mixing until you return from the function. This sort of function is usually best for just setting a flag, or do some simple variable manipulation, and then exiting, letting your main thread do what it needs to based on these flags or variables. ------------ This callback is LATENCY adjusted, so that the callback happens when you HEAR the sound, not when it is mixed, for accurate synchronization. Use FSOUND_INIT_DONTLATENCYADJUST if you want it to be called back at mix time, which is useful if you want to control the music interactively. ------------ Note : This function is not supported with the MIDI format.

Parameters:
module - Module to set the callback for
callback - The callback function you supply to get called
rowstep - Call the callback every multiple of this number of rows
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_SetOrderCallback

public static boolean FMUSIC_SetOrderCallback(FMusicModule module,
                                              FMusicCallback callback,
                                              int orderstep)
Sets a user callback to occur on every order divisible by the orderstep parameter, played from a MOD, S3M, XM or IT file

Remarks It is important to note that this callback will be called from directly WITHIN the mixer / music update thread, therefore it is imperative that whatever you do from this callback be extremely efficient. If the routine takes too long then breakups in the sound will occur, or it will basically stop mixing until you return from the function. This sort of function is usually best for just setting a flag, or do some simple variable manipulation, and then exiting, letting your main thread do what it needs to based on these flags or variables. ------------ This callback is LATENCY adjusted, so that the callback happens when you HEAR the sound, not when it is mixed, for accurate synchronization. Use FSOUND_INIT_DONTLATENCYADJUST if you want it to be called back at mix time, which is useful if you want to control the music interactively. ------------ Note : This function is not supported with the MIDI format.

Parameters:
module - Module to set the callback for
callback - The callback function you supply to get called
orderstep - Call the callback every multiple of this number of orders
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_SetInstCallback

public static boolean FMUSIC_SetInstCallback(FMusicModule module,
                                             FMusicCallback callback,
                                             int instrument)
Sets a user callback to occur every time a instrument is played, triggered from a MOD, S3M, XM or IT file.

Remarks It is important to note that this callback will be called from directly WITHIN the mixer / music update thread, therefore it is imperative that whatever you do from this callback be extremely efficient. If the routine takes too long then breakups in the sound will occur, or it will basically stop mixing until you return from the function. This sort of function is usually best for just setting a flag, or do some simple variable manipulation, and then exiting, letting your main thread do what it needs to based on these flags or variables. ------------ This callback is LATENCY adjusted, so that the callback happens when you HEAR the sound, not when it is mixed, for accurate synchronization. Use FSOUND_INIT_DONTLATENCYADJUST if you want it to be called back at mix time, which is useful if you want to control the music interactively. ------------ Note : This function is not supported with the MIDI format.

Parameters:
module - Module set the callback for
callback - The callback function you supply to get called
instrument - Call the callback when this instrument number is triggered
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_SetSample

public static boolean FMUSIC_SetSample(FMusicModule module,
                                       int sampno,
                                       FSoundSample sptr)
Replaces a mod's sample with a sample definition specified.

Remarks Because of the instrument nature of some formats like XM, this function lists all the samples in order of instruments and their subsamples. ie if instrument 1 has 2 samples and instrument 2 contains 3 samples, then sampno in this case would be 0 and 1 for instrument 1's samples, and 2,3 & 4 for instrument 2's samples. ------------ FMOD does not free the existing mod sample that you may be overwriting. If you do overwrite an existing handle, it may be lost, and you may incur a memory leak. It is a good idea to free the existing sample first before overwriting it. ------------ Important: For PlayStation 2, this function has to do a blocking query to the IOP, and can take significantly more time than a standard non blocking fmod function. This means it is best to cache the pointers for samples while loading, and not call this function in realtime. ------------ This function is not supported with the MIDI format.

Parameters:
module - Module to set the sample for.
sampno - index to sample inside module
sptr - sample definition to replace mod sample
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_SetUserData

public static boolean FMUSIC_SetUserData(FMusicModule module,
                                         java.nio.ByteBuffer userdata)
Sets a user defined value to store with the music file to be retrieved later.

Parameters:
module - Module to set user data for
userdata - Value to store with music object
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_OptimizeChannels

public static boolean FMUSIC_OptimizeChannels(FMusicModule module,
                                              int maxchannels,
                                              int minvolume)
This function helps with channel usage. If you are desperate for channels, and you are prepared to let the music routines drop a few channels, then calling this function can help. It basically doesnt try to play any new sounds if a certain channel limit is being played (including sound effects), and the new sound is below a certain specified volume. ie. You set it to maxchannels = 16, and minvolume = 0x10. In this case, the mod will play normally as long as the total number of channels being played inclusing sound effefcts is below 16 (see FSOUND_GetChannelsPlaying). If the number of channels playing exceeds 16 (through a change in the music, or extra sound effects are spawned, then sounds with a musician specified volume of less than 0x10 will be ignored. The volume is based on volume column/default volume/volume set commands in the mod. master volume, envelope volumes etc are not taken into account (this gives more control over how it will work from the tracker).

Remarks maxchannels will default to the number of channels allocated by FSOUND, so this will never happen by default. minvolume will default to 0, so it will always succeed by default. To see how many channels are currently being MIXED, use FSOUND_GetChannelsPlaying. As a musician mentioned to me once, most of his default volumes are set fairly high, and any low end volumes are usually echoes etc, and can afford to be dropped. ------------ Note : This function is not supported with the MIDI format.

Parameters:
module - Module to set channel/volume optimization settings
maxchannels - Channel count to be mixed before fmusic starts to drop channels from the song
minvolume - If maxchannels is exceeded, then music channels with volumes below this value will not be played. Range is 0-64. This is the value the tracker displays. All trackers use 0-64
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_SetReverb

public static boolean FMUSIC_SetReverb(boolean reverb)
Turns on reverb for MIDI/RMI files.

Remarks Reverb may be enabled through software emulation in the future for MOD based formats.

Parameters:
reverb - Set to true to turn MIDI reverb on, false to turn MIDI reverb off
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_SetLooping

public static boolean FMUSIC_SetLooping(FMusicModule module,
                                        boolean looping)
Sets looping mode for midi and mod files

Remarks Defaults to TRUE. To disable looping you must call this function using FALSE as the parameter. For midi files this only takes effect before FMUSIC_PlaySong is called. For mod files this can be called at any time including during playback.

Parameters:
module - Module to set looping for
looping - Set to true to make it loop forever, or false to only have it play once
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_SetOrder

public static boolean FMUSIC_SetOrder(FMusicModule module,
                                      int order)
Sets a songs order position / current playing position.

Remarks Note : This function is not supported with the MIDI format.

Parameters:
module - Module to have its order changed
order - Order number to jump to
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_SetPaused

public static boolean FMUSIC_SetPaused(FMusicModule module,
                                       boolean pause)
Pauses a song

Parameters:
module - Module to be paused/unpaused
pause - true - song should be PAUSED, false - song should be UNPAUSED
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_SetMasterVolume

public static boolean FMUSIC_SetMasterVolume(FMusicModule module,
                                             int volume)
Sets a songs master volume.

Parameters:
module - Module to have its master volume set
volume - value from 0-256. 0 = silence, 256 = full volume
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_SetMasterSpeed

public static boolean FMUSIC_SetMasterSpeed(FMusicModule module,
                                            float speed)
Sets a songs master speed scale, so that the song can be sped up or slowed down.

Parameters:
module - Module to have its speed scale set
speed - Speed scale for song. 1.0 is default. Minimum is 0 (stopped), maximum is 10.0
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_SetPanSeperation

public static boolean FMUSIC_SetPanSeperation(FMusicModule module,
                                              float pansep)
Sets the master pan seperation for a module

Parameters:
module - Module to set pan seperation for
pansep - The pan scale. 1.0 means full pan seperation, 0 means mono
Returns:
On success, true is returned. On failure, false is returned

FMUSIC_GetName

public static java.lang.String FMUSIC_GetName(FMusicModule module)
Returns the name of the song set by the composer. With MIDI format, the filename is returned

Parameters:
module - Module to retrieve name from
Returns:
On success, the name of the song is returned. On failure, Null is returned

FMUSIC_GetType

public static int FMUSIC_GetType(FMusicModule module)
Returns the format type a song

Parameters:
module - Module to retrieve type from
Returns:
FMusicType constant, FMUSIC_TYPE_NONE on failure

FMUSIC_GetNumOrders

public static int FMUSIC_GetNumOrders(FMusicModule module)
Returns the number of orders in this song

Parameters:
module - Module to retrieve number of orders from
Returns:
On success, the number of orders in this song is returned. On failure, 0 is returned

FMUSIC_GetNumPatterns

public static int FMUSIC_GetNumPatterns(FMusicModule module)
Returns the number of patterns contained in this song.

Parameters:
module - Module to retrieve number of patterns from
Returns:
On success, the number of patterns contained in this song is returned. On failure, 0 is returned

FMUSIC_GetNumInstruments

public static int FMUSIC_GetNumInstruments(FMusicModule module)
Returns the number of instruments contained in this song.

Parameters:
module - Module to retrieve number of instruments from
Returns:
On success, the number of instruments contained in this song is returned. On failure, 0 is returned.

FMUSIC_GetNumSamples

public static int FMUSIC_GetNumSamples(FMusicModule module)
Returns the number of samples contained in this song.

Parameters:
module - Module to retrieve number of samples
Returns:
Number of samples contained in this song. On failure, 0 is returned.

FMUSIC_GetNumChannels

public static int FMUSIC_GetNumChannels(FMusicModule module)
Returns the number of channels within this songs pattern data

Parameters:
module - Module to retrieve number of channels from
Returns:
Number of channels within this songs pattern data. On failure, 0 is returned.

FMUSIC_GetSample

public static FSoundSample FMUSIC_GetSample(FMusicModule module,
                                            int sampno)
Returns a reference to a sample inside a module. Once you have access to the module's sample, you can do a lot of things to it, including locking and modifying the data within; using the FSOUND_Sample_ functionality

Remarks Because of the instrument nature of some formats like XM, this function lists all the samples in order of instruments and their subsamples. ie if instrument 1 has 2 samples and instrument 2 contains 3 samples, then sampno in this case would be 0 and 1 for instrument 1's samples, and 2,3 & 4 for instrument 2's samples.

Parameters:
module - Module to retrieve a sample handle from
sampno - index to sample inside module
Returns:
On success, a valid sample is returned. On failure, Null is returned.

FMUSIC_GetPatternLength

public static int FMUSIC_GetPatternLength(FMusicModule module,
                                          int orderno)
Returns the the length in rows of the pattern for the specified order number

Parameters:
module - Module to get pattern lenght from
orderno - pattern at specified order
Returns:
On success, the songs pattern length at the specified order is returned. On failure, 0 is returned

FMUSIC_IsFinished

public static boolean FMUSIC_IsFinished(FMusicModule module)
Returns whether the song has completed playing, or when the last order has finished playing. This stays set even if the song loops.

Parameters:
module - Module that you want check if finished or not
Returns:
true if module has finished playing. false if module has not finished playing.

FMUSIC_IsPlaying

public static boolean FMUSIC_IsPlaying(FMusicModule module)
Returns whether the song is currently playing or not.

Parameters:
module - Module to retrieve name from
Returns:
true Song is playing. false Song is stopped.

FMUSIC_GetMasterVolume

public static int FMUSIC_GetMasterVolume(FMusicModule module)
Returns the song's current master volume

Parameters:
module - Module to retrieve song master volume from
Returns:
On success, the song's current master volume, from 0 (silence) to 256 (full volume) is returned. On failure, -1 is returned.

FMUSIC_GetGlobalVolume

public static int FMUSIC_GetGlobalVolume(FMusicModule module)
Returns the song's current global volume

Remarks GLOBAL volume is not the same as MASTER volume. GLOBAL volume is an internal overall volume which can be altered by the song itself (ie there might be commands to fade in a particular part of the song by scaling all the volumes in the song up slowly from nothing). GLOBAL volume is different to MASTER volume in that the song can modify without your permission, whereas MASTER volume is an overall scalar that you can control. For general use, MASTER volume is more useful, but you may want to reset a song's GLOBAL volume at certain times in the song. (for example the song might have faded out by using GLOBAL volume and you want to reset it)

Parameters:
module - Module to retrieve song global volume from
Returns:
Songs current global volume, from 0 (silence) to the maximum value determined by the music format. Global volume maximums are different in respect to each format, they range from 64 to 256. On failure, -1 is returned.

FMUSIC_GetOrder

public static int FMUSIC_GetOrder(FMusicModule module)
Returns the song's current order number

Parameters:
module - Module to retrieve current order number from
Returns:
On success, the song's current order number is returned.On failure, -1 is returned

FMUSIC_GetPattern

public static int FMUSIC_GetPattern(FMusicModule module)
Returns the song's current pattern number

Parameters:
module - Module to retrieve current pattern number from
Returns:
On success, The song's current pattern number is returned. On failure, -1 is returned

FMUSIC_GetSpeed

public static int FMUSIC_GetSpeed(FMusicModule module)
Returns the song's current speed.

Parameters:
module - Module to retrieve current song speed from
Returns:
On success, The song's current speed is returned. On failure, -1 is returned

FMUSIC_GetBPM

public static int FMUSIC_GetBPM(FMusicModule module)
Returns the song's current BPM.

Parameters:
module - Module to retrieve current song BPM from
Returns:
On success, song's current BPM is returned. On failure, -1 is returned

FMUSIC_GetRow

public static int FMUSIC_GetRow(FMusicModule module)
Returns the song's current row number

Remarks This value is latency adjusted by default, and returns the number you are hearing, not the 'mix-time' value. Use FSOUND_INIT_DONTLATENCYADJUST if you want the value at mix time, which is useful if you want to control the music interactively, or from a DSP callback.

Parameters:
module - Module to retrieve current row from
Returns:
On success, the song's current row number is returned. On failure, -1 is returned

FMUSIC_GetPaused

public static boolean FMUSIC_GetPaused(FMusicModule module)
Returns whether song is currently paused or not

Parameters:
module - Module to get paused flag from
Returns:
On success, true is returned to say the song is currently paused. On failure, false is returned to say the song is NOT currently paused

FMUSIC_GetTime

public static int FMUSIC_GetTime(FMusicModule module)
Returns the time in milliseconds since the song was started. This is useful for synchronizing purposes becuase it will be exactly the same every time, and it is reliably retriggered upon starting the song. Trying to synchronize using other windows timers can lead to varying results, and inexact performance. This fixes that problem by actually using the number of samples sent to the soundcard as a reference

Remarks This value is latency adjusted by default, and returns the number you are hearing, not the 'mix-time' value. Use FSOUND_INIT_DONTLATENCYADJUST if you want the value at mix time, which is useful if you want to control the music interactively, or from a DSP callback

Parameters:
module - Module to the song to get time from
Returns:
On success, the time played in milliseconds is returned. On failure, -1 is returned

FMUSIC_GetRealChannel

public static int FMUSIC_GetRealChannel(FMusicModule module,
                                        int modchannel)
Returns the real FSOUND channel playing based on the mod's FMUSIC channel

Remarks Note FMUSIC mod playback only allocates a real channel on a mod channel the first time an instrument is played. NNA's will not register. This function only returns the primary real channel for the mod channel.

Parameters:
module - Module to the song
modchannel - channel index, to query the real channel from
Returns:
On success, the channel index for the respective mod channel is returned. On failure, -1 is returned

FMUSIC_GetUserData

public static java.nio.ByteBuffer FMUSIC_GetUserData(FMusicModule module,
                                                     int capacity)
Retrieves the data set by FMUSIC_SetUserData

Parameters:
module - Module to get the open state from
Returns:
On success, userdata set by FMUSIC_SetUserData is returned. On failure, Null is returned.

music_instcallback

public static void music_instcallback(long modulehandle,
                                      int param)
This is the callback rutine called by the native implementation whenever a register callback is notified.

Parameters:
handle - Handle to native object being monitored
param - parameter passed to callback

music_ordercallback

public static void music_ordercallback(long modulehandle,
                                       int param)
This is the callback rutine called by the native implementation whenever a register callback is notified.

Parameters:
handle - Handle to native object being monitored
param - parameter passed to callback

music_rowcallback

public static void music_rowcallback(long modulehandle,
                                     int param)
This is the callback rutine called by the native implementation whenever a register callback is notified.

Parameters:
handle - Handle to native object being monitored
param - parameter passed to callback

music_zxxcallback

public static void music_zxxcallback(long modulehandle,
                                     int param)
This is the callback rutine called by the native implementation whenever a register callback is notified.

Parameters:
handle - Handle to native object being monitored
param - parameter passed to callback


Copyright © 2002-2006 lwjgl.org. All Rights Reserved.