F3DEX2

From z64 wiki
Jump to: navigation, search

Introduction

(add intro to rsp, dlists, etc. here)

Note: This article has been written from the point of view of a ROM hacker. Function information is given in the context of interpreting and modifying model data from the Zelda games, not necessarily in that of writing an accurate RSP emulator.

Command List

Certain commands used in the Zelda games are in their function or syntax unique to the F3DZEX microcode, while others are basic commands understood by all microcodes of the Fast3D series. Function names in the following list are derived from the glN64 video plugin's source code; shared commands are prefixed with "G_".

ID Name Function
0x01 F3DEX2_VTX Fills the vertex buffer with vertex information (ex. coordinates, color values)
0x02 F3DEX2_MODIFYVTX Allows modification of texture coordinates and color values of one vertex
0x03 F3DEX2_CULLDL (usage unknown)
0x04 F3DEX2_BRANCH_Z (usage unknown)
0x05 F3DEX2_TRI1 Renders one triangle according to the vertices inside the vertex buffer
0x06 F3DEX2_TRI2 Renders two triangles according to the vertices inside the vertex buffer
0x07 F3DEX2_QUAD Renders one quad according to the vertices inside the vertex buffer
(0x08 to 0xD2 unused)
0xD3 F3DEX2_SPECIAL_3 (usage unknown)
0xD4 F3DEX2_SPECIAL_2 (usage unknown)
0xD5 F3DEX2_SPECIAL_1 (usage unknown)
0xD6 F3DEX2_DMA_IO (usage unknown)
0xD7 F3DEX2_TEXTURE Sets the texture scaling factor
0xD8 F3DEX2_POPMTX (usage unknown)
0xD9 F3DEX2_GEOMETRYMODE Enables or disables certain geometry parameters (ex. lighting, front-/backface culling, Z-buffer)
0xDA F3DEX2_MTX (usage unknown)
0xDB F3DEX2_MOVEWORD (usage unknown)
0xDC F3DEX2_MOVEMEM (usage unknown)
0xDD F3DEX2_LOAD_UCODE (usage unknown)
0xDE F3DEX2_DL Signifies the start of a Display List
0xDF F3DEX2_ENDDL Terminates the current Display List
0xE0 F3DEX2_SPNOOP (usage unknown)
0xE1 F3DEX2_RDPHALF_1 Executes another Display List and returns to the current afterwards
0xE2 F3DEX2_SETOTHERMODE_L Sets other attributes (blending)
0xE3 F3DEX2_SETOTHERMODE_H Sets other attributes (combiner)
0xE4 G_TEXRECT (usage unknown)
0xE5 G_TEXRECTFLIP (usage unknown)
0xE6 G_RDPLOADSYNC (usage unknown)
0xE7 G_RDPPIPESYNC (usage unknown)
0xE8 G_RDPTILESYNC (usage unknown)
0xE9 G_RDPFULLSYNC (usage unknown)
0xEA G_SETKEYGB (usage unknown)
0xEB G_SETKEYR (usage unknown)
0xEC G_SETCONVERT (usage unknown)
0xED G_SETSCISSOR (usage unknown)
0xEE G_SETPRIMDEPTH (usage unknown)
0xEF G_RDPSETOTHERMODE (usage unknown)
0xF0 G_LOADTLUT Loads a palette to use for CI-type textures
0xF1 F3DEX2_RDPHALF_2 (usage unknown)
0xF2 G_SETTILESIZE Sets the texture coordinates and size
0xF3 G_LOADBLOCK (usage unknown)
0xF4 G_LOADTILE (usage unknown)
0xF5 G_SETTILE Sets the texture properties (ex. mirroring)
0xF6 G_FILLRECT (usage unknown)
0xF7 G_SETFILLCOLOR (usage unknown)
0xF8 G_SETFOGCOLOR Sets the fog color
0xF9 G_SETBLENDCOLOR Sets the blend color for combiner
0xFA G_SETPRIMCOLOR Sets the primitive color for combiner
0xFB G_SETENVCOLOR Sets the environment color for combiner
0xFC G_SETCOMBINE Performs combining operations (ex. multi-texturing)
0xFD G_SETTIMG Sets the texture image offset
0xFE G_SETZIMG (usage unknown)
0xFF G_SETCIMG (usage unknown)

Vertex Structure

xxxxyyyyzzzz0000uuuuvvvvrrggbbaa
-xxxx: X Position of vertex
-yyyy: Y Position of vertex
-zzzz: Z Position of vertex
-uuuu: X texture stretch along vertex
-vvvv: Y texture stretch along vertex
-rr: Red channel of vertex, used for vertex colors and/or normals
-gg: Green channel of vertex, used for vertex colors and/or normals
-bb: Blue channel of vertex, used for vertex colors and/or normals
-aa: Alpha channel of vertex, used in vertex colors, ignored in vertex normals

Command Syntax

0x01: F3DEX2_VTX

Syntax
01aaabbb ccdddddd
- aaa: (bbb -) Where to start writing vertices inside the vertex buffer
- bbb: Amount of vertices to write (* 2)
- cc: RAM bank in which vertices are stored
- dddddd: Offset at which vertices are stored in RAM bank

Example
0100701C 03000780: Load 14 (0x01C / 2) vertices from 0x03000780 - offset 0x780 inside bank 0x03 (current map data) - and put them into the vertex buffer, starting at position 7 (14 vertices - 7).

