objc2_avf_audio/generated/

AVAudioConverter.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
use objc2::__framework_prelude::*;
use objc2_foundation::*;

use crate::*;

/// values for the primeMethod property. See further discussion under AVAudioConverterPrimeInfo.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/avfaudio/avaudioconverterprimemethod?language=objc)
// NS_ENUM
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct AVAudioConverterPrimeMethod(pub NSInteger);
impl AVAudioConverterPrimeMethod {
    /// Primes with leading + trailing input frames.
    #[doc(alias = "AVAudioConverterPrimeMethod_Pre")]
    pub const Pre: Self = Self(0);
    /// Only primes with trailing (zero latency). Leading frames are assumed to be silence.
    #[doc(alias = "AVAudioConverterPrimeMethod_Normal")]
    pub const Normal: Self = Self(1);
    /// Acts in "latency" mode. Both leading and trailing frames assumed to be silence.
    #[doc(alias = "AVAudioConverterPrimeMethod_None")]
    pub const None: Self = Self(2);
}

unsafe impl Encode for AVAudioConverterPrimeMethod {
    const ENCODING: Encoding = NSInteger::ENCODING;
}

unsafe impl RefEncode for AVAudioConverterPrimeMethod {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

/// This struct is the value of the primeInfo property and specifies priming information.
///
/// When using convertToBuffer:error:withInputFromBlock: (either a single call or a series of calls), some
/// conversions, particularly involving sample-rate conversion, ideally require a certain
/// number of input frames previous to the normal start input frame and beyond the end of
/// the last expected input frame in order to yield high-quality results.
///
/// These are expressed in the leadingFrames and trailingFrames members of the structure.
///
/// The very first call to convertToBuffer:error:withInputFromBlock:, or first call after
/// reset, will request additional input frames beyond those normally
/// expected in the input proc callback to fulfill this first AudioConverterFillComplexBuffer()
/// request. The number of additional frames requested, depending on the prime method, will
/// be approximately:
///
/// Prime method                        | Additional frames
/// ------------------------------------|----------------------
/// AVAudioConverterPrimeMethod_Pre     | leadingFrames + trailingFrames
/// AVAudioConverterPrimeMethod_Normal  | trailingFrames
/// AVAudioConverterPrimeMethod_None    | 0
///
/// Thus, in effect, the first input proc callback(s) may provide not only the leading
/// frames, but also may "read ahead" by an additional number of trailing frames depending
/// on the prime method.
///
/// AVAudioConverterPrimeMethod_None is useful in a real-time application processing live input,
/// in which case trailingFrames (relative to input sample rate) of through latency will be
/// seen at the beginning of the output of the AudioConverter.  In other real-time
/// applications such as DAW systems, it may be possible to provide these initial extra
/// audio frames since they are stored on disk or in memory somewhere and
/// AVAudioConverterPrimeMethod_Pre may be preferable.  The default method is
/// AVAudioConverterPrimeMethod_Normal, which requires no pre-seeking of the input stream and
/// generates no latency at the output.
///
/// Field: leadingFrames
/// Specifies the number of leading (previous) input frames, relative to the normal/desired
/// start input frame, required by the converter to perform a high quality conversion. If
/// using AVAudioConverterPrimeMethod_Pre, the client should "pre-seek" the input stream provided
/// through the input proc by leadingFrames. If no frames are available previous to the
/// desired input start frame (because, for example, the desired start frame is at the very
/// beginning of available audio), then provide "leadingFrames" worth of initial zero frames
/// in the input proc.  Do not "pre-seek" in the default case of
/// AVAudioConverterPrimeMethod_Normal or when using AVAudioConverterPrimeMethod_None.
///
/// Field: trailingFrames
/// Specifies the number of trailing input frames (past the normal/expected end input frame)
/// required by the converter to perform a high quality conversion.  The client should be
/// prepared to provide this number of additional input frames except when using
/// AVAudioConverterPrimeMethod_None. If no more frames of input are available in the input stream
/// (because, for example, the desired end frame is at the end of an audio file), then zero
/// (silent) trailing frames will be synthesized for the client.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/avfaudio/avaudioconverterprimeinfo?language=objc)
#[cfg(feature = "AVAudioTypes")]
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct AVAudioConverterPrimeInfo {
    pub leadingFrames: AVAudioFrameCount,
    pub trailingFrames: AVAudioFrameCount,
}

#[cfg(feature = "AVAudioTypes")]
unsafe impl Encode for AVAudioConverterPrimeInfo {
    const ENCODING: Encoding = Encoding::Struct(
        "AVAudioConverterPrimeInfo",
        &[<AVAudioFrameCount>::ENCODING, <AVAudioFrameCount>::ENCODING],
    );
}

#[cfg(feature = "AVAudioTypes")]
unsafe impl RefEncode for AVAudioConverterPrimeInfo {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

/// You must return one of these codes from your AVAudioConverterInputBlock.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/avfaudio/avaudioconverterinputstatus?language=objc)
// NS_ENUM
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct AVAudioConverterInputStatus(pub NSInteger);
impl AVAudioConverterInputStatus {
    /// This is the normal case where you supply data to the converter.
    #[doc(alias = "AVAudioConverterInputStatus_HaveData")]
    pub const HaveData: Self = Self(0);
    /// If you are out of data for now, set *ioNumberOfPackets = 0 and return
    /// AVAudioConverterInputStatus_NoDataNow; it is possible that some of the supplied input data
    /// may not be converted to output immediately, but instead may be converted to output only
    /// if/when more input is provided or the end-of-stream is indicated with the
    /// AVAudioConverterInputStatus_EndOfStream status code.
    #[doc(alias = "AVAudioConverterInputStatus_NoDataNow")]
    pub const NoDataNow: Self = Self(1);
    /// If you are at the end of stream, set *ioNumberOfPackets = 0 and return
    /// AVAudioConverterInputStatus_EndOfStream.
    #[doc(alias = "AVAudioConverterInputStatus_EndOfStream")]
    pub const EndOfStream: Self = Self(2);
}

unsafe impl Encode for AVAudioConverterInputStatus {
    const ENCODING: Encoding = NSInteger::ENCODING;
}

unsafe impl RefEncode for AVAudioConverterInputStatus {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

/// These values are returned from convertToBuffer:error:withInputFromBlock:
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/avfaudio/avaudioconverteroutputstatus?language=objc)
// NS_ENUM
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct AVAudioConverterOutputStatus(pub NSInteger);
impl AVAudioConverterOutputStatus {
    /// All of the requested data was returned.
    #[doc(alias = "AVAudioConverterOutputStatus_HaveData")]
    pub const HaveData: Self = Self(0);
    /// Not enough input was available to satisfy the request at the current time. The output buffer
    /// contains as much as could be converted.
    #[doc(alias = "AVAudioConverterOutputStatus_InputRanDry")]
    pub const InputRanDry: Self = Self(1);
    /// The end of stream has been reached. No data was returned.
    #[doc(alias = "AVAudioConverterOutputStatus_EndOfStream")]
    pub const EndOfStream: Self = Self(2);
    /// An error occurred.
    #[doc(alias = "AVAudioConverterOutputStatus_Error")]
    pub const Error: Self = Self(3);
}

unsafe impl Encode for AVAudioConverterOutputStatus {
    const ENCODING: Encoding = NSInteger::ENCODING;
}

unsafe impl RefEncode for AVAudioConverterOutputStatus {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

/// A block which will be called by convertToBuffer:error:withInputFromBlock: to get input data as needed.
///
///
/// Parameter `inNumberOfPackets`: This will be the number of packets required to complete the request. You may supply more or
/// less that this amount. If less, then the input block will get called again.
///
///
/// Parameter `outStatus`: The block must set the appropriate AVAudioConverterInputStatus enum value.
///
/// If you have supplied data, set outStatus to AVAudioConverterInputStatus_HaveData and return
/// an AVAudioBuffer.
///
/// If you are out of data for now, set outStatus to AVAudioConverterInputStatus_NoDataNow and
/// return nil, and the conversion routine will return as much output as could be converted with
/// the input already supplied.
///
/// If you are at the end of stream, set outStatus to AVAudioConverterInputStatus_EndOfStream,
/// and return nil.
///
///
/// Returns: An AVAudioBuffer containing data to be converted, or nil if at end of stream or no data is
/// available. The data in the returned buffer must not be cleared or re-filled until the input
/// block is called again or the conversion has finished.
///
/// convertToBuffer:error:withInputFromBlock: will return as much output as could be converted
/// with the input already supplied.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/avfaudio/avaudioconverterinputblock?language=objc)
#[cfg(all(
    feature = "AVAudioBuffer",
    feature = "AVAudioTypes",
    feature = "block2"
))]
pub type AVAudioConverterInputBlock = *mut block2::DynBlock<
    dyn Fn(AVAudioPacketCount, NonNull<AVAudioConverterInputStatus>) -> *mut AVAudioBuffer,
