NAME

Rivl_ComputeSignalData - compute a region of a signal's data to a buffer

SYNOPSIS

#include <rivl.h>
int
Rivl_ComputeSignalData (interp, outSignal, needRegion, sampleRate, outBufPtr)

ARGUMENTS

Tcl_Interp *interp (in)
The Tcl interpreter.
Rivl_Signal outSignal (in)
Signal to compute data from.
Rivl_Region needRegion (in)
Region of signal to compute.
Rivl_Point sampleRate (in)
Sample rate at which to compute.
Rivl_Buf *outBufPtr (in, out)
Pointer to existing buffer in which to compute data, or pointer to fill with new buffer.

DESCRIPTION

Rivl_ComputeSignalData computes a region of a signal's data to a buffer.

needRegion indicates the region of data to compute. It will be automatically intersected with the have region of the signal.

There are two options for the value of outBufPtr. If *outBufPtr points to an existing buffer, then it is filled with the data. The buffer must contain room for at least the needRegion. Values in the buffer inside needRegion must be initialized to zero - this is true if the buffer comes directly from Rivl_BufCreate. Values outside needRegion will not be touched by this procedure.

If *outBufPtr instead points to NULL, then Rivl_ComputeSignalData allocates a new buffer and points *outBufPtr to it. The caller is responsible for freeing this buffer. The area of the new buffer is only guaranteed to be large enough to hold the non-zero data in needRegion. In particular, it may not be as large as needRegion if zero data was detected and cropped.

sampleRate indicates the sample rate at which needRegion and outBufPtr are expressed. This is illustrated in the second example below.

EXAMPLES

The first body of code below computes all the non-zero pixels of an image signal. The second body of code computes the data of an audio signal in the range from 2.0 seconds to 4.0 seconds at 21,000 samples per second (yielding a total of 42,000 values.) Error checking is omitted in both examples.

Rivl_Signal image, audio;
Rivl_Region needRegion;
Rivl_Buf buf;
Rivl_Box needBox;

needRegion = Rivl_SignalHaveRegion (interp, image, Rivl_UnitPoint());
Rivl_BufNew (interp, Rivl_SignalType(image), Rivl_RegionClipBox(needRegion), &buf);
Rivl_ComputeSignalData(interp, image, needRegion, Rivl_UnitPoint(), &buf);

needBox = BoxCreate(2.0 * 21000, 0, 4.0 * 21000, 1);
needRegion = Rivl_RegionCreateFromBox(needBox);
Rivl_BufNew (interp, Rivl_SignalType(audio), needBox, &buf);
Rivl_ComputeSignalData(interp, audio, needRegion, Rivl_PointCreate(21000, 1), &buf);