Sept 29 release RELEASE NOTES
=============================

Summary

	Although this release is targeted for RCP 2.0, we have also generated 
	a patch image for RCP 1.0 to fix bugs in the boot microcode and video
	interface functions that cause the demo app simple to hang. To use the 
	RCP 1.0 image properly, you need to set the environment variable 
	HW_FLAGS to "-D_HW_VERSION_1" before compiling any of the demo apps.
	Please note that all the references to debug port and new printf
	facilities described below apply only to RCP 2.0.

	The following is a summary of changes since the last release.

	---------------------------------------------------------------------

        Fog is now working.  See the man page: gSPFogPosition

        There is a new requirement for light directions:  the magnitude of the
        light vector must be less than 120.  That is, sqrt(x*x + y*y + z*z)<120.
        This requirement is repeated in the gSPLight and gdSPDefLights man
        pages.

	There are 3 new demos...

		print - app to test new debug port printf facilities (for 
		RCP 2.0 only).

		ginv - prints version information about RCP, and R4300 speed.
		If you have both RCP 1.0 and RCP 2.0 systems at your site, 
		you will find this app useful.

		A new application called blockmonkey allows you to measure the 
		performance penalty of using various features with various 
		orientations and polygons. See the README file in the 
		application directory for more information.


	The scheduler previously released as part of the 'simple' app
	has been extracted and moved to be part of libultra. Several bugs
	have also been fixed in the scheduler. If you use this scheduler
	as a template for your game, you should reexamine this code.

	Many man pages have been corrected.  Documentation is now more complete
	and coherent.

	The debug port is now working.  We intend to replace rmonPrintf by
	osAsynPrintf which uses the debug port instead of the ramrom.  The
	osSyncPrintf should only be used when OS is not fully functional,
	such as in the boot procedure.  Also, we renamed the rmonSprintf to
	sprintf since this function has nothing to do with either rmon or
	os; it is just for string processing.  Please adjust your apps to
	reflect these changes.

	The video mode glitches which were occuring when scaling was used in
	the supported modes has been fixed, see the osViSetXScale man page for
	more information about supported X/Y scale factors. 

	The problems with PAL interlaced modes has been fixed.

	Compact Midi Sequence Player.  This sequence player supports a compacted
	form of midi providing a reduction of RAM and ROM usage. Also included 
	in the compact sequence player is looping on a per track basis. Details
	of producing compacted sequences are covered in the chapter titled 
	"Using the Audio Tools." The programming interface to the compact midi 
	sequence player is discussed in the Audio Library documentation. The 
	specifics of the compact sequence format are covered in Audio Formats. 
	An example of using the compact sequence player is shown in playseq.c. 
	A new tool midicomp is included for automatically compressing midi 
	files.

KNOWN BUGS and CAVEATS ======================================================

Graphics

	---------------------------------------------------------------------

	HW 2.0 bug
	When zooming in on a texture-edge mode object, such as a tree that is
	very close to the viewpoint, and dithering is enabled, the filtering
	of the dither pattern around the edges does not work.  Workarounds:

	1.  Disable dithering when rendering texture edge mode objects.
	2.  Don't use texture-edge mode (the edges defined by the texture
		will not be as sharp as in texture-edge mode).
	3.  Use sharpen instead of texture edge mode. 

	---------------------------------------------------------------------

>	The HW 2.0 system has improved performance.

	---------------------------------------------------------------------

>	Dither hardware has been greatly improved in HW 2.0. The API has
	changed to allow several choices of dither. See the man pages
	and demos for examples.

	---------------------------------------------------------------------

>       Fog is now working.  See the man page: gSPFogPosition

	---------------------------------------------------------------------

