Binify Documentation
Author: Ben Campbell
Binify homepage: http://binify.sf.net
Introduction
Binify produces a binary file from a text description.
The use of text to specify binary files has a number of good features:
- Can contain comments
- Easier to diagnose broken files
- Easier to create manually (just use a text editor)
- Take advantage of existing tools for manipulating text files (eg
shell scripts, perl)
- Many version control systems don't handle binary files well
- Binary files can be hard to read without writing specific tools
to interpret them
Usage
binify [-d] infile [outfile]
-d
turns on debugging output.
If outfile is not specified, binify will derive a name from infile.
Firstly, if infile has an extension beginning with ".txt
",
the "txt
" will be removed. So:
"cube.txtmesh
" would become "cube.mesh
"
"outfile.txt
" would become "outfile
".
All other filenames will simply have a ".bin
" appended:
"foo.bar
" would become "foo.bar.bin
".
Description Language
Input consists of a list of comma separated values. Integer values are
written out in the format of the current data type. For fractional
values, binify assumes that the intention is to output a floating point
number.
Example
// cube.txtmesh - a simple 3d cube in an imaginary file format.
"MESH" // magic cookie for my mesh file format (4 bytes)
.type float // vertex data will be predominantly floats.
(u16)8 // number of vertices (16 bit unsigned int)
-1.0, 1.0, 1.0 // vertex 0
1.0, 1.0, 1.0 // 1
1.0, -1.0, 1.0 // 2
-1.0, -1.0, 1.0 // 3
-1.0, 1.0, -1.0 // 4
1.0, 1.0, -1.0 // 5
1.0, -1.0, -1.0 // 6
-1.0, -1.0, -1.0 // 7
.type u16 // face data will be 16 bit unsigned ints
6 // number of faces (quads)
0,1,2,3 // front
7,6,5,4 // back
1,5,6,2 // right
3,2,6,7 // bottom
4,0,7,3 // left
4,5,1,0 // top
Datatypes
u8
|
Unsigned 8 bit integer
|
u16
|
Unsigned 16 bit integer |
u32
|
Unsigned 32 bit integer |
s8
|
Signed 8 bit integer |
s16
|
Signed 16 bit integer |
s32
|
Signed 32 bit integer |
float
|
Single precision floating point
(32bits)
|
double
|
Double precision floating point
(64 bits)
|
Directives
The following directives are availible:
.type [datatype]
|
Change the current default data
type to [datatype]
|
.littleendian
|
Cause multibyte values to be
output least significant byte first
|
.bigendian
|
Cause multibyte values to be
output most significant byte first |
.align [n]
|
Insert pad zeros until the next [n]
byte boundary
|
.blank [n]
|
Insert [n] zero
bytes into the output
|
Strings
Strings are specified using double quotes. They are written out as a
sequence of 8 bit characters. Note that a null character is _not_
automatically appended - if you want a null character you must
explicitly include it.
Special characters can be specified using C-style backslash notation.
The following codes are recognised:
\0 |
null |
\n |
Linefeed (LF)
|
\t |
Tab
|
\r |
Carridge return (CR)
|
\" |
Quote
|
\\ |
Backslash
|
For example:
"Line One\nLine Two\nLine Three\n" // no null
terminator
"A null terminated string.\0"
Comments
Binify uses C++ style comments. Two forward slashes (//) mark the start
of the comment which runs until the end of the line.
Casting
The current data type can be overridden on a per-item basis by using a
casting syntax similar to C/C++.
For example:
23 // output as the
current data type
(u32)1000
(float)42 // output as a float
Expressions
Values can be specified as simple expressions.
For example:
(u32)8+4+4+4-12
Labels
A label is defined as a identifier followed by a colon. The value
assigned to the label is the current byte offset in the binary file.
Labels can be used in expressions. Label identifiers are case sensitive.
For example:
(u32)end-start // length of
string
start:
"This is some text"
end: