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.
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
};
This method calculates the minimum output buffer size that is needed when filtering.
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.
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.
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.
| inout long bps | Returns the bits-per-sample value of the output data stream. |
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.
| inout long chan | The number of channels value for the output data stream. |
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.
| inout long sps | Returns the samples-per-second value of the output data stream. |
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.
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.
| in long bps | Specifies the bits-per-sample value. |
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.
| in long chan | Specifies the number of channels. |
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.
| in long sps | Specifies the samples-per-second value. |
Subclasses of filter objects inheriting the UMSFilter object methods include the following.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
| in UMSFilter f | This is the filter to be added to the end of the list. |
This method returns the number of filters that have been added.
| out long number | The number of filters within the chain filter is returned. |
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:
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.
| 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. |
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.