mirror of
https://github.com/gbdev/rgbds.git
synced 2025-11-20 18:22:07 +00:00
Flesh out man page
Describe current options, and add some TODOs for functionality to be implemented
This commit is contained in:
ISSOtm
367
man/rgbgfx.1
367
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,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.
|
||||
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
|
||||
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.
|
||||
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.
|
||||
.Sh EXAMPLES
|
||||
The following will only validate the PNG [...] but output nothing:
|
||||
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
|
||||
.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 .
|
||||
|
||||
Reference in New Issue
Block a user