GNU Info

(mikmod.info)Module Player Functions

---

Next: Sample Functions Prev: Library Core Functions Up: Function Reference

---

Enter node , (file) or (file)node

Module Player Functions
-----------------------

Player_Active
.............

   `BOOL Player_Active(void)'
Description
     This function returns whether the module player is active or not.

Result
0
     No module is playing.

nonzero
     A module is currently playing.

Notes
     This function will still report that the player is active if the
     playing module is paused.

See also
     `Player_Paused', `Player_TogglePause', `Player_Start',
     `Player_Stop'

Player_Free
...........

   `void Player_Free(MODULE* module)'
Description
     This function stops the module if it is playing and unloads it
     from memory.

Parameters
module
     The module to free.

See also
     `Player_Load', `Player_LoadFP'.

Player_GetChannelVoice
......................

   `int Player_GetChannelVoice(UBYTE channel)'
Description
     This function determines the voice corresponding to the specified
     module channel.

Parameters
channel
     The module channel to use.

Result
     The number of the voice corresponding to the module channel.

Notes
     If the module channel has NNAs, the number will correspond to the
     main channel voice.

See also
     `Voice_SetPanning', `Voice_SetVolume', `Player_Mute',
     `Player_ToggleMute', `Player_Unmute'.

Player_GetModule
................

   `MODULE* Player_GetModule(void)'
Description
     This function returns the module currently being played.

Result
     A pointer to the `MODULE' being played, or `NULL' if no module is
     playing.

See also
     `Player_Stop', `Player_Start'.

Player_Load
...........

   `MODULE* Player_Load(CHAR* filename, int maxchan, BOOL curious)'
Description
     This function loads a music module.

Parameters
filename
     The name of the module file.

maxchan
     The maximum number of channels the song is allowed to request from
     the mixer.

curious
     The curiosity level to use.

Result
     A pointer to a `MODULE' structure, or `NULL' if an error occurs.

Notes
     If the curiosity level is set to zero, the module will be loaded
     normally.  However, if it is nonzero, the following things occur:
        * pattern positions occurring after the "end of song" marker in
          S3M and IT modules are loaded, and the end of song is set to
          the last position.

        * hidden extra patterns are searched in MOD modules, and if
          found, played after the last "official" pattern.

        * MED modules with synthsounds are loaded without causing the
          `MMERR_MED_SYNTHSAMPLES', and synthsounds are mapped to an
          empty sample.

See also
     `Player_Free', `Player_LoadFP', `Player_LoadTitle',
     `Player_LoadTitleFP', `Player_Start'.

Player_LoadFP
.............

   `MODULE* Player_LoadFP(FILE* file, int maxchan, BOOL curious)'
Description
     This function loads a music module.

Parameters
file
     An open file, at the position where the module starts.

maxchan
     The maximum number of channels the song is allowed to request from
     the mixer.

curious
     The curiosity level to use.

Result
     A pointer to a `MODULE' structure, or `NULL' if an error occurs.

Notes
     The file is left open, at the same position as before the function
     call.
     If the curiosity level is set to zero, the module will be loaded
     normally.  However, if it is nonzero, the following things occur:
        * pattern positions occurring after the "end of song" marker in
          S3M and IT modules are loaded, and the end of song is set to
          the last position.

        * hidden extra patterns are searched in MOD modules, and if
          found, played after the last "official" pattern.

        * MED modules with synthsounds are loaded without causing the
          `MMERR_MED_SYNTHSAMPLES', and synthsounds are mapped to an
          empty sample.

See also
     `Player_Free', `Player_Load', `Player_LoadTitle',
     `Player_LoadTitleFP', `Player_Start'.

Player_LoadTitle
................

   `MODULE* Player_LoadTitle(CHAR* filename)'
Description
     This function retrieves the title of a module file.

Parameters
filename
     The name of the module file.

Result
     A pointer to the song title, or `NULL' if either the module has no
     title or an error has occurred.

Notes
     The title buffer is created with `malloc'; the caller must free it
     when it is no longer necessary.

See also
     `Player_Load', `Player_LoadFP', `Player_LoadTitleFP'.

Player_LoadTitleFP
..................

   `MODULE* Player_LoadTitleFP(FILE* file)'
Description
     This function retrieves the title of a module file.

Parameters
file
     An open file, at the position where the module starts.

Result
     A pointer to the song title, or `NULL' if either the module has no
     title or an error has occurred.

Notes
     The title buffer is created with `malloc'; the caller must free it
     when it is no longer necessary.

See also
     `Player_Load', `Player_LoadFP', `Player_LoadTitle'.

