The Synthesis ToolKit in C++ (STK)

Home Information Classes Download Usage Mail List Requirements Links FAQ Tutorial

Public Member Functions | List of all members
stk::StkFrames Class Reference

An STK class to handle vectorized audio data. More...

`#include <Stk.h>`

## Public Member Functions
| StkFrames (unsigned int nFrames=0, unsigned int nChannels=0)
| The default constructor initializes the frame data structure to size zero.
| StkFrames (const StkFloat &value, unsigned int nFrames, unsigned int nChannels)
| Overloaded constructor that initializes the frame data to the specified size with `value`.
virtual | ~StkFrames ()
| The destructor.
StkFloat & | operator[] (size_t n)
| Subscript operator that returns a reference to element `n` of self.
StkFloat | operator[] (size_t n) const
| Subscript operator that returns the value at element `n` of self.
StkFrames | operator+ (const StkFrames &frames) const
| Sum operator.
StkFrames & | operator+= (StkFrames &f)
| Assignment by sum operator into self.
StkFrames & | operator*= (StkFrames &f)
| Assignment by product operator into self.
StkFrames | operator* (StkFloat v) const
| Scaling operator (StkFrame * StkFloat).
StkFrames & | operator*= (StkFloat v)
| Scaling operator (inline).
StkFloat & | operator() (size_t frame, unsigned int channel)
| Channel / frame subscript operator that returns a reference.
StkFloat | operator() (size_t frame, unsigned int channel) const
| Channel / frame subscript operator that returns a value.
StkFloat | interpolate (StkFloat frame, unsigned int channel=0) const
| Return an interpolated value at the fractional frame index and channel.
size_t | size () const
| Returns the total number of audio samples represented by the object.
bool | empty () const
| Returns true if the object size is zero and false otherwise.
virtual void | resize (size_t nFrames, unsigned int nChannels=1)
| Resize self to represent the specified number of channels and frames.
virtual void | resize (size_t nFrames, unsigned int nChannels, StkFloat value)
| Resize self to represent the specified number of channels and frames and perform element initialization.
StkFrames & | getChannel (unsigned int channel, StkFrames &destinationFrames, unsigned int destinationChannel) const
| Retrieves a single channel.
void | setChannel (unsigned int channel, const StkFrames &sourceFrames, unsigned int sourceChannel)
| Sets a single channel.
unsigned int | channels (void) const
| Return the number of channels represented by the data.
unsigned int | frames (void) const
| Return the number of sample frames represented by the data.
void | setDataRate (StkFloat rate)
| Set the sample rate associated with the StkFrames data.
StkFloat | dataRate (void) const
| Return the sample rate associated with the StkFrames data.

## Detailed Description

An STK class to handle vectorized audio data.

This class can hold single- or multi-channel audio data. The data type is always StkFloat and the channel format is always interleaved. In an effort to maintain efficiency, no out-of-bounds checks are performed in this class unless STK_DEBUG is defined.

Internally, the data is stored in a one-dimensional C array. An indexing operator is available to set and retrieve data values. Alternately, one can use pointers to access the data, using the index operator to get an address for a particular location in the data:

StkFloat* ptr = &myStkFrames[0];

Note that this class can also be used as a table with interpolating lookup.

Possible future improvements in this class could include functions to convert to and return other data types.

by Perry R. Cook and Gary P. Scavone, 1995–2023.

## Member Function Documentation

## ◆ operator[]() [1/2]

StkFloat & stk::StkFrames::operator[] | ( | size_t | n | ) |
| inline

Subscript operator that returns a reference to element `n` of self.

The result can be used as an lvalue. This reference is valid until the resize function is called or the array is destroyed. The index `n` must be between 0 and size less one. No range checking is performed unless STK_DEBUG is defined.

453{
454#if defined(_STK_DEBUG_)
455 if ( n >= size_ ) {
456 std::ostringstream error;
457 error << "StkFrames::operator[]: invalid index (" << n << ") value!";
458 Stk::handleError( error.str(), StkError::MEMORY_ACCESS );
459 }
460#endif
461
462 return data_[n];
463}
stk::Stk::handleError
static void handleError(const char *message, StkError::Type type)
Static function for error reporting and handling using c-strings.

