How to use the player library

GtkMod uses a library that I created to actually play the modules. One draw back of writing the library in c++ is that the library can only be used with compilers that use the style of name mangling. Since the source to the library is available under the LGPL, hopefully this won't cause too many people a problem.

I have tried to make the names of the method's easy to understand.


Here are the relevant portions of the player class

class player
{
public:

    // constructors
    player();
    player(audio* driver);
    virtual ~player();

    // playing, stopping and pause
    virtual void play(bool fRestart = true);
    virtual void stop();
    virtual void pause();

    // setting the player's attributes
    void set_mod(Module* new_mod);
    void set_stereo(bool stereo);
    void set_rate(int rate);
    void set_bits(int bits);
    void set_driver(audio* driver);

    // getting the players attributes
    ubyte   get_bpm()   const {return bpm;}
    ubyte   get_speed() const {return speed;}
    bool    is_stereo() const;
    int     get_rate()  const;
    int     get_bits()  const;
    Module  *get_mod()  const {return mod;}
protected:
    // callbacks (more like events)
    virtual void callback_order() {}
    virtual void callback_row  () {}
    virtual void callback_bpm  () {}
    virtual void callback_speed() {}
    virtual void callback_gv   () {}
    virtual void callback_end  () {}

    // channel callbacks -- called when something changes in the chan structure
    virtual void callback_ch_volume (int ch);
    virtual void callback_ch_panning(int ch);
    virtual void callback_ch_note   (int ch);
    virtual void callback_ch_smp    (int ch);
    virtual void callback_ch_inst   (int ch);

    // error stuff
    virtual void callback_error(const char *msg);

....

private:

...

};


the Module class

Modules can be loaded and passed to the player class by first creating an instance of the Module class,
calling the "Module::load(const char *filename)" method and the using the "player::set_mod(Module* new_mod) "  method to tell the player class about it.

eg.

Module mod;
player    p;
...
char* filename;
...
mod.load(filename);
p.set_mod(&mod);
p.play();
...

Notes:

"Module::load(const char *filename)" loads the module by using one of loadMOD, loadS3M, or loadXM, based on the file extension.

play() will fork a new process to play the module. In the future this may be replaced by a new thread instead.

Because of the creation of a fork, callback need to use some sort of interprocess communication to
communicate with the process that called play. See the gtkplayer class in the GtkMod source for
an example of doing this. Or alternatively, if your using gtk in you appplication you can use gtkplayer,
instead of player.

gtkplayer

If you use gtkplayer instead of player you will need to create a GdkInputFunction to pass to the
constructor.  This needs to process the input ( I've used a simple format for it) and react to it.

The format is "ID<value>" where ID is a special character defined in gtkplayer.hpp and value is
the new value

ID_SPEED<speed>                             eg ID_SPEED"6"
ID_END<>                                             eg ID_END""
ID_ORDER<order"/"pattern>          eg ID_ORDER"a2/a1"               (numbers in hex)
ID_ROW<row>                                     eg ID_ROW"2f"                           (numbers in  hex)
ID_BPM<bpm>                                     eg ID_BPM"125"                         (numbers in decimal)
ID_GV<gv>                                            eg ID_BPM"64"                           (numbers in decimal)

The player can be paused using pause() or stopped using stop().
 

Callbacks

The callbacks are defined so that a subclass of player can be created which can be notified when these
events occur. See the gtkplayer class in the GtkMod source for an example of how to do this.

The events that the class can be notified are: