[ Previous | Next | Contents | Glossary | Home | Search ]
Ultimedia Services Version 2 for AIX: Programmer's Guide and Reference

UMSFilter Object

The UMSFilter object is a parent class defining the methods for the family of filters. The UMSFilter object should not be instantiated; it only exists for inheritance.

To learn more about audio filter objects, see:

For introductory information, see Audio Filter Objects.

Enumeration Lists

To avoid name collision on defines, integer values have been captured as enumerated lists. The set of valid values from an enumerated list can vary with the application. The detailed method descriptions describe the valid or possible values for the specific use. The enumerated lists that are defined for this object are:

enum FilterReturnCode {
   Success,
   Failure,
   InvalidArgument,
   StorageAllocationFailure
   };

Method Descriptions

ReturnCode calculate_output_size(in long input_size, out long output_size)

Description

This method calculates the minimum output buffer size that is needed when filtering.

Arguments
in long input_size This is size in bytes of the input buffer that is passed to the filter_block method.
out long output_size This is a return value that gives the minimum size in bytes of the output buffer that is passed to the filter_block method.
Return Values

Success

Failure

InvalidArgument

ReturnCode filter(in sequence<octet> input_data, inout sequence<octet> output_data)

Description

This is the preferred method for filtering. The filter method is similar but uses a sequence of octets as parameters rather than using pointer parameters. (An octet is a byte of data.) This enables future use of the object in a distributed environment. A sequence of octets is a structure with the following members:

unsigned long _maximum
unsigned long _length
octet * _buffer

Where _maximum specifies the maximum space that has been allocated for the data, _length specifies the actual length of the data, and _buffer is a pointer to the data.

This method should be called as needed to filter the data. The filtering can be done as one call to this method or as several calls to this method. Other than the minimum output buffer size calculated with calculate_output_size, there are no block size requirements.

Arguments
in sequence<octet> input_data The input data defines the length of the input data in the _length member of the input_data sequence and provides a pointer to the data to be filtered in the _buffer member of the input_data sequence.
inout sequence<octet> output_data The output data defines the length of the output data in the _length member of the output_data sequence and provides a pointer to the filtered output data in the _buffer member of the output_data sequence. The output_data buffer must be allocated by the caller of the method and the available size should be specified in the _maximum member of the output_data sequence.
Return Values

Success

Failure

InvalidArgument

StorageAllocationFailure

ReturnCode filter_block(in void *input_data, in long input_size, in void *output_data, inout long *output_size)

Description

This method should be called as needed to filter the data. The filtering can be done as one call to this method or as several calls to this method. Other than the minimum output buffer size, calculated with calculate_output_size, there are no block size requirements.

Note: The filter method should be used instead of filter_block for all new applications. The filter method is similar but uses sequence parameters rather than pointer parameters to enable future use of the object in a distributed environment.
Arguments
in void *input_data This is a pointer to the input buffer.
in long input_size This is the size in bytes of the input buffer.
in void *output_data This is a pointer to the output buffer.
inout long *output_size Before the call, this is the real size in bytes of the output buffer. After the call, this is the size in bytes of the data in the buffer.
Return Values

Success

Failure

InvalidArgument

StorageAllocationFailure

ReturnCode get_output_bits_per_sample(inout long bps)

Description

Returns the bits-per-sample value of the output data stream. In general, this requires that the filter has been informed of the characteristics of the input data stream.

Arguments
inout long bps Returns the bits-per-sample value of the output data stream.
Return Values

Success

Failure

ReturnCode get_output_number_of_channels(inout long chan)

Description

Returns the number of channels value for the output data stream. In general, this requires that the filter has been informed of the characteristics of the input data stream.

Arguments
inout long chan The number of channels value for the output data stream.
Return Values

Success

Failure

ReturnCode get_output_samples_per_second(inout long sps)

Description

Returns the samples-per-second value of the output data stream. In general, this requires that the filter has been informed of the characteristics of the input data stream.

Arguments
inout long sps Returns the samples-per-second value of the output data stream.
Return Values

Success

Failure

ReturnCode reset()

Description

Some of the filters have state information (the last N input values) that need to be set to 0 occasionally. This method sets this state information to initial values (0). This method should be called, for example, when several independent sections of audio are being filtered with the same object. After the first section has been passed through the filter, a call to reset initializes the object as if it has just been created.

Return Values

Success

Failure

ReturnCode set_input_bits_per_sample(in long bps)

Description

Specifies the bits-per-sample of the input data stream. In general, filter objects should be informed of the characteristics of their input data stream.

Arguments
in long bps Specifies the bits-per-sample value.
Return Values

Success

Failure

InvalidArgument

ReturnCode set_input_number_of_channels(in long chan)

Description

Specifies the number of channels for the input data stream. In general, filter objects should be informed of the characteristics of their input data stream.

Arguments
in long chan Specifies the number of channels.
Return Values

Success

Failure

InvalidArgument

ReturnCode set_input_samples_per_second(in long sps)

Description

Specifies the samples-per-second value of the input data stream. In general, filter objects should be informed of the characteristics of their input data stream.

Arguments
in long sps Specifies the samples-per-second value.
Return Values

Success

Failure

InvalidArgument

Subclasses of UMSFilter Object

Subclasses of filter objects inheriting the UMSFilter object methods include the following.

UMSADPCMtoPCM16 Object

This object converts audio from ADPCM format to PCM16 format. ADPCM is the IMA-defined version of 4 bits-per-sample adaptive differential pulse code modulation (ADPCM). PCM16 is 16 bits-per-sample pulse code modulation (PCM), twos complement, MSB first. The conversion does not depend on the sample rate.

The reset method resets the ADPCM predictor and step size.

UMSPCM16toADPCM Object

This object converts audio from PCM16 format to ADPCM format. ADPCM is the IMA-defined version of 4 bits-per-sample ADPCM. PCM16 is 16 bits-per-sample PCM, twos complement, MSB first. The conversion does not depend on the sample rate.

The reset method resets the ADPCM predictor and step size and throws away a saved byte of a sample, if any. A byte can be saved if the last byte of an input block has the first byte of a 2-byte sample.

UMSALAWtoPCM16 Object

This object converts audio from ALAW format to PCM16 format. ALAW is the International Telegraph and Telephone Consultative Committee (CCITT) G.711 A-law audio adopted by the IMA. PCM16 is 16 bits-per-sample PCM, twos complement, MSB first. The conversion does not depend on the sample rate.

UMSPCM16toALAW Object

This object converts audio from PCM16 format to ALAW format. ALAW is the CCITT G.711 A-law audio adopted by the IMA. PCM16 is 16 bits-per-sample PCM, twos complement, MSB first. The conversion does not depend on the sample rate.

The reset method throws away any saved byte of a sample. A byte can be saved if the last byte of an input block has the first byte of a 2-byte sample.

UMSMULAWtoPCM16 Object

This object converts audio from MULAW format to PCM16 format. MULAW is the CCITT G.711 mu-law audio adopted by the IMA. PCM16 is 16 bits-per-sample PCM, twos complement, MSB first. The conversion does not depend on the sample rate.

UMSPCM16toMULAW Object

This object converts audio from PCM16 format to MULAW format. MULAW is the CCITT G.711 mu-law audio adopted by the IMA. PCM16 is 16 bits-per-sample PCM, twos complement, MSB first. The conversion does not depend on the sample rate.

The reset method throws away a saved byte of a sample, if any. A byte can be saved if the last byte of an input block has the first byte of a 2-byte sample.

UMSPCM8toPCM16 Object

This object converts audio from PCM8 format to PCM16 format. PCM8 is 8 bits-per-sample unsigned PCM. PCM16 is 16 bits-per-sample PCM, twos complement, MSB first. The conversion does not depend on the sample rate.

UMSPCM16toPCM8 Object

This object converts audio from PCM16 format to PCM8 format. PCM8 is 8 bits-per-sample unsigned Pulse Code Modulation. PCM16 is 16 bits-per-sample PCM, twos complement, MSB first. The conversion does not depend on the sample rate.

The reset method throws away a saved byte of a sample, if any. A byte can be saved if the last byte of an input block has the first byte of a 2-byte sample.

UMSByteOrder Object

This object converts PCM16 MSB to and from PCM16 LSB. PCM16 is 16 bits-per-sample PCM, twos complement. The conversion does not depend on the sample rate.

The reset method throws away a saved byte of a sample, if any. A byte can be saved if the last byte of an input block has the first byte of a 2-byte sample.

UMSChainFilter Object

This object accepts several filters and passes the output data from one as the input data to the next. The filters are called in the order that they are added using add_next_filter. The reset method inherited from the UMSFilter object calls the reset methods of all the filters in the list. The filters in the list are deleted (freed) cleanly when the UMSChainFilter object is deleted (freed). The caller should not try to use the filters after the chain filter is deleted. The caller does not need to delete (free) the filters after calling this method.

The reset method calls the reset methods of all the filters in the list. The UMSChainFilter object adds the add_next_filter method and the get_number_of_added_filters method:

ReturnCode add_next_filter(in UMSFilter f);

Description

This method adds a new filter to the end of the list of filters. The filters in the list are deleted (freed) cleanly when the UMSChainFilter object is deleted (freed). The caller should not try to use the filters after the chain filter is deleted. The caller does not need to delete (free) the filters after calling this method.

Arguments
in UMSFilter f This is the filter to be added to the end of the list.
Return Values

Success

Failure

InvalidArgument

StorageAllocationFailure

ReturnCode get_number_of_added_filters(out long number)

Description

This method returns the number of filters that have been added.

Arguments
out long number The number of filters within the chain filter is returned.
Return Values

Success

Failure

UMSSamplingRate Object

This object changes the sampling rate for PCM16 audio data. PCM16 is 16 bits-per-sample PCM, twos complement, MSB first. This object uses low-quality linear interpolation to do the conversion.

The reset method realigns the input and output samples so that the time of the first input sample is the same as the time of the first output sample. The reset method throws away a saved byte of a sample, if any. A byte can be saved if the last byte of an input block has the first byte of a 2-byte sample.

The UMSSamplingRate object adds the FilterReturnCode set_input_output_rates method:

ReturnCode set_input_output_rates(in long input_rate, in long output_rate)

Description

This method causes the converter to be initialized for use. The filter_block method inherited from the UMSFilter object returns a Failure error if this method is not called successfully. The calculate_output_size method inherited from the UMSFilter object returns a Failure error if this method is not called successfully.

Arguments
in long input_rate This is the input sampling rate in hertz (Hz).
in long output_rate This is the output sampling rate in Hz.
Return Values

Success

Failure

InvalidArgument

UMSMonoToStereo Object

This object duplicates a mono data stream to create a stereo stream. The conversion does not depend on the sample rate or the input format. The output format and sample rate are unmodified.

For introductory information, see Audio Filter Objects.


[ Previous | Next | Contents | Glossary | Home | Search ]