## ◆ operator[]() [2/2]

StkFloat stk::StkFrames::operator[] | ( | size_t | n | ) | const
| inline

Subscript operator that returns the value at element `n` of self.

The index `n` must be between 0 and size less one. No range checking is performed unless STK_DEBUG is defined.

466{
467#if defined(_STK_DEBUG_)
468 if ( n >= size_ ) {
469 std::ostringstream error;
470 error << "StkFrames::operator[]: invalid index (" << n << ") value!";
471 Stk::handleError( error.str(), StkError::MEMORY_ACCESS );
472 }
473#endif
474
475 return data_[n];
476}

## ◆ operator+()

StkFrames stk::StkFrames::operator+ | ( | const StkFrames & | frames | ) | const
| inline

Sum operator.

The dimensions of the argument are expected to be the same as self. No range checking is performed unless STK_DEBUG is defined.

505{
506#if defined(_STK_DEBUG_)
507 if ( f.frames() != nFrames_ || f.channels() != nChannels_ ) {
508 std::ostringstream error;
509 error << "StkFrames::operator+: frames argument must be of equal dimensions!";
510 Stk::handleError( error.str(), StkError::MEMORY_ACCESS );
511 }
512#endif
513 StkFrames sum((unsigned int)nFrames_,nChannels_);
514 StkFloat *sumPtr = &sum[0];
515 const StkFloat *fptr = f.data_;
516 const StkFloat *dPtr = data_;
517 for (unsigned int i = 0; i < size_; i++) {
518 *sumPtr++ = *fptr++ + *dPtr++;
519 }
520 return sum;
521}
stk::StkFrames::StkFrames
StkFrames(unsigned int nFrames=0, unsigned int nChannels=0)
The default constructor initializes the frame data structure to size zero.

## ◆ operator+=()

StkFrames & stk::StkFrames::operator+= | ( | StkFrames & | f | ) |
| inline

Assignment by sum operator into self.

The dimensions of the argument are expected to be the same as self. No range checking is performed unless STK_DEBUG is defined.

524{
525#if defined(_STK_DEBUG_)
526 if ( f.frames() != nFrames_ || f.channels() != nChannels_ ) {
527 std::ostringstream error;
528 error << "StkFrames::operator+=: frames argument must be of equal dimensions!";
529 Stk::handleError( error.str(), StkError::MEMORY_ACCESS );
530 }
531#endif
532
533 StkFloat *fptr = &f[0];
534 StkFloat *dptr = data_;
535 for ( unsigned int i=0; i<size_; i++ )
536 *dptr++ += *fptr++;
537 return *this;
538}

## ◆ operator*=()

StkFrames & stk::StkFrames::operator*= | ( | StkFrames & | f | ) |
| inline

Assignment by product operator into self.

The dimensions of the argument are expected to be the same as self. No range checking is performed unless STK_DEBUG is defined.

541{
542#if defined(_STK_DEBUG_)
543 if ( f.frames() != nFrames_ || f.channels() != nChannels_ ) {
544 std::ostringstream error;
545 error << "StkFrames::operator*=: frames argument must be of equal dimensions!";
546 Stk::handleError( error.str(), StkError::MEMORY_ACCESS );
547 }
548#endif
549
550 StkFloat *fptr = &f[0];
551 StkFloat *dptr = data_;
552 for ( unsigned int i=0; i<size_; i++ )
553 *dptr++ *= *fptr++;
554 return *this;
555}

## ◆ operator()() [1/2]

StkFloat & stk::StkFrames::operator() | ( | size_t | frame,
|  | unsigned int | channel
| ) |  |
| inline

Channel / frame subscript operator that returns a reference.

The result can be used as an lvalue. This reference is valid until the resize function is called or the array is destroyed. The `frame` index must be between 0 and frames() - 1. The `channel` index must be between 0 and channels() - 1. No range checking is performed unless STK_DEBUG is defined.

