1RGBGFX(1) BSD General Commands Manual RGBGFX(1)
2
4 rgbgfx — Game Boy graphics converter
5
7 rgbgfx [-CmuVZ] [-v [-v ...]] [-a attrmap | -A] [-b base_ids]
8 [-c color_spec] [-d depth] [-L slice] [-N nb_tiles] [-n nb_pals]
9 [-o out_file] [-p pal_file | -P] [-q pal_map | -Q] [-r stride]
10 [-s nb_colors] [-t tilemap | -T] [-x quantity] file
11
13 The rgbgfx program converts PNG images into data suitable for display on
14 the Game Boy and Game Boy Color, or vice-versa.
15 The main function of rgbgfx is to divide the input PNG into 8×8 pixel
17 squares, convert each of those squares into 1bpp or 2bpp tile data, and
18 save all of the tile data in a file. It also has options to generate a
19 tile map, attribute map, and/or palette set as well; more on that and how
20 the conversion process can be tweaked below.
21
23 Note that options can be abbreviated as long as the abbreviation is unam‐
24 biguous: --verb is --verbose, but --ver is invalid because it could also
25 be --version.
26 rgbgfx accepts decimal, binary, and hexadecimal numbers in option argu‐
28 ments. Decimal numbers are written as usual; binary numbers must be pre‐
29 fixed with either ‘%’ or ‘0b’, and hexadecimal numbers must be prefixed
30 with either ‘$’ (which will likely need escaping or quoting to avoid be‐
31 ing interpreted by the shell), or ‘0x’. Leading zeros (after the base
32 prefix, if any) are accepted, and letters are not case-sensitive. All of
33 these are equivalent: ‘42’, ‘042’, ‘0b00101010’, ‘0B101010’, ‘0x2A’,
34 ‘0X2A’, ‘0x2a’.
35 Unless otherwise noted, passing ‘-’ (a single dash) as a file name makes
37 rgbgfx use standard input (for input files) or standard output (for out‐
38 put files). To suppress this behavior, and open a file in the current
39 directory actually called ‘-’, pass ‘./-’ instead. Using standard input
40 or output more than once in a single command will likely produce unex‐
41 pected results.
42 The following options are accepted:
44 -a attrmap, --attr-map attrmap
46 Generate an attribute map, which is a file containing tile
47 “attributes”. For each square of the input image, its corre‐
48 sponding attribute map byte contains the mirroring bits (if -m
49 was specified), the bank bit (see -N), and the palette index.
50 See Pan Docs: https://gbdev.io/pandocs/Tile_Maps#bg-map-
51 attributes-cgb-mode-only for the individual bytes' format. The
52 output is written just like the tile map (see -t), follows the
53 same order (-Z), and has the same size.
54 -A, --output-attr-map
56 Same as -a path, where path is the input image's path with the
57 extension set to .attrmap.
58 -b base_ids, --base-tiles base_ids
60 Set the base IDs for tile map output. base_ids should be one or
61 two numbers between 0 and 255, separated by a comma; they are for
62 bank 0 and bank 1 respectively. Both default to 0.
63 -C, --color-curve
65 When generating palettes, use a color curve mimicking the Game
66 Boy Color's screen. The resulting colors may look closer to the
67 input image's on hardware and accurate emulators.
68 -c color_spec, --colors color_spec
70 Use the specified color palettes instead of having rgbgfx auto‐
71 matically determine some. color_spec can be one of the follow‐
72 ing:
73 inline palette spec
75 If color_spec begins with a hash character ‘#’, it is
76 treated as an inline palette specification. It should
77 contain a comma-separated list of hexadecimal colors,
78 each beginning with a hash. Colors in are accepted ei‐
79 ther as ‘#rgb’ or ‘#rrggbb’ format. Palettes must be
80 separated by a colon or semicolon (the latter may require
81 quoting to avoid special handling by the shell), and spa‐
82 ces are allowed around colons, semicolons and commas;
83 trailing commas and semicolons are allowed. See EXAMPLES
84 for an example of an inline palette specification.
85 embedded palette spec
87 If color_spec is the case-insensitive word embedded, then
88 the first four colors of the input PNG's embedded palette
89 are used. It is an error if the PNG is not indexed, or
90 if colors other than these 4 are used. (This is
91 different from the default behavior of indexed PNGs, as
92 then unused entries in the embedded palette are ignored,
93 whereas they are not with -c embedded).
94 external palette spec
96 Otherwise, color_spec is assumed to be an external pal‐
97 ette specification. The expected format is
98 ‘format:path’, where path is a path to a file (‘-’ is not
99 treated specially), which will be processed according to
100 the format. See PALETTE SPECIFICATION FORMATS for a list
101 of formats and their descriptions.
102 -d depth, --depth depth
104 Set the bit depth of the output tile data, in bits per pixel
105 (bpp), either 1 or 2 (the default). This changes how tile data
106 is output, and the maximum number of colors per palette (2 and 4
107 respectively).
108 -L slice, --slice slice
110 Only process a given rectangle of the image. This is useful for
111 example if the input image is a sheet of some sort, and you want
112 to convert each cel individually. The default is to process the
113 whole image as-is.
114 slice must be two number pairs, separated by a colon. The num‐
116 bers must be separated by commas; space is allowed around all
117 punctuation. The first number pair specifies the X and Y coordi‐
118 nates of the top-left pixel that will be processed (anything
119 above it or to its left will be ignored). The second number pair
120 specifies how many tiles to process horizontally and vertically,
121 respectively.
122 -L is ignored in reverse mode, no padding is inserted.
124 -m, --mirror-tiles
126 Deduplicate tiles that are mirrors of each other. Tiles are
127 checked for horizontal, vertical, and horizontal-vertical mirror‐
128 ing. Useful with a tile map and attribute map together to keep
129 track of the duplicated tiles and the dimension(s) mirrored. Im‐
130 plies -u.
131 -N nb_tiles, --nb-tiles nb_tiles
133 Set a maximum number of tiles that can be placed in each VRAM
134 bank. nb_tiles should be one or two numbers between 0 and 256,
135 separated by a comma; if the latter is omitted, it defaults to 0.
136 Setting either number to 0 prevents any tiles from being output
137 in that bank.
138 If more tiles are generated than can fit in the two banks com‐
140 bined, rgbgfx will abort. If -N is not specified, no limit will
141 be set on the amount of tiles placed in bank 0, and tiles will
142 not be placed in bank 1.
143 -n nb_pals, --nb-palettes nb_pals
145 Abort if more than nb_pals palettes are generated. This may not
146 be more than 256.
147 Note that attribute map output only has 3 bits for the palette
149 ID, so a limit higher than 8 may yield incomplete data unless re‐
150 lying on a palette map (see -q).
151 -o out_file, --output out_file
153 Output the tile data in native 2bpp format or in 1bpp (depending
154 on -d) to this file.
155 -p pal_file, --palette pal_file
157 Output the image's palette set to this file.
158 -P, --output-palette
160 Same as -p path, where path is the input image's path with the
161 extension set to .pal.
162 -q pal_file, --palette-map pal_file
164 Output the image's palette map to this file. This is useful if
165 the input image contains more than 8 palettes, as the attribute
166 map only contains the lower 3 bits of the palette indices.
167 -Q, --output-palette-map
169 Same as -q path, where path is the input image's path with the
170 extension set to .palmap.
171 -r width, --reverse width
173 Switches rgbgfx into “reverse” mode. In this mode, instead of
174 converting a PNG image into Game Boy data, rgbgfx will attempt to
175 reverse the process, and render Game Boy data into an image. See
176 REVERSE MODE below for details.
177 width is the image's width, in tiles (including any margins
179 specified by -L).
180 -s nb_colors, --palette-size nb_colors
182 Specify how many colors each palette contains, including the
183 transparent one if any. nb_colors cannot be more than ‘1 <<
184 depth’ (see -d).
185 -t tilemap, --tilemap tilemap
187 Generate a file of tile indices. For each square of the input
188 image, its corresponding tile map byte contains the index of the
189 associated tile in the tile data file. The IDs wrap around from
190 255 back to 0, and do not include the bank bit; use -a for that.
191 Useful in combination with -u and/or -m to keep track of dupli‐
192 cate tiles.
193 -T, --output-tilemap
195 Same as -t path, where path is the input image's path with the
196 extension set to .tilemap.
197 -u, --unique-tiles
199 Deduplicate identical tiles, and omit the duplicates from the
200 tile data file. Useful with a tile map (see -t) to keep track of
201 the duplicated tiles.
202 Note that if this option is enabled, no guarantee is made on the
204 order in which tiles are output; while it should be consistent
205 across identical runs of a given rgbgfx release, the same is not
206 true for different releases.
207 -V, --version
209 Print the version of the program and exit.
210 -v, --verbose
212 Be verbose. The verbosity level is increased by one each time
213 the flag is specified, with each level including the previous:
214 1. rgbgfx prints out its configuration before doing anything.
215 2. A generic message is printed before doing most actions.
216 3. Some of the actions' intermediate results are printed.
217 4. Some internal debug printing is enabled.
218 The verbosity level does not go past 6.
219 Note that verbose output is only intended to be consumed by hu‐
221 mans, and may change without notice between RGBDS releases; rely‐
222 ing on those for scripts is not advised.
223 -x quantity, --trim-end quantity
225 Do not output the last quantity tiles to the tile data file; no
226 other output is affected. This is useful for trimming “filler” /
227 blank squares at the end of an image. If fewer than quantity
228 tiles would have been emitted, the file will be empty.
229 Note that this is done after deduplication if -u was enabled, so
231 you probably don't want to use this option in combination with
232 -u. Note also that the tiles that don't get output will not
233 count towards -N's limit.
234 -Z, --columns
236 Read squares from the PNG in column-major order (column by col‐
237 umn), instead of the default row-major order (line by line).
238 This primarily affects tile map and attribute map output, al‐
239 though it may also change generated tile data and palettes.
240 At-files
242 In a given project, many images are to be converted with different flags.
243 The traditional way of solving this problem has been to specify the dif‐
244 ferent flags for each image in the Makefile / build script; this can be
245 inconvenient, as it centralizes all those flags away from the images they
246 concern.
247 To avoid these drawbacks, rgbgfx supports “at-files”: any command-line
249 argument that begins with an at sign (‘@’) is interpreted as one. The
250 rest of the argument (without the @, that is) is interpreted as the path
251 to a file, whose contents are interpreted as if given on the command
252 line. At-files can be stored right next to the corresponding image, for
253 example:
254 $ rgbgfx -o image.2bpp -t image.tilemap @image.flags image.png
256 This will read additional flags from file ‘image.flags’, which could con‐
258 tains for example ‘-b 128’ to specify a base offset for the image's
259 tiles. The above command could be generated from the following make(1)
260 rule, for example:
261 %.2bpp %.tilemap: %.flags %.png
263 rgbgfx -o $*.2bpp -t $*.tilemap @$*.flags $*.png
264 Since the contents of at-files are interpreted by rgbgfx, no shell
266 processing is performed; for example, shell variables are not expanded
267 (‘$PWD’, ‘%WINDIR%’, etc.). In at-files, lines that are empty or contain
268 only whitespace are ignored; lines that begin with a hash sign (‘#’), op‐
269 tionally preceded by whitespace, are considered comments and also ig‐
270 nored. Each line can contain any number of arguments, which are sepa‐
271 rated by whitespace. (No quoting feature to prevent this is provided.)
272 Note that a leading ‘@’ has no special meaning on option arguments, and
274 that the standard ‘--’ to stop option processing also disables at-file
275 processing. For example, the following command line reads command-line
276 options from ‘tilesets/town.flags’ then ‘tilesets.flags’, but processes
277 ‘@tilesets/town.png’ as the input image and outputs tile data to
278 ‘@tilesets/town.2bpp’:
279 $ rgbgfx -o @tilesets/town.2bpp @tilesets/town.flags
281 @tilesets.flags -- @tilesets/town.png
282 At-files can also specify the input image directly, and call for more at-
284 files, both using the regular syntax. Note that while ‘--’ can be used
285 in an at-file (with identical semantics), it is only effective inside of
286 it—normal option processing continues in the parent scope.
287
289 The following formats are supported:
290 act Adobe Photoshop color table: https://www.adobe.com/devnet-
292 apps/photoshop/fileformatashtml/#50577411_pgfId-1070626
293 aco Adobe Photoshop color swatch: https://www.adobe.com/devnet-
295 apps/photoshop/fileformatashtml/#50577411_pgfId-1055819
296 gbc A GBC palette memory dump, as emitted by rgbgfx -p. Useful to
298 force several images to share the same palette.
299 gpl GIMP palette: https://docs.gimp.org/2.10/en/gimp-concepts-
301 palettes.html
302 hex Plaintext lines of hexadecimal colors in ‘rrggbb’ format.
304 psp Paint Shop Pro palette:
306 https://www.selapa.net/swatches/colors/fileformats.php#psp_pal
307 If you wish for another format to be supported, please open an issue (see
309 BUGS below) or contact us, and supply a few sample files.
310
312 rgbgfx must generate palettes from the colors in the input image, unless
313 -c was used; in that case, the provided palettes will be used. If the
314 order of colors in the palettes is important to you, for example because
315 you want to use palette swaps, please use -c to specify the palette ex‐
316 plicitly.
317 First, if the image contains any transparent pixel, color #0 of all pal‐
319 ettes will be allocated to it. This is done even if palettes were
320 explicitly specified using -c; then the specification only covers color
321 #1 onwards. (If you do not want this, ask your image editor to remove
322 the alpha channel.)
323 After generating palettes, rgbgfx sorts colors within those palettes us‐
325 ing the following rules:
326 • If the PNG file internally contains a palette (often dubbed an
328 “indexed” PNG), then colors in each output palette will be
329 sorted according to their order in the PNG's palette. Any un‐
330 used entries will be ignored, and only the first entry is con‐
331 sidered if there are any duplicates. (If you want a given
332 color to appear more than once, or an unused color to appear at
333 all, you should specify the palettes explicitly instead using
334 -c; -c embedded may be appropriate.)
335 • Otherwise, if the PNG only contains shades of gray, they will
337 be categorized into as many “bins” as there are colors per pal‐
338 ette, and the palette is set to these bins. The darkest gray
339 will end up in bin #0, and so on; note that this is the oppo‐
340 site of the RGB method below. If two distinct grays end up in
341 the same bin, the RGB method is used instead.
342 Be careful that rgbgfx is picky about what it considers
344 “grays”: the red, green, and blue components of each color must
345 all be exactly the same.
346 • If none of the above apply, colors are sorted from lightest
348 (first) to darkest (last). The definition of luminance that
349 rgbgfx uses is “2126×red+7152×green+722×blue”.
350 Note that the “indexed” behavior depends on an internal detail of how the
352 PNG is saved, specifically its ‘PLTE’ chunk. Since few image editors
353 (such as GIMP) expose that detail, this behavior is only kept for compat‐
354 ibility and should be considered deprecated.
355
357 All files output by rgbgfx are binary files, and designed to follow the
358 Game Boy and Game Boy Color's native formats. What follows is succinct
359 descriptions of those formats, including rgbgfx-specific details. For
360 more complete, beginner-friendly descriptions of the native formats with
361 illustrations, please check out Pan Docs:
362 https://gbdev.io/pandocs/Rendering
363 Tile data
365 Tile data is output like a binary dump of VRAM, with no padding between
366 tiles. Each tile is 16 bytes, 2 per row of 8 pixels; the bits of color
367 IDs are split into each byte (or “bitplane”). The leftmost pixel's color
368 ID is stored in the two bytes' most significant bits, and the rightmost
369 pixel's color ID in their least significant bits.
370 When the bit depth (-d) is set to 1, the most significant bitplane (sec‐
372 ond byte) of each row, being all zeros, is simply not output.
373 Palette data
375 Palette data is output like a dump of palette memory. Each color is
376 written as GBC-native little-endian RGB555, with the unused bit 15 set to
377 0. There is no padding between colors, nor between palettes; however,
378 empty colors in the palettes are output as 0xFFFF. For example, if 5
379 palettes are generated with -s 4, the palette data file will be 2×4×5=40
380 bytes long, even if some palettes contain less than 3 colors. Note that
381 -n only caps how many palettes are generated (and thus this file's size),
382 but fewer may be generated still.
383 Tile map data
385 A tile map is an array of tile IDs, with one byte per tile ID. The first
386 byte always corresponds to the ID of the tile in top-left corner of the
387 input image; the second byte is either the ID of the tile to its right
388 (by default), or below it (with -Z); and so on, continuing in the same
389 direction. Rows / columns (respectively) are stored consecutively, with
390 no padding.
391 Attribute map data
393 Attribute maps mirror the format of tile maps, like on the GBC, espe‐
394 cially the order in which bytes are output. The contents of individual
395 bytes follows the GBC's native format:
396 Bit 7 BG-to-OAM Priority Set to 0
398 Bit 6 Vertical Flip 0=Normal, 1=Mirror vertically
399 Bit 5 Horizontal Flip 0=Normal, 1=Mirror horizontally
400 Bit 4 Not used Set to 0
401 Bit 3 Tile VRAM Bank number 0=Bank 0, 1=Bank 1
402 Bit 2–0 Background Palette number BGP0-7
403 Note that if more than 8 palettes are used, only the lowest 3 bits of the
405 palette ID are output.
406
408 rgbgfx can produce a PNG image from valid data. This may be useful for
409 ripping graphics, recovering lost source images, etc. An important
410 caveat on that last one, though: the conversion process is lossy both
411 ways, so the “reversed” image won't be perfectly identical to the
412 original—but it should be close to a Game Boy's output. (Keep in mind
413 that many of consoles output different colors, so there is no true
414 reference rendering.)
415 When using reverse mode, make sure to pass the same flags that were given
417 when generating the data, especially -C, -d, -N, -s, -x, and -Z.
418 “At-files” may help with this. rgbgfx will warn about any inconsisten‐
419 cies it detects.
420 Files that are normally outputs (-a, -p, -t) become inputs, and file will
422 be written to instead of read from, and thus needs not exist beforehand.
423 Any of these inputs not passed is assumed to be some default:
424 palettes Unspecified palette data makes rgbgfx assume DMG (mono‐
426 chrome Game Boy) mode: a single palette of 4 grays. It
427 is possible to pass palettes using -c instead of -p.
428 tile data Tile data must be provided, as there is no reasonable
429 assumption to fall back on.
430 tile map A missing tile map makes rgbgfx assume that tiles were
431 not deduplicated, and should be laid out in the order
432 they are stored.
433 attribute map Without an attribute map, rgbgfx assumes that no tiles
434 were mirrored.
435
437 Some flags have had their functionality removed. -D, -f, and -F are now
438 ignored, and -h is an alias for the new (and less confusingly named) -Z.
439 These will be removed and/or repurposed in future versions of rgbgfx, so
440 relying on them is not recommended. The same applies to the correspond‐
441 ing long options.
442 If you are curious, you may find out that palette generation is an NP-
444 complete problem, so rgbgfx does not attempt to find the optimal solu‐
445 tion, but instead to find a good one in a reasonable amount of time. It
446 is possible to compute the optimal solution externally (using a solver,
447 for example), and then provide it to rgbgfx via -c.
448
450 The following will only validate the PNG (check its size, that all tiles
451 have a suitable amount of colors, etc.), but output nothing:
452 $ rgbgfx src/res/maps/overworld/tileset.png
454 The following will convert the image using the two given palettes (and
456 only those), and store the generated 2bpp tile data in ‘tileset.2bpp’,
457 and the attribute map in ‘tileset.attrmap’.
458 $ rgbgfx -c '#ffffff,#8d05de, #dc7905,#000000; #fff,#8d05de,
460 #7e0000 , #000' -A -o tileset.2bpp tileset.png
461 TODO: more examples.
463
465 Please report bugs and mistakes in this man page on GitHub:
466 https://github.com/gbdev/rgbds/issues Bug reports and feature requests
467 about RGBDS are also welcome!
468
470 rgbds(7), rgbasm(1), rgblink(1), rgbfix(1), gbz80(7)
471 The Game Boy hardware reference Pan Docs:
473 https://gbdev.io/pandocs/Rendering.html, particularly the section about
474 graphics.
475
477 rgbgfx was originally created by stag019 to be included in RGBDS. It was
478 later rewritten by ISSOtm, and is now maintained by a number of contribu‐
479 tors at https://github.com/gbdev/rgbds
480BSD March 28, 2021 BSD