(v13) InterleaveDecode filter

This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP.

The InterleaveDecode filter is used to extract and transform packed samples from a bitstream. The filter expects a parameter dictionary and a source file object on the stack. The InterleaveDecode filter operates upon “windows” of data. Each window contains an initial number of bits to skip, a number of samples of the input depth, and a trailing number of bits to skip. The samples may be passed unchanged to the output, without the initial and trailing bits, or may be transformed to some other range of output values. The input may be aligned to a specified number of bits after processing a specified number of input windows, and the output may be aligned to a specified number of bits after processing a specified number of windows. (These options are typically used for aligning input and output for a scanline worth of image samples.) The parameter dictionary may contain the following entries:

Samples	positive integer (required)	The number of input samples in each window. Input samples are transformed to output values and are sent to the filter output.
InputBits	positive integer (optional)	This value is between `1-16` (inclusive), indicating the number of bits input for each sample value (default `8`).
BitsBefore	non-negative integer (optional)	This value indicates the number of bits to skip at the start of each input data window, before reading the data samples (default `0`).
BitsAfter	non-negative integer (optional)	This value indicates the number of bits to skip at the end of each input data window, after reading the data samples (default `0`).
InputAlignRepeat	non-negative integer (optional)	This value indicates the number of input “windows” to process before aligning the input sources. If zero, the input source will never be aligned (default `0`).
InputAlignBits	positive integer (optional)	If `InputAlignRepeat` is non-zero, then after that number of data windows are processed, the input source is aligned by reading extra bits such that a multiple of this number of bits has been read. The minimum number of bits to achieve the specified alignment is read. The default alignment is to byte boundaries (default `8`).
OutputBits	positive integer (optional)	This value is between `1-16` (inclusive), indicating the number of bits to output for each input sample. If a `/Mapping` parameter is provided, it specifies a lookup table between the input and output number of bits. Otherwise, a linear interpolation between the values storable in the number of input bits and the number of output bits are used (default is the same as `InputBits`).
OutputAlignRepeat	non-negative integer (optional)	This value indicates the number of input “windows” to process before aligning the filter output. If zero, the output is never aligned.(default `0`).
OutputAlignBits	positive integer (optional)	If `OutputAlignRepeat` is non-zero, then after that number of data windows are processed, the corresponding output source will be aligned by writing extra bits such that a multiple of this number of bits has been written. The minimum number of bits to achieve the specified alignment is written. The default alignment is to a byte boundary (default `8`).
Repeat	non-negative integer (optional)	This value indicates the number of windows to process. If zero, the filter keeps requesting data from its source until EOF is indicated by the source. If non-zero, this is the number of whole windows of data that is processed before the filter returns EOF. It may be useful to set this parameter to prevent the filter from reading more data than is applicable from an image source (default 0).
SeekSource	boolean (optional)	This value indicates if the filter source should have a `setfileposition` operation applied before reading each buffer of data. If this parameter is set to `true`, multiple `InterleaveDecode` filters can be used to extract interleaved data from the same source. The source must, however, be seekable (in general, that implies that the source is a file or a `ReusableStreamDecode` filter). A side-effect of setting this parameter to `true` is that the filter initialization immediately calls `fileposition` on the filter source, returning an ioerror if the position reading operation fails (default `false`).
Mapping	array (optional)	If specified, this parameter should be an array of length `2^InputBits` integers. The values in the array should be integers in the range `0 <= value < 2^OutputBits`. If this array is specified, it is used as a lookup table to transform input sample values to output values (default `unset`).