generic.h File Reference

#include <wx/wx.h>
#include <wx/file.h>

Go to the source code of this file.

Classes
class	Exception
	Exception class. More...
class	ExceptionIO
	Input/Output exception. More...
class	ExceptionZero
	Division by zero exception. More...
struct	format_ex_t
	Input/output channel format structure. More...
struct	format_t
	One mono track format structure. More...
struct	wxFloat80
	IEEE 754 80 bit float number (extended). More...
Defines
#define	FM_NAME   "FinalMix"
	Standard constants.
#define	FM_VENDOR   "MD"
#define	FM_NAME_UPPER   "FINALMIX"
#define	FM_VERSION_STRING   "0.9.5"
#define	FM_PEAK_TAG   "FMPE"
#define	FM_PEAK_EXT   "fpe"
#define	FM_CLIP_TAG   "FMCL"
#define	FM_CLIP_NAME   "clipboard"
#define	FM_CLIP_EXT   "fcl"
#define	FM_CLIP_SUFFIX   "-" FM_VERSION_STRING
#define	FM_PROJECT_TAG   "FMPR"
#define	FM_PROJECT_EXT   "fpr"
#define	FULL_PERCENT   100
#define	__FUNCTION__   "unknown"
	Workarounds.
#define	__MSW__INT64_BUG__   (signed __int64)
#define	__MSW__DIRDLG_STYLE__   wxDD_NEW_DIR_BUTTON
#define	ASSERT(expr)   if (!(expr)) { throw Exception(EXC_ASSERT, wxString::Format("Assertion failed: %s (in %s() at %s on line %d)", #expr, __FUNCTION__, __FILE__, __LINE__)); }
	Assert exception generator.
#define	FATAL(desc)   { throw Exception(EXC_FATAL, wxString::Format("Fatal exception: %s (in %s() at %s on line %d)", desc, __FUNCTION__, __FILE__, __LINE__)); }
	Fatal exception generator.
Typedefs
typedef wxUint8	volume_t
	Channel volume representation.
typedef wxUint8	sample_pcm8u_t
	Sample type PCM 8 bit unsigned.
typedef wxInt8	sample_pcm8s_t
	Sample type PCM 8 bit signed.
typedef wxUint16	sample_pcm16u_t
	Sample type PCM 16 bit unsigned.
typedef wxInt16	sample_pcm16s_t
	Sample type PCM 16 bit signed.
typedef wxUint32	sample_pcm8u_w_t
	Sample type PCM 8 bit unsigned (mix precision).
typedef wxInt32	sample_pcm8s_w_t
	Sample type PCM 8 bit signed (mix precision).
typedef wxUint64	sample_pcm16u_w_t
	Sample type PCM 16 bit unsigned (mix precision).
typedef wxInt64	sample_pcm16s_w_t
	Sample type PCM 16 bit signed (mix precision).
typedef wxFloat64	floatsample_t
	Sample in float-point format.
typedef wxUint32	samplerate_t
	Sample rate (frequency) representation.
typedef wxUint64	samples_t
	Sample count representation.
typedef wxUint16	version_t
	Version representation.
typedef wxUint64	length_t
	Maximal length type.
typedef wxUint16	track_t
	Channel or track indexing type.
typedef wxUint32	ratio_t
	Display ratio type.
typedef wxUint8	bool_t
	Platform independent bool type.
Enumerations
enum	exception_t { EXC_WARN = 0, EXC_RUNTIME, EXC_ASSERT, EXC_FATAL }
	Exception severity levels. More...
enum	status_t {   OK = 0, IO_ERROR = -1, UNK_ERROR = -2, UNK_FORMAT = -3,   STRUCT_ERR = -4, UNS_FORMAT = -5 }
	Function return status type. More...
enum	encoding_t { PCM = 0 }
	Sample encoding type. More...
enum	bitencoding_t { UNSIGNED = 0, SIGNED }
	Bitwise encoding of sample type. More...
enum	samplewidth_t { BIT16 = 0, BIT8 }
	Bit width of sample type. More...
enum	endianess_t { LITTLE = 0, BIG }
	Endianess of sample type. More...
