NAME

Rivl_SignalHaveRegion - return an upper bound on the non-zero data of a signal

SYNOPSIS

#include <rivl.h>
Rivl_Region
Rivl_SignalHaveRegion (interp, signal, sampleRate);

ARGUMENTS

Tcl_Interp *interp (in)
The Tcl interpreter.
Rivl_Signal signal (in)
Signal to query.
Rivl_Point sampleRate (in)
Sample rate at which the region should be expressed.

DESCRIPTION

Rivl_SignalHaveRegion returns the have region of signal in terms of sampleRate. The caller is responsible for eventually freeing the region with Rivl_RegionDestroy.

The have region of a signal is an upper bound on the region of non-zero data in the signal. Any value sampled outside the have region is guaranteed to be zero. For example, consider the images created by the following code:

set image [im_read tiger.jpg] 
im_clear! image 0 0 100 100
im_scaleC! image 0.5
im_rotateC! image 30
. . . . . .

The have region for each image is outlined with dashes. Notice that the have region for the final image is overestimated: this is because all regions must be stored as a small set of rectangles.

The have region is used for optimizing computation. When Rivl_ComputeSignalData is asked to compute some region N of a signal, it intersects N with the signal's have region and computes just the intersection. It knows that anything outside the intersection is either unneeded or zero.

It is permissible for the have region to be overestimated or even set to the infinite region - this merely reduces the effectiveness of the optimization. However, the have region must not be underestimated or Rivl_ComputeSignalData may fail to compute valid data.

The have region for a signal is computed by recursively computing the have regions of the input signals, if any, and then transforming these regions by the computeHaveRegionProc procedure specified in the class of the signal's node.