1.1.5 OcaMatrix

Class Hierarchy:

OcaRoot → OcaWorker → OcaMatrix

class OcaMatrix : OcaWorker

A matrix is a rectangular array of identical objects (” members “) that is coordinate addressable and has sets of common input and output ports. The matrix host does not instantiate these objects, but instead mediates the coordinate addressing, implements the common input and output ports, and provdes certain other aggregate functions. Matrix members may be workers (including blocks), or agents. All members of a matrix must be of the same class. No object may belong to more than one matrix at a time. No object may appear more than once in a given matrix. The complete model of an OCA matrix consists of: 1. One instance of OcaMatrix. 2. (N x M) members , where each member is an instance of a worker or agent class. For any given matrix, this class must be the same for all members, and is referred to as the member class. Members are sometimes referred to as cells of the matrix. 3. One additional instance of the member class, called the matrix proxy. Thus, the OcaMatrix instance is a container for the two-dimensional collection of its members. Once a matrix is set up, the controller may get and set member properties by the following procedures: Get To get a property value of member (x1, y1): 1. Controller calls OcaMatrix.SetXY(x1, y1) . This action: - locks the OcaMatrix instance, and - posts x1 and y1 as coordinates of the object whose property value is to be retrieved. 2. Controller calls the matrix proxy’s Get method for the property value desired. This action causes the OcaMatrix instance to: - decode the posted x1 and y1 values into a member ONo. - call the given Get method for the object identified by the decoded ONo. - aggregate the OcaResult from each Get call into a consolidated OcaResult . - unlock the OcaMatrix instance. - return the consolidated OcaResult to the controller. Set To set a property value of member (x1, y1), or of row (0, y1) or column (x1, 0) or whole matrix (0,0) 1. Controller calls OcaMatrix.SetXY(x1, y1) . This action: - locks the OcaMatrix instance, and - posts x1 and y1 as coordinates of the object whose property value is to be changed. 2. Controller calls the matrix proxy’s Set method for the target property. This action causes the OcaMatrix instance to: - decode the posted x1 and y1 values into a list of target member ONos, as follows: If x1 > 0 and y1 > 0, the list will be the single ONo of the addressed cell. If x1 = 0 and y1 > 0, the list will be the list of ONos of the cells in row y1 . If x1 > 0 and y1 = 0, the list will be the list of ONos of the cells in column x1. If x1 = 0 and y1 = 0, the list will be the list of ONos of all cells of the matrix. - call the given Set method for each target member in the ONo list. - aggregate the OcaResult from each Set call into a consolidated OcaResult . - unlock the OcaMatrix instance.

Properties:

static const OcaClassID ClassID = "1.1.5"

Number that uniquely identifies the class. Note that this differs from the object number, which identifies the instantiated object. This property is an override of the OcaRoot property.

This property has id 3.1.

static const OcaClassVersionNumber ClassVersion = 2

Identifies the interface version of the class. Any change to the class definition leads to a higher class version. This property is an override of the OcaRoot property.

This property has id 3.2.

OcaMatrixCoordinate X

Active column index. The active column is the column to which matrix proxy method calls will be reflected. Value is zero-relative, i.e. the first column is number zero. A value of 65535 means all columns in the matrix.

This property has id 3.1.

OcaMatrixCoordinate Y

Active row index. The active row is the row to which matrix proxy changes will be reflected. Value is zero-relative, i.e. the first row is number zero. A value of 65535 means all rows in the matrix.

This property has id 3.2.

OcaMatrixCoordinate xSize

Number of columns in the matrix. Readonly in some cases.

This property has id 3.3.

OcaMatrixCoordinate ySize

Number of rows in the matrix. Readonly in some cases.

This property has id 3.4.

OcaList2D<OcaONo> Members

2D array of member object numbers.

This property has id 3.5.

OcaONo Proxy

Object number of the matrix proxy.

This property has id 3.6.

OcaUint8 PortsPerRow

Number of input ports per row- e.g. for a stereo matrix, the value would be 2.

This property has id 3.7.

OcaUint8 PortsPerColumn

Number of output ports per column - e.g. for a stereo matrix, the value would be 2.

This property has id 3.8.

Properties inherited from OcaWorker:

Properties inherited from OcaRoot:

Methods:

OcaStatus GetCurrentXY(OcaMatrixCoordinate &x, OcaMatrixCoordinate &y)

Gets coordinates of the currently active area (cell, row, column, or whole matrix). The returned status indicates whether the operation was successful.

This method has id 3.1.

Parameters

  • OcaMatrixCoordinate x – Output parameter.

  • OcaMatrixCoordinate y – Output parameter.

OcaStatus SetCurrentXY(OcaMatrixCoordinate x, OcaMatrixCoordinate y)

