Jamoma API  0.6.0.a19
TTMatrixBase Class Reference

2-dimensional matrix of compound values with N elements each. More...

#include <TTMatrixBase.h>

+ Inheritance diagram for TTMatrixBase:
+ Collaboration diagram for TTMatrixBase:

Public Types

typedef TTInt32(* TTMatrixBaseOutOfBoundsHandler) (const TTInt32 index, const TTInt32 lowBound, const TTInt32 highBound)
 A function pointer for implementing handlers in the makeInBounds() method. More...
 
typedef void(* TTMatrixBaseIterator) (TTPtr c, const TTPtr a, const TTPtr b)
 A function pointer for implementing iterators used in the iterate() method. More...
 

Public Member Functions

TTErr setRowCount (const TTValue &aNewRowCount)
 Attribute accessor. More...
 
TTErr setColumnCount (const TTValue &aNewColumnCount)
 Attribute accessor. More...
 
TTErr setElementCount (const TTValue &newElementCount)
 Attribute accessor. More...
 
TTErr setType (const TTValue &aType)
 Attribute accessor. More...
 
TTErr setDimensions (const TTValue &someNewDimensions)
 Attribute accessor. More...
 
TTErr setDimensionsWithVector (const std::vector< TTInt32 > &newDimensions)
 Alternative to attribute accessor. More...
 
TTRowID getRowCount ()
 Simple data accessor. More...
 
TTColumnID getColumnCount ()
 Simple data accessor. More...
 
TTElementID getElementCount ()
 Simple data accessor. More...
 
TTUInt32 getComponentCount ()
 Simple data accessor. More...
 
TTErr getType (TTValue &returnedType) const
 Attribute accessor. More...
 
TTDataType getTypeAsDataType ()
 Simple data accessor. More...
 
TTSymbol getTypeAsSymbol ()
 Simple data accessor. More...
 
TTDataInfoPtr getTypeAsDataInfo ()
 Simple data accessor. More...
 
TTUInt32 getDataCount ()
 Simple data accessor. More...
 
TTUInt32 getComponentStride ()
 Simple data accessor. More...
 
TTErr getDimensions (TTValue &returnedDimensions) const
 Legacy attribute accessor. More...
 
TTErr clear ()
 Set every element in the matrix to zero. More...
 
TTErr fill (const TTValue &anInputValue, TTValue &anOutputValue)
 Fill every component in the matrix with the same value. More...
 
TTBoolean makeRowIDInBounds (TTRowID &i, TTMatrixBaseOutOfBoundsHandler handler=outOfBoundsWrap) const
 Make sure a TTRowID is within the limits set by RowCount. More...
 
TTBoolean makeColumnIDInBounds (TTColumnID &j, TTMatrixBaseOutOfBoundsHandler handler=outOfBoundsWrap) const
 Make sure a TTColumnID is within the limits set by ColumnCount. More...
 
TTBoolean makeElementIDInBounds (TTElementID &e, TTMatrixBaseOutOfBoundsHandler handler=outOfBoundsWrap) const
 Make sure a TTElementID is within the limits set by ElementCount. More...
 
TTBoolean makeInBounds (TTRowID &i, TTColumnID &j, TTMatrixBaseOutOfBoundsHandler handler=outOfBoundsWrap) const
 Make sure an (i,j) pair is within the limits set by RowCount & ColumnCount. More...
 
TTBoolean makeInBounds (TTRowID &i, TTColumnID &j, TTElementID &e, TTMatrixBaseOutOfBoundsHandler handler=outOfBoundsWrap) const
 Make sure an (i,j,e) set is within the limits set by RowCount, ColumnCount & ElementCount. More...
 
TTErr get (const TTValue &anInputValue, TTValue &anOutputValue) const
 Get the value of a component located at any location in 2-dimensional matrix. More...
 
template<typename T >
TTErr get2d (TTRowID i, TTColumnID j, T &data) const
 Get the value of a component located at (i,j) in a 2-dimensional matrix. More...
 
template<typename T >
TTErr get2d (TTRowID i, TTColumnID j, TTElementID e, T &data) const
 Get the value of element e of the component located at (i,j) in a 2-dimensional matrix. More...
 
TTErr set (const TTValue &anInputValue, TTValue &anOutputValue)
 Set the value of a component located at any location in an 2-dimensional matrix. More...
 
template<typename T >
TTErr set2d (TTRowID i, TTColumnID j, T data)
 Set the value of a component located at (i,j) in a 2-dimensional matrix. More...
 
template<typename T >
TTErr set2d (TTRowID i, TTColumnID j, TTElementID e, T data)
 Set the value of element e of the component located at (i,j) in a 2-dimensional matrix. More...
 
void referenceExternalData (TTPtr aDataPointer)
 You must proceed to set the various attributes, dimensions, etc. More...
 
TTBytePtr getLockedPointer ()
 Return a pointer to the matrix data, and lock the matrix so that others cannot access the data. More...
 
void releaseLockedPointer ()
 Release a locked pointer obtained using getLockedPointer(). More...
 
TTBoolean allAttributesMatch (const TTMatrixBase &anotherMatrix) const
 Compare the attributes of this matrix to another to see if they all match. More...
 
TTErr adaptTo (const TTMatrixBase &anotherMatrix)
 Set dimensions, element count, datatype, etc. More...
 
TTMatrixBaseoperator+ (const TTMatrixBase &B) const
 Add two matrices to produce a third matrix. More...
 
TTMatrixBaseoperator- (const TTMatrixBase &B) const
 Subtract matrix B from matrix A to produce matrix C. More...
 
- Public Member Functions inherited from TTDataObjectBase
TTErr calculate (const TTMatrixArray *inputs, TTMatrixArray *outputs)
 
- Public Member Functions inherited from TTObjectBase
virtual ~TTObjectBase ()
 Destructor.
 
TTUInt16 getReferenceCount ()
 Query an object to get its current reference count. More...
 
TTUInt32 getObserverCount () const
 Query an object to get the number of observers. More...
 
TTErr registerAttribute (const TTSymbol name, const TTDataType type, void *address)
 Register an attribute. More...
 