Functions
wxString	SetFilename (const wxString path, const wxString name, const wxString ext, const wxString fsuffix)
	Construct filename from components.
size_t	SampleLen (const format_t &format)
	Size of one sample.
size_t	SampleLen (const format_ex_t &format)
	Size of one sample (for format_ex_t).
void *	AllocSamples (const format_t &format, const samples_t count)
	Allocates memory for the given number of samples.
void *	AllocSamples (const format_ex_t &format, const samples_t count)
	Allocates memory for the given number of samples (for format_ex_t).
void	FreeSamples (const format_t &format, const void *data)
	Safely deallocates memory for samples.
void	FreeSamples (const format_ex_t &format, const void *data)
	Safely deallocates memory for samples (for format_ex_t).
void	SamplesAverage (const format_t &format, const samples_t samples, const void *inbuf, const void *outbuf)
	Returns average sample.
void	SamplesMax (const format_t &format, const samples_t samples, const void *inbuf, const void *outbuf)
	Returns maximal sample.
floatsample_t	NormSample (const format_t &format, const void *sample, const floatsample_t max)
	Returns normalized value of the sample (in internal format).
floatsample_t	SamplesAverageNorm (const format_t &format, const samples_t samples, const void *inbuf, const floatsample_t max)
	Returns average sample in normalized internal format.
floatsample_t	SamplesMaxNorm (const format_t &format, const samples_t samples, const void *inbuf, const floatsample_t max)
	Returns normalized value of the sample (in internal format).
samples_t	SamplesCmp (const format_t &infmt, const format_t &outfmt, const samples_t samples)
	Converts number of samples from one format to another.
samples_t	SamplesCmpIn (const format_t &infmt, const format_t &outfmt, const samples_t insamples)
	Converts number of samples from one format to another (reverse conversion).
samples_t	SamplesConv (const format_t &infmt, const format_ex_t &outfmt, const samples_t samples, void *inbuf, void *outbuf)
	Local coversion between various formats.
void	ClearSamples (const format_ex_t &format, const samples_t samples, void *buf)
	Zero modulation.
bool	AddSamples (const format_ex_t &format, const volume_t volume[], const samples_t tsamples, const samples_t samples, const void *tbuf, const void *buf)
	Add additional samples to given samples.
void	FormatAlias (const format_ex_t &infmt, format_t &outfmt)
	Convert format_ex_t to format_t.
void *	GetSample (const format_t &format, const samples_t pos, const void *samples)
	Returns pointer to one single sample in buffer.
void *	GetSample (const format_ex_t &format, const track_t chan, const samples_t pos, const void *samples)
	Returns pointer to one single sample in buffer.
void	ReadValue (wxFile &file, void *buf, size_t size)
	Read data from file.
void	ReadTag (wxFile &file, char *str, size_t size)
	Read string from file.
void	ReadString (wxFile &file, wxString &str)
	Read variable-length string from file.
void	WriteValue (wxFile &file, const void *buf, const size_t size)
	Write data to file.
void	WriteTag (wxFile &file, const char *str)
	Write string to file.
void	WriteString (wxFile &file, const char *str)
	Write variable-length string to file.
void	Seek (wxFile &file, off_t offset)
	Seek in file.
template<class T> T	min (const T a, const T b)
	Minimum of two values.
template<class T> T	max (const T a, const T b)
	Maximum of two values.
Variables
const volume_t	volume_min
	Minimal channel volume.
const volume_t	volume_max
	Maximal channel volume.
const sample_pcm8u_t	sample_pcm8u_min
	Sample precision constants.
const sample_pcm8u_t	sample_pcm8u_max
const sample_pcm8u_t	sample_pcm8u_0
const sample_pcm8s_t	sample_pcm8s_min
const sample_pcm8s_t	sample_pcm8s_max
const sample_pcm8s_t	sample_pcm8s_0
const sample_pcm16u_t	sample_pcm16u_min
const sample_pcm16u_t	sample_pcm16u_max
const sample_pcm16u_t	sample_pcm16u_0
const sample_pcm16s_t	sample_pcm16s_min
const sample_pcm16s_t	sample_pcm16s_max
const sample_pcm16s_t	sample_pcm16s_0
const version_t	fmfile_version_major
	Major version number in project file header.
