shithub: rgbds

Info  •  Files  •  Log  •  Branches

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 .