>;

extern_class!(
    /// Converts streams of audio between various formats.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/avfaudio/avaudioconverter?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct AVAudioConverter;
);

extern_conformance!(
    unsafe impl NSObjectProtocol for AVAudioConverter {}
);

impl AVAudioConverter {
    extern_methods!(
        #[cfg(feature = "AVAudioFormat")]
        /// Initialize from input and output formats.
        ///
        /// Parameter `fromFormat`: The input format.
        ///
        /// Parameter `toFormat`: The output format.
        ///
        /// Returns nil if the format conversion is not possible.
        #[unsafe(method(initFromFormat:toFormat:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initFromFormat_toFormat(
            this: Allocated<Self>,
            from_format: &AVAudioFormat,
            to_format: &AVAudioFormat,
        ) -> Option<Retained<Self>>;

        /// Resets the converter so that a new stream may be converted.
        #[unsafe(method(reset))]
        #[unsafe(method_family = none)]
        pub unsafe fn reset(&self);

        #[cfg(feature = "AVAudioFormat")]
        /// The format of the input audio stream. (NB. AVAudioFormat includes the channel layout)
        #[unsafe(method(inputFormat))]
        #[unsafe(method_family = none)]
        pub unsafe fn inputFormat(&self) -> Retained<AVAudioFormat>;

