OPAL: Open Physics Abstraction Layer

Bug Reports, Feature Requests, Patch Submissions, OPAL Design Philosophy, and Coding Conventions

This page is a reference for those people wanting to submit bug reports, feature requests, or patches submissions to the OPAL source code. Most of these processes are handled via SourceForge trackers (see Document E03 of the SourceForge Site Docs for more information on tracker system, or click here for the current link to this document). This page also describes OPAL’s design philosophy and coding conventions for people writing source code patches.

Bug Reports

To submit a bug report, visit the “Bugs” link on the SourceForge project page. Submit a detailed description of the problem.

Feature Requests

To submit a bug report, visit the “RFE” (“request for enhancement”) link on the SourceForge project page. Submit a detailed description of the feature you wish to be added and your reasoning for why this feature has mass appeal.

Patch Submission

1. If you have an idea for an OPAL patch (e.g. bug fix, additional class member functions, support for a physics engine, etc.) that you would like to implement and submit, first discuss it with others in the forum to see if it would be useful for a lot of people. Some ideas for patches will not be useful for much of the OPAL community and will not be considered (but, of course, you can always make modifications to your own version of OPAL). The OPAL development team makes the final decision of whether a patch gets applied or not, so it would be wise to discuss your idea on the forum with one of the developers before starting your implementation.

2. Implement your changes/additional code (following the OPAL design philosophy and coding conventions described below) and test it thoroughly.

3. Create a CVS .diff or .patch file containing all of your changes. If you are using unix and have simply changed some existing OPAL files, do the following:

cd /path/to/opal_directory

cvs diff -u -b > patch_name.patch

If you are using unix and have added new files, do the following:

cd /path/to/opal_directory

cvs diff -u -r -b -N -a --binary --exclude=CVS --exclude=build \

  /path/to/opal_directory . > patch_name.patch

If you are using TortoiseCVS in Windows, simply right-click on the project folder and go to CVS -> “Make Patch...”

4. Submit the patch file via the “Patches” link on the SourceForge project page.

Note: If SourceForge adds Subversion support (which they are currently testing), OPAL will probably switch over to that rather than CVS. The general patch submission process will be mostly unchanged, however.

Design Philosophy

This section contains a short description of the overall design philosophy. Remember, when in doubt, look at the existing source code.

OPAL has two main goals: 1) to provide a high-level physics interface, and 2) to provide an abstract interface that is independent of the underlying physics engines. Although some similar libraries focus mainly on #2, OPAL is more focused on #1. Even though #2 it important for comparing physics engines or using multiple physics engines in the same application, OPAL’s primary concern is giving developers a simple, powerful interface with high-level constructs.

The Simulator is a factory and container for all other objects, such as Solids, Joints, Motors, and Sensors.

All parts of the base OPAL code must be totally independent of the specific physics engines.

Supported physics engines should be cross-platform, with support for at least Linux and Win32.

Every main object has an internal Data class that defines the properties of the object. This makes it easy to copy, save, and load simulation
states. Thus, all information about an object needed to restore the state of the simulation should be added to that object's Data class. All variables in an object's Data class should be handled by the BlueprintManager when loading/saving XML files.

Coding Conventions

This section contains a set of coding conventions used in OPAL. Remember, when in doubt, look at the existing source code.

General

No space tabs! Use actual tabs for indentation, not spaces.

All curly braces should be on new lines (even for one-line if statements). For example:

if(test)
{

x = 5;
}

Keep each line to 80 characters or fewer.

Return types should be on same line as the function name (unless return type is long enough to hit the 80 character limit).

Every {} block is indented by one tab, including namespaces. For example:
namespace opal
{
if(condition)
{
// code
}
}

Capitalization Styles and Naming Conventions

“Pascal casing” capitalizes the first letter of each word (e.g. FooBar)

“Camel casing” capitalizes the first letter of each word except the first one (e.g. fooBar)

Classes - Pascal casing
Local variables – Camel casing
Member variables – Pascal casing with “m” prefix
Namespaces – Camel casing
Functions – Camel casing
Function arguments – Camel casing
Internal Functions - Camel casing with “internal_” prefix (an internal function is a class member function that needs to be publicly accessible but should not be accessed through the API)

All get/set functions begin with “get” and “set” except get functions that return a boolean, in which case the name should start with “is” or “are.”

Source Code Documentation

It is important that the source code is well-documented in two ways: 1) all components of the public API should have a detailed description of their function; this information gets automatically incorporated into the Doxygen-generated API documentation, and 2) all potentially confusing source code should be explained in the code.

Use Doxygen triple slash commenting style (e.g. /// Some comment) in front of all class, function, variable, enum, namespace, etc. definitions. Otherwise use all double slash comments (e.g. // Some comment), not block comments (e.g. /* Some comment */). Most source code editors have built-in functions for selecting and commenting out chunks of code, and they usually use double slash comments.