User:Clipka/Development

This is a page I started to collect a few things that might be helpful for fellow POV-Ray developers. It's a bit messy at present.

Coding Style

At different times, different people used different coding styles for different portions of POV-Ray's codebase, so there is currendly a hodgepodge of various coding styles. To stop proliferation and further explosion of the set of coding styles, here are a few rules to adhere when coding for POV-Ray:

• When modifying existing code, adapt to the existing style(s). While it would be nice to have a consistent coding style for all of POV-Ray's source files, it is even more important to retain per-file or at least per-function consistency of style. Of couse if a function is a hodgepodge of styles already, it makes sense to go for "the" POV-Ray style.
• If there's particularly good reason to make an exception from the recommended coding style, do so. These rules are guidelines, not laws.

Whitespace

POV-Ray C++ source and header files use the following rules regarding whitespace use:

• For general indentation, tabs are used, with one tab per indentation level.
• For in-line horizontal alignment, spaces are used.
• For horizontally aligning the start of a line with a feature on the preceding line, the same number of tabs are used as in that preceding line, followed by as many spaces as necessary for the desired alignment.

Note that when these rules are followed, the actual size of a tab is completely irrelevant, and is therefore left up to the individual developer.

People not accustomed to these rules may experience them as pretty cumbersome. To make their life easier, there exists a small tool in the Perforce repository at povray/smp/tools/tabifyer, which will attempt to convert all whitespace according to these rules, and usually does quite a decent (albeit not perfect) job at it. The tool presumes a tab size of 4, but can easily be adjusted for any other tab size at compile time.

Blocks

Block layout follows the Allman style (aka ANSI style), i.e. opening and closed braces are placed on a separate line each, with all lines in between - but not the braces themselves - being indented, e.g.:

for (int i = 0; i < count; i ++)
{
    foo();
    bar();
}

The following additional rules apply:

• In block structures that contain labels or label-like keywords - that is, class definitions and switch blocks - the labels are indented by one level, while the remaining code is indented by two levels, e.g.:

class Foo
{
    public:
        void Bar ();
    private:
        int foobar;
}

void Foo::Bar ()
{
    switch (foobar)
    {
        case FNORD:
            printf("This value does not exist.\n");
            break;
        default:
            printf("%d\n", foobar);
            break;
    }
}

• Namespace blocks are not indented.
• Single statements are not enclosed in a block (unless syntactically required), e.g.:

if (foobar)
{
    Something();
    SomethingMore();
}
else
    SomethingElse();

• For an else branch comprised of just an if statement, typically the familiar chained else if layout is used, though nested layout may be appropriate in some cases, too, e.g.:

if (foo < 10)
    DoThis();
else if (foo < 20)
    DoThat();
else if (foo < 30)
    DoNothing();
else
{
    if (errorHandler != NULL)
        errorHandler->handleError();
}

Data Types

Deprecated Types

The following types, while still in use by part of the code, should be avoided:

UV_VECT

Use Vector2d instead.

VECTOR

Use Vector3d instead.

COLOUR

Use Colour or, where possible, RGBColour instead.

RGB

Use RGBColour instead.

Note that the recommended replacement types can be passed to functions expecting the respective deprecated type by using the dereference operator.

Color Processing

COLC

Color component; a floating-point type intended for use whenever storing color components, brightness values, or any data that inherently has the same precision requirements as colors.

While this is typically defined as single-precision float, there might be reason to change it to half-precision float on platforms providing native support. The precision should therefore be expected to be as low as 3 significant digits, with a range from 6.0*10^-8 to 6.5*10⁴.

Use COLCSUM instead when summing up any signiticant number of color component (or similar) values.

COLCSUM

not implemented yet

Color component sum; a floating-point type suitable for summing up a significant number of color component (or similar) values.

The precision can be expected to be no lower than a single-precision float.

Colour

A type for storing of, and generally operating with, RGB, transmit and filter values at COLC precision.

Use RGBColour instead where sufficient.

Use ColourSum instead when summing up any signiticant number of color values.

ColourSum

not implemented yet

Color sum; similar to Colour, but using COLCSUM precision.

RGBColour

A type for storing RGB values, and performing common computations.

Use RGBColourSum instead when summing up any signiticant number of color values.

RGBColourSum

not implemented yet

RGB Color sum; similar to RGBColour, but using COLCSUM precision.

Geometry Processing

Vector2d

A high-precision 2D vector data type.

The precision can be expected to be no lower than a double-precision float per dimension.

Vector3d

A high-precision 3D vector data type.

The precision can be expected to be no lower than a double-precision float per dimension.

Integer Types

int

Do not use for boolean data; use bool instead.

Working with the Perforce Repository

General Recommendations

Get a decent interactive diff tool. Aside from just showing differences between two files, here are a few features you might want to keep your eyes peeled for:

• Optionally ignore unimportant differences, such as comment or whitespace changes.
• Manually adjust file alignment.
• Manually merge files.
• Edit files in-place.
• Compare directory trees.
• Synchronize directory trees.

I recommend investing some $30-$50 into a shareware tool such as UltraCompare from IDM (the people that brought you UltraEdit), or Beyond Compare from Scooter Software (my personal favorite), both of which go way beyond the above "shopping list". You'll probably find they're worth every cent of their price, and then some.

Building for Linux

To build a Linux version from the repository, you need to:

• Retrieve the desired revision from Perforce.
• Run "./unix/prebuild.sh".
• Follow the steps as outlined in "./INSTALL"

Adding New Source Files

When adding new source files, please make sure to:

• Add the source files to the corresponding Visual Studio projects - both the vs8 and vs9 version. (You may want to use a diff tool to update the project you're not using yourself: There are only few differences between the respective project files.) Please also make sure to strip the "Relase-SSE2|x64" configuration from the modified project file before checking it in; while Visual Studio keeps auto-generating that configuration, we don't actually want it in the repository. (Again, a diff tool comes in handy.)
• Add the standard POV-Ray comment block to the head of your files. (Don't forget to fill in the proper file name.)
• After marking the files for add in Perforce, change the Perforce filetype; for C++ source and header files, we want base type "text" with the "+k" option enabled ("ktext").

When someone else has added new source files, people compiling for Linux will have to:

• Run "./unix/prebuild.sh" to re-generate the makefiles.