Sets the currently active area (cell, row, column, or whole matrix). The returned status indicates whether the operation was successful.

This method has id 3.2.

Parameters

  • OcaMatrixCoordinate x – Input parameter.

  • OcaMatrixCoordinate y – Input parameter.

OcaStatus GetSize(OcaMatrixCoordinate &xSize, OcaMatrixCoordinate &ySize, OcaMatrixCoordinate &minXSize, OcaMatrixCoordinate &maxXSize, OcaMatrixCoordinate &minYSize, OcaMatrixCoordinate &maxYSize)

Gets the matrix size. The returned status indicates whether the operation was successful.

This method has id 3.3.

Parameters

  • OcaMatrixCoordinate xSize – Output parameter.

  • OcaMatrixCoordinate ySize – Output parameter.

  • OcaMatrixCoordinate minXSize – Output parameter.

  • OcaMatrixCoordinate maxXSize – Output parameter.

  • OcaMatrixCoordinate minYSize – Output parameter.

  • OcaMatrixCoordinate maxYSize – Output parameter.

OcaStatus SetSize(OcaMatrixCoordinate xSize, OcaMatrixCoordinate ySize)

Sets the matrix size. The returned status indicates whether the operation was successful. This method will not be available for fixed-size matrices.

This method has id 3.4.

Parameters

  • OcaMatrixCoordinate xSize – Input parameter.

  • OcaMatrixCoordinate ySize – Input parameter.

OcaStatus GetMembers(OcaList2D<OcaONo> &members)

Retrieves the 2D array of member object numbers. Cells for which no member has been defined will return Zero as the object number.

This method has id 3.5.

Parameters

OcaList2D<OcaONo> members – Output parameter.

OcaStatus SetMembers(OcaList2D<OcaONo> members)

Sets the entire 2D array of member object numbers. Row and column size of the members parameter must be equal to the current size of the matrix.

This method has id 3.6.

Parameters

OcaList2D<OcaONo> members – Input parameter.

OcaStatus GetMember(OcaMatrixCoordinate x, OcaMatrixCoordinate y, OcaONo &memberONo)

Retrieves the object number of the member at position (x,y). If no member is defined at this position, returns an object number value of Zero.

This method has id 3.7.

Parameters

  • OcaMatrixCoordinate x – Input parameter.

  • OcaMatrixCoordinate y – Input parameter.

  • OcaONo memberONo – Output parameter.

OcaStatus SetMember(OcaMatrixCoordinate x, OcaMatrixCoordinate y, OcaONo memberONo)

Installs a particular object as a member at position (x,y). If another object was at this position, it is removed.

This method has id 3.8.

Parameters

  • OcaMatrixCoordinate x – Input parameter.

  • OcaMatrixCoordinate y – Input parameter.

  • OcaONo memberONo – Input parameter.

OcaStatus GetProxy(OcaONo &ONo)

Gets the object number of the matrix proxy.

This method has id 3.9.

Parameters

OcaONo ONo – Output parameter.

OcaStatus SetProxy(OcaONo ONo)

Sets the object number of the matrix proxy.

This method has id 3.10.

Parameters

OcaONo ONo – Input parameter.

OcaStatus GetPortsPerRow(OcaUint8 &Ports)

Gets the number of ports per row. These are input ports.

This method has id 3.11.

Parameters

OcaUint8 Ports – Output parameter.

OcaStatus SetPortsPerRow(OcaUint8 Ports)

Sets the number of ports per row. These must be input ports.

This method has id 3.12.

Parameters

OcaUint8 Ports – Input parameter.

OcaStatus GetPortsPerColumn(OcaUint8 &Ports)

Gets the number of ports per output channel. These are output ports.

This method has id 3.13.

Parameters

OcaUint8 Ports – Output parameter.

OcaStatus SetPortsPerColumn(OcaUint8 Ports)

Sets the number of ports per column. These must be output ports.

This method has id 3.14.

Parameters

OcaUint8 Ports – Input parameter.

OcaStatus SetCurrentXYLock(OcaMatrixCoordinate x, OcaMatrixCoordinate y)

Sets the currently active area (cell, row, column, or whole matrix) and locks it. Fails if the referenced members cannot all be locked. The returned status indicates whether the operation was successful.

This method has id 3.15.

Parameters

  • OcaMatrixCoordinate x – Input parameter.

  • OcaMatrixCoordinate y – Input parameter.

OcaStatus UnlockCurrent()

Unlocks the currently active area of the matrix. Fails if all the members of the currently active area cannot be unlocked. Failure is _not_ triggered if one or more members of the currently active area are already unlocked at the time Unlock() is called. The returned status indicates whether the operation was successful.

This method has id 3.16.

Methods inherited from OcaWorker:

Methods inherited from OcaRoot: