ref: 8d00a61602df064d4fe5c4ea5acc72357f451400
parent: 20442c8a43286a1712ae97b43860cbf2f2bdac41
author: ISSOtm <eldredhabert0@gmail.com>
date: Wed Mar 9 04:03:04 EST 2022
Flesh out man page Describe current options, and add some TODOs for functionality to be implemented
--- a/man/rgbgfx.1
+++ b/man/rgbgfx.1
@@ -1,3 +1,4 @@
+'\" e
.\"
.\" This file is part of RGBDS.
.\"
@@ -13,19 +14,33 @@
.Nd Game Boy graphics converter
.Sh SYNOPSIS
.Nm
-.Op Fl CDhmuVv
-.Op Fl f | Fl F
+.Op Fl CfmuVZ
+.Op Fl v Op Fl v No ...
.Op Fl a Ar attrmap | Fl A
+.Op Fl b Ar base_ids
+.Op Fl c Ar color_spec
.Op Fl d Ar depth
+.Op Fl L Ar slice
+.Op Fl N Ar nb_tiles
+.Op Fl n Ar nb_pals
.Op Fl o Ar out_file
.Op Fl p Ar pal_file | Fl P
+.Op Fl s Ar nb_colors
.Op Fl t Ar tilemap | Fl T
-.Op Fl x Ar tiles
+.Op Fl U Ar unit_size
+.Op Fl x Ar quantity
.Ar file
.Sh DESCRIPTION
The
.Nm
-program converts PNG images into data suitable
+program converts PNG images into data suitable for display on the Game Boy and Game Boy Color.
+.Pp
+The main function of
+.Nm
+is to divide the input PNG into 8\[tmu]8 pixel
+.Em squares ,
+convert each of those squares into 1bpp or 2bpp tile data, and save all of the tile data in a file.
+It also has options to generate a tile map, attribute map, and/or palette set as well; more on that and how the conversion process can be tweaked below.
.Sh ARGUMENTS
Note that options can be abbreviated as long as the abbreviation is unambiguous:
.Fl Fl verb
@@ -35,99 +50,276 @@
.Fl Fl ver
is invalid because it could also be
.Fl Fl version .
-The arguments are as follows:
+.Pp
+TODO: describe what number formats are accepted.
+TODO: add "palette map" output.
+.Pp
+The following options are accepted:
.Bl -tag -width Ds
.It Fl a Ar attrmap , Fl Fl attr-map Ar attrmap
-Generate a file of tile mirroring attributes for OAM or (CGB-only) background tiles.
-For each tile in the input file, a byte is written representing the dimensions that the associated tile in the output file should be mirrored.
-Useful in combination with
+Generate an attribute map, which is a file containing tile
+.Dq attributes .
+For each square of the input image, its corresponding attribute map byte contains the mirroring bits (if
.Fl m
-to keep track the mirror direction of mirrored duplicate tiles.
+was specified), the bank bit
+.Pq see Fl N ,
+and the palette index.
+See
+.Lk https://gbdev.io/pandocs/Tile_Maps#bg-map-attributes-cgb-mode-only Pan Docs
+for the individual bytes' format.
+The output is written just like the tile map (see
+.Fl t ) ,
+follows the same order
+.Pq Fl Z ,
+and has the same size.
.It Fl A , Fl Fl output-attr-map
Same as
-.Fl a ,
-but the attrmap file output name is made by taking the input filename, removing the file extension, and appending
+.Fl a Ar path ,
+where
+.Ar path
+is the input image's path with the extension set to
.Pa .attrmap .
+.It Fl b Ar base_ids , Fl Fl base-tiles Ar base_ids
+Set the base IDs for tile map output.
+.Ar base_ids
+should be one or two numbers between 0 and 255, separated by a comma; they are for bank 0 and bank 1 respectively.
+Both default to 0.
.It Fl C , Fl Fl color-curve
-Use the color curve of the Game Boy Color when generating palettes.
-.It Fl D , Fl Fl debug
-Debug features are enabled.
+When generating palettes, use a color curve mimicking the Game Boy Color's screen.
+The resulting colors may look closer to the input image's
+.Sy on hardware and accurate emulators .
+.It Fl c Ar color_spec , Fl Fl colors Ar color_spec
+Use the specified color palettes instead of having
+.Nm
+automatically determine some.
+.Ar color_spec
+can be one of the following:
+.Bl -tag -width Ds
+.It Sy inline palette spec
+If
+.Ar color_spec
+begins with a hash character
+.Ql # ,
+it is treated as an inline palette specification.
+It should contain a comma-separated list of hexadecimal colors, each beginning with a hash.
+Colors in are accepted in the following formats:
+.Ql #rgb ,
+.Ql #rrggbb ,
+and
+.Ql #rrggbbaa .
+Palettes must be separated by a semicolon (they may require quoting to avoid special handling by the shell), and spaces are allowed around semicolons and commas; trailing commas and semicolons are allowed.
+See
+.Sx EXAMPLES
+for an example of an inline palette specification.
+.It Sy embedded palette spec
+If
+.Ar color_spec
+is the case-insensitive word
+.Cm embedded ,
+then the first four colors of the input PNG's embedded palette are used.
+It is an error if the PNG is not indexed, or if colors other than these 4 are used.
+.Pq This is different from the default behavior of indexed PNGs, as then unused entries in the embedded palette are ignored, whereas they are not with Fl c Cm embedded .
+.It Sy external palette spec
+Otherwise,
+.Ar color_spec
+is assumed to be an external palette specification.
+The expected format is
+.Ql format:path ,
+where
+.Ar path
+is a path to a file, which will be processed according to the
+.Ar format .
+See
+.Sx PALETTE SPECIFICATION FORMATS
+for a list of formats and their descriptions.
+.El
.It Fl d Ar depth , Fl Fl depth Ar depth
-The bit depth of the output image (either 1 or 2).
-By default, the bit depth is 2 (two bits per pixel).
+Set the bit depth of the output tile data, in bits per pixel (bpp), either 1 or 2 (the default).
+This changes how tile data is output, and the maximum number of colors per palette (2 and 4 respectively).
.It Fl f , Fl Fl fix
-Fix the input PNG file to be a correctly indexed image.
-.It Fl F , Fl Fl fix-and-save
-Same as
-.Fl f ,
-but additionally, the supplied command line parameters are saved within the PNG and will be loaded and automatically used next time.
-.It Fl h , Fl Fl horizontal
-Lay out tiles in column-major order (column by column), instead of the default row-major order (line by line).
-Especially useful for "8x16" OBJ mode, if the input image is 16 pixels tall.
+Make the input image an
+.Em indexed
+PNG.
+.Sy TODO: before or after processing ?
+Due to some changes in
+.Nm Ap s behavior, this option does not really Dq fix
+the input PNG anymore, and so it may be removed in a future RGBDS release.
+To manipulate a PNG's format, using an external editor like GIMP or command-line tools like ImageMagick's
+.Xr convert 1
+program is recommended instead.
+.It Fl L Ar slice , Fl Fl slice Ar slice
+Only process a given rectangle of the image.
+.Sy TODO: arg format .
+This is useful for example if the input image is a sheet of some sort, and you want to convert each item individually.
.It Fl m , Fl Fl mirror-tiles
-Truncate tiles by checking for tiles that are mirrored versions of others and omitting these from the output file.
-Useful with tilemaps and attrmaps together to keep track of the duplicated tiles and the dimension mirrored.
+Deduplicate tiles that are mirrors of each other.
Tiles are checked for horizontal, vertical, and horizontal-vertical mirroring.
+Useful with a tile map and attribute map together to keep track of the duplicated tiles and the dimension(s) mirrored.
Implies
.Fl u .
+.It Fl N Ar nb_tiles , Fl Fl nb-tiles Ar nb_tiles
+Set a maximum number of tiles that can be placed in each VRAM bank.
+.Ar nb_tiles
+should be one or two numbers between 0 and 256, separated by a comma; if the latter is omitted, it defaults to 0.
+Setting either number to 0 prevents any tiles froom being output in that bank.
+.Pp
+If more tiles are generated than can fit in the two banks combined,
+.Nm
+will abort.
+If
+.Fl N
+is not specified, no limit will be set on the amount of tiles placed in bank 0, and tiles will not be placed in bank 1.
+.It Fl n Ar nb_pals , Fl Fl nb-palettes Ar nb_pals
+Abort if more than
+.Ar nb_pals
+palettes are generated.
+Note that attribute map output only has 3 bits for the palette ID, so a limit higher than 8 may yield incomplete data.
.It Fl o Ar out_file , Fl Fl output Ar out_file
-The name of the output file.
+Output the tile data in native 2bpp format or in 1bpp
+.Pq depending on Fl d
+to this file.
.It Fl p Ar pal_file , Fl Fl palette Ar pal_file
-Output the image's palette in standard GBC palette format: bytes (8 bytes for two bits per pixel, 4 bytes for one bit per pixel) containing the RGB15 values in little-endian byte order.
-If the palette contains too few colors, the remaining entries are set to black.
+Output the image's palette set to this file.
+Palettes are emitted in order, TODO.
+If the palette contains too few colors, the remaining entries are TODO.
.It Fl P , Fl Fl output-palette
Same as
-.Fl p ,
-but the palette file output name is made by taking the input PNG file's filename, removing the file extension, and appending
+.Fl p Ar path ,
+where
+.Ar path
+is the input image's path with the extension set to
.Pa .pal .
+.It Fl s Ar nb_colors , Fl Fl palette-size Ar nb_colors
+Specify how many colors each palette contains, including the transparent one if any.
+.Ar nb_colors
+cannot be more than
+.Ql 1 << Ar depth
+.Pq see Fl d .
.It Fl t Ar tilemap , Fl Fl tilemap Ar tilemap
Generate a file of tile indices.
-For each tile in the input file, a byte is written representing the index of the associated tile in the output file.
+For each square of the input image, its corresponding tile map byte contains the index of the associated tile in the tile data file.
+The IDs wrap around from 255 back to 0, and do not include the bank bit; use
+.Fl a
+for that.
Useful in combination with
.Fl u
-or
+and/or
.Fl m
to keep track of duplicate tiles.
.It Fl T , Fl Fl output-tilemap
Same as
-.Fl t ,
-but the tilemap file output name is made by taking the input filename, removing the file extension, and appending
+.Fl t Ar path ,
+where
+.Ar path
+is the input image's path with the extension set to
.Pa .tilemap .
+.It Fl U Ar unit_size , Fl Fl unit-size Ar unit_size
+Set the deduplication
+.Dq unit
+size to
+.Ar unit_size ,
+which should be two comma-separated tile counts (width then height).
+Defaults to
+.Ql 1,1 ,
+i.e. one tile.
+.Fl U Cm 1,2
+is particularly useful for the
+.Dq 8\[tmu]16
+OAM mode.
+.Pp
+.Sy TODO: describe how this affects the dedup process, and how the image is visited .
.It Fl u , Fl Fl unique-tiles
-Truncate tiles by checking for tiles that are exact duplicates of others and omitting these from the output file.
-Useful with tilemaps to keep track of the duplicated tiles.
+Deduplicate identical tiles, and omit the duplicates from the tile data file.
+Useful with a tile map
+.Pq see Fl t
+to keep track of the duplicated tiles.
+.Pp
+Note that if this option is enabled, no guarantee is made on the order in which tiles are output; while it
+.Em should
+be consistent across identical runs of a given
+.Nm
+release, the same is not true for different releases.
.It Fl V , Fl Fl version
Print the version of the program and exit.
.It Fl v , Fl Fl verbose
-Verbose.
-Print errors when the command line parameters and the parameters in the PNG file don't match.
-.It Fl x Ar amount , Fl Fl trim-end Ar amount
-Trim the end of the output file by this many tiles.
-.Pq TODO: tiles, or tilemap?
+Be verbose.
+The verbosity level is increased by one each time the flag is specified, with each level including the previous:
+.Bl -enum -width 2n -compact
+.It
+.Nm
+prints out its configuration before doing anything.
+.It
+A generic message is printed before doing most actions.
+.It
+Some of the actions' intermediate results are printed.
+.It
+Some internal debug printing is enabled.
.El
+The verbosity level does not go past 6.
+.Pp
+Note that verbose output is only intended to be consumed by humans, and may change without notice between RGBDS releases; relying on those for scripts is not advised.
+.It Fl x Ar quantity , Fl Fl trim-end Ar quantity
+Do not output the last
+.Ar quantity
+tiles to the tile data file; no other output is affected.
+This is useful for trimming
+.Dq filler
+/ blank squares at the end of an image.
+If fewer than
+.Ar quantity
+tiles would have been emitted, the file will be empty.
+.Pp
+Note that this is done
+.Em after
+deduplication if
+.Fl u
+was enabled, so you probably don't want to use this option in combination with
+.Fl u .
+Note also that the tiles that don't get output will not count towards
+.Fl N Ap s
+limit.
+.It Fl Z , Fl Fl columns
+Read squares from the PNG in column-major order (column by column), instead of the default row-major order (line by line).
+This primarily affects tile map and attribute map output, although it may also change generated tile data and palettes.
+.El
+.Sh PALETTE SPECIFICATION FORMATS
+TODO.
.Sh PALETTE GENERATION
.Nm
-must decide in which order to place colors in the palettes, but the input PNG usually lacks any indications.
-A lot of the time, the order does not matter; however, sometimes it does, and
-.Nm
-attempts to account for those cases.
-.Bl -bullet -offset indent
-.It
+must generate palettes from the colors in the input image, unless
+.Fl c
+was used; in that case, the provided palettes will be used.
+.Sy If the order of colors in the palettes is important to you ,
+for example because you want to use palette swaps, please use
+.Fl c
+to specify the palette explicitly.
+.Pp
First, if the image contains
.Em any
transparent pixel, color #0 of
.Em all
palettes will be allocated to it.
-If palettes were explicitly specified using
-.Fl TODO ,
-then they will specify color #1 onwards.
+This is done
+.Sy even if palettes were explicitly specified using Fl c ;
+then the specification only covers color #1 onwards.
.Pq If you do not want this, ask your image editor to remove the alpha channel.
+.Pp
+After generating palettes,
+.Nm
+sorts colors within those palettes using the following rules:
+.EQ
+delim $$
+.EN
+.Bl -bullet -offset indent
.It
If the PNG file internally contains a palette (often dubbed an
.Dq indexed
PNG), then colors in each output palette will be sorted according to their order in the PNG's palette.
-Any unused entries will be ignored, and only the first entry is considered if there any duplicates.
-.Pq If you want a given color to appear more than once in a palette, you should specify the palettes explicitly instead using Fl TODO .
+Any unused entries will be ignored, and only the first entry is considered if there are any duplicates.
+.Po If you want a given color to appear more than once, or an unused color to appear at all, you should specify the palettes explicitly instead using Fl c ;
+.Fl c Cm embedded
+may be appropriate.
+.Pc
.It
Otherwise, if the PNG only contains shades of gray, they will be categorized into as many
.Dq bins
@@ -134,11 +326,18 @@
as there are colors per palette, and the palette is set to these bins.
The darkest gray will end up in bin #0, and so on; note that this is the opposite of the RGB method below.
If two distinct grays end up in the same bin, the RGB method is used instead.
+.Pp
+Be careful that
+.Nm
+is picky about what it considers
+.Dq grays :
+the red, green, and blue components of each color must
+.Em all
+be
+.Em exactly
+the same.
.It
If none of the above apply, colors are sorted from lightest to darkest.
-.EQ
-delim $$
-.EN
The definition of luminance that
.Nm
uses is
@@ -145,26 +344,64 @@
.Do
$2126 times red + 7152 times green + 722 times blue$
.Dc .
+.El
.EQ
delim off
.EN
-.El
.Pp
Note that the
.Dq indexed
-behavior depends on an internal detail of how the PNG is saved.
-Since few image editors (such as GIMP) expose that detail, this behavior is only kept for compatibility and should be considered deprecated; if the order of colors in the palettes is important to you, please use
-.Fl TODO
-to specify the palette explicitly.
+behavior depends on an internal detail of how the PNG is saved, specifically its
+.Ql PLTE
+chunk.
+Since few image editors (such as GIMP) expose that detail, this behavior is only kept for compatibility and should be considered deprecated.
.Sh OUTPUT FILES
+.Ss Tile data
+TODO.
.Ss Palette data
Palette data is output like a dump of GBC palette memory: the output is a binary file.
Each color is written as GBC-native little-endian RGB555 (that is, the first byte contains the red and the lower 3 bits of green).
-There is no padding between colors, nor between palettes; however, empty colors in the palettes are filled as 0xFF bytes.
+There is no padding between colors, nor between palettes; however, empty colors in the palettes are TODO.
+.Ss Tilemap data
+TODO.
+.Ss Attrmap data
+TODO.
+.Sh NOTES
+Some flags have had their functionality removed.
+.Fl D
+is now ignored,
+.Fl F
+now behaves like
+.Fl f ,
+and
+.Fl h
+is an alias for the new (and less confusingly named)
+.Fl Z .
+These will be removed and/or repurposed in future versions of
+.Nm ,
+so relying on them is not recommended.
+The same applies to the corresponding long options.
+.Pp
+If you are curious, you may find out that palette generation is an NP-complete problem, so
+.Nm
+does not attempt to find the optimal solution, but instead to find a good one in a reasonable amount of time.
+It is possible to compute the optimal solution externally (using a solver, for example), and then provide it to
+.Nm
+via
+.Fl c .
.Sh EXAMPLES
-The following will only validate the PNG [...] but output nothing:
+The following will only validate the PNG (check its size, that all tiles have a suitable amount of colors, etc.), but output nothing:
.Pp
-.D1 $ rgbgfx in.png
+.Dl $ rgbgfx src/res/maps/overworld/tileset.png
+.Pp
+The following will convert the image using the two given palettes (and only those), and store the generated 2bpp tile data in
+.Ql tileset.2bpp ,
+and the attribute map in
+.Ql tileset.attrmap .
+.Pp
+.Dl $ rgbgfx -c '#ffffff,#8d05de, #dc7905,#000000 ; #fff,#8d05de, #7e0000 \&, #000' -A -o tileset.2bpp tileset.png
+.Pp
+TODO: more examples.
.Sh BUGS
Please report bugs on
.Lk https://github.com/gbdev/rgbds/issues GitHub .