		PlugWrap - A WinAmp input-plugin wrapper for Euphoria 2.?
					 v. 010821
					 Mic, 2000/2001

 Files
#######

  Wrapper
 =========
 - plugwrap.ew			

  WinAmp plugins
 ================
 - in_littlesid.dll	Not the best SID plugin available, but it works.
 - in_mad.dll		MPEG Audio Decoder.
 - in_midi.dll
 - in_mod.dll
 - in_nsf.dll		NES Sound File plugin (its real name is "Bleep!").
 - in_ra.dll		RealAudio plugin.
 - in_spc.dll		SNES music (SPC700 RAM dump) plugin from the ZSNES team.


  Programs
 ==========
 - EuAmp.exw		A little example of what one can do with the wrapper.


  Additional libs
 =================
 - Win32lib.ew		Used by EuAmp.
 - Buttons.e		Some xpm buttons.
 - GetID3Tag.e		Gets the ID tag from mp3 files.


  Music files
 =============
   PC music
  ++++++++++
  - Alloyrun.mod	Pink - Alloy run. Original by Jeroen Tel.
  - Walking.mid		Walking in the air. Originally composed by Howard Blake (afaik).

   NES music
  +++++++++++
  - Doubledr.nsf	'Double Dragon' soundtrack, by Technos Corp.
  - Hebereke.nsf	(aka 'Uforia') Sunsoft did this one.
  - Kage.nsf		(aka 'Blue Shadow') by Natsume. Nice game - excellent music.
  - Trojan.nsf		'Trojan' soundtrack, by Capcom.

   C64 music
  +++++++++++
  - Commando.sid	Rob Hubbard.
  - Outrun_EL		Jeroen Tel - Outrun Europe (levels).

   SNES MUSIC
  ++++++++++++
  - Stage2.spc		"Stars and stripes forever" a la Parodius.	
  - Map.spc		Nice organ-type cut from Dracula X (Konami).


  Documentation
 ===============
 - ReadMe.txt		This file.




 Updates
#########

 010821
 - No need for the dll (plugwrap.dll) any more. Everything is now done using Euphoria
   (and some asm).
 - EuAmp now plays mp3 files.

 000711
 - Added ConfigPlug() and AboutPlug().

 000703
 - Rewrote plugwrap.dll using asm => went from 7 kB to 4 kB.

 000702
 - Reduced the size of plugwrap.dll from 28 kB to 7 kB by compiling it with Lcc-Win32
   instead of MSVC++ (wich prooves that a compiler doesn't have to be the best one just
   because it costs a gazillion bucks..).
 - Gave EuAmp a new look with some xpm buttons.

 000610
 - Reduced the size of plugwrap.dll from 248 kB to 28 kB by removing some unused stuff and
   other garbage (like MFC).
 - EuAmp now shows the name of the loaded file on the titlebar.
 - EuAmp can now play RealAudio files.
 - EuAmp can now give you (some) info about s3m/sid/spc/xm files. A bug in getMODInfo()
   has also been fixed. getS3MInfo(), getSIDInfo() and getXMInfo() were created after
   simply having studied the contents of a couple of files of those types, so they
   might not be 100% correct. 

 000513
 - Added GetLength(), GetOutputTime() and SetOutputTime().
 - The previous version of PlugWrap couldn't be used together with ewin32api.ew (used in
   Exotica, EuGL and maybe some other libs) because of name-conflicts. This has now been
   fixed.
 - Fixed a bug in this file. It's not possible to specify the absolute filename for the
   output plugin (it is possible for input plugins though).

 000512
 - Added Pause(), SetPan(), SetPlugParent() and SetVolume().
 - Added EuAmp and removed the old example program.
 - Wrote this file.



 What is this?
###############

This library lets you play audio files in (almost) any format using WinAmp input-plugins.
You may use whatever library tou wish for output, but it must share the same interface
as OUT_WAVE.DLL (wich comes with Winamp).



 Routines
##########

integer InitPlug(sequence plugname)
===================================
 Initializes the input plugin to use. Currently, only ONE
 plugin can be loaded so you must call ClosePlug() before
 you load a new one. plugname is "in_xxx.dll".
 Returns 0 on success.

 Ex:
  if InitPlug("in_spc.dll") then
   -- failed
  end if



