XPMCK - Cross Platform Music Compiler Kit
Mic, 2008

Website: http://jiggawatt.org/muzak/xpmck/
Contact: micol972@gmail.com


What you will need:

	Some basic knowledge of MML. For syntax information in english, see these guides:

	http://www.nullsleep.com/treasure/mck_guide/
	http://www.geocities.co.jp/Playtown-Denei/9628/mck/mckc-e.txt (mirrored at http://jiggawatt.org/muzak/mckc-e.txt )


	To build the SEGA Master System / Game Gear version of the player you need WLA-DX: 

	http://www.villehelin.com/wla.html



P(P)MCK commands supported in XPMCK:

	&, ^, [], {}, @, @@, @EN, @EP, @MP, q, @q 



Commandline options:

	-h [command]
	-v	
	-sgg		Output data suitable for the SEGA Game Gear
	-sms		Output data suitable for the SEGA Master System
	
	If no output filename is specified it will be given the name <inputFilename>.asm by
	default.
	
	If the output filename has a .vgm extension and the target is sms or sgg the compiler
	will generate a .vgm file (uncompressed) instead of an .asm file.
	
	
	
Compiler directives:

	These are the XPMCK-specific preprocessor commands available:

		#ELSE			Used together with IFDEF/IFNDEF.

		#ELSIFDEF		Used together with IFDEF/IFNDEF.
		
		#ENDIF			Used together with IFDEF/IFNDEF.

		#EN-REV [num]		If num==0 EN macros work similar to other 
					MML implementations.
					If num==1 EN is not cumulative, meaning that
					instead of {| 3 4 -7} you write {| 3 7 0}.
		
		#IFDEF, #IFNDEF		Conditional compilation depending on if a
					symbol is defined or not.
					
					Currently the only symbol defined is the selected
					target, so this check would be valid:
					
						#IFDEF SMS
							; blah
						#ELSIFDEF SGG
							; blah
						#ENDIF
		
		#INCLUDE "filename"	Include the contents of another MML file.
	
		#NTSC			Inform the compiler that you are going to play the
					song with an update frequency of ~60 Hz. Along with
					the tempo and the note lengths this is used to 
					calculate how long each note should be played.
					
		#PAL			Specify a 50 Hz update frequency. Mutually exclusive
					to #NTSC. Some targets only support 60 Hz playback -
					for these targets this command is ignored.
		
		#TUNE			Use an alternative frequency table on the SEGA Master
					System to lower the error percentage on higher octaves.
			
		#UNIFORM-VOLUME [num]	Specify a custom maximum volume for all channels. 
					The volumes will be scaled to the valid range of
					the target machine.
					

Syntax:

Comment
		Single line comments start with a ; (semi-colon).
		Multiline comments start with /* and end with */


Channel separation (pan) macro
	@CS[num] = { ... | ...}
		Pans the sound on targets that support it. Valid range is -63-63.
		-63 means full left, 0 means center and 63 means full right.
		
		The macro is applied to a channel with CS[num] and disabled with CSOF.
		

Waveform definition
	@WT[num] = { sample sample sample ... } or { "filename.wav" resample volume }
		Defines a waveform for playback on channels that supports it.
		In the first case the sequence should contain 32 unsigned samples in the
		range 0..MAX-VOLUME.
		In the second case the first value should be a string specifying a
		.wav file to convert. The resample parameter is the frequency to
		resample the .wav file to, and volume specifies the upper limit
		of the volume range the sample data will be scaled to.
		
		Example:
		
			@WT0 = {"kickdrum.wav" 8000 15}
			@WT1 = {0 0 0 15 0 0 0 15 0 0 0 15 0 0 0 15 0 0 0 15 0 0 0 15 0 0 0 15 0 0 0 15}
			
			C v3 WT1 c4
			
		
General macro
	$[id]<{ ... }>
		Define/use a general macro. These can be used to save typing if a
		lot of smilar patterns are used in a song. Parameters are dereferenced
		with %num% (%1% being the first parameter).

		Example:
	
			$1 { [%1%]4 %2%.. }

			A $1(c, a)
			
		The macro invokation on channel A will expand to [c]4 a..


Callback
	![id][(frequency)]
		Call a function on the host CPU. E.g. if playing a song on the
		SEGA Master System this command would call a function in your
		Z80 code. This can be used to synchronize the visual output
   		of your program with the music.
		The frequency parameter specifies how often the function should be
		called. The available values are:

		0			Never (disable the callback).

		1			Once (called during the next update).

		EVERY-NOTE		Called for every new note that is
					played on the channel(s).

		Example:

			AD !foo(EVERY-NOTE)
			A l16 cdef
			D l32 [g]8

		Here the function foo will be called each time a new note is
		played on channel A or D.
			


Implementation specific notes:

	
	Sega Master System / Game Gear:

		Volume range is 0..15. The lowest playable note is A in octave 2.
		Channels A, B, C are tone channels that output square waves. 
		Channel D is used for noise. @0 selects white noise and @1 selects periodic
		noise.
		Limited panning is supported on the Game Gear (negative values means full left,
		zero means center, positive values means full right).
		If all channels are active and you're using a lot of effects and/or short notes,
		the playback code can use up quite a few clock cycles. Therefore it's best to
		use the line interrupt to call the player update routine at scanline 0 of each
		frame in order to leave the vblank period free for other stuff.
		EP and MP can be used together, but they will interfere with eachother.
		

	General:

		Effects are stepped through once per frame.

	
		
TODO:

	Things that would be nice to do, time permitting:
	
		* Fix bugs.
		* Write playback libraries for other platforms.
		* Implement more effects.
		* Create a GUI / player for Windows.
		* Optimize the playback libraries.
	