MonoOutput Struct Reference

This struct encapsulates one frame of mono audio output. More...

#include <AudioOutput.h>

Detailed Description

This struct encapsulates one frame of mono audio output.

Internally, it really just boils down to a single int value, but the struct provides useful API an top of that, for the following:

a) To construct an output frame, you should use one of the from8Bit(), fromNBit(), etc. functions. Given a raw input value, at a known resolution (number of bits), this scales the output efficiently to whatever is needed on the target platform. Using this, your updateAudio() function will be portable across different CPU and different output methods, including external DACs. b) The struct provides some convenience API on top of this. Right now, this is the function clip(), replacing the more verbose, and non-portable constrain(x, -244, 243) found in some old sketches. c) The struct provides accessors l() and r() that are source-compatible with StereoOutput, making it easy to e.g. implement support for an external DAC in both mono and stereo. d) Finally, an automatic conversion operator to int aka AudioOutput_t provides backward compatibility with old Mozzi sketches. Internally, the compiler will actually do away with this whole struct, leaving just the same basic fast integer operations as in older Mozzi sketches. However, now, you don't have to rewrite those for different configurations.

Definition at line 111 of file AudioOutput.h.

Public Member Functions
	MonoOutput ()
	Default constructor. More...
	MonoOutput (AudioOutputStorage_t l)
	Construct an audio frame from raw values (zero-centered)
	operator AudioOutputStorage_t () const
	Conversion to int operator.
AudioOutputStorage_t	l () const
AudioOutputStorage_t	r () const
MonoOutput &	clip ()
	Clip frame to supported range. More...

Static Public Member Functions
template<typename T >
static MonoOutput	fromNBit (uint8_t bits, T l)
	Construct an audio frame a zero-centered value known to be in the N bit range. More...
static MonoOutput	from8Bit (int16_t l)
	Construct an audio frame from a zero-centered value known to be in the 8 bit range. More...
static MonoOutput	from16Bit (int16_t l)
	Construct an audio frame from a zero-centered value known to be in the 16 bit range. More...
template<int8_t NI, int8_t NF, uint64_t RANGE>
static MonoOutput	fromSFix (SFix< NI, NF, RANGE > l)
	Construct an audio frame from a SFix type from FixMath. More...
template<typename A , typename B >
static MonoOutput	fromAlmostNBit (A bits, B l)
	Construct an audio frame a zero-centered value known to be above at almost but not quite the N bit range, e.g. More...

Constructor & Destructor Documentation

MonoOutput()

MonoOutput::MonoOutput ( )

inline

Default constructor.

Does not initialize the sample!

Definition at line 113 of file AudioOutput.h.

Member Function Documentation

clip()

MonoOutput& MonoOutput::clip ( )

inline

Clip frame to supported range.

This is useful when at times, but only rarely, the signal may exceed the usual range. Using this function does not avoid artifacts, entirely, but gives much better results than an overflow.

Definition at line 129 of file AudioOutput.h.

from16Bit()

static MonoOutput MonoOutput::from16Bit ( int16_t  l )

inlinestatic

Construct an audio frame from a zero-centered value known to be in the 16 bit range.

This is jsut a shortcut for fromNBit(16, ...) provided for convenience.

Definition at line 139 of file AudioOutput.h.

from8Bit()

static MonoOutput MonoOutput::from8Bit ( int16_t  l )

inlinestatic

Construct an audio frame from a zero-centered value known to be in the 8 bit range.

On AVR, if MOZZI_OUTPUT_PWM mode, this is effectively the same as calling the constructor, directly (no scaling gets applied). On platforms/configs using more bits, an appropriate left-shift will be performed.

Definition at line 137 of file AudioOutput.h.

fromAlmostNBit()

template<typename A , typename B >

static MonoOutput MonoOutput::fromAlmostNBit ( A  bits, B  l  )

inlinestatic

Construct an audio frame a zero-centered value known to be above at almost but not quite the N bit range, e.g.

at N=8 bits and a litte. On most platforms, this is exactly the same as fromNBit(), shifting up or down to the platforms' available resolution.

However, on AVR, MOZZI_OUTPUT_PWM mode (where about 8.5 bits are usable), the value will be shifted to the (almost) 9 bit range, instead of to the 8 bit range. allowing to make use of that extra half bit of resolution. In many cases it is useful to follow up this call with clip(). E.g.:

return MonoOutput::fromAlmostNBit(10, oscilA.next() + oscilB.next() + oscilC.next()).clip();

Definition at line 153 of file AudioOutput.h.

fromNBit()

template<typename T >

static MonoOutput MonoOutput::fromNBit ( uint8_t  bits, T  l  )

inlinestatic

Construct an audio frame a zero-centered value known to be in the N bit range.

Appropriate left- or right-shifting will be performed, based on the number of output bits available. While this function takes care of the shifting, beware of potential overflow issues, if your intermediary results exceed the 16 bit range. Use proper casts to int32_t or larger in that case (and the compiler will automatically pick the 32 bit overload in this case)

Definition at line 134 of file AudioOutput.h.

fromSFix()

template<int8_t NI, int8_t NF, uint64_t RANGE>

static MonoOutput MonoOutput::fromSFix ( SFix< NI, NF, RANGE >  l )

inlinestatic

Construct an audio frame from a SFix type from FixMath.

Mozzi will figure out how many bits are in there and performs appropriate shifting to match the output range.

Definition at line 142 of file AudioOutput.h.