Jamoma API  0.6.0.a19
TTSampleMatrix.h
Go to the documentation of this file.
1 /** @file
2  *
3  * @ingroup dspLibrary
4  *
5  * @brief #TTSampleMatrix holds some audio in a chunk of memory.
6  *
7  * @details #TTSampleMatrix extends the #TTMatrix class found in Foundation to provide support for loading audio into a chunk of memory. Each sample value is stored as a one-element component with a datatype of 64-bit Float. Locations for individual components in the matrix can be identified by (sample, channel) pairs where samples correspond to rows in the matrix and channels translate to columns.@n@n
8  * Because the #TTMatrix class uses <a href="http://en.wikipedia.org/wiki/Row-major_order#Column-major_order">column-major order</a>, it results in channels being <a href="http://en.wikipedia.org/wiki/Interleave">interleaved</a> and provides more efficient memory access for multi-channel sound. However, this interleaving must be accounted for when developing other objects to process or playback the audio.@n@n
9  * Both sample and channel indices begin counting at zero. This means that index values greater than or equal to the respective mLengthInSamples or mNumChannels will be out of bounds. @n@n
10  *
11  * @see TTMatrix, TTAudioSignal
12  *
13  * @authors Timothy Place & Nathan Wolek
14  *
15  * @copyright Copyright © 2003-2012, Timothy Place & Nathan Wolek @n
16  * This code is licensed under the terms of the "New BSD License" @n
17  * http://creativecommons.org/licenses/BSD/
18  */
19 
20 #ifndef __TT_SAMPLEMATRIX_H__
21 #define __TT_SAMPLEMATRIX_H__
22 
23 #include "TTDSP.h"
24 
25 // the following definitions allow our code the use audio related terms
26 // while still maintaining connection to the definitions set in #TTMatrix.
27 // hopefully this will reduce confusion [NW]
28 #define mLengthInSamples mRowCount
29 #define mNumChannels mColumnCount
30 
31 // any sample/frame index should use type definition TTRowID
32 // any channel index should use type definition TTColumnID
33 
34 /** @enum bufferPoolStages
35  @brief Defines the stages used when TTSampleMartix is part of a pool available in TTBuffer
36 */
38  kSM_Idle = 0, ///< not currently in use
39  kSM_BecomingActive, ///< being prepared for active stage by resizing or file loading operation
40  kSM_Active, ///< in use and pointer to this TTSampleMatrix will be given to users at check out
41  kSM_BecomingIdle ///< no longer active, but waiting for remaining users to check in
42 };
43 
44 /** Container object that holds some audio in a chunk of memory.
45 
46 SampleMatrix extends the Matrix class found in Foundation to provide support for loading audio into a chunk of memory. Each sample value is stored as a one-element component with a datatype of 64-bit Float. Locations for individual components in the matrix can be identified by (sample, channel) pairs where samples correspond to rows in the matrix and channels translate to columns.
47 
48  @see TTAudioSignal, TTMatrix
49 */
50 class TTDSP_EXPORT TTSampleMatrix : public TTMatrixBase {
52 
53 protected:
54 
55  TTUInt32 mSampleRate;
56  TTUInt16 mUserCount; ///< how many objects out there are currently using this TTSampleMatrix
57  TTBufferPoolStageEnum mBufferPoolStage;
58  // NOTE: This object does not process audio by itself, but inherits from TTAudioObject for sample-rate support.
59  // TODO: Perhaps we could add a simple process method that takes a sample index as input and provides the value as output?
60 
61 public:
62 
63  /** Attribute accessor: set the number of channels for this buffer.
64  @return Returns a TTErr error code. */
65  TTErr setNumChannels(const TTValue& newNumChannels);
66  TTErr getNumChannels(TTValue& returnedNumChannels);
67 
68  /** Attribute accessor: set the buffer length specified in seconds.
69  @return Returns a TTErr error code. */
70  TTErr setLengthInSeconds(const TTValue& newLength);
71  TTErr getLengthInSeconds(TTValue& returnedLength);
72 
73  /** Attribute accessor: set the buffer length specified as a number of samples.
74  @return Returns a TTErr error code. */
75  TTErr setLengthInSamples(const TTValue& newLengthInSamples);
76  TTErr getLengthInSamples(TTValue& returnedLengthInSamples);
77 
78  /** Set dimensions, element count, datatype, etc. (i.e. the metadata describing a matrix)
79  to match the another matrix which is passed-in as an argument. Overrides the TTMatrix method
80  so that sample rate is set as well.
81 
82  @param anotherMatrix sample matrix to which you would like to conform the attributes of this one
83  @return TTErr kTTErrInvalidValue if operation is not completed, otherwise kTTErrNone
84  */
85  TTErr adaptTo(const TTSampleMatrix& anotherMatrix);
86  TTErr adaptTo(const TTSampleMatrix* anotherMatrix)
87  {
88  return adaptTo(*anotherMatrix);
89  }
90 
91  /** Increase the user count by one.
92  The userCount member is used to track usage of an individual TTSampleMatrix. When another object makes use of a specific matrix, the code should use this method to increase the user counter prior to the start of use.
93  @return TTErr always returns kTTErrNone
94  @seealso decrementUserCount
95  */
96  TTErr incrementUserCount();
97 
98  /** Decrease the user count by one.
99  The userCount member is used to track usage of an individual TTSampleMatrix. When another object makes use of a specific matrix, the code should use this method to decrease the reference counter at the conclusion of use.
100  @return TTErr returns kTTErrGeneric if UserCount is already 0, else kTTErrNone
101  @seealso incrementUserCount
102  */
103  TTErr decrementUserCount();
104 
105  /** Report the current user count.
106  The userCount member is used to track usage of an individual TTSampleMatrix.
107  @return TTUInt16 returns current UserCount is already 0, else kTTErrNone
108  @seealso incrementUserCount
109  */
111  {
112  return mUserCount;
113  }
114 
115  /** Test to see if current bufferPoolStage matches a test value.
116  The bufferPoolStage member is used when TTSampleMartix is part of a pool available in TTBuffer. This methods allows you to check the current stage against a test value. It is useful in setting up conditional statements.
117  @param test_value any option defined in the bufferPoolStageEnum
118  @return TTBoolean returns true if the they match, false if they do not
119  @seealso bufferPoolStageEnum, setBufferPoolStage
120  */
122  {
123  return testValue == this->mBufferPoolStage;
124  }
125 
126  /** Set the current bufferPoolStage to a new value.
127  The bufferPoolStage member is used when TTSampleMartix is part of a pool available in TTBuffer. This methods allows you to set the current stage with a new value.
128  @param test_value any option defined in the bufferPoolStageEnum
129  @return TTErr always returns kTTErrNone
130  @seealso bufferPoolStageEnum, isBufferPoolStage
131  */
133  {
134  this->mBufferPoolStage = newValue;
135  return kTTErrNone;
136  }
137 
138  // METHOD: SET_BUFFER
139  // void set_buffer(tt_buffer *newbuffer);
140  TTErr getContents(TTSampleValuePtr& beggining)
141  {
142  beggining = (TTSampleValuePtr)mData;
143  return kTTErrNone;
144  }
145 
146  TTErr getValueAtIndex(const TTValue& index, TTValue &output);
147  TTErr peek(const TTRowID index, const TTColumnID channel, TTSampleValue& value);
148  TTErr peeki(const TTFloat64 index, const TTColumnID channel, TTSampleValue& value);
149 
150  /** Set the sample value for a given index.
151  The first number passed in the index parameter will be interpreted as the sample index.
152  If there are three numbers passed, then the second number, if passed, will designate the channel index (defaults to zero).
153  The final value will be used as the sample value that will be copied to the designated index.
154  */
155  TTErr setValueAtIndex(const TTValue& index, TTValue& unusedOutput);
156  TTErr poke(const TTRowID index, const TTColumnID channel, const TTSampleValue value);
157 
158  /** Set the contents of the buffer using a specified algorithm and, if appropriate, coefficients for that algorithm. */
159  TTErr fill(const TTValue& value, TTValue& unusedOutput);
160 
161  /** Load sample values from a soundfile into the TTSampleMatrix. This method is dependant on the SoundfileLib extension which handles operations on sound files using third-party libraries.
162  @param[in] input Multi-item TTValue used to set the copy parameters:
163  -# TTSymbol containing the filepath
164  -# (optional) channel to copy from source, default is 0
165  -# (optional) frame to start copy from source, default is 0
166  -# (optional) frame to stop copy from source, default is last
167  @param[out] unusedOutput not used
168  @return TTErr kTTErrNone load was successful. kTTErrInstantiateFailed if the TTSoundfileLoader could not be instantiated. kTTErrInvalidFilepath if the filepath was invalid. kTTErrInvalidValue if the pointer to TTSampleMatrix was invalid.
169  */
170  TTErr load(const TTValue& input, TTValue& unusedOutput);
171 
172  /** First, resize the TTSampleMatrix to match the number of channels and length in seconds found in a soundfile. Then, load the soundfile into the TTSampleMatrix. Sample rate of the TTSampleMatrix is not changed by this operation and interpolation will be applied to the loaded soundfile to acheive the necessary sample rate.
173 
174  @return TTErr kTTErrNone load was successful. kTTErrInstantiateFailed if the TTSoundfileLoader could not be instantiated.
175  */
176  TTErr resizeThenLoad(const TTValue& input, TTValue& unusedOutput);
177 
178  /** Normalize the contents of a buffer.
179  If no arg is passed, then the buffer is normalized to 1.0.
180  Otherwise it is normalized to the passed value.
181  */
182  TTErr normalize(const TTValue& aValue);
183 
184 
185  /** Unit testing */
186  virtual TTErr test(TTValue& returnedTestInfo);
187 
188 };
189 
191 
192 
193 #endif // __TT_SAMPLEMATRIX_H__
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
std::uint16_t TTUInt16
16 bit unsigned integer
Definition: TTBase.h:176
TTInt32 TTColumnID
Datatype for any number used to indicate a column index within the matrix.
Definition: TTBase.h:216
no longer active, but waiting for remaining users to check in
TTErr fill(const TTValue &anInputValue, TTValue &anOutputValue)
Fill every component in the matrix with the same value.
TTInt32 TTRowID
Datatype for any number used to indicate a row index within a matrix.
Definition: TTBase.h:207
Jamoma DSP Library.
double TTFloat64
64 bit floating point number
Definition: TTBase.h:188
TTErr adaptTo(const TTMatrixBase &anotherMatrix)
Set dimensions, element count, datatype, etc.
Container object that holds some audio in a chunk of memory.
#define TTCLASS_SETUP(className)
TODO Doxygen: need more comments here.
Definition: TTFoundation.h:54
2-dimensional matrix of compound values with N elements each.
Definition: TTMatrixBase.h:41
TTBufferPoolStageEnum
TTUInt16 getUserCount()
Report the current user count.
in use and pointer to this TTSampleMatrix will be given to users at check out
virtual TTErr test(TTValue &returnedTestInfo)
Unit test for the window function unit.
TTBoolean isBufferPoolStage(TTBufferPoolStageEnum testValue)
Test to see if current bufferPoolStage matches a test value.
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
not currently in use
std::uint32_t TTUInt32
32 bit unsigned integer
Definition: TTBase.h:178
TTUInt16 mUserCount
how many objects out there are currently using this TTSampleMatrix
No Error.
Definition: TTBase.h:343
TTErr setBufferPoolStage(TTBufferPoolStageEnum newValue)
Set the current bufferPoolStage to a new value.
TTFloat64 TTSampleValue
A value representing a single audio sample.
Definition: TTBase.h:230
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34
being prepared for active stage by resizing or file loading operation