const version_t	fmfile_version_minor
	Minor version number in project file header.

---

Define Documentation

#define __FUNCTION__   "unknown"

Workarounds. MS Visual C++ doesn't support __FUNCTION__ macro and cannot convert from unsigned __in64 to double.

#define __MSW__DIRDLG_STYLE__   wxDD_NEW_DIR_BUTTON

#define __MSW__INT64_BUG__   (signed __int64)

#define ASSERT (  expr   )     if (!(expr)) { throw Exception(EXC_ASSERT, wxString::Format("Assertion failed: %s (in %s() at %s on line %d)", #expr, __FUNCTION__, __FILE__, __LINE__)); }

Assert exception generator. Checks the value of the expression and if it is false, raises an exception describing the assertion with severity EXC_ASSERT. The test is active. Parameters: expr  Condition which should be true.

#define FATAL (  desc   )     { throw Exception(EXC_FATAL, wxString::Format("Fatal exception: %s (in %s() at %s on line %d)", desc, __FUNCTION__, __FILE__, __LINE__)); }

Fatal exception generator. Raises unconditionaly a fatal exception Parameters: desc  Description of the error.

#define FM_CLIP_EXT   "fcl"

#define FM_CLIP_NAME   "clipboard"

#define FM_CLIP_SUFFIX   "-" FM_VERSION_STRING

#define FM_CLIP_TAG   "FMCL"

#define FM_NAME   "FinalMix"

Standard constants.

#define FM_NAME_UPPER   "FINALMIX"

#define FM_PEAK_EXT   "fpe"

#define FM_PEAK_TAG   "FMPE"

#define FM_PROJECT_EXT   "fpr"

#define FM_PROJECT_TAG   "FMPR"

#define FM_VENDOR   "MD"

#define FM_VERSION_STRING   "0.9.5"

#define FULL_PERCENT   100

---

Typedef Documentation

typedef wxUint8 bool_t

Platform independent bool type.

typedef wxFloat64 floatsample_t

Sample in float-point format.

typedef wxUint64 length_t

Maximal length type.

typedef wxUint32 ratio_t

Display ratio type.

typedef wxInt16 sample_pcm16s_t

Sample type PCM 16 bit signed.

typedef wxInt64 sample_pcm16s_w_t

Sample type PCM 16 bit signed (mix precision).

typedef wxUint16 sample_pcm16u_t

Sample type PCM 16 bit unsigned.

typedef wxUint64 sample_pcm16u_w_t

Sample type PCM 16 bit unsigned (mix precision).

typedef wxInt8 sample_pcm8s_t

Sample type PCM 8 bit signed.

typedef wxInt32 sample_pcm8s_w_t

Sample type PCM 8 bit signed (mix precision).

typedef wxUint8 sample_pcm8u_t

Sample type PCM 8 bit unsigned.

typedef wxUint32 sample_pcm8u_w_t

Sample type PCM 8 bit unsigned (mix precision).

typedef wxUint32 samplerate_t

Sample rate (frequency) representation.

typedef wxUint64 samples_t

Sample count representation.

typedef wxUint16 track_t

Channel or track indexing type.

typedef wxUint16 version_t

Version representation.

typedef wxUint8 volume_t

Channel volume representation.

---

Enumeration Type Documentation

enum bitencoding_t

Bitwise encoding of sample type. Enumeration values: UNSIGNED  Unsigned. SIGNED  Signed.

enum encoding_t

Sample encoding type. Enumeration values: PCM  PCM.

enum endianess_t

Endianess of sample type. Type of multi-byte encoding. Enumeration values: LITTLE  Little endian (Intel). BIG  Big endian (Motorola).

enum exception_t

Exception severity levels. Enumeration values: EXC_WARN  Warning, no error. EXC_RUNTIME  Run-time error. EXC_ASSERT  Assertion failed. EXC_FATAL  Fatal error.

enum samplewidth_t

Bit width of sample type. Enumeration values: BIT16  16 bits BIT8  8 bits

enum status_t

