1: Major Classes and Data Types

This section describes the central C++ classes and simple data types that Terraform relies on. In order to do any serious work with Terraform, you will need to be familiar with these types in order to make your code compile easily, interact properly with the rest of Terraform, and maintain Terraform's the level of portability.

1.1: Simple data types

Like many large software projects that attempt not to rely on machine- or compiler-specific definitions for basic types, Terraform defines a few synonyms for basic types to avoid using potentially unportable keywords. Fortunately, there are few of these for you to keep track of. Make an effort to use these synonyms in your code, so that your code will remain portable. These synonyms are defined in GlobalDefs.h and HeightFieldCore.h:

Note that Terraform is a work in progress, and does not itself always adhere to these guidelines. Future code cleanups will address these issues.

1.2: Naming Conventions

Typically, class members are prefixed by a short string which identifies the variable type/class as follows:

1.3: class HeightField

The HeightField class stores the elevation data for terrain models, as you would expect. The data members and member functions defined in the HeightField class itself are largely concerned with file I/O, naming, supporting undo functionality, etc. There is little in HeightField itself that is interesting from the point of view of operations that can modify or inform you about the height field data itself.

The HeightField class is derived from the HeightFieldCore class, which is itself derived from the Matrix2D template class. The HeightField class is the finished product which supplies all the HeightField related services the application needs. The following table lists the public member functions of HeightField that are of particular interest.

Accessor Member Functions:

Mutator Member Functions:

The listing of HeightField related methods given here is not complete. HeightField.{h,cc} contains other functions which may be useful when manipulating Height Field data. For more information, see HeightField.{h,cc} and HeightFieldCore.{h,cc}.

1.4: class HeightFieldDraw

The HeightFieldDraw class encapsulates operations having to do with drawing a heightfield on the screen. If you wish to add a new display mode, such as a POV rendered view, you would extend HeightFieldDraw.{h,cc}. As well, some member functions in the HeightFieldOps class receive HeightFieldDraw pointers as arguments, because those functions occasionally need to use information about the current rendering settings, particularly the current colormap. The following table lists the public member functions of HeightFieldDraw that are of particular interest:

Member Functions

For more information, see HeightFieldDraw.{h,cc}.

1.5: class HeightFieldReader / HeightFieldWriter

These classes encapsulate functionality related to reading and writing heightfields from various file formats. The currently supported formats are Poskanzer Gray Map (.pgm), Targa (.tga), Matlab (.mat), Octave ASCII (.oct), United States Geological Survey DEM format (.dem), GTOPO (.gtop), Portable Network Graphics (.png), Tagged Image File Format (.tiff), and Windows Bitmap (.bmp). If you wish to support additional formats or enhance the support for any of these formats, you will be modifying the HeightFieldReader and/or HeightFieldWriter classes. Note that not all of those formats are currently supported for both input and output.

HeightFieldReader exists mainly as a place to hold the various file reading functions, and to contain some additional helper functions that are useful when implementing support for a new file format. The useful helper functions are:

void	checkRead(points_read, npoints)	Check that the number of data points read from the input file matches the number of points in the heightfield. If the file did not contain enough points, set the unassigned points to zero elevation.
void	readOK()	Copies the input file's name to the heightfield's d_name member, and collects some statistics about the new heightfield.

Similarly, HeightFieldWriter exists mainly to hold the various file writing functions, and to contain some handy member variables. Unlike HeightFieldReader, this class doesn't have any helper member functions. You should, however, make use of the class's d_Fio member in order to open an output file, to access filename information, if necessary, and to close the output file.

1.6: class HeightFieldExport

The HeightFieldExport class exists to contain functions which produce some sort of "derived" data as output. It is difficult to provide a clear definition of "processed" that does not include the functionality provided in HeightFieldWriter, but in general HeightFieldWriter should be used to create _exact_ representations of the heightfield that could, at least in theory, be read back into Terraform or be used as input to some other related program. HeightFieldExport, by contrast, is more implicitly a "one-way" transformation. For example, the HeightFieldExport::renderPOV method creates some POV input files based on the heightfield data and then runs POV to render the terrain. The POV file output is derived from the heightfield data, but is not suitable as an input format for Terraform. Likewise, POV's output is not suitable as input to Terraform, even in theory.