TTErr extendAttribute (const TTSymbol name, const TTObjectBasePtr extendedObject, const TTSymbol extendedName)
 Extend the attribute of an existing TTObjectBase to this TTObjectBase (using another attribute name) More...
 
TTErr removeAttribute (const TTSymbol name)
 Remove an attribute. More...
 
TTErr findAttribute (const TTSymbol name, TTAttribute **attr)
 Find an attribute. More...
 
TTErr setAttributeValue (const TTSymbol name, TTValue &value)
 Set an attribute value for an object. More...
 
template<class T >
TTErr set (const TTSymbol aName, T aValue)
 Set an attribute value for an object This is the same as calling setAttributeValue(). More...
 
TTErr getAttributeValue (const TTSymbol name, TTValue &value)
 Get an attribute value for an object. More...
 
template<class T >
TTErr get (const TTSymbol aName, T &aReturnedValue)
 Get an attribute value for an object This is the same as calling getAttributeValue(). More...
 
TTSymbol getAttributeType (const TTSymbol name)
 Return the type of an attribute as a symbol. More...
 
TTErr getAttributeGetterFlags (const TTSymbol name, TTAttributeFlags &value)
 Get the getterFlags of an attribute. More...
 
TTErr setAttributeGetterFlags (const TTSymbol name, TTAttributeFlags &value)
 Set the getterFlags of an attribute. More...
 
TTErr getAttributeSetterFlags (const TTSymbol name, TTAttributeFlags &value)
 Get the setterFlags of an attribute. More...
 
TTErr setAttributeSetterFlags (const TTSymbol name, TTAttributeFlags &value)
 Set the setterFlags of an attribute. More...
 
TTErr registerAttributeProperty (const TTSymbol attributeName, const TTSymbol propertyName, const TTValue &initialValue, TTGetterMethod getter, TTSetterMethod setter)
 Register an attribute property. More...
 
TTErr registerMessageProperty (const TTSymbol messageName, const TTSymbol propertyName, const TTValue &initialValue, TTGetterMethod getter, TTSetterMethod setter)
 Register an message property. More...
 
TTErr getAttribute (const TTSymbol name, TTAttributePtr *attributeObject)
 Search for and locate an attribute. More...
 
TTErr getMessage (const TTSymbol name, TTMessagePtr *messageObject)
 Search for and locate a message. More...
 
void getAttributeNames (TTValue &attributeNameList)
 Return a list of names of the available attributes. More...
 
void getMessageNames (TTValue &messageNameList)
 Return a list of names of the available messages. More...
 
TTSymbol getName () const
 Return the name of this class. More...
 
TTErr registerMessage (const TTSymbol name, TTMethod method)
 Register a message with this object. More...
 
TTErr findMessage (const TTSymbol name, TTMessage **message)
 Find a message registered with this object. More...
 
TTErr removeMessage (const TTSymbol name)
 Remove a message. More...
 
TTErr sendMessage (const TTSymbol name)
 TODO: Document this function. More...
 
TTErr registerObserverForMessage (const TTObject &observingObject, const TTSymbol messageName)
 Register an observer for a message. More...
 
TTErr registerObserverForAttribute (const TTObject &observingObject, const TTSymbol attributeName)
 Register an observer for an attribute. More...
 
TTErr registerObserverForNotifications (const TTObject &observingObject)
 Register an observer. More...
 
TTErr unregisterObserverForMessage (const TTObject &observingObject, const TTSymbol messageName)
 Unregister an observer for a message. More...
 
TTErr unregisterObserverForAttribute (const TTObject &observingObject, const TTSymbol attributeName)
 Unregister an observer for an attribute. More...
 
TTErr unregisterObserverForNotifications (const TTObject &observingObject)
 Unregister an observer for notifications. More...
 
TTErr sendNotification (const TTSymbol name, const TTValue &arguments)
 Send a notification. More...
 
TTErr logMessage (TTImmutableCString fmtstring,...)
 Log messages scoped to this object instance. More...
 
TTErr logWarning (TTImmutableCString fmtstring,...)
 Log warnings scoped to this object instance. More...
 
TTErr logError (TTImmutableCString fmtstring,...)
 Log errors scoped to this object instance. More...
 
TTErr logDebug (TTImmutableCString fmtstring,...)
 Log messages (scoped to this object instance) to output only if the basic debugging flag is enabled in the environment. More...
 
TTErr lock ()
 Lock the object in order to ensure thread-safe processing. More...
 
TTErr unlock ()
 Unlock the object when thread-safe processing is no longer required. More...
 
TTBoolean isLocked ()
 Query if the object currently is locked for thread-safe processing. More...
 
