Texture Overview
------------------

Texture mapping, or texturing, is the process of applying an image
to a polygonal surface. There are many graphics books that discuss
this topic and it is assumed that the user is familiar with
the basic principles of texture mapping.  This document will explain
the functionality of texture mapping as implemented in the Reality
Co-Processor (RCP).

  <Fig 1.  BLOCK DIAGRAM>

<More General Discussion>


Major Modes
-------------

Copy, <Fig 2.  Copy Diagram>
One-cycle, <Fig 3.  One-Cycle Mode diagram> 
Two-cycle, <Fig 4.  Two-Cycle mode diagram>


GBI Texture Commands
----------------------

The graphics binary interface (GBI) is a set of macros
which create 64-bit commands that are read and parsed by
the RSP microcode.  Some of these commands cause actions 
or state changes in the RSP.  Others are simply passed 
through the RSP to the RDP.  Here is a list of GBI commands
concerned with texture.

	<BIG LIST>


Modebits (SetOtherModes) Effecting Texture
--------------------------------------------
	o  cycle_type
	o  pers_tex_enable
	o  detail_tex_enable
	o  sharpen_tex_enable
	o  tex_lod_enable
	o  en_tlut
	o  tlut_type
	o  sample_type
	o  mid_texel
	o  bi_lerp_0
	o  bi_lerp_1
	o  convert_one
	

RDP Commands Effecting Texture
--------------------------------
	o  LoadBlock
	o  LoadTile
	o  LoadTlut
	o  SetOtherModes
	o  SetTextureImage
	o  SetTile
	o  SetTileSize
	o  SyncLoad
	o  SyncTile
	o  TextureRectangle
	o  TextureRectangleFlip
	o  Textured Triangle Commands (0x0a, 0x0e, 0x0b, 0x0f)


Example Display List
----------------------

The following display list fragment uses GBI display list commands
to render an object using a 16-bit RGBA texture map.  The texture 
is loaded into Tmem using the LoadBlock command.  The texture
coordinates are perspective corrected.  Note that the texture is 
allowed to wrap on 32-texel boundaries in the s and t directions.  
The texture filter will bi-linearly interpolate the 2x2 texels
output by the texture unit.  Finally, the resulting texure color is 
multiplied with the object's shade color in the Color Combiner 
for each pixel of the object.

	/* Enable textured poly generation in RSP */
	gSPTexture(glistp++, 0x8000, 0x8000, G_TX_RENDERTILE, G_ON);

	/* Set Texture modes in RDP */
	gDPPipeSync(glistp++);
	gDPSetTextureFilter(glistp++, G_TF_BILERP);
	gDPSetTexturePersp(glistp++, G_TP_PERSP);
	gDPSetCombineMode(glistp++, G_CC_MODULATERGB, G_CC_MODULATERGB);

	/* Load texture block */
	gDPLoadTextureBlock(glistp++, RGBA16dana, G_IM_FMT_RGBA,
                         G_IM_SIZ_16b, 32, 32, 0,
                         G_TX_WRAP | G_TX_NOMIRROR, G_TX_WRAP | G_TX_NOMIRROR,
                         5, 5, G_TX_NOLOD, G_TX_NOLOD);

	/* Render object */
	gSPDisplayList(glistp++, model);



Texture Types
--------------

There are a wide variety of texture types and sizes that can be stored
in the Texture Memory (Tmem).  Each of these has tradeoffs with regard to
texture size, resolution, color, and transparency.

Types: 
	I - Intensity
	IA - Intensity/Alpha
	RGBA - Red/Green/Blue/Alpha
	CI - Color Index
	YUV - Intensity(Y), Blue-Y, Red-Y

Sizes:
	0 - 4 bit
	1 - 8 bit
	2 - 16 bit
	3 - 32 bit

Supported Type/Size Combinations Table:

	<PUT TABLE HERE>


Tile Descriptors
---------------------