ClosePlug(integer closeOut)
===========================
 Unloads the current input plugin. If closeOut is non-zero,
 the output plugin (out_wave.dll) will also be unloaded.

 Ex:
  ClosePlug(0)



SetPlugParent(atom parent)
==========================
 Set the parent window of _both_ the input & output plugin.
 Some plugins display graphical objects (like scrollbars), for
 wich they need the handle of the parent window. This worked ok
 with NoseFart (NSF plugin) but not with SidAmp..
 Only needs to be called once, unless you at some point want to change
 the parent of the plugins. 

 Ex:
  SetPlugParent(hWindow)



ConfigPlug()
============
 Opens the current plugin's configuration dialouge (if it has one).
 You have to give the plugin a parent before you call this routine
 (see SetPlugParent()).

 Ex:
  ConfigPlug()



AboutPlug()
===========
 Opens the current plugin's "About" monolouge (if it has one).
 You have to give the plugin a parent before you call this routine
 (see SetPlugParent()).

 Ex:
  AboutPlug()



integer Play(sequence filename)
===============================
 Play the specified file. The file should obviously be relevant
 to the current input plugin.
 Returns 0 on success.

 Ex:
  if Play("song.mid") then
   -- failed
  end if



Pause()
=======
 Pauses/Unpauses playback.

 Ex:
  Pause()



Stop()
======
 Stops playback.

 Ex:
  Stop()
 


integer GetLength()
===================
 Returns the length of the current track in milliseconds.

 Ex:
  length_in_ms = GetLength()



integer GetOutputTime()
=======================
 Returns the output time (time played) in milliseconds.

 Ex:
  time_in_ms = GetOutputTime()



SetOutputTime(integer tm)
=========================
 Set the output time in milliseconds (typically used for seeking in a stream, like ffwd or rew).

 Ex:
  SetOutputTime(1500)



SetVolume(integer volume)
=========================
 Set the output volume in the range 0 (min) to 255 (max). Should 
 be called _after_ a Play() command (or it won't take effect).

 Ex:
  SetVolume(180)



SetPan(integer pan)
===================
 Set the speaker panning in the range -127 (all left) to 127 (all right).
 Should be called _after_ a Play() command (or it won't take effect).

 Ex:
  SetPan(-60)



All routines are more or less dummy-proof, but my code is probably a bit buggy so
don't try no fancy tricks..



 Some words about EuAmp
########################

The upper scrollbar controls the volume. The lower scrollbar controls the speaker panning.
Press the play button repeatedly to change the song when playing NSF files.
Press the info button (the one with a '?') to get some info (if available) about the
current file.



 Problems/Limitations
######################

 - You can only have one plugin loaded. _Please_, call ClosePlug(0) to unload a loaded
   plugin before loading a new one, and ClosePlug(1) before program termination.

 - Programs sometimes fail to load a plugin when trying to open a file from outside the
   directory in wich the calling program is located, without first having opened a file
   of the same type in the "callee directory" (phew..). I have no idea why this happends.

 - If EuAmp (or a program of your own) can't find OUT_WAVE.DLL, try moving the dll to the
   directory where the program is located.

 - I haven't been able to get in_mp3.dll nor SidAmp to work with this wrapper. This is
   also because of unknown reasons.

 - Win32lib doesn't seem to like it when plugins display windows of their own (scrollbars etc.).
   I've solved this by only using plugins wich doesn't have their own interface.



 Credits
#########

 - Marius Fodor, for his Super Jukebox, on wich the plugin wrapper is based.
 - David Cuny, for Win32lib, wich made the demo program a lot easier to write.



 Music archives
################

 www.alpha64.org					IT/MOD/S3M/XM archive.
 www.hornet.org			 			 -- " --
 www.chiptune.com					All sorts of chip music (mod/xm/sid/nsf etc.)
 www.zophar.net/nsf					NSF archive.
 nesdev.parodius.com					You can get the NSF collection here.
 www.zophar.net/zsnes/spc				SPC archive.
 www.altavista.com + "high voltage sid collection"	10.000+ SID files.







/Mic | stabmaster_@hotmail.com
