patchbmp - Bitmap File Patching Utility ===== ABOUT ===== "patchbmp" is a utility for patching bitmap files: i.e., to update selected portions of (usually large) 'base' bitmaps by merging areas from (usually smaller) 'patch' bitmaps - resulting in a new version of the base bitmaps. A 'patch script' specifies the files to be operated on and the regions to be merged. The intention is to store or distribute updated versions of large bitmaps by way of the smaller patch bitmaps and scripts, rather than the new bitmaps in their entirety. This is also useful when the base bitmaps or their partially modified versions are not redistributable due to licensing reasons. A single patch script can be used to load, patch and save a number of bitmaps. Rectangular ranges of pixels can be transferred from a patch bitmap to a base bitmap. For bitmaps that contain a matrix of smaller 'tile' images, indices into the tile matrix may be specified instead of pixel co-ordinates, after first specifying the layout of tiles in the bitmap. Currently only 24-BPP and 8-BPP uncompressed .bmp files are supported. The base and patch bitmaps should be of the same format. For 8-BPP bitmaps, the palettes should also be identical, as the program directly operates on bytes without translating palette indices. Although this is a general-purpose utility, it was developed for the purpose of distributing modified graphics for the game "Tile World", which is a re-incarnation of the game "Chip's Challenge". ============ INSTALLATION ============ The program is a simple stand-alone application; the executable may be copied to any desired location. Building from Source -------------------- Using a command-line compiler, the executable can usually be built with a single command, e.g.:- g++ -o patchbmp *.cpp If using a project-based IDE, create a project for a console application called patchbmp, add all the source files to it and build the executable. ===== USAGE ===== patchbmp patchScriptFileName The program should be invoked by specifying the filename of the patch script on the command-line. There are currently no command-line options. The filenames in the script usually refer to files using relative paths, which will be resolved w.r.t. the current working directory. Hence, the command should generally be executed from the directory containing the input .bmp files. =================== PATCH SCRIPT SYNTAX =================== The patch script is a plain-text file containing one command per line. Commands are case-insensitive. Words in a command are delimited by spaces or tabs; any extra white space is ignored. C++-style comments beginning with "//" may appear on any line. Any sort of error causes execution of the script to terminate with an error message. The program maintains a memory buffer each for one base bitmap and one patch bitmap. A bitmap file can be loaded into each. Commands for merging pixels update the base buffer contents using the patch buffer contents: this happens in-memory and does not affect the original files. A different bitmap file could be loaded into either buffer at any time. So after loading one base bitmap file, a number of patch bitmap file loading and merging operations could follow - in order to update the base bitmap using portions from multiple patch bitmaps. The updated base buffer should then be saved to a file. A new base bitmap may then be loaded, patched and saved, etc. When working with tiles, the size of the tiles (common to both buffers) needs to be specified. In addition, a set of values called 'tile specs' that describe the layout of spaced-out tiles can be specified (independently for each buffer). All these values can be changed at any point and will be used in all subsequent tile-merging operations. Loading a new bitmap does NOT cause any of these values to be reset. Commands -------- load {base|patch} Loads a bitmap file into the specified buffer. It is acceptable to load the same file into both buffers, if required. save Saves the base buffer to a bitmap file. If the file already exists, the user will be prompted, and may choose not to overwrite it. tilesize [] Specifies the tile size in pixels. The height may be omitted for a square w x w tile. Initially set to 1 x 1. tilespecs {base|patch} [ [ [ [ [ []]]]]] Sets the tile specs for the specified buffer. All values are in pixels. Omitted arguments leave the respective current values unchanged. Initially set to all 0's. In the simple case of all 0's, the bitmap consists of a matrix of contiguous tiles - each of size w x h - starting from (0,0). (dx0,dy0) specify a different top-left origin for the matrix. When the tiles are not contiguous but equally spaced out, (dx1,dy1) and (dx2,dy2) specify the top-left and bottom-right margins for a tile inside each 'block' of size (dx1+w+dx2) x (dy1+h+dy2) within the matrix. Only the w x h tile portions are operated on when merging tiles. The tile specs are used only for tile-based merging, and are completely irrelevant when specifying raw pixel co-ordinates. merge {pixels|tiles} [ [ [ [ [ [ [ []]]]]]]] Transfers a range of pixels or tiles from the patch buffer to the base buffer: either overwriting the base pixels or merging with them using a specified bit-wise operation. The operations that can be specified by op are:- op operation -- --------- = copy & AND | OR ^ XOR For paletted 8-BPP bitmaps, the program operates on the palette indices untranslated; so except in case of a grayscale (or similarly monotonic) palette, only copying is mostly meaningful. dx, dy, sx, sy, w and h describe the regions to be merged. For pixels, values are in terms of 0-based (x,y) co-ordinates and pixel widths/heights. For tiles, values are in terms of 0-based (col,row) indices and number of columns/rows. (dx,dy) specify the destination position. Defaults: (0,0) (sx,sy) specify the source position. Defaults: (dx,dy) w x h specify the size of the region to be merged. Defaults: (1,1) for tiles, (tilewidth,tileheight) for pixels. Effectively, omitting the size will cause the area of 1 tile to be merged in either case. Even if the base and patch buffers use different tile specs, a range of tiles will correctly be merged one-by-one. m and n are repeat counts to merge the same source region m x n times into the destination. e.g.:- merge tiles = 1 2 3 4: will copy 1 tile from patch[3, 4] to base[1, 2] merge tiles = 1 2 3 4 5 6: will copy 30 tiles from patch[3..7, 4..9] to base[1..5, 2..7] merge tiles = 1 2 3 4 1 1 5 6: will fill 30 tiles at base[1..5, 2..7] using the same single tile at patch[3, 4] <{p|t} [ [ [ [ [ [ [ []]]]]]]] (A literal '<' followed immediately by 'p' or 't') Shorthand for "merge pixels" and "merge tiles". ======= LICENCE ======= patchbmp is freeware. (c) 2006 Landlubber Decorporated