Function return status type. Enumeration values: OK  No error. IO_ERROR  Input/output error. UNK_ERROR  Unknown error. UNK_FORMAT  Unknown file format. STRUCT_ERR  Error in file structure. UNS_FORMAT  Unsupported file format.

---

Function Documentation

bool AddSamples (  const format_ex_t &  format, const volume_t  volume[], const samples_t  tsamples, const samples_t  samples, const void *  tbuf, const void *  buf )

Add additional samples to given samples. This function adds additional samples to the samples already present in the buffer, practically performing an overlay-mix. The samples are simply added together, however underflow or overflow is checked and handled by cropping (setting maximal or minimal valid value). The return value indicates whether the overflow or underflow occured. Raises Fatal on unknown format. Parameters: format  Format description. volume  Array of volume_t defining the volume for each output channel. tsamples  Number of samples of the new audio data. samples  Number of samples in the input/output buffer. tbuf  New audio data. buf  Input/output buffer. Returns: Returns true if overflow or underflow occured.

void* AllocSamples (  const format_ex_t &  format, const samples_t  count )

Allocates memory for the given number of samples (for format_ex_t). Dynamicaly allocates memory for storing given number of samples in given format. Raises Fatal on unknown format. Parameters: format  Sample format description, in case of format_ex_t the number of channels in the structure is ignored. count  Number of samples to allocate. Returns: Pointer to the new allocated memory, NULL on fail.

void* AllocSamples (  const format_t &  format, const samples_t  count )

Allocates memory for the given number of samples. Dynamicaly allocates memory for storing given number of samples in given format. Raises Fatal on unknown format. Parameters: format  Sample format description, in case of format_ex_t the number of channels in the structure is ignored. count  Number of samples to allocate. Returns: Pointer to the new allocated memory, NULL on fail.

void ClearSamples (  const format_ex_t &  format, const samples_t  samples, void *  buf )

Zero modulation. Sets the buffer to zero amplitude. Raises Fatal on unknown format. Parameters: format  Format description. samples  Number of samples to zero. buf  Output buffer, must be preallocated to hold at least all zero samples.

void FormatAlias (  const format_ex_t &  infmt, format_t &  outfmt )

Convert format_ex_t to format_t. Converts format_ex_t structure to format_t, discarting the number of channels. Parameters: infmt  Input structure (format_ex_t). outfmt  Output structure (format_t).

void FreeSamples (  const format_ex_t &  format, const void *  data )

Safely deallocates memory for samples (for format_ex_t). Safely deallocates memory previously allocated by AllocSamples. Raises Fatal on unknown format, other error states indicates in the same way as delete operator. Parameters: format  Sample format description, in case of format_ex_t the number of channels in the structure is ignored. data  Pointer to the memory allocated by AllocSamples. Returns: Return true on sucess.

void FreeSamples (  const format_t &  format, const void *  data )

Safely deallocates memory for samples. Safely deallocates memory previously allocated by AllocSamples. Raises Fatal on unknown format, other error states indicates in the same way as delete operator. Parameters: format  Sample format description, in case of format_ex_t the number of channels in the structure is ignored. data  Pointer to the memory allocated by AllocSamples. Returns: Return true on sucess.

void* GetSample (  const format_ex_t &  format, const track_t  chan, const samples_t  pos, const void *  samples )  [inline]

Returns pointer to one single sample in buffer. Returns the pointer of a sample indexed by pos in buffer. Raises Fatal on unknown format. Parameters: format  Sample format description. chan  Channel number. pos  Position of the sample in the buffer (in samples, zero based). samples  Input buffer. Returns: Pointer to the sample (in the original buffer, not a copy).

void* GetSample (  const format_t &  format, const samples_t  pos, const void *  samples )  [inline]

Returns pointer to one single sample in buffer. Returns the pointer of a sample indexed by pos in buffer. Raises Fatal on unknown format. Parameters: format  Sample format description. pos  Position of the sample in the buffer (in samples, zero based). samples  Input buffer. Returns: Pointer to the sample (in the original buffer, not a copy).

template<class T> T max (  const T  a, const T  b )  [inline]

Maximum of two values. Returns the greatest value (according to operator <) of two inputs of the same type. The operator < must be defined for this type. Parameters: a  First value. b  Second value. Returns: Maximum of the two values.

