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.6 or MegaPOV requires some basic knowledge about:
Although POV-Ray™ and MegaPOV sources can be considered as a nice lesson in programming and raytracing it is not recommended for beginners in programming and computer graphics to try modifying it. There are relatively complex relations between the different parts and changing something without knowing exactly what you do is likely to cause problems, even if it compiles and works well in first tests. 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 and most important: study the source code. 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.1 is the source of the official 3.6.0 version. Filenames usually already give a hint on the purpose and most files contain a short description in the header on their purpose. 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:
The patches subdirectory contains all new files for features introduced in MegaPOV:
Common structures and definitions:
Lighting and other "visible" effects:
Math helpers with operation on different types of data:
IO routines for various formats:
Functions Virtual Machine implementation together with internal functions:
general program routines:
the base subdirectory contains routines for file input/output as well as string and option handling.
the frontend subdirectory contains the default frontend:
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, unix 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.
Extending POV-Ray™ with new features is something that requires significant skills (see Section 5.1, “Sources”), experience and time.
There are many different reasons for modifying the POV-Ray™ source. Most important are the fixing of bugs and extending POV-Ray™ with new features.
When fixing a bug it should be considered what is the right, expected behavior of the program, the fix should establish this. In many cases patches introduced as a bugfix are in fact feature extensions or only superficial fixes that do not solve the underlying problem.
When you are planning a new feature you should first think about how it should fit into the rest of POV-Ray™ features. A good patch can be used quite universally, not only for the purpose it was originally developed for. Do not try to reinvent the wheel but make use of existing techniques that already exist in the POV-Ray™ source. For things like status output and file reading use functions existing in POV-Ray™.
It is hard to describe good guidelines for the actual coding of a patch. 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.
When coding make use of existing helper functions in POV-Ray™ like those in vector.h. Try to reduce changes in existing code to avoid damaging existing features.
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
... #define FAST_SQR_PATCH ...
... #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 builtin 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, “Binaries”).
#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, “Discussions”).
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.