spin

README_DEMOS CONTENTS:
	An RDP exploration  tool.  See it's README file for more info.

README CONTENTS:
------------------------------------------------------------------------------------
Spin is a sample application, not a supported product. There may or may not be
upgrades and bug fixes. Or there might.
------------------------------------------------------------------------------------

Spin is run by executing the script 'spinit'

Spin is an interactive application that uses the ramrom interface to the ultra64
hardware to allow transfer of RCP commands through a user interface (UI) built on 
top of tcl/tk and simultaneously view the effects on the TV monitor. Different 
models can be chosen, various textures loaded and many Color Combiner and Rendering
modes tried out. Most classes of gbi commands are available here though not all 
flavours of each command.

Spin was originally written as a tool for verifying the ultra64 hardware 
and software. It is not a general programming interface and should not be used
as such.  More than anything else, spin is a docuumentation of the RDP hardware. 
For anyone starting to learn the graphics commands, messing around with spin is 
an ideal starting point.

Each relevant UI event (button press, menu select etc) sends one or more set of
RCP commands that are then interpereted by the application running on the 
ultra64. Not all UI changes will cause a display list to be sent to the app.
Some just set the UI state and have a 'done' button assigned to them that
will send down all the accumulated state to the application.

The user interface is split into 4 windows roughly corresponding to the 
logical divisions of the RCP functionality although there is some blurring
of the boundaries:


1. RSP
2. Texture Unit
3. Color Combiner
4. Blender 

Within each window buttons are grouped together based on the particular
gbi command they correspond to. Here's a brief description of the less
obvous buttons in each window.

RSP window
----------

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
	The centerpiece of this window is a trackball/fly interface for 
manipulating objects using the mouse. Mouse buttons are mapped as follows:

RIGHT_BUTTON: 
	toggle between trackball/fly modes
	You can also do this using the TRACKBALL button below
	the central frame.

LEFT_BUTTON:
	trackball control in trackball mode
	Inactive in fly mode

MIDDLE_BUTTON:
	grab and move left,right,up,down in trackball mode
	Inactive in fly mode

LEFT_BUTTON & MIDDLE_BUTTON:
	Move forward and backward in trackball mode

In fly mode the cursor location controls flight forwards and backwards.
No roll pitch or yaw controls are provided in fly mode.

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Sliders marked "lef"t,"right","top","bottom" control the RDP scissor box

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

The "init state" button resets the RSP and RDP states to some 'reasonable'
default value.

The "init model pos" button resets the model position

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

The "record" and "play" buttons allow recording and playing back of UI widget
operations. Widget changes are recorded into the specified file and can
be played back.

NOTE: 	SINCE ONLY UI ~CHANGES~ ARE RECORDED, IN ORDER TO GET CONSISTENT
  	RESULTS, RECORDING MUST BE DONE AFTER SETTING THE RCP TO THE 
	DEFAULT INITIAL STATE AND SO MUST PLAYBACK.

The scripts directory under spin/ui contains some pre-recorded sample
tests and can be played back by specifying the files:

	scripts/mip.rec 	- mipmap example
	scripts/det.rec		- detail texture example
	scripts/xlu.rec		- xlucency example
	scripts/xlu1.rec	- xlucency example
	scripts/tex_edge.rec	- texture_edge mode example

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Texture window
--------------
	This is probably the most confusing of all the sets of controls
so pay attention!

The texture controls are broadly grouped into 'texture actions' and
'texture state'. The actions buttons are those related to selecting
and loading textures and texture lookup tables. The state buttons
set Tile descriptor parameters and some of the other texture parameters.

Texture Actions
---------------
	"selectTextureMap": This menu button selects the texture in preparation to
loading. The menu button also causes setting of "setTile", "setTextureImage"
"loadBlock", "loadTile" and "loadTLUT" parameters in anticipation of a texture
load occuring. The "Done" button actually causes the load to occur by 
executing the "spTex", "setTimg", "setTile", "setTileSize", "loadBlock"
and "setTother" commands. Note that this is an example of a UI action that
causes a complex sequence of RCP commands to be sent to the application.
Many other buttons are simpler and send only a single command to be sent.

This two-step process of selecting then loading a texture allows the user to
select a texture but load it using not the "Done" button of the "selectTexture
Map" menu but the "loadBlock" or "loadTile" buttons with user chosen parameters.
It is also possible to change  "setTile" parameters before executing one of the
load methods.

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

"loadBlock" executes only a loadBlock command and so does "loadTile" which means
that to succesfully load a texture using these commands the other necessary RDP
state must be setup previously by executing "setTile", "setTimg" etc. commands.
This can be done through the texture state buttons below.

"loadTLUT" is a special case since it needs the textureImage to be setup to point
to the TLUT before a load occurs. This is done automatically for the user:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Texture State
-------------
	The centerpiece of the texture state commands is the "setTile" array.
This array of widgets sets all the parameters for all the 8 tile descriptors.
These settings do not take effect immediately but only after the "Done" button
is pressed. This long "Done" button sends down all the texture state commands
including the following:

"spTex":
	 scaleS and scaleT:
	 	Sets up the texture coordinate scale parameters in the RSP.
	 primTile:
	 	Sets up the index of the tile descriptor used which in this case is
	 	defaults to Tile 1 (Tile 0 is reserved for detail texture purposes)
	 maxLevel:
	 	Sets up the number of mipmap levels to use for mipmapping beyond
	 	which the tile number will be clamped
	 spTexEnable:
		Enables and disables texturing in the RDP

"setTother":
	 sets up a bunch of miscellaneous texture parameters

NOTE: All the parameters in the texture state group take effect only when the
      long "Done" button at the bottom of the window is pressed.
	
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Color Combiner
--------------
	This window is pretty simple. It sets a bunch of registers and 
the color combiner equation itself. The muxes in the equation can be
either indivisually set or set by selecting one of the preset values
through the two long menu buttons at the bottom of the window. All widgets
in this window take effect instantaneously (No "Done" button presses
required)

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Blender
-------
	This window is similar to the color combiner window except that it
is wiser to use the preset blender modes that try setting the muxes and
the buttons individually since much of the functionality of the blender is
obscure to say the least.

A note though about the "rgbDither", "alphaDither", "vidAAFilt", "vidDithFilt"
and the "cfbSize32" buttons. There is a dependency here. Since there rgbDither
is only needed in 16-bit frame buffer mode, both the rgbDither and the back-end
dither filter are automatically turned off when 32-bit frame buffer is chosen.

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

NOTES
-----
A pulldown menu can be 'torn' off and placed to one side so that the
menu items can be chosen with a single button click.

KNOWN BUGS
-----------

Switching between trackball and fly modes messes up the trackball controls
at times

Record and playback of mouse position is not always precise.