Chapter 5. Internals

Table of Contents

5.1. Sources
5.1.1. Understanding the POV-Ray source structure
5.1.2. Markup - key to make portable patches
5.1.3. Coding - stay portable
5.1.4. Sharing patches
5.2. Binaries
5.2.1. compiling on Windows/DOS systems
5.2.2. compiling on Macintosh systems
5.2.3. compiling on Unix systems
5.3. Parser
5.3.1. Adding tokens
5.4. Expressions
5.4.1. Polynomial solver
5.5. Multi-format Documentation with DocBook
5.5.1. Environment for DocBook documentation
5.5.2. Editing DocBook documentation
5.5.3. Converting DocBook documents

With increasing raytracing experience and knowledge about algorithms you may want to change/fix some features or add new ones to the core sources of POV-Ray™ or MegaPOV. You may also want modify sources when you want to move a slowly parsed SDL macro to faster C/C++ code within POV-Ray™.

The following section is our effort to write down the conclusions we made from our experience in writing patches compatible with POV-Ray™ architecture with portable documentation and merging those made by others. If you are new to POV-Ray™ or patch writing you should bear in mind we have a long term experience with POV-Ray™ and you probably can learn something useful from the things written here. If you are an experienced patch writer do not hesitate to vary the rules where you think this is appropriate.

Working with sources of POV-Ray™ 3.5 or MegaPOV requires some basic knowledge about:

POV-Ray™ and MegaPOV sources can be considered as a nice lesson in programming and raytracing however do not try to modify sources without basic understanding of the above things. Please, do not waste time asking for detailed explanations when answer seems obvious in the above categories. Try to find some online tutorials or just buy a comprehensive book. Below information is gathered mainly to highlight POV-Ray™ source specific aspects.

Sources of MegaPOV are based on the POV-Ray™ sources distributed officially by POV-Team™. The basis for the modifications included in MegaPOV 1.0 is the source of the 3.5a windows version. Filenames usually well explain the usage. Most files also contain a simple description at the beginning. Each *.cpp filename is delivered with appropriate *.h header file.

All files located in the /source directory in the archives can be considered as part of the following categories:

As mentioned above the config.h configuration file is located in a platform specific directory. This directory is usually named like the target platform (like windows, dos etc.). There are also other files located in that directory: implementation of GUI, binary resources (like icons), implementation of some (protected) IO operations and other platform specific solutions.

It is hard to describe good guidelines for patching POV-Ray™. Every programmer has own habits and methods including indention, placing of braces, inserting white spaces, favorite naming scheme. But there are some common rules POV-Ray™ patch writers usually follow. Here is our effort for a brief summary - mainly meant as a starting aid for beginning patch writers.

Usually, people put something like #define MY_PATCH in a commonly used file:

Now you should enclose all patch-specific code in #ifdef ... [#else ...] #endif blocks, so removing (commenting) /* #define MY_PATCH */ causes compilation without your patch, and the modifications you make are clearly visible. Optional #else ... is suggested when you are making replacement for existing code (i.e. for bug fixes).

The most common system for patch naming are uppercased words separated with underscores. Names are usually concatenated with word PATCH somehow. In world of Apple mixed case variable names without underscores like MyPatch are also popular.

Some additions can be also compiler specific changes required by lack of some builded C function or different naming. In such cases you can use predefined compiler specific macros together with your own markup. Each compiler delivers several predefined macros (see Section 5.2).

#ifdef __DJGPP__
  // some compiler specific code
#else
  // code for other compilers
#endif

#if defined( __WATCOMC__ ) && defined( MY_PATCH)
  // code here
#end

Of course it is a little bit more work to maintain changes this way but on the other hand it is also much more readable and allows to prepare two binaries for comparison. It is also much more easier to port your changes into other compilations like MegaPOV then.

Once a patch is finished you may want to share this patch with the POV-Ray™ Community. Doing this in a wise way can make your patch popular and included in other unofficial custom compilations like MegaPOV is. So before you upload your changes somewhere first check if:

When your modifications are validated then it is time to publish it. There are some common methods in publishing patches:

It is hard to tell which method is the best. The choose of particular method depends on free time, complexity of changes and used sources.