GAS_StencilUtils.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        GAS_StencilUtil.h (GAS Library, C++)
 *
 * COMMENTS:
 *  This file contains convenience macros for performing stencilled operations
 *  in a generic way.
 *
 *  These macros are meant to be used roughly as follows:
 *      UT_VoxelArrayIteratorF iter(dst->fieldNC());
 *      DECLARE_STENCIL_VARIABLES(dst)
 *      for(iter.rewind(); !iter.atEnd(); iter.advance())
 *      {
 *          if(iter.isStartOfTile())
 *          {
 *              CHECK_STENCIL_TILE(iter)
 *          }
 *          CHECK_STENCIL_VOXEL(iter)
 *          ...
 *          iter.setValue(...);
 *      }
 *
 *  `SIM_RawField* dst` is the destination field that we're iterating over, and
 *  `const SIM_RawField* stencil` is the required signature of the stencil
 *  field. The following variables will also be defined
 *  (by DECLARE_STENCIL_VARIABLES):
 *      - `float cstencilval` -- last known constant value of the stencil (only
 *        applies when conststencil is true);
 *      - `bool conststencil` -- true if stencil values are known to be constant
 *        in the current tile (in this case, the constant value is cstencilval);
 *      - `SIM_ScalarFieldSampler stencilsampler` -- sampler object to probe
 *        stencil values.
 */

#include <SIM/SIM_FieldSampler.h>

/// Declares the variables needed to check stencil values. These variables are
/// updated and used by the subsequent macros.
#define DECLARE_STENCIL_VARIABLES(dst)                                         \
    float cstencilval = 1;                                                     \
    bool conststencil = true;                                                  \
    SIM_ScalarFieldSampler stencilsampler;                                     \
    if (stencil)                                                               \
        stencilsampler.init(dst, stencil);

/// This macro checks the stencil value in the current destination tile. If the
/// stencil tile is constant and below the active threshold, the whole tile will
/// be skipped.
#define CHECK_STENCIL_TILE(iterator)                                           \
    if (stencil)                                                               \
    {                                                                          \
        conststencil = stencilsampler.isTileConstant(iterator, cstencilval);   \
        if (conststencil && cstencilval <= 0.5f)                               \
        {                                                                      \
            iterator.skipToEndOfTile();                                        \
            continue;                                                          \
        }                                                                      \
    }

/// This macro checks the stencil value in the current destination tile. Whether
/// the tile can be skipped is stored in skip_value, but iterator is left
/// untouched.
#define CHECK_STENCIL_TILE_NOSKIP(iterator, skip_value)                        \
    skip_value = false;                                                        \
    if (stencil)                                                               \
    {                                                                          \
        conststencil = stencilsampler.isTileConstant(iterator, cstencilval);   \
        skip_value = (conststencil && cstencilval <= 0.5f);                    \
    }

/// This macro will check the stencil value for the current voxel and skip if
/// it's not active.
#define CHECK_STENCIL_VOXEL(iterator)                                          \
    if (!conststencil && stencilsampler.getValue(iterator) <= 0.5f)            \
        continue;

/// This macro will check the stencil value for the current voxel. Whether the
/// voxel can be skipped is stored in skip_value, but iterator is left
/// untouched.
#define CHECK_STENCIL_VOXEL_NOSKIP(iterator, skip_value)                       \
    skip_value = (!conststencil && stencilsampler.getValue(iterator) <= 0.5f);