Dither Class Reference

This class implements various functions for dithering and is derived from the dither code in the Ardour project, written by Steve Harris. More...

#include <Dither.h>

Collaboration diagram for Dither:

Public Member Functions
	Dither ()
	Default constructor. More...
void	Reset ()
	Reset state of the dither. More...
void	Apply (DitherType ditherType, constSamplePtr source, sampleFormat sourceFormat, samplePtr dest, sampleFormat destFormat, unsigned int len, unsigned int sourceStride=1, unsigned int destStride=1)

Static Public Member Functions
static DitherType	FastDitherChoice ()
static DitherType	BestDitherChoice ()

Static Public Attributes
static EnumSetting< DitherType >	FastSetting
static EnumSetting< DitherType >	BestSetting

Detailed Description

This class implements various functions for dithering and is derived from the dither code in the Ardour project, written by Steve Harris.

Dithering is only done if it really is necessary. Otherwise (e.g. when the source and destination format of the samples is the same), the samples are only copied or converted. However, copied samples are always checked for out-of-bounds values and possibly clipped accordingly.

These dither algorithms are currently implemented:

• No dithering at all
• Rectangle dithering
• Triangle dithering
• Noise-shaped dithering

Dither class. You must construct an instance because it keeps state. Call Dither::Apply() to apply the dither. You can call Reset() between subsequent dithers to reset the dither state and get deterministic behaviour.

Definition at line 22 of file Dither.h.

Constructor & Destructor Documentation

Dither()

Dither::Dither

(

)

Default constructor.

Definition at line 187 of file Dither.cpp.

{
    // On startup, initialize dither by resetting values
    Reset();
}

References Reset().

Here is the call graph for this function:

Member Function Documentation

Apply()

void Dither::Apply	(	DitherType	ditherType,
		constSamplePtr	source,
		sampleFormat	sourceFormat,
		samplePtr	dest,
		sampleFormat	destFormat,
		unsigned int	len,
		unsigned int	sourceStride = 1,
		unsigned int	destStride = 1
	)

Apply the actual dithering. Expects the source sample in the 'source' variable, the destination sample in the 'dest' variable, and hints to the formats of the samples. Even if the sample formats are the same, samples are clipped, if necessary.

Definition at line 216 of file Dither.cpp.

{
    unsigned int i;
 
    // This code is not designed for 16-bit or 64-bit machine
    wxASSERT(sizeof(int) == 4);
    wxASSERT(sizeof(short) == 2);
 
    // Check parameters
    wxASSERT(source);
    wxASSERT(dest);
    wxASSERT(len >= 0);
    wxASSERT(sourceStride > 0);
    wxASSERT(destStride > 0);
 
    if (len == 0)
        return; // nothing to do
 
    if (destFormat == sourceFormat)
    {
        // No need to dither, because source and destination
        // format are the same. Just copy samples.
        if (destStride == 1 && sourceStride == 1)
            memcpy(dest, source, len * SAMPLE_SIZE(destFormat));
        else
        {
            if (sourceFormat == floatSample)
            {
                auto d = (float*)dest;
                auto s = (const float*)source;
 
                for (i = 0; i < len; i++, d += destStride, s += sourceStride)
                    *d = *s;
            } else
            if (sourceFormat == int24Sample)
            {
                auto d = (int*)dest;
                auto s = (const int*)source;
 
                for (i = 0; i < len; i++, d += destStride, s += sourceStride)
                    *d = *s;
            } else
            if (sourceFormat == int16Sample)
            {
                auto d = (short*)dest;
                auto s = (const short*)source;
 
                for (i = 0; i < len; i++, d += destStride, s += sourceStride)
                    *d = *s;
            } else {
                wxASSERT(false); // source format unknown
            }
        }
    } else
    if (destFormat == floatSample)
    {
        // No need to dither, just convert samples to float.
        // No clipping should be necessary.
        auto d = (float*)dest;
 
        if (sourceFormat == int16Sample)
        {
            auto s = (const short*)source;
            for (i = 0; i < len; i++, d += destStride, s += sourceStride)
                *d = FROM_INT16(s);
        } else
        if (sourceFormat == int24Sample)
        {
            auto s = (const int*)source;
            for (i = 0; i < len; i++, d += destStride, s += sourceStride)
                *d = FROM_INT24(s);
        } else {
            wxASSERT(false); // source format unknown
        }
    } else
    if (destFormat == int24Sample && sourceFormat == int16Sample)
    {
        // Special case when promoting 16 bit to 24 bit
        auto d = (int*)dest;
        auto s = (const short*)source;
        for (i = 0; i < len; i++, d += destStride, s += sourceStride)
            *d = ((int)*s) << 8;
    } else
    {
        // We must do dithering
        switch (ditherType)
        {
        case DitherType::none:
            DITHER(NoDither, mState, dest, destFormat, destStride, source, sourceFormat, sourceStride, len);
            break;
        case DitherType::rectangle:
            DITHER(RectangleDither, mState, dest, destFormat, destStride, source, sourceFormat, sourceStride, len);
            break;
        case DitherType::triangle:
            Reset(); // reset dither filter for this NEW conversion
            DITHER(TriangleDither, mState, dest, destFormat, destStride, source, sourceFormat, sourceStride, len);
            break;
        case DitherType::shaped:
            Reset(); // reset dither filter for this NEW conversion
            DITHER(ShapedDither, mState, dest, destFormat, destStride, source, sourceFormat, sourceStride, len);
            break;
        default:
            wxASSERT(false); // unknown dither algorithm
        }
    }
}

