# MatrixData¶

We have reached a point where passing matrices of floating point data is an increasingly important need.

## Use Cases¶

Can we come up with some concrete examples here? It would be helpful to make sure we don't overlook anything in the design.

- Maintaining state of the audio matrix objects
- Probable usage in the SpatLib
- ?

## Architecture¶

As a point of departure, let's begin by considering four C++ classes.

First there is a base class which we will call `TTMatrixData`

. In terms of an analog to examples with which we are already familiar, this might be the most like Jitter's jit.matrix. This is a structure that needs to represent:

- the number of matrix dimensions (e.g. 1, 2, 3, 4, ...)
- the sizes of the matrix dimensions (e.g. 320 x 240, 44100 x 2, ...)
- the datatype / bitdepth of the values in the matrix
- a pointer to the data
- methods to set the values, and get the values, etc.
- a way to copy the data
- a way to reference the data (i.e. increase a ref count) without copying it

Then we can subclass as appropriate. Immediate examples of subclasses are `TTAudioSignal`

, `TTAudioBuffer`

and `TTFMat`

.

The `TTAudioSignal`

already exists and the data for N channels or an M-length vectorsize is stored in a block of memory which is essentially a 64-bit floating-point matrix.

The `TTAudioBuffer`

object also already exists and carries a lot of overlap with `TTAudioSignal`

.

The `TTFMat`

object can be a 32-bit floating-point matrix that provides some means by which it is also convenient for working in FTM. A couple of ideas here:

`TTAudioSignal`

has mechanisms by which it can own its own data or refer to external data (could be useful for FTM too)- we could use function pointers and a "soft" linking so that when FTM is present then some function pointers are made non-null and then calling these function pointers will increase/decrease the FTM fmat ref count as needed.

## Data Structure¶

As alluded to earlier, the block of memory is envisaged as a K-dimensional matrix. Initial concerns will optimize for the 2-dimensional case of NxM (row major as in C++, Jitter, and FTM).

Jitter has the notion of "planes" whereby 4 "values" are stuffed into a single "cell". This terminology seems potentially confusing, particularly since planes often mean something else when working with linear algebraic equations. However, the concept is genuinely useful:

- storage of compound values in a matrix is useful, e.g. for complex numbers (FFT) as well as color (RGBA or other)
- keeping such compound values adjacent in memory (as opposed to separated in memory due to putting value fragments in additional dimensions) can vastly improve speed and performance

Rather than planes, let's refer to these as the `elements`

of a `matrix of compound values`

. In cases such as `TTFMat`

there will only be simple values, or in otherwords an `elementcount`

of 1 for the values in the matrix.