Player_Mute
...........

   `void Player_Mute(SLONG operation, ...)'
Description
     This function mutes a single module channel, or a range of module
     channels.

Parameters
operation
     Either the number of a module channel to mute (starting from
     zero), or an operation code. In the latter case, two extra
     parameters are needed to determine the range of channels.

Notes
     If the operation is `MUTE_INCLUSIVE', the two channel numbers
     delimit the range and are part of the range ; otherwise, if the
     operation is `MUTE_EXCLUSIVE', they are outside of the range.

Example
              /* mute channel 10 */
              Player_Mute(10);
              /* mute channels 2 to 5 */
              Player_Mute(MUTE_INCLUSIVE, 2, 5);
              /* mute channels 7 to 9 */
              Player_Mute(MUTE_EXCLUSIVE, 6, 10);

See also
     `Player_Muted', `Player_ToggleMute', `Player_Unmute'.

Player_Muted
............

   `BOOL Player_Muted(UBYTE channel)'
Description
     This function determines whether a module channel is muted or not.

Parameters
channel
     The module channel to test (starting from zero).

Result
0
     The channel is not muted.

1
     The channel is muted.

See also
     `Player_Mute', `Player_ToggleMute', `Player_Unmute'.

Player_NextPosition
...................

   `void Player_NextPosition(void)'
Description
     This function jumps to the next position in the module.

Notes
     All playing samples and active song voices are cut to avoid
     hanging notes.

See also
     `Player_PrevPosition', `Player_SetPosition'.

Player_Paused
.............

   `BOOL Player_Paused(void)'
Description
     This function determines whether the module is paused or not.

Result
0
     The module is not paused.

1
     The module is paused.

See also
     `Player_TogglePause'.

Player_PrevPosition
...................

   `void Player_PrevPosition(void)'
Description
     This function jumps to the previous position in the module.

Notes
     All playing samples and active song voices are cut to avoid
     hanging notes.

See also
     `Player_NextPosition', `Player_SetPosition'.

Player_SetPosition
..................

   `void Player_SetPosition(UWORD position)'
Description
     This function jumps to the specified position in the module.

Parameters
position
     The pattern position to jump to.

Notes
     All playing samples and active song voices are cut to avoid
     hanging notes.

See also
     `Player_NextPosition', `Player_PrevPosition'.

Player_SetSpeed
...............

   `void Player_SetSpeed(UWORD speed)'
Description
     This function sets the module speed.

Parameters
speed
     The new module speed, in the range 1-32.

See also
     `Player_SetTempo'.

Player_SetTempo
...............

   `void Player_SetTempo(UWORD tempo)'
Description
     This function sets the module tempo.

Parameters
tempo
     The new module tempo, in the range 32-255.

See also
     `Player_SetSpeed'.

Player_SetVolume
................

   `void Player_SetVolume(SWORD volume)'
Description
     This function sets the module volume.

Parameters
volume
     The new overall module playback volume, in the range 0-128.

Player_Start
............

   `void Player_Start(MODULE* module)'
Description
     This function starts the specified module playback.

Parameters
module
     The module to play.

Notes
     If another module is playing, it will be stopped and the new
     module will play.

See also
     `Player_Stop'.

Player_Stop
...........

   `void Player_Stop(void)'
Description
     This function stops the currently playing module.

See also
     `Player_Start'.

Player_ToggleMute
.................

   `void Player_ToggleMute(SLONG operation, ...)'
Description
     This function changes the muted status of a single module channel,
     or a range of module channels.

Parameters
operation
     Either the number of a module channel to work on (starting from
     zero), or an operation code. In the latter case, two extra
     parameters are needed to determine the range of channels.

Notes
     If the operation is `MUTE_INCLUSIVE', the two channel numbers
     delimit the range and are part of the range ; otherwise, if the
     operation is `MUTE_EXCLUSIVE', they are outside of the range.

Example
              /* toggle mute on channel 10 */
              Player_ToggleMute(10);
              /* toggle mute on channels 2 to 5 */
              Player_ToggleMute(MUTE_INCLUSIVE, 2, 5);
              /* toggle mute on channels 7 to 9 */
              Player_ToggleMute(MUTE_EXCLUSIVE, 6, 10);

See also
     `Player_Mute', `Player_Muted', `Player_Unmute'.

Player_TogglePause
..................

   `void Player_TogglePause(void)'
Description
     This function toggles the playing/paused status of the module.

Notes
     Calls to `Player_xx' functions still have effect when the module
     is paused.

See also
     `Player_Paused', `Player_Start', `Player_Stop'.

Player_Unmute
.............

   `void Player_Unmute(SLONG operation, ...)'
Description
     This function unmutes a single module channel, or a range of
     module channels.

Parameters
operation
     Either the number of a module channel to unmute (starting from
     zero), or an operation code. In the latter case, two extra
     parameters are needed to determine the range of channels.

Notes
     If the operation is `MUTE_INCLUSIVE', the two channel numbers
     delimit the range and are part of the range ; otherwise, if the
     operation is `MUTE_EXCLUSIVE', they are outside of the range.

Example
              /* unmute channel 10 */
              Player_Unmute(10);
              /* unmute channels 2 to 5 */
              Player_Unmute(MUTE_INCLUSIVE, 2, 5);
              /* unmute channels 7 to 9 */
              Player_Unmute(MUTE_EXCLUSIVE, 6, 10);

See also
     `Player_Mute', `Player_Muted', `Player_ToggleMute'.