mirror of
https://github.com/gbdev/rgbds.git
synced 2025-11-20 10:12:06 +00:00
186 lines
6.6 KiB
Groff
186 lines
6.6 KiB
Groff
.\"
|
|
.\" This file is part of RGBDS.
|
|
.\"
|
|
.\" Copyright (c) 2013-2021, stag019 and RGBDS contributors.
|
|
.\"
|
|
.\" SPDX-License-Identifier: MIT
|
|
.\"
|
|
.Dd March 28, 2021
|
|
.Dt RGBGFX 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm rgbgfx
|
|
.Nd Game Boy graphics converter
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl CDhmuVv
|
|
.Op Fl f | Fl F
|
|
.Op Fl a Ar attrmap | Fl A
|
|
.Op Fl d Ar depth
|
|
.Op Fl o Ar out_file
|
|
.Op Fl p Ar pal_file | Fl P
|
|
.Op Fl t Ar tilemap | Fl T
|
|
.Op Fl x Ar tiles
|
|
.Ar file
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
program converts PNG images into data suitable
|
|
.Sh ARGUMENTS
|
|
Note that options can be abbreviated as long as the abbreviation is unambiguous:
|
|
.Fl Fl verb
|
|
is
|
|
.Fl Fl verbose ,
|
|
but
|
|
.Fl Fl ver
|
|
is invalid because it could also be
|
|
.Fl Fl version .
|
|
The arguments are as follows:
|
|
.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
|
|
.Fl m
|
|
to keep track the mirror direction of mirrored duplicate tiles.
|
|
.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
|
|
.Pa .attrmap .
|
|
.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.
|
|
.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).
|
|
.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.
|
|
.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.
|
|
Tiles are checked for horizontal, vertical, and horizontal-vertical mirroring.
|
|
Implies
|
|
.Fl u .
|
|
.It Fl o Ar out_file , Fl Fl output Ar out_file
|
|
The name of the output 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.
|
|
.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
|
|
.Pa .pal .
|
|
.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.
|
|
Useful in combination with
|
|
.Fl u
|
|
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
|
|
.Pa .tilemap .
|
|
.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.
|
|
.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?
|
|
.El
|
|
.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
|
|
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.
|
|
.Pq If you do not want this, ask your image editor to remove the alpha channel.
|
|
.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 .
|
|
.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.
|
|
.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 .
|
|
.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.
|
|
.Sh OUTPUT FILES
|
|
.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:
|
|
.Pp
|
|
.D1 $ rgbgfx in.png
|
|
.Sh BUGS
|
|
Please report bugs on
|
|
.Lk https://github.com/gbdev/rgbds/issues GitHub .
|
|
.Sh SEE ALSO
|
|
.Xr rgbds 7 ,
|
|
.Xr rgbasm 1 ,
|
|
.Xr rgblink 1 ,
|
|
.Xr rgbfix 1 ,
|
|
.Xr gbz80 7
|
|
.Sh HISTORY
|
|
.Nm
|
|
was originally created by
|
|
.An stag019
|
|
to be included in RGBDS.
|
|
It was later rewritten by
|
|
.An ISSOtm ,
|
|
and is now maintained by a number of contributors at
|
|
.Lk https://github.com/gbdev/rgbds .
|