Writing Primitives Using the PtMatrix Class

This section describes how to use the matrix data classes when writing primitives. Some examples are given here, more can be found among the primitives in $MLD→MLD Libraries→SDF→Matrix and $MLD→MLD Libraries→SDF→Image.

Memory management

The most important thing to understand about the use of matrix data classes in the MLDesigner environment is that primitives that intend to output the matrix in a particle should allocate memory for the matrix but never delete that matrix. Memory reclamation is done automatically by the reference-counting mechanism of the Message class. Strange errors will occur if the primitive deletes the matrix before it is used by another primitive later in the execution sequence.

Naming conventions

Primitives that implement general-purpose matrix operations usually have names with the _M suffix to distinguish them from primitives that operate on scalar particles. For example, the SDF primitive Gain_M multiplies an input matrix by a scalar value and outputs the resulting matrix. This is in contrast to SDF primitive MpyConstFloat (formerly known as Gain), which multiplies an input value held in a FloatParticle by a double and puts that result in an output FloatParticle.

Include files

To use the PtMatrix classes in a primitive, the file Matrix.h has to be included either in its .h or .cc file. If the primitive has a matrix data member, then the declaration

needs to be in the Primitive definition. Otherwise, the declaration

is sufficient.