gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit fcc92604afa5f9972490a69c37997405ce671f0c parent 08bcc9fce5118903337196994c585abce26c8f87 Author: bbbbbr <reg+github@roughhousing.com> Date: Sun, 19 Sep 2021 00:00:08 -0700 Merge pull request #264 from bbbbbr/docs_4_0_5 Docs: updates for 4.0.5 Diffstat:
| M | docs/pages/06_toolchain.md | 85 | ++++++++++++++++++++++++++++++++++++++++++++++++------------------------------- |
| M | docs/pages/08_faq.md | 4 | ++++ |
| M | docs/pages/10_release_notes.md | 4 | ++++ |
| M | gbdk-support/png2asset/readme.md | 79 | ++++++++++++++++++++++++++++++++++++++++++------------------------------------- |
4 files changed, 102 insertions(+), 70 deletions(-)
diff --git a/docs/pages/06_toolchain.md b/docs/pages/06_toolchain.md @@ -200,43 +200,62 @@ Compresses (and decompresses) binary file data with the gbcompress algorithm (al @anchor utility_png2asset -## PNG to Asset -Tool for converting PNGs into GBDK format MetaSprites +## png2asset +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. +- 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 For detailed settings see @ref png2asset-settings For working with sprite properties (including cgb palettes), see @ref metasprite_and_sprite_properties For API support see @ref move_metasprite() and related functions in @ref metasprites.h ### Working with png2asset - - The origin (pivot) for the metasprite is not required to be in the upper left-hand corner as with regular hardware sprites. - - - The conversion process supports using both SPRITES_8x8 and SPRITES_8x16 mode. If 8x16 mode is used then the height of the metasprite must be a multiple of 16. - - - It will attempt to deduplicate/re-use as many tiles as possible (including ones flipping on the X and Y axis) when building the tile set to be used by the convterted metasprite. This does mean that minor changes to the input graphics may change the numer and order of tiles in the resulting tile set. - - - While the tool supports both indexed and full color images as inputs, it only exports as a fixed 3 color + transparent palette per metasprite. - - The input images are first converted to 32 bit RGBA color, then to greyscale (using `255 - ((R * 0.3f) + (G * 0.59f) + (B * 0.11f))`) and then to grouped into the 3 colors based on their brightness. - - The brightness mapping is approximately as follows: - - Alpha 100% transparent pixels : Transparent - ~78% - ~100% : Lightest/White - ~26% - ~77% : Medium - 0% - ~25% : Darkest/Black - - - A fixed palette is used for export, the order of colors will get re-arranged to map onto this fixed palette. It is arranged/assumed as follows (An example would be `OBP0_REG = 0xE4` or `=0xE0`). - - OBP Index 0: Transparent - OBP Index 1: Lightest/White - OBP Index 2: Medium - OBP Index 3: Darkest/Black - - - If you want to assign different colors then you can either change the settings in @ref OBP0_REG / @ref OBP1_REG in your _source code_ or change the colors of your _input image_ to produce different output, but the output of the png2asset tool itself cannot be altered (for now). - - For best graphics conversion results: - - Input images should only have 3 colors + transparent and which are spaced along the brightness spectrum based on the mapping described above. - - For optimal deduplication, try to align the graphics so that tiles used multiple times align on the same 8 pixel boundaries. - - @todo Support indexed color (non-remapped) for source images to bypass the brightness binning and palette mapping. - + - The origin (pivot) for the metasprite is not required to be in the upper left-hand corner as with regular hardware sprites. See `-px` and `-py`. + + - The conversion process supports using both SPRITES_8x8 (`-spr8x8`) and SPRITES_8x16 mode (`-spr8x16`). If 8x16 mode is used then the height of the metasprite must be a multiple of 16. + +#### Terminology +The following abbreviations are used in this section: +* Original Game Boy and Game Boy Pocket style hardware: `DMG` +* Game Boy Color: `CGB` + +#### 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 + +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 + +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 + +#### Maps +Passing `-map` the png can be converted to a map that can be used in both the background and the window. In this case, png2asset will generate: + - The palettes + - The tileset + - 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. + - Use `-noflip` to make background maps which are compatible with `DMG` devices. + +#### Meta sprites +By default the png will be converted to metasprites. The image will be subdivided into meta sprites of `-sw` x `-sh`. In this case png2asset will generate: + - The metasprites, containing an array of: + - tile index + - y offset + - x offset + - flags, containing the mirror info, the palettes for both DMG and GBC and the sprite priority + - The metasprites array diff --git a/docs/pages/08_faq.md b/docs/pages/08_faq.md @@ -23,6 +23,10 @@ - See @ref setting_mbc_and_rom_ram_banks <!-- --> # Errors / Compiling / Toolchain + @anchor faq_sdcc_peephole_instruction_error + - What does `z80instructionSize() failed to parse line node, assuming 999 bytes` mean? + - This is a known issue with SDCC Peephole Optimizer parsing and can be ignored. A bug report has been filed for it. <!-- --> + @anchor faq_bank_overflow_errors - What do these kinds of warnings / errors mean? `WARNING: possibly wrote twice at addr 4000 (93->3E)` diff --git a/docs/pages/10_release_notes.md b/docs/pages/10_release_notes.md @@ -8,6 +8,10 @@ https://github.com/gbdk-2020/gbdk-2020/releases ## GBDK 2020 4.0.5 2021/09 + - Includes SDCC version 12539 with GBDK-2020 patches for Z80 + - Known Issues + - SDCC: `z80instructionSize() failed to parse line node, assuming 999 bytes` + - This is a known issue with the SDCC Peephole Optimizer parsing and can be ignored. - Added support for new consoles. See @ref docs_supported_consoles - Analogue Pocket (`ap`) - Sega Master System (`sms`) and Game Gear (`gg`) diff --git a/gbdk-support/png2asset/readme.md b/gbdk-support/png2asset/readme.md @@ -1,48 +1,53 @@ # png2asset - A tool that converts png to maps or meta sprites in C for gbdk 2020 -## Working with png2asset - -pn2asset accepts any png as input. That doesn't 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 fill be generated -- If there are more than 4 colors in the palette it will throw an error -- The palette will be sorted from black to white, and if there is a transparent color that will be the first one (this will create a palette that will also work in DMG) -- If there are more than 8 palettes the program will throw an error +### Working with png2asset + - The origin (pivot) for the metasprite is not required to be in the upper left-hand corner as with regular hardware sprites. See `-px` and `-py`. -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 + - The conversion process supports using both SPRITES_8x8 (`-spr8x8`) and SPRITES_8x16 mode (`-spr8x16`). If 8x16 mode is used then the height of the metasprite must be a multiple of 16. -It is also posible to pass a png8 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 -- 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 -- The palette won't be taken into account, only the order, meaning there will be a match between tiles using different palettes but looking identical on grayscale - -### Maps - -Passing -map the png can be converted to a map that can be used in both the background and the window. In this case, png2asset will generate: -- The palettes -- The tileset -- 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 GBC - - Passing -use_map_attributes will create an array of map attributes. It will also add mirror info for each tile and because of that maps created with this won't be compatible with DMG +#### Terminology +The following abbreviations are used in this section: +* Original Game Boy and Game Boy Pocket style hardware: `DMG` +* Game Boy Color: `CGB` +#### 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 +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 -### Meta sprites +It is also posible to pass an 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 -By default the png will be converted to metasprites. The image will be subdivided into meta sprites of -sw x -sh. In this case png2asset will generate: -- The metasprites, containing an array of: - - tile index - - y offset - - x offset - - flags, containing the mirror info, the palettes for both DMG and GBC and the sprite priority -- The metasprites array +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 + +#### Maps +Passing `-map` the png can be converted to a map that can be used in both the background and the window. In this case, png2asset will generate: + - The palettes + - The tileset + - 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. + - Use `-noflip` to make background maps which are compatible with `DMG` devices. + +#### Meta sprites +By default the png will be converted to metasprites. The image will be subdivided into meta sprites of `-sw` x `-sh`. In this case png2asset will generate: + - The metasprites, containing an array of: + - tile index + - y offset + - x offset + - flags, containing the mirror info, the palettes for both DMG and GBC and the sprite priority + - The metasprites array
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.