TTBoolean waitForLock ()
 If the object is locked (e.g. More...
 

Static Public Member Functions

static TTInt32 outOfBoundsClip (const TTInt32 index, const TTInt32 lowBound, const TTInt32 highBound)
 In implementation of the TTMatrixBaseOutOfBoundsHandler that wraps #TTClip. More...
 
static TTInt32 outOfBoundsWrap (const TTInt32 index, const TTInt32 lowBound, const TTInt32 highBound)
 In implementation of the TTMatrixBaseOutOfBoundsHandler that wraps #TTInfWrap. More...
 
static TTInt32 outOfBoundsFold (const TTInt32 index, const TTInt32 lowBound, const TTInt32 highBound)
 In implementation of the TTMatrixBaseOutOfBoundsHandler that wraps #TTFold. More...
 
static TTErr copy (const TTMatrixBase &source, TTMatrixBase &dest)
 Copy the data from one matrix into another. More...
 
static TTErr iterate (TTMatrixBase *C, const TTMatrixBase *A, const TTMatrixBase *B, TTMatrixBaseIterator iterator)
 Step through every component in the matrix A and B to produce matrix C using the specified iterator method. More...
 
static TTErr iterateWhenAllAttributesMatch (TTMatrixBase *C, const TTMatrixBase *A, const TTMatrixBase *B, TTMatrixBaseIterator iterator)
 Only if all the attributes of matrix A and B match, then step through every component to produce matrix C using the specified iterator method. More...
 

Protected Member Functions

TTErr resize ()
 Internal method that resizes memory allocated when various attributes change. More...
 
virtual TTErr test (TTValue &returnedTestInfo)
 Unit test for the window function unit. More...
 
TTBoolean setRowCountWithoutResize (TTRowID aNewRowCount)
 Internal method that sets the value for RowCount without resizing the matrix of values. More...
 
TTBoolean setColumnCountWithoutResize (TTColumnID aNewColumnCount)
 Internal method that sets the value for ColumnCount without resizing the matrix of values. More...
 
TTBoolean setElementCountWithoutResize (TTElementID aNewElementCount)
 Internal method that sets the value for ElementCount without resizing the matrix of values. More...
 
TTBoolean setTypeWithoutResize (TTDataType aNewType)
 Internal method that sets the values for type-related variables without resizing the matrix of values. More...
 
- Protected Member Functions inherited from TTDataObjectBase
 TTDataObjectBase (const TTValue &arguments)
 Object constructor. More...
 
virtual ~TTDataObjectBase ()
 Object destructor. More...
 
TTErr setMatrixCalculate (TTMatrixCalculateMethod newMatrixCalculateMethod)
 Set the sample calculate routine to point to a method that is defined as an arg to this function. More...
 
TTErr setBypass (const TTValue &value)
 Bypass the audio processing routine and copy all input samples to the output unchanged. More...
 
TTErr bypassMatrixCalculate (const TTMatrixArray *inputs, TTMatrixArray *outputs)
 Built-in method to be used when calculation is to bypassed. More...
 
TTErr defaultMatrixCalculateMethod (const TTMatrixArray *inputs, TTMatrixArray *outputs)
 The default calculation method to use. More...
 
TTErr resetBenchmarking ()
 Reset internal values used when benchmarking performance. More...
 
TTErr getProcessingBenchmark (TTValueRef v)
 Do performance benchmarking. More...
 
- Protected Member Functions inherited from TTObjectBase
 TTObjectBase (const TTValue arguments)
 Constructor. More...
 

Protected Attributes

TTBytePtr mData
 memory used to store matrix values
 
TTRowID mRowCount
 How many rows of values the matrix should have. Uses an signed 32-bit integer which provides a maximum value of 2,147,483,647.
 
TTColumnID mColumnCount
 How many columns of values the matrix should have. Uses an signed 32-bit integer which provides a maximum value of 2,147,483,647.
 
TTElementID mElementCount
 How many elements (parts) per value (e.g. 2 for complex numbers, 4 for colors, default = 1). Uses an signed 16-bit integer which provides a maximum value of 32,767.
 
TTUInt32 mComponentCount
 mRowCount * mColumnCount
 
TTUInt32 mComponentStride
 how many bytes from one the beginning one matrix component to the next
 
TTUInt32 mDataCount
 mComponentCount * mElementCount (e.g. total number of floats or ints in the matrix)
 
TTDataType mType
 member of global enumerated list #TTBase::TTDataType (i.e., kTypeUInt8, kTypeUInt16, kTypeInt32, kTypeUInt64, kTypeFloat32, kTypeFloat64)
 
TTDataInfoPtr mTypeAsDataInfo
 pointer to info about the data type found in #TTBase::ttDataTypeInfo
 
TTSymbol mTypeAsSymbol
 symbol with data type name for the public interface
 
TTUInt8 mTypeSizeInBytes
 number of bytes present in mType
 
TTUInt32 mDataSize
 mTypeSizeInBytes * mDataCount
 
TTBoolean mDataIsLocallyOwned
 If false, then we are referencing outside memory which we don't own.
 
- Protected Attributes inherited from TTDataObjectBase
TTMatrixCalculateMethod mMatrixCalculateMethod
 This function pointer points to the active (non-bypass) calculate routine.
 
TTMatrixCalculateMethod mCurrentMatrixCalculateMethod
 This function pointer always points to the current calculate routine.
 
TTBoolean mBypass
 Are we bypassing the matrix calculation?
 
TTMatrixArraymInputArray
 If the calculate method is passed a matrix, rather than an array of matrices, we wrap it in this array.
 
TTMatrixArraymOutputArray
 If the calculate method is passed a matrix, rather than an array of matrices, we wrap it in this array.
 
TTFloat64 mStartProcessingTime
 The time at which this object's process method was last invoked (for benchmarking)
 
TTFloat64 mAccumulatedProcessingTime
 The amount of time spent in this object's process method (for benchmarking)
 
TTFloat64 mAccumulatedProcessingCalls
 The number of times the process method has been called (for benchmarking)
 
TTPtrSizedInt mReserved1
 Reserved – May be used for something in the future without changing the size of the struct.
 
TTPtrSizedInt mReserved2
 Reserved – May be used for something in the future without changing the size of the struct.
 
- Protected Attributes inherited from TTObjectBase
TTList observers
 List of all objects watching this object for life-cycle and other changes.
 

Additional Inherited Members

- Public Attributes inherited from TTObjectBase
TTBoolean valid
 If the object isn't completely built, or is in the process of freeing, this will be false.
 
TTBoolean track
 enable the print of a log message to ease the track of reference counting mechanism on an instance More...
 

Detailed Description

2-dimensional matrix of compound values with N elements each.

Each compound value stored in the matrix is known as a component. The number of elements in each component is variable, enabling the storage of things like complex numbers or RGBA colors. However, this element count for each component and their datatype is uniform across the entire matrix.

Definition at line 41 of file TTMatrixBase.h.

Member Typedef Documentation

typedef void(* TTMatrixBase::TTMatrixBaseIterator) (TTPtr c, const TTPtr a, const TTPtr b)

A function pointer for implementing iterators used in the iterate() method.

Parameters
[out]cpointer to matrix that holds the results of the operation
[in]apointer to matrix 1 of 2 for the iteration operation
[in]bpointer to matrix 2 of 2 for the iteration operation

Definition at line 608 of file TTMatrixBase.h.

typedef TTInt32(* TTMatrixBase::TTMatrixBaseOutOfBoundsHandler) (const TTInt32 index, const TTInt32 lowBound, const TTInt32 highBound)

A function pointer for implementing handlers in the makeInBounds() method.

The format for this function pointer follows most of the methods defined in TTLimits (i.e. TTClip, TTInfWrap, TTFold) which means they can be used here to handle out of bounds values. However, the methods defined in this class (i.e. outOfBoundsClip, outOfBoundsWrap, outOfBoundsFold) are safer because they handle considerations specific to TTMatrixBase.

Parameters
[in]indexreference to an index that will be checked and corrected if not in bounds
[in]lowBoundlowest value allowed for index
[in]highBoundhighest value allowed for index
Returns
TTInt32 new index value that is within bounds

TTLimits.h

Definition at line 278 of file TTMatrixBase.h.

Member Function Documentation

TTErr TTMatrixBase::adaptTo ( const TTMatrixBase anotherMatrix)

Set dimensions, element count, datatype, etc.

(i.e. the metadata describing a matrix) to match the another matrix which is passed-in as an argument.

Parameters
anotherMatrixmatrix to which you would like to conform the attributes of this one
Returns
TTErr kTTErrInvalidValue if operation is not completed, otherwise kTTErrNone

Definition at line 452 of file TTMatrixBase.cpp.

References kTTErrInvalidValue, mColumnCount, mElementCount, mRowCount, mType, resize(), setColumnCountWithoutResize(), setElementCountWithoutResize(), setRowCountWithoutResize(), and setTypeWithoutResize().

Referenced by TTSampleMatrix::adaptTo(), copy(), and iterate().

+ Here is the call graph for this function:

TTBoolean TTMatrixBase::allAttributesMatch ( const TTMatrixBase anotherMatrix) const

Compare the attributes of this matrix to another to see if they all match.

Used before conducting certain math operations.

Parameters
anotherMatrixmatrix that you would like to compare to this one
Returns
TTBoolean true if mType, mElementCount, mRowCount AND mColumnCount match, otherwise false

Definition at line 428 of file TTMatrixBase.cpp.

References mColumnCount, mElementCount, mRowCount, and mType.

Referenced by iterateWhenAllAttributesMatch(), and test().

TTErr TTMatrixBase::clear ( )

Set every element in the matrix to zero.

Returns
TTErr always returns kTTErrNone

Definition at line 237 of file TTMatrixBase.cpp.

References kTTErrNone, mData, and mDataSize.

Referenced by TTDataObjectBase::bypassMatrixCalculate(), and TTMatrix::clear().

TTErr TTMatrixBase::copy ( const TTMatrixBase source,
TTMatrixBase dest 
)
static

Copy the data from one matrix into another.

Parameters
[in]sourcematrix that you would like to copy FROM
[out]destmatrix that you would like to copy TO
Returns
TTErr kTTErrInvalidValue if operation is not completed, otherwise kTTErrNone

Definition at line 443 of file TTMatrixBase.cpp.

References adaptTo(), kTTErrNone, mData, and mDataSize.

Referenced by TTDataObjectBase::bypassMatrixCalculate(), TTMixer::setNumInputs(), and TTMixer::setNumOutputs().

+ Here is the call graph for this function:

TTErr TTMatrixBase::fill ( const TTValue anInputValue,
TTValue anOutputValue 
)

Fill every component in the matrix with the same value.

Parameters
[in]anInputValueTTValue array containing the elements used to fill matrix
[out]anOutputValueunused
Returns
TTErr always returns kTTErrNone

Definition at line 244 of file TTMatrixBase.cpp.

References kTTErrInvalidType, kTTErrNone, kTypeFloat32, kTypeFloat64, kTypeInt16, kTypeInt32, kTypeInt64, kTypeInt8, kTypeUInt16, kTypeUInt32, kTypeUInt64, kTypeUInt8, mComponentStride, mData, mDataSize, mElementCount, mType, mTypeSizeInBytes, and TTValue::size().

+ Here is the call graph for this function:

TTErr TTMatrixBase::get ( const TTValue anInputValue,
TTValue anOutputValue 
) const

Get the value of a component located at any location in 2-dimensional matrix.

Pass in coordinate pair using anInputValue. Returns via anOutputValue an mElementCount-item TTValue using the values stored at the coordinates specified by anInputValue. Remember that the first location in the matrix is row 0 and column 0. Used primarily as an interface to the matrix data from Jamoma implementations in Ruby and Max. To retrieve values from the matrix with less overhead, see the get2d() method.

Parameters
[in]anInputValueTTValue array containing the row and column values of coordinates
[out]anOutputValuemethod sets to a TTValue array containing element(s) found at the given coordinates
Returns
TTErr kTTErrWrongNumValues if anInputValue does not have 2 items, else kTTErrNone

Definition at line 341 of file TTMatrixBase.cpp.

References TTValue::append(), TTValue::clear(), INDEX_OF_COMPONENT_FIRSTBYTE, kTTErrNone, kTTErrOutOfBounds, kTTErrWrongNumValues, kTypeFloat32, kTypeFloat64, kTypeInt32, kTypeUInt8, makeInBounds(), mData, mElementCount, mType, mTypeSizeInBytes, and TTValue::size().

+ Here is the call graph for this function:

template<typename T >
TTErr TTMatrixBase::get2d ( TTRowID  i,
TTColumnID  j,
T &  data 
) const
inline

Get the value of a component located at (i,j) in a 2-dimensional matrix.

Remember that the first component in the matrix is (0,0).

In order to provide some degree of efficiency, the data passed-in is not bounds checked – you must ensure that you are passing memory that is at least mComponentStride bytes large.

In fact, you should pass a compound type if you want more than one of the primitive types. For example, pass a pointer to a TTComplex if you want two doubles.

Parameters
[in]irow in matrix of desired component
[in]jcolumn in matrix of desired component
[out]datareference to where method should return value
Returns
TTErr always returns kTTErrNone

Definition at line 422 of file TTMatrixBase.h.

References INDEX_OF_COMPONENT_FIRSTBYTE, and kTTErrNone.

Referenced by TTMatrix::get2d(), TTSpatBaseRenderer::processAudio(), and test().

template<typename T >
TTErr TTMatrixBase::get2d ( TTRowID  i,
TTColumnID  j,
TTElementID  e,
T &  data 
) const
inline

Get the value of element e of the component located at (i,j) in a 2-dimensional matrix.

Remember that the first component in the matrix is (0,0) and its first element is 0.

In order to provide some degree of efficiency, the data passed-in is not bounds checked – you must ensure that you are passing memory that is at least mComponentStride bytes large.

In fact, you should pass a compound type if you want more than one of the primitive types. For example, pass a pointer to a TTComplex if you want two doubles.

Parameters
[in]irow in matrix of desired component
[in]jcolumn in matrix of desired component
[in]eelement within matrix component
[out]datareference to where method should return value
Returns
TTErr always returns kTTErrNone

Definition at line 447 of file TTMatrixBase.h.

References INDEX_OF_ELEMENT_FIRSTBYTE, and kTTErrNone.

TTColumnID TTMatrixBase::getColumnCount ( )
inline

Simple data accessor.

Returns
TTColumnID the value stored at mColumnCount

Definition at line 154 of file TTMatrixBase.h.

Referenced by TTMatrix::getColumnCount(), and TTSpatBaseRenderer::processAudio().

TTUInt32 TTMatrixBase::getComponentCount ( )
inline

Simple data accessor.

Returns
TTUInt32 the value stored at mComponentCount

Definition at line 168 of file TTMatrixBase.h.

TTUInt32 TTMatrixBase::getComponentStride ( )
inline

Simple data accessor.

Returns
TTUInt32 the value stored at mComponentStride

Definition at line 210 of file TTMatrixBase.h.

Referenced by TTMatrix::getComponentStride().

TTUInt32 TTMatrixBase::getDataCount ( )
inline

Simple data accessor.

Returns
TTUInt32 the value stored at mDataCount

Definition at line 203 of file TTMatrixBase.h.

TTErr TTMatrixBase::getDimensions ( TTValue returnedDimensions) const

Legacy attribute accessor.

Will set returnedDimensions as a 2-item TTValue using the values saved as RowCount & ColumnCount.

Parameters
[out]returnedDimensionsa 2-item TTValue with mRowCount first & mColumnCount second
Returns
TTErr always returns kTTErrNone

Definition at line 227 of file TTMatrixBase.cpp.

References kTTErrNone, mColumnCount, mRowCount, and TTValue::resize().

+ Here is the call graph for this function:

TTElementID TTMatrixBase::getElementCount ( )
inline

Simple data accessor.

Returns
TTElementID the value stored at mElementCount

Definition at line 161 of file TTMatrixBase.h.

TTBytePtr TTMatrixBase::getLockedPointer ( )
inline

Return a pointer to the matrix data, and lock the matrix so that others cannot access the data.

If matrix is already locked, this function waits until it becomes free.

Definition at line 547 of file TTMatrixBase.h.

Referenced by TTMatrix::getLockedPointer(), and TTSampleMatrix::normalize().

TTRowID TTMatrixBase::getRowCount ( )
inline

Simple data accessor.

Returns
TTRowID the value stored at mRowCount

Definition at line 147 of file TTMatrixBase.h.

Referenced by TTMatrix::getRowCount(), and TTSpatBaseRenderer::processAudio().

TTErr TTMatrixBase::getType ( TTValue returnedType) const

Attribute accessor.

Will set returnedType to a symbol matching the name of data type used in matrix.

Parameters
[out]returnedTypea TValue with a symbol matching the name of data type
Returns
TTErr always returns kTTErrNone

Definition at line 219 of file TTMatrixBase.cpp.

References kTTErrNone, and mTypeAsSymbol.

TTDataInfoPtr TTMatrixBase::getTypeAsDataInfo ( )
inline

Simple data accessor.

Returns
TTDataInfoPtr the value stored at mTypeAsDataInfo

Definition at line 196 of file TTMatrixBase.h.

TTDataType TTMatrixBase::getTypeAsDataType ( )
inline

Simple data accessor.

Returns
TTDataType the value stored at mType

Definition at line 182 of file TTMatrixBase.h.

Referenced by test().

TTSymbol TTMatrixBase::getTypeAsSymbol ( )
inline

Simple data accessor.

Returns
TTSymbolPtr the value stored at mTypeAsDataInfo->name

Definition at line 189 of file TTMatrixBase.h.

TTErr TTMatrixBase::iterate ( TTMatrixBase C,
const TTMatrixBase A,
const TTMatrixBase B,
TTMatrixBaseIterator  iterator 
)
static

Step through every component in the matrix A and B to produce matrix C using the specified iterator method.

Parameters
[out]Cpointer to matrix that holds the results of the operation
[in]Apointer to matrix 1 of 2 for the iteration operation
[in]Bpointer to matrix 2 of 2 for the iteration operation
[in]iteratorfunction that will be used to operate on matrices A and B
Returns
TTErr kTTErrGeneric if attributes do not match or if iterate fails, otherwise returns kTTErrNone

Definition at line 474 of file TTMatrixBase.cpp.

References adaptTo(), kTTErrGeneric, kTTErrNone, mData, mDataSize, and mTypeSizeInBytes.

Referenced by iterateWhenAllAttributesMatch().

+ Here is the call graph for this function:

TTErr TTMatrixBase::iterateWhenAllAttributesMatch ( TTMatrixBase C,
const TTMatrixBase A,
const TTMatrixBase B,
TTMatrixBaseIterator  iterator 
)
static

Only if all the attributes of matrix A and B match, then step through every component to produce matrix C using the specified iterator method.

Parameters
[out]Cpointer to matrix that holds the results of the operation
[in]Apointer to matrix 1 of 2 for the iteration operation
[in]Bpointer to matrix 2 of 2 for the iteration operation
[in]iteratorfunction that will be used to operate on matrices A and B
Returns
TTErr kTTErrGeneric if attributes do not match or if iterate fails, otherwise returns kTTErrNone

Definition at line 490 of file TTMatrixBase.cpp.

References allAttributesMatch(), iterate(), and kTTErrGeneric.

+ Here is the call graph for this function:

TTBoolean TTMatrixBase::makeColumnIDInBounds ( TTColumnID j,
TTMatrixBaseOutOfBoundsHandler  handler = outOfBoundsWrap 
) const
inline

Make sure a TTColumnID is within the limits set by ColumnCount.

This method can be used to force column values to fall within the defined limits of the TTMatrixBase.

Parameters
[in,out]jcolumn in matrix of desired component
[in]handlerfunction used to transform out of bounds values, outOfBoundsWrap is default if undefined
Returns
TTBoolean true if values changed, false if they remained constant

Definition at line 335 of file TTMatrixBase.h.

Referenced by test().

TTBoolean TTMatrixBase::makeElementIDInBounds ( TTElementID e,
TTMatrixBaseOutOfBoundsHandler  handler = outOfBoundsWrap 
) const
inline

Make sure a TTElementID is within the limits set by ElementCount.

This method can be used to force element values to fall within the defined limits of the TTMatrixBase.

Parameters
[in,out]eelement within desired component
[in]handlerfunction used to transform out of bounds values, outOfBoundsWrap is default if undefined
Returns
TTBoolean true if values changed, false if they remained constant

Definition at line 349 of file TTMatrixBase.h.

TTBoolean TTMatrixBase::makeInBounds ( TTRowID i,
TTColumnID j,
TTMatrixBaseOutOfBoundsHandler  handler = outOfBoundsWrap 
) const
inline

Make sure an (i,j) pair is within the limits set by RowCount & ColumnCount.

This method can be used just before calls to the get or set methods and forces values to fall within the defined limits of the TTMatrixBase. This is simpler than checking the boundaries of (i,j) separately, but may be less efficient when one value is not changing as frequently as the other. It will also always use the same TTMatrixBaseOutOfBoundsHandler on all dimensions.

Parameters
[in,out]irow in matrix of desired component
[in,out]jcolumn in matrix of desired component
[in]handlerfunction used to transform out of bounds values, outOfBoundsWrap is default if undefined
Returns
TTBoolean true if values changed, false if they remained constant

makeRowIDInBounds, makeColumnIDInBounds

Definition at line 366 of file TTMatrixBase.h.

Referenced by get(), and set().

TTBoolean TTMatrixBase::makeInBounds ( TTRowID i,
TTColumnID j,
TTElementID e,
TTMatrixBaseOutOfBoundsHandler  handler = outOfBoundsWrap 
) const
inline

Make sure an (i,j,e) set is within the limits set by RowCount, ColumnCount & ElementCount.

This method can be used just before calls to the get or set methods and forces values to fall within the defined limits of the TTMatrixBase. This is simpler than checking the boundaries of (i,j, e) separately, but may be less efficient when one value is not changing as frequently as the others. It will also always use the same TTMatrixBaseOutOfBoundsHandler on all dimensions.

Parameters
[in,out]irow in matrix of desired component
[in,out]jcolumn in matrix of desired component
[in,out]eelement within desired component
[in]handlerfunction used to transform out of bounds values, outOfBoundsWrap is default if undefined
Returns
TTBoolean true if values changed, false if they remained constant

makeRowIDInBounds, makeColumnIDInBounds, makeElementIDInBounds

Definition at line 385 of file TTMatrixBase.h.

TTBoolean TTMatrixBase::makeRowIDInBounds ( TTRowID i,
TTMatrixBaseOutOfBoundsHandler  handler = outOfBoundsWrap 
) const
inline

Make sure a TTRowID is within the limits set by RowCount.

This method can be used to force row values to fall within the defined limits of the TTMatrixBase.

Parameters
[in,out]irow in matrix of desired component
[in]handlerfunction used to transform out of bounds values, outOfBoundsWrap is default if undefined
Returns
TTBoolean true if values changed, false if they remained constant

Definition at line 321 of file TTMatrixBase.h.

Referenced by test().

TTMatrixBase * TTMatrixBase::operator+ ( const TTMatrixBase B) const

Add two matrices to produce a third matrix.

The resulting matrix is instantiated by this method. You, the caller, are responsible for freeing it.

Definition at line 50 of file TTMatrixMath.cpp.

References mType.

TTMatrixBase * TTMatrixBase::operator- ( const TTMatrixBase B) const

Subtract matrix B from matrix A to produce matrix C.

The resulting matrix is instantiated by this method. You, the caller, are responsible for freeing it.

Definition at line 68 of file TTMatrixMath.cpp.

References mType.

static TTInt32 TTMatrixBase::outOfBoundsClip ( const TTInt32  index,
const TTInt32  lowBound,
const TTInt32  highBound 
)
inlinestatic

In implementation of the TTMatrixBaseOutOfBoundsHandler that wraps #TTClip.

TTMatrixBaseOutOfBoundsHandler

Definition at line 283 of file TTMatrixBase.h.

Referenced by test().

static TTInt32 TTMatrixBase::outOfBoundsFold ( const TTInt32  index,
const TTInt32  lowBound,
const TTInt32  highBound 
)
inlinestatic

In implementation of the TTMatrixBaseOutOfBoundsHandler that wraps #TTFold.

TTMatrixBaseOutOfBoundsHandler

Definition at line 303 of file TTMatrixBase.h.

Referenced by test().

static TTInt32 TTMatrixBase::outOfBoundsWrap ( const TTInt32  index,
const TTInt32  lowBound,
const TTInt32  highBound 
)
inlinestatic

In implementation of the TTMatrixBaseOutOfBoundsHandler that wraps #TTInfWrap.

TTMatrixBaseOutOfBoundsHandler

Definition at line 292 of file TTMatrixBase.h.

void TTMatrixBase::referenceExternalData ( TTPtr  aDataPointer)
inline

You must proceed to set the various attributes, dimensions, etc.

to match the data format of the matrix you are referencing.

One caveat regards data alignment. Jitter, for example, aligns rows on 16-byte boundaries. In this case, a 4x10 matrix (using the m-by-n convention rather than Jitter's width-by-height convention) of 32-bit ints, all with a value of "4" will look like this:

4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 0, 0 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 0, 0 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 0, 0 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 0, 0

Thus, the rows are really of a dimension length 12 instead of 10 and the total size of the matrix scales as well.

For the time being, we do not handle this case. Jitter users must dimension their matrices so that the row size in bytes is a multiple of 16. This is not actually hard to do for most purposes. For example:

float64, element count of 1, width is a multiple of 2 (an even number) float32 or int32, element count of 1, width is a multiple of 4 uint8, element count of 1, width is a multiple of 16 (which includes 80, 160, 320, 640, ...), but element count of 4 (i.e. color pixels) width should be a multiple of values.

Definition at line 534 of file TTMatrixBase.h.

Referenced by TTMatrix::referenceExternalData().

void TTMatrixBase::releaseLockedPointer ( )
inline

Release a locked pointer obtained using getLockedPointer().

Definition at line 556 of file TTMatrixBase.h.

Referenced by TTSampleMatrix::normalize(), and TTMatrix::releaseLockedPointer().

TTErr TTMatrixBase::resize ( )
protected

Internal method that resizes memory allocated when various attributes change.

Returns
TTErr kTTErrAllocFailed if the resize operation could not be completed, otherwise kTTErrNone

Definition at line 66 of file TTMatrixBase.cpp.

References kTTErrAllocFailed, kTTErrNone, mColumnCount, mComponentCount, mComponentStride, mData, mDataCount, mDataIsLocallyOwned, mDataSize, mElementCount, mRowCount, and mTypeSizeInBytes.

Referenced by adaptTo(), setColumnCount(), setDimensions(), setElementCount(), setRowCount(), and setType().

TTErr TTMatrixBase::set ( const TTValue anInputValue,
TTValue anOutputValue 
)

Set the value of a component located at any location in an 2-dimensional matrix.

Pass in coordinate pair and new value using anInputValue. Returns nothing via anOutputValue. Remember that the first location in the matrix is row 0 and column 0. Used primarily as an interface to the matrix data from Jamoma implementations in Ruby and Max. To store values in the matrix with less overhead, see the set2d() method.

Parameters
[in]anInputValueTTValue array containing the row and column values of coordinates and elements to be stored at this location, therefore anInputValue requires (2 + mElementCount) items
[out]anOutputValueunused
Returns
TTErr kTTErrWrongNumValues if anInputValue does not have (2 + mElementCount) items, else kTTErrNone

Definition at line 386 of file TTMatrixBase.cpp.

References TTValue::copyFrom(), INDEX_OF_COMPONENT_FIRSTBYTE, kTTErrNone, kTTErrOutOfBounds, kTTErrWrongNumValues, kTypeFloat32, kTypeFloat64, kTypeInt32, kTypeUInt8, makeInBounds(), mData, mElementCount, mType, mTypeSizeInBytes, and TTValue::size().

+ Here is the call graph for this function:

template<typename T >
TTErr TTMatrixBase::set2d ( TTRowID  i,
TTColumnID  j,
data 
)
inline

Set the value of a component located at (i,j) in a 2-dimensional matrix.

Remember that the first component in the matrix is (0,0).

In order to provide some degree of efficiency, the data passed-in is not bounds checked – you must ensure that you are passing memory that is at least mComponentStride bytes large.

In fact, you should pass a compound type if you want more than one of the primitive types. For example, pass a pointer to a TTComplex if you want two doubles.

Parameters
[in]irow in matrix of component to be set
[in]jcolumn in matrix of component to be set
[out]datareference to where method should return value
Returns
TTErr always returns kTTErrNone

Definition at line 481 of file TTMatrixBase.h.

References INDEX_OF_COMPONENT_FIRSTBYTE, and kTTErrNone.

Referenced by TTSampleMatrix::fill(), TTSpatSnapRenderer::recalculateMatrixCoefficients(), TTSpatDBAPRenderer::recalculateMatrixCoefficients(), TTMatrix::set2d(), and test().

template<typename T >
TTErr TTMatrixBase::set2d ( TTRowID  i,
TTColumnID  j,
TTElementID  e,
data 
)
inline

Set the value of element e of the component located at (i,j) in a 2-dimensional matrix.

Remember that the first component in the matrix is (0,0) and its first element is 0.

In order to provide some degree of efficiency, the data passed-in is not bounds checked – you must ensure that you are passing memory that is at least mComponentStride bytes large.

In fact, you should pass a compound type if you want more than one of the primitive types. For example, pass a pointer to a TTComplex if you want two doubles.

Parameters
[in]irow in matrix of component to be set
[in]jcolumn in matrix of component to be set
[in]eelement within matrix component
[out]datareference to where method should return value
Returns
TTErr always returns kTTErrNone

Definition at line 504 of file TTMatrixBase.h.

References INDEX_OF_ELEMENT_FIRSTBYTE, and kTTErrNone.

TTErr TTMatrixBase::setColumnCount ( const TTValue aNewColumnCount)

Attribute accessor.

Sets the value for ColumnCount. Values that are less than 1 will return an error.

Parameters
aNewColumnCountnumber of desired columns in this matrix
Returns
TTErr kTTErrInvalidValue if value was outside allowed range, kTTErrAllocFailed if the resize operation could not be completed, otherwise kTTErrNone

Definition at line 154 of file TTMatrixBase.cpp.

References kTTErrInvalidValue, resize(), and setColumnCountWithoutResize().

Referenced by TTSpatSnapRenderer::recalculateMatrixCoefficients(), TTSpatDBAPRenderer::recalculateMatrixCoefficients(), and TTSampleMatrix::setNumChannels().

+ Here is the call graph for this function:

TTBoolean TTMatrixBase::setColumnCountWithoutResize ( TTColumnID  aNewColumnCount)
protected

Internal method that sets the value for ColumnCount without resizing the matrix of values.

It is included so that other methods in the class use consistent range checking. Values that are less than 1 will return false and leave the value unchanged.

Parameters
aNewColumnCountnumber of desired columns in this matrix
Returns
TTBoolean false if value was outside allowed range and therefore not changed, otherwise true

Definition at line 102 of file TTMatrixBase.cpp.

References mColumnCount.

Referenced by adaptTo(), setColumnCount(), and setDimensions().

TTErr TTMatrixBase::setDimensions ( const TTValue someNewDimensions)

Attribute accessor.

Set the values of mRowCount and mColumnCount using a TTValue array. Values beyond the first two items in the TTValue array will be ignored without an error. Values that are less than 1 will return an error. Support for N dimensions has been deprecated.

Parameters
someNewDimensionsa 2-item TTValue array with the desired mRowCount and mColumnCount
Returns
TTErr kTTErrInvalidValue if value was outside allowed range, kTTErrAllocFailed if the resize operation could not be completed, otherwise kTTErrNone

Definition at line 196 of file TTMatrixBase.cpp.

References kTTErrInvalidValue, resize(), setColumnCountWithoutResize(), setRowCountWithoutResize(), and TTValue::size().

+ Here is the call graph for this function:

TTErr TTMatrixBase::setDimensionsWithVector ( const std::vector< TTInt32 > &  newDimensions)
inline

Alternative to attribute accessor.

Set the values of mRowCount and mColumnCount with a TTInt32 vector (instead of using TTValue array). Values beyond the first two items in the vector will be ignored without an error. Values that are less than 1 will return an error. Support for N dimensions has been deprecated.

Parameters
newDimensionsa 2-item TTInt32 vector with the desired mRowCount and mColumnCount
Returns
TTErr kTTErrInvalidValue if value was outside allowed range, kTTErrAllocFailed if the resize operation could not be completed, otherwise kTTErrNone

Definition at line 131 of file TTMatrixBase.h.

References kTTErrInvalidValue.

TTErr TTMatrixBase::setElementCount ( const TTValue newElementCount)

Attribute accessor.

Sets the value for ElementCount. Values that are less than 1 will return an error.

Parameters
newElementCountnumber of desired elements in each component
Returns
TTErr kTTErrInvalidValue if value was outside allowed range, kTTErrAllocFailed if the resize operation could not be completed, otherwise kTTErrNone

Definition at line 167 of file TTMatrixBase.cpp.

References kTTErrInvalidValue, resize(), and setElementCountWithoutResize().

+ Here is the call graph for this function:

TTBoolean TTMatrixBase::setElementCountWithoutResize ( TTElementID  aNewElementCount)
protected

Internal method that sets the value for ElementCount without resizing the matrix of values.

It is included so that other methods in the class use consistent range checking. Values that are less than 1 will return false and leave the value unchanged.

Parameters
aNewElementCountnumber of desired elements in each component
Returns
TTBoolean false if value was outside allowed range and therefore not changed, otherwise true

Definition at line 114 of file TTMatrixBase.cpp.

References mElementCount.

Referenced by adaptTo(), and setElementCount().

TTErr TTMatrixBase::setRowCount ( const TTValue aNewRowCount)

Attribute accessor.

Sets the value for RowCount. Values that are less than 1 will return an error.

Parameters
aNewRowCountnumber of desired rows in this matrix
Returns
TTErr kTTErrInvalidValue if value was outside allowed range, kTTErrAllocFailed if the resize operation could not be completed, otherwise kTTErrNone

Definition at line 141 of file TTMatrixBase.cpp.

References kTTErrInvalidValue, resize(), and setRowCountWithoutResize().

Referenced by TTSpatSnapRenderer::recalculateMatrixCoefficients(), TTSpatDBAPRenderer::recalculateMatrixCoefficients(), TTSampleMatrix::setLengthInSamples(), and TTSampleMatrix::setLengthInSeconds().

+ Here is the call graph for this function:

TTBoolean TTMatrixBase::setRowCountWithoutResize ( TTRowID  aNewRowCount)
protected

Internal method that sets the value for RowCount without resizing the matrix of values.

It is included so that other methods in the class use consistent range checking. Values that are less than 1 will return false and leave the value unchanged.

Parameters
aNewRowCountnumber of desired rows in this matrix
Returns
TTBoolean false if value was outside allowed range and therefore not changed, otherwise true

Definition at line 90 of file TTMatrixBase.cpp.

References mRowCount.

Referenced by adaptTo(), setDimensions(), and setRowCount().

TTErr TTMatrixBase::setType ( const TTValue aType)

Attribute accessor.

Sets the value for type-related variables. Value must be a symbol that matches the name of a numeric type defined in TTBase::ttDataTypeInfo (i.e., float32, float64, int8, uint8, int16, uint16, int32, uint32, int64, uint64).

Parameters
aTypename of desired datatype to be used for each element
Returns
TTErr kTTErrInvalidValue if value was outside allowed range, kTTErrAllocFailed if the resize operation could not be completed, otherwise kTTErrNone

Definition at line 180 of file TTMatrixBase.cpp.

References kTTErrInvalidValue, mTypeAsSymbol, resize(), and setTypeWithoutResize().

+ Here is the call graph for this function:

TTBoolean TTMatrixBase::setTypeWithoutResize ( TTDataType  aNewType)
protected

Internal method that sets the values for type-related variables without resizing the matrix of values.

It is included so that other methods in the class consistently check for valid entries. Values that are not a defined numeric type in TTBase::ttDataTypeInfo will return false and leave the values unchanged.

Parameters
aNewTypedesired TTDataType to be used for elements
Returns
TTBoolean false if value was outside allowed range and therefore not changed, otherwise true

Definition at line 126 of file TTMatrixBase.cpp.

References mType, mTypeAsDataInfo, mTypeAsSymbol, mTypeSizeInBytes, and ttDataTypeInfo.

Referenced by adaptTo(), and setType().

TTErr TTMatrixBase::test ( TTValue returnedTestInfo)
protectedvirtual

Unit test for the window function unit.

Parameters
returnedTestInfoThe outcome from the performed unit test.
Returns
TTErr error code if the method fails to execute, else kTTErrNone.

Reimplemented from TTDataObjectBase.

Reimplemented in TTSampleMatrix.

Definition at line 14 of file TTMatrix.test.cpp.

References allAttributesMatch(), TTValue::append(), get2d(), getTypeAsDataType(), kTTErrInstantiateFailed, kTTErrNone, makeColumnIDInBounds(), makeRowIDInBounds(), mComponentStride, mData, mDataSize, mTypeSizeInBytes, outOfBoundsClip(), outOfBoundsFold(), TTValue::resize(), TTObjectBase::sendMessage(), set2d(), and TTObjectBase::setAttributeValue().

+ Here is the call graph for this function:


The documentation for this class was generated from the following files: