This class manages a lossy compression and decompression of a stream of floating-point numbers to a datagram, based a fourier transform algorithm (similar in principle to JPEG compression). More...

#include "fftCompressor.h"

Public Member Functions
	FFTCompressor ()
	Constructs a new compressor object with default parameters.
int	get_quality () const
	Returns the quality number that was previously set via set_quality().
bool	get_transpose_quats () const
	Returns the transpose_quats flag.
bool	get_use_error_threshold () const
	Returns whether the error threshold measurement is enabled.
bool	read_header (DatagramIterator &di, int bam_minor_version)
	Reads the compression header that was written previously.
bool	read_hprs (DatagramIterator &di, pvector< LVecBase3 > &array, bool new_hpr)
	Reads an array of HPR angles.
bool	read_hprs (DatagramIterator &di, pvector< LVecBase3 > &array)
	Reads an array of HPR angles.
bool	read_reals (DatagramIterator &di, vector_stdfloat &array)
	Reads an array of floating-point numbers.
void	set_quality (int quality)
	Sets the quality factor for the compression.
void	set_transpose_quats (bool flag)
	Sets the transpose_quats flag.
void	set_use_error_threshold (bool use_error_threshold)
	Enables or disables the use of the error threshold measurement to put a cap on the amount of damage done by lossy compression.
void	write_header (Datagram &datagram)
	Writes the compression parameters to the indicated datagram.
void	write_hprs (Datagram &datagram, const LVecBase3 *array, int length)
	Writes an array of HPR angles to the indicated datagram.
void	write_reals (Datagram &datagram, const PN_stdfloat *array, int length)
	Writes an array of floating-point numbers to the indicated datagram.
Static Public Member Functions
static void	free_storage ()
	Frees memory that has been allocated during past runs of the FFTCompressor.
static bool	is_compression_available ()
	Returns true if the FFTW library is compiled in, so that this class is actually capable of doing useful compression/decompression work.

Detailed Description

This class manages a lossy compression and decompression of a stream of floating-point numbers to a datagram, based a fourier transform algorithm (similar in principle to JPEG compression).

Actually, it doesn't do any real compression on its own; it just outputs a stream of integers that should compress much tighter via gzip than the original stream of floats would have.

This class depends on the external FFTW library; without it, it will fall back on lossless output of the original data.

Definition at line 45 of file fftCompressor.h.

Constructor & Destructor Documentation

FFTCompressor::FFTCompressor ( )

Constructs a new compressor object with default parameters.

Definition at line 59 of file fftCompressor.cxx.

References set_quality().

Member Function Documentation

void FFTCompressor::free_storage ( ) [static]

Frees memory that has been allocated during past runs of the FFTCompressor.

This is an optional call, but it may be made from time to time to empty the global cache that the compressor objects keep to facilitate fast compression/decompression.

Definition at line 837 of file fftCompressor.cxx.

int FFTCompressor::get_quality ( ) const

Returns the quality number that was previously set via set_quality().

Definition at line 172 of file fftCompressor.cxx.

bool FFTCompressor::get_transpose_quats ( ) const

Returns the transpose_quats flag.

See set_transpose_quats().

Definition at line 224 of file fftCompressor.cxx.

bool FFTCompressor::get_use_error_threshold ( ) const

Returns whether the error threshold measurement is enabled.

See set_use_error_threshold().

Definition at line 200 of file fftCompressor.cxx.

bool FFTCompressor::is_compression_available ( ) [static]

Returns true if the FFTW library is compiled in, so that this class is actually capable of doing useful compression/decompression work.

Returns false otherwise, in which case any attempt to write a compressed stream will actually write an uncompressed stream, and any attempt to read a compressed stream will fail.

Definition at line 78 of file fftCompressor.cxx.

Referenced by EggJointData::score_reparent_to(), AnimChannelScalarTable::write_datagram(), and AnimChannelMatrixXfmTable::write_datagram().

bool FFTCompressor::read_header	(	DatagramIterator &	di,
		int	bam_minor_version
	)

Reads the compression header that was written previously.

This fills in the compression parameters necessary to correctly decompress the following data.

Returns true if the header is read successfully, false otherwise.

