diff --git a/panda/src/doc/egg-palettize.txt b/panda/src/doc/egg-palettize.txt new file mode 100644 index 0000000000..b53cc875f2 --- /dev/null +++ b/panda/src/doc/egg-palettize.txt @@ -0,0 +1,213 @@ +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.