gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 475f0dc7b21daca698d56dbd6beda5a0dd09c0fa parent 3b7174b22e18c7569f8444bf83031434b8b959a8 Author: bbbbbr <bbbbbr@users.noreply.github.com> Date: Wed, 1 Mar 2023 23:51:03 -0800 Merge pull request #485 from bbbbbr/docs_4_2_0 Docs 4.2.0 Diffstat:
| M | docs/pages/01_getting_started.md | 4 | +++- |
| M | docs/pages/08_faq.md | 10 | +++++++++- |
| M | gbdk-lib/include/gb/gb.h | 4 | ++-- |
| M | gbdk-lib/include/gb/metasprites.h | 36 | +++++++++++++++++++++--------------- |
| M | gbdk-lib/include/msx/metasprites.h | 24 | ++---------------------- |
| M | gbdk-lib/include/msx/msx.h | 4 | ++-- |
| M | gbdk-lib/include/nes/metasprites.h | 48 | ++---------------------------------------------- |
| M | gbdk-lib/include/nes/nes.h | 4 | ++-- |
| M | gbdk-lib/include/sms/metasprites.h | 24 | ++---------------------- |
| M | gbdk-lib/include/sms/sms.h | 4 | ++-- |
10 files changed, 47 insertions(+), 115 deletions(-)
diff --git a/docs/pages/01_getting_started.md b/docs/pages/01_getting_started.md @@ -33,7 +33,9 @@ This should build all of the examples sequentially. You can also navigate into a @anchor macos_unsigned_security_workaround ### macOS security warnings -If you get a security warning about unsigned binaries on macOS, you will need to unquarrantine the files in the bin folder. This can be fixed using the following steps. +If you get a security warning on macOS that says ("`... developer cannot be verified, macOS cannot verify that this app is free from malware`"), it does not mean that GBDK is malware. It just means the GBDK toolchain binaries are not signed by Apple, so it won't run them without an additional step. + +You will need to unquarrantine the files in the bin folder in order to run them. This can be fixed using the following steps. Open a terminal and navigate to the gbdk bin folder (`"bin/"` under your GBDK-2020 install folder). Then type: diff --git a/docs/pages/08_faq.md b/docs/pages/08_faq.md @@ -34,7 +34,7 @@ - How do I set the ROM @ref MBC type, and what MBC values are available to use with the `-yt` @ref makebin flag? - See @ref setting_mbc_and_rom_ram_banks <!-- --> -# Errors / Compiling / Toolchain +# Errors @anchor faq_gbz80_sm83_old_port_name_error - What does the error `old "gbz80" SDCC PORT name specified (in "-mgbz80:gb"). Use "sm83" instead. You must update your build settings.` mean? - The `PORT` name for the Game Boy and related clones changed from `gbz80` to `sm83` in the SDCC version used in GBDK-2020 4.1.0 and later. You must change your Makefile, Build settings, etc to use the new name. Additional details in the @ref console_port_plat_settings "Console Port and Platform Settings" section. <!-- --> @@ -72,6 +72,14 @@ - 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. <!-- --> +@anchor faq_error_mbc_size + - On macOS, what does `... developer cannot be verified, macOS cannot verify that this app is free from malware` mean? + - It does not mean that GBDK is malware. It just means the GBDK toolchain binaries are not signed by Apple, so it won't run them without an additional step. + + - For the workaround, see the @ref macos_unsigned_security_workaround "macOS unsigned binary workaround" for details. <!-- --> + + +# Debugging / Compiling / Toolchain - 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/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h @@ -1674,11 +1674,11 @@ __REG _shadow_OAM_base; */ #define MAX_HARDWARE_SPRITES 40 -/** True if sprite hardware can flip sprites by X +/** True if sprite hardware can flip sprites by X (horizontally) */ #define HARDWARE_SPRITE_CAN_FLIP_X 1 -/** True if sprite hardware can flip sprites by Y +/** True if sprite hardware can flip sprites by Y (vertically) */ #define HARDWARE_SPRITE_CAN_FLIP_Y 1 diff --git a/gbdk-lib/include/gb/metasprites.h b/gbdk-lib/include/gb/metasprites.h @@ -1,5 +1,6 @@ /** @file gb/metasprites.h + @anchor metasprite_main_docs # Metasprite support A metasprite is a larger sprite made up from a @@ -35,7 +36,7 @@ // Hide rest of the hardware sprites, because amount // of sprites differ between animation frames. // (where hiwater == last hardware sprite used + 1) - for (uint8_t i = hiwater; i < 40; i++) shadow_OAM[i].y = 0; + hide_sprites_range(hiwater, MAX_HARDWARE_SPRITES); \endcode @anchor metasprite_and_sprite_properties @@ -48,20 +49,25 @@ will get overwritten. How to use sprite property flags with metasprites: - - Metsaprite structures can be copied into RAM so their - property flags can be modified at runtime. - - The metasprite structures can have the property flags - modified before compilation (such as with `-sp <props>` - in the @ref utility_png2asset "png2asset" tool). - - Update properties for the affected sprites after calling - a move_metasprite_*() function. - - The following functions are only available for Game Boy and - related clone consoles due to lack of hardware support for - sprite flipping in other consoles. See @ref docs_consoles_supported_list - - @ref move_metasprite_vflip() - - @ref move_metasprite_hflip() - - @ref move_metasprite_hvflip() + - Primary method: Use the `base_prop` parameter for the + move_metasprite_*() functions. + - Alternate method: The metasprite structures can have the + property flags modified before compilation (such as with + `-sp <props>` in the @ref utility_png2asset "png2asset" tool). + + The following functions only support hardware sprite flipping + on the Game Boy / Mega Duck and NES. For other consoles which + do not have hardware sprite flipping see the cross-platform + metasprite example for a workaround (with some performance penalty). + + - @ref move_metasprite_flipx() + - @ref move_metasprite_flipy() + - @ref move_metasprite_flipxy() + + To test for hardware support see + @ref HARDWARE_SPRITE_CAN_FLIP_X and @ref HARDWARE_SPRITE_CAN_FLIP_Y. + Also see @ref docs_consoles_supported_list for a brief summary of + console capabilities. */ #ifndef _METASPRITES_H_INCLUDE diff --git a/gbdk-lib/include/msx/metasprites.h b/gbdk-lib/include/msx/metasprites.h @@ -7,28 +7,8 @@ Different frames of the same metasprites can share tile data. - The api supports metasprites in both - @ref SPRITES_8x8 and @ref SPRITES_8x16 mode. If - 8x16 mode is used then the height of the metasprite - must be a multiple of 16. - - The origin (pivot) for the metasprite is not required - to be in the upper left-hand corner as with regular - hardware sprites. - - Use the @ref utility_png2asset tool to convert single - or multiple frames of graphics into metasprite - structured data for use with the ...metasprite...() - functions. - - # Metasprites composed of variable numbers of sprites - - When using png2asset, it's common for the output of - different frames to be composed of different numbers - of hardware sprites (since it's trying to create each - frame as efficiently as possible). Due to that, it's - good practice to clear out (hide) unused sprites in the - shadow_OAM that have been set by previous frames. + See the main @ref metasprite_main_docs "metasprite docs" + under the game Boy platform for additional details. */ #ifndef _METASPRITES_H_INCLUDE diff --git a/gbdk-lib/include/msx/msx.h b/gbdk-lib/include/msx/msx.h @@ -635,11 +635,11 @@ extern volatile uint8_t _shadow_OAM_OFF; */ #define MAX_HARDWARE_SPRITES 32 -/** True if sprite hardware can flip sprites by X +/** True if sprite hardware can flip sprites by X (horizontally) */ #define HARDWARE_SPRITE_CAN_FLIP_X 0 -/** True if sprite hardware can flip sprites by Y +/** True if sprite hardware can flip sprites by Y (vertically) */ #define HARDWARE_SPRITE_CAN_FLIP_Y 0 diff --git a/gbdk-lib/include/nes/metasprites.h b/gbdk-lib/include/nes/metasprites.h @@ -7,52 +7,8 @@ Different frames of the same metasprites can share tile data. - The api supports metasprites in both - @ref SPRITES_8x8 and @ref SPRITES_8x16 mode. If - 8x16 mode is used then the height of the metasprite - must be a multiple of 16. - - The origin (pivot) for the metasprite is not required - to be in the upper left-hand corner as with regular - hardware sprites. - - Use the @ref utility_png2asset tool to convert single - or multiple frames of graphics into metasprite - structured data for use with the ...metasprite...() - functions. - - # Metasprites composed of variable numbers of sprites - - When using png2asset, it's common for the output of - different frames to be composed of different numbers - of hardware sprites (since it's trying to create each - frame as efficiently as possible). Due to that, it's - good practice to clear out (hide) unused sprites in the - shadow_OAM that have been set by previous frames. - - \code - // Example: - // Hide rest of the hardware sprites, because amount - // of sprites differ between animation frames. - // (where hiwater == last hardware sprite used + 1) - for (uint8_t i = hiwater; i < 64; i++) shadow_OAM[i].y = 0; - \endcode - - # Metasprites and sprite properties (including cgb palette) - - When the move_metasprite_*() functions are called they - update all properties for the affected sprites in the - Shadow OAM. This means any existing property flags set - for a sprite will get overwritten. - - How to use sprite property flags with metasprites: - - Metsaprite structures can be copied into RAM so their - property flags can be modified at runtime. - - The metasprite structures can have the property flags - modified before compilation (such as with `-sp <props>` - in the @ref utility_png2asset "png2asset" tool). - - Update properties for the affected sprites after calling - a move_metasprite_*() function. + See the main @ref metasprite_main_docs "metasprite docs" + under the game Boy platform for additional details. */ #ifndef _METASPRITES_H_INCLUDE diff --git a/gbdk-lib/include/nes/nes.h b/gbdk-lib/include/nes/nes.h @@ -823,11 +823,11 @@ extern uint8_t _shadow_OAM_base; */ #define MAX_HARDWARE_SPRITES 64 -/** True if sprite hardware can flip sprites by X +/** True if sprite hardware can flip sprites by X (horizontally) */ #define HARDWARE_SPRITE_CAN_FLIP_X 1 -/** True if sprite hardware can flip sprites by Y +/** True if sprite hardware can flip sprites by Y (vertically) */ #define HARDWARE_SPRITE_CAN_FLIP_Y 1 diff --git a/gbdk-lib/include/sms/metasprites.h b/gbdk-lib/include/sms/metasprites.h @@ -7,28 +7,8 @@ Different frames of the same metasprites can share tile data. - The api supports metasprites in both - @ref SPRITES_8x8 and @ref SPRITES_8x16 mode. If - 8x16 mode is used then the height of the metasprite - must be a multiple of 16. - - The origin (pivot) for the metasprite is not required - to be in the upper left-hand corner as with regular - hardware sprites. - - Use the @ref utility_png2asset tool to convert single - or multiple frames of graphics into metasprite - structured data for use with the ...metasprite...() - functions. - - # Metasprites composed of variable numbers of sprites - - When using png2asset, it's common for the output of - different frames to be composed of different numbers - of hardware sprites (since it's trying to create each - frame as efficiently as possible). Due to that, it's - good practice to clear out (hide) unused sprites in the - shadow_OAM that have been set by previous frames. + See the main @ref metasprite_main_docs "metasprite docs" + under the game Boy platform for additional details. */ #ifndef _METASPRITES_H_INCLUDE diff --git a/gbdk-lib/include/sms/sms.h b/gbdk-lib/include/sms/sms.h @@ -680,11 +680,11 @@ extern volatile uint8_t _shadow_OAM_OFF; */ #define MAX_HARDWARE_SPRITES 64 -/** True if sprite hardware can flip sprites by X +/** True if sprite hardware can flip sprites by X (horizontally) */ #define HARDWARE_SPRITE_CAN_FLIP_X 0 -/** True if sprite hardware can flip sprites by Y +/** True if sprite hardware can flip sprites by Y (vertically) */ #define HARDWARE_SPRITE_CAN_FLIP_Y 0
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.