diff --git a/content/3d_disp_cnt.md b/content/3d_disp_cnt.md index a940c6f..bc244da 100644 --- a/content/3d_disp_cnt.md +++ b/content/3d_disp_cnt.md @@ -21,16 +21,6 @@ This chapter talks about the registers used to control the 3D display. | 14 | Rear plane mode (0=Use clear color, 1=Bitmap) | 15-31 | Unused - -## VIEWPORT: Set 3D viewport (0x4000580, W) - -| Bit(s) | Description | -|--------|---------------------------------------------------------| -| 0-7 | X1: Left-most X coordinate (0...255) -| 8-15 | Y1: Bottom-most Y coordinate (0...191) -| 16-23 | X2: Right-most X coordinate (0...255) -| 24-31 | Y2: Top-most Y coordinate (0...191) - To fill the screen: X1=0, Y1=0, X2=255, Y2=191 Note that coordinate (0, 0) is the bottom-left corner of the screen, while ht is diff --git a/content/3d_geometry_engine.md b/content/3d_geometry_engine.md new file mode 100644 index 0000000..c461eb9 --- /dev/null +++ b/content/3d_geometry_engine.md @@ -0,0 +1,79 @@ +# 3D Geometry Engine + +The Geometry Engine on the Nintendo DS is the hardware responsible for taking in 3D Graphics Commands and coverting them to verticies and polygons which can be rendered by the Rendering Engine. It's jobs include performing various matrix multiplications involving vertex positions, vertex colors, light vectors, etc. + +# Readable Matricies + +The Geometry provides access to the final directional matrix and screen space transformation matrix. (as in, position matricies * projection matrix) Reading these requires the geometry engine to be disabled via bit 27 in the ``GXSTAT`` register. + +## Clip Matrix (0x4000640..=0x400067F, 16 words, R) + +Read the 4x4 "Clip matrix" with cells going from row 0 column 0, row by row. + +## Read Directional Matrix (0x4000680..=0x40006A3, 9 words, R) + +Read the "top left" 3x3 segment of the directional matrix with cells going from row 0 column 0, row by row. + +# 3D Command FIFO +The Geometry engine is heavily based upon a Command FIFO and PIPE used to transfer vertex lists, bind textures, set viewport, modify matricies, etc. The FIFO can be directly accessed by writing command numbers and parameters to memory location ``0x4000400`` or indirectly by writing parameters to the corresponding "Command Ports" at various memory locations from``0x4000440..=0x40005FF``. + +## Using the FIFO indirectly +The simpler and more user friendly method of interacting with the FIFO is via the "Command Ports", where parameters are written to the corresponding memory address for a given command. The command + parameter combo is automatically sent down the FIFO to the 3D hardware once every parameter has been sent. For commands that don't have any parameters one may simply write any value to the port. + +## Using the FIFO directly +When using the FIFO directly, commands are sent by first writing a "Command word" containing up to 4 packed command indicies. Followed by writing the parameters for each command in order. If the last command does not have a parameter, 0 must be written as a dummy parameter in order for the hardware to accept a new "command word". When trying to specify invalid command indicies they will be treated the same as command index 0. (no command, no parameters) This way of using the fifo is better suited to transferring large chunks of commands, such as via DMA. + +### "Command word" definition + +| Bit(s) | Description | +|--------|---------------------------------------------------------| +| 0-7 | Command Index 0 +| 8-15 | Command Index 1 +| 16-23 | Command Index 2 +| 24-31 | Command Index 3 + +#### Notes: +When packing multiple commands you may not leave zeroed indicies (indicating no command) in between non-zeroed indicies. Meaning that when sending one command the top 24 bits must be zero, when sending 2 commands the top 16 bits must be zero, and when sending 3 commands the top 8 bits must be zero. + +## Command Summary + +| Command Index | Port address | Summary | +|---------------|--------------|--------------------------------------| +| 0x10 | 0x0400_0440 | Select Matrix Mode/Matrix Stack +| 0x11 | 0x0400_0444 | Push matrix onto stack +| 0x12 | 0x0400_0448 | Pull matrix from stack +| 0x13 | 0x0400_044C | Store matrix on stack +| 0x14 | 0x0400_0450 | Restore matrix from stack +| 0x15 | 0x0400_0454 | Set current matrix to ``I`` (Unit/Identity matrix) +| 0x16 | 0x0400_0458 | Load 4x4 values into current matrix. +| 0x17 | 0x0400_045C | Load 4x3 values into current matrix. +| 0x18 | 0x0400_0460 | Multiply current matrix by 4x4 Matrix +| 0x19 | 0x0400_0464 | Multiply current matrix by 4x3 Matrix +| 0x1A | 0x0400_0468 | Multiply current matrix by 3x3 Matrix +| 0x1B | 0x0400_046C | Scale current matrix by vector +| 0x1C | 0x0400_0470 | Translate current matrix by vector +| 0x20 | 0x0400_0480 | Set Vertex Color +| 0x21 | 0x0400_0484 | Set Vertex Normal +| 0x22 | 0x0400_0488 | Set Vertex Texture Coordinates +| 0x23 | 0x0400_048C | Set Vertex Position (16-bit) +| 0x24 | 0x0400_0490 | Set Vertex Position (10-bit) +| 0x25 | 0x0400_0494 | Set Vertex XY position +| 0x26 | 0x0400_0498 | Set Vertex XZ position +| 0x27 | 0x0400_049C | Set Vertex YZ position +| 0x28 | 0x0400_04A0 | Set Vertex position relative to the last +| 0x29 | 0x0400_04A4 | Set Vertex Attributes +| 0x2A | 0x0400_04A8 | Set Texture Parameters +| 0x2B | 0x0400_04AC | Set Texture Palette +| 0x30 | 0x0400_04C0 | Set Diffused/Ambient Color +| 0x31 | 0x0400_04C4 | Set Specular/Emissive Color +| 0x32 | 0x0400_04C8 | Set Light Direction +| 0x33 | 0x0400_04CC | Set Light Color +| 0x34 | 0x0400_04D0 | Set Shininess table +| 0x40 | 0x0400_0500 | Start vertex list +| 0x41 | 0x0400_0504 | End vertex list +| 0x50 | 0x0400_0540 | Swap Buffers between geometry and rendering engine +| 0x60 | 0x0400_0580 | Set 3D Viewport +| 0x70 | 0x0400_05C0 | Test view volume against cuboid +| 0x71 | 0x0400_05C4 | Test Position Vector +| 0x72 | 0x0400_05C8 | Test Direction Vector + diff --git a/content/3d_light_commands.md b/content/3d_light_commands.md new file mode 100644 index 0000000..1e13c04 --- /dev/null +++ b/content/3d_light_commands.md @@ -0,0 +1,41 @@ +# 3D Light Commands + +These are the commands which specifies the lighting conditions for any upcoming polygons and verticies. + + +## Set Lights Directional Vector: Port 0x040004C8, Index 0x32, 1 Parameter + +Sets the direction a given light points in. + +Parameter Definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-9 | X coordinate +| 10-19 | Y coordinate +| 20-29 | Z coordinate +| 30-31 | Light Index (0..=3) + +all coordinate parameters are in the same format, as in: 1bit sign + 9 bit fraction. + + +## Set Lights Color: Port 0x040004CC, Index 0x33, 1 Parameter + +Sets the color of a given light. + +Parameter Definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-4 | Red +| 5-9 | Green +| 10-14 | Blue +| 15-29 | Unused +| 30-31 | Light Index (0..=3) + + +## Set Shininess table: Port 0x040004D0, Index 0x34, 32 Parameters + +Sets the contents of a 128-byte shininess table used for specular reflections. transferred 4 entries (bytes) at a time. 0 = least shiny, 255 = most shiny. + +Notes: When the shininess table is disabled, the Rendering Engine will act as if the table is filled with linearly increasing entries from the minimum to the maximum. \ No newline at end of file diff --git a/content/3d_matrix_commands.md b/content/3d_matrix_commands.md new file mode 100644 index 0000000..1390509 --- /dev/null +++ b/content/3d_matrix_commands.md @@ -0,0 +1,128 @@ +# 3D Matrix Commands +On the DS there are multiple matrix operations as well as matrix stacks responsible for calculating the resulting light, normal, and position vectors related to any given vertex. These matrix stacks are: + +* Projection stack (Size: 1, Mode: 0) +* Coordinate stack (Size: 32, Mode: 1,2) +* Directional stack (Size: 32, Mode: 1,2) +* Texture stack: (Size: 1, Mode: 3) + +Mode in this case reffers to what index needs to be sent to CMD 0x10 in order to "select" the given stack. Notice how the coordinate and directional stack share modes 1 and 2. Which indicates how both are changed when in those modes (and also internally share the same stack pointer). The two modes however change both stacks in different ways depending on the commands used. + +When working with the matrix commands, you may often stumble upon the term "Current matrix", which reffers to the matrix at the top of the selected matrix stack(s). + +# Matrix Stack Commands + +Here are the commands which depends on the matrix stack(s): + + +## Set Matrix Mode: Port 0x04000440, Index 0x10, 1 Parameter +Selects the matrix stack which is to be modified + +Parameter Definition: + +| Bit(s) | Description | +|--------|---------------------------------------------------------| +| 0-1 | Mode Index +| 2-31 | Unused + +Possible Mode Indicies: + +| Mode Index | Selected Stack and purpose | +|------------|----------------------------| +| 0 | Selects Projection Matrix, in a traditional MVP matrix this would be the P part. +| 1 | Position and Direction Matrix stack. In a traditional MVP matrix this would be the MV parts. +| 2 | Position and Direction Matrix stack. Primarily used in lighting and test related context. +| 3 | Selects Texture Coordinate Matrix stack. Modifies how texture coordinates are transformed. + + + +## Push Matrix stack: Port 0x04000444, Index 0x11, No Parameter +Pushes the "Current matrix" onto the stack + + +## Pull Matrix stack: Port 0x04000448, Index 0x12, 1 Parameter +Pops N matricies off the current matrix stack + +Parameter Definition: + +| Bit(s) | Description | +|--------|---------------------------------------------------------| +| 0-5 | Ammount of matricies to pop in range -30..=31 (N) +| 6-31 | Unused + +Notes: + +On matrix stacks with a size of 1, the parameter is ignored and 1 is always used. + + +## Store Current Matrix on Stack: Port 0x0400044C, Index 0x13, 1 Parameter +Stores the current matrix on another part of the stack. Leaves the stack pointer unchanged. + +Parameter Definition: + +| Bit(s) | Description | +|--------|---------------------------------------------------------| +| 0-4 | Stack Offset +| 5-31 | Unused + +Note: + +A Stack Offset of 31 causes the stack error flag in the ``GXSTAT`` register to be set. + +On stacks where the size is 1, the parameter is ignored and 0 is always used. + + +## Restore Current Matrix from Stack: Port 0x04000450, Index 0x14, 1 Parameter +Sets the current matrix to the values of another matrix on the stack. Leaves the stack pointer unchanged. + +Parameter Definition: + +| Bit(s) | Description | +|--------|---------------------------------------------------------| +| 0-4 | Stack Offset +| 5-31 | Unused + +Note: + +A Stack Offset of 31 causes the stack error flag in the ``GXSTAT`` register to be set. + +On stacks where the size is 1, the parameter is ignored and 0 is always used. + +# General Matrix Commands + +These are the commands which modify the current matrix: + + +## Load Identity Matrix: Port 0x04000454, Index 0x15, No Parameter +Sets the current matrix to a Unit/Identity matrix. Sometimes denoted as ``I`` or ``1``. + + +## Load 4x4 Matrix: Port 0x04000458, Index 0x16, 16 Parameters +Sets the current matrix to a 4x4 matrix, where each parameter corresponds to a cell in the matrix. Values are loaded row by row. starting at row 0 column 0. + + +## Load 4x3 Matrix: Port 0x0400045C, Index 0x17, 12 Parameters +Sets the current matrix to a 4x3 matrix (padded to a 4x4 matrix which doesn't scale W), where each parameter corresponds to a cell in the matrix. Values are loaded row by row. starting at row 0 column 0. + + +## Multiply 4x4 Matrix: Port 0x04000460, Index 0x18, 16 Parameters +Multiply the current matrix by a 4x4 matrix, where each parameter corresponds to a cell in the matrix. Values are loaded row by row. starting at row 0 column 0. + + +## Multiply 4x3 Matrix: Port 0x04000464, Index 0x19, 12 Parameters +Multiply the current matrix by a 4x3 matrix (padded to a 4x4 matrix which doesn't scale W), where each parameter corresponds to a cell in the matrix. Values are loaded row by row. starting at row 0 column 0. + + +## Multiply 3x3 Matrix: Port 0x04000468, Index 0x1A, 9 Parameters +Multiply the current matrix by a 3x3 matrix (padded to a 4x4 matrix which makes W unnaffected), where each parameter corresponds to a cell in the matrix. Values are loaded row by row. starting at row 0 column 0. + + +## Scale Current Matrix by vector: Port 0x0400046C, Index 0x1B, 3 Parameters +Multiply the current matrix by a scale matrix where each scalar value corresponds to the coordinates in a vector. (W coordinate is always 1) + + +## Translate Current Matrix by vector: Port 0x04000470, Index 0x1C, 3 Parameters +Multiply the current matrix by a translation matrix containing the supplied vector coordinates. + + + diff --git a/content/3d_rendering_engine.md b/content/3d_rendering_engine.md new file mode 100644 index 0000000..98aaafa --- /dev/null +++ b/content/3d_rendering_engine.md @@ -0,0 +1,5 @@ +# 3D Rendering Engine + +The Rendering Engine on the Nintendo DS is responsible for taking in the Vertex And Polygon buffers from the Geometry Engine and constructing frames of video. This can either be displayed as background 0 on the main 2D PPU or captured by the capture unit to be used as a bitmap image. + +The Rendering Engine uses a 48-line "Scanline Cache" as opposed to a full framebuffer containing the entire output of a frame when rendering. \ No newline at end of file diff --git a/content/3d_status_registers.md b/content/3d_status_registers.md new file mode 100644 index 0000000..f165dea --- /dev/null +++ b/content/3d_status_registers.md @@ -0,0 +1,42 @@ +# 3D Display Control + +This chapter talks about the status registers of the 3D hardware. + + +## GXSTAT: Geometry Engine Status Register (0x04000600, mixed R/W) + +| Bit(s) | Description | +|--------|--------------------| +| 0 | Test functions Busy +| 1 | Box Test Result +| 2-7 | unused +| 8-12 | Position & Directional Matrix Stack Pointer +| 13 | Projection Matrix Stack Pointer +| 14 | Matrix Stack Busy +| 15 | Matrix Stack Overflow/Undeflow +| 16-24 | Number of 40-bit entries in Command FIFO +| 25 | FIFO is less than half full +| 26 | FIFO is empty +| 27 | General Busy Flag +| 28-29 | unused +| 30-31 | Command FIFO IRQ (0 = Never, 1 = Less than half full, 2 = Empty, 3 = Reserved) + + +## RAM statistics: Polygon List & Vertex RAM Count (0x04000604, R) + +| Bit(s) | Description | +|--------|--------------------| +| 0-11 | Number of Polygons currently in Polygon List RAM +| 12-15 | unused +| 16-28 | Number of Verticies currently in Vertex RAM +| 29-31 | unused + +Note: Once a buffer swap has been sent, the counters are reset 10 cycles after V-Blank. + +## Performance Statistics (0x04000320, R) + +| Bit(s) | Description | +|--------|--------------------| +| 0-5 | Minimum number of buffered lines during last frame - 2 +| 6-31 | unused + diff --git a/content/3d_test_commands.md b/content/3d_test_commands.md new file mode 100644 index 0000000..546965f --- /dev/null +++ b/content/3d_test_commands.md @@ -0,0 +1,55 @@ +# 3D Test Commands + +These Commands test various parameters against desired results by the user. Each command requires that the "test busy" bit of the ``GXSTAT`` register is cleared before reading the result. + + +## Test if Cuboid Intersects View Volume: Port 0x040005C0, Index 0x70, 3 Parameters + +The result of this command can be read from bit 1 of the ``GXSTAT`` register and indicates if any part of the specified cuboid intesects the view volume. A value of 1 indicates that the cuboid would have been visible if drawn. + +Parameter definition: + +| Parameter | Bit(s) | Description | +|-----------|--------|-------------| +| 1 | 0-15 | Origin X coordinate +| 1 | 16-31 | Origin Y coordinate +| 2 | 0-15 | Origin Z coordinate +| 2 | 16-31 | Width (X-Offset) +| 3 | 0-15 | Height (Y-Offset) +| 3 | 16-31 | Depth (Z-Offset) + +all parameters are in the same format as 16 bit vertex coordinates. As in, 1bit sign + 3 bit integer + 12 bit fraction. + + +## Set Coordinates for Position Test: Port 0x040005C4, Index 0x71, 2 Parameters + +Takes the vector ``(x,y,z,1)`` and multiplies by the positional and projection matrix stacks. Result can be read from the memory region at ``0x04000620..=0x0400062F`` where each word corresponds to a coordinate of the resulting vector. In format 1bit sign + 19 bit integer + 12 bit fraction. + +Parameter Definition: + +| Parameter | Bit(s) | Description | +|-----------|--------|-------------| +| 1 | 0-15 | X coordinate +| 1 | 16-31 | Y coordinate +| 2 | 0-15 | Z coordinate +| 2 | 16-31 | Unused + +all parameters are in the same format as 16 bit vertex coordinates. As in, 1bit sign + 3 bit integer + 12 bit fraction. + +Notes: This command should not be issued while a vertex list is being constructed. As any vertex position commands that inherit the coordinates of the previous vertex will instead inherit the coordinates set by this command. + + +## Set Directional vector for Direction Test: Port 0x040005C8, Index 0x72, 1 Parameter + +Takes the vector ``(x,y,z,0)`` and multiplies by the directional matrix stack. (according to no$ also requires matrix mode 2?) Result can be read from the memory region at ``0x04000630..=0x04000635`` where each 2byte half word corresponds to a coordinate of the resulting vector. In format 4bit sign + 12 bit fraction. (sign is either ``0b0000`` or ``0b1111``) + +Parameter Definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-9 | X coordinate +| 10-19 | Y coordinate +| 20-29 | Z coordinate +| 30-31 | Unused + +all parameters are in the same format as those for other light direction commands, as in: 1bit sign + 9 bit fraction. \ No newline at end of file diff --git a/content/3d_vertex_polygon_commands.md b/content/3d_vertex_polygon_commands.md new file mode 100644 index 0000000..054c9d6 --- /dev/null +++ b/content/3d_vertex_polygon_commands.md @@ -0,0 +1,301 @@ +# Vertex and Polygon Commands + +This chapter explains the various commands used to send verticies to the 3D hardware in order to construct polygons. On top of this theres also basic lighting, materials, and texture mapping attributes. The DS 3D hardware natively supports constructing both triangles and quadrilaterals (which should not self intersect or have concavities). + +## Usage Overview +Verticies, as well as edges and polygons are to be constructed on the 3D hardware in the following manner: + +1. Set Polygon attributes + +2. Start a vertex list, where the parameter passed to the start command dictates the type of polygons you wish to construct (Seperated or Connected, Tris or Quads) + +3. For each vertex, set relevant vertex attributes in any order. Setting any coordinate of the vertex position sends it to the 3D hardware. Attributes that are left unset will use the values of the previous vertex. + +4. End the vertex list. + +Notice here that the 3D hardware does not natively support index lists for constructing polygons, +only a vertex list that constructs either seperated or connected "strips" of primitives. Another +quirk of the 3D hardware is that the last step is optional, as vertex lists are automatically +ended when a new one begins or the geometry and rendering engine buffers are swapped. It may +still be useful however to manually end it for debugging purposes and the sake of "Completeness". + + + + + + +# Vertex List Commands +Commands used to start and end vertex lists, as well as commands which can only be used once per vertex list. + + +## Start Vertex List: Port 0x04000500, Index 0x40, 1 Parameter +Parameter definition: + +| Bit(s) | Description | +|--------|-------------| +| 0 | Primitive Type (0 = triangle, 1 = quadrilateral) +| 1 | Primitive Topology (0 = seperated, 1 = strips) + + +## End Vertex List: Port 0x04000504, Index 0x41, 0 Parameters +Ends a vertex list, as previously discussed this command is optional, and only require for the sake of debugging + + +## Polygon Attributes: Port 0x040004A4, Index 0x29, 1 Parameter +Sets various miscallenous attributes for polygons created by the next vertex list. + +Parameter definition: + +| Bit(s) | Description | +|--------|-------------| +| 0 | Enable Light 0 +| 1 | Enable Light 1 +| 2 | Enable Light 2 +| 3 | Enable Light 3 +| 4-5 | Polygon Mode (0 = Modulation, 1=Decal, 2=Toon, 3=Shadow) +| 6 | Render Backface +| 7 | Render Frontface +| 8-10 | Unused +| 11 | Set new depth for translucent pixels +| 12 | Render Far-Plane intersecting polygons +| 13 | Render 1-Dot polygons behind 1-Dot depth +| 14 | Depth test (0 = less than, 1 = equal) +| 15 | Enable Fog +| 16-20 | Alpha (0 = Wireframe, 1..30 = Translucent, 31 = Solid) +| 21-23 | Unused +| 24-29 | Polygon ID +| 30-31 | Unused + +Notes: If a polygon attribute command is sent while a vertex list is ongoing, it will be deffered until next time a vertex list is begun. (Repeated calls will not stack, only the last written one will be used) Changes in lighting related attributes will not change until a new normal vector is set/calculated. + + + + + +# Vertex Attribute Commands +These are the commands for various attributes which can be applied to a vertex. + + +## Set Vertex Color: Port 0x04000480, Index 0x20, 1 Parameter +Sets the vertex color used for the next vertex. + +Parameter definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-4 | Red +| 5-9 | Green +| 10-14 | Blue +| 15-31 | Unused + + + +## Set Normal Vector: Port 0x04000484, Index 0x21, 1 Parameter +Sets the "normal vector" used for the next vertex. In reality this will use the currently set light parameters to calculate a new vertex color. + +Parameter definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-9 | Vertex X coordinate (sign + 9 bit fraction) +| 10-19 | Vertex Y coordinate (sign + 9 bit fraction) +| 20-29 | Vertex Z coordinate (sign + 9 bit fraction) +| 30-31 | Unused + + +## Set Texture Coordinates: Port 0x04000488, Index 0x22, 1 Parameter +Sets the UV / ST coordinates for the next vertex. 16 units = 1 texel + +Parameter definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-15 | S/U coordinate (signed, 4 bit fraction) +| 16-31 | T/V coordinate (signed, 4 bit fraction) + + +## Set Texture Parameters: Port 0x040004A8, Index 0x2A, 1 Parameter +Binds a texture to the upcoming verticies, along with various texture attributes. + +Parameter definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-15 | Texture VRAM offset (in steps of 8) +| 16 | Repeat Horizontally (0 = Clamp, 1 = Repeat) +| 17 | Repeat Vertically (0 = Clamp, 1 = Repeat) +| 18 | Flip on horizontal repeat (see notes.) +| 19 | Flip on Vertical repeat (see notes.) +| 20-22 | Horizontal size (see notes.) +| 23-25 | Vertical size (see notes.) +| 26-28 | Texture Format (see notes.) +| 29 | Set color 0 to transparent +| 30-31 | Texture Coordinate transformation mode (see notes.) + +Notes: + +Texture size is calculated as (8 << N) pixels where N is the specified size. Meaning possible resulting values are 8,16,32,64,128,256,512,1024. + +Texture flipping on repeats requires that repeats are on. + +When a Texture is clamped, the outmost edge pixels are stretched across any out of bounds pixels. + +The various Texture Formats are as follows: + +| Index | Description | +|-------|-------------| +| 0 | No texture +| 1 | A315 Translucent Texture +| 2 | 4-Color Paletted texture +| 3 | 16-Color Paletted texture +| 4 | 256-Color Paletted texture +| 5 | Compressed Texture +| 6 | A513 Translucent texture; +| 7 | Bitmap Texture (R5G5B5) + +Texture Coordinate Transformation Modes: + +| Index | Description | +|-------|-------------| +| 0 | No transformation +| 1 | Texture Coordinate Source +| 2 | Normal Source +| 3 | Vertex Source + + + +## Set Texture Color Palette: Port 0x040004AC, Index 0x2B, 1 Parameter +Set the color palette used for the currently binded texture. Ignored by non-palette based textures. + +Parameter Definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-12 | Texture Palette VRAM offset (see notes.) +| 13-31 | Ignored + +Notes: When using 4-color paletted textures the offset is calculated in steps of 8. In any other cases it's steps of 16. + + +## Diffuse/Ambient Properties: Port 0x040004C0, index 0x30, 1 Parameter +Sets the Diffused/Ambient properties for the next vertex. + +Parameter definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-4 | Diffuse Reflection (Red channel) +| 5-9 | Diffuse Reflection (Green channel) +| 10-14 | Diffuse Refletcion (Blue channel) +| 15 | Set Diffuse reflection as vertex color (0 = No, 1 = Yes) +| 16-20 | Ambient Reflection (Red Channel) +| 21-25 | Ambient Reflection (Green channel) +| 26-30 | Ambient Reflection (Blue channel) +| 31 | Unused + + +## Specular/Emissive Properties: Port 0x040004C4, index 0x31, 1 Parameter +Sets the Specular/Emissive properties for the next vertex. + +Parameter definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-4 | Specular Reflection (Red channel) +| 5-9 | Specular Reflection (Green channel) +| 10-14 | Specular Refletcion (Blue channel) +| 15 | Use shininess table (0 = No, 1 = Yes, see chapter on other commands for shininess table details) +| 16-20 | Emission (Red Channel) +| 21-25 | Emission (Green channel) +| 26-30 | Emission (Blue channel) +| 31 | Unused + + + + + +# Vertex Position Commands +All of these commands send a new vertex to the geometry engine once executes. +Unless stated otherwise, the vertex coordinates will be a 16bit signed integer +with a 12bit fraction. (i.e Range is +7.99 to -8.00) + + +## Position Set (16-bit): Port 0x0400048C, Index 0x23, 2 Parameters +Set all coordinates of the next vertex at once. + +Parameter Definition: + +| Parameter | Bit(s) | Description | +|-----------|--------|-------------| +| 1 | 0-15 | Vertex X coordinate +| 1 | 16-31 | Vertex Y coordinate +| 2 | 0-15 | Vertex Z coordinate +| 2 | 16-31 | Unused + + +## Position Set (10-bit): Port 0x04000490, Index 0x24, 1 Parameter +Set all coordinates of the next vertex at once, but with less accuracy. + +Parameter Definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-9 | Vertex X coordinate (signed, 6 bit fraction) +| 10-19 | Vertex Y coordinate (signed, 6 bit fraction) +| 20-29 | Vertex Z coordinate (signed, 6 bit fraction) +| 30-31 | Unused + + +## Position Set XY: Port 0x04000494, Index 0x25, 1 Parameter +Set X and Y coordinate of the next vertex. + +Parameter Definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-15 | Vertex X coordinate +| 16-31 | Vertex Y coordinate + + +## Position Set XZ: Port 0x04000498, Index 0x26, 1 Parameter +Set X and Z coordinate of the next vertex. + +Parameter Definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-15 | Vertex X coordinate +| 16-31 | Vertex Z coordinate + + +## Position Set YZ: Port 0x0400049C, Index 0x27, 1 Parameter +Set Y and Z coordinate of the next vertex. + +Parameter Definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-15 | Vertex Y coordinate +| 16-31 | Vertex Z coordinate + + +## Position Set Relative: Port 0x040004A0, Index 0x28, 1 Parameter +Set all coordinates of the next vertex at once, but relative to the last vertex. + +Parameter Definition: + +| Bit(s) | Description | +|--------|-------------| +| 0-9 | Vertex X coordinate (signed, 12 bit fraction, see notes.) +| 10-19 | Vertex Y coordinate (signed, 12 bit fraction, see notes.) +| 20-29 | Vertex Z coordinate (signed, 12 bit fraction, see notes.) +| 30-31 | Unused + +Note: As the value is smaller than the fraction, the relative range is very small (+-0.125) + + + + + + + diff --git a/content/3d_vital_commands.md b/content/3d_vital_commands.md new file mode 100644 index 0000000..79712e2 --- /dev/null +++ b/content/3d_vital_commands.md @@ -0,0 +1,33 @@ +# Vital 3D Hardware Commands +This chapter will go over the various commands required to be able to display graphics on the 3D hardware. + + +## Swap buffers: Port 0x4000540, Index 0x50, 1 Parameter + +Swaps the buffers used between the rendering engine, and the geometry engine. + +| Bit(s) | Description | +|--------|---------------------------------------------------------| +| 0 | Y Sorting for translucent polygons (0=Automatic, 1=Manual) +| 1 | Depth buffering (0 = using Z value, 1 = using W value) +| 2-31 | unused + + + +## Set 3D viewport: Port 0x4000580, Index 0x60, 1 Parameter + +Sets the region of the screen which the 3D hardware may render to. + +| Bit(s) | Description | +|--------|---------------------------------------------------------| +| 0-7 | X1: Left-most X coordinate (0...255) +| 8-15 | Y1: Bottom-most Y coordinate (0...191) +| 16-23 | X2: Right-most X coordinate (0...255) +| 24-31 | Y2: Top-most Y coordinate (0...191) + +Notes: + +Due to a misimplementation in the hardware, polygons can still be rendered one pixel beyond (X2, Y1) + +Setting the viewport should be reserved to only be done once per frame or once before the beginning of a vertex list. + diff --git a/content/SUMMARY.md b/content/SUMMARY.md index 2fbae78..a4da777 100644 --- a/content/SUMMARY.md +++ b/content/SUMMARY.md @@ -8,6 +8,15 @@ * [DS 2D Graphics](ds_2d_graphics.md) * [DS 3D Graphics](ds_3d_graphics.md) * [3D Display Control](3d_disp_cnt.md) + * [3D Status Registers](3d_status_registers.md) + * [3D Geometry Engine](3d_geometry_engine.md) + * [Vital Commands](3d_vital_commands.md) + * [Vertex Commands](3d_vertex_polygon_commands.md) + * [Matrix Commands](3d_matrix_commands.md) + * [Light Commands](3d_light_commands.md) + * [Test Commands](3d_test_commands.md) + * [3D Rendering Engine](3d_rendering_engine.md) + * [DS Sound](ds_sound.md) * [DS Peripherals](ds_peripherals.md) * [DS WiFi (Mitsumi)](ds_wifi.md)