Similarly, the HeightFieldExport::exportContourLinesToPS method creates a postscript file representing the contour lines generated by the HF->Contour Line Map command. However, this function only writes selected points in the heightfield to the postscript file, and as such the results are not an exact representation of the heightfield. Such a postscript file could not, even in theory, be used as an input file for Terraform because it does not contain an elevation for every point in the heightfield.

If you wish to add a feature to Terraform that fits into this "processed data output" category, you will be working mostly in HeightFieldExport.{h,cc}.

2: A brief tour of Terraform's source code

3: Adding new source files

4: Adding a new input type (i.e. extending File->Open)

Adding support for a new input format, if you wish to read heightfields from some file type that Terraform does not currently support, is not difficult. Terraform's file input mechanism is well designed to support additional types. You will be working with the HeightFieldReader and HeightFieldIO classes, defined in HeightFieldReader.{h,cc} and HeightFieldIO.{h,cc}.

Supporting a new input file format involves writing a function to parse that format, adding logic to detect that format's file type, and adding a call to your file parsing function.

Add your file parsing function to the HeightFieldReader class. Give it a name of the form "readXXX()", where XXX represents the new file format. Examples are readGIF, readPGM, etc. You may also implement private helper functions in the HeightFieldReader class, if necessary, to assist your readXXX function. Your function will need to allocate an array of PTYPE large enough to hold the data from the file (e.g. myarray = new PTYPE[width * height];), read the file's data and convert it into PTYPEs in the range 0.0 to 1.0, store that data in your array, and finally assign the heightfield's d_hf member to your array (e.g. d_hf = myarray;). Finally, your parsing function should call HeightFieldReader::checkRead when it is done in order to do some important post-processing on the new heightfield.

Once you have written your parsing function, you need to hook it into the HeightFieldIO class. First, modify HeightFieldIO.h to define a new constant to represent your file type, if a suitable type is not yet defined. In that file you will find definitions for the other file types Terraform already supports. In HeightFieldIO.cc, you will need to do two things. One, modify the HeightFieldIO::getFileType() function to associate the correct file extension with your file type. Two, modify the HeightFieldIO::read() function to add a call to your readXXX function.

5: Adding a new output type (i.e. extending File->Save As)

Adding support for a new output format, if you wish to write heightfields to some file type that Terraform does not currently support, is not difficult. Terraform's file output mechanism is well designed to support additional types. You will be working with the HeightFieldWriter and HeightFieldIO classes, defined in HeightFieldWriter.{h,cc} and HeightFieldIO.{h,cc}.

Supporting a new output file format requires writing a function that can convert heightfield data into some other appropriately structured format, as well as handle writing any necessary file header or footer information, adding logic to detect your new file type based on the filename the user has chosen to save the heightfield to, and adding a call to your writing function.

Add your writing function to the HeightFieldWriter class. Give it a name of the form "writeXXX()", where XXX represents the new file format. Examples are writeTGA, writePGM, etc. You may also implement private helper functions in the HeightFieldReader class, if necessary, to assist your writeXXX function. Your function will need to loop over all the data in the heightfield (recall that you can use the HeightField::El() function to access this data), convert it to the appropriate format for your file type, and write it to a filehandle provided by the HeightFieldWriter class. The heightfield data you will be working with will be stored as PTYPEs in the range 0.0 to 1.0. Finally, your writing function should close the file handle and call HeightField::setSaved(TRUE) when it is done.

Once you have written your writing function, you need to hook it into the HeightFieldIO class. First, modify HeightFieldIO.h to define a new constant to represent your file type, if a suitable type is not yet defined. In that file you will find definitions for the other file types Terraform already supports. In HeightFieldIO.cc, you will need to do two things. One, modify the HeightFieldIO::getFileType() function to associate the correct file extension with your file type, if your file type is not already listed. Two, modify the HeightFieldIO::write() function to add a call to your writeXXX function.

6: Modifying the height field

