MSequence Struct Reference


Public Methods

struct MSequence* MSequence_ctor (struct MSequence *ptr_msequence, char *sz_file_name)
bool MSequence_is_sane (struct MSequence *ptr_msequence)
void MSequence_play (struct MSequence *ptr_msequence)
void MSequence_stop (struct MSequence *ptr_msequence)
bool MSequence_is_playing (struct MSequence *ptr_msequence)
int MSequence_get_curr_pos (struct MSequence *ptr_msequence)
bool MSequence_load (struct MSequence *ptr_msequence, struct Input *ptr_input)
void MSequence_dtor (struct MSequence *ptr_msequence, int memory_flag)
void MSequence_play_background (struct MSequence *ptr_msequence)
void MSequence_global_mute (bool mute_flag)
void MSequence_mute_foreground (bool mute_flag)
void MSequence_mute_background (bool mute_flag)

Detailed Description

The music sequence object. Allows the end user to manipulate the music-playing on Cybiko computers. You must call MSequence_ctor before use and MSequence_dtor after use.

See also:
MSequence_ctor, MSequence_dtor, Sound, Music and Vibration

Member Function Documentation

struct MSequence * MSequence_ctor ( struct MSequence * ptr_msequence,
char * sz_file_name )
 

Creates a music sequence from a specified resource (file) name.

Parameters:
ptr_msequence   A pointer to a MSequence structure.
sz_file_name   The music seqence's resource file name (*.mus)
Returns:
A pointer to the initialized music sequence 
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if( MSequence_is_sane( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       // Loops background music.
       if( !MSequence_is_playing ( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...

void MSequence_dtor ( struct MSequence * ptr_msequence,
int memory_flag )
 

Destructor.
Performs cleanup.

Parameters:
ptr_msequence   A pointer to the initialized music sequence.
memory_flag   Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None 
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if( MSequence_is_sane( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       // Loops background music.
       if( !MSequence_is_playing ( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY.

int MSequence_get_curr_pos ( struct MSequence * ptr_msequence )
 

Returns the current position (0xFFFF if it's about to start playing the first event).

Parameters:
ptr_msequence   A pointer to the initialized music sequence
Returns:
The current position 
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if( MSequence_is_sane( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       // Loops background music in the first of 20 music events.
       if( MSequence_get_curr_pos ( &intro_music ) > 20 )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...

void MSequence_global_mute ( bool mute_flag )
 

Sets or clears the global mute flag.

Parameters:
mute_flag   If TRUE all sounds will be disabled; otherwise enabled
Returns:
None 
       #include <cybiko.h>
       ...
       // Turns off music at all.
       MSequence_global_mute( TRUE );
       ...
       // Turns on music again.
       MSequence_global_mute( FALSE );
       ...

bool MSequence_is_playing ( struct MSequence * ptr_msequence )
 

Checks whether a music sequence is playing.

Parameters:
ptr_msequence   A pointer to the initialized music sequence
Returns:
TRUE if music is playing 
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if( MSequence_is_sane( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       // Loops background music.
       if( !MSequence_is_playing ( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...

bool MSequence_is_sane ( struct MSequence * ptr_msequence )
 

Checks whether the current content appears to be valid.

Parameters:
ptr_msequence   A pointer to the initialized music sequence
Returns:
TRUE if the content is valid 
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if( MSequence_is_sane( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       // Loops background music.
       if( !MSequence_is_playing ( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...

bool MSequence_load ( struct MSequence * ptr_msequence,
struct Input * ptr_input )
 

Loads a sequence from a specified Input stream.

Parameters:
ptr_msequence   A pointer to the initialized music sequence
ptr_input   A pointer to the Input stream structure of an opened music resource
Returns:
TRUE if initialization succeeded 
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       struct Input* ptr_input;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       ptr_input = open_recourse_Ex( "new_intro.mus" );
       MSequence_load( &intro_music, ptr_input );
       if( MSequence_is_sane( &intro_music ) )
       {
         MSequence_play( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       Input_dtor( ptr_input, FREE_MEMORY );
       ...

void MSequence_mute_background ( bool mute_flag )
 

Sets or clears the background music(effects) mute flag.

Parameters:
mute_flag   If TRUE background sounds will be disabled; otherwise enabled
Returns:
None 
       #include <cybiko.h>
       ...
       // Turns off background sound.
       MSequence_mute_background( TRUE );
       ...
       // Turns on background sound again.
       MSequence_mute_background( FALSE );
       ...

void MSequence_mute_foreground ( bool mute_flag )
 

Sets or clears the foreground music(effects) mute flag.

Parameters:
mute_flag   If TRUE, foreground sounds will be disabled; otherwise enabled
Returns:
None 
       #include <cybiko.h>
       ...
       //  Turns off sound effects.
       MSequence_mute_foreground( TRUE );
       ...
       //  Turns on sound effects again.
       MSequence_mute_foreground( FALSE );
       ...

void MSequence_play ( struct MSequence * ptr_msequence )
 

Plays a music sequence in the foreground.

Parameters:
ptr_msequence   A pointer to the initialized music sequence.
Returns:
None 
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if ( MSequence_is_sane( &intro_music ) )
       {
         MSequence_play( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...

void MSequence_play_background ( struct MSequence * ptr_msequence )
 

Plays the a music sequence in the background.

Parameters:
ptr_msequence   A pointer to the initialized music sequence.
Returns:
None 
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if ( MSequence_is_sane( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       // Loops background music.
       if( !MSequence_is_playing ( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...

void MSequence_stop ( struct MSequence * ptr_msequence )
 

Stops playing a music sequence.

Parameters:
ptr_msequence   A pointer to the initialized music sequence.
Returns:
None 
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if ( MSequence_is_sane( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       // Stops background music.
       if( MSequence_is_playing ( &intro_music ) )
       {
         MSequence_stop( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...