Notes on JAM

0.  BUGS:
	-- lots of reports about unpredictable behavior
		of this program.  The program runs on some
		machines but not on others, and dies unpredictably.
		It causes the Turbo Debugger to get into a funny
		state.

		My guess is that there are ``memory leaks'' some				where. Why is there such a big .stack (500h)?

	-- get_palette_register:
		should be "ret 8" instead of "ret"
		(but no harm, as it is not used).
	-- lots of unnecessary "xor bx,bx" before
		"lea bx,var".  Harmless, of course.

1.  OVERVIEW:

	--This program is in two modules: a main module called
		game.asm, with graphics routines in graphics.asm.
	--The standard memory model used is COMPACT, which supports
		one code segment and multiple data segments.  In this
		case, only two data segments are used.
	--Images are stored in pcx format (PCX=``PC Paintbrush file Format''). 
	--It uses video mode 13h, which has resolution 320x200,
		and has a color palette of 256 out of 256K (=64^3)
		colors.
	--There is a ``double_buffer'' that is 64000 bytes in size.

2.  The .dat and .pcx files with the same name
	are apparently identical.

3.  The routine pcx_load (in graphics module):
	Basically the pcx file format is as follows:
	(1) First 128 bytes form the header.
	(2) The last 768=3x256 bytes forms the color
		palette.  The bytes are

		R1,G1,B1,R2,G2,B2,R3,...
		
		where (Ri,Gi,Bi) is the RGB values for
		the $i$th palette.  However, each color component
		must be right-shifted by 2 to get its true
		value (see the routine update_color_register).
	(3) This is basically a run-length encoding of the pixels.
		The pixels are assumed to represent a 320x200 screen.
		The pixels are grouped as
		(a) a single pixel, or as
		(b) a consecutive group of similar valued pixels.
		Each byte value N that is read is treated as follows:
			(1) if the byte value is less than 192d (=0C0h)
				then it represents a single pixel with
				palette index N. 
			(2) if the byte value is greater than or equal to 192d,
				then it is the number of pixels whose common
				palette index is given by the next byte.

	NOTE: should write a slightly more general version of PCX_LOAD
	which does not assume the screen size of the original file data.

4. Other useful routines in the graphics module:
	show_double_buffer	-- display it on screen
	set_palette_register	-- set the color of a particular
					palette register
	get_palette_register	-- get the color of a particular
					palette register
	update_color_register	-- set the colors of all the
					palette registers

5. More details about PCX format taken from p.403,
		``Graphics File Formats'', by C. Wayne Brown
		and Barry J. Shepherd, Manning Pub. Co., Greenwich, CT (1995).

	HEADER:
		Byte#	   DATA		Details
		=====	   ====		=======
		1	signature	Hex A0
		2	version		Version 2.5, 2.8, 3.0 and greater, etc
		3	compression	1=run-length
		4	bits/pixel	per color plane
		5-6	Xmin		Upper left corner
		7-8	Ymin		upper left corner
		9-10	Xmax		Lower right corner
		11-12	Ymax		Lower right corner
		13-14	hor.resolution	
		15-16	ver.resolution	
		17-74	palette
		65	reserved
		66	no.of color planes
		67-68	bytes/line	buffer space needed for decoding
		69-70	palette type	1=grayscale, 2=color
		71-128	filler(not used)

	Image Data:
		Each scan line is encoded separately (run-lengths do not cross
		scan line boundaries).

	Palette (769 bytes):
		Byte 1 is the signature (=0Ch)
		Bytes 2,3,4 = RGB for palette index 1
		Bytes 5,6,7 = RGB for palette index 2
		etc
		
	PCX run-length scheme:
		the first 2 bits of each byte is used to distinguish length
		values from data values.  If a data value already has its
		first 2 bits set, then a length value must be inserted
		in front of the data (regardless of whether there is
		any repetition).  ALGORITHM:

		repeat:
			Val = next byte in compressed data stream
			If Val < 192, 
			   then
				output Val (as literal value)
			   else
				Count = Val-192 (this strip off the high order 2 bits)
				Color  = next byte in stream
				output Color, Count number of times. 
		until the stream is processed.