Flesh out man page

Describe current options, and add some TODOs for functionality to be implemented

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 CfmuVZ
-.Op Fl f | Fl F
+.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,136 +50,358 @@ but
 .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.
+Generate an attribute map, which is a file containing tile
-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.
+.Dq attributes .
-Useful in combination with
+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 ,
+.Fl a Ar path ,
-but the attrmap file output name is made by taking the input filename, removing the file extension, and appending
+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.
+When generating palettes, use a color curve mimicking the Game Boy Color's screen.
-.It Fl D , Fl Fl debug
+The resulting colors may look closer to the input image's
-Debug features are enabled.
+.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).
+Set the bit depth of the output tile data, in bits per pixel (bpp), either 1 or 2 (the default).
-By default, the bit depth is 2 (two bits per pixel).
+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.
+Make the input image an
-.It Fl F , Fl Fl fix-and-save
+.Em indexed
-Same as
+PNG.
-.Fl f ,
+.Sy TODO: before or after processing ?
-but additionally, the supplied command line parameters are saved within the PNG and will be loaded and automatically used next time.
+Due to some changes in
-.It Fl h , Fl Fl horizontal
+.Nm Ap s behavior, this option does not really Dq fix
-Lay out tiles in column-major order (column by column), instead of the default row-major order (line by line).
+the input PNG anymore, and so it may be removed in a future RGBDS release.
-Especially useful for "8x16" OBJ mode, if the input image is 16 pixels tall.
+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.
+Deduplicate tiles that are mirrors of each other.
-Useful with tilemaps and attrmaps together to keep track of the duplicated tiles and the dimension mirrored.
 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.
+Output the image's palette set to this file.
-If the palette contains too few colors, the remaining entries are set to black.
+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 ,
+.Fl p Ar path ,
-but the palette file output name is made by taking the input PNG file's filename, removing the file extension, and appending
+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 ,
+.Fl t Ar path ,
-but the tilemap file output name is made by taking the input filename, removing the file extension, and appending
+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.
+Deduplicate identical tiles, and omit the duplicates from the tile data file.
-Useful with tilemaps to keep track of the duplicated tiles.
+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.
+Be verbose.
-Print errors when the command line parameters and the parameters in the PNG file don't match.
+The verbosity level is increased by one each time the flag is specified, with each level including the previous:
-.It Fl x Ar amount , Fl Fl trim-end Ar amount
+.Bl -enum -width 2n -compact
-Trim the end of the output file by this many tiles.
+.It
-.Pq TODO: tiles, or tilemap?
+.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.
+must generate palettes from the colors in the input image, unless
-A lot of the time, the order does not matter; however, sometimes it does, and
+.Fl c
-.Nm
+was used; in that case, the provided palettes will be used.
-attempts to account for those cases.
+.Sy If the order of colors in the palettes is important to you ,
-.Bl -bullet -offset indent
+for example because you want to use palette swaps, please use
-.It
+.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
+This is done
-.Fl TODO ,
+.Sy even if palettes were explicitly specified using Fl c ;
-then they will specify color #1 onwards.
+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.
+Any unused entries will be ignored, and only the first entry is considered if there are 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 .
+.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
 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
 .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.
+behavior depends on an internal detail of how the PNG is saved, specifically its
-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
+.Ql PLTE
-.Fl TODO
+chunk.
-to specify the palette explicitly.
+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.
-.Sh EXAMPLES
+.Ss Tilemap data
-The following will only validate the PNG [...] but output nothing:
+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
-.D1 $ rgbgfx in.png
+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 (check its size, that all tiles have a suitable amount of colors, etc.), but output nothing:
+.Pp
+.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 .