Jamoma API  0.6.0.a19
TTMatrix.h
Go to the documentation of this file.
1 /** @file
2  *
3  * @ingroup foundationLibrary
4  *
5  * @brief #TTMatrix wraps a TTMatrixBase for use.
6  *
7  * @details
8  *
9  * @author Timothy Place, Nathan Wolek
10  *
11  * @copyright Copyright © 2014 by Timothy Place @n
12  * This code is licensed under the terms of the "New BSD License" @n
13  * http://creativecommons.org/licenses/BSD/
14  */
15 
16 
17 #ifndef __TT_MATRIX_H__
18 #define __TT_MATRIX_H__
19 
20 #include "TTBase.h"
21 #include "TTObject.h"
22 
23 class TTMatrixBase;
24 
25 
26 /** Wrap TTMatrixBase instances. */
27 class TTFOUNDATION_EXPORT TTMatrix : public TTObject {
28 public:
29 
30  /** Constructor */
32  TTObject("matrix")
33  {}
34 
35 
36  /** Get a pointer to the wrapped #TTMatrixBase instance. */
38  {
39  return (TTMatrixBase*)mObjectInstance;
40  }
41 
42 
43  /** Set all components of a matrix to zero. */
44  void clear();
45 
46 
47  /** You must proceed to set the various attributes, dimensions, etc. to match the data format of the matrix you are referencing.
48 
49  One caveat regards data alignment. Jitter, for example, aligns rows on 16-byte boundaries.
50  In this case, a 4x10 matrix (using the m-by-n convention rather than Jitter's width-by-height convention) of 32-bit ints,
51  all with a value of "4" will look like this:
52 
53  4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 0, 0
54  4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 0, 0
55  4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 0, 0
56  4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 0, 0
57 
58  Thus, the rows are really of a dimension length 12 instead of 10 and the total size of the matrix scales as well.
59 
60  For the time being, we do not handle this case.
61  Jitter users must dimension their matrices so that the row size in bytes is a multiple of 16.
62  This is not actually hard to do for most purposes. For example:
63 
64  float64, element count of 1, width is a multiple of 2 (an even number)
65  float32 or int32, element count of 1, width is a multiple of 4
66  uint8, element count of 1, width is a multiple of 16 (which includes 80, 160, 320, 640, ...), but
67  element count of 4 (i.e. color pixels) width should be a multiple of values.
68  */
69  void referenceExternalData(TTPtr aDataPointer);
70 
71 
72  /** Return a pointer to the matrix data, and lock the matrix so that others cannot access the data.
73  If matrix is already locked, this function waits until it becomes free. */
74  TTByte* getLockedPointer();
75 
76 
77  /** Release a locked pointer obtained using getLockedPointer(). */
78  void releaseLockedPointer();
79 
80 
81 
82  /** Number of rows in the matrix.
83  @return TTRowID the value stored at mRowCount
84  */
85  TTRowID getRowCount() const;
86 
87 
88  /** Number of columns in the matrix.
89  @return TTColumnID the value stored at mColumnCount
90  */
91  TTColumnID getColumnCount() const;
92 
93 
94  /** Return number of bytes from one the beginning one matrix component to the next. */
95  TTUInt32 getComponentStride() const;
96 
97 
98  /** Get the value of a component located at (i,j) in a 2-dimensional matrix.
99  Remember that the first component in the matrix is (0,0).
100 
101  In order to provide some degree of efficiency, the data passed-in is not bounds checked --
102  you must ensure that you are passing memory that is at least mComponentStride bytes large.
103 
104  In fact, you should pass a compound type if you want more than one of the primitive types.
105  For example, pass a pointer to a TTComplex if you want two doubles.
106 
107  @param[in] i row in matrix of desired component
108  @param[in] j column in matrix of desired component
109  @param[out] data reference to where method should return value
110  @return TTErr always returns kTTErrNone
111  */
112  template<typename T>
113  TTErr get2d(TTRowID i, TTColumnID j, T& data) const;
114 
115 
116  /** Get the value of element e of the component located at (i,j) in a 2-dimensional matrix.
117  Remember that the first component in the matrix is (0,0) and its first element is 0.
118 
119  In order to provide some degree of efficiency, the data passed-in is not bounds checked --
120  you must ensure that you are passing memory that is at least mComponentStride bytes large.
121 
122  In fact, you should pass a compound type if you want more than one of the primitive types.
123  For example, pass a pointer to a TTComplex if you want two doubles.
124 
125  @param[in] i row in matrix of desired component
126  @param[in] j column in matrix of desired component
127  @param[in] e element within matrix component
128  @param[out] data reference to where method should return value
129  @return TTErr always returns kTTErrNone
130  */
131  template<typename T>
132  TTErr get2d(TTRowID i, TTColumnID j, TTElementID e, T& data) const;
133 
134 
135  /** Set the value of a component located at (i,j) in a 2-dimensional matrix.
136  Remember that the first component in the matrix is (0,0).
137 
138  In order to provide some degree of efficiency, the data passed-in is not bounds checked --
139  you must ensure that you are passing memory that is at least mComponentStride bytes large.
140 
141  In fact, you should pass a compound type if you want more than one of the primitive types.
142  For example, pass a pointer to a TTComplex if you want two doubles.
143 
144  @param[in] i row in matrix of component to be set
145  @param[in] j column in matrix of component to be set
146  @param[out] data reference to where method should return value
147  @return TTErr always returns kTTErrNone
148  */
149  template<typename T>
150  TTErr set2d(TTRowID i, TTColumnID j, T data);
151 
152 
153  /** Set the value of element e of the component located at (i,j) in a 2-dimensional matrix.
154  Remember that the first component in the matrix is (0,0) and its first element is 0.
155 
156  In order to provide some degree of efficiency, the data passed-in is not bounds checked --
157  you must ensure that you are passing memory that is at least mComponentStride bytes large.
158 
159  In fact, you should pass a compound type if you want more than one of the primitive types.
160  For example, pass a pointer to a TTComplex if you want two doubles.
161 
162  @param[in] i row in matrix of component to be set
163  @param[in] j column in matrix of component to be set
164  @param[in] e element within matrix component
165  @param[out] data reference to where method should return value
166  @return TTErr always returns kTTErrNone
167  */
168  template<typename T>
169  TTErr set2d(TTRowID i, TTColumnID j, TTElementID e, T data);
170 
171 };
172 
173 
174 
175 #endif // __TT_MATRIX_H__
Create Jamoma object instances.
Create and use Jamoma object instances.
Definition: TTObject.h:29
TTInt32 TTColumnID
Datatype for any number used to indicate a column index within the matrix.
Definition: TTBase.h:216
TTMatrixBase * instance() const
Get a pointer to the wrapped TTMatrixBase instance.
Definition: TTMatrix.h:37
TTInt32 TTRowID
Datatype for any number used to indicate a row index within a matrix.
Definition: TTBase.h:207
TTMatrix()
Constructor.
Definition: TTMatrix.h:31
void * TTPtr
A generic pointer.
Definition: TTBase.h:248
2-dimensional matrix of compound values with N elements each.
Definition: TTMatrixBase.h:41
Jamoma's lowest-level base class and related infrastructure.
Wrap TTMatrixBase instances.
Definition: TTMatrix.h:27
unsigned char TTByte
Byte value.
Definition: TTBase.h:168
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
TTInt16 TTElementID
Datatype for any number used to indicate an element index within the matrix.
Definition: TTBase.h:224
std::uint32_t TTUInt32
32 bit unsigned integer
Definition: TTBase.h:178