>       There is a new requirement for light directions:  the magnitude of the
        light vector must be less than 120.  That is, sqrt(x*x + y*y + z*z)<120.        
	This requirement is repeated in the gSPLight and gdSPDefLights man
        pages.

	---------------------------------------------------------------------

	decal polygon bug

	Z-buffered decal polygons use the delta Z value for a pixel,
	defined as:

		delta_z = log2 (| dz_x | + | dz_y |)

	to determine whether two surface should be considered co-planar.
	A 'fuzzy' compare of the current pixel's Z and the previously
	stored Z is made.  A surface is coplanar if your have set the Z
	compare mode bits to decal and:

		(pix_z + delta_z >= memory_z) && (pix_z - delta_z <= mem_z)

	If this condition is met, the color is written and the mem_z is
	not updated.

	Unfortunately, when the two surfaces are perpendicular or nearly
	perpendicular to the eyepoint, the delta_z goes to zero and the
	Z comparison is not fuzzy anymore, but exact.  Because of differences
	in accumulated error in the rasterization of two planes that don't
	share the same vertices, the comparison will sometimes indicate the
	decal poly is in front and sometimes behind.  This will show up as
	random flashing in the decal as you move the eyepoint when the
	decal is approaching perpendicular.

	One hardware solution is to use the max of delta_z and some 
	hardware register value to ensure that a fuzzy Z compare is
	always possible.  Unfortunately, this bug was not found in time
	to fix in the second silicon.

	Other workarounds are to always make the decal and the underlying
	polygon share the same vertices.  This has the disadvantage of 
	wasting pixel visits.

	It may be possible to use texture decals rather than geometric
	decals.  This technique is discussed in the Texture document
	shipped to  developers.

	Always a possibility is to simply not use geometric decals.  Instead,
	break up the surface to use more polygons around the decal and
	remove the part of the polygon underneath the decal.  This increases
	the number of polygons but is more efficient in terms of pixel visits
	(fill rate).

>	A microcode fix has been implemented that clamps the dZy term
	during setup.  This workaround is still being investigated, but
	is available for use in the released microcode. To use it,
	you must use the un-documented macro gSPTextureL(), which works
	just like the gSPTexture() macro, except it has an additional
	parameter. This parameter is normally zero, but in the decal
	case, if you increase it to 2 or 4, etc., you can clamp the
	dZy term.

	Note that this bug only applies to Z-buffered decals.  Some
	applications may be able to use non zbuffered decals.

	---------------------------------------------------------------------

	gDPLoadTextureBlock has a bug that some of the sizes results in
		incorrect texture loads.

> 	A table of the maximum number of rows that can be correctly loaded
	given a certain number of columns in the texture has been added as
	an Appendix to the Texture Mapping chapter of the NU64 Programming 
	Manual.

	---------------------------------------------------------------------

	alpha X coverage in parallel with alpha dither bug

>   This is a HW 1.0/2.0 system limitation.

	---------------------------------------------------------------------

	In HW 1.0, alpha x coverage did not handle 1.0 (totally opaque)
	values correctly, causing edges to be incorrectly anti-aliased
	behind objects such as texture-edge mode trees.

>   This problem has been corrected in HW 2.0.

	---------------------------------------------------------------------

	In HW 1.0, the RDP performance counters did not work correctly.

>   This problem has been corrected in HW 2.0. See the osDpGetCounters
	man page.

	---------------------------------------------------------------------

	To get better texture accuracy, we scale the texture coordinates using
	perspective normalization gSPPerspNormalize() to retain more useful
	bits in the RSP fixed point transformation. We then rely on perspective
	correction hardware in the RDP to divide and regain the correct (s,t)
	value. Basically, this is a fixed point trick to scale up the number
	prior to divide in hope of retaining maximum significant bits.

	This means that you need to turn on perspective correction.
	gDPSetTexturePersp(G_TP_PERSP) whenever you draw textured triangles.
	Even in orthographic projection. However, when doing texture rectangles
	where you specify (s,t) directly without any geometry transformation.
	You need to turn off perspective correction.
	
	---------------------------------------------------------------------

>	The RDP bug which small thin triangles caused the RDP pipeline
	to hang, has been fixed with HW 2.0. Any graphics that cause the RDP
	to hang is a new bug, and should be reported ASAP!

	---------------------------------------------------------------------