479{
480#if defined(_STK_DEBUG_)
481 if ( frame >= nFrames_ || channel >= nChannels_ ) {
482 std::ostringstream error;
483 error << "StkFrames::operator(): invalid frame (" << frame << ") or channel (" << channel << ") value!";
484 Stk::handleError( error.str(), StkError::MEMORY_ACCESS );
485 }
486#endif
487
488 return data_[ frame * nChannels_ + channel ];
489}

## ◆ operator()() [2/2]

StkFloat stk::StkFrames::operator() | ( | size_t | frame,
|  | unsigned int | channel
| ) |  | const
| inline

Channel / frame subscript operator that returns a value.

The `frame` index must be between 0 and frames() - 1. The `channel` index must be between 0 and channels() - 1. No range checking is performed unless STK_DEBUG is defined.

492{
493#if defined(_STK_DEBUG_)
494 if ( frame >= nFrames_ || channel >= nChannels_ ) {
495 std::ostringstream error;
496 error << "StkFrames::operator(): invalid frame (" << frame << ") or channel (" << channel << ") value!";
497 Stk::handleError( error.str(), StkError::MEMORY_ACCESS );
498 }
499#endif
500
501 return data_[ frame * nChannels_ + channel ];
502}

## ◆ interpolate()

StkFloat stk::StkFrames::interpolate | ( | StkFloat | frame,
|  | unsigned int | channel = `0`
| ) |  | const

Return an interpolated value at the fractional frame index and channel.

This function performs linear interpolation. The `frame` index must be between 0.0 and frames() - 1. The `channel` index must be between 0 and channels() - 1. No range checking is performed unless STK_DEBUG is defined.

## ◆ resize() [1/2]

virtual void stk::StkFrames::resize | ( | size_t | nFrames,
|  | unsigned int | nChannels = `1`
| ) |  |
| virtual

Resize self to represent the specified number of channels and frames.

Changes the size of self based on the number of frames and channels. No element assignment is performed. No memory deallocation occurs if the new size is smaller than the previous size. Further, no new memory is allocated when the new size is smaller or equal to a previously allocated size.

## ◆ resize() [2/2]

virtual void stk::StkFrames::resize | ( | size_t | nFrames,
|  | unsigned int | nChannels,
|  | StkFloat | value
| ) |  |
| virtual

Resize self to represent the specified number of channels and frames and perform element initialization.

Changes the size of self based on the number of frames and channels, and assigns `value` to every element. No memory deallocation occurs if the new size is smaller than the previous size. Further, no new memory is allocated when the new size is smaller or equal to a previously allocated size.

## ◆ getChannel()

StkFrames & stk::StkFrames::getChannel | ( | unsigned int | channel,
|  | StkFrames & | destinationFrames,
|  | unsigned int | destinationChannel
| ) |  | const

Retrieves a single channel.

Copies the specified `channel` into `destinationFrames's` `destinationChannel`. `destinationChannel` must be between 0 and destination.channels() - 1 and `channel` must be between 0 and channels() - 1. destination.frames() must be >= frames(). No range checking is performed unless STK_DEBUG is defined.

## ◆ setChannel()

void stk::StkFrames::setChannel | ( | unsigned int | channel,
|  | const StkFrames & | sourceFrames,
|  | unsigned int | sourceChannel
| ) |  |

Sets a single channel.

Copies the `sourceChannel` of `sourceFrames` into the `channel` of self. SourceFrames.frames() must be equal to frames(). No range checking is performed unless STK_DEBUG is defined.

## ◆ setDataRate()

void stk::StkFrames::setDataRate | ( | StkFloat | rate | ) |
| inline

Set the sample rate associated with the StkFrames data.

By default, this value is set equal to the current STK sample rate at the time of instantiation.

426{ dataRate_ = rate; };

## ◆ dataRate()

StkFloat stk::StkFrames::dataRate | ( | void |  | ) | const
| inline

Return the sample rate associated with the StkFrames data.

By default, this value is set equal to the current STK sample rate at the time of instantiation.

433{ return dataRate_; };

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

- Stk.h

The Synthesis ToolKit in C++ (STK)
©1995--2023 Perry R. Cook and Gary P. Scavone. All Rights Reserved.