OpenDCX

Deep Compositing Extended

OpenDCX 2.2.2 documentation

Coding & Documentation

Coding

OpenDCX code conforms to the OpenEXR coding style since the intention is the eventual inclusion of the library into the OpenEXR project (and is the reason why OpenDCX’s major/minor version tracks OpenEXR.)

The OpenEXR project does not appear to have a published coding style document so OpenDCX code simply tries to look like OpenEXR code the best it can.

OpenEXR code is not formatted to be autodoc (doxygen/sphinx/etc) friendly. Unfortunately this means OpenDCX code is also not formatted to be autodoc friendly, however a Python script is used to parse the header files and create Sphinx-compatible reStructuredText(.rst) doc files. It’s a pretty dumb parser and is relatively successful but relies on fairly simple C++ stuctures so it can easily be fooled.

To help produce nice looking .rst code there’s some custom Directives that guide the parser’s output formatting.

Documenting Code

The more common C-style comment block delimiters /* */ are not used in the OpenEXR code so autodoc generators like doxygen will not produce very pleasing output.

To translate these headers into Sphinx compatible .rst files we’re using a modified version of an OpenColorIO Python script which looks for OpenEXR-style comment blocks starting and ending with //-- lines, and translate them into .rst declarations while also allowing embedded .rst directives to pass through.

For example the DeepPixel.h excerpt below includes a label declaration with the custom directive !rst:left-align:: which declares the indent handling of the comment block and directs the rest of the comment to the output .rst file. The leading comment block is surrounded by //-- lines is trapped and the content is turned into descriptions for classes/functions/types/vars, or if the first line in the comment starts with a !rst:: directive then the contents are added directly to the output .rst file.

Comments wrapped in character sequences other than //-- are not considered comment blocks and can be used for general header documentation. See below where the class DeepPixel title block is solely for header readability.

//-------------------------
//!rst:left-align::
//.. _deeppixel_class:
//
//DeepPixel
//*********
//-------------------------

//=====================
//
//  class DeepPixel
//
//=====================
//----------------------------------------------------------------------------------------
//
//  Contains a series of DeepSegments and their associated Pixels (containing float
//  channel data,) which combined together comprise a series of deep samples.
//
//  Supports metadata storage for each deep sample and offers methods to aid the
//  manipulation of samples within the deep pixel, including compositing (flattening,)
//  and sorting.
//  Because a DeepSegment is lightweight the list can be rearranged and sorted very
//  quickly.  The list of large Pixel channel data structures is kept static.
//
//  ::
//
//      TODO: investigate cost of using varying-sized Pixel channel array
//      TODO: extend flatten methods to accept near/far depth range to flatten within
//
//----------------------------------------------------------------------------------------

class DCX_EXPORT DeepPixel
{
  public:

    //------------------------------------------------------
    // Segment interpolation modes for flattening operations
    //------------------------------------------------------

    enum InterpolationMode
    {

And here’s the .rst code created created from the above example:

.. _deeppixel_class:

DeepPixel
*********


.. cpp:class:: DeepPixel

    Contains a series of DeepSegments and their associated Pixels (containing float
    channel data,) which combined together comprise a series of deep samples.

    Supports metadata storage for each deep sample and offers methods to aid the
    manipulation of samples within the deep pixel, including compositing (flattening,)
    and sorting.
    Because a DeepSegment is lightweight the list can be rearranged and sorted very
    quickly.  The list of large Pixel channel data structures is kept static.

    ::

        TODO: investigate cost of using varying-sized Pixel channel array
        TODO: extend flatten methods to accept near/far depth range to flatten within

.. cpp:type:: InterpolationMode

    Segment interpolation modes for flattening operations

And here’s the html output from Sphinx:

DeepPixel

class DeepPixel

Contains a series of DeepSegments and their associated Pixels (containing float channel data,) which combined together comprise a series of deep samples.

Supports metadata storage for each deep sample and offers methods to aid the manipulation of samples within the deep pixel, including compositing (flattening,) and sorting. Because a DeepSegment is lightweight the list can be rearranged and sorted very quickly. The list of large Pixel channel data structures is kept static.

TODO: investigate cost of using varying-sized Pixel channel array
TODO: extend flatten methods to accept near/far depth range to flatten within
enum class InterpolationMode

Segment interpolation modes for flattening operations

Directives

Note

The default directive for comment blocks without a directive is !rst:indent::.

!rst:indent::

Indents the comment text with the left edge alignment taken from the first active line in the comment. The allows arbitrary indentation in the comment block to be retained but indents the entire block.

//-----------------------------------------------------
//!rst:indent::
//  This text will be indented 4 spaces from the left
//  to be inside the class definition.
//
//  ::
//
//      This will be too but retaining the additional
//      arbitrary indents.
//          Foo
//              Bar
//------------------------------------------------------
class FooBar
{

produces:

|

.. cpp:class:: FooBar
    This text will be indented 4 spaces from the left
    to be inside the class definition.

    ::

        This will be too but retaining the additional
        arbitrary indents.
            Foo
                Bar

|

!rst:left-align::

Inserts raw rst text aligning the left edge with the first active line in the comment.

//-----------------------------------------------------
//!rst:left-align::
//  .. _foobar_class:
//
//  FooBar
//  ******
//
//  ::
//
//      This will be left-aligned based on the indent of the
//      first line '.. _foobar_class'
//------------------------------------------------------

produces:

.. _foobar_class:

FooBar
******

::
    This will be left-aligned based on the indent of the
    first line '.. _foobar_class'

!rst:: , !rst::raw::

Inserts raw rst text. Any indentation after the leading // will be preserved which may cause Sphinx parsing problems.

//-----------------------------------------------------------------
//!rst::
//  .. _foobar_class:
//
//  FooBar
//  ******
//
//  << The leading spaces will cause an indent warning from Sphinx
//-----------------------------------------------------------------

produces:

|

  !rst::
  .. _foobar_class:

  FooBar
  ******

  << The leading spaces will cause an indent warning from Sphinx

|

This however will work ok:

//---------------------------------
//!rst:raw::
//.. _foobar_class:
//
//FooBar
//******
//
//<< This is ok, no leading spaces
//---------------------------------