>	The RDP bug that caused gDPLoadTextureTile* to not work for
	certain alignements has been fixed with HW 2.0. The work-around 
	macros from pervious releases should NOT be used.

	---------------------------------------------------------------------

>	The RDP bug that caused gDPLoadTLUT to not work correctly, has
	been fixed with HW 2.0. The work-around macros from previous
	releases should NOT be used.  It is no longer necessary to
	quadricate TLUTs in DRAM, e.g. don't use rgb2c -Q.

	---------------------------------------------------------------------

>	The HW 2.0 system now calculates texture LOD per-pixel rather then
	per-vertex.  The quality of mip-mapped textures is greatly improved, 
	and the software pipeline is faster. Please use this feature and 
	provide feedback.

	---------------------------------------------------------------------

>	gSPCullDisplayList() has been implemented, see the man page.
	
	---------------------------------------------------------------------

	gSPMatrixState() is not implemented.
	
	---------------------------------------------------------------------

>	The video glitches in LAN2 and LAF2 video modes should not appear
	on HW 2.0 systems, using the final system frequency.

	---------------------------------------------------------------------

 	The Video output pipeline which performs scaling on frame buffer data
	has a pipeline delay bug which causes 2 pixel wide artifacts to be seen
	on scaled pixel data whenever a scale factor other than .5 or 1.0 is 
	used.

>	This has been fixed on HW 2.0 systems.

	The video scaling hardware was not designed to support scale factors 
	less than .25, and doing so results in undesirable image breakup; the
	os calls osViSetXScale(), osViSetXScale() now have assertion checking
	for a minimum scale factor of .25 (formerly they asserted for a 
	minimum scale factor of 0.0).

	---------------------------------------------------------------------

Audio
	A new application called midiDmon allows you to download your audio
	banks and playback on the Ultra64 with midi from keyboard or sequencer.
	To use this application, the ultra inst image depends on installation
	of the dmedia_eoe (version 5.5) image. The 5.5 dmedia_eoe is included
	on the inst tape sent to you.

	---------------------------------------------------------------------

	audio performance has dramatically improved on this release. We have
	rearranged code to minimize the ICache misses. The cost for audio
	is 1% per channel at 30Hz update for 22KHz output.

	---------------------------------------------------------------------

Operating System

	IMPORTANT: The memory map has changed. The final machine will have 3 MB
	of memory.  The color and z framebuffer can only reside in the
	first 2 MB of memory.  The boot code must reside in the 3rd MB of
	memory. Therefore, if you DMA data into the 3rd MB, you can potentially
	wipe out the code/data that was loaded duing boot time.

	---------------------------------------------------------------------

Tools

	---------------------------------------------------------------------

Demos

	ginv - prints version information about RCP, and R4300 speed.
	If you have both RCP 1.0 and RCP 2.0 systems at your site, 
	you will find this app useful.

	---------------------------------------------------------------------

Debugger

	gvd sometimes can't find the source because it gets confused on the
	path to the source. A definite occurance is when you login the graphics
	console as root. If you login as guest and su - root, everything seems
	to work.

	---------------------------------------------------------------------

	There has been a bug fix for the multi-thread window in gvd.
	After user has switched to a specific thread, he can then invoke
	the multi-thread window to obtain a complete list of all active threads
	running on the target machine. There is still a bug in showing the
	actual state of the threads in this window; that is, a stopped thread 
	can still be listed as running on the window. Therefore, user should 
	use the threadstatus utility to obtain accurate state information of 
	a specific thread.
	
	---------------------------------------------------------------------

	Currently, the debugger cannot support background mode debugging.
	That is, if a breakpoint is encountered, all user threads are stopped.
	gvd does not support private breakpoints per thread; all breakpoints
	are shared globally. Furthermore, the Continue button on the main gvd
	window only resumes execution of the thread being debugged. To resume
	or stop execution of all threads, user should use the Continue or Stop
	button in the multi-thread window.

	---------------------------------------------------------------------