grabber - Create datafiles
The grabber accepts a few different commandline options:
Sets the color depth, eg. -8, -16, -32.
Sets the screen resolution, eg. -320x200, -1024x768
Forces the grabber to start up in a window.
Forces the grabber to start up in fullscreen mode.
Disables audio output.
Use 'key' as the datafile password.
Loads the named datafile.
Using the grabber
Various options can be set using the buttons and text fields at the top of
the screen. You can edit the name of the datafile, the name of the header
file for exporting object indexes (leave this blank if you don't want to
output a header), and the prefix string for the header file definitions. You
can change the grid settings for grabbing bitmaps, and alter the compression
mode (see below). You can enable or disable backups: if this box is checked,
the old version will be renamed to a .bak extension when datafiles are saved.
You can also turn dithering on (this can improve the image quality when you
reduce graphics from 15, 16, 24 or 32-bit color to 8-bit color and from 24 or
32-bit color to 15 or 16-bit color) and enable transparency preserving (this
will ensure that the masked areas in bitmaps stay exactly the same through
The contents of the datafile are listed in the box at the bottom left of the
screen, and can be selected with the mouse or arrow keys. Multiple objects
can be selected by holding down the shift or control keys while you click
on the list or move the cursor. The selected object can be edited with
commands from the Object menu, or using the shortcut menu produced by
pressing Esc or right-clicking on an object. Double-clicking on an object
performs a function which varies depending on the type of the object.
Bitmaps are displayed full-screen (use the plus and minus keys to zoom in
and out), samples and MIDI files are played, palettes are selected (meaning
that they will be used when displaying and exporting bitmaps), and fonts can
be edited by adding and removing specific character ranges.
New objects can be created using the menus or by pressing Insert while the
item list has the input focus. To make nested datafiles, create a FILE
object (New/Datafile), and select it before inserting other objects.
To insert information into a datafile you must first create an object of the
appropriate type, and then select the grab command (keyboard shortcut
ctrl+G). For most objects this will bring up a file selector for you to
select the file to read, but for graphic objects (bitmaps, RLE sprites,
compiled sprites, and palettes) it will grab from the current contents of
the image buffer, so you must previously have read a picture into this
buffer with the File/Read Bitmap command (keyboard shortcut ctrl+G). You can
use the mouse or arrow keys to select which portion of the image to grab.
With the mouse, select the top left corner, click and hold the left mouse
button, and move to the bottom right corner before releasing the button.
Press the right mouse button to cancel. With the keyboard, use the arrow
keys to select the top left corner, press Space or Enter, adjust the size
with the arrow keys, and press Space or Enter again. By default the position
will snap to a 16x16 grid, which can be adjusted by changing the values in
the X-grid and Y-grid fields. Alternatively you can use the Box Grab
command, in which case you should draw a bounding box in color #255 around
your sprites, and can then just click once inside a box to grab the contents.
Note that palette data is not stored along with bitmap and sprite objects.
To store the entire contents of a PCX or BMP file, you will need to create
both bitmap and palette objects, and grab data into both of them. When you
reload the datafile the bitmap will probably be displayed with the wrong
palette. This can be corrected by double-clicking on the palette object,
which will select its contents as the current palette, meaning that it will
be used when displaying and exporting bitmaps.
The properties of the selected object are listed in the box to the right of
the item list. These can be edited by double-clicking on one of the
properties, and deleted by selecting one and pressing Del. You can insert
new properties by pressing Insert while the property list has the input
focus, or using the Object/Set Property command. Object names are stored as
NAME properties, so the rename command is simply a shortcut for editing this
To simplify the process of grabbing several related images from a single
bitmap (for example a set of frames which form an animation), you can use
the File/Grab from Grid command. Like the normal bitmap grab command, this
uses data from the image buffer, so you must read in a bitmap before you use
it. You will then be able to adjust the grabbing parameters, enter a name
for the new objects, and choose the type of object to create (bitmap, RLE
sprite, or compiled sprite). Because several objects may be created, their
names will be formed by adding a number to the end of the name you supply,
for example if you enter "a_picture", the grabber will create the objects
"a_picture000", "a_picture001", etc. There are two grabbing modes: using
cutouts of color 255, and using a regular grid. The regular grid option
simply divides the bitmap up into a set of equally sized tiles, using the
specified grid size, and grabs each of these as a separate object. If you
set the Skip Empties flag, the grabber will ignore tiles that don't contain
any data (ie. those that are a single solid color). The color 255 option is
more flexible. It expects the bitmap to contain information describing the
position and size of each tile, in the form of a bounding box drawn in color
255. The most reliable way to do this is to fill all the image except the
parts you want with color 255, but the grabber should be able to understand
more complicated layouts, even if you simply draw color 255 lines along the
top and left edges of the area you want to be grabbed. For truecolor images
where color 255 is not particularly meaningful, use a cyan bounding box
(maximum blue and green, zero red), with a single yellow (maximum red and
green, zero blue) pixel in the top left corner of the box.
By default, the grabber will run in a 640x480 resolution, using the highest
color depth possible on your graphics card. If you want to override this,
you can specify an alternative color depth or resolution on the commandline,
eg. "grabber -8" for a 256 color mode, "grabber -16" for 16 bit hicolor
graphics, "grabber -320x200" to use VGA mode 13h, or "grabber 1024x768".
Warning: editing datafiles that contain truecolor graphics is very slow in
256 color video modes, and the grabber is not really usable in resolutions
lower than 640x400.
You can configure the grabber to use external tools for editing data, by
setting some variables in the [grabber] section of the allegro.cfg file.
These are in the form "type=command", where the type is a four letter object
ID, and the command is whatever program you want to be invoked to edit this
kind of data. For these variables to be seen, the allegro.cfg file must
either be in the same directory as the grabber executable, or in the
directory pointed to by your ALLEGRO environment variable. To invoke this
feature, select the Shell Edit command or press ctrl+Z. The grabber will try
to invoke the tool on the original version of the file if it knows where you
grabbed the data from in the first place, or otherwise it will write the
object out into a temporary file prior to editing.
Datafiles can be saved using any of three compression types, selected from
the list at the top right of the grabber screen, or with the '-c0', '-c1',
and '-c2' options to dat. With type 0, the data is not compressed at all.
Type 1 compresses each object individually, while type 2 uses global
compression over the entire file. As a rule, global compression will give
better results than per-object compression, but it should not be used if you
intend to dynamically load specific objects with the load_datafile_object()
function or "filename.dat#objectname" packfile syntax.
There are also three strip modes for saving datafiles, selected with the
File/Save Stripped command in the grabber, or using the '-s0', '-s1', and
'-s2' options to dat. With zero stripping, all object properties are written
to the datafile, which is normally what you will want. With strip mode 1,
properties specific to the grabber (the ones describing the origins and
dates of each object) are removed, which will marginally reduce the file
size, but will prevent the update command from working. For the smallest
possible file sizes, strip mode 2 removes all properties, including object
names and any custom properties you have added. This level of stripping
should obviously be used with extreme caution, although in some cases it may
be possible to recover the object names even after they have been stripped
out of the datafile. If the grabber and dat utilities cannot find any name
properties in a datafile, they will look for a header (.h) file with the
same name, and attempt to parse this to recover the names. This is far from
foolproof, and will not work for nested datafiles, but in some situations
it allows the names to be read back from the index definition header. In
addition to those three strip modes, you can define properties to be kept,
whatever the strip mode. For example, if you want to strip all properties
but the NAME, this command will do the job:
dat -s2 -s-NAME file.dat
The objects of the datafile can be sorted alphabetically by name. This is
selected by the Sort checkbox in the grabber, or by using the '-n0' and
'-n1' options to dat. With zero sorting, objects are listed in the order
they were added to the datafile. With sort level 1, they are listed in
alphabetical order according to their NAME property, including inside
Both the grabber and the dat utility have an update command, which scans
through the datafile checking if any objects have changed, and replacing
those which are out of date. This depends on the origin and date properties
which were set when the data was grabbed in the first place, so it won't
work if these properties have been stripped out of the file. This command
can be very useful if you build a datafile containing hundreds of objects
grabbed from external bitmaps, and later go back and change some of these
bitmaps. Rather than having to figure out which objects are out of date and
then manually re-grab all the affected data, the update command will
automatically refresh the modified objects.
Fonts can be read from GRX format .fnt files, 8x8 or 8x16 BIOS format .fnt
files, and from bitmap images, or you can import a multiple-range Unicode
font by writing a .txt script that specifies a number of different source
files for each range of characters. The script file contains a number of
lines in the format "filename start end", which specify the source file for
that range of characters, the Unicode value of the first character in the
range, and the end character in the range (optional, if left out, the entire
input file will be grabbed). If the filename is replaced by a hyphen, more
characters will be grabbed from the previous input file. For example, the
ascii.fnt 0x20 0x7F
- 0xA0 0xFF
would import the first 96 characters from ascii.fnt as the range 0x20-0x7F,
the next 96 characters from ascii.fnt as the range 0xA0-0xFF, and the entire
contents of dingbats.fnt starting at Unicode position 0x1000.
When reading a font from a bitmap file, the size of each character is
determined by the layout of the image, which should be a rectangular grid
containing all the ASCII characters from space (32) up to the tilde (126),
unless you are using the script mechanism described above, in which case the
range(s) should match the one(s) specified in the .txt file. The spaces
between each letter should be filled with color 255. If each character is
sized exactly 8x8 or 8x16 the grabber will create a fixed size font,
otherwise it will make a proportional font. Probably the easiest way
to get to grips with how this works is to load up the demo.dat file and
export the TITLE_FONT into a PCX file. Have a look at the resulting picture
in your paint program: that is the format a font should be in...
Bitmap and RLE sprites can store an alpha channel along with the color
information, as long as they are in a 32 bit format. Alpha data can be read
directly from 32 bit TGA files, or you can use the alpha channel commands
(in the Object menu, or the right mouse button popup menu) to import a
greyscale alpha image over the top of an existing object. This menu also
contains options for viewing the alpha channel of the selected object,
exporting the alpha data to a greyscale image file, and deleting the alpha
data to leave only pure color information. You can also use the File menu to
import an alpha channel over the top of a bitmap that you have loaded with
the Read Bitmap command, after which the alpha information will be included
when you next perform a Grab or Grab From Grid operation.
Datafiles can be encrypted with a password, by typing it into the
"Password:" field in the grabber, or using the '-007 password' option to the
dat utility. Passwords may be up to 256 characters in length, and are case
sensitive. Encrypted files _cannot_ be read without the password, so please
don't forget it and then come crying to me for help :-) To read an encrypted
file into your program, call the packfile_password() function before
load_datafile(). It is also a good idea to call packfile_password(NULL)
afterwards, to set everything back to normal.