/*
* Copyright (c) 2010 Ixonos Plc.
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - Initial contribution
*
* Contributors:
* Ixonos Plc
*
* Description:  
*
*/


#ifndef BUFFERMANAGEMENTCI_H
#define BUFFERMANAGEMENTCI_H

//  INCLUDES
#include <mmf/devvideo/devvideobase.h>


// CONSTANTS

/** Buffer Management Custom Interface UID */
const TUid KMmfVideoBuffermanagementUid = { 0x10204bea };


// CLASS DECLARATIONS

class MMmfVideoBufferManagementObserver;

/**
 * Buffer Management Custom Interface main interface class. Media
 * devices that support this custom interface implement this class.
 *
 * The Buffer Management Custom Interface enchances the MDF DevVideo
 * data flow model by enabling target media devices to allocate input
 * data buffers for uncompressed data input. This lets client
 * applications and source media devices write the input data directly
 * into a suitable memory area that the target media device can use,
 * possibly eliminating one extra memory copy from the data path. This
 * is especially important with hardware implementations, where the
 * target hardware may only have access to specially allocated memory
 * that only the media device can allocate.
 * 
 * The interface is typically implemented in pre-processing, encoding,
 * and post-processing media devices. It is mainly used for video
 * encoder memory buffer input in applications like video editors, and
 * when using hardware-accelerated post-processors with software video
 * decoders.
 */

class MMmfVideoBufferManagement
    {
public:
    /** A class used to signal the buffer options used. */
    class TBufferOptions
        {
    public:
        /**
         * The number of input buffers that the media device *
         * has. This is the number of buffers the client can request *
         * through MmvbmGetBufferL() before writing any back.
         */        
        TUint iNumInputBuffers;

        /**
         * Buffer size in pixels. This should match the input data
         * picture size, optionally with padding to meet coding
         * standard requirements.
         */
        TSize iBufferSize;
        };

    
    /** 
     * Sets the observer object to use. The observer gets notified
     * when new buffers are available and when buffers need to be
     * released back to the media device.
     *
     * This method can only be called before the media device has
     * been initialised with InitializeL().
     * 
     * @param aObserver The observer object to use.
     */
    virtual void MmvbmSetObserver(MMmfVideoBufferManagementObserver* aObserver) = 0;
    
    /** 
     * Enables input buffer management mode. In buffer management mode
     * the target media device allocates memory for input buffers and
     * the client can only use input buffers allocated with
     * MmvbmGetBufferL().
     *
     * This method can only be called before the media device has been
     * initialised with InitializeL(). This method must be called if
     * the client uses MmvbmGetBufferL().
     * 
     * @param aEnable ETrue if input buffer management mode is used.
     */
    virtual void MmvbmEnable(TBool aEnable) = 0;
    
    /** 
     * Sets the buffer options to use. The client can request the
     * number of input buffers that should be available, but typically
     * only few (one or two) buffers can be used.
     *
     * This method can only be called before the media device has been
     * initialised with InitializeL().
     * 
     * @param aOptions The buffer options to use, see TBufferOptions.
     *
     * @leave KErrNotSupported The requested buffer options are not
     *   supported. Typically the client has requested too many input
     *   buffers.
     */
    virtual void MmvbmSetBufferOptionsL(const TBufferOptions& aOptions) = 0;
    
    /** 
     * Gets the buffer options currently in use.
     *
     * This method can only be called before the media device has been
     * initialised with InitializeL().
     * 
     * @param aOptions Target buffer options data structure.
     */
    virtual void MmvbmGetBufferOptions(TBufferOptions& aOptions) = 0;
    
    /** 
     * Gets a new input picture buffer. The client can then write data
     * into the buffer and write it back to the media device with
     * WritePictureL().
     *
     * This method can only be called after the media device has been
     * initialised with InitializeL(). This method can only be called
     * in buffer management mode, i.e. if the client has called
     * MmvbmEnable(ETrue).
     *
     * Note that target-allocated and client-allocated input buffers
     * cannot be mixed. In buffer management mode only input buffers
     * allocated with this method can be sent to the media device.
     *
     * If a client has retrieved buffers with MmvbmGetBufferL(), it
     * must be prepated to release them synchronously at any point if
     * MmmfBufferManagementObserver::MmvbmoReleaseBuffers() is
     * called. This may happen if the target media device suddenly
     * loses access to the buffers due to DSA abort, resource
     * management conflict, or media device destruction.
     * 
     * @param aSize The requested buffer size, in pixels. The buffer
     *   size should match the picture size set at initialisation phase,
     *   or otherwise suitable buffer may not be available. If the size
     *   is smaller than the size set at initialisation phase, the
     *   allocated buffer may be larger than requested.
     * 
     * @return A new input picture buffer. If no free buffers are
     * available, the return value is NULL.
     *
     * @leave General The method will leave if an error occurs. Lack
     * of free buffers is not considered an error.
     */
    virtual TVideoPicture* MmvbmGetBufferL(const TSize& aSize) = 0;
    
    /** 
     * Releases an input buffer back to the media device without using
     * it. This method is mainly used as a response to a
     * MmvbmReleaseBuffers() callback.
     * 
     * @param aBuffer The buffer to release.
     */
    virtual void MmvbmReleaseBuffer(TVideoPicture* aBuffer) = 0;
    };


/**
 * An observer class for the buffer management custom interface.
 * Clients and source media devices using the interface
 * must implement this class.
*/
class MMmfVideoBufferManagementObserver
    {
public:
    /**
     * Notifies the observer that one or more new input buffers are
     * available. The client can then use MmvbmGetBufferL() to get a
     * buffer.
     */
    virtual void MmvbmoNewBuffers() = 0;

    /**
     * Notifies the observer all outstanding input buffers must be
     * released immediately. The client must synchronously call
     * MmvbmReleaseBuffer() for all buffers it has allocated but not
     * returned before returning from this method. This method is
     * mainly used when the target media device loses access to the
     * buffers, as a result of a Direct Screen Access abort, resource
     * management override, or media device desctruction.
     */
    virtual void MmvbmoReleaseBuffers() = 0;
    };


#endif      // BUFFERMANAGEMENTCI_H
            
// End of File