        #[cfg(feature = "AVAudioFormat")]
        /// The format of the output audio stream. (NB. AVAudioFormat includes the channel layout)
        #[unsafe(method(outputFormat))]
        #[unsafe(method_family = none)]
        pub unsafe fn outputFormat(&self) -> Retained<AVAudioFormat>;

        /// An array of integers indicating from which input to derive each output.
        ///
        /// The array has size equal to the number of output channels. Each element's value is the input
        /// channel number, starting with zero, that is to be copied to that output. A negative value
        /// means that the output channel will have no source and will be silent. Setting a channel map
        /// overrides channel mapping due to any channel layouts in the input and output formats that
        /// may have been supplied.
        #[unsafe(method(channelMap))]
        #[unsafe(method_family = none)]
        pub unsafe fn channelMap(&self) -> Retained<NSArray<NSNumber>>;

        /// Setter for [`channelMap`][Self::channelMap].
        #[unsafe(method(setChannelMap:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setChannelMap(&self, channel_map: &NSArray<NSNumber>);

        /// Decoders require some data in the form of a magicCookie in order to decode properly.
        /// Encoders will produce a magicCookie.
        #[unsafe(method(magicCookie))]
        #[unsafe(method_family = none)]
        pub unsafe fn magicCookie(&self) -> Option<Retained<NSData>>;

        /// Setter for [`magicCookie`][Self::magicCookie].
        #[unsafe(method(setMagicCookie:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setMagicCookie(&self, magic_cookie: Option<&NSData>);

        /// If YES and channel remapping is necessary, then channels will be mixed as
        /// appropriate instead of remapped. Default value is NO.
        #[unsafe(method(downmix))]
        #[unsafe(method_family = none)]
        pub unsafe fn downmix(&self) -> bool;

