{"id":41902737,"url":"https://github.com/drojaazu/chrgfx","last_synced_at":"2026-01-25T15:11:13.988Z","repository":{"id":42001438,"uuid":"153390322","full_name":"drojaazu/chrgfx","owner":"drojaazu","description":"Converts to and from tile based graphics from retro video game hardware","archived":false,"fork":false,"pushed_at":"2025-07-27T08:51:03.000Z","size":680,"stargazers_count":72,"open_issues_count":1,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-07-27T10:28:05.475Z","etag":null,"topics":["16bit","capcom","famicom","game-development","gameboy","graphics","megadrive","neogeo","nes","nintendo","nintendo-snes","retro-hardware-systems","retrogaming","sega","sega-genesis","sega-mega-drive","snes","snk"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drojaazu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-10-17T03:29:33.000Z","updated_at":"2025-07-27T08:51:07.000Z","dependencies_parsed_at":"2023-11-18T18:24:57.696Z","dependency_job_id":"e633033d-ef33-4cff-b4b8-c926c4b0e164","html_url":"https://github.com/drojaazu/chrgfx","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/drojaazu/chrgfx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drojaazu%2Fchrgfx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drojaazu%2Fchrgfx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drojaazu%2Fchrgfx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drojaazu%2Fchrgfx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drojaazu","download_url":"https://codeload.github.com/drojaazu/chrgfx/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drojaazu%2Fchrgfx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28754817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T13:59:49.818Z","status":"ssl_error","status_checked_at":"2026-01-25T13:59:33.728Z","response_time":113,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["16bit","capcom","famicom","game-development","gameboy","graphics","megadrive","neogeo","nes","nintendo","nintendo-snes","retro-hardware-systems","retrogaming","sega","sega-genesis","sega-mega-drive","snes","snk"],"created_at":"2026-01-25T15:11:13.409Z","updated_at":"2026-01-25T15:11:13.979Z","avatar_url":"https://github.com/drojaazu.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# chrgfx\nA library with CLI utilities for converting tile (aka CHR) based graphics used in retro video games to and from bitmap images, with support for a wide range of hardware via external graphics definitions. It is useful for viewing data as well as converting modern graphics into native formats for retro game development.\n\n## Building\n\nchrgfx requires libpng and the [png++](https://www.nongnu.org/pngpp/) wrapper for the support utilities. These are available in most distro repositories. Installing the wrapper will include libpng as a dependency. In Arch Linux, the wrapper package is `png++`; in Debian, it is `libpng++-dev`.\n\nIf you wish to build only libchrgfx without the utilities (and thus without the need for the png packages), pass `-DNO_UTILS=1` when running cmake.\n\nCMake is used for the build process. From the root of the project directory:\n\n    mkdir build \u0026\u0026 cd build\n    cmake ..\n    make\n    sudo make install\n\nNote that cmake installs library content to `/usr/local` by default, which is not included in the ld search path in some distros. If libchrgfx.so cannot be found, you may want to add `/usr/local/lib` to the search path using `ldconfig`, or manually specify the installation prefix, e.g.:\n\n    cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..\n\nManual uninstallation can be done using the install_manifest.txt file within the cmake build directory:\n\n    sudo xargs rm \u003c install_manifest.txt \n\n# Utilities\nThere are three support utilities included: `chr2png`, `png2chr`, and `palview`.\n\n## chr2png\n\nThis will convert encoded tile/palette data to a PNG image.\n \n## png2chr\n\nThis will take a sufficiently compatible PNG and output encoded tile/palette data.\n\nCompatible in this case means a PNG in indexed color mode with a 256 color palette.\n\n## palview\n\nThis will take a color palette and generate an image of color swatches corresponding to the palette.\n\n## Graphics Definitions (gfxdefs)\n\nThe conversion routines rely on graphics definitions (gfxdef), which describe the format of the data for encoding and decoding. There are three kinds of definitions: tile (chrdef), palette (paldef) and color (coldef).\n\nGraphics definitions can be mixed and modified at run time. With this system, chrgfx is extensible and can support practically any tile-based hardware.\n\nGraphics definitions are loaded from three possible sources.\n\n### Internal Definitions\n\nThe chrgfx library has a number of common, generic definitions included. Please see the [builtin_defs.hpp source file](src/chrgfx/builtin_defs.hpp) for a list.\n\n### gfxdefs File\n\nExternal graphics definitions are stored in the `gfxdefs` file. The project comes with a number of definitions for many common hardware systems already created in this file.\n\nPlease [see the readme in the gfxdef directory](share/README.md) and [the gfxdefs file itself](share/gfxdefs) for more details on the format.\n\n### CLI Definitions\n\nGraphics definitions can also be defined on the command line. This is useful for testing or dealing with dynamic formats (for example, perhaps tile sizes are not consistent across multiple files when running a batch conversion).\n\nDefinitions specified on the command line override definitions loaded from internal/external sources in a piecemeal fashion. For example, you may load the `col_bgr_222_packed` coldef and then specify `--col-big-endian` on the command line to change the endianness aspect only.\n\n### Hardware Profiles\n\nFor convenience, there are also profiles, which are groupings of a single chrdef, paldef and coldef to represent the graphics subsystem of a certain piece of hardware. In this way, it is simple for the user to specify which decoders/encoders to use for certain hardware. Moreover, we reduce redundancies for hardware that may share one type of definition, but not others.\n\nFor example, the Sega Master System and Game Gear have the same tile format, but the palette and color encodings are different. We can make a different profile for each system, with both using the same tile encoding but seperate palette and color encodings. Another example is the original Gameboy and the later Gameboy Pocket. They are exactly the same in hardware, but the original has a more green tint while the Pocket is more gray. We can create profiles for both, with the same tile and palette formats, but with a different color list to simulate their different perceived colors.\n\nThe entries within the profile can be override by specifying a chrdef, paldef or coldef ID seperately on the command line.\n\n### gfxdef Loading Order\n\nBecause definitions can be loaded from multiple sources, there is an ordering for processing to determine what definition is finally used:\n\n1. If a profile is specified, the external gfxdefs file is checked first to get the target chrdef/paldef/coldef from that profile.\n2. The internal list is checked for the target gfxdef.\n3. If not present in the internal list, the gfxdef file is checked for the target gfxdef. If a chrdef/paldef/coldef ID was specified and was not found at this point, an error occurs.\n4. If a tile or color definition option is specified on the command line, that modifes the definition\n\nNOTE: If a chrdef/paldef/coldef or profile ID was NOT specified, steps 1 to 3 are skipped and it is assumed all required gfxdefs are fully defined on the command line.\n\n## Usage\n\n### Shared Options\n\nThe following options are available for all three utilitiese (`chr2png`, `png2chr`, `palview`)\n\n`--help`, `-h`\n\nDisplay built in program usage\n\n`--gfx-def \u003cfilepath\u003e`, `-G \u003cfilepath\u003e`\n\nPath to gfxdef file. If not specified, it checks for:\n\n - `${XDG_DATA_HOME}/chrgfx/gfxdefs`\n - `${XDG_DATA_DIRS}/chrgfx/gfxdefs`\n\n`--profile \u003chardware_profile_id\u003e`, `-H \u003chardware_profile_id\u003e`\n\nSpecify hardware profile to use\n\n`--chr-def \u003ctile_encoding_id\u003e`, `-T \u003ctile_encoding_id\u003e`\n\n`--col-def \u003ccolor_encoding_id\u003e`, `-C \u003ccolor_encoding_id\u003e`\n\n`--pal-def \u003cpalette_encoding_id\u003e`, `-P \u003cpalette_encoding_id\u003e`\n\nThese arguments specify the tile, color and palette encoding, respectively. They are only required if a graphics profile was not specified. If they are used in conjunction with a graphics profile, they will override that particular encoding. (For example, using `--chr-def` will override the tile encoding that was specified in the profile.)\n\nPlease [see the readme in the gfxdef directory](share/README.md) for more information about values represent in a gfxdef.\n\nThe following options are used to build or modify a gfxdef:\n\n`--chr-width \u003cinteger\u003e`\n\nSpecify the width of a tile\n\n`--chr-height \u003cinteger\u003e`\n\nSpecify the height of a tile\n\n`--chr-bpp \u003cinteger\u003e`\n\nSpecify the bits per pixel (BPP) of a tile\n\n`--chr-plane-offsets \u003cp0,p1,p2...|[start:count:step]\u003e`\n\nSpecify the offset (in bits) to the start of each plane within a pixel.\n\nThis is written as either a comma-delimted list of values, or as a range in the format of [start:count:step]. Please [see the readme in the gfxdef directory](share/README.md) for more about this option and list/range formatting.\n\nThe number of entries should match the bits per pixel value for the tile.\n\n`--chr-pixel-offsets \u003cp0,p1,p2...|[start:count:step]\u003e`\n\nSpecify the start (in bits) to the start of each pixel within a row.\n\nValue is specified in the same format as `--chr-plane-offsets`.\n\nThe number of entries should match the width of the tile.\n\n`--chr-row-offsets \u003cr0,r1,r2...|[start:count:step]\u003e`\n\nSpecify the offset (in bits) to the start of each pixel row within a tile.\n\nValue is specified in the same format as `--chr-plane-offsets`.\n\nThe number of entries should match the height of the tile.\n\n`--pal-datasize \u003cinteger\u003e`\n\nSpecify the size (in bits) of one palette.\n\nThis is optional when defining a palette and should rarely be needed. It is only necessary when the size of palette differs entry datasize * palette length. For example, if a color entry is 2 bits with a palette length of 4, but the palette is stored in a 16 bit value. In such a case, the `--pal-datasize` should be 16.\n\n`--pal-entry-datasize \u003cinteger\u003e`\n\nSpecify the size (in bits) of a color entry.\n\n`--pal-length \u003cinteger\u003e`\n\nSpecify the number of entries in a single palette.\n\n`--col-bitdepth \u003cinteger\u003e`\n\nSpecify the bitdepth of a color.\n\n`--col-layout \u003cred_offset,red_size,green_offset,green_size,blue_offset,blue_size\u003e`\n\nSpecify the groupings of red, green and blue color channels within a color value. This should be a comma delimited list of exactly 6 entries, in this format: red_offset, red_size, green_offset, green_size, blue_offset, blue_size\n\nNote that, for simplicity's sake, only one layout pass can be done via the command line. If you need to work with a complex color format that requires multiple layout passes, please use an external file (gfxdefs).\n\n`--col-big-endian \u003c1|0|true|false\u003e`\n\nSpecify that the color data is big-endian. Data is processed as little-endian by default.\n\n### chr2png - Additional Options\n\n`--chr-data \u003cfilepath\u003e`, `-c \u003cfilepath\u003e`\n\nRequired; path to the encoded tile data\n\n`--pal-data \u003cfilepath\u003e`, `-p \u003cfilepath\u003e`\n\nPath to the encoded palette data; if not specified, a palette of random colors will be generated\n\n`--output \u003cfilepath\u003e`, `-o \u003cfilepath\u003e`\n\nPath to output PNG image; if not specifed, will output to stdout\n\n`--pal-line \u003cinteger\u003e`, `-l \u003cinteger\u003e`\n\nSpecify the palette line (also called the subpalette) to use for rendering when passing in palette data that contains more tha one palette\n\n`--row-size \u003cinteger\u003e`, `-r \u003cinteger\u003e`\n\nSpecify the number of tiles in a row in the output PNG\n\n`--trns-index \u003cinteger\u003e`, `-i \u003cinteger\u003e`\n\nSpecify a palette index to use for transparency. This is often index 0. If not specified, the output image will not have transparency.\n\n### Example Usage\n    chr2png --profile sega_md --chr-data sonic1_sprite.chr --pal-data sonic1.cram --trns --row-size 32 \u003e sonic1_sprite.png\n\n## png2chr - Additional Options\n\n`--png-data \u003cfilepath\u003e`, `-b \u003cfilepath\u003e` \n\nPath to the input PNG image; if not specified, expects PNG data piped from stdin\n\n`--chr-output \u003cfilepath\u003e`, `-c \u003cfilepath\u003e`\n\n`--pal-output \u003cfilepath\u003e`, `-p \u003cfilepath\u003e`\n\nPath to the output tile and palette data, respectively. One or both must be specified.\n\n### Example\n    png2chr --profile nintendo_sfc --chr-output crono.chr --pal-output crono.pal \u003c crono_sprite.png\n\n### palview - Additional Options\n\nImages are generated with indexed color, unless `--full-pal` is specified, in which case direct color is used.\n\n`--pal-data \u003cfilepath\u003e`, `-p \u003cfilepath\u003e`\n\nPath to the encoded palette data; if not specified, a palette of random colors will be generated\n\n`--pal-line \u003cinteger\u003e`, `-l \u003cinteger\u003e`\n\nSpecify the palette line (also called the subpalette) to use for rendering when passing in palette data that contains more tha one palette.\n\nIgnored when `--full-pal` is specified.\n\n`--full-pal`, `-f`\n\nRenders an image with multiple palettes. It will draw as many palettes as the data provided contains.\n\n`--output \u003cfilepath\u003e`, `-o \u003cfilepath\u003e`\n\nPath to output PNG image; if not specifed, will output to stdout\n\n### Example Usage\n\n## Special Thanks\n\nSpecial thanks to:\n\n- Klarth, for his venerable `consolegfx.txt`, which was my introduction to the data side of tiled graphics and was instrumental in my early development work on Dumpster and now chrgfx.\n\n- The MAME Team, for their work in documenting hardware through source code and for inspiring some solutions that are essential to chrgfx.\n\n- UCC BLACK canned coffee.\n\n- Greetz to dosdemon, mdl, sebmal, lord, eri, freem and the rest of the internet graybeards from IRC and the old scene.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrojaazu%2Fchrgfx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrojaazu%2Fchrgfx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrojaazu%2Fchrgfx/lists"}