Top Up Prev Next Bottom Contents Index Search

4.7 Unsupported Types

There are a number of data types in Ptolemy that we recommend not be used by external developers because they are either insufficiently mature or likely to change. This section briefly describes those classes.

4.7.1 Sub-matrices

The Ptolemy kernel contains a set of matrices to support efficient computation with sub-matrices. These classes were developed specifically for the experimental multidimensional SDF (MDSDF) domain and will probably be implemented differently in a future release.

There are four sub-matrix classes, one for each concrete matrix class: ComplexSubMatrix, FixSubMatrix, FloatSubMatrix, and IntSubMatrix, each of which inherits from the corresponding PtMatrix class. A sub-matrix contains a reference to a "parent" matrix of the same type, and modifies its internal data pointers and matrix size parameters to reference a rectangular region of the parent's data. The constructors for the submatrix classes have arguments that specify the region of the parent matrix referenced by the sub-matrix.

As for matrices, the description of sub-matrices uses the convention that XXX means Complex, Fix, Float, or Int, and xxx means Complex, Fix, double, or int.

The submatrix constructors are:


Create an uninitialized matrix.

XXXSubMatrix(int numRow, int numCol)

Create a regular matrix with dimensions numRow by numCol; return a new submatrix with this matrix as its parent. Memory is allocated for the data storage but the entries are uninitialized.

XXXSubMatrix(XXXSubMatrix& src, int sRow, int sCol, int nRow, int nCol)

Create a sub-matrix of the given dimensions and initialize it to reference the region of the parent matrix starting at (sRow, sCol) and of size (nRow, nCol). The parent matrix is the same as the parent matrix of src. The given dimensions must fit into the parent matrix, or an error will be flagged. Unlike the "sub-matrix" constructors in the regular matrix classes, this constructor does not copy matrix data.

XXXSubMatrix(const XXXSubMatrix& src)

Make a duplicate of the src sub-matrix. The parent of the new matrix is the same as the parent of src.

Submatrices support all operations supported by the regular matrix classes. Because the matrix classes uniformly use only the entry() and operator [] member functions to access the data, the sub-matrix classes need only to override these functions, and all matrix operations become available on sub-matrices.

xxx& entry(int i)

Return the ith entry of the sub-matrix when its data storage is considered to be a linear array.

xxx* operator [] (int row)

Return a pointer to the start of the row of the sub-matrix's data storage.

Using sub-matrices in stars

Sub-matrices are not currently useful in general-purpose dataflow stars. Rather, they were developed to provide an efficient means of referencing portions of a single larger matrix in the multi-dimensional synchronous dataflow (MDSDF) domain. We give here a summary. For more details, see [Che94] and the MDSDF sources in $PTOLEMY/src/domains/mdsdf/kernel and $PTOLEMY/src/domains/mdsdf/stars.

Unlike other domains, the MDSDF kernel does not transfer particles through FIFO buffers. Instead, each geodesic keeps a single copy of a "parent" matrix, that represents the "current" two-dimensional datablock. Each time a star fires, it obtains a sub-matrix that references this parent matrix with the getOutput() function of the MDSDF input port class. For example, a star might contain:

FloatSubMatrix* data = (FloatSubMatrix*)(input.getInput()); Note that this is not really getting a matrix, but a sub-matrix that references a region of the current data matrix. The size of the sub-matrix has been set by the star in its initialization code by calling the setMDSDFParams() function of the port.

To write data to the output matrix, the star gets a sub-matrix which references a region of the current output matrix and writes to it with a matrix operator. For example,

FloatSubMatrix* result = (FloatSubMatrix*)(output.getOutput());
result = -data;
Because the sub-matrices are only references to the current matrix on each arc they must be deleted after use:

delete &input;
delete &result;
Here is a simplified example of a complete MDSDF star:

defstar {
name { Add }
domain { MDSDF }
desc {
Matrix addition of two input matrices A and B to
produce matrix C. All matrices must have the same
version { %W% %G% }
author { Mike J. Chen }
location { MDSDF library }
input {
name { Ainput }
input {
name { Binput }
output {
name { output }
defstate {
name { numRows }
type { int }
default { 2 }
desc { The number of rows in the input/output matrices. }
defstate {
name { numCols }
type { int }
default { 2 }
desc { The number of columns in the input/output
matrices. }
ccinclude { "SubMatrix.h" }
setup {
Ainput.setMDSDFParams(int(numRows), int(numCols));
Binput.setMDSDFParams(int(numRows), int(numCols));
output.setMDSDFParams(int(numRows), int(numCols));
go {
// get a SubMatrix from the buffer
FloatSubMatrix& input1
= *(FloatSubMatrix*) (Ainput.getInput());
FloatSubMatrix& input2
= *(FloatSubMatrix*)(Binput.getInput());
FloatSubMatrix& result
= *(FloatSubMatrix*)(output.getOutput());

// compute product, putting result into output

result = input1 + input2;

delete &input1;
delete &input2;
delete &result;

The sub-matrix "particles"

The ptlang type of submatrices is FLOAT_MATRIX, INT_MATRIX, and so on. (This is not documented in the User's Manual and is likely to change in a future release.) Each of these ptlang types is implemented by a sub-class of Particle: IntMatrixParticle, FloatMatrixParticle, FixMatrixParticle and ComplexMatrixParticle. These particle classes exist only for setting up the portholes and performing type-checking-they are never created or passed around during a simulation. Instead, sub-matrices are created and destroyed by the MDSDF kernel and stars as described above.

4.7.2 Image particles

A set of experimental image data types, designed to make it convenient to manipulate images and video sequences in Ptolemy, were defined by Paul Haskell. They are based on Ptolemy's built-in Message type, described above. A library of stars that uses these image data types can be found in the image library of the DE domain.

This set of classes is being replaced by the PtMatrix classes, and the SDF image classes now all use PtMatrix. We give here a brief introduction to the image data types used in the DE domain, although new work should consider using PtMatrix classes instead. Class definitions can be found in $PTOLEMY/src/domains/de/kernel.

The base class of all the image classes is called BaseImage. It has some generic methods and members for manipulating images. Most of the methods are redefined in the derived classes. The fragment method partitions an image into many smaller images, which together represent the same picture as the original. The assemble method combines many small images which make up a single picture into a single image that contains the picture. The fragment method works recursively, so an image that has been produced by a previous fragment call can be further fragmented. Assembly always produces a full-sized image from fragments, however small.

Use of the size, fullSize, and startPos members varies within each subclass. Typically the size variable holds the number of pixels that an object is storing. If an object is not produced by fragment(), then (size == fullSize). If the object is produced by a fragment() call, size may be less than or equal to fullSize. An objects's fullSize may be bigger or smaller than width*height. It would be bigger, for example, in DCTImage, where the amount of allocated storage must be rounded up to be a multiple of the blocksize. It would be smaller, for example, for an object that contains run-length coded video.

The frameId variable is used during assembly. Fragments with the same frameId's are assembled into the same image. So, it is important that different frames from the same source have different frameIds.

The comparison functions {==, !=, <, >, etc.} compare two objects' frameId's. They can be used to resequence images or to sort image fragments.

The copy constructor and clone methods have an optional integer argument. If a nonzero argument is provided, then all state values of the copied object are copied to the created object, but none of the image data is copied. If no argument or a zero argument is provided, then the image data is copied as well. Classes derived from BaseImage should maintain this policy.

The GrayImage class, derived from BaseImage, is used to represent gray-scale images. The DCTImage class is used to represent images or image fragments that have been encoded using the discrete-cosine transform. The MVImage class is a bit more specialized; it stores a frame's worth of motion vectors.

4.7.3 "First-class" types

All of the types built-in to the Ptolemy kernel are "first-class" in the sense that they are understood by pigi and ptlang. We recommend that users create their own types using the mechanism described in "Defining New Data Types" on page 4-14. This approach has the disadvantage that all user-defined types are seen by pigi and ptlang as being of type "message." If this is not acceptable, then it is possible to create your own first-class types by sub-classing Particle and adding the new types to VEM. The following instructions briefly describes this process. We stress, however, that this method is not officially supported and that types created this way will probably have to be reworked in a future release of Ptolemy. You will need to use some other color-say fileColor-as a sample to follow when modifying the various source files.

Top Up Prev Next Bottom Contents Index Search

Copyright © 1990-1997, University of California. All rights reserved.