        /// Setter for [`downmix`][Self::downmix].
        #[unsafe(method(setDownmix:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setDownmix(&self, downmix: bool);

        /// Setting YES will turn on dither, if dither makes sense in given the current formats
        /// and settings. Default value is NO.
        #[unsafe(method(dither))]
        #[unsafe(method_family = none)]
        pub unsafe fn dither(&self) -> bool;

        /// Setter for [`dither`][Self::dither].
        #[unsafe(method(setDither:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setDither(&self, dither: bool);

        /// An AVAudioQuality value as defined in AVAudioSettings.h.
        #[unsafe(method(sampleRateConverterQuality))]
        #[unsafe(method_family = none)]
        pub unsafe fn sampleRateConverterQuality(&self) -> NSInteger;

        /// Setter for [`sampleRateConverterQuality`][Self::sampleRateConverterQuality].
        #[unsafe(method(setSampleRateConverterQuality:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setSampleRateConverterQuality(
            &self,
            sample_rate_converter_quality: NSInteger,
        );

        /// An AVSampleRateConverterAlgorithmKey value as defined in AVAudioSettings.h.
        #[unsafe(method(sampleRateConverterAlgorithm))]
        #[unsafe(method_family = none)]
        pub unsafe fn sampleRateConverterAlgorithm(&self) -> Option<Retained<NSString>>;

        /// Setter for [`sampleRateConverterAlgorithm`][Self::sampleRateConverterAlgorithm].
        #[unsafe(method(setSampleRateConverterAlgorithm:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setSampleRateConverterAlgorithm(
            &self,
            sample_rate_converter_algorithm: Option<&NSString>,
        );

        /// Indicates the priming method to be used by the sample rate converter or decoder.
        #[unsafe(method(primeMethod))]
        #[unsafe(method_family = none)]
        pub unsafe fn primeMethod(&self) -> AVAudioConverterPrimeMethod;

        /// Setter for [`primeMethod`][Self::primeMethod].
        #[unsafe(method(setPrimeMethod:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setPrimeMethod(&self, prime_method: AVAudioConverterPrimeMethod);

        #[cfg(feature = "AVAudioTypes")]
        /// Indicates the the number of priming frames.
        #[unsafe(method(primeInfo))]
        #[unsafe(method_family = none)]
        pub unsafe fn primeInfo(&self) -> AVAudioConverterPrimeInfo;

        #[cfg(feature = "AVAudioTypes")]
        /// Setter for [`primeInfo`][Self::primeInfo].
        #[unsafe(method(setPrimeInfo:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setPrimeInfo(&self, prime_info: AVAudioConverterPrimeInfo);

        #[cfg(feature = "AVAudioBuffer")]
        /// Perform a simple conversion. That is, a conversion which does not involve codecs or sample rate conversion.
        ///
        /// Parameter `inputBuffer`: The input buffer.
        ///
        /// Parameter `outputBuffer`: The output buffer.
        ///
        /// Parameter `outError`: An error if the conversion fails.
        ///
        /// Returns: YES is returned on success, NO when an error has occurred.
        ///
        /// The output buffer's frameCapacity should be at least at large as the inputBuffer's frameLength.
        /// If the conversion involves a codec or sample rate conversion, you instead must use
        /// convertToBuffer:error:withInputFromBlock:.
        #[unsafe(method(convertToBuffer:fromBuffer:error:_))]
        #[unsafe(method_family = none)]
        pub unsafe fn convertToBuffer_fromBuffer_error(
            &self,
            output_buffer: &AVAudioPCMBuffer,
            input_buffer: &AVAudioPCMBuffer,
        ) -> Result<(), Retained<NSError>>;

        #[cfg(all(
            feature = "AVAudioBuffer",
            feature = "AVAudioTypes",
            feature = "block2"
        ))]
        /// Perform any supported conversion.
        ///
        /// Parameter `inputBlock`: A block which will be called to get input data as needed. See description for AVAudioConverterInputBlock.
        ///
        /// Parameter `outputBuffer`: The output buffer.
        ///
        /// Parameter `outError`: An error if the conversion fails.
        ///
        /// Returns: An AVAudioConverterOutputStatus is returned.
        ///
        /// It attempts to fill the buffer to its capacity. On return, the buffer's length indicates the number of
        /// sample frames successfully converted.
        #[unsafe(method(convertToBuffer:error:withInputFromBlock:))]
        #[unsafe(method_family = none)]
        pub unsafe fn convertToBuffer_error_withInputFromBlock(
            &self,
            output_buffer: &AVAudioBuffer,
            out_error: Option<&mut Option<Retained<NSError>>>,
            input_block: AVAudioConverterInputBlock,
        ) -> AVAudioConverterOutputStatus;
    );
}