The RDP contains an on-chip texture memory called 'Tmem' which buffers all source
image data used for texturing.  Tmem contains up to eight 'tiles', a tile being
a rectangular region of an image.  A tile is loaded into Tmem using the LoadXXX
commands, and described using the SetTileXXX commands.  If the image is too large
to fit in entirely in Tmem, primitives must be subdivided in object space based
on their texture coordinate values so that each primitive references a tile that
fits in Tmem.  In terms of load commands, Tmem looks like a 64-bit by 512 word
memory.  Internally, the memory is arranged as 4 banks of 512 16-bit words with
the low and high half allowing simultaneous access.

The RDP has a small on-chip memory for buffering up to eight tile descriptors
at a time.  A tile descriptor contains all the information for a texture tile
including:


Format:	
	Format of texels in texture tile.  See Texture Types above.

	Format Value	Format
	------------	-------
	  0		RGBA
	  1		YUV
	  2		CI
	  3		IA
	  4		I	

Size:
	Size of texels in texture tile.   See Texture Types above.
	
	Size value	Size (bits)
	---------- 	-------------
	  0		  4
	  1		  8
	  2		  16
	  3		  32

Line:
	Number of 64-bit words in a texel row.  When tiles are loaded using
	the LoadTile command, the rows are padded to 64-bit boundaries.  When
	LoadBlock is used to load a texture, it is assumed that the rows have
	already been padded.

Tmem Adrs:
	Tile offset (0-512) in Tmem (64-bit) words. 

Palette:
	Palette number (0-15) of 4-bit Color Index (CI) textures.  An 8-bit index into
	the high half of Tmem is formed by placing the palette number in the
	4 MSBs and the 4-bit texture index in the 4 LSBs.  The color in Tmem
	at this index becomes the color of the pixel.  Therefore, for a 4-bit CI
	texture, you may select one of 16 palettes with each palette having up to
	16 entries.

Mirror Enable S,T:
	Enables mirroring of texture coordinates.  When the bit indicated by the
	(Mask Value + 1) is 0 the coordinates are unchanged.  When this bit is
	one, however, the coordinates are inverted.  For example, a mask of 2
	with mirror enabled would yield the following texture coordinates:

	Input	0 1 2 3 4 5 6 7 8 9 10 11 ...
	Output  0 1 2 3 3 2 1 0 0 1 2  3  ...
	

Mask S,T:
	Number of bits to 'let through' the mask.  For example, a mask of 1 indicates 
	one bit of the texture coordinate should come through the mask, giving
	a pattern of 0,1,0,1... As another example, a mask value of 5
	indicates the texture should wrap every 32 texels.  A mask value of
	0 forces clamping the texture coordinates to be between (SL,TL),(SH,TH)
	inclusive.  The mask value + 1 indicates the bit position that is looked
	at for mirroring.  See discusion in Mirror Enable above.

Shift S,T:
	Shift texture coordinates after perspective divide.  Used in mipmaps and
	possibly for precision reasons.

	Shift Value(hex)	Shift 
	----------------	-----
	  0			no shift
	  1			>> 1
	  2			>> 2
	  3			>> 3
	  4			>> 4
	  5			>> 5
	  6			>> 6
	  7			>> 7
	  8			>> 8
	  9			>> 9
	  a			>> 10
	  b			<< 5
	  c			<< 4
	  d			<< 3
	  e			<< 2
	  f			<< 1


SL,TL of tile:
	Starting texel column,row of tile in texture image space
	<Draw image coord. picture>

SH,TH of tile:
	Ending texel column,row of tile in texture image space.  Used for 
	clamping only.


Clamp S,T:
	Enable clamp during wrap or mirror.  This bit allows clamping
	the texture coordinates when the mask is non-zero.  For
	example, SH = 12, mask = 2, clamp = 1

	Input 	0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
	Output	0 1 2 3 0 1 2 3 0 1 2  3  0  0  0  0  0



Tile Indices
-----------------

The lod_en mode bit in SetOtherModes determines if tile indices are 
determined using Level fo Detail (LOD) or from the primitive command 
directly.

With LOD _disabled_, the user specifies the texture tile for a primitive
directly (gSPTexture).  In two-cycle mode, the tile index is:

	o  cycle 0:  primitive tile
	o  cycle 1:  primitive tile + 1