Definition at line 566 of file fftCompressor.cxx.

References DatagramIterator::get_float64(), DatagramIterator::get_int8(), and set_quality().

Referenced by AnimChannelScalarTable::fillin(), and AnimChannelMatrixXfmTable::fillin().

bool FFTCompressor::read_hprs	(	DatagramIterator &	di,
		pvector< LVecBase3 > &	array,
		bool	new_hpr
	)

Reads an array of HPR angles.

The result is pushed onto the end of the indicated vector, which is not cleared first; it is the user's responsibility to ensure that the array is initially empty.

new_hpr is a temporary, transitional parameter. If it is set false, the hprs are decompressed according to the old, broken hpr calculation; if true, the hprs are decompressed according to the new, correct hpr calculation. See temp_hpr_fix.

Definition at line 692 of file fftCompressor.cxx.

References LQuaternionf::extract_to_matrix(), LQuaternionf::normalize(), and read_reals().

Referenced by AnimChannelMatrixXfmTable::fillin(), and read_hprs().

bool FFTCompressor::read_hprs	(	DatagramIterator &	di,
		pvector< LVecBase3 > &	array
	)

Reads an array of HPR angles.

The result is pushed onto the end of the indicated vector, which is not cleared first; it is the user's responsibility to ensure that the array is initially empty.

Definition at line 822 of file fftCompressor.cxx.

References read_hprs().

bool FFTCompressor::read_reals	(	DatagramIterator &	di,
		vector_stdfloat &	array
	)

Reads an array of floating-point numbers.

The result is pushed onto the end of the indicated vector, which is not cleared first; it is the user's responsibility to ensure that the array is initially empty. Returns true if the data is read correctly, false if there is an error.

Definition at line 605 of file fftCompressor.cxx.

References DatagramIterator::get_bool(), DatagramIterator::get_int32(), and DatagramIterator::get_stdfloat().

Referenced by AnimChannelScalarTable::fillin(), AnimChannelMatrixXfmTable::fillin(), and read_hprs().

void FFTCompressor::set_quality ( int quality )

Sets the quality factor for the compression.

This is an integer in the range 0 - 100 that roughly controls how aggressively the reals are compressed; lower numbers mean smaller output, and more data loss.

There are a few special cases. Quality -1 means to use whatever individual parameters are set in the user's Configrc file, rather than the single quality dial. Quality 101 or higher means to generate lossless output (this is the default if libfftw is not available).

Quality 102 writes all four components of quaternions to the output file, rather than just three, quality 103 converts hpr to matrix (instead of quat) and writes a 9-component matrix, and quality 104 just writes out hpr directly. Quality levels 102 and greater are strictly for debugging purposes, and are only available if NDEBUG is not defined.

Definition at line 110 of file fftCompressor.cxx.

Referenced by FFTCompressor(), read_header(), AnimChannelScalarTable::write_datagram(), and AnimChannelMatrixXfmTable::write_datagram().

void FFTCompressor::set_transpose_quats ( bool flag )

Sets the transpose_quats flag.

This is provided mainly for backward compatibility with old bam files that were written out with the quaternions inadvertently transposed.

Definition at line 213 of file fftCompressor.cxx.

void FFTCompressor::set_use_error_threshold ( bool use_error_threshold )

Enables or disables the use of the error threshold measurement to put a cap on the amount of damage done by lossy compression.

When this is enabled, the potential results of the compression are analyzed before the data is written; if it is determined that the compression will damage a particular string of reals too much, that particular string of reals is written uncompressed.

Definition at line 189 of file fftCompressor.cxx.

Referenced by AnimChannelScalarTable::write_datagram(), and AnimChannelMatrixXfmTable::write_datagram().

void FFTCompressor::write_header ( Datagram & datagram )

Writes the compression parameters to the indicated datagram.

It is necessary to call this before writing anything else to the datagram, since these parameters will be necessary to correctly decompress the data later.

Definition at line 238 of file fftCompressor.cxx.

References Datagram::add_float64(), and Datagram::add_int8().

Referenced by AnimChannelScalarTable::write_datagram(), and AnimChannelMatrixXfmTable::write_datagram().