








              [1mAdPlug Player development HOWTO[0m

                [4mSimon[24m [4mPeter[24m [4m<dn.tlp@gmx.net>[0m


[1m1.  Precautions[0m


     Be sure to also read the [1mAdPlug Hacking HOWTO[22m.


     Your  player  normally  consists of two files (the .h &
.cpp files) and you normally name them by  the  file  exten-
sions, your player handles. For example, the HSC player con-
sists of the files hsc.cpp & hsc.h, because it handles  .hsc
files.  This  is the same with your player class name. Thus,
the HSC player's class is  called  [4mChscPlayer[24m.   If  any  of
these  names happens to be already taken for other purposes,
just name your player something else, appropriately.


     player.h contains the abstract  player  interface.  You
have  to  include  it  in  your  player  to communicate with
AdPlug. It also contains some very  helpful  structures  for
use  in  your player. You don't need to use the structs, but
you have to use the  methods  provided  by  the  [4mopl[24m  object
(declared   in   opl.h,   but  automatically  included  from
player.h) inside the player class to do the OPL I/O and ini-
tialization work.


[1m2.  Main Work[0m


     All  you have to do now is to inherit the [4mCPlayer[24m class
into your own player class and  fill  the  abstract  methods
with  code. You at least have to fill in the following meth-
ods:


     bool load(istream &f, const char *filename); // load file
     bool update();                     // execute replay code
     void rewind(unsigned int subsong);      // rewind to specified subsong
     float getrefresh();                // return needed timer refresh rate
     std::string gettype();                  // return file type



     The other methods from [4mCPlayer[24m just serve informational
purposes  (as  does [4mgettype()[24m, but it's required anyway ;) )
for AdPlug's info box and needn't to be filled. It would  be









                             -2-


nice  if you fill them anyway, if that's reasonable for your
player.


     There's one more public method you have  to  define  in
your player class:


     static CPlayer *factory(Copl *newopl);  // return a new instance



     Since  it is static, it isn't already virtually defined
in the [4mCPlayer[24m class and you have to add it  manually.  This
method  should  return  a freshly initialized object of your
player class.  If any errors occured (e.g. not  enough  mem-
ory), return 0 instead.


     Return  true  from  your [4mload()[24m method, if the file was
loaded successfully, or false if it couldn't be  loaded  for
any  reason  (will  mostly  be wrong file type errors, since
AdPlug tries its files with any replayer, it is linked  to).
Your  [4mupdate()[24m method will be called with the frequency, you
return from your [4mgetrefresh()[24m method,  in  Hz.  Return  true
from  [4mupdate()[24m if your module hasn't ended yet. If it looped
or ended, return false from that point, but play further for
any  subsequent  calls to [4mupdate()[24m.  AdPlug will rewind your
player by itself, using the [4mrewind()[24m method, when necessary.


     AdPlug  passes  the  number of the subsong, it wants to
play next, to the [4mrewind()[24m method of your player.  This  can
be  any value from 0 to the value returned by [4mgetsubsongs()[24m.
If you haven't provided your own [4mgetsubsongs()[24m, AdPlug  will
presume  your  player  doesn't have support for subsongs. In
that case, AdPlug will always [4mrewind(0)[24m.  Please ignore  any
value  passed  with  [4mrewind()[24m  that  is out of spec for your
player. This should virtually never happen, but who knows...


     After  initializing  your player, AdPlug normally first
calls [4mload()[24m, and then [4mgetrefresh()[24m and [4mupdate()[24m in  a  loop
until something happens (i.e. the user stops playback or the
song ends).  [4mrewind()[24m and all the informational methods  can
be  called anytime in between the other calls, but of course
only after [4mload()[24m has been called.


     You can add  your  own  constructors,  destructors  and
methods  to  your  player  object, as you like. AdPlug won't
care in any way.








