Types definitions for the gb.
+GBDK includes several example programs both in C and in assembly. They are located in the examples directory, and in its subdirectories. They can be built by typing make in the correnponding directory.
There are several different projects showing how to use ROM banking with GBDK.
-Illustrates how to use communication routines.
-Demonstrates how to use the optional GBDK crash handler which dumps debug info to the Game Boy screen in the event of a program crash.
-The colorbar program, written by Mr. N.U. of TeamKNOx, illustrates the use of colors on a Color GameBoy.
-Deep Scan is a game written by Mr. N.U. of TeamKNOx that supports the Color GameBoy. Your aim is to destroy the submarines from your boat, and to avoid the projectiles that they send to you. The game should be self-explanatory. The following keys are used:
RIGHT/LEFT : Move your boat A/B : Send a bomb from one side of your boat @@ -113,45 +113,48 @@ When game is paused: SELECT : Invert A and B buttons RIGHT/LEFT : Change speed UP/DOWN : Change level -
Demonstrates various graphics routines.
-Examples of how to work with the built in font and printing features.
-A C translation of the space.s assembly program.
-The gb-dtmf, written by Osamu Ohashi, is a Dual Tone Multi-Frequency (DTMF) generator.
-Illustrates how to install interrupt handlers.
-Shows how to scroll with maps larger than 32 x 32 tiles using set_bkg_submap(). It fills rows and columns at the edges of the visible viewport (of the hardware Background Map) as it scrolls from the desired sub-region of the large map.
+An example of how to use the LCD ISR for visual special effects
-The paint example is a painting program. It supports different painting tools, drawing modes, and colors. At the moment, it only paints individual pixels. This program illustrates the use of the full-screen drawing library. It also illustrates the use of generic structures and big sprites.
Arrow keys : Move the cursor SELECT : Display/hide the tools palette A : Select tool -
The rand program, written by Luc Van den Borre, illustrates the use of the GBDK random generator.
-The ram_fn example illustrates how to copy functions to RAM or HIRAM, and how to call them from C.
-A basic RPN calculator. Try entering expressions like 12 134* and then 1789+.
-Demonstration of playing a sound sample.
-A collection of examples showing how to use the Super Game Boy API features.
-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:
UP/DOWN : Move the cursor RIGHT/LEFT : Increment/decrement the value @@ -161,14 +164,17 @@ START : Play the current mode's sound (or all modes if in control screen) START+A : Play a little music with the current mode's sound SELECT : Change the sound mode (1, 2, 3, 4 and control) SELECT+A : Dump the sound registers to the screen -
The space example is an assembly program that demonstrates the use of sprites, window, background, fixed-point values and more. The following keys are used:
Arrow keys : Change the speed (and direction) of the sprite Arrow keys + A : Change the speed (and direction) of the window Arrow keys + B : Change the speed (and direction) of the background START : Open/close the door SELECT : Basic fading effect -
Two basic template examples are provided as a starting place for writing your GBDK programs.
+ diff --git a/docs/api/docs_faq.html b/docs/api/docs_faq.html new file mode 100644 index 00000000..76640e4f --- /dev/null +++ b/docs/api/docs_faq.html @@ -0,0 +1,183 @@ + + + + + + + + + +|
+ GBDK 2020 Docs
+
+ API Documentation for GBDK 2020
+ |
+
+
+
+
What do these kinds of warnings / errors mean? WARNING: possibly wrote twice at addr 4000 (93->3E) Warning: Write from one bank spans into the next. 7ff7 -> 8016 (bank 1 -> 2)
You may have a overflow in one of your ROM banks. If there is more data allocated to a bank than it can hold it then will spill over into the next bank. The warnings are generated by ihxcheck during conversion of an .ihx file into a ROM file.
+See the section ROM/RAM Banking and MBCs for more details about how banks work and what their size is. You may want to use a tool such as romusage to calculate the amount of free and used space.
+
+
const keyword. It's important to use the const keyword for read-only data. See const_gbtd_gbmb and const_array_data
+
+
+
+
+
Follow the steps in this section to start using GBDK-2020.
-Make sure your GBDK-2020 installation is working correctly by compiling some of the included example projects.
Navigate to the example projects folder ("examples/gb/" under your GBDK-2020 install folder) and open a command line. Then type:
make
This should build all of the examples sequentially. You can also navigate into an individual example project's folder and build it by typing make.
If everything works and there are no errors reported each example sub-folder should have it's on .gb ROM file.
-To create a new project use a template!
There are template projects included in the GBDK example projects to help you get up and running. Their folder names start with template_.
make on the command line in that folder to verify it still builds.If you plan to use GBTD / GBMB for making graphics, make sure to get the version with the const fix and other improvements. See const_gbtd_gbmb.
Take a look at the coding guidelines, even if you have experience writing software for other platforms. There is important information to help you get good results and performance on the Game Boy.
If you haven't written programs in C before, check the C tutorials section.
-If you have a specific project in mind, consider what hardware want to target. It isn't something that has to be decided up front, but it can influence design and implementation.
+What size will your game or program be?
What hardware will it run on?
Tracking down problems in code is easier with a debugger. Emulicious has a debug adapter that provides C source debugging with GBDK-2020.
+You might want to start off with a guided GBDK tutorial from the GBDK Tutorials section.
Check out the links for online community and support.
+Check out the links for online community and support and read the FAQ.
This is a brief list of useful tools and information. It is not meant to be complete or exhaustive, for a larger list see awesome_gb
-This section contains information that may be useful to know or important when upgrading to a newer GBDK release.
-WRAM memory region is no longer automatically initialized to zeros during startup.set_*_tiles() now wrap maps around horizontal and vertical boundaries correctly. Code relying on it not wrapping correctly may be affected.-Wl-yp0x<address>=0x<value> is no longer supported. Instead use makebin flags. For example, use -Wm-yC instead of -Wl-yp0x143=0xC0.The GBDK 2020 releases can be found on Github: https://github.com/Zal0/gbdk-2020/releases
-2021/01/17
2020/11/14
2020/10/01
2020/06/05
2020/05/17
2020/05/16
2020/04/12
2020/04/12
17 April, 2000
Many changes.
@@ -225,7 +225,7 @@ GBDK 2.96
19th August, 2000
This is an experimental release for those who feel keen. The main change is a new lexer (the first part in the compilation process which recognises words and symbols like '!=' and 'char' and turns them into a token number) which speeds up compilation of large initialised arrays like tile data by a factor of three. Please report any bugs that show up - this is a big change.
I have also included a 'minimal' release for win32 users which omits the documentation, library sources, and examples. If this is useful I will keep doing it.
-5th August, 2000
Just a small update. From the README:
22nd July, 2000
7th July, 2000
Information on float and long support. Someone asked about the state of float/long support recently. Heres my reply:
long support is partly there, as is float support. The compiler will correctly recognise the long and float keywords, and will generate the code for most basic ops (+, -, &, | etc) for longs correctly and will generate the function calls for floats and hard long operations (*, /, %) correctly. However it wont generate float constants in the correct format, nor will it 'return' a long or float - gbdk doesn't yet support returning types of 4 bytes. Unfortunately its not going to make it into 2.95 as there's too much else to do, but I should be able to complete long support for 2.96
-7th May, 2000
Many fixes - see the README for more.
6th April, 2000
From the README
26th March, 2000
This is a maintenance release for win32 which fixes some of the niggly install problems, especially:
18th March, 2000
libc5 version available / "Error creating temp file" Thanks to Rodrigo Couto there is now a Linux/libc5 version of gbdk3-2.92 available - follow the download link above. At least it will be there when the main sourceforge site comes back up... Also some people have reported a bug where the compiler reports '*** Error creating temp file'. Try typing "mkdir c: tmp" from a DOS prompt and see if that helps.
8th March, 2000
Better than 2.91 :). Can now be installed anywhere. All the demos work. See the README for more.
27th Feb, 2000
Better than 2.90 and includes Linux, win32 and a source tar ball. Some notes:
18th Oct, 1999
Bug tracking / FAQ up. Try the link on the left to report any bugs with GBDK. It's also the first place to look if your having problems.
17th Oct, 1999
You can manually switch banks using the SWITCH_ROM_MBC1(), SWITCH_RAM_MBC1(), and other related macros. See banks.c project for an example.
Note: You can only do a switch_rom_bank call from unbanked _CODE since otherwise you would switch out the code that was executing. Global routines that will be called without an expectation of bank switching should fit within the limited 16k of unbanked _CODE.
If a function call is made inside an ISR which changes the bank without restoring it, then the _current_bank variable should be saved and then restored.
+Restoring the current bank (after calling functions which change it without restoring) +If a function call is made (for example inside an ISR) which changes the bank without restoring it, then the _current_bank variable should be saved and then restored.
For example, instead of this code:
A bank overflow during compile/link time (in makebin) is when more code and data are allocated to a ROM bank than it has capacity for. The address for any overflowed data will be incorrect and the data is potentially unreachable since it now resides at the start of a different bank instead of the end of the expected bank.
-See the FAQ entry about bank overflow errors.
+See the FAQ entry about bank overflow errors.
The current toolchain can only detect and warn (using ihxcheck) when one bank overflows into another bank that has data at its start. It cannot warn if a bank overflows into an empty one. For more complete detection, you can use the third-party romusage tool.
GBDK 2020 uses the SDCC compiler along with some custom tools to build Game Boy ROMs.
bin/To see individual arguments and options for a tool, run that tool from the command line with either no arguments or with -h.
-
-
-
What do these kinds of warnings / errors mean? WARNING: possibly wrote twice at addr 4000 (93->3E) Warning: Write from one bank spans into the next. 7ff7 -> 8016 (bank 1 -> 2)
You may have a overflow in one of your ROM banks. If there is more data allocated to a bank than it can hold it then will spill over into the next bank. The warnings are generated by ihxcheck during conversion of an .ihx file into a ROM file.
-See the section ROM/RAM Banking and MBCs for more details about how banks work and what their size is. You may want to use a tool such as romusage to calculate the amount of free and used space.
-
-
const keyword. It's important to use the const keyword for read-only data. See const_gbtd_gbmb and const_array_data
-
For data types and special C keywords, see asm/gbz80/types.h and asm/types.h.
+Also see the SDCC manual (scroll down a little on the linked page): http://sdcc.sourceforge.net/doc/sdccman.pdf#section.1.1
-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).
lcc will include the following linker defaults for sdldgb if they are not defined by the user.
@@ -192,7 +141,7 @@ Changing Important Addresses -The lcc 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:
You may also want to read a tutorial on Makefiles. For example:
https://makefiletutorial.com/ https://www.tutorialspoint.com/makefile/index.htm
lcc is the compiler driver (front end) for the GBDK/sdcc toolchain. It can be used to invoke all the tools needed for building a rom. If preferred, the individual tools can be called directly.
-v flag can be used to show the exact steps lcc executes for a buildSDCC C Source compiler
-Wf-<argument> and -Wp-<argument> (pre-processor)SDCC Assembler for the gameboy
-Wa-<argument>Automatic Bank packer
When enabled, automatically assigns banks for object files where bank has been set to 255, see rom_autobanking. Unless an alternative output is specified the given object files are updated with the new bank numbers.
__bank_* symbol).The SDCC linker for the gameboy.
Links object files (.o) into a .ihx file which can be processed by makebin
-Wl-<argument>IHX file validator
Checks .ihx files produced by sdldgb for correctness.
-Wi-<argument>IHX to ROM converter
Converts .ihx files produced by sdldgb into ROM files (.gb, .gbc).
-Wm-<argument>Compresssion utility
Compresses (and decompresses) binary file data with the gbcompress algorithm (also used in GBTD/GBMB). Decompression support is available in GBDK, see gb_decompress().
-Tool for converting PNGs into GBDK format MetaSprites
Interrupts allow execution to jump to a different part of your code as soon as an external event occurs - for example the LCD entering the vertical blank period, serial data arriving or the timer reaching its end count. For an example see the irq.c sample project.
Interrupts in GBDK are handled using the functions disable_interrupts(), enable_interrupts(), set_interrupts(UBYTE ier) and the interrupt service routine (ISR) linkers add_VBL(), add_TIM, add_LCD, add_SIO and add_JOY which add interrupt handlers for the vertical blank, timer, LCD, serial link and joypad interrupts respectively.
@@ -97,7 +97,7 @@ InterruptsInterrupts should be disabled before adding ISRs. To use multiple interrupts, logical OR the relevant IFLAGs together.
ISRs should be kept as small and short as possible, do not write an ISR so long that the Game Boy hardware spends all of its time servicing interrupts and has no time spare for the main code.
For more detail on the Game Boy interrupts consider reading about them in the Pandocs.
-The GameBoy hardware can generate 5 types of interrupts. Custom Interrupt Service Routines (ISRs) can be added in addition to the built-in ones available in GBDK.
It is possible to install your own interrupt handlers (in C or in assembly) for any of these interrupts. Up to 4 chained handlers may be added, with the last added being called last. If the remove_VBL() function is to be called, only three may be added for VBL.
Interrupt handlers are called in sequence. To install a new interrupt handler, do the following:
@@ -140,25 +140,25 @@ Adding your own interrupt handlerSee the irq example project for additional details for a complete example.
By default when an Interrupt handler completes and is ready to exit it will check STAT_REG and only return at the BEGINNING of either LCD Mode 0 or Mode 1. This helps prevent graphical glitches caused when an ISR interrupts a graphics operation in one mode but returns in a different mode for which that graphics operation is not allowed.
You can change this behavior using nowait_int_handler() which does not check STAT_REG before returning. Also see wait_int_handler().
-GBDK sets up a Shadow OAM which gets copied automatically to the hardware OAM by the default V-Blank ISR. The Shadow OAM allows updating sprites without worrying about whether it is safe to write to them or not based on the hardware LCD mode.
-Including stdio.h and using functions such as printf() will use a large number of the background tiles for font characters. If stdio.h is not included then that space will be available for use with other tiles instead.
-The ram_function example project included with GBDK demonstrates copying functions to RAM and HIRAM.
It is possible to copy functions to RAM and HIRAM (using the memcpy() and hiramcpy() functions), and execute them from C. The compiler automatically generates two symbols for the start and the end of each function, named start_X and end_X (where X is the name of the function). This enables to calculate the length of a function when copying it to RAM. Ensure you have enough free space in RAM or HIRAM for copying a function.
@@ -168,10 +168,10 @@ Copying Functions to RAM and HIRAMThe second approach is slightly more efficient. Both approaches are demonstrated in the ram_function.c example.
You can mix C and assembly (ASM) in two ways as described below. For additional detail see the links_sdcc_docs.
-Example:
__asm__("nop");
@@ -183,7 +183,7 @@ Inline ASM within C source files
(ASM code goes here)
__endasm;
}
-It is possible to assemble and link files written in ASM alongside files written in C.
@@ -223,9 +223,9 @@ LD D,H LD E,L ; There is no register to restore RET ; Return result in DE -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.|
+ GBDK 2020 Docs
+
+ API Documentation for GBDK 2020
+ |
+
Sets a rectangular region of Tile Map entries for the Background layer.
+Sets a rectangular region of Background Tile Map.
| x | X Start position in Background Map tile coordinates. Range 0 - 31 |
| y | Y Start position in Background Map tile coordinates. Range 0 - 31 |
| w | Width of area to set in tiles. Range 0 - 31 |
| h | Height of area to set in tiles. Range 0 - 31 |
| tiles | Pointer to source Tile Map data |
| w | Width of area to set in tiles. Range 1 - 32 |
| h | Height of area to set in tiles. Range 1 - 32 |
| tiles | Pointer to source tile map data |
Entries are copied from tiles to the Background Tile Map starting at x, y writing across for w tiles and down for h tiles.
-One byte per Tile map entry.
+Entries are copied from map at tiles to the Background Tile Map starting at x, y writing across for w tiles and down for h tiles.
+Use set_bkg_submap() instead when:
One byte per source tile map entry.
+Writes that exceed coordinate 31 on the x or y axis will wrap around to the Left and Top edges.
Note: Patterns 128-255 overlap with patterns 128-255 of the sprite Tile Pattern table.
GBC only: VBK_REG determines whether Tile Numbers or Tile Attributes get set.
| void set_bkg_submap | +( | +UINT8 | +x, | +
| + | + | UINT8 | +y, | +
| + | + | UINT8 | +w, | +
| + | + | UINT8 | +h, | +
| + | + | const unsigned char * | +map, | +
| + | + | UINT8 | +map_w | +
| + | ) | ++ |
Sets a rectangular area of the Background Tile Map using a sub-region from a source tile map. Useful for scrolling implementations of maps larger than 32 x 32 tiles.
+| x | X Start position in Background Map tile coordinates. Range 0 - 31 |
| y | Y Start position in Background Map tile coordinates. Range 0 - 31 |
| w | Width of area to set in tiles. Range 1 - 255 |
| h | Height of area to set in tiles. Range 1 - 255 |
| map | Pointer to source tile map data |
| map_w | Width of source tile map in tiles. Range 1 - 255 |
Entries are copied from map to the Background Tile Map starting at x, y writing across for w tiles and down for h tiles, using map_w as the rowstride for the source tile map.
+Use this instead of set_bkg_tiles when the source map is wider than 32 tiles or when writing a width that does not match the source map width.
+One byte per source tile map entry.
+Writes that exceed coordinate 31 on the x or y axis will wrap around to the Left and Top edges.
+
See set_bkg_tiles for setting CGB attribute maps with VBK_REG.
+Sets a rectangular region of Tile Map entries for the Window layer.
+Sets a rectangular region of the Window Tile Map.
| x | X Start position in Window Map tile coordinates. Range 0 - 31 |
| y | Y Start position in Window Map tile coordinates. Range 0 - 31 |
| w | Width of area to set in tiles. Range 0 - 31 |
| h | Height of area to set in tiles. Range 0 - 31 |
| tiles | Pointer to source Tile Map data |
| w | Width of area to set in tiles. Range 1 - 32 |
| h | Height of area to set in tiles. Range 1 - 32 |
| tiles | Pointer to source tile map data |
Entries are copied from tiles to the background Tile Map starting at x, y writing across for w tiles and down for h tiles.
-One byte per Tile Map entry.
+Entries are copied from map at tiles to the Window Tile Map starting at x, y writing across for w tiles and down for h tiles.
+Use set_win_submap() instead when:
One byte per source tile map entry.
+Writes that exceed coordinate 31 on the x or y axis will wrap around to the Left and Top edges.
Note: Patterns 128-255 overlap with patterns 128-255 of the sprite Tile Pattern table.
GBC only: VBK_REG determines whether Tile Numbers or Tile Attributes get set.
For more details about GBC Tile Attributes see set_bkg_tiles.
+| void set_win_submap | +( | +UINT8 | +x, | +
| + | + | UINT8 | +y, | +
| + | + | UINT8 | +w, | +
| + | + | UINT8 | +h, | +
| + | + | const unsigned char * | +map, | +
| + | + | UINT8 | +map_w | +
| + | ) | ++ |
Sets a rectangular area of the Window Tile Map using a sub-region from a source tile map.
+| x | X Start position in Window Map tile coordinates. Range 0 - 31 |
| y | Y Start position in Wimdpw Map tile coordinates. Range 0 - 31 |
| w | Width of area to set in tiles. Range 1 - 255 |
| h | Height of area to set in tiles. Range 1 - 255 |
| map | Pointer to source tile map data |
| map_w | Width of source tile map in tiles. Range 1 - 255 |
Entries are copied from map to the Window Tile Map starting at x, y writing across for w tiles and down for h tiles, using map_w as the rowstride for the source tile map.
+Use this instead of set_win_tiles when the source map is wider than 32 tiles or when writing a width that does not match the source map width.
+One byte per source tile map entry.
+Writes that exceed coordinate 31 on the x or y axis will wrap around to the Left and Top edges.
+GBC only: VBK_REG determines whether Tile Numbers or Tile Attributes get set.
See set_bkg_tiles for details about CGB attribute maps with VBK_REG.
+| x | X Start position in Map tile coordinates. Range 0 - 31 |
| y | Y Start position in Map tile coordinates. Range 0 - 31 |
| w | Width of area to set in tiles. Range 0 - 31 |
| h | Height of area to set in tiles. Range 0 - 31 |
| w | Width of area to set in tiles. Range 1 - 32 |
| h | Height of area to set in tiles. Range 1 - 32 |
| vram_addr | Pointer to destination VRAM Address |
| tiles | Pointer to source Tile Map data |
Entries are copied from tiles to Tile Map at address vram_addr starting at x, y writing across for w tiles and down for h tiles.
-One byte per Tile map entry.
+One byte per source tile map entry.
There are two 32x32 Tile Maps in VRAM at addresses 9800h-9BFFh and 9C00h-9FFFh.
GBC only: VBK_REG determines whether Tile Numbers or Tile Attributes get set.