template<class T> T min (  const T  a, const T  b )  [inline]

Minimum of two values. Returns the smallest value (according to operator <) of two inputs of the same type. The operator < must be defined for this type. Parameters: a  First value. b  Second value. Returns: Minimum of the two values.

floatsample_t NormSample (  const format_t &  format, const void *  sample, const floatsample_t  max )

Returns normalized value of the sample (in internal format). Calculates the value of the sample in internal representation (zero amplitude is 0, maximal amplitude is +max, maximal negative amplitude is -max). Raises Fatal on unknown format. Parameters: format  Sample format description. sample  Input sample. max  Maximal value of linear PCM amplitude. If the value is negative, the resulting amplitude is phase reversed. Returns: Normalized PCM amplitude in the range from -max to +max.

void ReadString (  wxFile &  file, wxString &  str )  [inline]

Read variable-length string from file. Read string from file into memory. First a 64b integer is read, which carries the length of the string. Then the string is allocated and read. Parameters: file  File to read from. str  String to read to.

void ReadTag (  wxFile &  file, char *  str, size_t  size )  [inline]

Read string from file. Read string from file into memory, check for errors (ExceptionIO is thrown on error). Parameters: file  File to read from. str  String to read to. size  Size the string (including trailing zero).

void ReadValue (  wxFile &  file, void *  buf, size_t  size )  [inline]

Read data from file. Read data from file into memory, check for errors (ExceptionIO is thrown on error). Parameters: file  File to read from. buf  Buffer to read to. size  Size of the buffer.

size_t SampleLen (  const format_ex_t &  format  )

Size of one sample (for format_ex_t). Returns the size in bytes of one sample in given format. Raises Fatal on unknown format. Parameters: format  Sample format description. Returns: Size of one sample in bytes, in case of format_ex_t the returned size is not referencing to the number of channels.

size_t SampleLen (  const format_t &  format  )

Size of one sample. Returns the size in bytes of one sample in given format. Raises Fatal on unknown format. Parameters: format  Sample format description. Returns: Size of one sample in bytes, in case of format_ex_t the returned size is not referencing to the number of channels.

void SamplesAverage (  const format_t &  format, const samples_t  samples, const void *  inbuf, const void *  outbuf )

Returns average sample. Calculates the average value of all samples from input buffer. Raises Fatal on unknown format. Parameters: format  Sample format description. samples  Number of samples in inbuf. inbuf  Input buffer. outbuf  Output buffer, which must be preallocated to hold at least one sample in the format described by the first parameter.

floatsample_t SamplesAverageNorm (  const format_t &  format, const samples_t  samples, const void *  inbuf, const floatsample_t  max )

Returns average sample in normalized internal format. Calculates the average value of all samples from input buffer. Raises Fatal on unknown format. Parameters: format  Sample format description. samples  Number of samples in inbuf. inbuf  Input buffer. max  Maximal value of linear PCM amplitude. If the value is negative, the resulting amplitude is phase reversed. Returns: Returns average sample in normalized format.

samples_t SamplesCmp (  const format_t &  infmt, const format_t &  outfmt, const samples_t  samples )

Converts number of samples from one format to another. Converts the number of samples in one sample format to the number of samples that would be needed after conversion to another sample format. The calculation is based on encoding, bit encoding, sample width and sample rate. The returned value is consistent with the output buffer requirements of SampleConv (both local and global conversion). Raises Fatal on unknown format. Parameters: infmt  Input format description. outfmt  Output format description. samples  Number of samples in input format. Returns: Number of samples in output format.

samples_t SamplesCmpIn (  const format_t &  infmt, const format_t &  outfmt, const samples_t  insamples )

Converts number of samples from one format to another (reverse conversion). Converts the number of samples in one sample format to the number of samples that would be needed after conversion to another sample format. The calculation is based on encoding, bit encoding, sample width and sample rate. The returned value is consistent with the output buffer requirements of SampleConv (both local and global conversion). Raises Fatal on unknown format. Parameters: infmt  Input format description. outfmt  Output format description. insamples  Number of samples in output format. Returns: Number of samples in input format.

