== BGM 1.0a ==

http://thebrickmonkey.com/bgm/

CONTENTS:


I.) What is this?
II.) File desriptions
III.) Instructions
IV.) Legal-type stuff (You have to read it...)
V.) Changes

I.) What is this?
==================================================================================
      BGM is a frontend for Un4seen's Bass.dll to run with GameMaker. Through 
 Bass.dll, It allows the playback of many different tracked music formats like
 MOD, XM and Bass' own MO3 format.
      But why would you want to use this particular music system instead of some
 other, more feature-enriched system like Shaltif's famous SXMS? Well, although
 BGM isn't as loaded with functionality as it's competitors and doesn't even try
 to match, it offers an extremely simple inteface as well as a very small addition
 to the total filesize of your project; less than 100kb.
 
      Here is a complete feature list:
  
  * Support for these audio formats:
    MP3, MP2, MP1, OGG, WAV, XM, IT, S3M, MOD, MTM, UMX, MO3.
  * Total filesize of the DLLs is a mere 97.5 kb, which, as you probably know,
    is about 1/10 of a megabyte. :)
  * Extremely simple to use. In GML, a single call to gmb_init() is enough to
    initialize the entire system. From there, you need only call bgm_play(song's_file_name)
    to play a song.
  * Supports music stopping, volume control and pausing.
  
 If you find BGM to be too limiting, then, by all means, check out Shatif's SXMS dll.
 (http://forums.gamemaker.nl/index.php?showtopic=24108)
 It is a great DLL that uses FMOD to do all the things that BGM can do, plus much more.
 However, it's a bit more complicated to use than BGM. (No offense, Shaltif! -_^)
 
II.) Files
==================================================================================
 The files are pretty much self explanatory, but I'll go over them anyway.

 -- bgm.dll --
  The wrapper DLL that must be present with BASS.DLL in your game's directory
  for the GML scripts to work.
 -- bass.dll --
  This is where the REAL functionality of BGM comes from. Bass.dll is the library
  that BGM uses for doing all of it's music playing stuff. It is provided for free
  by un4seen.com for non-comercial purposes.
 -- bgm.gml --
  You can load this into your .gm6 or .gmd file in the usual gml-importing way.
  If loaded correctly you should get a subfolder within Scripts with some scripts
  to use BGM. The functions are pretty much self explanatory just like this set
  of files.
 -- bgm_example.gm6 --
  These are example GM programs to use as tests.
  Even though there is no GM 5.3 gmd file, BGM will still work with it.
 -- Makefile --
  If you have MinGW32 installed, you can run mingw32-make in the bgm directory to
  compile and link a fresh, new bgm.dll from the sourcefile provided.
  (Of course, you'll have to change the C:\Dev-Cpp\lib\bass.lib line so that it points
  to the location of your bass.lib file.)

III.) Instructions
==================================================================================
 How to use BGM:
 1.) Put BGM.dll and bass.dll into the working directory of your game.
 2.) Import BGM.gml into your project in the usual way.
 3.) Read the script called INSTRUCTIONS to find out how to use the scripts,
     or just read below:

 Key:
 <return_value> script_name(parameters)
 
 <true or false> bgm_init()
 -------------------------------------------
  This must be called once (and ONLY once) before any other bgm
  scripts are used.
  Returns wether or not the initialization of BASS.DLL worked.
 
 <none> bgm_close()
 -------------------------------------------
  Closes down BGM. You don't normally need to call this because
  GameMaker will automatically close it when the program ends. 

 <none> bgm_play(filename)
 -------------------------------------------
  Plays the file in the given filename, or restarts it if it
  is already playing. If you play a new song while a song is
  already being played, the old song will be stopeed and
  unloaded from memory.

 <none> bgm_stop()
 --------------------------------------------
  Stops the song that is currently playing.

 <none> bgm_pause()
 --------------------------------------------
  Pauses the song that's playing.

 <none> bgm_unpause()
 --------------------------------------------
  Unpauses the song that's paused.
  Note that calling bgm_play() will start the song
  over instead of resuming it.

 <volume or none> bgm_vol(volume or -1)
 --------------------------------------------
  Either gets or sets the playing volume.
  The volume may be between 0 and 100.
  Pass -1 (or negative value) to make it
  return the current playing volume rather than
  setting it.
 
 <true, false or 2> bgm_isplaying()
 --------------------------------------------
  Returns wethor or not a song is playing.
  Returns 2 if the song is paused but not stopped.
 
IV.) Legal-type stuff
==================================================================================
 Okay, nobody likes reading disclaimers and stuff like that so I'll make this quick.
 
 In no particular order, here are things you need to know before using BGM:
 
 * BASS.DLL is not made by me. It is made by the guys at http://www.un4seen.com
   so if you have a question regarding BASS.dll specificly, ask them. 
 * You can't use BGM commercially since, first of all, you're not allowed to use
   BASS.DLL commercially without buying a license from un4seen.com. Second, I don't
   really want BGM to go commercial because that would introduce...problems.
 * The BGM system is NOT garunteed to work with your system, and is not even garunteed
   to run without damaging your system. If it does, I cannot be blamed for it and
   cannot take responsabillity. (But this shouldn't happen)
 * Remember to read BASS's licensing information at un4seen.com!
 * Although it's not required, it would be nice if you you put bgm's homepage
  (and un4seen.com as well) in the credits of your game.

V.) Changes
==================================================================================
 -- 1.0a --
  * Fixed the bug that prevents non-tracked music from playing. The problem was simple;
    I thought that BASS.dll used a single function for loading of every type of file,
    but it actually has a different system to load "sampled" formats (like MP3 and WAV)
    than it does for "music" formats (tracked formats).


For questions or comments, email me at musicguy@thebrickmonkey.com.
-The Music Guy