Binary quad-tiled surfaces (.qtile files)

Files ending in '.qtile' are binary, texture-map-prepared relatives
of '.tile' files.  The application tile2qtile converts a .tile file
into a .qtile file, keeping the point arrays intact, but replacing the
color and normal arrays with texture arrays in the binary form that can
be directly sent to OpenGL texture load calls.  Also, binary trees of
error bounds are created per tile.  NOTE that .qtile files are
*not* portable across machine architectures (e.g. one written on an
SGI will not read under i386 Linux, and vice versa).  This is because
they are intended to be read without copies/translations that would hurt
performance, especially on high-speed RAID file systems.  In other words,
this should be considered a temporary or cache format, and not an
archive-quality or portable format.  Use .tile files for portability
and archiving.

The entire .qtile file consists of 4-byte words, either ints or
floats.  The first three words are the header ints:

    word 0: n, the number of quad tile arrays making up the surface
    word 1: ns, where the point arrays are size ((1<<ns)+1)x((1<<ns)+1)
    word 2: tex_size (a power of two), indicating tex_size x tex_size texels

The remainder of the file consists of the per-tile records.  These are
laid out as follows:

    8 ints for tile connectivity:
        (word 0) edge 0 tile neighbor index
        (word 1) that neighbor's back-pointing edge index
        (words 2,3) same for edge 1
        (words 4,5) same for edge 2
        (words 6,7) same for edge 3

    3*((1<<ns)+1)*((1<<ns)+1) floats for the point array, stored xyzxyz...

        These points are listed in the following order (same as .tile files):

                   |                           |
                   |                           |
                   |                           |
                   |                           |
                   |                           |
                 3 10   11    ...              | 1
                   |                           |
                   |                           |
                   5     6       7      8      9
                   |                           |
                   |                           |
         start --> 0------1------2------3------4

    tex_size*tex_size texels, in byte order rgbargba... (4 bytes per texel)

    2<<lmax floats for binary-tree array of error-sphere radii:

        lmax=ns<<1, bintree triangles are laid out as:

                    |          /|
                    |         / |
                    |  i=2   /  |
                    |       /   |
                    |      /    |
                  3 |     /     |1
                    |    /      |
                    |   /       |
                    |  / i=3    |
                    | /         |
                    |/          |

        The error for the upper-left triangle is stored in error[2], where
        float *error points to the first word of the error array.  The
        lower-right triangle's error is stored at error[3].  Note that
        error[0] and error[1] are not used for now.  Getting the kids
        indices from a parent is easy: the left kid is i<<1, the right
        kid is (i<<1)+1.

That's it.  The next tile record starts right after the last entry in the
error array.  NOTE: no errors are stored for the finest level of resolution,
because we know ahead of time these will be zero.  This means you should be
careful not to try and retrieve errors from the array for these, because you
will get garbage and/or crash your program.

Check out the source file Qscene/qscene.l for data structures qscene and
qtile, which hold the tiled surface data, and especially the function
qscene_readqtile(), which reads a .qtile file into these data structures
in one page of code, including creating OpenGL texture objects and loading
the textures.

Contact Information

Mark A. Duchaineau --

Updated Jan 5, 2000