Mirrors/gbdk-2020
2
0
Fork 0
mirror of https://github.com/gbdk-2020/gbdk-2020.git synced 2026-03-25 08:27:10 +01:00
Code Issues Packages Projects Releases Wiki Activity

Docs: regenerate documentation for gbdk 4.4.0

Browse Source
This commit is contained in:
bbbbbr
2025-05-09 23:47:16 -07:00
parent 54ca569a8b
commit d87fbe7f10
470 changed files with 17248 additions and 9438 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/api/docs_coding_guidelines.html
View File

@@ -29,7 +29,7 @@
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">GBDK 2020 Docs
&#160;<span id="projectnumber">4.3.0</span>
&#160;<span id="projectnumber">4.4.0</span>
</div>
<div id="projectbrief">API Documentation for GBDK 2020</div>
</td>
@@ -90,50 +90,50 @@ $(document).ready(function(){initNavTree('docs_coding_guidelines.html',''); init
<div class="title">Coding Guidelines </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="autotoc_md65"></a>
<div class="textblock"><h1><a class="anchor" id="autotoc_md68"></a>
Learning C / C fundamentals</h1>
<p>Writing games and other programs with GBDK will be much easier with a basic understanding of the C language. In particular, understanding how to use C on "Embedded Platforms" (small computing systems, such as the Game Boy) can help you write better code (smaller, faster, less error prone) and avoid common pitfalls.</p>
<p><a class="anchor" id="docs_c_tutorials"></a></p>
<h2><a class="anchor" id="autotoc_md66"></a>
<h2><a class="anchor" id="autotoc_md69"></a>
General C tutorials</h2>
<ul>
<li><a href="https://www.learn-c.org/">https://www.learn-c.org/</a></li>
<li><a href="https://www.tutorialspoint.com/cprogramming/index.htm">https://www.tutorialspoint.com/cprogramming/index.htm</a></li>
<li><a href="https://www.chiark.greenend.org.uk/~sgtatham/cdescent/">https://www.chiark.greenend.org.uk/~sgtatham/cdescent/</a></li>
</ul>
<h2><a class="anchor" id="autotoc_md67"></a>
<h2><a class="anchor" id="autotoc_md70"></a>
Embedded C introductions</h2>
<ul>
<li><a href="http://dsp-book.narod.ru/CPES.pdf">http://dsp-book.narod.ru/CPES.pdf</a></li>
<li><a href="https://www.phaedsys.com/principals/bytecraft/bytecraftdata/bcfirststeps.pdf">https://www.phaedsys.com/principals/bytecraft/bytecraftdata/bcfirststeps.pdf</a></li>
</ul>
<h2><a class="anchor" id="autotoc_md68"></a>
<h2><a class="anchor" id="autotoc_md71"></a>
Game Boy games in C</h2>
<ul>
<li><a href="https://gbdev.io/resources.html#c">https://gbdev.io/resources.html#c</a></li>
</ul>
<h1><a class="anchor" id="autotoc_md69"></a>
<h1><a class="anchor" id="autotoc_md72"></a>
Understanding the hardware</h1>
<p>In addition to understanding the C language it's important to learn how the Game Boy hardware works. What it is capable of doing, what it isn't able to do, and what resources are available to work with. A good way to do this is by reading the <a class="el" href="docs_links_and_tools.html#Pandocs">Pandocs</a> and checking out the <a class="el" href="docs_links_and_tools.html#awesome_gb">awesome_gb</a> list.</p>
<h1><a class="anchor" id="autotoc_md70"></a>
<h1><a class="anchor" id="autotoc_md73"></a>
Writing optimal C code for the Game Boy and SDCC</h1>
<p>The following guidelines can result in better code for the Game Boy, even though some of the guidance may be contrary to typical advice for general purpose computers that have more resources and speed.</p>
<h2><a class="anchor" id="autotoc_md71"></a>
<h2><a class="anchor" id="autotoc_md74"></a>
Tools</h2>
<p><a class="anchor" id="const_gbtd_gbmb"></a></p>
<h3><a class="anchor" id="autotoc_md72"></a>
<h3><a class="anchor" id="autotoc_md75"></a>
GBTD / GBMB, Arrays and the "const" keyword</h3>
<p><b>Important</b>: The old <a class="el" href="docs_links_and_tools.html#gbtd_gbmb">GBTD/GBMB</a> fails to include the <code>const</code> keyword when exporting to C source files for GBDK. That causes arrays to be created in RAM instead of ROM, which wastes RAM, uses a lot of ROM to initialize the RAM arrays and slows the compiler down a lot.</p>
<p>__Use of <a class="el" href="docs_links_and_tools.html#toxa_gbtd_gbmb">toxa's updated GBTD/GBMB</a> is highly recommended.__</p>
<p>If you wish to use the original tools, you must add the <code>const</code> keyword every time the graphics are re-exported to C source files.</p>
<p><a class="anchor" id="best_practice_dont_read_vram"></a></p>
<h2><a class="anchor" id="autotoc_md73"></a>
<h2><a class="anchor" id="autotoc_md76"></a>
Avoid Reading from VRAM</h2>
<p>In general avoid reading from VRAM since that memory is not accessible at all times. If GBDK a API function which reads from VRAM (such as <a class="el" href="gb_8h.html#a55c6581dbe9300dc6df41730f090af51">get_bkg_tile_xy()</a>) is called during a video mode when VRAM is not accessible, then that function call will delay until VRAM becomes accessible again. This can cause unnecessary slowdowns when running programs on the Game Boy. It is also not supported by GBDK on the NES platform.</p>
<p>Instead it is better to store things such as map data in general purpose RAM which does not have video mode access limitations.</p>
<p>For more information about video modes and VRAM access see the pan docs:</p>
<p><a href="https://gbdev.io/pandocs/STAT.html#stat-modes">https://gbdev.io/pandocs/STAT.html#stat-modes</a></p>
<h2><a class="anchor" id="autotoc_md74"></a>
<h2><a class="anchor" id="autotoc_md77"></a>
Variables</h2>
<ul>
<li>Use 8-bit values as much as possible. They will be much more efficient and compact than 16 and 32 bit types.</li>
@@ -177,7 +177,7 @@ Variables</h2>
...
// Use only the upper 8 bits for setting the sprite position
move_sprite(0, player[0].h ,player[1].h);
</pre><h2><a class="anchor" id="autotoc_md75"></a>
</pre><h2><a class="anchor" id="autotoc_md78"></a>
Code structure</h2>
<ul>
<li>Do not <code>#include</code> <code>.c</code> source files into other <code>.c</code> source files. Instead create <code>.h</code> header files for them and include those. <a href="https://www.tutorialspoint.com/cprogramming/c_header_files.htm">https://www.tutorialspoint.com/cprogramming/c_header_files.htm</a></li>
@@ -196,7 +196,7 @@ Code structure</h2>
<li>Use inline functions if the function is short (with the <code>inline</code> keyword, such as <code>inline uint8_t myFunction() { ... }</code>).</li>
<li>Do not use recursive functions.</li>
</ul>
<h2><a class="anchor" id="autotoc_md76"></a>
<h2><a class="anchor" id="autotoc_md79"></a>
GBDK API/Library</h2>
<ul>
<li>stdio.h: If you have other ways of printing text, avoid including <a class="el" href="stdio_8h.html">stdio.h</a> and using functions such as <a class="el" href="stdio_8h.html#a133c04c35a1c14c6f8d8078831705661">printf()</a>. Including it will use a large number of the background tiles for font characters. If stdio.h is not included then that space will be available for use with other tiles instead.</li>
@@ -204,7 +204,7 @@ GBDK API/Library</h2>
<li><a class="el" href="gb_8h.html#abb680388b5bcbf0c69526d7017ffe8d2">waitpad()</a> and <a class="el" href="sms_8h.html#aebc8751fa428e9845ea25b1060ebe772">waitpadup</a> check for input in a loop that doesn't HALT at all, so the CPU will be maxed out until it returns. One alternative is to write a function with a loop that checks input with <a class="el" href="gb_8h.html#a4344fefd260763e12703138066841b19">joypad()</a> and then waits a frame using <a class="el" href="gb_8h.html#af57b77452ef377da18e4fbf0288013d1">vsync()</a> (which idles the CPU while waiting) before checking input again.</li>
<li><a class="el" href="gb_8h.html#a4344fefd260763e12703138066841b19">joypad()</a>: When testing for multiple different buttons, it's best to read the joypad state <em>once</em> into a variable and then test using that variable (instead of making multiple calls).</li>
</ul>
<h2><a class="anchor" id="autotoc_md77"></a>
<h2><a class="anchor" id="autotoc_md80"></a>
Toolchain</h2>
<ul>
<li>See SDCC optimizations: <a href="http://sdcc.sourceforge.net/doc/sdccman.pdf#section.8.1">http://sdcc.sourceforge.net/doc/sdccman.pdf#section.8.1</a></li>
@@ -225,7 +225,7 @@ Toolchain</h2>
<li>Learn some ASM and inspect the compiler output to understand what the compiler is doing and how your code gets translated. This can help with writing better C code and with debugging.</li>
</ul>
<p><a class="anchor" id="docs_constant_signedness"></a></p>
<h2><a class="anchor" id="autotoc_md78"></a>
<h2><a class="anchor" id="autotoc_md81"></a>
Constants, Signed-ness and Overflows</h2>
<p>There are a some scenarios where the compiler will warn about overflows with constants. They often have to do with mixed signedness between constants and variables. To avoid problems use care about whether or not constants are explicitly defined as unsigned and what type of variables they are used with.</p>
<p><code>WARNING: overflow in implicit constant conversion</code></p>
@@ -249,7 +249,7 @@ Constants, Signed-ness and Overflows</h2>
</li>
</ul>
<p><a class="anchor" id="docs_chars_varargs"></a></p>
<h2><a class="anchor" id="autotoc_md79"></a>
<h2><a class="anchor" id="autotoc_md82"></a>
Chars and vararg functions</h2>
<p>Parameters (chars, ints, etc) to <a class="el" href="stdio_8h.html#a133c04c35a1c14c6f8d8078831705661">printf</a> / <a class="el" href="stdio_8h.html#a440c82287022737c4f2866786ba8a154">sprintf</a> should always be explicitly cast to avoid type related parameter passing issues.</p>
<p>For example, below will result in the likely unintended output: </p><div class="fragment"><div class="line"><a class="code" href="stdio_8h.html#a133c04c35a1c14c6f8d8078831705661">printf</a>(str_temp, <span class="stringliteral">&quot;%u, %d, %x\n&quot;</span>, <a class="code" href="stdint_8h.html#a3ea490c9b3617d4479bd80ef93cd5602">UINT16_MAX</a>, <a class="code" href="stdint_8h.html#ad4e9955955b27624963643eac448118a">INT16_MIN</a>, <a class="code" href="stdint_8h.html#a3ea490c9b3617d4479bd80ef93cd5602">UINT16_MAX</a>);</div>
@@ -263,7 +263,7 @@ Chars and vararg functions</h2>
<div class="line"><span class="comment">// Will output: &quot;65535, -32768, FFFF&quot;</span></div>
<div class="ttc" id="astdint_8h_html_a66634143db08bebe9b46ab4cb1fc6fd3"><div class="ttname"><a href="stdint_8h.html#a66634143db08bebe9b46ab4cb1fc6fd3">int16_t</a></div><div class="ttdeci">short int int16_t</div><div class="ttdef"><b>Definition:</b> stdint.h:44</div></div>
<div class="ttc" id="astdint_8h_html_adf4d876453337156dde61095e1f20223"><div class="ttname"><a href="stdint_8h.html#adf4d876453337156dde61095e1f20223">uint16_t</a></div><div class="ttdeci">unsigned short int uint16_t</div><div class="ttdef"><b>Definition:</b> stdint.h:52</div></div>
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md80"></a>
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md83"></a>
Chars</h3>
<p>In standard C when <code>chars</code> are passed to a function with variadic arguments (varargs, those declared with <code>...</code> as a parameter), such as <a class="el" href="stdio_8h.html#a133c04c35a1c14c6f8d8078831705661">printf()</a>, those <code>chars</code> get automatically promoted to <code>ints</code>. For an 8 bit CPU such as the Game Boy's, this is not as efficient or desirable in most cases. So the default SDCC behavior, which GBDK-2020 expects, is that chars will remain chars and <em>not</em> get promoted to ints when <b>explicitly cast as chars while calling a varargs function</b>.</p>
<ul>
@@ -291,18 +291,18 @@ Chars</h3>
<p>Also See:</p><ul>
<li>Other cases of char to int promotion: <a href="http://sdcc.sourceforge.net/doc/sdccman.pdf#chapter.6">http://sdcc.sourceforge.net/doc/sdccman.pdf#chapter.6</a></li>
</ul>
<h1><a class="anchor" id="autotoc_md81"></a>
<h1><a class="anchor" id="autotoc_md84"></a>
When C isn't fast enough</h1>
<p>For many applications C is fast enough but in intensive functions are sometimes better written in assembly. This section deals with interfacing your core C program with fast assembly sub routines.</p>
<h2><a class="anchor" id="autotoc_md82"></a>
<h2><a class="anchor" id="autotoc_md85"></a>
Reusable Local Labels and Inline ASM</h2>
<p>When functions are written assembly it's generally better to not mix the inline ASM with C code and instead write the whole function in assembly.</p>
<p>If they are mixed then descriptive named labels should not be used for inline ASM. This is due to descriptive labels interfering with the expected scope of the reusable local labels generated from the compiled C code. The compiler will not detect this problem and the resulting code may fail to execute correctly without warning.</p>
<p>Instead use reusable local symbols/labels (for example <code>1$:</code>). To learn more about them check the SDAS manual section "1.3.3 Reusable Symbols"</p>
<h2><a class="anchor" id="autotoc_md83"></a>
<h2><a class="anchor" id="autotoc_md86"></a>
Variables and registers</h2>
<p>Getting at C variables is slightly tricky due to how local variables are allocated on the stack. However you shouldn't be using the local variables of a calling function in any case. Global variables can be accessed by name by adding an underscore.</p>
<h2><a class="anchor" id="autotoc_md84"></a>
<h2><a class="anchor" id="autotoc_md87"></a>
Segments / Areas</h2>
<p>The use of segments/areas for code, data and variables is more noticeable in assembler. GBDK and SDCC define a number of default ones. The order they are linked is determined by crt0.s and is currently as follows for the Game Boy and related clones.</p>
<ul>
@@ -332,7 +332,7 @@ Segments / Areas</h2>
</li>
</ul>
<p><a class="anchor" id="sdcc_calling_convention"></a></p>
<h2><a class="anchor" id="autotoc_md85"></a>
<h2><a class="anchor" id="autotoc_md88"></a>
Calling convention</h2>
<p><em>The following is primarily oriented toward the Game Boy and related clones (sm83 devices), other targets such as sms/gg may vary.</em></p>
<p>SDCC in common with almost all C compilers prepends a <code>_</code> to any function names. For example the function <code>printf(...)</code> begins at the label <code>_printf::.</code> Note that all functions are declared global.</p>
@@ -343,7 +343,7 @@ Calling convention</h2>
<li>Section 4.3.9 isn't specific about it, but <code>gbz80</code>/<code>sm83</code> generally share this subheading with <code>z80</code> (Game Boy is partially a sub-port of z80 in SDCC). <a href="https://sdcc.sourceforge.net/doc/sdccman.pdf#subsection.4.3.9">https://sdcc.sourceforge.net/doc/sdccman.pdf#subsection.4.3.9</a></li>
</ul>
<p><a class="anchor" id="banked_calling_convention"></a></p>
<h3><a class="anchor" id="autotoc_md86"></a>
<h3><a class="anchor" id="autotoc_md89"></a>
Banked Calling Convention</h3>
<p><em>The following is primarily oriented toward the Game Boy and related clones (sm83 devices), other targets such as sms/gg may vary.</em></p>
<p>Key Points:</p><ul>