From 874d942030ba65ef3677e2d79069e0086cc5f16e Mon Sep 17 00:00:00 2001 From: coco875 <59367621+coco875@users.noreply.github.com> Date: Mon, 17 Jun 2024 03:56:10 +0200 Subject: [PATCH] fix docs --- Doxyfile | 4 ++-- docs/Code/Camera.md | 2 ++ docs/Code/Counters.md | 2 ++ docs/Documentation/Backwards Compatibility.md | 8 ++++--- docs/Documentation/Configuration.md | 14 ++++++------ docs/Documentation/Design Tradeoffs.md | 20 ++++++++++-------- docs/Documentation/Minimal Scanlines.md | 6 ++++-- docs/Documentation/Performance.md | 4 +++- docs/Documentation/Porting your Romhack.md | 12 ++++++----- docs/code.md | 5 +++++ docs/documentation.md | 14 ++++++++++++ docs/{Documentation => }/images/5tris.png | Bin .../images/colorinterp.png | Bin .../images/colorinterp.svg | 0 14 files changed, 63 insertions(+), 28 deletions(-) create mode 100644 docs/code.md create mode 100644 docs/documentation.md rename docs/{Documentation => }/images/5tris.png (100%) rename docs/{Documentation => }/images/colorinterp.png (100%) rename docs/{Documentation => }/images/colorinterp.svg (100%) diff --git a/Doxyfile b/Doxyfile index f92ff58..fbe2a98 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1049,7 +1049,7 @@ FILE_PATTERNS = *.c \ # be searched for input files as well. # The default value is: NO. -RECURSIVE = NO +RECURSIVE = YES # The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a @@ -1108,7 +1108,7 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = images +IMAGE_PATH = docs/images # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program diff --git a/docs/Code/Camera.md b/docs/Code/Camera.md index ef7e61e..b671f36 100644 --- a/docs/Code/Camera.md +++ b/docs/Code/Camera.md @@ -1,3 +1,5 @@ +@page camera Camera + For any game, the idea is to send the camera world position to the RSP whenever you send / apply the view matrix. For OoT, this is not trivial because the game allocates the view matrix at the beginning of the frame and runs diff --git a/docs/Code/Counters.md b/docs/Code/Counters.md index c48e63b..ba59d58 100644 --- a/docs/Code/Counters.md +++ b/docs/Code/Counters.md @@ -1,3 +1,5 @@ +@page counters Performance Counters + This example code is for HackerOoT. The structs and the general method of reading the counters will be the same for any game. The structs are valid though the other code is a little simplistic. A full implementation exists in diff --git a/docs/Documentation/Backwards Compatibility.md b/docs/Documentation/Backwards Compatibility.md index 2b1dc65..6e75320 100644 --- a/docs/Documentation/Backwards Compatibility.md +++ b/docs/Documentation/Backwards Compatibility.md @@ -1,6 +1,8 @@ -## Backwards Compatibility with F3DEX2 +@page compatibility Backwards Compatibility with F3DEX2 -### C GBI Compatibility +# Backwards Compatibility with F3DEX2 + +## C GBI Compatibility F3DEX3 is backwards compatible with F3DEX2 at the C GBI level for all features and commands except: @@ -39,7 +41,7 @@ and commands except: `SPSetLights`, so it is not usually necessary to use `SPLight` and `SPAmbient` at all. -### Binary Display List Compatibility +## Binary Display List Compatibility F3DEX3 is generally binary backwards compatible with OoT-style display lists for objects, scenes, etc. **It is not compatible at the binary level with SM64-style diff --git a/docs/Documentation/Configuration.md b/docs/Documentation/Configuration.md index 8732738..471edd5 100644 --- a/docs/Documentation/Configuration.md +++ b/docs/Documentation/Configuration.md @@ -1,11 +1,13 @@ -## Microcode Configuration +@page microcode Microcode Configuration + +# Microcode Configuration There are several selectable configuration settings when building F3DEX3, which can be enabled in any combination. With a couple minor exceptions, none of these settings affect the GBI--in fact, you can swap between the microcode versions on a per-frame basis if you build multiple versions into your romhack. -### No Occlusion Plane (NOC) +## No Occlusion Plane (NOC) If you are not using the occlusion plane feature in your romhack, you can use this configuration, which removes the computation of the occlusion plane @@ -28,7 +30,7 @@ which version to use on the profiling results from the previous frame: if the RSP is the bottleneck (e.g. the RDP `CLK - CMD` is high), use the NOC version, and otherwise use the base version. -### Legacy Vertex Pipeline (LVP) +## Legacy Vertex Pipeline (LVP) The primary tradeoff for all the new lighting features in F3DEX3 is increased RSP time for vertex processing. The base version of F3DEX3 takes about @@ -75,7 +77,7 @@ However, it retains all other F3DEX3 features: The performance of F3DEX3 vertex processing with both LVP and NOC is almost the same as that of F3DEX2; see the Performance Results section below. -### Profiling +## Profiling As mentioned above, F3DEX3 includes many performance counters. There are far too many counters for a single microcode to maintain, so multiple configurations of @@ -98,14 +100,14 @@ because their removal does not affect the RDP render time. - The `SPLightToRDP` commands are removed (they become no-ops) - Flat shading mode, i.e. `!G_SHADING_SMOOTH`, is removed (all tris are smooth) -### Branch Depth Instruction (`BrZ` / `BrW`) +## Branch Depth Instruction (`BrZ` / `BrW`) Use `BrZ` if the microcode is replacing F3DEX2 or an earlier F3D version (i.e. SM64), or `BrW` if the microcode is replacing F3DZEX (i.e. OoT or MM). This controls whether `SPBranchLessZ*` uses the vertex's W coordinate or screen Z coordinate. -### Debug Normals (`dbgN`) +## Debug Normals (`dbgN`) To help debug lighting issues when integrating F3DEX3 into your romhack, this feature causes the vertex colors of any material with lighting enabled to be set diff --git a/docs/Documentation/Design Tradeoffs.md b/docs/Documentation/Design Tradeoffs.md index f3ed697..8a0b4d8 100644 --- a/docs/Documentation/Design Tradeoffs.md +++ b/docs/Documentation/Design Tradeoffs.md @@ -1,10 +1,12 @@ -## What are the tradeoffs for all these new features? +@page design-tradeoffs Design Tradeoffs -### Vertex Processing RSP Time +# What are the tradeoffs for all these new features? + +## Vertex Processing RSP Time See the Microcode Configuration and Performance Results sections above. -### Overlay 4 +## Overlay 4 (Note that in the LVP configuration, Overlay 4 is absent; there is no M inverse transpose matrix discussed below, and the other commands mentioned below are @@ -80,13 +82,13 @@ It is recommended to use `G_NORMALS_MODE_FAST` (the default) for most things, and use `G_NORMALS_MODE_AUTO` only for objects while they currently have a nonuniform scale (e.g. Mario only while he is squashed). -### Optimizing for RSP code size +## Optimizing for RSP code size A number of optimizations in F3DEX2 which saved a few cycles but took several more instructions have been removed. Outside of vertex processing, these have a very small impact on overall RSP time and no impact on RDP time. -### Far clipping removal +## Far clipping removal Far clipping is completely removed in F3DEX3. Far clipping is not intentionally used for performance or aesthetic reasons in levels in vanilla SM64 or OoT, @@ -102,7 +104,7 @@ microcode option used in OoT. Note that tris are still clipped at the camera plane; nearclipping means they are clipped at the nearplane, which is a short distance in front of the camera plane. -### Removal of scaled vertex normals +## Removal of scaled vertex normals A few clever romhackers figured out that you could shrink the normals on verts in your mesh (so their length is less than "1") to make the lighting on those @@ -133,7 +135,7 @@ with vertex alpha actually used for transparency (therefore also no fog). Note that in LVP mode, scaled normals are supported and work the same way as in F3DEX2, while ambient occlusion is not supported. -### RDP temporary buffers shrinking +## RDP temporary buffers shrinking In FIFO versions of F3DEX2, there are two DMEM buffers to hold RDP commands generated by the microcode, which are swapped and copied to the FIFO in DRAM. @@ -148,7 +150,7 @@ the FIFO is occupied by full-size tris, so the buffers are effectively only two tris in size because a third tri can't fit. So, their size has been reduced to two tris, saving a substantial amount of DMEM. -### Segment 0 +## Segment 0 Segment 0 is now reserved: ensure segment 0 is never set to anything but 0x00000000. In F3DEX2 and prior this was only a good idea (and SM64 and OoT @@ -159,7 +161,7 @@ behavior when supplying a direct-mapped or physical address such as 0x80101000, segment 0 must always be 0x00000000 so that this address resolves to e.g. 0x101000 as expected in this example. -### Obscure semantic differences from F3DEX2 that should never matter in practice +## Obscure semantic differences from F3DEX2 that should never matter in practice - `SPLoadUcode*` corrupts the current M inverse transpose matrix state. If using `G_NORMALS_MODE_FAST`, this doesn't matter. If using `G_NORMALS_MODE_AUTO`, diff --git a/docs/Documentation/Minimal Scanlines.md b/docs/Documentation/Minimal Scanlines.md index 985662c..cf3fa23 100644 --- a/docs/Documentation/Minimal Scanlines.md +++ b/docs/Documentation/Minimal Scanlines.md @@ -1,4 +1,6 @@ -## What happened to the clipping minimal scanlines algorithm? +@page minimal-scanlines What happened to the clipping minimal scanlines algorithm? + +# What happened to the clipping minimal scanlines algorithm? Earlier F3DEX3 versions included a modified algorithm for triangulating the polygon which was formed as the result of clipping. This algorithm broke up the @@ -23,7 +25,7 @@ result of this. To show why this is an unavoidable issue on the N64, here is an example: -![Color interpolation example](images/colorinterp.png) +![Color interpolation example](colorinterp.png) A: The triangle has vertex colors 0, 128, 255 (same for all three color components) as shown. It is clipped off the left side of the screen halfway diff --git a/docs/Documentation/Performance.md b/docs/Documentation/Performance.md index dc54f72..6c9be73 100644 --- a/docs/Documentation/Performance.md +++ b/docs/Documentation/Performance.md @@ -1,4 +1,6 @@ -## Performance Results +@page performance Performance Results + +# Performance Results Vertex pipeline cycles per **vertex pair** in steady state (lower is better). Hand-counted timings taking into account all pipeline stalls and all dual-issue diff --git a/docs/Documentation/Porting your Romhack.md b/docs/Documentation/Porting your Romhack.md index 5c134f8..f7aad1b 100644 --- a/docs/Documentation/Porting your Romhack.md +++ b/docs/Documentation/Porting your Romhack.md @@ -1,4 +1,6 @@ -## Porting Your Romhack Codebase to F3DEX3 +@page porting Porting Your Romhack Codebase to F3DEX3 + +# Porting Your Romhack Codebase to F3DEX3 For an OoT codebase, only a few minor changes are required to use F3DEX3. However, more changes are recommended to increase performance and enable new @@ -31,7 +33,7 @@ similar for other games): - If you start using new features in F3DEX3, make the "Changes required for new features" listed below. -### Required Changes +## Required Changes Both OoT and SM64: @@ -72,7 +74,7 @@ SM64 only: using matrix stack fix and enabling `G_NORMALS_MODE_AUTO` to correct the matrix). -### Recommended Changes (Non-Lighting) +## Recommended Changes (Non-Lighting) - Clean up any code using the deprecated, hacky `SPLookAtX` and `SPLookAtY` to use `SPLookAt` instead (this is only a few lines change). Also remove any @@ -105,7 +107,7 @@ SM64 only: are typically drawn between each material change. For more information, see the GBI documentation near this define. -### Recommended Changes (Lighting) +## Recommended Changes (Lighting) - Change your game engine lighting code to load all lights in one DMA transfer with `SPSetLights`, instead of one-at-a-time with repeated `SPLight` commands. @@ -132,7 +134,7 @@ SM64 only: you will need to redesign how game engine light parameters (e.g. "light radius") map to these parameters. -### Changes Required for New Features +## Changes Required for New Features Each of these changes is required if you want to use the respective new feature, but is not necessary if you are not using it. diff --git a/docs/code.md b/docs/code.md new file mode 100644 index 0000000..130e7c0 --- /dev/null +++ b/docs/code.md @@ -0,0 +1,5 @@ +# Code +You can find more details about camera [here](@ref Camera) and counters [here](@ref Counters). + +@subpage camera +@subpage counters \ No newline at end of file diff --git a/docs/documentation.md b/docs/documentation.md new file mode 100644 index 0000000..44d1bc6 --- /dev/null +++ b/docs/documentation.md @@ -0,0 +1,14 @@ +# Documentation +- [Backwards Compatibility with F3DEX2](@ref compatibility) +- [Microcode Configuration](@ref microcode) +- [Design Tradeoffs](@ref design-tradeoffs) +- [What happened to the clipping minimal scanlines algorithm?](@ref minimal-scanlines) +- [Performance Results](@ref performance) +- [Porting Your Romhack Codebase to F3DEX3](@ref porting) + +@subpage compatibility +@subpage microcode +@subpage design-tradeoffs +@subpage minimal-scanlines +@subpage performance +@subpage porting \ No newline at end of file diff --git a/docs/Documentation/images/5tris.png b/docs/images/5tris.png similarity index 100% rename from docs/Documentation/images/5tris.png rename to docs/images/5tris.png diff --git a/docs/Documentation/images/colorinterp.png b/docs/images/colorinterp.png similarity index 100% rename from docs/Documentation/images/colorinterp.png rename to docs/images/colorinterp.png diff --git a/docs/Documentation/images/colorinterp.svg b/docs/images/colorinterp.svg similarity index 100% rename from docs/Documentation/images/colorinterp.svg rename to docs/images/colorinterp.svg