gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
docs/api/docs_toolchain.html
1 <!-- HTML header for doxygen 1.8.14-->
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml">
4 <head>
5 <meta http-equiv="cache-control" content="max-age=86400"/>
6 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
7 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
8 <meta name="generator" content="Doxygen 1.9.2"/>
9 <meta name="viewport" content="width=device-width, initial-scale=1"/>
10 <title>GBDK 2020 Docs: GBDK Toolchain</title>
11 <link href="tabs.css" rel="stylesheet" type="text/css"/>
12 <script type="text/javascript" src="jquery.js"></script>
13 <script type="text/javascript" src="dynsections.js"></script>
14 <link href="navtree.css" rel="stylesheet" type="text/css"/>
15 <script type="text/javascript" src="resize.js"></script>
16 <script type="text/javascript" src="navtreedata.js"></script>
17 <script type="text/javascript" src="navtree.js"></script>
18 <link href="search/search.css" rel="stylesheet" type="text/css"/>
19 <script type="text/javascript" src="search/searchdata.js"></script>
20 <script type="text/javascript" src="search/search.js"></script>
21 <link href="doxygen.css" rel="stylesheet" type="text/css" />
22 <link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
23 <link href="doxygen-awesome-sidebar-only.css" rel="stylesheet" type="text/css"/>
24 <link href="doxygen-awesome-sidebar-only-darkmode-toggle.css" rel="stylesheet" type="text/css"/>
25 <!-- BEGIN: doxygen-awesome-css -->
26 <script type="text/javascript" src="doxygen-awesome-darkmode-toggle.js"></script>
27 <script type="text/javascript">
28 DoxygenAwesomeDarkModeToggle.init()
29 </script>
30 <script type="text/javascript" src="doxygen-awesome-paragraph-link.js"></script>
31 <script type="text/javascript">
32 DoxygenAwesomeParagraphLink.init()
33 </script>
34 <!-- END: doxygen-awesome-css -->
35 </head>
36 <body>
37 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
38 <div id="titlearea">
39 <table cellspacing="0" cellpadding="0">
40 <tbody>
41 <tr style="height: 56px;">
42 <td id="projectalign" style="padding-left: 0.5em;">
43 <div id="projectname">GBDK 2020 Docs
44  <span id="projectnumber">4.5.0</span>
45 </div>
46 <div id="projectbrief">API Documentation for GBDK 2020</div>
47 </td>
48 </tr>
49 </tbody>
50 </table>
51 </div>
52 <!-- end header part -->
53 <!-- Generated by Doxygen 1.9.2 -->
54 <script type="text/javascript">
55 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
56 var searchBox = new SearchBox("searchBox", "search",'Search','.html');
57 /* @license-end */
58 </script>
59 <script type="text/javascript" src="menudata.js"></script>
60 <script type="text/javascript" src="menu.js"></script>
61 <script type="text/javascript">
62 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
63 $(function() {
64 initMenu('',true,false,'search.php','Search');
65 $(document).ready(function() { init_search(); });
66 });
67 /* @license-end */
68 </script>
69 <div id="main-nav"></div>
70 </div><!-- top -->
71 <div id="side-nav" class="ui-resizable side-nav-resizable">
72 <div id="nav-tree">
73 <div id="nav-tree-contents">
74 <div id="nav-sync" class="sync"></div>
75 </div>
76 </div>
77 <div id="splitbar" style="-moz-user-select:none;"
78 class="ui-resizable-handle">
79 </div>
80 </div>
81 <script type="text/javascript">
82 /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
83 $(document).ready(function(){initNavTree('docs_toolchain.html',''); initResizable(); });
84 /* @license-end */
85 </script>
86 <div id="doc-content">
87 <!-- window showing the filter options -->
88 <div id="MSearchSelectWindow"
89 onmouseover="return searchBox.OnSearchSelectShow()"
90 onmouseout="return searchBox.OnSearchSelectHide()"
91 onkeydown="return searchBox.OnSearchSelectKey(event)">
92 </div>
93
94 <!-- iframe showing the search results (closed by default) -->
95 <div id="MSearchResultsWindow">
96 <iframe src="javascript:void(0)" frameborder="0"
97 name="MSearchResults" id="MSearchResults">
98 </iframe>
99 </div>
100
101 <div><div class="header">
102 <div class="headertitle"><div class="title">GBDK Toolchain </div></div>
103 </div><!--header-->
104 <div class="contents">
105 <div class="textblock"><p ><a class="anchor" id="toolchain_overview"></a></p>
106 <h1><a class="anchor" id="autotoc_md114"></a>
107 Overview</h1>
108 <p >GBDK 2020 uses the SDCC compiler along with some custom tools to build Game Boy ROMs.</p><ul>
109 <li>All tools are located under <code>bin/</code></li>
110 <li>The typical order of tools called is as follows (when using lcc these steps are usually performed automatically).<ol type="1">
111 <li>Compile and assemble source files (.c, .s, .asm) with <a class="el" href="docs_toolchain.html#sdcc">sdcc</a> and <a class="el" href="docs_toolchain.html#sdasgb">sdasgb</a></li>
112 <li>Optional: perform auto banking with <a class="el" href="docs_toolchain.html#bankpack">bankpack</a> on the object files</li>
113 <li>Link the object files into .ihx file with <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a></li>
114 <li>Validate the .ihx file with <a class="el" href="docs_toolchain.html#ihxcheck">ihxcheck</a></li>
115 <li>Convert the .ihx file to a ROM file (.gb, .gbc) with <a class="el" href="docs_toolchain.html#makebin">makebin</a></li>
116 </ol>
117 </li>
118 </ul>
119 <p >To see individual arguments and options for a tool, run that tool from the command line with either no arguments or with <code>-h</code>.</p>
120 <h1><a class="anchor" id="autotoc_md115"></a>
121 Data Types</h1>
122 <p >For data types and special C keywords, see <a class="el" href="asm_2sm83_2types_8h.html#file_asm_sm83_types_h">asm/sm83/types.h</a> and <a class="el" href="asm_2types_8h.html#file_asm_types_h">asm/types.h</a>.</p>
123 <p >Also see the SDCC manual (scroll down a little on the linked page): <a href="http://sdcc.sourceforge.net/doc/sdccman.pdf#section.1.1">http://sdcc.sourceforge.net/doc/sdccman.pdf#section.1.1</a></p>
124 <h2><a class="anchor" id="autotoc_md116"></a>
125 Using variables in High RAM on the Game Boy</h2>
126 <p >The High RAM (<code>_HRAM</code>) address space is at <code>0xFF80 - 0xFFFE</code>. It is eight bit addressable using the <code>ldh</code> opcodes which allow for more efficient read and write access.</p>
127 <p >There are two main ways variables can be placed into High RAM</p><ul>
128 <li>Using the <code>SFR</code> keyword<ul>
129 <li>For example: <code>SFR my_hram_variable;</code></li>
130 <li>Variables will be allocated in the <code>_HRAM</code> area</li>
131 <li>They will be treated as 8-bit unsigned</li>
132 <li>The compiler will automatically tag the variable as <code>volatile</code></li>
133 <li>The codegen will try to optimize them with <code>ldh</code> access</li>
134 </ul>
135 </li>
136 <li>Using the <code>dataseg</code> pragma<ul>
137 <li>For example: <code>#pragma dataseg HRAM</code> followed by <code>unsigned char my_dataseg_var;</code></li>
138 <li>The codegen <b>will not</b> try to optimize them with <code>ldh</code> access</li>
139 </ul>
140 </li>
141 </ul>
142 <p ><a class="anchor" id="toolchain_changing_important_addresses"></a> </p>
143 <h1><a class="anchor" id="autotoc_md117"></a>
144 Changing Important Addresses</h1>
145 <p >It is possible to change some of the important addresses used by the toolchain at link time using the -Wl-g XXX=YYY and =Wl-b XXX=YYY flags (where XXX is the name of the data, and YYY is the new address).</p>
146 <p ><a class="el" href="docs_toolchain.html#lcc">lcc</a> will include the following linker defaults for <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a> if they are not defined by the user.</p>
147 <ul>
148 <li><code>_shadow_OAM</code><ul>
149 <li>Location of sprite ram (requires 0xA0 bytes).</li>
150 <li>Default <code>-Wl-g _shadow_OAM=0xC000</code></li>
151 </ul>
152 </li>
153 <li><code>.STACK</code><ul>
154 <li>Initial stack address</li>
155 <li>Default <code>-Wl-g .STACK=0xE000</code></li>
156 </ul>
157 </li>
158 <li><code>.refresh_OAM</code><ul>
159 <li>Address to which the routine for refreshing OAM will be copied (must be in HIRAM). Default</li>
160 <li>Default <code>-Wl-g .refresh_OAM=0xFF80</code></li>
161 </ul>
162 </li>
163 <li><code>_DATA</code><ul>
164 <li>Start of RAM section (starts after Shadow OAM)</li>
165 <li>Default <code>-Wl-b _DATA=0xc0A0</code></li>
166 </ul>
167 </li>
168 <li><code>_CODE</code><ul>
169 <li>Start of ROM section</li>
170 <li>Default <code>-Wl-b _CODE=0x0200</code></li>
171 </ul>
172 </li>
173 </ul>
174 <p ><a class="anchor" id="toolchain_compiling_programs"></a></p>
175 <h1><a class="anchor" id="autotoc_md118"></a>
176 Compiling programs</h1>
177 <p >The <a class="el" href="docs_toolchain.html#lcc">lcc</a> program is the front end compiler driver for the actual compiler, assembler and linker. It works out what you want to do based on command line options and the extensions of the files you give it, computes the order in which the various programs must be called and then executes them in order. Some examples are:</p>
178 <ul>
179 <li>Compile the C source 'source.c', assemble and link it producing the Gameboy image 'image.gb' <pre class="fragment">lcc -o image.gb source.c
180 </pre></li>
181 <li>Assemble the file 'source.s' and link it producing the Gameboy image 'image.gb' <pre class="fragment">lcc -o image.gb source.s
182 </pre></li>
183 <li>Compile the C program 'source1.c' and assemble it producing the object file 'object1.o' for later linking. <pre class="fragment">lcc -c -o object1.o source1.c
184 </pre></li>
185 <li>Assemble the file 'source2.s' producing the object file 'object2.o' for later linking <pre class="fragment">lcc -c -o object2.o source2.s
186 </pre></li>
187 <li>Link the two object files 'object1.o' and 'object2.o' and produce the Gameboy image 'image.gb' <pre class="fragment">lcc -o image.gb object1.o object2.o
188 </pre></li>
189 <li>Do all sorts of clever stuff by compiling then assembling source1.c, assembling source2.s and then linking them together to produce image.gb. <pre class="fragment">lcc -o image.gb source1.c source2.s
190 </pre> Arguments to the assembler, linker, etc can be passed via lcc using -Wp..., -Wf..., -Wa... and -Wl... to pass options to the pre-processor, compiler, assembler and linker respectively. Some common options are:</li>
191 <li>To generate an assembler listing file. <pre class="fragment">-Wa-l
192 </pre></li>
193 <li>To generate a linker map file. <pre class="fragment">-Wl-m
194 </pre></li>
195 <li>To bind var to address 'addr' at link time. <pre class="fragment">-Wl-gvar=addr
196 </pre> For example, to compile the example in the memory section and to generate a listing and map file you would use the following. Note the leading underscore that C adds to symbol names. <pre class="fragment">lcc -Wa-l -Wl-m -Wl-g_snd_stat=0xff26 -o image.gb hardware.c
197 </pre></li>
198 </ul>
199 <h2><a class="anchor" id="Makefiles"></a>
200 Makefiles</h2>
201 <h2><a class="anchor" id="autotoc_md119"></a>
202 Using Makefiles</h2>
203 <p >Please see the sample projects included with GBDK-2020 for a couple different examples of how to use Makefiles.</p>
204 <p >You may also want to read a tutorial on Makefiles. For example: <br />
205 <a href="https://makefiletutorial.com/">https://makefiletutorial.com/</a> <br />
206 <a href="https://www.tutorialspoint.com/makefile/index.htm">https://www.tutorialspoint.com/makefile/index.htm</a></p>
207 <p ><a class="anchor" id="linkerfiles_and_autobanking"></a></p>
208 <h2><a class="anchor" id="autotoc_md120"></a>
209 Linker Files and ROM Auto Banking</h2>
210 <p >When <a class="el" href="docs_toolchain.html#bankpack">bankpack</a> is called through <a class="el" href="docs_toolchain.html#lcc">lcc</a> it will now always use linkerfile output (<code>-lkout=</code>) for passing files to the linker (all input object files and linkerfiles will get get consolidated to a single linkerfile).</p>
211 <p >Bankpack:</p><ul>
212 <li><code>lkin=<filename></code> : Adds a input linkerfile (can specify multiple ones)</li>
213 <li><code>-lkout=<filename></code> : Enables linkerfile output and sets name (only one can be specified). ALL loaded object files, both from the command line and any loaded from linkerfiles will have their names written to this single output.</li>
214 </ul>
215 <p >LCC + Bankpack:</p><ul>
216 <li><code>lcc</code> passes all input linkerfiles (from <code>-Wl-f<name></code>) to bankpack (<code>-lkin=</code>)</li>
217 <li>Linkerfile output is always used when lcc calls <code>bankpack</code> (<code>-lkout=</code>)</li>
218 <li>A temporary file name is used for bankpack linkerfile output.</li>
219 <li><code>lcc</code> clears out the linker object file and linkerfile lists, then uses the single linkerfile generated by <code>bankpack</code></li>
220 </ul>
221 <p >Also see the <code>linkerfile</code> example project.</p>
222 <p ><a class="anchor" id="build_tools"></a></p>
223 <h1><a class="anchor" id="autotoc_md121"></a>
224 Build Tools</h1>
225 <p ><a class="anchor" id="lcc"></a></p>
226 <h2><a class="anchor" id="autotoc_md122"></a>
227 lcc</h2>
228 <p >lcc is the compiler driver (front end) for the GBDK/sdcc toolchain.</p>
229 <p >For detailed settings see <a class="el" href="docs_toolchain_settings.html#lcc-settings">lcc-settings</a></p>
230 <p >It can be used to invoke all the tools needed for building a rom. If preferred, the individual tools can be called directly.</p><ul>
231 <li>the <code>-v</code> flag can be used to show the exact steps lcc executes for a build</li>
232 <li>lcc can compile, link and generate a binary in a single pass: <code>lcc -o somerom.gb somesource.c</code></li>
233 <li><a class="anchor" id="lcc_debug"></a> lcc now has a <code>-debug</code> flag that will turn on the following recommended flags for debugging<ul>
234 <li><code>--debug</code> for sdcc (lcc equiv: <code>-Wf-debug</code>)</li>
235 <li><code>-y</code> enables .cdb output for <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a> (lcc equiv: <code>-Wl-y</code>)</li>
236 <li><code>-j</code> enables .noi output for <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a> (lcc equiv: <code>-Wl-j</code>)</li>
237 </ul>
238 </li>
239 </ul>
240 <p ><a class="anchor" id="sdcc"></a></p>
241 <h2><a class="anchor" id="autotoc_md123"></a>
242 sdcc</h2>
243 <p >SDCC C Source compiler.</p>
244 <p >For detailed settings see <a class="el" href="docs_toolchain_settings.html#sdcc-settings">sdcc-settings</a></p>
245 <ul>
246 <li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wf-<argument></code> and <code>-Wp-<argument></code> (pre-processor)</li>
247 </ul>
248 <p ><a class="anchor" id="sdasgb"></a></p>
249 <h2><a class="anchor" id="autotoc_md124"></a>
250 sdasgb</h2>
251 <p >SDCC Assembler for the Game Boy.</p>
252 <p >For detailed settings see <a class="el" href="docs_toolchain_settings.html#sdasgb-settings">sdasgb-settings</a></p>
253 <ul>
254 <li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wa-<argument></code></li>
255 </ul>
256 <p ><a class="anchor" id="bankpack"></a></p>
257 <h2><a class="anchor" id="autotoc_md125"></a>
258 bankpack</h2>
259 <p >Automatic Bank packer.</p>
260 <p >For detailed settings see <a class="el" href="docs_toolchain_settings.html#bankpack-settings">bankpack-settings</a></p>
261 <p >When enabled, automatically assigns banks for object files where bank has been set to <code>255</code>, see <a class="el" href="docs_rombanking_mbcs.html#rom_autobanking">rom_autobanking</a>. Unless an alternative output is specified the given object files are updated with the new bank numbers.</p><ul>
262 <li>Can be enabled by using the <code>-autobank</code> argument with <a class="el" href="docs_toolchain.html#lcc">lcc</a>.</li>
263 <li>Must be called after compiling/assembling and before linking.</li>
264 <li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wb-<argument></code></li>
265 </ul>
266 <p ><a class="anchor" id="sdldgb"></a></p>
267 <h2><a class="anchor" id="autotoc_md126"></a>
268 sdldgb</h2>
269 <p >The SDCC linker for the gameboy.</p>
270 <p >For detailed settings see <a class="el" href="docs_toolchain_settings.html#sdldgb-settings">sdldgb-settings</a></p>
271 <p >Links object files (.o) into a .ihx file which can be processed by <a class="el" href="docs_toolchain.html#makebin">makebin</a></p><ul>
272 <li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wl-<argument></code></li>
273 </ul>
274 <p ><a class="anchor" id="ihxcheck"></a></p>
275 <h2><a class="anchor" id="autotoc_md127"></a>
276 ihxcheck</h2>
277 <p >IHX file validator.</p>
278 <p >For detailed settings see <a class="el" href="docs_toolchain_settings.html#ihxcheck-settings">ihxcheck-settings</a></p>
279 <p >Checks .ihx files produced by <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a> for correctness.</p><ul>
280 <li>It will warn if there are multiple writes to the same ROM address. This may indicate mistakes in the code or ROM bank overflows</li>
281 <li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wi-<argument></code></li>
282 </ul>
283 <p ><a class="anchor" id="makebin"></a></p>
284 <h2><a class="anchor" id="autotoc_md128"></a>
285 makebin</h2>
286 <p >IHX to ROM converter.</p>
287 <ul>
288 <li>For detailed settings see <a class="el" href="docs_toolchain_settings.html#makebin-settings">makebin-settings</a></li>
289 <li>For makebin <code>-yt</code> MBC values see <a class="el" href="docs_rombanking_mbcs.html#setting_mbc_and_rom_ram_banks">setting_mbc_and_rom_ram_banks</a></li>
290 </ul>
291 <p >Converts .ihx files produced by <a class="el" href="docs_toolchain.html#sdldgb">sdldgb</a> into ROM files (.gb, .gbc). Also used for setting some ROM header data.</p><ul>
292 <li>Arguments can be passed to it through <a class="el" href="docs_toolchain.html#lcc">lcc</a> using <code>-Wm-<argument></code></li>
293 </ul>
294 <p ><a class="anchor" id="gbdk_utilities"></a></p>
295 <h1><a class="anchor" id="autotoc_md129"></a>
296 GBDK Utilities</h1>
297 <p ><a class="anchor" id="utility_gbcompress"></a></p>
298 <h2><a class="anchor" id="autotoc_md130"></a>
299 GBCompress</h2>
300 <p >Compression utility.</p>
301 <p >For detailed settings see <a class="el" href="docs_toolchain_settings.html#gbcompress-settings">gbcompress-settings</a></p>
302 <p >Compresses (and decompresses) binary file data with the gbcompress algorithm (also used in GBTD/GBMB). Decompression support is available in GBDK:</p><ul>
303 <li><a class="el" href="gb_2gbdecompress_8h.html#gb_decompress">gb_decompress()</a>, <a class="el" href="gb_2gbdecompress_8h.html#gb_decompress_bkg_data">gb_decompress_bkg_data()</a>, <a class="el" href="gb_2gbdecompress_8h.html#gb_decompress_win_data">gb_decompress_win_data()</a>, <a class="el" href="gb_2gbdecompress_8h.html#gb_decompress_sprite_data">gb_decompress_sprite_data()</a></li>
304 <li>The <code>cross-platform/gbdecompress</code> example demonstrates how to use this compression</li>
305 </ul>
306 <p >The utility can also compress (and decompress) using block style RLE encoding with the <code>--alg=rle</code> flag. Decompression support is available in GBDK:</p><ul>
307 <li><a class="el" href="rledecompress_8h.html#rle_init">rle_init()</a>, <a class="el" href="rledecompress_8h.html#rle_decompress">rle_decompress()</a></li>
308 <li>The <code>cross-platform/rle_map</code> example demonstrates how to use this compression</li>
309 </ul>
310 <p ><a class="anchor" id="utility_png2asset"></a></p>
311 <h2><a class="anchor" id="autotoc_md131"></a>
312 png2asset</h2>
313 <p >Tool for converting PNGs into GBDK format MetaSprites and Tile Maps.</p>
314 <ul>
315 <li>Convert single or multiple frames of graphics into metasprite structured data for use with the ...metasprite...() functions.</li>
316 <li>When <code>-map</code> is used, converts images into Tile Maps and matching Tile Sets</li>
317 <li>Supports Game Boy / Color, SGB borders, SMS/GG, NES</li>
318 </ul>
319 <p >For detailed settings see <a class="el" href="docs_toolchain_settings.html#png2asset-settings">png2asset-settings</a> <br />
320 For working with sprite properties (including cgb palettes), see <a class="el" href="gb_2metasprites_8h.html#metasprite_and_sprite_properties">metasprite_and_sprite_properties</a> <br />
321 For API support see <a class="el" href="gb_2metasprites_8h.html#move_metasprite">move_metasprite()</a> and related functions in <a class="el" href="sms_2metasprites_8h.html">metasprites.h</a> <br />
322 </p>
323 <h3><a class="anchor" id="autotoc_md132"></a>
324 Working with png2asset</h3>
325 <ul>
326 <li>The origin (pivot) for the metasprite is not required to be in the upper left-hand corner as with regular hardware sprites. See <code>-px</code> and <code>-py</code>.</li>
327 <li>The conversion process supports using both SPRITES_8x8 (<code>-spr8x8</code>) and SPRITES_8x16 mode (<code>-spr8x16</code>). If 8x16 mode is used then the height of the metasprite must be a multiple of 16.</li>
328 </ul>
329 <h4><a class="anchor" id="autotoc_md133"></a>
330 Terminology</h4>
331 <p >The following abbreviations are used in this section:</p><ul>
332 <li>Original Game Boy and Game Boy Pocket style hardware: <code>DMG</code></li>
333 <li>Game Boy Color: <code>CGB</code></li>
334 </ul>
335 <h4><a class="anchor" id="autotoc_md134"></a>
336 Conversion Process</h4>
337 <p >png2asset accepts any png as input, although that does not mean any image will be valid. The program will follow the next steps:</p><ul>
338 <li>The image will be subdivided into tiles of 8x8 or 8x16.</li>
339 <li>For each tile a palette will be generated.</li>
340 <li>If there are more than 4 colors in the palette it will throw an error.</li>
341 <li>The palette will be sorted from darkest to lightest. If there is a transparent color that will be the first one (this will create a palette that will also work with <code>DMG</code> devices).</li>
342 <li>If there are more than 8 palettes the program will throw an error.</li>
343 </ul>
344 <p >With all this, the program will generate a new indexed image (with palette), where each 4 colors define a palette and all colors within a tile can only have colors from one of these palettes</p>
345 <p >It is also posible to pass a indexed 8-bit png with the palette properly sorted out, using <code>-keep_palette_order</code></p><ul>
346 <li>Palettes will be extracted from the image palette in groups of 4 colors.</li>
347 <li>Each tile can only have colors from one of these palettes per tile.</li>
348 <li>The maximum number of colors is 32.</li>
349 </ul>
350 <p >For indexed color images, sometimes RGB paint programs mix up indexed colors in tiles if the same color exists in multiple palettes.</p><ul>
351 <li><code>-repair_indexed_pal</code> can be used to fix this problem, though tiles must still follow the rule of using only one palette per tile.</li>
352 </ul>
353 <p >Using this image a tileset will be created</p><ul>
354 <li>Duplicated tiles will be removed.</li>
355 <li>Tiles will be matched without mirror, using vertical mirror, horizontal mirror or both (use <code>-noflip</code> to turn off matching mirrored tiles).</li>
356 <li>The palette won't be taken into account for matching, only the pixel color order, meaning there will be a match between tiles using different palettes but looking identical on grayscale.</li>
357 </ul>
358 <h4><a class="anchor" id="autotoc_md135"></a>
359 Maps</h4>
360 <p >Passing <code>-map</code> the png can be converted to a map that can be used in both the background and the window. In this case, png2asset will generate:</p><ul>
361 <li>The palettes</li>
362 <li>The tileset</li>
363 <li>The map</li>
364 <li>The color info<ul>
365 <li>By default, an array of palette index for each tile. This is not the way the hardware works but it takes less space and will create maps compatibles with both <code>DMG</code> and <code>CGB</code> devices.</li>
366 <li>Passing <code>-use_map_attributes</code> will create an array of map attributes. It will also add mirroring info for each tile and because of that maps created with this won't be compatible with <code>DMG</code>.<ul>
367 <li>Use <code>-noflip</code> to make background maps which are compatible with <code>DMG</code> devices.</li>
368 </ul>
369 </li>
370 </ul>
371 </li>
372 </ul>
373 <h4><a class="anchor" id="autotoc_md136"></a>
374 Meta sprites</h4>
375 <p >By default the png will be converted to metasprites. The image will be subdivided into meta sprites of <code>-sw</code> x <code>-sh</code>. In this case png2asset will generate:</p><ul>
376 <li>The metasprites, containing an array of:<ul>
377 <li>tile index</li>
378 <li>y offset</li>
379 <li>x offset</li>
380 <li>flags, containing the mirror info, the palettes for both DMG and GBC and the sprite priority</li>
381 </ul>
382 </li>
383 <li>The metasprites array</li>
384 </ul>
385 <h4><a class="anchor" id="autotoc_md137"></a>
386 Super Game Boy Borders (SGB)</h4>
387 <p >Screen border assets for the Super Game Boy can be generated using png2asset.</p>
388 <p >The following flags should be used to perform the conversion:</p><ul>
389 <li><code><input_border_file.png> -map -bpp 4 -max_palettes 4 -pack_mode sgb -use_map_attributes -c <output_border_data.c></code></li>
390 <li>Where <code><input_border_file.png></code> is the image of the SGB border (256x224) and <code><output_border_data.c></code> is the name of the source file to write the assets out to.</li>
391 </ul>
392 <p >See the <code>sgb_border</code> example project for more details.</p>
393 <p ><a class="anchor" id="utility_makecom"></a></p>
394 <h2><a class="anchor" id="autotoc_md138"></a>
395 makecom</h2>
396 <p >Converts a binary .rom file to .msxdos com format, including splitting the banks up into separate files.</p>
397 <ul>
398 <li>For detailed settings see <a class="el" href="docs_toolchain_settings.html#makecom-settings">makecom-settings</a></li>
399 </ul>
400 <p ><a class="anchor" id="utility_makenes"></a></p>
401 <h2><a class="anchor" id="autotoc_md139"></a>
402 makenes</h2>
403 <p >Converts a binary .rom file to a .nes file, prepending a 16-byte header.</p>
404 <ul>
405 <li>For an explanation of the interpretation of header bits see <a href="https://www.nesdev.org/wiki/INES">https://www.nesdev.org/wiki/INES</a></li>
406 </ul>
407 <p ><a class="anchor" id="utility_png2hicolorgb"></a></p>
408 <h2><a class="anchor" id="autotoc_md140"></a>
409 png2hicolorgb</h2>
410 <p >An updated version of Glen Cook's Windows GUI "hicolour.exe" 1.2 conversion tool for the Game Boy Color. The starting code base was the 1.2 release.</p>
411 <ul>
412 <li>For detailed settings see <a class="el" href="docs_toolchain_settings.html#png2hicolorgb-settings">Hi Color</a> on the Game Boy Color is a technique for displaying backgrounds with thousands of colors instead being limtied to 32 colors for the entire screen background. It achieves this by changing ~16 colors of the background palette per scanline. The main tradeoffs are that it uses much of the Game Boy's available cpu processing per frame and requires more ROM space. The tile patterns, map, attributes and per-scanline palettes are pre-calculated using the PC based conversion tool.</li>
413 </ul>
414 <p >For the current GBDK example ISR implementation there is a limit of 6 sprites per line before the hi-color timing breaks down and there start to be background artifacts.</p>
415 <p >Example: <code>png2hicolorgb myimage.png --csource -o=my_output_filename</code> Example with higher quality (slower conversion): <code>png2hicolorgb myimage.png --csource -o=my_output_filename --type=3 -L=2 -R=2</code></p>
416 <div class="fragment"><div class="line">Historical credits and info:</div>
417 <div class="line"> Original Concept : Icarus Productions</div>
418 <div class="line"> Original Code : Jeff Frohwein</div>
419 <div class="line"> Full Screen Modification : Anon</div>
420 <div class="line"> Adaptive Code : Glen Cook</div>
421 <div class="line"> Windows Interface : Glen Cook</div>
422 <div class="line"> Additional Windows Programming : Rob Jones</div>
423 <div class="line"> Original Quantiser Code : Benny</div>
424 <div class="line"> Quantiser Conversion : Glen Cook</div>
425 </div><!-- fragment --><h3><a class="anchor" id="autotoc_md141"></a>
426 Additional Details</h3>
427 <p >For technical details about the conversion process and rendering, see: <a href="https://github.com/bbbbbr/png2hicolorgb">https://github.com/bbbbbr/png2hicolorgb</a></p>
428 <p ><a class="anchor" id="utility_romusage"></a></p>
429 <h2><a class="anchor" id="autotoc_md142"></a>
430 romusage</h2>
431 <p >A utility for estimating usage of Game Boy and SMS/GG ROMs from .noi and .map files, binary ROMs and more.</p>
432 <ul>
433 <li>For detailed settings see <a class="el" href="docs_toolchain_settings.html#romusage-settings">romusage-settings</a></li>
434 </ul>
435 <p >Example: <code>romusage myprogram.noi -g</code> </p>
436 </div></div><!-- contents -->
437 </div><!-- PageDoc -->
438 </div><!-- doc-content -->
439 <!-- start footer part -->
440 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
441 <ul>
442 <li class="navelem"><a class="el" href="index.html">General Documentation</a></li>
443 <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>
444 </ul>
445 </div>
446 </body>
447 </html>
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.