Table of Contents
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:
Switches to enable features of MegaPOV:
Features introduced in MegaPOV:
Common structures and definitions:
Object definitions:
Lighting and other "visible" effects:
Radiosity:
Texturing:
Raytracing helpers:
Builded benchmark:
Math helpers with operation on different types of data:
Parser routines:
IO routines for various formats:
Functions Virtual Machine implementation together with internal functions:
Rendering process:
general program routines, options parsing, text output and other stuff:
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.
Example 5.1. Typical patch markup
patches.h:
... #define FAST_SQR_PATCH ...
some_file.cpp:
... #ifdef FAST_SQR_PATCH // new code Value = sqr( Parameter ); #else // old code Value = Parameter * Parameter; #endif ...
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.
Apart from the markup it is important to keep modifications portable. Patches using compiler specific features or functions from a proprietary library won't make it into a patch collection like MegaPOV.
When you add new elements to the POV-Ray scene description language it is a good idea to keep it consistent with the existing syntax. Even if you think a certain syntax would be much easier to use it is very likely to cause much confusion for the user when it differs from existing similar functions.
Some useful information about portability aspects can be found on http://predef.sourceforge.net/.
If you are unsure about a certain aspect of your patch implementation better ask (see Section 1.5.3).
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.