This mode is useful when bi-lerping a single texture, or when
interpolating between two arbitrary textures.

With LOD enabled, the tile index is a function of the Level of Detail
attribute (L) of the primitive. This attribute is computed to reflects the 
magnification of the texture in screen space (texel/pixel ratio).  The LOD 
module also calculates an LOD fraction for third axis interpolation between 
mipmaps.  The combination of LOD-derived tile coordinates and fraction, a 
particular tile descriptor arrangement, and tri-linear filtering allows the 
implementation of mipmaps.  Notice that mipmapping is a specialized use of 
the general texture hardware.  Other types of mappings, such as 'sparse mipmaps' 
where all the levels of a mipmap are not present, are possible.  The LOD 
calculation makes the following features (and maybe more) possible:

	o  Trilinear MipMapping
	o  Sparse MipMapping
	o  Sharpened Texture
	o  Detail Texture


The LOD calculation depends on the following inputs:

	o  LOD, level of detail@pixel (texels/pixel), from primitive
	o  MIN_LEVEL, minimum LOD clamp for sharpen or detail modes from
		the SetPrimColor command.
	o  MAX_LEVEL, Number of mipmaps minus one, from primitive
	o  DETAIL_EN, enable detailed texture, from SetOtherModes
	o  SHARP_EN, enable sharpened texture, from SetOtherModes
	o  PRIM_TILE, primitive's tile index
	o  LOD_EN, use LOD indetermining tile indices, otherwise
		use PRIM_TILE (cycle 0) and PRIM_TILE+1 (cycle 1).

The LOD calculation produces the following outputs:

	o  L_FRAC (s,0.8): LOD fraction for 3rd axis interpolation when
		mipmapping
	o  L_TILE (0-7):  tile index into tile memory

The input stepped LOD per pixel is clamped to MIN_LEVEL.  The LOD tile 
index is then calculated using the equation:

	LOD_INDEX = log2((int)LOD_CLAMP)

So, for example, an LOD of 7.5 would be converted to a lod index of 2.  This index
is clamped to MAX_LEVEL and then added to the PRIM_TILE.  For example, the tile
arrangement for a mipmap with PRIM_TILE = 2 and MAX_LEVEL = 3 would look like:

Tile Memory Addresses  0  1  2  3  4  5  6  7
LOD_INDEX                    0  1  2  3

The LOD_FRAC is derived by shifting the clamped LOD to the right by the LOD_INDEX.
For example, an LOD of 7.5 would yeild an LOD_FRAC of 0.875.  The LOD_FRAC
is modified depending on the mode bits DETAIL_EN and SHARP_EN.  Note that
the detail and sharpen modes discussed below are exclusive.  If enabled
simultaneously, the detail mode will override the sharpen mode.  If neither 
DETAIL_EN or SHARP_EN is true, then the LOD_FRAC is passed to the color
combiner unmolested.

To implement trilinear mipmapping, the RDP must be in two-cycle mode.  A tile is 
referenced in each of the cycles and linearly interpolated using the LOD_FRAC in 
the color combiner. The following table summarizes how the tile index is derived
in each cycle:

				Cycle 0				Cycle 1

!LOD				PRIM_TILE			PRIM_TILE+1

Since the LOD is computed once per-vertex, large polygons (like runways) can have 
inaccurate LOD values in the interior. This can be easily solved by tesselating t
large polygons down to smaller polygons.


Sharpen and detail mode change the behavior of the tile index calculation
when magnifying.  The texture is magnified when you get so close to the
primitive that one texel is being applied to many pixels, even using the
highest resolution texture in the mipmap.

			                      Magnifying
				Cycle 0				Cycle 1
LOD & DETAIL			PRIM_TILE+LOD_INDEX		PRIM_TILE+LOD_INDEX+1

LOD & SHARPEN			PRIM_TILE+LOD_INDEX		PRIM_TILE+LOD_INDEX+1

LOD & (!DETAIL & !SHARPEN)	PRIM_TILE+LOD_INDEX		PRIM_TILE+LOD_INDEX

			                    Not Magnifying
				Cycle 0				Cycle 1
