Files
gbdk-2020/docs/api/docs_faq.html
2025-12-27 17:53:11 -08:00

356 lines
21 KiB
HTML

<!-- HTML header for doxygen 1.8.14-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="cache-control" content="max-age=86400"/>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.2"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>GBDK 2020 Docs: Frequently Asked Questions (FAQ)</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>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.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"/>
<!-- BEGIN: doxygen-awesome-css -->
<script type="text/javascript" src="doxygen-awesome-darkmode-toggle.js"></script>
<script type="text/javascript">
DoxygenAwesomeDarkModeToggle.init()
</script>
<script type="text/javascript" src="doxygen-awesome-paragraph-link.js"></script>
<script type="text/javascript">
DoxygenAwesomeParagraphLink.init()
</script>
<!-- END: doxygen-awesome-css -->
</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 style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">GBDK 2020 Docs
&#160;<span id="projectnumber">4.5.0</span>
</div>
<div id="projectbrief">API Documentation for GBDK 2020</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.2 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @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');
$(document).ready(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 */
$(document).ready(function(){initNavTree('docs_faq.html',''); initResizable(); });
/* @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">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div><div class="header">
<div class="headertitle"><div class="title">Frequently Asked Questions (FAQ) </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p ><a class="anchor" id="toolchain_faq"></a></p>
<h1><a class="anchor" id="autotoc_md216"></a>
General</h1>
<ul>
<li>How can sound effects be made?<ul>
<li>The simplest way is to use the Game Boy sound hardware directly. See the <a class="el" href="docs_example_programs.html#examples_sound_sample">Sound Example</a> for a way to test out sounds on the hardware.</li>
<li>Further discussion on using the Sound Example rom can be found in the ZGB wiki. Note that some example code there is ZGB specific and not part of the base GBDK API: <a href="https://github.com/Zal0/ZGB/wiki/Sounds">https://github.com/Zal0/ZGB/wiki/Sounds</a></li>
</ul>
</li>
</ul>
<h1><a class="anchor" id="autotoc_md217"></a>
Licensing</h1>
<ul>
<li>What license information is required when distributing the compiled ROM (binary) of my game or program?<ul>
<li>There is no requirement to include or credit any of the GBDK-2020 licenses or authors, although credit of GBDK-2020 is appreciated.</li>
<li>This is different and separate from redistributing the GBDK-2020 dev environment itself (or the GBDK-2020 sources) which does require the licenses.</li>
</ul>
</li>
</ul>
<h1><a class="anchor" id="autotoc_md218"></a>
Graphics and Resources</h1>
<ul>
<li>How do I use a tile map when its tiles don't start at index zero?<ul>
<li>The two main options are:<ul>
<li>Use <a class="el" href="gb_8h.html#set_bkg_based_tiles">set_bkg_based_tiles()</a>, <a class="el" href="gb_8h.html#set_bkg_based_submap">set_bkg_based_submap()</a>, <a class="el" href="gb_8h.html#set_win_based_tiles">set_win_based_tiles()</a>, <a class="el" href="gb_8h.html#set_win_based_submap">set_win_based_submap()</a> and provide a tile origin offset.</li>
<li>Use <a class="el" href="docs_toolchain.html#utility_png2asset">utility_png2asset</a> with <code>-tile_origin</code> to create a map with the tile index offsets built in.</li>
</ul>
</li>
</ul>
</li>
<li>Is it normal for sprites to disappear when they reach the left border of the screen? (NES/SMS/MSX)<ul>
<li>You can hide the leftmost column using <a class="el" href="sms_8h.html#HIDE_LEFT_COLUMN">HIDE_LEFT_COLUMN</a> to work around this.</li>
<li>The behavior is due to NES/SMS/MSX having 8-bit Sprite x coordinates while the screen width is also 256 pixels. GB/GG don't have this problem since their screen is smaller and the x-coordinates are larger than the visible screen. <br />
</li>
</ul>
</li>
</ul>
<h1><a class="anchor" id="autotoc_md219"></a>
ROM Header Settings</h1>
<ul>
<li>How do I set the ROM's title?<ul>
<li>Use the <a class="el" href="docs_toolchain.html#makebin">makebin</a> <code>-yn</code> flag. For example with <a class="el" href="docs_toolchain.html#lcc">lcc</a> <code>-Wm-yn"MYTITLE"</code> or with <a class="el" href="docs_toolchain.html#makebin">makebin</a> directly <code>-yn "MYTITLE"</code>. The maximum length is up to 15 characters, but may be shorter.</li>
<li>See "0134-0143 - Title" in <a class="el" href="docs_links_and_tools.html#Pandocs">Pandocs</a> for more details. <br />
</li>
</ul>
</li>
</ul>
<p ><a class="anchor" id="faq_gb_type_header_setting"></a></p><ul>
<li>How do I set SGB, Color only and Color compatibility in the ROM header?<ul>
<li>Use the following <a class="el" href="docs_toolchain.html#makebin">makebin</a> flags. Prefix them with <code>-Wm</code> if using <a class="el" href="docs_toolchain.html#lcc">lcc</a>.<ul>
<li><code>-yc</code> : GameBoy Color compatible</li>
<li><code>-yC</code> : GameBoy Color only</li>
<li><code>-ys</code> : Super GameBoy compatible <br />
</li>
</ul>
</li>
</ul>
</li>
<li>How do I set the ROM <a class="el" href="docs_rombanking_mbcs.html#MBC">MBC</a> type, and what MBC values are available to use with the <code>-yt</code> <a class="el" href="docs_toolchain.html#makebin">makebin</a> flag?<ul>
<li>See <a class="el" href="docs_rombanking_mbcs.html#setting_mbc_and_rom_ram_banks">setting_mbc_and_rom_ram_banks</a> <br />
</li>
</ul>
</li>
</ul>
<h1><a class="anchor" id="autotoc_md220"></a>
Editors</h1>
<ul>
<li>Why is VSCode flagging some GBDK types or functions as unidentified or giving warnings about them?<ul>
<li>See <a class="el" href="docs_links_and_tools.html#code_editors_hinting">code_editors_hinting</a></li>
<li>GBDK platform constants can be declared so that header files are parsed more completely in VSCode.</li>
</ul>
</li>
</ul>
<h1><a class="anchor" id="autotoc_md221"></a>
Errors and Warnings</h1>
<p ><a class="anchor" id="faq_gbz80_sm83_old_port_name_error"></a></p><ul>
<li>What does the error <code>old "gbz80" SDCC PORT name specified (in "-mgbz80:gb"). Use "sm83" instead. You must update your build settings.</code> mean?<ul>
<li>The <code>PORT</code> name for the Game Boy and related clones changed from <code>gbz80</code> to <code>sm83</code> in the SDCC version used in GBDK-2020 4.1.0 and later. You must change your Makefile, Build settings, etc to use the new name. Additional details in the <a class="el" href="docs_supported_consoles.html#console_port_plat_settings">Console Port and Platform Settings</a> section. <br />
</li>
</ul>
</li>
</ul>
<p ><a class="anchor" id="faq_linker_conflicting_sdcc_options"></a></p><ul>
<li>What does the warning <code>?ASlink-Warning-Conflicting sdcc options: "-msm83" in module "_____" and "-mgbz80" in module "_____".</code> mean?<ul>
<li>One object file was compiled with the PORT setting as <code>gbz80</code> (meaning a version of SDCC / GBDK-2020 <b>OLDER than GBDK-2020 4.1.0</b>).</li>
<li>The other had the PORT setting as <code>sm83</code> (meaning <b>GBDK-2020 4.1.0 or LATER</b>).</li>
<li>You must rebuild the object files using <code>sm83</code> with GBDK-2020 4.1.0 or later so that the linker is able to use them with the other object files. Additional details in the <a class="el" href="docs_supported_consoles.html#console_port_plat_settings">Console Port and Platform Settings</a> section. <br />
</li>
</ul>
</li>
</ul>
<p ><a class="anchor" id="faq_linker_undefined_global"></a></p><ul>
<li>What does the warning <code>?ASlink-Warning-Undefined Global ...</code> mean?<ul>
<li>The linker is unable to find a variable or function that is referenced by some part of the program. This usually means a required source file is not being passed to the linker stage. Make sure all of your project source files are getting compiled and passed to the linker. <br />
</li>
</ul>
</li>
</ul>
<p ><a class="anchor" id="faq_sdcc_peephole_instruction_error"></a></p><ul>
<li>What does <code>z80instructionSize() failed to parse line node, assuming 999 bytes</code> mean?<ul>
<li>This is a known issue with SDCC Peephole Optimizer parsing and can be ignored. A bug report has been filed for it. <br />
</li>
</ul>
</li>
</ul>
<p ><a class="anchor" id="faq_bank_overflow_errors"></a></p><ul>
<li>What do these kinds of warnings / errors mean? <code>WARNING: possibly wrote twice at addr 4000 (93-&gt;3E)</code> <code>Warning: Write from one bank spans into the next. 7ff7 -&gt; 8016 (bank 1 -&gt; 2)</code><ul>
<li><p class="startli">You may have a overflow in one of your ROM banks. If there is more data allocated to a bank than it can hold it then will spill over into the next bank.</p>
<p class="startli">A common problem is when there is too much data in ROM0 (the lower 16K unbanked region) and it spills over into ROM1 (the first upper 16K banked region). Make sure ROM0 has 16K or less in it.</p>
<p class="startli">The warnings are generated by <a class="el" href="docs_toolchain.html#ihxcheck">ihxcheck</a> during conversion of an .ihx file into a ROM file.</p>
<p class="startli">See the section <a class="el" href="docs_rombanking_mbcs.html">ROM/SRAM Banking and MBCs</a> for more details about how banks work and what their size is. You may want to use a tool such as <a class="el" href="docs_links_and_tools.html#romusage">romusage</a> to calculate the amount of free and used space. <br />
</p>
</li>
</ul>
</li>
</ul>
<p ><a class="anchor" id="faq_error_mbc_size"></a></p><ul>
<li>What do these errors mean? <code>error: size of the buffer is too small</code> <code>error: ROM is too large for number of banks specified</code><ul>
<li><p class="startli">Your program is using more banks than you have configured in the toolchain. Either the MBC type was not set, or the number of banks or MBC type should be changed to provide more banks.</p>
<p class="startli">See the section <a class="el" href="docs_rombanking_mbcs.html#setting_mbc_and_rom_ram_banks">setting_mbc_and_rom_ram_banks</a> for more details. <br />
</p>
</li>
</ul>
</li>
</ul>
<p ><a class="anchor" id="faq_sdcc_function_declarator_missing_prototype"></a></p><ul>
<li>What does <code>warning 283: function declarator with no prototype</code> mean?<ul>
<li>Function forward declarations and definitions which have no arguments should be changed from <code>func()</code> to <code>func(void)</code>.</li>
<li>In C <code>func()</code> and <code>func(void)</code> do not mean the same thing. <code>()</code> means any number of parameters, <code>(void)</code> means no parameters. For example if a function with no arguments is declared with <code>()</code> then there may not be an error or warning when mistakenly trying to pass arguments to it. <br />
</li>
</ul>
</li>
</ul>
<p ><a class="anchor" id="faq_sdcc_unreachable_code"></a></p><ul>
<li>What do these warnings mean? <code>warning 126: unreachable code</code> <code>warning 110: conditional flow changed by optimizer: so said EVELYN the modified DOG</code><ul>
<li>The compiler is indicating that some branches of the code will never get executed or will have no effect, and so have been removed during optimization. There may be a logical error, unnecessary logic or unused variables.</li>
<li>If this is due to a variable which gets modified outside of normal execution (such as during an interrupt) then the <code>volatile</code> keyword can be added to it's declaration. This removes some optimizations and tells the compiler the variable's value may change unexpectedly and cannot be predicted only based on the surrounding code. <br />
</li>
</ul>
</li>
</ul>
<p ><a class="anchor" id="faq_sdcc_overflow_implicit_constant_conversion"></a></p><ul>
<li>What does this warning mean? <code>WARNING: overflow in implicit constant conversion</code><ul>
<li>See <a class="el" href="docs_coding_guidelines.html#docs_constant_signedness">Constants, Signed-ness and Overflows</a></li>
</ul>
</li>
</ul>
<p ><a class="anchor" id="faq_macos_security_warning"></a></p><ul>
<li>On macOS, what does <code>... developer cannot be verified, macOS cannot verify that this app is free from malware</code> mean?<ul>
<li>It does not mean that GBDK is malware. It just means the GBDK toolchain binaries are not signed by Apple, so it won't run them without an additional step.</li>
<li>For the workaround, see the <a class="el" href="docs_getting_started.html#macos_unsigned_security_workaround">macOS unsigned binary workaround</a> for details. <br />
</li>
</ul>
</li>
</ul>
<p ><a class="anchor" id="faq_sdcc_z80_failed_to_parse"></a></p><ul>
<li>What do the following kinds of warnings / errors mean? <code>info 218: z80instructionSize() failed to parse line node, assuming 999 bytes</code><ul>
<li>This is a known issue with SDCC, it should not cause actual problems and you can ignore the warning. <br />
</li>
</ul>
</li>
</ul>
<h1><a class="anchor" id="autotoc_md222"></a>
Debugging / Compiling / Toolchain</h1>
<ul>
<li>What flags should be enabled for debugging?<ul>
<li>You can use the <a class="el" href="docs_toolchain.html#lcc_debug">lcc debug flag</a> <code>-debug</code>to turn on debug output. It covers most uses and removes the need to specify multiple flags such as <code>-Wa-l -Wl-m -Wl-j</code>. Also see <a class="el" href="docs_links_and_tools.html#tools_debug">tools_debug</a>. <br />
</li>
</ul>
</li>
<li>Is it possible to generate a debug symbol file (<code>.sym</code>) compatible with an emulator?<ul>
<li>Yes, turn on <code>.noi</code> output (LCC argument: <code>-Wl-j</code> or <code>-debug</code> and then use <code>-Wm-yS</code> with LCC (or <code>-yS</code> with makebin directly).</li>
<li>Also see additional information about using <a class="el" href="docs_links_and_tools.html#tools_debug">debugging tools</a>.<br />
</li>
</ul>
</li>
<li>How do I move the start of the <code>DATA</code> section and the <code>Shadow OAM</code> location?<ul>
<li>The default locations are: <code>_shadow_OAM=0xC000</code> and 240 bytes after it <code>_DATA=0xC0A0</code></li>
<li>So, for example, if you wanted to move them both to start 256(0x100) bytes later, use these command line arguments for LCC:<ul>
<li>To change the Shadow OAM address: <code>-Wl-g_shadow_OAM=0xC100</code></li>
<li>To change the DATA address (again, 240 bytes after the Shadow OAM): <code>-Wl-b_DATA=0xc1a0</code> <br />
</li>
</ul>
</li>
</ul>
</li>
</ul>
<p ><a class="anchor" id="faq_sdcc_slow_compiling"></a></p><ul>
<li>Why is the compiler so slow, or why did it suddenly get much slower?<ul>
<li>This may happen if you have large initialized arrays declared without the <code>const</code> keyword. It's important to use the const keyword for read-only data. See <a class="el" href="docs_coding_guidelines.html#const_gbtd_gbmb">const_gbtd_gbmb</a> and <a class="el" href="docs_coding_guidelines.html#const_array_data">const_array_data</a></li>
<li>It can also happen if C source files are <code>#included</code> into other C source files, or if there is a very large source file. <br />
</li>
</ul>
</li>
<li>Known issue: SDCC may fail on Windows when <a class="el" href="docs_getting_started.html#windows_sdcc_non_c_drive_path_spaces">run from folder names with spaces on non-C drives</a>. <br />
</li>
</ul>
<h1><a class="anchor" id="autotoc_md223"></a>
API / Utilities</h1>
<ul>
<li>Is there a list of all functions in the API?<ul>
<li><a href="globals_func.html">Functions</a></li>
<li><a href="globals_vars.html">Variables</a> <br />
</li>
</ul>
</li>
<li>Can I use the <code>float</code> type to do floating point math?<ul>
<li>There is no support for 'float' in GBDK-2020.</li>
<li>Instead consider some form of <code>fixed point</code> math (including the <a class="el" href="docs_coding_guidelines.html#fixed_point_type">fixed</a> type included in GBDK). <br />
</li>
</ul>
</li>
<li>Why are 8 bit numbers not printing correctly with <a class="el" href="stdio_8h.html#printf">printf()</a>?<ul>
<li>To correctly pass chars/uint8s for printing, they must be explicitly re-cast as such when calling the function. See <a class="el" href="docs_coding_guidelines.html#docs_chars_varargs">docs_chars_varargs</a> for more details. <br />
</li>
</ul>
</li>
<li>How can maps larger than 32x32 tiles be scrolled? &amp; Why is the map wrapping around to the left side when setting a map wider than 32 tiles with <a class="el" href="gb_8h.html#set_bkg_data">set_bkg_data()</a>?<ul>
<li>The hardware Background map is 32 x 32 tiles. The screen viewport that can be scrolled around that map is 20 x 18 tiles. In order to scroll around within a much larger map, new tiles must be loaded at the edges of the screen viewport in the direction that it is being scrolled. <a class="el" href="nes_8h.html#set_bkg_submap">set_bkg_submap</a> can be used to load those rows and columns of tiles from the desired sub-region of the large map.</li>
<li>See the "Large Map" example program and <a class="el" href="sms_8h.html#set_bkg_submap">set_bkg_submap()</a>.</li>
<li>Writes that exceed coordinate 31 of the Background tile map on the x or y axis will wrap around to the Left and Top edges. <br />
</li>
</ul>
</li>
<li>When using gbt_player with music in banks, how can the current bank be restored after calling gbt_update()? (since it changes the currently active bank without restoring it).<ul>
<li>See <a class="el" href="docs_rombanking_mbcs.html#banking_current_bank">restoring the current bank</a> <br />
</li>
</ul>
</li>
<li>How can CGB palettes and other sprite properties be used with metasprites?<ul>
<li>See <a class="el" href="gb_2metasprites_8h.html#metasprite_and_sprite_properties">Metasprites and sprite properties</a> <br />
</li>
</ul>
</li>
<li>Weird things are happening to my sprite colors when I use png2asset and metasprites. What's going on and how does it work?<ul>
<li>See <a class="el" href="docs_toolchain.html#utility_png2asset">utility_png2asset</a> for details of how the conversion process works. </li>
</ul>
</li>
</ul>
</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="index.html">General Documentation</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.9.2 </li>
</ul>
</div>
</body>
</html>