Home   Information   Classes   Download   Usage   Mail List   Requirements   Links   FAQ   Tutorial


Public Member Functions | Friends | 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. More...
 
StkFloat operator[] (size_t n) const
 Subscript operator that returns the value at element n of self. More...
 
StkFrames operator+ (const StkFrames &frames) const
 Sum operator. More...
 
StkFramesoperator+= (StkFrames &f)
 Assignment by sum operator into self. More...
 
StkFramesoperator*= (StkFrames &f)
 Assignment by product operator into self. More...
 
StkFrames operator* (StkFloat v) const
 Scaling operator (StkFrame * StkFloat).
 
StkFramesoperator*= (StkFloat v)
 Scaling operator (inline).
 
StkFloat & operator() (size_t frame, unsigned int channel)
 Channel / frame subscript operator that returns a reference. More...
 
StkFloat operator() (size_t frame, unsigned int channel) const
 Channel / frame subscript operator that returns a value. More...
 
StkFloat interpolate (StkFloat frame, unsigned int channel=0) const
 Return an interpolated value at the fractional frame index and channel. More...
 
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. More...
 
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. More...
 
StkFramesgetChannel (unsigned int channel, StkFrames &destinationFrames, unsigned int destinationChannel) const
 Retrieves a single channel. More...
 
void setChannel (unsigned int channel, const StkFrames &sourceFrames, unsigned int sourceChannel)
 Sets a single channel. More...
 
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. More...
 
StkFloat dataRate (void) const
 Return the sample rate associated with the StkFrames data. More...
 

Friends

StkFrames operator* (StkFloat v, const StkFrames &f)
 Scaling operator (StkFloat * StkFrame)
 

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–2021.

Member Function Documentation

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 }
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 }
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 }
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 }
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 }
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 }
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 }
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.

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.

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.

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.

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.

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; };
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:

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