gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 82b396af81ef86a4dcaf93abaacaa9c2159a755c parent 159ac56d7c8355490f6e89bdf772ab89f03da16b Author: bbbbbr <bbbbbr@users.noreply.github.com> Date: Mon, 14 Feb 2022 22:19:58 -0800 Merge pull request #321 from DaSalba/develop Fixed typos in docs Diffstat:
| M | docs/pages/01_getting_started.md | 12 | ++++++------ |
| M | docs/pages/02_links_and_tools.md | 10 | +++++----- |
| M | docs/pages/03_using_gbdk.md | 11 | +++++------ |
| M | docs/pages/04_coding_guidelines.md | 18 | +++++++++--------- |
| M | docs/pages/05_banking_mbcs.md | 51 | +++++++++++++++++++++++++-------------------------- |
| M | docs/pages/06_toolchain.md | 51 | +++++++++++++++++++++++++-------------------------- |
| M | docs/pages/06b_supported_consoles.md | 10 | +++++----- |
| M | docs/pages/07_sample_programs.md | 6 | +++--- |
| M | docs/pages/08_faq.md | 8 | ++++---- |
9 files changed, 87 insertions(+), 90 deletions(-)
diff --git a/docs/pages/01_getting_started.md b/docs/pages/01_getting_started.md @@ -10,7 +10,7 @@ You can get the latest releases from here: https://github.com/gbdk-2020/gbdk-202 # 2. Compile Example projects Make sure your GBDK-2020 installation is working correctly by compiling some of the included @ref docs_example_programs "example projects". -If everything in works in the steps below and there are no errors reported then each project that was build should have it's on .gb ROM file (or suitable extension for the other supported targets). +If everything works in the steps below and there are no errors reported then each project that was built should have its own .gb ROM file (or suitable extension for the other supported targets). ## Windows (without Make installed): Navigate to a project within the example projects folder (`"examples\gb\"` under your GBDK-2020 install folder) and open a command line. Then type: @@ -37,7 +37,7 @@ __To create a new project use a template!__ There are template projects included in the @ref docs_example_programs "GBDK example projects" to help you get up and running. Their folder names start with `template_`. -1. Copy one of the template folders to a new folder name +1. Copy one of the template folders to a new folder name. 2. If you moved the folder out of the GBDK examples then you __must__ update the `GBDK` path variable and/or the path to `LCC` in the `Makefile` or `compile.bat` so that it will still build correctly. @@ -62,7 +62,7 @@ If you have a specific project in mind, consider what hardware want to target. I What size will your game or program be? - 32K Cart (no-MBC required) - Larger than 32K (MBC required) - - See more details about @ref docs_rombanking_mbcs "ROM Banking and MBCs". + - See more details about @ref docs_rombanking_mbcs "ROM Banking and MBCs" What console platform(s) will it run on? - Game Boy (GB/GBC) @@ -86,7 +86,7 @@ Tracking down problems in code is easier with a debugger. Emulicious has a @ref # 8. Try a GBDK Tutorial You might want to start off with a guided GBDK tutorial from the @ref links_gbdk_tutorials "GBDK Tutorials section". - - __Note:__ Tutorials (or parts of them) may be based on the older GBDK from the 2000's before it was updated to be GBDK-2020. The general principals are all the same, but the setup and parts of the @ref docs_toolchain "toolchain" (compiler/etc) may be somewhat different and some links may be outdated (pointing to the old GBDK or old tools). + - __Note:__ Tutorials (or parts of them) may be based on the older GBDK from the 2000's before it was updated to be GBDK-2020. The general principles are all the same, but the setup and parts of the @ref docs_toolchain "toolchain" (compiler/etc) may be somewhat different and some links may be outdated (pointing to the old GBDK or old tools). # 9. Read up! @@ -124,7 +124,7 @@ If you plan to use GBTD / GBMB for making graphics, make sure to get the version ## LCC and SDCC flags that are not needed The following flag is no longer needed with @ref lcc and @ref sdcc, it can be removed without any loss of performance. - `-DUSE_SFR` - - Behavior formerly enabled by USE_SFR_FOR_REG is on by default now (no need to specify it, it isn't a tested `#ifdef` anymore). check here why: https://gbdev.gg8.se/forums/viewtopic.php?id=697 + - Behavior formerly enabled by USE_SFR_FOR_REG is on by default now (no need to specify it, it isn't a tested `#ifdef` anymore). Check here why: https://gbdev.gg8.se/forums/viewtopic.php?id=697 ## ROM Header Settings (such as Color, SGB, etc) Setting ROM bytes directly with `-Wl-yp0x<address>=0x<value>` is no longer supported. Instead use @ref makebin flags. For example, use `-Wm-yC` instead of `-Wl-yp0x143=0xC0`. See @ref faq_gb_type_header_setting. @@ -141,6 +141,6 @@ Do not `#include` `.c` source files into other `.c` source files. Instead create Modern project templates are included with GBDK-2020. Using them (and their Makefile or compile.bat) as a starting point for projects is recommended and can help ensure better default settings and project organization. ## Use hUGEtracker instead of gbt_player -hUGEtracker and it's driver @ref hUGEdriver are smaller, more efficient and more versatile than gbt_player. +hUGEtracker and its driver @ref hUGEdriver are smaller, more efficient and more versatile than gbt_player. diff --git a/docs/pages/02_links_and_tools.md b/docs/pages/02_links_and_tools.md @@ -36,7 +36,7 @@ This is a brief list of useful tools and information. It is not meant to be comp # Sega Master System / Game Gear Documentation - @anchor smspower __SMS Power!__ - Community site with technical documentation, reviews and other content related to the Sega 8-bit systems. + Community site with technical documentation, reviews and other content related to the Sega 8-bit systems. https://www.smspower.org/ @@ -44,7 +44,7 @@ This is a brief list of useful tools and information. It is not meant to be comp # Tutorials - @anchor tutorials_larolds __Larold's Jubilant Junkyard Tutorials__ - Several walk throughs about the fundamentals of developing for the Game Boy with GBDK-2020. There are simple examples with source code. + Several walk throughs about the fundamentals of developing for the Game Boy with GBDK-2020. There are simple examples with source code. https://laroldsjubilantjunkyard.com/tutorials/ - @anchor tutorials_gamingmonsters @@ -54,7 +54,7 @@ This is a brief list of useful tools and information. It is not meant to be comp https://github.com/gingemonster/GamingMonstersGameBoySampleCode - @anchor tutorials_typorter - __Pocket Leage Tutortial__ + __Pocket Leage Tutorial__ https://blog.ty-porter.dev/development/2021/04/04/writing-a-gameboy-game-in-2021-pt-0.html @@ -73,7 +73,7 @@ This is a brief list of useful tools and information. It is not meant to be comp @anchor toxa_gbtd_gbmb __Game Boy Tile Designer and Map Builder (GBTD / GBMB)__ Sprite / Tile editor and Map Builder that can export to C that works with GBDK. - This is an updated version with const export fixed and other improvments. + This is an updated version with const export fixed and other improvements. https://github.com/gbdk-2020/GBTD_GBMB - A GIMP plugin to read/write GBR/GBM files and do map conversion: @@ -145,7 +145,7 @@ This is a brief list of useful tools and information. It is not meant to be comp @anchor tools_build_ci_cd # Continuous Integration and Deployment - @anchor GBDK_GitHub_Action_Builder - __GBDK GitHub Action Builder__ + __GBDK GitHub Action Builder__ A Github Action which provides basic CI/CD for building projects based on GBDK (not for building GBDK itself). https://github.com/wujood/gbdk-2020-github-builder diff --git a/docs/pages/03_using_gbdk.md b/docs/pages/03_using_gbdk.md @@ -50,9 +50,9 @@ Interrupt handlers are called in sequence. To install a new interrupt handler, d See the `irq` example project for additional details for a complete example. ## Using your own Interrupt Dispatcher -If you want to use your own Interrupt Dispatcher instead of the GBDK chained dispatcher (for improved performance), then don't call the `add_...()` function for the respective interrupt and it's dispatcher won't be installed. +If you want to use your own Interrupt Dispatcher instead of the GBDK chained dispatcher (for improved performance), then don't call the `add_...()` function for the respective interrupt and its dispatcher won't be installed. - Exception: the VBL dispatcher will always be linked in at compile time. - - For the SIO interrupt, also do not make any standard SIO calls to avoid having it's dispatcher installed. + - For the SIO interrupt, also do not make any standard SIO calls to avoid having its dispatcher installed. Then, @ref ISR_VECTOR() or @ref ISR_NESTED_VECTOR() can be used to install a custom ISR handler. @@ -76,7 +76,7 @@ Including @ref stdio.h and using functions such as @ref printf() will use a larg # Copying Functions to RAM and HIRAM -See the `ram_function` example project included with GBDK demonstrates copying functions to RAM and HIRAM. +See the `ram_function` example project included with GBDK which demonstrates copying functions to RAM and HIRAM. `Warning!` Copying of functions is generally not safe since they may contain jumps to absolute addresses that will not be converted to match the new location. @@ -119,7 +119,7 @@ It is possible to assemble and link files written in ASM alongside files written - A C identifier `i` will be called `_i` in assembly. - Results are always returned into the `DE` register. - Parameters are passed on the stack (starting at `SP+2` because the return address is also saved on the stack). - - Assembly identifier are exported using the `.globl` directive. + - Assembly identifiers are exported using the `.globl` directive. - You can access GameBoy hardware registers using `_reg_0xXX` where `XX` is the register number (see `sound.c` for an example). - Registers must be preserved across function calls (you must store them at function begin, and restore them at the end), except `HL` (and `DE` when the function returns a result). @@ -170,4 +170,4 @@ See the `incbin` example project for a demo of how to use it. ## SDCC - Const arrays declared with `somevar[n] = {x}` will __NOT__ get initialized with value `x`. This may change when the SDCC RLE initializer is fixed. Use memset for now if you need it. - - SDCC banked calls and @ref far_pointers in GBDK only save one byte for the ROM bank, so for example they are limtied to __bank 15__ max for MBC1 and __bank 255__ max for MBC5. See @ref banked_calls for more details. - + - SDCC banked calls and @ref far_pointers in GBDK only save one byte for the ROM bank, so for example they are limtied to __bank 15__ max for MBC1 and __bank 255__ max for MBC5. See @ref banked_calls for more details. diff --git a/docs/pages/04_coding_guidelines.md b/docs/pages/04_coding_guidelines.md @@ -1,7 +1,7 @@ @page docs_coding_guidelines Coding Guidelines # Learning C / C fundamentals -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 pitfals. +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. @anchor docs_c_tutorials @@ -40,7 +40,7 @@ If you wish to use the original tools, you must add the `const` keyword every ti ## Variables - Use 8-bit values as much as possible. They will be much more efficient and compact than 16 and 32 bit types. - - Prefer unsigned variables to signed ones: The code generated will be generally more efficient, especially when comparing two values. + - Prefer unsigned variables to signed ones: the code generated will be generally more efficient, especially when comparing two values. - Use explicit types so you always know the size of your variables. `int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t` and `bool`. These are standard types defined in `stdint.h` (`#include <stdint.h>`) and `stdbool.h` (`#include <stdbool.h>`). @@ -48,7 +48,7 @@ If you wish to use the original tools, you must add the `const` keyword every ti - Global and local static variables are generally more efficient than local non-static variables (which go on the stack and are slower and can result in slower code). - @anchor const_array_data - `const` keyword: Use const for arrays, structs and variables with read-only (constant) data. It will reduce ROM, RAM and CPU usage significantly. Non-`const` values are loaded from ROM into RAM inefficiently, and there is no benefit in loading them into the limited available RAM if they aren't going to be changed. + `const` keyword: use const for arrays, structs and variables with read-only (constant) data. It will reduce ROM, RAM and CPU usage significantly. Non-`const` values are loaded from ROM into RAM inefficiently, and there is no benefit in loading them into the limited available RAM if they aren't going to be changed. - Here is how to delcare `const` pointers and variables: - non-const pointer to a const variable: `const uint8_t * some_pointer;` @@ -78,7 +78,7 @@ If you wish to use the original tools, you must add the `const` keyword every ti fixed player[2]; ... - // Modify player position using it's 16 bit representation + // Modify player position using its 16 bit representation player[0].w += player_speed_x; player[1].w += player_speed_y; ... @@ -101,11 +101,11 @@ If you wish to use the original tools, you must add the `const` keyword every ti - Modulo by powers of 2. For example: `(n % 8)` will be optimized to `(n & 0x7)`. - If you need decimal numbers to count or display a score, you can use the GBDK BCD ([binary coded decimal](https://en.wikipedia.org/wiki/Binary-coded_decimal)) number functions. See: @ref bcd.h and the `BCD` example project included with GBDK. - - Avoid long lists of function parameters. Passing many parameters can add overhead, especially if the function is called often. When applicable globals and local static vars can be used instead. + - Avoid long lists of function parameters. Passing many parameters can add overhead, especially if the function is called often. Globals and local static vars can be used instead when applicable. - - Use inline functions if the function is short. (with the `inline` keyword, such as `inline uint8_t myFunction() { ... }`) + - Use inline functions if the function is short (with the `inline` keyword, such as `inline uint8_t myFunction() { ... }`). - - Do not use recursive functions + - Do not use recursive functions. <!-- This entry needs re-work. Signed vs unsigned, current SDCC optimizations... - Prefer `==` and `!=` comparison operators to `<`, `<=`, `>`, and `>=`. The code will be shorter and quicker. @@ -157,7 +157,7 @@ If you wish to use the original tools, you must add the `const` keyword every ti @anchor docs_chars_varargs ## chars and vararg functions -In standard C when `chars` are passed to a function with variadic arguments (varargs, those delcared with `...` as a parameter), such as @ref printf(), those `chars` get automatically promoted to `ints`. For an 8 bit cpu such as the Game Boy's, this is not as efficient or desireable in most cases. So the default SDCC behavior, which GBDK-2020 expects, is that chars will remain chars and _not_ get promoted to ints when **explicitly cast as chars while calling a varargs function**. +In standard C when `chars` are passed to a function with variadic arguments (varargs, those declared with `...` as a parameter), such as @ref printf(), those `chars` get automatically promoted to `ints`. 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 _not_ get promoted to ints when **explicitly cast as chars while calling a varargs function**. - They must be explicitly re-cast when passing them to a varargs function, even though they are already declared as chars. @@ -223,5 +223,5 @@ The order these segments are linked together is determined by crt0.s and is curr As the `_BSS` segment occurs outside the ROM area you can only use .ds to reserve space in it. -While you don't have to use the `_CODE` and `_DATA` distinctions in assembler you may wish to do so consistancy. +While you don't have to use the `_CODE` and `_DATA` distinctions in assembler you may wish to do so to maintain consistency. diff --git a/docs/pages/05_banking_mbcs.md b/docs/pages/05_banking_mbcs.md @@ -31,9 +31,9 @@ To assign code and constant data (such as graphics) to a ROM bank and use it: ## Setting the ROM bank for a Source file The ROM and RAM bank for a source file can be set in a couple different ways. Multiple different banks cannot be assigned inside the same source file (unless the `__addressmod` method is used), but multiple source files can share the same bank. -If no ROM and RAM bank are speciied for a file then the default _CODE, _BSS and _DATA segments are used. +If no ROM and RAM bank are specified for a file then the default _CODE, _BSS and _DATA segments are used. -Ways to set the ROM bank for a Source file +Ways to set the ROM bank for a Source file: - `#pragma bank <N>` at the start of a source file. Example (ROM bank 2): `#pragma bank 2` - The lcc switch for ROM bank `-Wf-bo<N>`. Example (ROM bank 2): `-Wf-bo2` - Using @ref rom_autobanking @@ -42,7 +42,7 @@ Note: You can use the `NONBANKED` keyword to define a function as non-banked if ## Setting the RAM bank for a Source file - - Using the lcc switch for RAM bank `-Wf-ba<N>`. Example (ROM bank 3): `-Wf-bo3` + - Using the lcc switch for RAM bank `-Wf-ba<N>`. Example (RAM bank 3): `-Wf-ba3` @anchor setting_mbc_and_rom_ram_banks @@ -84,10 +84,9 @@ Additional details available at [Pandocs](https://gbdev.io/pandocs/The_Cartridge ## Getting Bank Numbers The bank number for a banked function, variable or source file can be stored and retrieved using the following macros: - - @ref BANKREF(): Create a reference for retrieving the bank number of a variable or function - - @ref BANK(): Retrieve a bank number using a reference created with @ref BANKREF() - - @ref BANKREF_EXTERN() - Make a @ref BANKREF() reference residing in another source - file accessible in the current file for use with @ref BANK(). + - @ref BANKREF(): create a reference for retrieving the bank number of a variable or function + - @ref BANK(): retrieve a bank number using a reference created with @ref BANKREF() + - @ref BANKREF_EXTERN(): Make a @ref BANKREF() reference residing in another source file accessible in the current file for use with @ref BANK(). ## Banking and Functions @@ -95,23 +94,23 @@ The bank number for a banked function, variable or source file can be stored and @anchor banked_keywords ### BANKED/NONBANKED keywords - `BANKED`: - - The function will use banked sdcc calls - - Placed in the bank selected by it's source file (or compiler switches) + - The function will use banked sdcc calls. + - Placed in the bank selected by its source file (or compiler switches). - `NONBANKED`: - - Placed in the non-banked lower 16K region (bank 0), regardless of the bank selected by it's source file. + - Placed in the non-banked lower 16K region (bank 0), regardless of the bank selected by its source file. - `<not-specified>`: - - The function does not use sdcc banked calls (`near` instead of `far`) - - Placed in the bank selected by it's source file (or compiler switches) + - The function does not use sdcc banked calls (`near` instead of `far`). + - Placed in the bank selected by its source file (or compiler switches). @anchor banked_calls ### Banked Function Calls -Banked functions can be called as follows. - - When defined with the `BANKED` keyword. Example: `void my_function() BANKED { do stuff }` in a source file which has had it's bank set (see above). +Banked functions can be called as follows: + - When defined with the `BANKED` keyword. Example: `void my_function() BANKED { do stuff }` in a source file which has had its bank set (see above). - Using @ref far_pointers - - When defined with an area set up using the `__addressmod` keyword (See the `banks_new` example project and the SDCC manual for details) + - When defined with an area set up using the `__addressmod` keyword (see the `banks_new` example project and the SDCC manual for details). - Using @ref SWITCH_ROM() (and related functions for other MBCs) to manually switch in the required bank and then call the function. -Non-banked functions (either in fixed Bank 0, or in an non-banked ROM with no MBC) +Non-banked functions (either in fixed Bank 0, or in an non-banked ROM with no MBC): - May call functions in any bank: __YES__ - May use data in any bank: __YES__ @@ -121,7 +120,7 @@ Banked functions (located in a switchable ROM bank) - May use data in any bank: __NO__ (may only use data from currently active banks) Limitations: - - SDCC banked calls and far_pointers in GBDK only save one byte for the ROM bank. So, for example, they are limtied to __bank 31__ max for MBC1 and __bank 255__ max for MBC5. This is due to the bank switching for those MBCs requiring a second, additional write to select the upper bits for more banks (banks 32+ in MBC1 and banks 256+ in MBC5). + - SDCC banked calls and far_pointers in GBDK only save one byte for the ROM bank. So, for example, they are limited to __bank 31__ max for MBC1 and __bank 255__ max for MBC5. This is due to the bank switching for those MBCs requiring a second, additional write to select the upper bits for more banks (banks 32+ in MBC1 and banks 256+ in MBC5). ## Const Data (Variables in ROM) @@ -185,14 +184,14 @@ The global variable @ref _current_bank is updated automatically when calling @re # Auto-Banking A ROM bank auto-assignment feature was added in GBDK 2020 4.0.2. -Instead of having to manually specify which bank a source file will reside it, the banks can be assigned automatically to make the best use of space. The bank assignment operates on object files, after compiling/assembling and before linking. +Instead of having to manually specify which bank a source file will reside in, the banks can be assigned automatically to make the best use of space. The bank assignment operates on object files, after compiling/assembling and before linking. -To turn on auto-banking, use the `-autobank` argument with lcc +To turn on auto-banking, use the `-autobank` argument with lcc. For a source example see the `banks_autobank` project. In the source files you want auto-banked, do the following: - - Set the source file to be autobanked `#pragma bank 255` (this sets the temporary bank to `255`, which @ref bankpack then updates when repacking) + - Set the source file to be autobanked `#pragma bank 255` (this sets the temporary bank to `255`, which @ref bankpack then updates when repacking). - Create a reference to store the bank number for that source file: `BANKREF(<some-bank-reference-name>)`. - More than one `BANKREF()` may be created per file, but they should always have unique names. @@ -223,11 +222,11 @@ Making sure bankpack checks all files: Recommended: .c and .s -> (compiler) .o -> (bankpack) -> .rel -> (linker) ... -> .gb - - It is important because when bankpack assigns a bank for an autobanked (bank=255) object file (.o) it rewrites the bank and will then no longer see the file as one that needs to be auto-banked. That file will then remain in it's previously assigned bank until a source change causes the compiler to rebuild it to an object file again which resets it's bank to 255. + - It is important because when bankpack assigns a bank for an autobanked (bank=255) object file (.o) it rewrites the bank and will then no longer see the file as one that needs to be auto-banked. That file will then remain in its previously assigned bank until a source change causes the compiler to rebuild it to an object file again which resets its bank to 255. - For example consider a fixed-bank source file growing too large to share a bank with an auto-banked source file that was previously assigned to it. To avoid a bank overflow it would be important to have the auto-banked file check every time whether it can share that bank or not. - - See @ref bankpack for more options and settings + - See @ref bankpack for more options and settings. @@ -250,8 +249,8 @@ In order to see how much space is used or remains available in a bank, you can u # Banking example projects There are several projects in the GBDK 2020 examples folder which demonstrate different ways to use banking. - - `Banks`: A basic banking example - - `Banks_new`: Examples of using new bank assignment and calling conventions available in GBDK 2020 and it's updated SDCC version. - - `Banks_farptr`: Using far pointers which have the bank number built into the pointer. - - `Banks_autobank`: Shows how to use the bank auto-assignment feature of in GBDK 2020 4.0.2 or later, instead of having to manually specify which bank a source file will reside it. + - `Banks`: a basic banking example + - `Banks_new`: examples of using new bank assignment and calling conventions available in GBDK 2020 and its updated SDCC version. + - `Banks_farptr`: using far pointers which have the bank number built into the pointer. + - `Banks_autobank`: shows how to use the bank auto-assignment feature in GBDK 2020 4.0.2 or later, instead of having to manually specify which bank a source file will reside it. diff --git a/docs/pages/06_toolchain.md b/docs/pages/06_toolchain.md @@ -5,7 +5,7 @@ # Overview GBDK 2020 uses the SDCC compiler along with some custom tools to build Game Boy ROMs. - All tools are located under `bin/` -- The typical order of tools called is as follows. (When using lcc these steps are usually performed automatically.) +- The typical order of tools called is as follows (when using lcc these steps are usually performed automatically). 1. Compile and assemble source files (.c, .s, .asm) with @ref sdcc and @ref sdasgb 2. Optional: perform auto banking with @ref bankpack on the object files 3. Link the object files into .ihx file with @ref sdldgb @@ -77,7 +77,7 @@ The @ref lcc program is the front end compiler driver for the actual compiler, a lcc -o image.gb source1.c source2.s -Arguments to the assembler etc can be passed via lcc using -Wp..., -Wf..., -Wa... and -Wl... to pass options to the pre-processor, compiler, assembler and linker respectivly. Some common options are: +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: - To generate an assembler listing file. @@ -97,12 +97,12 @@ For example, to compile the example in the memory section and to generate a list @subsection Makefiles -Using Makefiles +## Using Makefiles Please see the sample projects included with GBDK-2020 for a couple different examples of how to use Makefiles. You may also want to read a tutorial on Makefiles. For example: -https://makefiletutorial.com/ +https://makefiletutorial.com/ https://www.tutorialspoint.com/makefile/index.htm @anchor build_tools @@ -127,7 +127,7 @@ If preferred, the individual tools can be called directly. @anchor sdcc ## sdcc -SDCC C Source compiler +SDCC C Source compiler. For detailed settings see @ref sdcc-settings @@ -135,7 +135,7 @@ For detailed settings see @ref sdcc-settings @anchor sdasgb ## sdasgb -SDCC Assembler for the gameboy +SDCC Assembler for the Game Boy. For detailed settings see @ref sdasgb-settings @@ -144,14 +144,14 @@ For detailed settings see @ref sdasgb-settings @anchor bankpack ## bankpack -Automatic Bank packer +Automatic Bank packer. For detailed settings see @ref bankpack-settings When enabled, automatically assigns banks for object files where bank has been set to `255`, see @ref rom_autobanking. Unless an alternative output is specified the given object files are updated with the new bank numbers. - Can be enabled by using the `-autobank` argument with @ref lcc. -- Must be called after compiling/assembling and before linking +- Must be called after compiling/assembling and before linking. - Arguments can be passed to it through @ref lcc using `-Wb-<argument>` @@ -167,7 +167,7 @@ Links object files (.o) into a .ihx file which can be processed by @ref makebin @anchor ihxcheck ## ihxcheck -IHX file validator +IHX file validator. For detailed settings see @ref ihxcheck-settings @@ -178,7 +178,7 @@ Checks .ihx files produced by @ref sdldgb for correctness. @anchor makebin ## makebin -IHX to ROM converter +IHX to ROM converter. - For detailed settings see @ref makebin-settings - For makebin `-yt` MBC values see @ref setting_mbc_and_rom_ram_banks @@ -193,18 +193,18 @@ Converts .ihx files produced by @ref sdldgb into ROM files (.gb, .gbc). Also use @anchor utility_gbcompress ## GBCompress -Compresssion utility +Compresssion utility. For detailed settings see @ref gbcompress-settings Compresses (and decompresses) binary file data with the gbcompress algorithm (also used in GBTD/GBMB). Decompression support is available in GBDK, see @ref gb_decompress(). -Can also compress (and decompress) using block style rle encoding with the `--alg=rle` flag. Decompression support is available in GBDK, see @ref rle_decompress(). +Can also compress (and decompress) using block style RLE encoding with the `--alg=rle` flag. Decompression support is available in GBDK, see @ref rle_decompress(). @anchor utility_png2asset ## png2asset -Tool for converting PNGs into GBDK format MetaSprites and Tile Maps +Tool for converting PNGs into GBDK format MetaSprites and Tile Maps. - Convert single or multiple frames of graphics into metasprite structured data for use with the ...metasprite...() functions. - When `-map` is used, converts images into Tile Maps and matching Tile Sets @@ -226,23 +226,23 @@ The following abbreviations are used in this section: #### Conversion Process png2asset accepts any png as input, although that does not mean any image will be valid. The program will follow the next steps: - - The image will be subdivided into tiles of 8x8 or 8x16 - - For each tile a palette will be generated - - If there are more than 4 colors in the palette it will throw an error - - 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 `DMG` devices) - - If there are more than 8 palettes the program will throw an error + - The image will be subdivided into tiles of 8x8 or 8x16. + - For each tile a palette will be generated. + - If there are more than 4 colors in the palette it will throw an error. + - 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 `DMG` devices). + - If there are more than 8 palettes the program will throw an error. 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 It is also posible to pass a indexed 8-bit png with the palette properly sorted out, using `-keep_palette_order` - Palettes will be extracted from the image palette in groups of 4 colors. - - Each tile can only have colors from one of these palettes per tile - - The maximum number of colors is 32 + - Each tile can only have colors from one of these palettes per tile. + - The maximum number of colors is 32. Using this image a tileset will be created - - Duplicated tiles will be removed - - Tiles will be matched without mirror, using vertical mirror, horizontal mirror or both (use `-noflip` to turn off matching mirrored tiles) - - 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 + - Duplicated tiles will be removed. + - Tiles will be matched without mirror, using vertical mirror, horizontal mirror or both (use `-noflip` to turn off matching mirrored tiles). + - 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. #### Maps @@ -252,7 +252,7 @@ Passing `-map` the png can be converted to a map that can be used in both the ba - The map - The color info - 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 `DMG` and `CGB` devices. - - Passing `-use_map_attributes` 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. + - Passing `-use_map_attributes` 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 `DMG`. - Use `-noflip` to make background maps which are compatible with `DMG` devices. #### Meta sprites @@ -273,4 +273,4 @@ The following flags should be used to perform the conversion: - Where `<input_border_file.png>` is the image of the SGB border (256x224) and `<output_border_data.c>` is the name of the source file to write the assets out to. -See the `sgb_border` example project for more details. - +See the `sgb_border` example project for more details. diff --git a/docs/pages/06b_supported_consoles.md b/docs/pages/06b_supported_consoles.md @@ -13,14 +13,14 @@ As of version `4.0.5` GBDK includes support for other consoles in addition to th - Sega Master System (SMS) - Sega Game Gear (GG) -While the GBDK API has many convenience functions that work the same or similar across different consoles, it's important to keep their different capabilities in mind when writing code intended to run on more than one. Some (but not all) of the differences are screen sizes, color abilities, memory layouts, processor type (z80 vs gbz80/sm83) and speed. +While the GBDK API has many convenience functions that work the same or similar across different consoles, it's important to keep their different capabilities in mind when writing code intended to run on more than one. Some (but not all) of the differences are screen sizes, color capabilities, memory layouts, processor type (z80 vs gbz80/sm83) and speed. @anchor docs_consoles_compiling # Cross Compiling for Different Consoles ## lcc -When compiling and building through @ref lcc use the `-m<port>:<plat>` flag to select the desired console via it's port and platform combination. +When compiling and building through @ref lcc use the `-m<port>:<plat>` flag to select the desired console via its port and platform combination. ## sdcc @@ -74,7 +74,7 @@ There are several constant \#defines that can be used to help select console spe - `MEGADUCK` will be \#defined - - When `<sms/sms.h >` is included (either directly or through `<gbdk/platform.h>`) + - When `<sms/sms.h>` is included (either directly or through `<gbdk/platform.h>`) - When building for Master System - `SEGA` will be \#defined - `MASTERSYSTEM` will be \#defined @@ -128,7 +128,7 @@ In the example @ref utility_png2asset is used to generate assets in the native f The Analogue Pocket is (for practical purposes) functionally identical to the Game Boy / Color, but has a couple altered register flag and address definitions and a different boot logo. In order for software to be easily ported to the Analogue Pocket, or to run on both, use the following practices. ## Registers and Flags -Use API defined registers and register flags instead of hardwired ones +Use API defined registers and register flags instead of hardwired ones. - LCDC register: @ref LCDC_REG or @ref rLCDC - STAT register: @ref STAT_REG or @ref rSTAT - LCDC flags: -> LCDCF_... (example: @ref LCDCF_ON) @@ -156,7 +156,7 @@ Use API defined registers and register flags instead of hardwired ones ### Tile and Map Data in 2bpp Game Boy Format - @ref set_bkg_data() and @ref set_sprite_data() will load 2bpp tile data in "game boy" format on both GB and SMS/GG. - On the SMS/GG @ref set_2bpp_palette() sets 4 colors that will be used when loading 2bpp assets with set_bkg_data(). This allows GB assets to be easily colorized without changing the asset format. There is some performance penalty for using the conversion. -- @ref set_bkg_tiles() loads 1-byte-per-tile tilemaps both for the GB and SMS/GG +- @ref set_bkg_tiles() loads 1-byte-per-tile tilemaps both for the GB and SMS/GG. ### Tile and Map Data in Native Format Use the following api calls when assets are avaialble in the native format for each platform. diff --git a/docs/pages/07_sample_programs.md b/docs/pages/07_sample_programs.md @@ -51,7 +51,7 @@ The gb-dtmf, written by Osamu Ohashi, is a Dual Tone Multi-Frequency (DTMF) gene # gbdecompress -Demonstrates using gbdecompress to load a compressed tile set into vram. +Demonstrates using gbdecompress to load a compressed tile set into VRAM. # irq @@ -71,7 +71,7 @@ Demonstrates using the metasprite features to move and animate a large sprite. # lcd isr wobble -An example of how to use the LCD ISR for visual special effects +An example of how to use the LCD ISR for visual special effects. # paint @@ -104,7 +104,7 @@ A collection of examples showing how to use the Super Game Boy API features. @anchor examples_sound_sample # sound -The sound example is meant for experimenting with the soung generator of the GameBoy (to use on a real GameBoy). The four different sound modes of the GameBoy are available. It also demonstrates the use of bit fields in C (it's a quick hack, so don't expect too much from the code). The following keys are used: +The sound example is meant for experimenting with the sound generator of the GameBoy (to use on a real GameBoy). The four different sound modes of the GameBoy are available. It also demonstrates the use of bit fields in C (it's a quick hack, so don't expect too much from the code). The following keys are used: UP/DOWN : Move the cursor RIGHT/LEFT : Increment/decrement the value diff --git a/docs/pages/08_faq.md b/docs/pages/08_faq.md @@ -8,7 +8,7 @@ - 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: https://github.com/Zal0/ZGB/wiki/Sounds <!-- --> # Graphics and Resources - - How do I use a tile map when it's tiles don't start at index zero? + - How do I use a tile map when its tiles don't start at index zero? - The two main options are: - Use @ref set_bkg_based_tiles(), @ref set_bkg_based_submap(), @ref set_win_based_tiles(), @ref set_win_based_submap() and provide a tile origin offset. - Use @ref utility_png2asset with `-tile_origin` to create a map with the tile index offsets built in. @@ -73,14 +73,14 @@ - Can I use the `float` type to do floating point math? - There is no support for 'float' in GBDK-2020. - - Instead consider some form of `fixed point` math (including the @ref fixed_point_type "fixed" type included in GBDK) <!-- --> + - Instead consider some form of `fixed point` math (including the @ref fixed_point_type "fixed" type included in GBDK). <!-- --> - Why are 8 bit numbers not printing correctly with printf()? - - To correctly pass chars/uint8s for printing, they must be explicitly re-cast as such when calling the function. See docs_chars_varargs for more details. <!-- --> + - To correctly pass chars/uint8s for printing, they must be explicitly re-cast as such when calling the function. See @ref docs_chars_varargs for more details. <!-- --> - How can maps larger than 32x32 tiles be scrolled? & Why is the map wrapping around to the left side when setting a map wider than 32 tiles with set_bkg_data()? - 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. @ref set_bkg_submap can be used to load those rows and columns of tiles from the desired sub-region of the large map. - - See the "Large Map" example program and @ref set_bkg_submap() + - See the "Large Map" example program and @ref set_bkg_submap(). - 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. <!-- --> - 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).
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.