LOD & DETAIL			PRIM_TILE+LOD_INDEX+1		PRIM_TILE+LOD_INDEX+2

LOD & SHARPEN			PRIM_TILE+LOD_INDEX		PRIM_TILE+LOD_INDEX+1

LOD & (!DETAIL & !SHARPEN)	PRIM_TILE+LOD_INDEX		PRIM_TILE+LOD_INDEX+1


Also note that the tile index is clamped to MAX_LEVEL when at the coarsest level of
detail.

Even with trilinear mipmapping, textures look blurry under magnification
(i.e. when 0.0 < LOD < 1.0). One way of avoiding this would be to use very
large textures that contain lots of high-frequency detail. But this would
be expensive in Tmem. Detail mode comes into play in magnification. The
finest level of the base texture is combined with a (usually small) detail
texture in such a way as to repeat the detail-texture over the base texture 
several times.  A base-texel would, upon magnification, appear to contain
4 or more detail texels blended in with the base-texel color thus providing 
high-frequency information without having to sacrifice large amounts of Tmem.  
This can be used very effectively for example to provide motion-cues when
close to the terrain.

Detail texture mode is very effective in situations where the high frequency 
information in a texture is similar througout the texture. To convert a 
high-resolution image into a low-resolution image (for the base texture) and a 
detail texture:

o Make the low-res image by shrinking the high-res image to the desired size.
o The high frequency detail can now be extracted by scaling the low-res image
  back to its original size and subtracting it from the high-res image.
o The result is a difference image containing only the high-frequency information
  in the image. Any nxn sub-tile of this can be used as a detail-texture
  This sub-tile should preferably be modified to match across 's' and 't' borders 
  so that when it is repeated on the base-texture, the seams are not visible. Detail
  textures can have a different texel type than the base-texture (subject to Tmem
  restrictions). Often, it is sufficient to use a 4-bit or 8-bit intensity detail-texture.

The  shift field of the tile pointing to the detail texture is used to shift
the incoming 's' and 't' coordinates before indexing into the map. This shift
then determines the base-texel to detail texel ratio. For example if the detail 
tile's shift was set to shift left by 1, (the shift of the finest level of the 
base texture being 0 of course) each base-texel, upon magnification would display 
4 detail-texels blended with the base-texel color. A shift left of 2 would result 
in 16 detail-texels per base- texel and so on. Larger shifts will result in more 
aliasing in the detail-texture since the interpolation will occur between widely 
different magnifications. It should also be kept in mind that the shift values 
compromise between the base-texel to detail-texel ratio and the effectiveness of 
the bilerp operation on the detail texture. This is because the number of fractional 
bits in the 's' and 't' coordinates (s10.5) is limited to 5 bits. Hence a shift left 
of 3 bits will leave only 2 bits of fraction within each texel to do the bilerp.

Detail textures must always be pointed to using PRIM_TILE.  For example, the 
tile arrangement for a mipmap with PRIM_TILE = 2 and MAX_LEVEL = 3 and DETAIL_EN 
would look like:

Tile Memory Addresses  0  1  2  3  4  5  6  7
LOD_INDEX                   Det 0  1  2  3


If DETAIL_EN is true and the LOD is less than 1.0, indicating that the LOD is below
the finest mipmap level, the fraction is a table lookup of the LOD_FRAC.  
Currently, the table lookup is simply identity, so the fraction is 
not modified in detail mode but this may change in a future spin of the RCP.
In order to always have a porion of the base-texture visible, LOD_FRAC is clamped
to be greater than 0.5  This fraction can then be used to interpolate 
between the detail-texture (pointed to by PRIM_TILE) and the base-texture (pointed
to by PRIM_TILE+1). Filtering within the detail-texture can be controlled as usual 
by using the setOtherModes bits to be POINT or BILERP.

Sharpen mode is used in a situation similar to that of detail texture. An image
with high contrast edges has been magnified to the point where the edge details
are becoming blurry.  Sharpen mode increases the apparent sharpness of the texture
edge by inverting the LOD_FRAC. 

       <Sharpen Figures>


	Loading tiles
	Syncing loads