samples_t SamplesConv (  const format_t &  infmt, const format_ex_t &  outfmt, const samples_t  samples, void *  inbuf, void *  outbuf )

Local coversion between various formats. Converts audio data between given formats. The conversion is done using the nearest neibourghood algorithm w/o antialiasing, which makes it suitable for both global and local (partial) conversion. The conversion is based on encoding, bit encoding, sample width and sample rate. The function can also duplicate the output data to multiple output channels if needed. Sample rate is converted always in the more precise format of both input and output. Channel multiplication is done always as the final step. Raises Fatal on unknown format. Parameters: infmt  Input format description. outfmt  Output format description. samples  Number of input samples. inbuf  Input buffer. outbuf  Output buffer, must be preallocated to hold at least the size of samples returned by SamplesCmp. Returns: Returns the number of output samples.

void SamplesMax (  const format_t &  format, const samples_t  samples, const void *  inbuf, const void *  outbuf )

Returns maximal sample. Calculates the maximal value of all samples from input buffer. Raises Fatal on unknown format. Parameters: format  Sample format description. samples  Number of samples in inbuf. inbuf  Input buffer. outbuf  Output buffer, which must be preallocated to hold at least one sample in the format described by the first parameter.

floatsample_t SamplesMaxNorm (  const format_t &  format, const samples_t  samples, const void *  inbuf, const floatsample_t  max )

Returns normalized value of the sample (in internal format). Calculates the value of the sample in internal representation (zero amplitude is 0, maximal amplitude is +max, maximal negative amplitude is -max). Raises Fatal on unknown format. Parameters: format  Sample format description. samples  Number of samples in inbuf. inbuf  Input buffer. max  Maximal value of linear PCM amplitude. If the value is negative, the resulting amplitude is phase reversed. Returns: Normalized PCM amplitude in the range from -max to +max.

void Seek (  wxFile &  file, off_t  offset )  [inline]

Seek in file. Seek to a given position in file (from the beginning). ExceptionIO is thrown on error. Parameters: file  File to seek in. offset  Offset to seek to.

wxString SetFilename (  const wxString  path, const wxString  name, const wxString  ext, const wxString  fsuffix )

Construct filename from components. Constructs filename with path (in standard wxWidgets representation). Extension and path is chopped from the name of the file (second parameter), the new path is prepended at the beginning and the new suffix and extension is appended. Parameters: path  New filename path (absolute or relative). name  Original filename (path and extension is chopped). ext  New filename extension. fsuffix  Filename suffix (placed between the bare name and new extension). Returns: Constructed filename.

void WriteString (  wxFile &  file, const char *  str )  [inline]

Write variable-length string to file. Write string from memory to file. First a 64b integer with the length of the string is written, then the string characters. Parameters: file  File to read from. str  String to read to.

void WriteTag (  wxFile &  file, const char *  str )  [inline]

Write string to file. Write string from memory to file, check for errors (ExceptionIO is thrown on error). Parameters: file  File to write to. str  String to write.

void WriteValue (  wxFile &  file, const void *  buf, const size_t  size )  [inline]

Write data to file. Write data from memory to file, check for errors (ExceptionIO is thrown on error). Parameters: file  File to write to. buf  Buffer to write from. size  Size of the buffer.

---

Variable Documentation

const version_t fmfile_version_major

Major version number in project file header.

const version_t fmfile_version_minor

Minor version number in project file header.

const sample_pcm16s_t sample_pcm16s_0

const sample_pcm16s_t sample_pcm16s_max

const sample_pcm16s_t sample_pcm16s_min

const sample_pcm16u_t sample_pcm16u_0

const sample_pcm16u_t sample_pcm16u_max

const sample_pcm16u_t sample_pcm16u_min

const sample_pcm8s_t sample_pcm8s_0

const sample_pcm8s_t sample_pcm8s_max

const sample_pcm8s_t sample_pcm8s_min

const sample_pcm8u_t sample_pcm8u_0

const sample_pcm8u_t sample_pcm8u_max

const sample_pcm8u_t sample_pcm8u_min

Sample precision constants.

const volume_t volume_max

Maximal channel volume.

const volume_t volume_min

Minimal channel volume.

---