pa_converters.c File Reference

Conversion function implementations. More...

#include "pa_converters.h"
#include "pa_dither.h"
#include "pa_endianness.h"
#include "pa_types.h"

Macros
#define	PA_SELECT_FORMAT_(format, float32, int32, int24, int16, int8, uint8)
#define	PA_SELECT_CONVERTER_DITHER_CLIP_(flags, source, destination)
#define	PA_SELECT_CONVERTER_DITHER_(flags, source, destination)
#define	PA_USE_CONVERTER_(source, destination)   return paConverters. source ## _To_ ## destination;
#define	PA_UNITY_CONVERSION_(wordlength)   return paConverters. Copy_ ## wordlength ## _To_ ## wordlength;
#define	PA_CLIP_(val, min, max)   { val = ((val) < (min)) ? (min) : (((val) > (max)) ? (max) : (val)); }

Functions
PaSampleFormat	PaUtil_SelectClosestAvailableFormat (PaSampleFormat availableFormats, PaSampleFormat format)
PaUtilConverter *	PaUtil_SelectConverter (PaSampleFormat sourceFormat, PaSampleFormat destinationFormat, PaStreamFlags flags)
PaUtilZeroer *	PaUtil_SelectZeroer (PaSampleFormat destinationFormat)

Variables
PaUtilConverterTable	paConverters
PaUtilZeroerTable	paZeroers

Detailed Description

Conversion function implementations.

If the C9x function lrintf() is available, define PA_USE_C99_LRINTF to use it

Todo:

Consider whether functions which dither but don't clip should exist, V18 automatically enabled clipping whenever dithering was selected. Perhaps we should do the same. see: "require clipping for dithering sample conversion functions?" http://www.portaudio.com/trac/ticket/112

Todo:

implement the converters marked IMPLEMENT ME: Int32_To_Int24_Dither, Int32_To_UInt8_Dither, Int24_To_Int16_Dither, Int24_To_Int8_Dither, Int24_To_UInt8_Dither, Int16_To_Int8_Dither, Int16_To_UInt8_Dither see: "some conversion functions are not implemented in pa_converters.c" http://www.portaudio.com/trac/ticket/35

Todo:

review the converters marked REVIEW: Float32_To_Int32, Float32_To_Int32_Dither, Float32_To_Int32_Clip, Float32_To_Int32_DitherClip, Int32_To_Int16_Dither, Int32_To_Int8_Dither, Int16_To_Int32

Macro Definition Documentation

#define PA_CLIP_	(		val,
			min,
			max
	)		{ val = ((val) < (min)) ? (min) : (((val) > (max)) ? (max) : (val)); }

#define PA_SELECT_CONVERTER_DITHER_	(		flags,
			source,
			destination
	)

Value:

if( flags & paDitherOff ){ /* no dither */                                 \
        return paConverters. source ## _To_ ## destination;                    \
    }else{ /* dither */                                                        \
        return paConverters. source ## _To_ ## destination ## _Dither;         \
    }

Referenced by PaUtil_SelectConverter().

#define PA_SELECT_CONVERTER_DITHER_CLIP_	(		flags,
			source,
			destination
	)

Value:

if( flags & paClipOff ){ /* no clip */                                     \
        if( flags & paDitherOff ){ /* no dither */                             \
            return paConverters. source ## _To_ ## destination;                \
        }else{ /* dither */                                                    \
            return paConverters. source ## _To_ ## destination ## _Dither;     \
        }                                                                      \
    }else{ /* clip */                                                          \
        if( flags & paDitherOff ){ /* no dither */                             \
            return paConverters. source ## _To_ ## destination ## _Clip;       \
        }else{ /* dither */                                                    \
            return paConverters. source ## _To_ ## destination ## _DitherClip; \
        }                                                                      \
    }

Referenced by PaUtil_SelectConverter().

#define PA_SELECT_FORMAT_	(		format,
			float32,
			int32,
			int24,
			int16,
			int8,
			uint8
	)

Value:

switch( format & ~paNonInterleaved ){                                      \
    case paFloat32:                                                            \
        float32                                                                \
    case paInt32:                                                              \
        int32                                                                  \
    case paInt24:                                                              \
        int24                                                                  \
    case paInt16:                                                              \
        int16                                                                  \
    case paInt8:                                                               \
        int8                                                                   \
    case paUInt8:                                                              \
        uint8                                                                  \
    default: return 0;                                                         \
    }

