StateAllocator

Overview

Writes data into an internal circular state buffer and provides a reference for access

Discussion

This module writes incoming data to an internal circular state buffer. It outputs a "reference" frame which includes the heap and offset of the buffer, as well as the state write-index. The module is used in conjunction with downstream "user" modules which can interpret the frame to access the data. FIRUser is one such module.

The output frame has 7 words with the following zero-based indices and data:
[0] - buffer-offset relative to the start of the heap
[1] - whether the input data is complex (1) or not (0)
[2] - number of input channels (does not change if data is complex)
[3] - channel length (number of samples stored per channel, where complex values count as 1 sample only)
[4] - heap number where buffer is allocated (can differ from user argument in single-heap targets)
[5] - state index (points to the next write position in the buffer(s), which is the oldest kept sample)
[6] - whether the input was deinterleaved (1) or not (0)

The argument DELAYSAMPS specifies the number of samples to keep per-channel in addition to the input block (i.e. delay or past state). If used in conjunction with FIRUser, DELAYSAMPS must be greater-or-equal than numTaps-1. The channel length (chanLen) equals DELAYSAMPS + inBlockSize + makeEven samples, where inBlockSize is the blocksize of the input pin, and makeEven is calculated to make this sum even. This is the channel length that is sent in the output frame, and does not change if the input is complex. The total allocated buffer size has one extra sample, and it is doubled if the input is complex. This buffer is large enough so that a new block of data can be first written into the buffer and then data as old as DELAYSAMPS samples can be read out.

The argument MEMHEAP defines which heap will hold the state buffer.

The argument DEINTERLEAVE specifies whether the channels should be deinterleaved before storing, or whether to copy data as is (normally the input is interleaved). In deinterleave mode, samples from the same channel are stored sequentially, and each channel segment is exactly chanLen samples long. Each channel is treated as its own circular buffer, and a single state index is shared among all channels (i.e. the index is relative to the start of each channel). Complex values count as a single sample, so chanLen must be doubled to get the total number of words per channel (and hence the offset of the next channel). When not in deinterleave mode, a single large circular buffer is used and data is stored in the order it comes in. Complex values are stored interleaved regardless of mode (real, img, real, img, etc.)

See usage examples in the AllocatorUser_*.awd layouts found in the audioweaver/Examples/Module_Usage folder

Module Pack

Advanced

ClassID

classID = 1458

Type Definition

typedef struct _ModuleStateAllocator
{
ModuleInstanceDescriptor instance;            // Common Audio Weaver module instance structure
INT32 delaySamps;                             // Number of samples to keep per channel, in addition to input block (delay).
INT32 stateLen;                               // Size of the internal state buffer.
INT32 chanLen;                                // Per-channel state size.
INT32 stateHeapAlloc;                         // True heap in which array was allocated.
INT32 deinterleave;                           // If true, channels are deinterleaved before storing. Otherwise, input format is kept.
INT32 stateIndex;                             // Index of the oldest value in the state array.
INT32 stateHeap;                              // Heap in which to allocate memory.
UINT32 arrayOffset;                           // Heap offset where array is allocated.
FLOAT32* state;                               // State values array.
} ModuleStateAllocatorClass;

Variables

Properties

Name	Type	Usage	isHidden	Default Value	Range	Units
delaySamps	int	const	0	100	Unrestricted	samples
stateLen	int	derived	0	132	Unrestricted
chanLen	int	derived	0	132	Unrestricted
stateHeapAlloc	int	derived	0	1	Unrestricted
deinterleave	int	const	0	1	0:1
stateIndex	int	state	1	0	Unrestricted
stateHeap	int	const	1	1	Unrestricted
arrayOffset	uint	derived	1	0	Unrestricted
state	float*	state	1	[132 x 1]	Unrestricted

Pins

Input Pins


Name	in
Description	audio input
Data type	{float, int, fract32}
Channel range	Unrestricted
Block size range	Unrestricted
Sample rate range	Unrestricted
Complex support	Real and Complex

Output Pins


Name	S
Description	state buffer reference
Data Type	int

Matlab Usage

File Name: state_allocator_module.m 
 M = state_allocator_module(NAME, DELAYSAMPS, MEMHEAP, DEINTERLEAVE) 
 This module holds a circular buffer and is used in combination 
 with other "allocator" and "user" modules, such as the fir_user_module.m 
 Arguments: 
    NAME - name of the module. 
    DELAYSAMPS - number of samples to store per channel in addition to 
       input block samples (i.e. delay). 
       This partially specifies the size of the state/delay buffer. 
       By default, DELAYSAMPS = 100; 
    MEMHEAP - specifies the memory heap to use to allocate the main 
         state buffer. This is a string and follows the memory allocation 
         enumeration in Framework.h. Allowable values are: 
            'AWE_HEAP_FAST' - always use internal DM memory (default). 
            'AWE_HEAP_FASTB' - always use internal PM memory. 
            'AWE_HEAP_SLOW' - always use external memory. 
            'AWE_HEAP_SHARED' - always use shared memory. 
    DEINTERLEAVE - specifies whether channels are deinterleaved before 
       storing or not. Default is DEINTERLEAVE = 1 (true).