Input portholes

To declare an input port that accepts matrices, the following syntax is used:

input
{
  name { Input }
  type { float_matrix_env }
}

The syntax is the same for output ports. The type field can be COMPLEX_MATRIX_ENV, FLOAT_MATRIX_ENV, FIX_MATRIX_ENV, or INT_MATRIX_ENV. The icons created by MLDesigner will have terminals that are thicker and that have larger arrow points than the terminals for scalar particle types. The colors of the terminals follow the pattern of colors for scalar data types, e.g., blue represents float and FloatMatrix.

The syntax to extract a matrix from the input porthole is:

Envelope tInPkt;
(Input%0).getMessage(tInPkt);
const FloatMatrix& tInputMatrix = *(const FloatMatrix*)tInPkt.myData();

The first line declares an Envelope, which is used to access the matrix. Details of the Envelope class are given in Use of the Envelope Class. The second line fills the envelope with the input matrix. Note that, because of the reference-counting mechanism, this line does not make a copy of the matrix. The last line extracts a reference to the matrix from the envelope. It is up to the programmer to make sure that the cast agrees with the definition of the input port.

Because multiple envelopes might reference the same matrix, a primitive is generally not permitted to modify the matrix held by the Envelope. Thus, the function myData() returns a const Message *. This can be cast to be a const FloatMatrix * and then be de-referenced and assigned the value to tInputMatrix. It is generally better to handle matrices by reference instead of pointers because it is easier to write A + B rather than *A + *B when working with matrix operations. Primitives that wish to modify an input matrix should access it by using the writableCopy method, as explained in Use of the Envelope Class.