gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 1f6f10b6fda3b2079e18a01b61ec7042231bfe46 parent 0dbb5651993d4b69d354f77b1c92252afd146c81 Author: bbbbbr <bbbbbr@users.noreply.github.com> Date: Sun, 14 Aug 2022 23:16:30 -0700 Merge pull request #400 from bbbbbr/docs_4_1_0 Docs: 4.1.0 Misc Updates Diffstat:
| M | Makefile | 18 | +++++++++--------- |
| M | docs/pages/02_links_and_tools.md | 10 | ++++++++++ |
| M | docs/pages/04_coding_guidelines.md | 4 | +++- |
| M | docs/pages/05_banking_mbcs.md | 2 | ++ |
| M | docs/pages/06_toolchain.md | 8 | ++++++++ |
| M | docs/pages/06b_supported_consoles.md | 9 | +++++++-- |
| M | docs/pages/08_faq.md | 3 | ++- |
| M | docs/pages/09_migrating_new_versions.md | 9 | +++++++-- |
| M | docs/pages/10_release_notes.md | 61 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- |
| M | docs/pages/20_toolchain_settings.md | 160 | ++++++++++++++++++++++++++++++++++++++++++++++++++----------------------------- |
| M | docs/pages/docs_index.md | 2 | +- |
| A | gbdk-lib/examples/gb/sgb_border/Readme.md | 15 | +++++++++++++++ |
| M | gbdk-lib/examples/gb/sgb_border/border.c | 15 | +++++++++++++++ |
| M | gbdk-lib/include/gb/drawing.h | 8 | +++++++- |
| M | gbdk-lib/include/stdlib.h | 12 | ++++++++++++ |
15 files changed, 259 insertions(+), 77 deletions(-)
diff --git a/Makefile b/Makefile @@ -366,42 +366,42 @@ ifneq (,$(wildcard $(BUILDDIR)/bin/)) echo \# sdcc settings >> $(TOOLCHAIN_DOCS_FILE); echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); $(BUILDDIR)/bin/sdcc -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 - echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); # sdasgb echo \@anchor sdasgb-settings >> $(TOOLCHAIN_DOCS_FILE); echo \# sdasgb settings >> $(TOOLCHAIN_DOCS_FILE); echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); - $(BUILDDIR)/bin/sdasgb -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true + $(BUILDDIR)/bin/sdasgb -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); # sdasz80 echo \@anchor sdasz80-settings >> $(TOOLCHAIN_DOCS_FILE); echo \# sdasz80 settings >> $(TOOLCHAIN_DOCS_FILE); echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); - $(BUILDDIR)/bin/sdasgb -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true + $(BUILDDIR)/bin/sdasgb -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); # bankpack echo \@anchor bankpack-settings >> $(TOOLCHAIN_DOCS_FILE); echo \# bankpack settings >> $(TOOLCHAIN_DOCS_FILE); echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); - $(BUILDDIR)/bin/bankpack -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true + $(BUILDDIR)/bin/bankpack -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); # sdldgb echo \@anchor sdldgb-settings >> $(TOOLCHAIN_DOCS_FILE); echo \# sdldgb settings >> $(TOOLCHAIN_DOCS_FILE); echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); - $(BUILDDIR)/bin/sdldgb >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true + $(BUILDDIR)/bin/sdldgb >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); # sdldz80 echo \@anchor sdldz80-settings >> $(TOOLCHAIN_DOCS_FILE); echo \# sdldz80 settings >> $(TOOLCHAIN_DOCS_FILE); echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); - $(BUILDDIR)/bin/sdldgb >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true + $(BUILDDIR)/bin/sdldgb >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); # ihxcheck echo \@anchor ihxcheck-settings >> $(TOOLCHAIN_DOCS_FILE); echo \# ihxcheck settings >> $(TOOLCHAIN_DOCS_FILE); echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); - $(BUILDDIR)/bin/ihxcheck -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true + $(BUILDDIR)/bin/ihxcheck -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); # makebin echo \@anchor makebin-settings >> $(TOOLCHAIN_DOCS_FILE); @@ -414,13 +414,13 @@ ifneq (,$(wildcard $(BUILDDIR)/bin/)) echo \@anchor makecom-settings >> $(TOOLCHAIN_DOCS_FILE); echo \# makecom settings >> $(TOOLCHAIN_DOCS_FILE); echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); - $(BUILDDIR)/bin/makecom -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 + $(BUILDDIR)/bin/makecom -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); # gbcompress echo \@anchor gbcompress-settings >> $(TOOLCHAIN_DOCS_FILE); echo \# gbcompress settings >> $(TOOLCHAIN_DOCS_FILE); echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); - $(BUILDDIR)/bin/gbcompress -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true + $(BUILDDIR)/bin/gbcompress -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); # png2asset echo \@anchor png2asset-settings >> $(TOOLCHAIN_DOCS_FILE); diff --git a/docs/pages/02_links_and_tools.md b/docs/pages/02_links_and_tools.md @@ -151,6 +151,16 @@ This is a brief list of useful tools and information. It is not meant to be comp https://gbdev.gg8.se/forums/viewtopic.php?id=710 +@anchor links_optimizing +# Optimizing Assembly + - @anchor optimizing_assembly + __Optimizing Assembly Code__ + Pret has a useful guide to optimizing assembly for + the Game Boy for times when asm using in a project + in addition to C. + https://github.com/pret/pokecrystal/wiki/Optimizing-assembly-code + + @anchor tools_build_ci_cd # Continuous Integration and Deployment - @anchor GBDK_GitHub_Action_Builder diff --git a/docs/pages/04_coding_guidelines.md b/docs/pages/04_coding_guidelines.md @@ -7,7 +7,9 @@ Writing games and other programs with GBDK will be much easier with a basic unde @anchor docs_c_tutorials ## General C tutorials - https://www.learn-c.org/ - - https://www.tutorialspoint.com/cprogramming/index.htm + - https://www.tutorialspoint.com/cprogramming/index.htm + - https://www.chiark.greenend.org.uk/~sgtatham/cdescent/ + ## Embedded C introductions diff --git a/docs/pages/05_banking_mbcs.md b/docs/pages/05_banking_mbcs.md @@ -71,6 +71,7 @@ The MBC settings below are available when using the makebin `-Wl-yt<N>` switch. Source: Pandocs. Additional details available at [Pandocs](https://gbdev.io/pandocs/The_Cartridge_Header.html#0147---cartridge-type "Pandocs") +## MBC Type Chart ``` 0147: Cartridge type: 0x00: ROM ONLY 0x12: ROM+MBC3+RAM @@ -89,6 +90,7 @@ Source: Pandocs. Additional details available at [Pandocs](https://gbdev.io/pand 0x11: ROM+MBC3 ``` +@anchor mbc_type_chart | Hex Code | MBC Type | SRAM | BATTERY | RTC | RUMBLE | EXTRA | | -------- | ------------- | ---- | ------- | --- | ------ | ------ | diff --git a/docs/pages/06_toolchain.md b/docs/pages/06_toolchain.md @@ -274,3 +274,11 @@ The following flags should be used to perform the conversion: See the `sgb_border` example project for more details. + + +@anchor utility_makecom +## makecom +Converts a binary .rom file to .msxdos com format, including splitting the banks up into separate files. + +- For detailed settings see @ref makecom-settings + diff --git a/docs/pages/06b_supported_consoles.md b/docs/pages/06b_supported_consoles.md @@ -13,7 +13,8 @@ As of version `4.0.5` GBDK includes support for other consoles in addition to th - Sega Master System (SMS) - Sega Game Gear (GG) - - MSX DOS (MSXDOS) + - MSX DOS (MSXDOS) (partial support) + - NES (NES) (partial support) 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. @@ -40,7 +41,7 @@ When linking with @ref sdldgb-settings "sdldgb" (for GB/AP) and @ref sdldz80-set - Include the appropriate library files `-l <port>.lib`, `-l <plat>.lib` - The crt will be under ` <gbdk-path>lib/<plat>/crt0.o` -MSXDOS requires an additional build step after makebin to create the final binary: +MSXDOS requires an additional build step with @ref utility_makecom "makecom" after @ref makebin to create the final binary: - `makecom <image.bin> [<image.noi>] <output.com>` @@ -69,6 +70,10 @@ Note: Starting with GBDK-2020 4.1.0 and SDCC 4.2, the Game Boy and related clone - @ref lcc : `-mz80:msxdos` - port:`z80`, plat:`msxdos` + - NES + - @ref lcc : `-mmos6502:nes` + - port:`mos6502`, plat:`nes` + # Cross-Platform Constants There are several constant \#defines that can be used to help select console specific code during compile time (with `#ifdef`, `#ifndef`) . diff --git a/docs/pages/08_faq.md b/docs/pages/08_faq.md @@ -58,7 +58,8 @@ - This is a known issue with SDCC, it should not cause actual problems and you can ignore the warning. <!-- --> - Why is the compiler so slow, or why did it suddenly get much slower? - - This may happen if you have large initialized arrays declared without the `const` keyword. It's important to use the const keyword for read-only data. See @ref const_gbtd_gbmb and @ref const_array_data <!-- --> + - This may happen if you have large initialized arrays declared without the `const` keyword. It's important to use the const keyword for read-only data. See @ref const_gbtd_gbmb and @ref const_array_data + - It can also happen if C source files are `#included` into other C source files, or if there is a very large source file. <!-- --> - What flags should be enabled for debugging? - You can use the @ref lcc_debug "lcc debug flag" `-debug`to turn on debug output. It covers most uses and removes the need to specify multiple flags such as `-Wa-l -Wl-m -Wl-j`. <!-- --> diff --git a/docs/pages/09_migrating_new_versions.md b/docs/pages/09_migrating_new_versions.md @@ -7,10 +7,15 @@ This section contains information that may be useful to know or important when u ## Porting to GBDK-2020 4.1.0 - GBDK now requires SDCC 4.2 or higher with GBDK-2020 patches for the the z80 linker - - The default calling convention changed in SDCC 4.2, see @ref sdcc_calling_convention "Calling Conventions" for more details. - - The SDCC `PORT` name for the Game Boy and related clones changed from `gbz80` to `sm83`. Additional details in the @ref console_port_plat_settings "Console Port and Platform Settings" section and @ref faq_gbz80_sm83_old_port_name_error "FAQ entry". @ref lcc will error out if the old `PORT` name is passed in. + - The default calling convention changed in SDCC 4.2, see @ref sdcc_calling_convention "Calling Conventions" for more details. + - If you are linking to libraries compiled with an older version of SDCC / GBDK then you may have to recompile them. + - The SDCC `PORT` name for the Game Boy and related clones changed from `gbz80` to `sm83`. + - Additional details in the @ref console_port_plat_settings "Console Port and Platform Settings" section and @ref faq_gbz80_sm83_old_port_name_error "FAQ entry". @ref lcc will error out if the old `PORT` name is passed in. - The library base path changed from `lib/small/asxxxx/` to `lib/`. - For example `lib/small/asxxxx/gb` becomes `lib/gb` + - Allocations for ISR chain lengths were fixed. + - Now they are VBL: 4 user handlers, LCD: 3 user handlers, SIO/TIM/JOY: 4 user handlers + ## Porting to GBDK-2020 4.0.6 - Renamed `bgb_emu.h` to `emu_debug.h` and BGB_* functions to EMU_* diff --git a/docs/pages/10_release_notes.md b/docs/pages/10_release_notes.md @@ -8,7 +8,66 @@ https://github.com/gbdk-2020/gbdk-2020/releases ## GBDK-2020 4.1.0 2022 - + - Building GBDK + - The linux port of SDCC is custom built on Ubuntu 16.04 due to reduced GLIBC compatibility issues in more recent SDCC project builds. + - Added Windows 32-Bit build + - Platforms + - SDCC has renamed the `gbz80` port to `sm83` see @ref faq_gbz80_sm83_old_port_name_error + - Added initial support for MSXDOS (`msxdos`) and NES (`nes`). These platforms are not fully supported at this time. See @ref docs_supported_consoles + - Library + - SGB: Use longer wait between the SGB packet transfers + - SMS/GG: less garbage on screen when clearing VRAM in the init code + - SMS/GG: Added @ref cgb_compatibility() to set default palette with the four shades of gray + - Fixed: @ref get_sprite_data(), @ref get_bkg_data() , @ref get_win_data() when @ref LCDCF_BG8000 bit of @ref LCDC_REG is set + - Fixed ISR chain lengths. VBL: 4 user handlers, LCD: 3 user handlers, SIO/TIM/JOY: 4 user handlers + - Added new constants for the Game Boy Color (CGB): + - @ref VBK_BANK_0, @ref VBK_BANK_1 + - @ref VBK_TILES, @ref VBK_ATTRIBUTES + - @ref BKGF_PRI, @ref BKGF_YFLIP, @ref BKGF_XFLIP, @ref BKGF_BANK0, @ref BKGF_BANK1 + - @ref BKGF_CGB_PAL0, @ref BKGF_CGB_PAL1, @ref BKGF_CGB_PAL2, @ref BKGF_CGB_PAL3, @ref BKGF_CGB_PAL4, @ref BKGF_CGB_PAL5, @ref BKGF_CGB_PAL6, @ref BKGF_CGB_PAL7 + - @ref VBK_TILES, @ref VBK_ATTRIBUTES + - Toolchain / Utilities + - @ref lcc + - Changed to Error out and warn when `gbz80` port is used instead of `sm83` + - @ref utility_png2asset "png2asset" + - Added `-tiles_only`: Export tile data only + - Added `-maps_only`: Export map tilemap only + - Added `-metasprites_only`: Export metasprite descriptors only + - Added `-source_tileset`: Use source tileset image with common tiles + - Added `-keep_duplicate_tiles`: Do not remove duplicate tiles + - Added `-bin`: Export to binary format + - Added `-transposed`: Export transposed (column-by-column instead of row-by-row) + - Added basic MSXDOS support + - Added 1bpp packing mode (BPP1) + - `-spr16x16msx` + - Added basic NES support + - `-use_nes_attributes` + - `-use_nes_colors` + - Changed to only export `_tile_pals[]` arrays when `-use-structs` is set (ZGB specific) + - @ref utility_gbcompress "gbcompress" + - Added `--bank=<num>` Add Bank Ref: 1 - 511 (default is none, with `--cout` only) + - Fixed failure to flush data at end of compression (uncommitted bytes) + - Fixed `Warning: File read size didn't match expected` + - @ref utility_makecom "makecom" + - Added `makecom` for post-processing msxdos binary + - @ref makebin + - Fixed (via sdcc) bug with `-yp` not always working correctly + - https://sourceforge.net/p/sdcc/code/12975/ + - @ref bankpack + - Added support for the Game Boy Camera MBC + - @ref ihxcheck + - Check and warn for bank overflows under specific conditions + - A multiple write to the same address must occur. The address where the overlap ends is used as BANK. + - There must also be a write which spans multiple banks, the ending address of that must match BANK. The starting addresses is the OVERFLOW-FROM BANK. + - Examples + - Changed Logo example to use new GBDK logo art from Digit + - Added example for APA image mode with more than 256 tiles + - Added SGB Sound Effects example + - Changed to new WAV sound example + - Docs + - Added improved @ref mbc_type_chart "MBC Type chart" + - Include SDCC manual in pdf format + - Various doc updates and improvements ## GBDK-2020 4.0.6 2022/02 diff --git a/docs/pages/20_toolchain_settings.md b/docs/pages/20_toolchain_settings.md @@ -18,7 +18,7 @@ -Idir add `dir' to the beginning of the list of #include directories -K don't run ihxcheck test on linker ihx output -lx search library `x' --m select port and platform: "-m[port]:[plat]" ports:gbz80,z80 plats:ap,duck,gb,sms,gg +-m select port and platform: "-m[port]:[plat]" ports:sm83,z80,mos6502 plats:ap,duck,gb,sms,gg,nes -N do not search the standard directories for #include files -n emit code to check for dereferencing zero pointers -no-crt do not auto-include the gbdk crt0.o runtime in linker list @@ -42,7 +42,7 @@ @anchor sdcc-settings # sdcc settings ``` -SDCC : z80/gbz80 4.1.6 #12539 (Linux) +SDCC : z80/sm83/mos6502 4.2.2 #13350 (Linux) published under GNU General Public License (GPL) Usage : sdcc [options] filename Options :- @@ -59,6 +59,7 @@ General options: -U Undefine macro as in -Umacro -M Preprocessor option -W Pass through options to the pre-processor (p), assembler (a) or linker (l) + --include Pre-include a file during pre-processing -S Compile only; do not assemble or link -c --compile-only Compile and assemble, but do not link -E --preprocessonly Preprocess only, do not compile @@ -97,7 +98,6 @@ Code generation options: --float-reent Use reentrant calls on the float support functions --xram-movc Use movc instead of movx to read xram (xdata) --callee-saves <func[,func,...]> Cause the called function to save registers instead of the caller - --profile On supported ports, generate extra profiling information --fomit-frame-pointer Leave out the frame pointer. --all-callee-saves callee will always save registers used --stack-probe insert call to function __stack_probe at each function prologue @@ -155,19 +155,22 @@ Linker options: Special options for the z80 port: --callee-saves-bc Force a called function to always save BC --portmode= Determine PORT I/O mode (z80/z180) + -bo <num> use code bank <num> + -ba <num> use data bank <num> --asm= Define assembler name (rgbds/asxxxx/isas/z80asm/gas) --codeseg <name> use this name for the code segment --constseg <name> use this name for the const segment --dataseg <name> use this name for the data segment - --no-std-crt0 For the z80/gbz80 do not link default crt0.rel + --no-std-crt0 Do not link default crt0.rel --reserve-regs-iy Do not use IY (incompatible with --fomit-frame-pointer) - --oldralloc Use old register allocator (deprecated) --fno-omit-frame-pointer Do not omit frame pointer --emit-externs Emit externs list in generated asm --legacy-banking Use legacy method to call banked functions --nmos-z80 Generate workaround for NMOS Z80 when saving IFF2 + --sdcccall Set ABI version for default calling convention + --allow-undocumented-instructions Allow use of undocumented instructions -Special options for the gbz80 port: +Special options for the sm83 port: -bo <num> use code bank <num> -ba <num> use data bank <num> --asm= Define assembler name (rgbds/asxxxx/isas/z80asm/gas) @@ -175,84 +178,104 @@ Special options for the gbz80 port: --codeseg <name> use this name for the code segment --constseg <name> use this name for the const segment --dataseg <name> use this name for the data segment - --no-std-crt0 For the z80/gbz80 do not link default crt0.rel + --no-std-crt0 Do not link default crt0.rel --legacy-banking Use legacy method to call banked functions + --sdcccall Set ABI version for default calling convention + +Special options for the mos6502 port: + --model-small 8-bit address space for data + --model-large 16-bit address space for data (default) + --no-std-crt0 Do not link default crt0.rel ``` @anchor sdasgb-settings # sdasgb settings ``` -sdas Assembler V02.00 + NoICE + SDCC mods (GameBoy Z80-like CPU) +sdas Assembler V02.00 + NoICE + SDCC mods (GameBoy) Copyright (C) 2012 Alan R. Baldwin This program comes with ABSOLUTELY NO WARRANTY. -Usage: [-Options] file -Usage: [-Options] outfile file1 [file2 file3 ...] +Usage: [-Options] [-Option with arg] file +Usage: [-Options] [-Option with arg] outfile file1 [file2 ...] + -h or NO ARGUMENTS Show this help list +Input: + -I Add the named directory to the include file + search path. This option may be used more than once. + Directories are searched in the order given. +Output: + -l Create list file/outfile[.lst] + -o Create object file/outfile[.rel] + -s Create symbol file/outfile[.sym] +Listing: -d Decimal listing -q Octal listing -x Hex listing (default) - -g Undefined symbols made global - -n Don't resolve global assigned value symbols - -a All user symbols made global -b Display .define substitutions in listing -bb and display without .define substitutions -c Disable instruction cycle count in listing - -j Enable NoICE Debug Symbols - -y Enable SDCC Debug Symbols - -l Create list file/outfile[.lst] - -o Create object file/outfile[.rel] - -s Create symbol file/outfile[.sym] + -f Flag relocatable references by ` in listing file + -ff Flag relocatable references by mode in listing file -p Disable automatic listing pagination -u Disable .list/.nlist processing -w Wide listing format for symbol table +Assembly: + -v Enable out of range signed / unsigned errors +Symbols: + -a All user symbols made global + -g Undefined symbols made global + -n Don't resolve global assigned value symbols -z Disable case sensitivity for symbols - -f Flag relocatable references by ` in listing file - -ff Flag relocatable references by mode in listing file - -I Add the named directory to the include file - search path. This option may be used more than once. - Directories are searched in the order given. +Debugging: + -j Enable NoICE Debug Symbols + -y Enable SDCC Debug Symbols -removing ``` @anchor sdasz80-settings # sdasz80 settings ``` -sdas Assembler V02.00 + NoICE + SDCC mods (GameBoy Z80-like CPU) +sdas Assembler V02.00 + NoICE + SDCC mods (GameBoy) Copyright (C) 2012 Alan R. Baldwin This program comes with ABSOLUTELY NO WARRANTY. -Usage: [-Options] file -Usage: [-Options] outfile file1 [file2 file3 ...] +Usage: [-Options] [-Option with arg] file +Usage: [-Options] [-Option with arg] outfile file1 [file2 ...] + -h or NO ARGUMENTS Show this help list +Input: + -I Add the named directory to the include file + search path. This option may be used more than once. + Directories are searched in the order given. +Output: + -l Create list file/outfile[.lst] + -o Create object file/outfile[.rel] + -s Create symbol file/outfile[.sym] +Listing: -d Decimal listing -q Octal listing -x Hex listing (default) - -g Undefined symbols made global - -n Don't resolve global assigned value symbols - -a All user symbols made global -b Display .define substitutions in listing -bb and display without .define substitutions -c Disable instruction cycle count in listing - -j Enable NoICE Debug Symbols - -y Enable SDCC Debug Symbols - -l Create list file/outfile[.lst] - -o Create object file/outfile[.rel] - -s Create symbol file/outfile[.sym] + -f Flag relocatable references by ` in listing file + -ff Flag relocatable references by mode in listing file -p Disable automatic listing pagination -u Disable .list/.nlist processing -w Wide listing format for symbol table +Assembly: + -v Enable out of range signed / unsigned errors +Symbols: + -a All user symbols made global + -g Undefined symbols made global + -n Don't resolve global assigned value symbols -z Disable case sensitivity for symbols - -f Flag relocatable references by ` in listing file - -ff Flag relocatable references by mode in listing file - -I Add the named directory to the include file - search path. This option may be used more than once. - Directories are searched in the order given. +Debugging: + -j Enable NoICE Debug Symbols + -y Enable SDCC Debug Symbols -removing ``` @anchor bankpack-settings # bankpack settings @@ -265,7 +288,8 @@ Options -h : Show this help -lkin=<file> : Load object files specified in linker file <file> -lkout=<file>: Write list of object files out to linker file <file> --yt<mbctype> : Set MBC type per ROM byte 149 in Decimal or Hex (0xNN) (see pandocs) +-yt<mbctype> : Set MBC type per ROM byte 149 in Decimal or Hex (0xNN) + ([see pandocs](https://gbdev.io/pandocs/The_Cartridge_Header.html#0147---cartridge-type)) -mbc=N : Similar to -yt, but sets MBC type directly to N instead of by intepreting ROM byte 149 mbc1 will exclude banks {0x20,0x40,0x60} max=127, @@ -312,7 +336,6 @@ Libraries: Relocation: -b area base address = expression -g global symbol = expression - -a (platform) Select platform specific virtual address translation Map format: -m Map output generated as (out)file[.map] -w Wide listing format for map file @@ -352,7 +375,6 @@ Libraries: Relocation: -b area base address = expression -g global symbol = expression - -a (platform) Select platform specific virtual address translation Map format: -m Map output generated as (out)file[.map] -w Wide listing format for map file @@ -395,10 +417,12 @@ Options: -s romsize size of the binary file (default: rom banks * 16384) -Z generate GameBoy format binary file -S generate Sega Master System format binary file + -N generate Famicom/NES format binary file + -o bytes skip amount of bytes in binary file SMS format options (applicable only with -S option): - -xo n rom size (0xa-0x2) - -xj n set region code (3-7) - -xv n version number (0-15) + -xo n rom size (0xa-0x2) (default: 0xc) + -xj n set region code (3-7) (default: 4) + -xv n version number (0-15) (default: 0) GameBoy format options (applicable only with -Z option): -yo n number of rom banks (default: 2) (autosize: A) -ya n number of ram banks (default: 0) @@ -417,6 +441,12 @@ Arguments: <in_file> optional IHX input file, '-' means stdin. (default: stdin) <out_file> optional output file, '-' means stdout. (default: stdout) ``` +@anchor makecom-settings +# makecom settings +``` +makecom image.rom image.noi output.com +Use: convert a binary .rom file to .msxdos com format. +``` @anchor gbcompress-settings # gbcompress settings ``` @@ -424,13 +454,14 @@ gbcompress [options] infile outfile Use: compress a binary file and write it out. Options --h : Show this help screen --d : Decompress (default is compress) --v : Verbose output ---cin : Read input as .c source format (8 bit char ONLY, uses first array found) ---cout : Write output in .c / .h source format (8 bit char ONLY) +-h : Show this help screen +-d : Decompress (default is compress) +-v : Verbose output +--cin : Read input as .c source format (8 bit char ONLY, uses first array found) +--cout : Write output in .c / .h source format (8 bit char ONLY) --varname=<NAME> : specify variable name for c source output --alg=<type> : specify compression type: 'rle', 'gb' (default) +--bank=<num> : Add Bank Ref: 1 - 511 (default is none, with --cout only) Example: "gbcompress binaryfile.bin compressed.bin" Example: "gbcompress -d compressedfile.bin decompressed.bin" Example: "gbcompress --alg=rle binaryfile.bin compressed.bin" @@ -450,16 +481,27 @@ usage: png2asset <file>.png [options] -py <y coord> metasprites pivot y coordinate (default: metasprites height / 2) -pw <width> metasprites collision rect width (default: metasprites width) -ph <height> metasprites collision rect height (default: metasprites height) --spr8x8 use SPRITES_8x8 (default: SPRITES_8x16) --spr8x16 use SPRITES_8x16 (default: SPRITES_8x16) +-spr8x8 use SPRITES_8x8 +-spr8x16 use SPRITES_8x16 (this is the default) +-spr16x16msx use SPRITES_16x16 -b <bank> bank (default 0) -keep_palette_order use png palette -noflip disable tile flip -map Export as map (tileset + bg) --use_map_attributes Use CGB BG Map attributes (default: palettes are stored for each tile in a separate array) +-use_map_attributes Use CGB BG Map attributes +-use_nes_attributes Use NES BG Map attributes +-use_nes_colors Convert RGB color values to NES PPU colors -use_structs Group the exported info into structs (default: false) (used by ZGB Game Engine) --bpp bits per pixel: 2, 4 (default: 2) --max_palettes maximum number of palettes allowed (default: 2) --pack_mode gb, sgb or sms (default:GB) --tile_origin tile index offset for maps (instead of zero) +-bpp bits per pixel: 1, 2, 4 (default: 2) +-max_palettes max number of palettes allowed (default: 8) + (note: max colors = max_palettes x num colors per palette) +-pack_mode gb, sgb, sms, 1bpp (default: gb) +-tile_origin tile index offset for maps (default: 0) +-tiles_only export tile data only +-maps_only export map tilemap only +-metasprites_only export metasprite descriptors only +-source_tileset use source tileset (image with common tiles) +-keep_duplicate_tiles do not remove duplicate tiles (default: not enabled) +-bin export to binary format +-transposed export transposed (column-by-column instead of row-by-row) ``` diff --git a/docs/pages/docs_index.md b/docs/pages/docs_index.md @@ -46,7 +46,7 @@ GBDK is freeware. Most of the tooling code is under the GPL. The runtime librari Work on the original GBDK (pre-2020) was by: -Pascal Felber, Lars Malmborg, Michael Hope, David Galloway (djmips), and others. +Pascal Felber, Lars Malmborg, Michael Hope, David Galloway (djmips), John Fuge, and others. The following is from the original GBDK documentation: diff --git a/gbdk-lib/examples/gb/sgb_border/Readme.md b/gbdk-lib/examples/gb/sgb_border/Readme.md @@ -0,0 +1,15 @@ +# Super Game Boy Border Example +This example shows how to convert and display an SGB border when the game is running on a Super Game Boy. + +png2asset is used for converting the border. + + +### Image Properties +* The entire image should be 256 x 224 pixels +* The game area in the center should be: + * 160 x 144 pixels, from (48,40) to (207,183) + * The pixels in the game area at the center of the image should be set to 100% Alpha Transparency (as in the example image). If this is not done then the game area may share a palette color with other parts of the border leading to tile pattern flasing while the border loads. +* See the pandocs for additional details + * https://gbdev.io/pandocs/SGB_Functions.html + * https://gbdev.io/pandocs/SGB_Color_Palettes.html + diff --git a/gbdk-lib/examples/gb/sgb_border/border.c b/gbdk-lib/examples/gb/sgb_border/border.c @@ -3,6 +3,21 @@ #include "sgb_border.h" #include "border_data.h" +/* + +- The entire image should be 256 x 224 pixels + +- The game area in the center should be: + - 160 x 144 pixels, from (48,40) to (207,183) + - The pixels in the game area at the center of the image should be set + to 100% Alpha Transparency (as in the example image). If this is not + done then the game area may share a palette color with other parts + of the border leading to tile pattern flasing while the border loads. + +- See the pandocs for additional details + - https://gbdev.io/pandocs/SGB_Functions.html + - https://gbdev.io/pandocs/SGB_Color_Palettes.html +*/ void main(void) { diff --git a/gbdk-lib/include/gb/drawing.h b/gbdk-lib/include/gb/drawing.h @@ -139,7 +139,13 @@ void wrtchr(char chr) OLDCALL; void gotogxy(uint8_t x, uint8_t y) OLDCALL; /** Set the current __foreground__ colour (for pixels), __background__ colour, and - draw __mode__ */ + draw __mode__ + + Several settings are available for the drawing __mode__ : + `SOLID`, `OR`, `XOR`, `AND`. + + In order to completely overwrite existing pixels use `SOLID` for __mode__ +*/ void color(uint8_t forecolor, uint8_t backcolor, uint8_t mode) OLDCALL; #endif /* __DRAWING_H */ diff --git a/gbdk-lib/include/stdlib.h b/gbdk-lib/include/stdlib.h @@ -69,6 +69,9 @@ long atol(const char *s); @param radix Numerical base for converted number, ex: 10 is decimal base (parameter is required but not utilized on Game Boy and Analogue Pocket) + Can be used with @ref set_bkg_based_tiles() for printing if + the digit character tiles are not ascii-mapped. + Returns: Pointer to converted string */ char *itoa(int n, char *s, unsigned char radix) OLDCALL; @@ -79,6 +82,9 @@ char *itoa(int n, char *s, unsigned char radix) OLDCALL; @param radix Numerical base for converted number, ex: 10 is decimal base (parameter is required but not utilized on Game Boy and Analogue Pocket) + Can be used with @ref set_bkg_based_tiles() for printing if + the digit character tiles are not ascii-mapped. + Returns: Pointer to converted string */ char *uitoa(unsigned int n, char *s, unsigned char radix) OLDCALL; @@ -89,6 +95,9 @@ char *uitoa(unsigned int n, char *s, unsigned char radix) OLDCALL; @param radix Numerical base for converted number, ex: 10 is decimal base (parameter is required but not utilized on Game Boy and Analogue Pocket) + Can be used with @ref set_bkg_based_tiles() for printing if + the digit character tiles are not ascii-mapped. + Returns: Pointer to converted string */ char *ltoa(long n, char *s, unsigned char radix) OLDCALL; @@ -99,6 +108,9 @@ char *ltoa(long n, char *s, unsigned char radix) OLDCALL; @param radix Numerical base for converted number, ex: 10 is decimal base (parameter is required but not utilized on Game Boy and Analogue Pocket) + Can be used with @ref set_bkg_based_tiles() for printing if + the digit character tiles are not ascii-mapped. + Returns: Pointer to converted string */ char *ultoa(unsigned long n, char *s, unsigned char radix) OLDCALL;
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.