Texture Addressing
---------------------
	Stepped Coordinates
	Perspective Correction
	Conversion from image coords to tile coords
	Operations on tile coords
	  Wrap, Mirror, Clamp
		<Some pictures here>
	Tile Coord to Tmem Addresses
		Sampling Modes (4x1, 2x2, point sample)
		
	Restrictions for types/pipe mode
	

Texture Memory
-----------------
	Loading Textures
		DRAM alignment
		Tmem alignment
		Load Block
		Load Tile
		Load Tlut
		Syncing Loads

	Texture Formats in Tmem
		4,8,16,32-bit; YUV
		<show Tony's diagram>

	Color Index Textures


Texture Formatting
----------------------

In the RDP graphics pipeline, most operations are done on 8-bit per 
component RGBA pixels.  After looking up the texels, the texture unit 
converts them into the 32-bit RGBA format.  The list below describes 
how each type is converted.  Where partial bit fields are shown, the
MSBs of each component are used.

	****** MAKE THIS A TABLE ********

	o  4-bit I (Intensity)
		The I value is replicated to create an 8-bit 
		value <4 I><4 I>.  This value is placed on each 
		of the RGBA channels.  

	o  8-bit I (Intensity)
		The value looked up from Tmem is placed on
		each of the RGBA channels.

	o  4-bit IA (Intensity/Alpha)
		The format of this texel is <3 I><1 A>.  The I value
		is replicated <3 I><3 I><2 I> and placed on the RGB
		channel.  The alpha value is replicated 
		<A><A><A><A><A><A><A><A>.  This value is placed on the
		A channel.

	o  8-bit IA (Intensity/Alpha)
		The format of this texel is <4 I><4 A>.  The I value
		is replicated <4 I><4 I> and placed on the RGB channel.  
		The alpha value is replicated <4 A><4 A>.  This value is 
		placed on the A channel.

	o  16-bit IA (Intensity/Alpha)
		The format of this texel is <8 I><8 A>.  The I value
		placed on the RGB channel.  The alpha value is 
		placed on the A channel.

	o  16-bit RGBA (Red/Green/Blue/Alpha)
		The format for this texel is <5 R><5 G><5 B><1 A>.  The
		red channel is converted from 5 bits to 8 bits <5 R><3 R>.
		The green and blue channel are replicated similarly.  The
		alpha channel is converted from one bit to eight bits as
		<A><A><A><A><A><A><A><A>.
		
	o  32-bit RGBA (Red/Green/Blue/Alpha)
		The format for this texel is <8 R><8 G><8 B><8 A>.  Each
		component is placed directly on its corresponding channel.
		
	o  4-bit CI (Color Index)
		The 4-bit index looked up from Tmem is combined with the
		4-bit palette specified in the tile as <4 pal><4 indx>.  Each
		of the 4 indexes looked up is routed through the lookup table
		in the high half of Tmem.  The lookup table can have a format 
		of either 16-bit RGBA or 16-bit IA as described above.  Since
		the index is 4-bits, one of 16 possible colors can be selected.
		There are 16 possible palettes available.
		
	o  8-bit CI (Color Index)
		The 4 indexes looked up are routed through the lookup table
		in the high half of Tmem.  The lookup table can have a format 
		of either 16-bit RGBA or 16-bit IA as described above.  One
		of 256 possible colors can be selected.
		
	o  16-bit YUV
		The format for this texel is <4 U><4 V><4 Y><4 Y>.
	


Texture Filter
----------------
	Bilinear Interpolation
	Tri-Linear Interpolation
	Color Conversion
	Bi-Linear Filtering and Color Conversion
	MPEG Resampling


Things to Watch Out For
	Nyquist Criterion


	
Related Topics
	Tiling large textures
		LoadTile
		LoadBlock
		Panning/Scrolling
	MipMaps
	Sparse MipMaps
	Cycling Color Maps
	Animating Textures
	Two Arbitrary Textures
	Using shift to Get Precision
	Using shift to control detail texture
	Keep texture coords near map size for perspective divide
	Load S,T for tile not necessarily Render S,T for tile
	Loading one type as another
	Rendering one type as another