/// Methods declared on superclass `NSObject`.
impl AVAudioConverter {
    extern_methods!(
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

/// Encoding.
impl AVAudioConverter {
    extern_methods!(
        /// bitRate in bits per second. Only applies when encoding.
        #[unsafe(method(bitRate))]
        #[unsafe(method_family = none)]
        pub unsafe fn bitRate(&self) -> NSInteger;

        /// Setter for [`bitRate`][Self::bitRate].
        #[unsafe(method(setBitRate:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setBitRate(&self, bit_rate: NSInteger);

        /// When encoding, an AVEncoderBitRateStrategyKey value constant as defined in AVAudioSettings.h. Returns nil if not encoding.
        #[unsafe(method(bitRateStrategy))]
        #[unsafe(method_family = none)]
        pub unsafe fn bitRateStrategy(&self) -> Option<Retained<NSString>>;

        /// Setter for [`bitRateStrategy`][Self::bitRateStrategy].
        #[unsafe(method(setBitRateStrategy:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setBitRateStrategy(&self, bit_rate_strategy: Option<&NSString>);

        /// The maximum size of an output packet, in bytes.
        ///
        /// When encoding it is useful to know how large a packet can be in order to allocate a buffer to receive the output.
        #[unsafe(method(maximumOutputPacketSize))]
        #[unsafe(method_family = none)]
        pub unsafe fn maximumOutputPacketSize(&self) -> NSInteger;

        /// When encoding, an NSArray of NSNumber of all bit rates provided by the codec. Returns nil if not encoding.
        #[unsafe(method(availableEncodeBitRates))]
        #[unsafe(method_family = none)]
        pub unsafe fn availableEncodeBitRates(&self) -> Option<Retained<NSArray<NSNumber>>>;

        /// When encoding, an NSArray of NSNumber of bit rates that can be applied based on the current formats and settings. Returns nil if not encoding.
        #[unsafe(method(applicableEncodeBitRates))]
        #[unsafe(method_family = none)]
        pub unsafe fn applicableEncodeBitRates(&self) -> Option<Retained<NSArray<NSNumber>>>;

        /// When encoding, an NSArray of NSNumber of all output sample rates provided by the codec. Returns nil if not encoding.
        #[unsafe(method(availableEncodeSampleRates))]
        #[unsafe(method_family = none)]
        pub unsafe fn availableEncodeSampleRates(&self) -> Option<Retained<NSArray<NSNumber>>>;

        /// When encoding, an NSArray of NSNumber of output sample rates that can be applied based on the current formats and settings. Returns nil if not encoding.
        #[unsafe(method(applicableEncodeSampleRates))]
        #[unsafe(method_family = none)]
        pub unsafe fn applicableEncodeSampleRates(&self) -> Option<Retained<NSArray<NSNumber>>>;

        /// When encoding, an NSArray of NSNumber of all output channel layout tags provided by the codec. Returns nil if not encoding.
        #[unsafe(method(availableEncodeChannelLayoutTags))]
        #[unsafe(method_family = none)]
        pub unsafe fn availableEncodeChannelLayoutTags(
            &self,
        ) -> Option<Retained<NSArray<NSNumber>>>;
    );
}