From: jwalz Date: Sat, 5 Jan 2002 21:06:02 +0000 (+0000) Subject: *** empty log message *** X-Git-Tag: MOVE2GIT~3567 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=84c9a476334f5be307a562140cf878c4dbdd2d9d;p=nethack *** empty log message *** --- diff --git a/win/share/tile.doc b/win/share/tile.doc new file mode 100644 index 000000000..a6d8f58e9 --- /dev/null +++ b/win/share/tile.doc @@ -0,0 +1,140 @@ +Window ports can optionally make use of the tiles (pictures for NetHack +symbols) found in this directory. They are distributed in a text format +with routines to help in converting them to a system's preferred format +and using them there. The original tiles were provided by Warwick Allison. + +The tile distribution format for monsters.txt, objects.txt, and other.txt +starts with a palette header like: + +A = (0, 0, 0) +... +P = (254, 254, 254) + +and then each tile has an entry like: + +# tile 292 (comment identifying tile) +{ + AAAAGHPAAAAACDAA + AAAFGDEMLOCNAAAA +... +} + +Each port can convert these .txt files to whatever format it wants the +game executable to use, probably providing only one merged output file. +See the tilemap.c discussion at the bottom for more hints on adding tiles. + + +Shared code provided for conversion utilities: + +tile.h contains shared declarations. + +tiletext.c defines the external variables from tile.h and supplies +the external routines for reading and writing the defined text format. + +Each conversion utility is expected to use tiletext.c and provide code of +its own for reading and/or writing another format. The important global +variables implement a colormap shared between tiletext.c and the other +half of utilities. As an example of conversion utilities, we provide +txt2ppm (tiletext.c + ppmwrite.c) and gif2txt (tiletext.c + gifread.c). +(Sorry, we're not paying Unisys patent royalties for the right to provide +you with a gifwrite.c, which would necessarily use the LZW compression +algorithm they claim.) + +The text I/O routines are: + +boolean fopen_text_file(const char *filename, const char *type); + select file for subsequent tile I/O + "type" a la fopen + returns FALSE if file not opened, otherwise reads/writes header + (including colormap) and sets up to decode/encode tiles +int fclose_text_file(); + close file +boolean read_text_tile(pixel[TILE_Y][TILE_X]); + returns FALSE if no next tile in current file + otherwise TRUE and insert the tile in the provided array +boolean write_text_tile(pixel[TILE_Y][TILE_X]); + writes tile + +There are two additional shared routines provided for writers: + +void init_colormap(); + initialize the output colormap from the input one + must be called before opening output file as colormap is part of header +void merge_colormap(); + merge the current input colormap into the output one + +Due to the amount of state being kept, only one text or gif file can be +open at a time. If you are combining multiple files into one other-format +file with a single common colormap, you may need to open each source file +and merge their colormaps into a common colormap before processing any tiles. + +Although there are expected to be only 16 colors in the distribution tiles, +conversion programs should be prepared to accept up to MAXCOLORMAPSIZE +colors and map them to a smaller number if their port requires it. + + +Expected sequence for editing tiles: + edit foo.txt + + -or- + + run txt2ppm foo.txt foo.ppm + convert ppm to gif, either via ppmtogif from pbmplus/netpbm or + stripping the first 15 bytes of foo.ppm (containing the + size of the image) and feeding the rest to any raw-24bit- + image-reading program + edit tiles with gif-editing program + run gif2txt foo.gif foo.txt + + +When converted to ppm, monsters.ppm, objects.ppm, and other.ppm are: + each a single ppm format (rgb triples with header) + 20 tiles across, however many down (need "blank" tile to fill in + extras on last row -- currently alternating pixels in + first and second colors) + allows looking at tiles en masse for comparison or whatever + +The gif reading routines accept further variations so long as the gif is +n*TILE_X pixels across. + +The gif I/O routines are: + +boolean fopen_gif_file(const char *filename, const char *type); + select file for subsequent tile I/O + "type" a la fopen + returns FALSE if file not opened, otherwise reads gif header + (including colormap) and sets up to decode tiles +int fclose_gif_file(); + tear down decode mechanism + close file +boolean read_gif_tile(pixel[TILE_Y][TILE_X]); + returns FALSE if no next tile in current file (including when any + remaining tiles are "blank"), + otherwise TRUE and insert the tile in the provided array + + +Array provided by shared code for NetHack use, by compiling and running +tilemap.c to form tile.c: + +short glyph2tile[MAXGLYPH]; + maps glyph number to tile number for display purposes, assuming + (non-blank) tiles are numbered sequentially through + monsters/objects/other + +tilemap.c (shudder) accounts for things disappearing due to compilation +options -- there should be a tile for everything appearing under any +supported option, but under some options some tiles won't be referenced. +Therefore, tilemap.c has the knowledge to provide the comments for gif2txt +and is compiled with GIF2TXT to link in there, along with the various +strings for things that are compiled in (monst.o etc.). + +If you add monsters/objects/other things to NetHack and need to add tiles +to go with them, just add an entry in the right place in the appropriate +.txt file, and one to tilemap.c if the new item is conditionally compiled. +While the "comment identifying tile" in the .txt file must be correct, +the number of the tile need not be, and can just be a duplicate of the +tile on either side (or any other integer, for that matter). In an +official release, the tiles in a .txt file will be numbered consecutively +so that you may cross-reference with a graphics format, but the conversion +code does not care about the numbering. (In fact, running txt2ppm, ppmtogif, +and gif2txt gives you a consecutively numbered version of the .txt file.)