SampleFormat.cpp File Reference

Functions that work with Dither and initialise it. More...

#include "SampleFormat.h"
#include "Dither.h"
#include <math.h>
#include <stdlib.h>
#include <string.h>
#include "Prefs.h"
#include "Internat.h"

Include dependency graph for SampleFormat.cpp:

Go to the source code of this file.

Functions
void	InitDitherers ()
TranslatableString	GetSampleFormatStr (sampleFormat format)
void	ClearSamples (samplePtr dst, sampleFormat format, size_t start, size_t len)
void	ReverseSamples (samplePtr dst, sampleFormat format, int start, int len)
void	SamplesToFloats (constSamplePtr src, sampleFormat srcFormat, float *dst, size_t len, size_t srcStride, size_t dstStride)
	Copy samples from any format into the widest format, which is 32 bit float, with no dithering. More...
void	CopySamples (constSamplePtr src, sampleFormat srcFormat, samplePtr dst, sampleFormat dstFormat, size_t len, DitherType ditherType, unsigned int srcStride, unsigned int dstStride)
	Copy samples from any format to any other format; apply dithering only if narrowing the format. More...

Variables
DitherType	gLowQualityDither = DitherType::none
	These global variables are assigned at application startup or after change of preferences. More...
DitherType	gHighQualityDither = DitherType::shaped
static Dither	gDitherAlgorithm

Detailed Description

Functions that work with Dither and initialise it.

This file handles converting between all of the different sample formats that Audacity supports, such as 16-bit, 24-bit (packed into a 32-bit int), and 32-bit float.

Floating-point samples use the range -1.0...1.0, inclusive. Integer formats use the full signed range of their data type, for example 16-bit samples use the range -32768...32767. This means that reading in a wav file and writing it out again ('round tripping'), via floats, is lossless; -32768 equates to -1.0f and 32767 equates to +1.0f - (a little bit). It also means (unfortunately) that writing out +1.0f leads to clipping by 1 LSB. This creates some distortion, but I (MJS) have not been able to measure it, it's so small. Zero is preserved.

http://limpet.net/audacity/bugzilla/show_bug.cgi?id=200 leads to some of the discussions that were held about this.

Note: These things are now handled by the Dither class, which also replaces the CopySamples() method (msmeyer)

Definition in file SampleFormat.cpp.

Function Documentation

ClearSamples()

void ClearSamples	(	samplePtr	dst,
		sampleFormat	format,
		size_t	start,
		size_t	len
	)

Definition at line 75 of file SampleFormat.cpp.

{
   auto size = SAMPLE_SIZE(format);
   memset(dst + start*size, 0, len*size);
}

References anonymous_namespace{ExportPCM.cpp}::format, SAMPLE_SIZE, and size.

Referenced by RingBuffer::Clear(), AudioIO::DrainRecordBuffers(), Sequence::Get(), WideSampleSequence::GetFloats(), WaveTrack::GetOne(), SampleBlock::GetSamples(), RingBuffer::Put(), and Sequence::SetSamples().

Here is the caller graph for this function:

CopySamples()

void CopySamples	(	constSamplePtr	src,
		sampleFormat	srcFormat,
		samplePtr	dst,
		sampleFormat	dstFormat,
		size_t	len,
		DitherType	ditherType = gHighQualityDither,
		unsigned int	srcStride = 1,
		unsigned int	dstStride = 1
	)

Copy samples from any format to any other format; apply dithering only if narrowing the format.

Parameters

src	address of source samples
srcFormat	format of source samples, determines sizeof each one
dst	address of floating-point numbers
len	count of samples to copy
srcStride	how many samples to advance src after copying each one
dstString	how many samples to advance dst after copying each one
dstFormat	format of destination samples, determines sizeof each one
ditherType	choice of dithering algorithm to use if narrowing the format

Parameters

ditherType

default is loaded from a global variable

Definition at line 109 of file SampleFormat.cpp.

{
   gDitherAlgorithm.Apply(
      ditherType,
      src, srcFormat, dst, dstFormat, len, srcStride, dstStride);
}

References Dither::Apply(), and gDitherAlgorithm.

Referenced by AUPImportFileHandle::AddSamples(), Sequence::Append(), Sequence::ConvertToSampleFormat(), Sequence::DoAppend(), RingBuffer::Get(), SqliteSampleBlock::GetBlob(), PCMExportProcessor::Process(), Mixer::Process(), RingBuffer::Put(), SamplesToFloats(), and Sequence::SetSamples().