References DITHER(), floatSample, FROM_INT16(), FROM_INT24(), int16Sample, int24Sample, mState, NoDither(), none, rectangle, RectangleDither(), Reset(), SAMPLE_SIZE, shaped, ShapedDither(), triangle, and TriangleDither().

Referenced by CopySamples().

Here is the call graph for this function:

Here is the caller graph for this function:

BestDitherChoice()

DitherType Dither::BestDitherChoice ( )

static

Definition at line 415 of file Dither.cpp.

{
   return (DitherType) BestSetting.ReadEnum();
}

References BestSetting, and EnumSetting< Enum >::ReadEnum().

Referenced by InitDitherers().

Here is the call graph for this function:

Here is the caller graph for this function:

FastDitherChoice()

DitherType Dither::FastDitherChoice ( )

static

Definition at line 410 of file Dither.cpp.

{
   return (DitherType) FastSetting.ReadEnum();
}

References FastSetting, and EnumSetting< Enum >::ReadEnum().

Referenced by InitDitherers().

Here is the call graph for this function:

Here is the caller graph for this function:

Reset()

void Dither::Reset

(

)

Reset state of the dither.

Definition at line 193 of file Dither.cpp.

{
    mState.mTriangleState = 0;
    mState.mPhase = 0;
    memset(mState.mBuffer, 0, sizeof(float) * BUF_SIZE);
}

References BUF_SIZE, State::mBuffer, State::mPhase, mState, and State::mTriangleState.

Referenced by Apply(), and Dither().

Here is the caller graph for this function:

Member Data Documentation

BestSetting

EnumSetting< DitherType > Dither::BestSetting

static

Initial value:

{
   wxT("Quality/HQDitherAlgorithmChoice"),
   choicesDither,
   3, 
 
   
   intChoicesDither,
   wxT("Quality/HQDitherAlgorithm")
}

Definition at line 29 of file Dither.h.

Referenced by BestDitherChoice(), and QualityPrefs::PopulateOrExchange().

FastSetting

EnumSetting< DitherType > Dither::FastSetting

static

Initial value:

{
   wxT("Quality/DitherAlgorithmChoice"),
   choicesDither,
   0, 
 
   
   intChoicesDither,
   wxT("Quality/DitherAlgorithm")
}

Definition at line 28 of file Dither.h.

Referenced by FastDitherChoice(), and QualityPrefs::PopulateOrExchange().

---

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

• Dither.h
• Dither.cpp