Referenced by PaUtil_SelectConverter().

#define PA_UNITY_CONVERSION_

(

wordlength

)

return paConverters. Copy_ ## wordlength ## _To_ ## wordlength;

Referenced by PaUtil_SelectConverter().

#define PA_USE_CONVERTER_	(		source,
			destination
	)		return paConverters. source ## _To_ ## destination;

Referenced by PaUtil_SelectConverter().

Function Documentation

PaSampleFormat PaUtil_SelectClosestAvailableFormat	(	PaSampleFormat	availableFormats,
		PaSampleFormat	format
	)

Choose an available sample format which is most appropriate for representing the requested format. If the requested format is not available higher quality formats are considered before lower quality formates.

Parameters

availableFormats	A variable containing the logical OR of all available formats.
format	The desired format.

Returns

The most appropriate available format for representing the requested format.

References paCustomFormat, paNonInterleaved, and paSampleFormatNotSupported.

PaUtilConverter* PaUtil_SelectConverter	(	PaSampleFormat	sourceFormat,
		PaSampleFormat	destinationFormat,
		PaStreamFlags	flags
	)

Find a sample converter function for the given source and destinations formats and flags (clip and dither.)

Returns

A pointer to a PaUtilConverter which will perform the requested conversion, or NULL if the given format conversion is not supported. For conversions where clipping or dithering is not necessary, the clip and dither flags are ignored and a non-clipping or dithering version is returned. If the source and destination formats are the same, a function which copies data of the appropriate size will be returned.

References PA_SELECT_CONVERTER_DITHER_, PA_SELECT_CONVERTER_DITHER_CLIP_, PA_SELECT_FORMAT_, PA_UNITY_CONVERSION_, and PA_USE_CONVERTER_.

Referenced by main(), and PaUtil_InitializeBufferProcessor().

PaUtilZeroer* PaUtil_SelectZeroer

(

PaSampleFormat

destinationFormat

)

Find a buffer zeroer function for the given destination format.

Returns

A pointer to a PaUtilZeroer which will perform the requested zeroing.

References paFloat32, paInt16, paInt24, paInt32, paInt8, paNonInterleaved, paUInt8, paZeroers, PaUtilZeroerTable::Zero16, PaUtilZeroerTable::Zero24, PaUtilZeroerTable::Zero32, PaUtilZeroerTable::Zero8, and PaUtilZeroerTable::ZeroU8.

Referenced by PaUtil_InitializeBufferProcessor().

Variable Documentation

PaUtilConverterTable paConverters

A table of pointers to all required converter functions. PaUtil_SelectConverter() uses this table to lookup the appropriate conversion functions. The fields of this structure are initialized with default conversion functions. Fields may be NULL, indicating that no conversion function is available. User code may substitue optimised conversion functions by assigning different function pointers to these fields.

Note

If the PA_NO_STANDARD_CONVERTERS preprocessor variable is defined, PortAudio's standard converters will not be compiled, and all fields of this structure will be initialized to NULL. In such cases, users should supply their own conversion functions if the require PortAudio to open a stream that requires sample conversion.

See Also

PaUtilConverterTable, PaUtilConverter, PaUtil_SelectConverter

Referenced by PaUtil_InitializeX86PlainConverters().

PaUtilZeroerTable paZeroers

Initial value:

= {
    ZeroU8,  
    Zero8,  
    Zero16,  
    Zero24,  
    Zero32,  
}

A table of pointers to all required zeroer functions. PaUtil_SelectZeroer() uses this table to lookup the appropriate conversion functions. The fields of this structure are initialized with default conversion functions. User code may substitue optimised conversion functions by assigning different function pointers to these fields.

Note

If the PA_NO_STANDARD_ZEROERS preprocessor variable is defined, PortAudio's standard zeroers will not be compiled, and all fields of this structure will be initialized to NULL. In such cases, users should supply their own zeroing functions for the sample sizes which they intend to use.

See Also

PaUtilZeroerTable, PaUtilZeroer, PaUtil_SelectZeroer

Referenced by PaUtil_SelectZeroer().