1.\" 2.\" This file is part of RGBDS. 3.\" 4.\" Copyright (c) 2013-2021, stag019 and RGBDS contributors. 5.\" 6.\" SPDX-License-Identifier: MIT 7.\" 8.Dd March 28, 2021 9.Dt RGBGFX 1 10.Os 11.Sh NAME 12.Nm rgbgfx 13.Nd Game Boy graphics converter 14.Sh SYNOPSIS 15.Nm 16.Op Fl CDhmuVv 17.Op Fl f | Fl F 18.Op Fl a Ar attrmap | Fl A 19.Op Fl d Ar depth 20.Op Fl o Ar out_file 21.Op Fl p Ar pal_file | Fl P 22.Op Fl t Ar tilemap | Fl T 23.Op Fl x Ar tiles 24.Ar file 25.Sh DESCRIPTION 26The 27.Nm 28program converts PNG images into the Nintendo Game Boy's planar tile format. 29.Pp 30The resulting colors and their palette indices are determined differently depending on the input PNG file: 31.Bl -dash -width Ds 32.It 33If the file has an embedded palette, that palette's color and order are used. 34.It 35If not, and the image only contains shades of gray, rgbgfx maps them to the indices appropriate for each shade. 36Any undetermined indices are set to respective default shades of gray. 37For example: if the bit depth is 2 and the image contains light gray and black, they become the second and fourth colors, and the first and third colors get set to default white and dark gray. 38If the image has multiple shades that map to the same index, the palette is instead determined as if the image had color. 39.It 40If the image has color (or the grayscale method failed), the colors are sorted from lightest to darkest. 41.El 42.Pp 43The input image may not contain more colors than the selected bit depth allows. 44Transparent pixels are set to palette index 0. 45.Sh ARGUMENTS 46Note that options can be abbreviated as long as the abbreviation is unambiguous: 47.Fl Fl verb 48is 49.Fl Fl verbose , 50but 51.Fl Fl ver 52is invalid because it could also be 53.Fl Fl version . 54The arguments are as follows: 55.Bl -tag -width Ds 56.It Fl a Ar attrmap , Fl Fl attr-map Ar attrmap 57Generate a file of tile mirroring attributes for OAM or (CGB-only) background tiles. 58For each tile in the input file, a byte is written representing the dimensions that the associated tile in the output file should be mirrored. 59Useful in combination with 60.Fl m 61to keep track the mirror direction of mirrored duplicate tiles. 62.It Fl A , Fl Fl output-attr-map 63Same as 64.Fl a , 65but the attrmap file output name is made by taking the input filename, removing the file extension, and appending 66.Pa .attrmap . 67.It Fl C , Fl Fl color-curve 68Use the color curve of the Game Boy Color when generating palettes. 69.It Fl D , Fl Fl debug 70Debug features are enabled. 71.It Fl d Ar depth , Fl Fl depth Ar depth 72The bit depth of the output image (either 1 or 2). 73By default, the bit depth is 2 (two bits per pixel). 74.It Fl f , Fl Fl fix 75Fix the input PNG file to be a correctly indexed image. 76.It Fl F , Fl Fl fix-and-save 77Same as 78.Fl f , 79but additionally, the supplied command line parameters are saved within the PNG and will be loaded and automatically used next time. 80.It Fl h , Fl Fl horizontal 81Lay out tiles in column-major order (column by column), instead of the default row-major order (line by line). 82Especially useful for "8x16" OBJ mode, if the input image is 16 pixels tall. 83.It Fl m , Fl Fl mirror-tiles 84Truncate tiles by checking for tiles that are mirrored versions of others and omitting these from the output file. 85Useful with tilemaps and attrmaps together to keep track of the duplicated tiles and the dimension mirrored. 86Tiles are checked for horizontal, vertical, and horizontal-vertical mirroring. 87Implies 88.Fl u . 89.It Fl o Ar out_file , Fl Fl output Ar out_file 90The name of the output file. 91.It Fl p Ar pal_file , Fl Fl palette Ar pal_file 92Output 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. 93If the palette contains too few colors, the remaining entries are set to black. 94.It Fl P , Fl Fl output-palette 95Same as 96.Fl p , 97but the palette file output name is made by taking the input PNG file's filename, removing the file extension, and appending 98.Pa .pal . 99.It Fl t Ar tilemap , Fl Fl tilemap Ar tilemap 100Generate a file of tile indices. 101For each tile in the input file, a byte is written representing the index of the associated tile in the output file. 102Useful in combination with 103.Fl u 104or 105.Fl m 106to keep track of duplicate tiles. 107.It Fl T , Fl Fl output-tilemap 108Same as 109.Fl t , 110but the tilemap file output name is made by taking the input filename, removing the file extension, and appending 111.Pa .tilemap . 112.It Fl u , Fl Fl unique-tiles 113Truncate tiles by checking for tiles that are exact duplicates of others and omitting these from the output file. 114Useful with tilemaps to keep track of the duplicated tiles. 115.It Fl V , Fl Fl version 116Print the version of the program and exit. 117.It Fl v , Fl Fl verbose 118Verbose. 119Print errors when the command line parameters and the parameters in the PNG file don't match. 120.It Fl x Ar tiles , Fl Fl trim-end Ar tiles 121Trim the end of the output file by this many tiles. 122.El 123.Sh EXAMPLES 124The following will take a PNG file with a bit depth of 1, 2, or 8, and output planar 2bpp data: 125.Pp 126.D1 $ rgbgfx -o out.2bpp in.png 127.Pp 128The following creates a planar 2bpp file with only unique tiles, and its tilemap 129.Pa out.tilemap : 130.Pp 131.D1 $ rgbgfx -T -u -o out.2bpp in.png 132.Pp 133The following creates a planar 2bpp file with only unique tiles 134.Pa accounting for tile mirroring 135and its associated tilemap 136.Pa out.tilemap 137and attrmap 138.Pa out.attrmap : 139.Pp 140.D1 $ rgbgfx -A -T -m -o out.2bpp in.png 141.Pp 142The following will do nothing: 143.Pp 144.D1 $ rgbgfx in.png 145.Sh BUGS 146Please report bugs on 147.Lk https://github.com/gbdev/rgbds/issues GitHub . 148.Sh SEE ALSO 149.Xr rgbds 7 , 150.Xr rgbasm 1 , 151.Xr rgblink 1 , 152.Xr rgbfix 1 , 153.Xr gbz80 7 154.Sh HISTORY 155.Nm 156was created by 157.An stag019 158to be included in RGBDS. 159It is now maintained by a number of contributors at 160.Lk https://github.com/gbdev/rgbds . 161