                   HOW TO USE EGG_PALETTIZE

The program egg-palettize is used when building models to optimize
texture usage on all models before loading them into the show.  It is
capable of collecting together several different small texture images
from different models and assembling them together onto the same image
file, potentially reducing the total number of different texture
images that must be loaded and displayed at runtime from several
thousand to several hundred or fewer.

It also can be used to group together related textures that will be
rendered at the same time (for instance, textures related to one
neighborhood), and if nothing else, it can resize textures at build
time so that they may be painted at any arbitrary resolution according
to the artist's convenience, and then reduced to a suitable size for
texture memory management (and to meet hardware requirements of having
dimensions that are always a power of two).

It is suggested that textures always be painted at high resolution and
reduced using egg-palettize, since this allows the show designer the
greatest flexibility; if a decision is later made to increase the
resolution of a texture, this may be done by changing an option with
egg-palettize, and does not require intervention of the artist.



The behavior of egg-palettize is largely controlled through a source
file called textures.txa, which is usually found in the src/maps
directory within the model tree.  For a complete description of the
syntax of the textures.txa file, invoke the command egg-palettize -H.


GROUPING EGG FILES

Much of the contents of textures.txa involves assigning egg files to
various groups; assigning two egg files to the same group indicates
that they are associated in some way, and their texture images may be
copied together into the same palettes.

The groups are arbitrary and should be defined at the beginning of the
egg file with the syntax:

  :group groupname

Where groupname is the name of the group.  It is also possible to
assign a directory name to a group.  This is optional, but if done, it
indicates that all of the textures for this group should be installed
within the named subdirectory.  The syntax is:

  :group groupname dir dirname

Where dirname is the name of the subdirectory.  If you are
generating a phased download, the dirname should be one of phase_1,
phase_2, etc., corresponding to the PHASE variable in the install_egg
rule (see ppremake-models.txt).


Finally, it is possible to relate the different groups to each other
hierachically.  Doing this allows egg-palettize to assign textures to
the minimal common subset between egg files that share the textures.
For instance, if group beta and group gamma both depend on group
alpha, a texture that is assigned to both groups beta and gamma can
actually be placed on group alpha, to maximize sharing and minimize
duplication of palette space.

You relate two groups with the syntax:

  :group groupname with basegroupname



Once all the groups are defined, you can assign egg files to the
various groups with a syntax like this:

  model.egg : groupname

where model.egg is the name of some egg model file built within the
tree.  You can explicitly group each egg file in this way, or you can
use wildcards to group several at once, e.g.:

  dog*.egg : dogs

Assigning an egg file to a group assigns all of the textures used by
that egg file to that same group.  If no other egg files reference the
same textures, those textures will be placed in one or more palette
images named after the group.  If another egg file in a different
group also references the textures, they will be assigned to the
lowest group that both groups have in common (see relating the groups
hierarchically, above), or copied into both palette images if the two
groups having nothing in common.



CONTROLLING TEXTURE PARAMETERS

Most of the contents of the textures.txa is usually devoted to scaling
the texture images appropriately.  This is usually done with a line
something like this:

  texture.rgb : 64 64

where texture.rgb is the name of some texture image, and 64 64 is the
size in pixels it should be scaled to.  It is also possible to specify
the target size as a factor of the source size, e.g.:

  bigtexture.rgb : 50%

specifies that the indicated texture should be scaled to 50% in each
dimension (for a total reduction to 0.5 * 0.5 = 25% of the original
area).

As above, you may group together multiple textures on the same line
using wildcards, e.g.:

  wall*.rgb : 25%



Finally, you may include one or more optional keywords on the end of
the texture scaling line that indicate additional properties to apply
to the named textures.  See egg-palettize -H for a complete list.
Some of the more common keywords are:

  mipmap - Enables mipmaps for the texture.

  linear - Disables mipmaps for the texture.

  omit - Omits the texture from any palettes.  The texture will still
    be scaled and installed, but it will not be combined with other
    textures.  Normally you need to do this only when the texture will
    be applied to some geometry at runtime.  (Since palettizing a
    texture requires adjusting the UV's of all the geometry that
    references it, a texture that is applied to geometry at runtime
    cannot be palettized.)



RUNNING EGG-PALETTIZE

Normally, egg-palettize is run automatically just by typing:

  make install

in the model tree.  It automatically reads the textures.txa file and
generates and installs the appropriate palette image files, as part of
the whole build process, and requires no further intervention from the
user.  See ppremake-models.txt for more information on setting up the
model tree.

When egg-palettize runs in the normal mode, it generates suboptimal
palettes.  Sometimes, for instance, a palette image is created with
only one small texture in the corner, and the rest of it unused.  This
happens because egg-palettize is reserving space for future textures,
and is ideal for development; but it is not suitable for shipping a
finished product.  When you are ready to repack all of the palettes as
optimally as possible, run the command:

  make opt-pal

This causes egg-palettize to reorganize all of the palette images to
make the best usage of texture memory.  It will force a regeneration
of most of the egg files in the model tree, so it can be a fairly
involved operation.



It is sometimes useful to analyze the results of egg-palettize.  You
can type:

  make pi >pi.txt

to write a detailed report of every egg file, texture image, and
generated palette image to the file pi.txt.

Finally, the command:

  make pal-stats >stats.txt

will write a report to stats.txt of the estimated texture memory usage
for all textures, broken down by group.



WHEN THINGS GO WRONG

The whole palettizing process is fairly complex; it's necessary for
egg-palettize to keep a record of the complete state of all egg files
and all textures ever built in a particular model tree.  It generally
does a good job of figuring out when things change and correctly
regenerating the necessary egg files and textures when needed, but
sometimes it gets confused.

This is particularly likely to happen when you have reassigned some
egg files from one group to another, or redefined the relationship
between different groups.  Sometimes egg-palettize appears to run
correctly, but does not generate correct palettes.  Other times
egg-palettize will fail with an assertion failure, or even a segment
fault (general protection fault) when running egg-palettize, due to
this kind of confusion.  This behavior should not happen, but it does
happen every once and a while.

When this sort of thing happens, often the best thing to do is to
invoke the command:

  make undo-pal

followed by:

  make install

This removes all of the old palettization information, including the
state information cached from previous runs, and rebuilds a new set of
palettes from scratch.  It is a fairly heavy hammer, and may take some
time to complete, depending on the size of your model tree, but it
almost always clears up any problems related to egg-palettize.
