diff options
Diffstat (limited to 'libs/appleutility/CoreAudio/PublicUtility/CAAUProcessor.h')
| -rw-r--r-- | libs/appleutility/CoreAudio/PublicUtility/CAAUProcessor.h | 120 |
1 files changed, 60 insertions, 60 deletions
diff --git a/libs/appleutility/CoreAudio/PublicUtility/CAAUProcessor.h b/libs/appleutility/CoreAudio/PublicUtility/CAAUProcessor.h index f0fb34574d..c8c02bed91 100644 --- a/libs/appleutility/CoreAudio/PublicUtility/CAAUProcessor.h +++ b/libs/appleutility/CoreAudio/PublicUtility/CAAUProcessor.h @@ -2,14 +2,14 @@ File: CAAUProcessor.h Abstract: Part of CoreAudio Utility Classes Version: 1.1 - + Disclaimer: IMPORTANT: This Apple software is supplied to you by Apple Inc. ("Apple") in consideration of your agreement to the following terms, and your use, installation, modification or redistribution of this Apple software constitutes acceptance of these terms. If you do not agree with these terms, please do not use, install, modify or redistribute this Apple software. - + In consideration of your agreement to abide by the following terms, and subject to these terms, Apple grants you a personal, non-exclusive license, under Apple's copyrights in this original Apple software (the @@ -25,13 +25,13 @@ implied, are granted by Apple herein, including but not limited to any patent rights that may be infringed by your derivative works or by other works in which the Apple Software may be incorporated. - + The Apple Software is provided by Apple on an "AS IS" basis. APPLE MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN COMBINATION WITH YOUR PRODUCTS. - + IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS @@ -40,9 +40,9 @@ AND WHETHER UNDER THEORY OF CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - + Copyright (C) 2014 Apple Inc. All Rights Reserved. - + */ #ifndef __CAAUProcessor_h__ #define __CAAUProcessor_h__ @@ -60,76 +60,76 @@ It can be used in a RealTime context (rendering data with RT constraints) or in an OffLine context such as using an AU to process data that is stored in a file, and on which there are no RT constraints to be imposed. - + Order of operations: Create an instance Establish an Input Callback Initialize the AU to the audio formats and whether it is going to process in an offline or RT context Preflight - + while (...) Render // based on your calling context - + PostProcess if needed (only in OL case) - + After any initialization, preflighting is required. - + Parameter Values on the AU should be set just before each call to Render. The sampleFrameOffsets supplied when setting those values are an offset into that next render buffer's numFrames. - + RT vs OT is determined by whether the inputSampleCount is set during Initialization, thus this class can move the AU between RT and OL contexts. If you are using an AU of type 'auol' (Offline), then it cannot be used in a RT context. The CAAUProcessor will only call your Input Callback for input when it needs valid input. This input callback will contain a sample time that indicates where within your input - you should read data from, where after preflighting, the first output data produces is for + you should read data from, where after preflighting, the first output data produces is for the output sample count of zero. - + MaxFrames should be set before initialisation (or is also passed in to the Reinitialize API) - + If RT, then PostProcessing will *never* be required, nor will Render ever return an isDone value If OL, then Render will at some point return isDone==true, and then also indicate if PostProcessing is required - + If using a Format Converter AU in offline context, then the only way for it to determine that you've finished is for the Input callback to return an error. This means ultimately, that you'll have potentially longer output - than you should have. The only way to manage this is for the caller to know the relationship between + than you should have. The only way to manage this is for the caller to know the relationship between input to output samples that will be required, and to call Render for just that amount of output samples then return an error, so the tail and latency can be processed. - + Tail and Latency are *only* calculated at initialisation.. Some AU's may change these properties based on either different presets or parameter settings... Ideally, this class should listen to those properties and recalculate its values based on those changes. -*/ - +*/ + class CAAUProcessor { public: // by default this is set to process offline CAAUProcessor (const CAComponent& inComp); ~CAAUProcessor (); - + CAAudioUnit& AU() { return mUnit; } const CAAudioUnit& AU() const { return mUnit; } - -#pragma mark __Setup APIs + +#pragma mark __Setup APIs bool IsOfflineContext () const { return mNumInputSamples != 0; } - - // this contains the callback and client data that the AU + + // this contains the callback and client data that the AU // uses to call when it needs input OSStatus EstablishInputCallback (AURenderCallbackStruct &inInputCallback); - + OSStatus SetAUPreset (CFPropertyListRef inPreset); OSStatus SetAUPresetIndex (SInt32 inPresetIndex); - + OSStatus SetParameter (AudioUnitParameterID inID, AudioUnitScope scope, AudioUnitElement element, Float32 value, UInt32 bufferOffsetFrames = 0); - + // a result of zero here signifies an error UInt32 MaxFramesPerRender () const; - + // this call can return an error if the AU is initialized - see Reinitialize OSStatus SetMaxFramesPerRender (UInt32 inMaxFrames); - + // Prepares the AU for processing at the specified format // only doing n-n channel processing here.. could extend this for n-m channel processing easily enough // if you are processing using an Offline AU, you HAVE to specify the numInputSamples to process @@ -138,15 +138,15 @@ public: { return Initialize (inIODesc, inIODesc, inNumInputSamples); } - OSStatus Initialize (const CAStreamBasicDescription &inInputDesc, - const CAStreamBasicDescription &inOutputDesc, + OSStatus Initialize (const CAStreamBasicDescription &inInputDesc, + const CAStreamBasicDescription &inOutputDesc, UInt64 inNumInputSamples = 0); - + // takes the existing format state of the AU, but resets the AUProcessor so that: // applies an optional new number of max frames // the AUProcessor will have to be Preflighted again after this call // Use this when you want to keep the same formats, same input sample count, - // but want to re-initialize the AU to use a new num max frames and prepare it + // but want to re-initialize the AU to use a new num max frames and prepare it // appropriately... OSStatus Reinitialize (UInt32 inNewMaxFrames); @@ -155,18 +155,18 @@ public: #pragma mark __Render APIs // Preflighting - you HAVE to preflight // returns noErr when preflighting is done - + // Offline Context: // Offline AU's require preflighting, even if they will end up doing no work. - // In the case where the AU is offline the latency samples are trimmed and not returned + // In the case where the AU is offline the latency samples are trimmed and not returned // from the consequent Render calls - - // If you are NOT an offline AU then the first time Render is called, + + // If you are NOT an offline AU then the first time Render is called, // there will need to be some consumption of the input before you will get any valid output data. // This is determined by the value of the AU's reported latency. So, in this case preflight // will consume those initial samples and then return. // Your InputCallback MUST provide the initial data that is to be processed. - + // RealTime Context: // (1 No priming. In this case inProcessPreceedingTail is false (the default) and no // processing is done on the AU. However, because preflight is the first time that Rendering @@ -185,12 +185,12 @@ public: // and you'll need to read up to the numSamples of tail time of the preceeding data. // It discards the output results of the preflighting. If you don't have any previous data // with which to prepare the AU, then you do NOT need to take this path and can do the step below. - + // In both of these cases the inital latency frames are *not* trimmed from // the output that will be generated by a consequent call to render. OSStatus Preflight (bool inProcessPreceedingTail = false); - // this can be used with an OfflineAU to do a gradual preflight (so you could for instance, + // this can be used with an OfflineAU to do a gradual preflight (so you could for instance, // present a progress indicator. The Preflight call will do it all at once. // If you break out of the preflight before you are done, then you HAVE to reinitialise the AU // before you can either do another preflight or do a render, otherwise the Render call will produce @@ -199,45 +199,45 @@ public: // Here's the major stage that produces output. // You pass in two bool flags and an ioNumFrames.... - + // So ioNumFrames will be *untouched* if outOLCompleted == false // if outOLCompleted is true, ioNumFrames contains the number of valid frames within the ioData data that are valid data // (ioData's pointers and sizes will also have been resized to match these number of frames) - // outOLRequiresPostProcess should also be checked when outOLCompleted is true, + // outOLRequiresPostProcess should also be checked when outOLCompleted is true, // to see if any post-processing is required // if rendering in a RT context, then neither outOLCompleted or outOLRequiresPostProcess is required // if rendering in an OL context, both must be specified. // Caller MUST provide an ABL that is set up in the previously specified output format - + // If you receive kAudioUnitErr_InvalidOfflineRender when dealing with an OfflineAU Type, then you have either not // preflighted it (and the AU requires it) or you have changed some state (its num input samples, its start offest) // and it needs to be re-preflighted. In that case, preflight the AU again first. - OSStatus Render (AudioBufferList *ioData, - UInt32 &ioNumFrames, + OSStatus Render (AudioBufferList *ioData, + UInt32 &ioNumFrames, bool &outIsSilence, - bool *outOLCompleted = NULL, + bool *outOLCompleted = NULL, bool *outOLRequiresPostProcess = NULL); - + // call this method if outOLRequiresPostProcess returned true upon rendering completion OSStatus PostProcess (AudioBufferList *ioData, UInt32 &ioNumFrames, bool &outIsSilence, bool &outDone); - + // This method returns how many input samples will need to be provided before // valid output data is produced. UInt32 LatencySampleCount () const { return mLatencySamples; } - + UInt32 TailSampleCount () const { return mTailSamples; } - + UInt64 InputSampleCount () const { return mNumInputSamples; } - + // the class maintains the TimeStamp from render call to render call // this value is the sample count that will be used in the *next* render call Float64 SampleTime () const { return mRenderTimeStamp.mSampleTime; } - + // in some settings (for instance a delay with 100% feedback) tail time is essentially infinite // so you should safeguard the final OL render stage (post process) which is aimed at pulling the tail through // default is 10 seconds Float64 GetMaxTailTime () const { return mMaxTailTime; } - + // this ONLY takes affect when you initialise the processor, it doesn't change that AU's tail time, // but just the max amount of time that this object will allow the AU to post-process data // set this to 0, to use the AU's tail time with no adjustment @@ -247,20 +247,20 @@ public: // if this is NULL, then there is no explicit (optional or required) preflight requirement of the AU // if this is valid, then the AU either requires or optionally requires preflighting. The default // behaviour in this case is that the processor will preflight. This name can be used to preset - // to the user. If the AU doesn't present a name, but preflighting is optional/required, then the + // to the user. If the AU doesn't present a name, but preflighting is optional/required, then the // processor return "Preflight" as its string. // the String should be released by the caller. CFStringRef GetOLPreflightName () const; - // Returns true if this is processor is an offline AU, and that AU (whether optional or required) + // Returns true if this is processor is an offline AU, and that AU (whether optional or required) // needs preflighting bool OfflineAUNeedsPreflight () const; - + // this provides a rough approximation of the progress of an Offline Processing operation (both for the // preflight and the render phases) Float32 GetOLPercentComplete (); #endif - + private: CAAudioUnit mUnit; UInt32 mLatencySamples; @@ -274,11 +274,11 @@ private: AURenderCallbackStruct mUserCallback; Float64 mMaxTailTime; Float32 mLastPercentReported; - + bool IsOfflineAU () const { return mUnit.Comp().Desc().IsOffline(); } void CalculateRemainderSamples (Float64 inSampleRate); - + OSStatus DoInitialisation (const CAStreamBasicDescription &inInputFormat, const CAStreamBasicDescription &inOutputFormat, UInt64 inNumInputSamples, |