/*
 * Copyright (c) 1999-2000, Eric Moon.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions, and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions, and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */


// IAudioOp.h
// * PURPOSE
//   Abstract audio-operation interface.  Each implementation
//   of IAudioOp represents an algorithm for processing
//   streaming media.
//
//   IAudioOp instances are returned by implementations of
//   IAudioOpFactory, responsible for finding the
//   appropriate algorithm for a given format combination.
//
// * NOTES
//   7sep99:
//   +++++ moving back towards a raw interface approach; the host node
//         can provide the state/parameter/event-queue access.
//         See IAudioOpHost for the operations that the host node needs
//         to provide.
//
// * HISTORY
//   e.moon             26aug99         Begun

#ifndef __IAudioOp_H__
#define __IAudioOp_H__

#include "AudioBuffer.h"

class IAudioOpHost;
class ParameterSet;

class IAudioOp {

public:                                                                                 // *** HOST (NODE)
        IAudioOpHost* const                             host;

public:                                                                                 // *** ctor/dtor
        IAudioOp(
                IAudioOpHost*                                           _host) : host(_host) {}

        virtual ~IAudioOp() {}

public:                                                                                 // *** REQUIRED INTERFACE 

        // Process a given source buffer to produce framesRequired
        // frames of output (this may differ from the number of frames
        // read from input if this is a resampling operation,
        // or if the operation requires some amount of 'lookahead'.)
        // The time at which the first destination frame should reach
        // its destination is given by performanceTime (this should help
        // wrt/ accurate parameter-change response.)
        //
        // Return the number of frames produced (if insufficient source
        // frames were available, this may be less than framesRequired;
        // it must never be greater.)
        // NOTE
        //   If the formats are identical, source and destination
        //   may reference the same buffer.
        //
        // ANOTHER NOTE
        //   This method may well be called multiple times in response to
        //   a single call to the functor method (operator()) if one or
        //   more events occur midway through the buffer.
        //
        virtual uint32 process(
                const AudioBuffer&                      source,
                AudioBuffer&                                            destination,
                double&                                                                 sourceFrame,
                uint32&                                                                 destinationFrame,
                uint32                                                                  framesRequired,
                bigtime_t                                                               performanceTime) =0;
        
        // Replace the given filter operation (responsibility for deleting
        // it is yours, in case you want to keep it around for a while.)
        //
        virtual void replace(
                IAudioOp*                                                               oldOp) =0;
                
public:                                                                                 // *** OPTIONAL INTERFACE

        // Called when the host node is started, before any calls to
        // process().

        virtual void init() {}

        // Return the number of input frames required before an output
        // frame can be produced.
        
        virtual uint32 bufferLatency() const { return 0; }
        
};

#endif /*__IAudioOp_H__*/