Files
mk64/controlflow.html
T

335 lines
21 KiB
HTML

<!-- HTML header for doxygen 1.10.0-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.11.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Mario Kart 64: Codebase Overview</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
<link href="doxygen-awesome-sidebar-only.css" rel="stylesheet" type="text/css"/>
<link href="doxygen-awesome-sidebar-only-darkmode-toggle.css" rel="stylesheet" type="text/css"/>
<link href="docs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="doxygen-awesome-darkmode-toggle.js"></script>
<script type="text/javascript">
DoxygenAwesomeDarkModeToggle.init()
</script>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">Mario Kart 64
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.11.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() { codefold.init(0); });
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search',true);
$(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function(){initNavTree('controlflow.html',''); initResizable(true); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div><div class="header">
<div class="headertitle"><div class="title">Codebase Overview</div></div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#paradigm">Paradigm</a></li>
<li class="level1"><a href="#threading">Threading</a></li>
<li class="level1"><a href="#overall-control-flow">Overall Control Flow</a></li>
<li class="level1"><a href="#segments">Segments</a></li>
<li class="level1"><a href="#code-breakdown">Code Breakdown</a><ul><li class="level2"><a href="#menus">Menus</a></li>
<li class="level2"><a href="#players">Players</a></li>
<li class="level2"><a href="#actors-1">Actors</a></li>
<li class="level2"><a href="#objects-1">Objects</a></li>
<li class="level2"><a href="#courses">Courses</a><ul><li class="level3"><a href="#course-folder">Course Folder</a></li>
</ul>
</li>
<li class="level2"><a href="#ui--other-2d-screen-data">UI &amp; Other 2D Screen data</a></li>
<li class="level2"><a href="#engine">Engine</a></li>
<li class="level2"><a href="#math">Math</a></li>
<li class="level2"><a href="#ending">Ending</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="paradigm"></a>
Paradigm</h1>
<p>The developers wrote mk64 using a state-driven paradigm. Gamestate, gamemode, course, actors, structs, and more decide which branches code should follow. As an example, a condition can check the current course to load that courses resources or run logic based on that.</p>
<h1><a class="anchor" id="threading"></a>
Threading</h1>
<p>After boot, the game begins by setting up its four threads; <a class="el" href="main_8c.html#a1e35d2b842121e6aea373f09381616e5">idle</a>, <a class="el" href="main_8c.html#a023b8f272e4efbd33f371e91ffff6b30">video</a>, <a class="el" href="main_8c.html#adc4ddc4dba28c4eebe8a7c28e5559b11">audio</a>, and the <a class="el" href="main_8c.html#a633ed517e458daeb768f5361895dcac9">game loop</a>.</p>
<p>The <a class="el" href="main_8c.html#a1e35d2b842121e6aea373f09381616e5">idle thread</a> allows the cpu to sleep. Without it, if at any time execution of all threads were paused, the cpu would never be able to continue. The idle thread is active if all the other threads are paused.</p>
<p>As such, the <a class="el" href="main_8c.html#a1e35d2b842121e6aea373f09381616e5">idle thread</a> runs the following loop: <code>while(true);</code> (it runs in a perpetual loop of nothing; sleep). In mips assembly it looks like this:</p>
<div class="fragment"><div class="line">.L800005B8:</div>
<div class="line">b .L800005B8</div>
<div class="line">nop</div>
</div><!-- fragment --><p>b stands for branch which acts akin to a goto. In this case, branch to the label <code>.L800005B8</code>. This creates an infinite loop. Whenever the cpu branches it always runs the next instruction as well which is called a delay slot. This means the cpu will continuously branch then run <code>nop</code> or <code>no operation</code> with no method of escaping the loop (except for when another thread has a higher priority which means the cpu switches to that thread and stops running the idle thread).</p>
<p>N64 threads are ran based on priority running whichever thread holds the most of it. Threads can also pause and wait for events. <a class="el" href="structNote.html">Note</a> that the N64 is not multi-threaded by modern standards as the other threads contain specific purposes which slightly differs from the concept of splitting a single program into multiple processes for efficiency.</p>
<h1><a class="anchor" id="overall-control-flow"></a>
Overall Control Flow</h1>
<p>order of initialisation of thread: boot:</p>
<ul>
<li>init_threads:<br />
<ul>
<li><a class="el" href="main_8c.html#a1e35d2b842121e6aea373f09381616e5">idle</a>, <a class="el" href="main_8c.html#a023b8f272e4efbd33f371e91ffff6b30">video</a>, <a class="el" href="main_8c.html#adc4ddc4dba28c4eebe8a7c28e5559b11">audio</a>, <a class="el" href="main_8c.html#a633ed517e458daeb768f5361895dcac9">game loop</a><br />
</li>
</ul>
</li>
<li><a class="el" href="main_8c.html#a633ed517e458daeb768f5361895dcac9">game loop</a>:<br />
<ul>
<li><a class="el" href="main_8c.html#adc4ddc4dba28c4eebe8a7c28e5559b11">audio</a><br />
</li>
<li><a class="el" href="main_8c.html#ad0625ed56ac663d3ec7ae8f1ba50c735">jumpTo a specific menu or race based on a gameState flag.</a><br />
</li>
<li><a class="el" href="profiler_8c.html#ad822f08530dc02ebea867b58f6b2cf5b">profiler</a><br />
</li>
<li><a class="el" href="main_8c.html#a9b253735194a23ab701e8ab9cdc7b128">config_gfx_pool</a><br />
</li>
<li><a class="el" href="main_8c.html#a5443032971be2eac69c7590d16e515b4">read_controllers</a><br />
</li>
<li><a class="el" href="main_8c.html#ae04143ce8113cdafa007c642eb620bc8">game_state_handler</a><br />
</li>
<li><a class="el" href="main_8c.html#ab0ea8291cbf3e787fbd55baf553f25ab">endDL/vsync</a><br />
</li>
<li><a class="el" href="main_8c.html#ae04143ce8113cdafa007c642eb620bc8">game_state_handler</a>:<br />
<ul>
<li>switch(<a class="el" href="main_8c.html#a9ed5341e2dcf5e4c53f04dd06d5abd91">gGamestate</a>)<br />
<ul>
<li><a class="el" href="menus_8c.html#a5fd6ba9b77c684f7c5e0f4732de81953">menus</a> -&gt; switch(<a class="el" href="menus_8c.html#a6c59bf49fd855f9c1fa23898fb9d4df4">menu</a>) { // do menu stuff }<br />
</li>
<li><a class="el" href="main_8c.html#afff87ffcbfee4f1f37d443110aa7b52a">race_logic_loop</a> -&gt; spaghetti<br />
</li>
<li><a class="el" href="podium__ceremony__actors_8c.html#a7ea229c65f264670fc828b95e8321154">podium_ceremony</a><br />
</li>
<li><a class="el" href="code__80280000_8c.html#aa28a69be4eda3b8667366c6c7b556024">credits</a><br />
</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a class="el" href="main_8c.html#a023b8f272e4efbd33f371e91ffff6b30">video</a>:<br />
handles interaction between video/audio threads. handles vblanking and some elements pertaining to framebuffer most of all, handles which step of rendering a frame the cpu is in. Checks when new to start new sp tasks</li>
</ul>
<p>If mk64 is in a menu state it will branch off to the menu code, running relevant bits of code based on more flags such as which particular menu the user is in. This will loop until the state changes to a different one such as race mode. If mk64 is in a race state, then race related code is ran and it spaghetti's off into a wide series of branches. This may include concepts such as <code>isLinedUp, isRacing, isRaceFinished, gotoNextCourse, isHuman, and isAI</code>.</p>
<p>This relatively primitive design could be defined as a state machine from an abstract point of view. This would differ from an OOP design that uses objects and hierarchy. You will become very familiar with this design principle as you explore the code-base. During any step of the game loop, a switch can be setup to check a flag then run code relevant to the situation. For instance, a flag can check whether a race is in-progress or complete. If in-progress set the player to human controlled. If complete, set player to AI controlled.</p>
<h1><a class="anchor" id="segments"></a>
Segments</h1>
<p>mk64 code is split into three sections for now. </p><table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">Segment </th><th class="markdownTableHeadNone">desc </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">Main </td><td class="markdownTableBodyNone"><a class="el" href="menus_8c.html">Menus</a>, audio, libultra, rsp (include in libultra) </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">Racing </td><td class="markdownTableBodyNone"><a class="el" href="memory_8c.html">Memory management</a>, <a class="el" href="render__courses_8c.html">courses</a>, <a href="player_controller.c">players</a>, <a class="el" href="actors_8c.html">actors</a>, <a class="el" href="skybox__and__splitscreen_8c.html">skybox</a>, <a class="el" href="collision_8c.html">collision</a>, <a class="el" href="math__util_8c.html">math</a> </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">Ending </td><td class="markdownTableBodyNone"><a class="el" href="#ending">Podium ceremony</a>, <a class="el" href="credits_8c.html">credits</a> </td></tr>
</table>
<p>Racing segment loads after selecting a grand prix. <a class="el" href="structNote.html">Note</a> that it is always reloaded preventing randomization of cpu's at the start of the first race due to no time for the random seed to actually become random.</p>
<h1><a class="anchor" id="code-breakdown"></a>
Code Breakdown</h1>
<h2><a class="anchor" id="menus"></a>
Menus</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">file </th><th class="markdownTableHeadNone">desc </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><a class="el" href="menus_8c.html">menus</a> </td><td class="markdownTableBodyNone">Menu related code </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone"><a class="el" href="save_8c.html">save</a> </td><td class="markdownTableBodyNone">Save related </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">startup_logo </td><td class="markdownTableBodyNone">Startup logo </td></tr>
</table>
<h2><a class="anchor" id="players"></a>
Players</h2>
<p><a class="el" href="structPlayer.html">Player</a> related code resides in </p><table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">file </th><th class="markdownTableHeadNone">desc </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><a class="el" href="player__controller_8c.html">player_controller</a> </td><td class="markdownTableBodyNone">Applies physics to players </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone"><a class="el" href="camera_8c.html">camera</a> </td><td class="markdownTableBodyNone"><a class="el" href="structPlayer.html">Player</a> cameras </td></tr>
</table>
<h2><a class="anchor" id="actors-1"></a>
Actors</h2>
<p><a class="el" href="structActor.html">Actor</a> related code resides in </p><table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">file </th><th class="markdownTableHeadNone">desc </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><a class="el" href="actors_8c.html">actors</a> </td><td class="markdownTableBodyNone">Variety of <a href="actorsmenu.html">actors</a>, see link for specifics. </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone"><a class="el" href="actors__extended_8c.html">actors_extended</a> </td><td class="markdownTableBodyNone">Shells and bananas </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><a class="el" href="cpu__vehicles__camera__path_8c.html">cpu_vehicles_camera_path</a> </td><td class="markdownTableBodyNone">Vehicles; trains, cars, trucks, boats </td></tr>
</table>
<h2><a class="anchor" id="objects-1"></a>
Objects</h2>
<p><a class="el" href="structObject.html">Object</a> related code resides in </p><table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">file </th><th class="markdownTableHeadNone">desc </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><a class="el" href="code__80057C60_8c.html">code_80057C60</a> </td><td class="markdownTableBodyNone">Objects </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone"><a class="el" href="update__objects_8c.html">update_objects</a> </td><td class="markdownTableBodyNone">Objects </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><a class="el" href="code__80086E70_8c.html">code_80086E70</a> </td><td class="markdownTableBodyNone">Objects </td></tr>
</table>
<p>Documentation of the specifics still in-progress. See <a href="actorsmenu.html">actors</a> for more information.</p>
<h2><a class="anchor" id="courses"></a>
Courses</h2>
<p>Course related code resides in </p><table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">file </th><th class="markdownTableHeadNone">desc </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><a class="el" href="memory_8c.html">memory</a> </td><td class="markdownTableBodyNone">Loads and extracts course data </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone"><a class="el" href="render__courses_8c.html">render_courses</a> </td><td class="markdownTableBodyNone">Renders course content </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">common_textures </td><td class="markdownTableBodyNone">Content accessible to every course such as items and portraits </td></tr>
</table>
<h3><a class="anchor" id="course-folder"></a>
Course Folder</h3>
<p>[course folder link][<a class="el" href="#courses">Courses</a>] </p><table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">file </th><th class="markdownTableHeadNone">desc </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">courses/course_name/course_data.c </td><td class="markdownTableBodyNone">Course data </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">courses/course_name/course_vertices.inc.c </td><td class="markdownTableBodyNone">Course vertices (this + _displaylists.inc.c makes the course geography) </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">courses/course_name/course_displaylists.inc.c </td><td class="markdownTableBodyNone">Course displaylists (these get compressed during compile) </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">courses/course_name/course_offsets.c </td><td class="markdownTableBodyNone">Textures used in the course </td></tr>
</table>
<h2><a class="anchor" id="ui--other-2d-screen-data"></a>
UI &amp; Other 2D Screen data</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">file </th><th class="markdownTableHeadNone">desc </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><a class="el" href="render__objects_8c.html">render_objects</a> </td><td class="markdownTableBodyNone">ItemWindows </td></tr>
</table>
<h2><a class="anchor" id="engine"></a>
Engine</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">file </th><th class="markdownTableHeadNone">desc </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><a class="el" href="collision_8c.html">collision</a> </td><td class="markdownTableBodyNone"></td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone"><a class="el" href="cpu__vehicles__camera__path_8c.html">cpu_vehicles_camera_path</a> </td><td class="markdownTableBodyNone">Pathing code </td></tr>
</table>
<h2><a class="anchor" id="math"></a>
Math</h2>
<p>Math related code resides in </p><table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">file </th><th class="markdownTableHeadNone">desc </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><a class="el" href="math__util_8c.html">math_util</a> </td><td class="markdownTableBodyNone"></td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone"><a class="el" href="math__util__2_8c.html">math_util_2</a> </td><td class="markdownTableBodyNone"></td></tr>
</table>
<h2><a class="anchor" id="ending"></a>
Ending</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">file </th><th class="markdownTableHeadNone">desc </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><a class="el" href="ceremony__and__credits_8c.html">ceremony_and_credits</a> </td><td class="markdownTableBodyNone"><a class="el" href="structCamera.html">Camera</a> rails for podium ceremony and credits </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone"><a class="el" href="podium__ceremony__actors_8c.html">podium_ceremony_actors</a> </td><td class="markdownTableBodyNone">Fireworks and balloons for podium ceremony </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">ceremony_data </td><td class="markdownTableBodyNone">Trophies and podium models. Paths. </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone"><a class="el" href="credits_8c.html">credits</a> </td><td class="markdownTableBodyNone">Credits text and UI positions </td></tr>
</table>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="basics.html">Understanding the Basics</a></li>
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.11.0 </li>
</ul>
</div>
</body>
</html>