0x05: F3DEX2_TRI1

Syntax
05aabbcc XXXXXXXX
- aa: First vertex to use for the triangle (* 2)
- bb: Second vertex to use for the triangle (* 2)
- cc: Third vertex to use for the triangle (* 2)
- XXXXXXXX: (unused)

Example
05000204 00000000: Render a triangle using the vertex data specified at the vertex buffer positions 0, 1 (0x02 / 2) and 2 (0x04 / 2).

0x06: F3DEX2_TRI2

Syntax
06aabbcc XXddeeff
- aa: First vertex to use for the first triangle (* 2)
- bb: Second vertex to use for the first triangle (* 2)
- cc: Third vertex to use for the first triangle (* 2)
- XX: (unused)
- aa: First vertex to use for the second triangle (* 2)
- bb: Second vertex to use for the second triangle (* 2)
- cc: Third vertex to use for the second triangle (* 2)

Example
06000204 00000406: Render a triangle using the vertex data specified at the vertex buffer positions 0, 1 (0x02 / 2) and 2 (0x04 / 2), and render a second triangle using the vertex data specified at the vertex buffer positions 0, 2 (0x04 / 2) and 3 (0x06 / 2).

0x07: F3DEX2_QUAD

Syntax
07aabbcc XXddeeff
- aa: First vertex to use for the quad (* 2)
- bb: Second vertex to use for the quad (* 2)
- cc: Third vertex to use for the quad (* 2)
- XX: (unused)
- aa: Fourth vertex to use for the quad (* 2)
- bb: Fifth vertex to use for the quad (* 2)
- cc: Sixth vertex to use for the quad (* 2)

Example
07000204 00000406: Render a quad using the vertex data specified at the vertex buffer positions 0, 1 (0x02 / 2), 2 (0x04 / 2), 0, 2 (0x04 / 2) and 3 (0x06 / 2).

0xD7: F3DEX2_TEXTURE

Examples

A simple triangle

F3DZEX Example Triangle.png

Address   Data
00000000: 00000000 00000000 00000000 FF0000FF /*First vertex. x, y, z=(0,0,0), u, v=(0,0), r,g,b,a = (255,0,0,255)*/
00000010: 00640000 00000000 00000000 00FF00FF /*Second vertex. x, y, z=(100,0,0), u, v=(0,0), r,g,b,a = (0,255,0,255)*/
00000020: 00000064 00000000 00000000 0000FFFF /*Third vertex. x, y, z=(0,100,0), u, v=(0,0), r,g,b,a = (0,0,255,255)*/
00000030: 01003006 06000000 05000204 00000000 /*The 0x1 loads the vertecies into the vertex buffer. The 0x5 command draws a
                                                triangle out of these vertecies*/
00000040: DF000000 00000000 00000000 00000000 /*Indicates end display list*/

A simple cube

F3DZEX Example Cube.png

Address   Data
00000000: FF80FF80 00800000 00000000 FFFF00FF /* First Vertex. xyz(-128,-128,128), uv(0,0), rgb(255,255,0,255) */
00000010: 0080FF80 00800000 00000000 00FF00FF /* Second Vertex.  xyz(128,-128,128), uv (0,0), rgb(0,255,0,255) */
00000020: 00800080 00800000 00000000 000000FF /* Third Vertex. xyz(128,128,128), uv(0,0), rgb(0,0,0,255) */
00000030: FF800080 00800000 00000000 FF0000FF /* Fourth Vertex. xyz(-128,128,128), uv(0,0), rgb(255,0,0,255) */
00000040: FF80FF80 FF800000 00000000 FFFFFFFF /* Fifth Vertex. xyz(-128,-128,-128), uv(0,0), rgb(255,255,255,255) */
00000050: 0080FF80 FF800000 00000000 00FFFFFF /* Sixth Vertex. xyz(128,-128,-128), uv(0,0), rgb(0,255,255,255,255) */
00000060: 00800080 FF800000 00000000 0000FFFF /* Seventh Vertex. xyz(128,128,-128), uv(0,0), rgb(0,0,255,255) */
00000070: FF800080 FF800000 00000000 FF00FFFF /* Eighth Vertex. xyz(-128,128,-128), uv(0,0), rgb (255,0,255,255) */
00000080: 01008010 06000000 06000204 00000406 /* 0x1 command loads verticies, 0x6 command draws a quad. First Face. First Triangle
                                                 VBP (0,1,2) | 2nd Triangle (0,2,3) */
00000090: 06000802 0002080A 0600060E 00000E08 /* Second Face. 1st Triangle VBP (0,4,1) | 2nd Triangle VBP (1,4,5). Third Face. 1st
                                                 Triangle VBP (0,3,7)  2nd Triangle VBP (0,7,4)*/
000000A0: 06080E0C 00080C0A 06020A0C 0004020C /* Fourth Face. 1st Triangle VBP (4,7,6) | 2nd Triangle VBP (4,6,5). Fifth Face. 1st
                                                 Triangle VBP (1,5,6) | 2nd Triangle VBP (2,1,5)*/
000000B0: 0606040E 000C0E04 DF000000 00000000 /* Sixth Face. 1st Triangle VBP (3,2,7) | 2nd Triangle VBP (6,7,2). 0xDF command
                                                 indicates end display list */