From a234645d699cab09c14ec222d19db472844bef96 Mon Sep 17 00:00:00 2001 From: David Rose Date: Mon, 13 Dec 2004 23:12:56 +0000 Subject: [PATCH] more clarifications, section about mayacopy etc. --- panda/src/doc/ppremake-models.txt | 105 +++++++++++++++++++++++++++++- 1 file changed, 104 insertions(+), 1 deletion(-) diff --git a/panda/src/doc/ppremake-models.txt b/panda/src/doc/ppremake-models.txt index fe97cf1407..d275cf1a2c 100644 --- a/panda/src/doc/ppremake-models.txt +++ b/panda/src/doc/ppremake-models.txt @@ -38,6 +38,18 @@ perform these steps, although it currently generates only a Unix-like makefile, so the at the moment a model tree can only be built on a Linux or Unix machine, or on a PC with Cygwin installed. +See the dmodels tree in the Panda3D repository for an example of a +simple buildable model tree. This is different from the models tree, +which is much simpler and includes only ready-to-load egg files; the +dmodels tree is set up as a full-fledged buildable model tree using +the ppremake system. With a few small exceptions, the dmodels tree +does not contain any egg files, although intermediate egg files are +generated during the make process. When you have finished building +the dmodels tree, you will have generated a number of bam files that +are fully optimized and ready to load for your current version of +Panda. + + To set up a ppremake model tree, you must create a Sources.pp file in the directory with the models (or in the directory above the SoftImage tree in the case of SoftImage models). @@ -411,4 +423,95 @@ filter_char_egg - Similar to filter_egg, above, except that one #defer COMMAND \ egg-topstrip -i -t joint_pelvis -d $[TARGET_DIR] $[sources] #end filter_char_egg - \ No newline at end of file + + +HOW TO POPULATE A CVS-CONTROLLED MODEL TREE + +Since a model tree is really just a source tree like any other, you +can check in the source files--the .mb files or .flt files, for +instance, and all of the associated image files--as source files in a +CVS directory. Then any developer can check out the source tree, +ppremake, and make install, exactly the same way you would build +Panda. Of course, .mb files and .flt files are binary files, but CVS +(and most other revision control systems) allows you to add binary +files to the system. You just can't merge multiple changes coming in +at once to the same file, so it's important to make frequent updates +and commits in order to minimize the chance of an accidental +collision with another artist. + +In order for this to work, the source files must reference texture +paths and other external filenames using relative filenames--for +instance, a model should apply a texture named "../maps/grid.tif" +rather than "/home/drose/panda3d/dmodels/maps/grid.tif", for instance. +This is because the entire model tree might be checked out by another +developer within some other directory, and only relative paths within +the model tree will be valid. + +For most modeling packages, it is not difficult to ensure that all of +the external references use only relative paths. Populating a model +tree with, say, MultiGen source files may thus be as simple as copying +the MultiGen files and the image files in and then adding them to cvs +by hand (using -kb to indicate a binary file, of course). + +Maya, on the other hand, for some reason insists on storing texture +references as full pathnames, even if you enter a relative path. It +is not possible using the Maya API to create an .mb file that +references its textures using relative pathnames. This makes it +impossible to add a Maya file to a CVS repository in the normal way. + +However, it *is* possible to store relative paths within a Maya file +if you use an OpenMaya program to generate the Maya file. Panda +provides a utility called mayacopy that does this (among other useful +features). + +In fact, Panda provides a family of utilities, with similar behavior; +at the time of this writing, the list includes mayacopy, fltcopy, and +lwocopy. (There is also a separate tool called softcvs, used for +integrating SoftImage version 4.3 databases; this works differently +from the others, because of the very different nature of a SoftImage +scene. The use of softcvs is not documented in this file.) + +In general, the copy tools work like this: + + cd mymodels/src/mydir + mayacopy /path/to/my/maya.mb + +This copies the indicated Maya (or MultiGen, LightWave, etc.) file +from the named directory into the current directory. It also copies +in all of the texture files referenced by the Maya file, and it +modifies the Maya file to use only local pathnames to the newly copied +texture files, instead of the full pathnames that would have been +stored in the original Maya file. + +A little heuristic is used to decide where to place each texture image +referenced by the Maya file. The following rules are applied: + + (1) If another texture file with the same name already exists + elsewhere in the source hierarchy, assume this texture image + represents the same image (or a new version of that image) and + overwrite it. (Note that it is not a good idea to have + different texture images that are stored under the same + filename. egg-palettize also makes the assumption that any two + files with the same filename represent the same texture image.) + + (2) If the texture file does not already exist, copy it into src/maps. + + (3) If the src/maps directory does not exist, copy the texture file + into the same directory with the source Maya file. + +As the Maya file and each texture file is copied into the source tree, +the cvs command is automatically invoked to add the file(s) to the +repository, if necessary. It is still your responsibility to issue +the cvs commit command when you are ready to make the changes +permanent. + +You can use mayacopy, fltcopy, etc. to copy in a file from a +completely different hierarchy, or to update a file already within the +source tree. It is particularly important to re-run mayacopy after +modifying any .mb file using Maya, since Maya will replace all of the +local pathnames with full pathnames each time you save the file. +Re-running mayacopy on the same file will restore the relative +pathnames again. + + +