Here is the call graph for this function:

Here is the caller graph for this function:

GetSampleFormatStr()

TranslatableString GetSampleFormatStr

(

sampleFormat

format

)

Definition at line 58 of file SampleFormat.cpp.

{
   switch(format) {
   case int16Sample:
      /* i18n-hint: Audio data bit depth (precision): 16-bit integers */
      return XO("16-bit PCM");
   case int24Sample:
      /* i18n-hint: Audio data bit depth (precision): 24-bit integers */
      return XO("24-bit PCM");
   case floatSample:
      /* i18n-hint: Audio data bit depth (precision): 32-bit floating point */
      return XO("32-bit float");
   }
   return XO("Unknown format"); // compiler food
}

References floatSample, anonymous_namespace{ExportPCM.cpp}::format, int16Sample, int24Sample, and XO().

Referenced by FormatMenuTable::OnFormatChange(), and Sequence::Paste().

Here is the call graph for this function:

Here is the caller graph for this function:

InitDitherers()

void InitDitherers

(

)

Definition at line 51 of file SampleFormat.cpp.

{
   // Read dither preferences
   gLowQualityDither = Dither::FastDitherChoice();
   gHighQualityDither = Dither::BestDitherChoice();
}

References Dither::BestDitherChoice(), Dither::FastDitherChoice(), gHighQualityDither, and gLowQualityDither.

Referenced by QualityPrefs::Commit(), and AudacityApp::InitPart2().

Here is the call graph for this function:

Here is the caller graph for this function:

ReverseSamples()

void ReverseSamples	(	samplePtr	dst,
		sampleFormat	format,
		int	start,
		int	len
	)

Definition at line 82 of file SampleFormat.cpp.

{
   auto size = SAMPLE_SIZE(format);
   samplePtr first = dst + start * size;
   samplePtr last = dst + (start + len - 1) * size;
   enum : size_t { fixedSize = SAMPLE_SIZE(floatSample) };
   wxASSERT(static_cast<size_t>(size) <= fixedSize);
   char temp[fixedSize];
   while (first < last) {
      memcpy(temp, first, size);
      memcpy(first, last, size);
      memcpy(last, temp, size);
      first += size;
      last -= size;
   }
}

References floatSample, anonymous_namespace{ExportPCM.cpp}::format, SAMPLE_SIZE, and size.

Referenced by WaveTrack::GetOne(), and ClipTimeAndPitchSource::Pull().

Here is the caller graph for this function:

SamplesToFloats()

void SamplesToFloats	(	constSamplePtr	src,
		sampleFormat	srcFormat,
		float *	dst,
		size_t	len,
		size_t	srcStride = 1,
		size_t	dstStride = 1
	)

Copy samples from any format into the widest format, which is 32 bit float, with no dithering.

Parameters

src	address of source samples
srcFormat	format of source samples, determines sizeof each one
dst	address of floating-point numbers
len	count of samples to copy
srcStride	how many samples to advance src after copying each one
dstString	how many samples to advance dst after copying each one

Definition at line 100 of file SampleFormat.cpp.

{
   CopySamples( src, srcFormat,
      reinterpret_cast<samplePtr>(dst), floatSample, len,
      DitherType::none,
      srcStride, dstStride);
}

References CopySamples(), floatSample, and none.

Referenced by AudioIoCallback::AudioCallback(), SqliteSampleBlock::CalcSummary(), and DoSoftwarePlaythrough().

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

gDitherAlgorithm

Dither gDitherAlgorithm

static

Definition at line 49 of file SampleFormat.cpp.

Referenced by CopySamples().

gHighQualityDither

DitherType gHighQualityDither = DitherType::shaped

Definition at line 48 of file SampleFormat.cpp.

Referenced by AUPImportFileHandle::AddSamples(), Sequence::Append(), Sequence::ConvertToSampleFormat(), InitDitherers(), PCMExportProcessor::Process(), Mixer::Process(), and Sequence::SetSamples().

gLowQualityDither

DitherType gLowQualityDither = DitherType::none

These global variables are assigned at application startup or after change of preferences.

Definition at line 47 of file SampleFormat.cpp.

Referenced by InitDitherers(), and Mixer::Process().