One obvious class of hack to Terraform are features that do something interesting to an existing heightfield, such as adding craters, inverting the terrain, raising or lowering it, etc. These functions typically reside in the HeightFieldOps class, which is where you should implement such functions. Add your function as a new public member function in HeightFieldOps.h, and put the function in HeightFieldOps.cc. Your function should have this general structure:

int HeightFieldOps::myFunc(args...) 
{
  // declare any variables you need
  PTYPE	newElevation;

  // loop over the terrain and modify it:
  for(int x=0; x < p_HF->getWidth(); x++)
    for(int y=0; y < p_HF->getWidth(); y++) 
      {
      newElevation = ... ;	// do something cool...
      p_HF->setEl(x,y, newElevation);
      }

  // any broad-scale changes to the heightfield also need to do the following:
  p_HF->gatherStatistics();
  p_HF->setSaved(FALSE);

  // return a status code.
  return(0);
}

Of course, depending on the algorithm you're using to modify the terrain, your function may not contain an internal loop structure exactly like the above. Use whatever code you need to make whatever changes you want to the terrain. Once you're done, call p_HF->gatherStatistics(); this will rescale the height field to the value range 0..1 and do some other limited sanity checking.

7: Adding a new terrain generator

Terraform currently supports two different terrain generators, the spectral synthesis generator and the subdivision generator. To add a new terrain generator, you need to do the following:

Create a class to encapsulate your generator.

Your class needs to support one method, generate() in addition to a constructor and destructor. The constructor will receive a HeightField pointer that you will need save for use in your generate function. Your generate function needs to set the heightfield's d_xsize, d_ysize, and d_size (remember, d_size is always equal to d_xsize*d_ysize) members, and create an array of d_size PTYPEs (e.g. myarray = new PTYPE[d_size];). Fill that array with values in the range 0.0 to 1.0 by whatever means you like, then assign the heightfield's d_hf member to your array (e.g. d_hf = myarray;).

Patch your generator into HeightFieldGenRandom.{h,cc}

The HeightFieldGenRandom class simply chooses at random among the other terrain generators. Thus, you need to teach HeightFieldGenRandom about your new generator in order for it to be available for use when users choose to generate a random heightfield.

Add your generator to the File->New submenu's list of available terrain generators.

You will need to modify MenuDefs.h, and TFWindowMain.*. If your terrain generator is sufficiently complex as to require user input, you will also need to add a pair of TFDialogGen*.{h.cc} files to implement a dialog box so users can choose parameters for your terrain generator. See TFDialogGenSubdiv.* for a good example of how to do this. For terrain generators that need a dialog box, the dialog box will be responsible for creating a new object of your generator's class, getting parameters from the user, and passing those parameters to your generate() function. If your generator is simple enough not to need parameters, then the code you add to TFWindowMain to implement your File->New submenu option will have to create the new generator object and call its generate() function.

8: Debugging Support

Luckily for you, Terraform comes with a number of fairly robust debugging mechanisms already in place. First, the GlobalTrace class allows you to set (and check) various trace output levels, to give you easy control over how much debugging output your code generates. This class also contains the trace() method, which writes a string to standard out if the current debugging level matches the level specified in the call to trace().

Next, the GlobalSanityCheck class provides facilities for validating that certain conditions hold true, and either exiting or printing a warning if they do not. GlobalSanityCheck should be used to check the validity of any assumptions your code makes before that code runs. In fact, as you browse through Terraform's source code, you will find calls to GlobalSanityCheck::warning and GlobalSanityCheck::bailout as the first few lines of many functions.

Finally, as a last line of defense, Terraform implements exception handling, to catch various errors that would crash the program and to give users the options of what to do next. You shouldn't have to do anything special to make use of this functionality, although if your code is causing lots of core dumps, you may well become intimately familiar with Terraform's exception handling support. If you want to use this built-in exception handler, you must run ./configure --enable-debug for the exception handling code to be enabled.

If you've compiled your own executable anyhow, you might just want to recompile with the "-g" flag enabled and then use gdb. I prefer this to using the built in debugging support.

9: Submitting your changes