1 /*

     2 * Copyright (c) 2010 Ixonos Plc.

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - Initial contribution

    11 *

    12 * Contributors:

    13 * Ixonos Plc

    14 *

    15 * Description:  

    16 *

    17 */

    18 

    19 

    20 #ifndef BUFFERMANAGEMENTCI_H

    21 #define BUFFERMANAGEMENTCI_H

    22 

    23 //  INCLUDES

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

    25 

    26 

    27 // CONSTANTS

    28 

    29 /** Buffer Management Custom Interface UID */

    30 const TUid KMmfVideoBuffermanagementUid = { 0x10204bea };

    31 

    32 

    33 // CLASS DECLARATIONS

    34 

    35 class MMmfVideoBufferManagementObserver;

    36 

    37 /**

    38  * Buffer Management Custom Interface main interface class. Media

    39  * devices that support this custom interface implement this class.

    40  *

    41  * The Buffer Management Custom Interface enchances the MDF DevVideo

    42  * data flow model by enabling target media devices to allocate input

    43  * data buffers for uncompressed data input. This lets client

    44  * applications and source media devices write the input data directly

    45  * into a suitable memory area that the target media device can use,

    46  * possibly eliminating one extra memory copy from the data path. This

    47  * is especially important with hardware implementations, where the

    48  * target hardware may only have access to specially allocated memory

    49  * that only the media device can allocate.

    50  * 

    51  * The interface is typically implemented in pre-processing, encoding,

    52  * and post-processing media devices. It is mainly used for video

    53  * encoder memory buffer input in applications like video editors, and

    54  * when using hardware-accelerated post-processors with software video

    55  * decoders.

    56  */

    57 

    58 class MMmfVideoBufferManagement

    59     {

    60 public:

    61     /** A class used to signal the buffer options used. */

    62     class TBufferOptions

    63         {

    64     public:

    65         /**

    66          * The number of input buffers that the media device *

    67          * has. This is the number of buffers the client can request *

    68          * through MmvbmGetBufferL() before writing any back.

    69          */        

    70         TUint iNumInputBuffers;

    71 

    72         /**

    73          * Buffer size in pixels. This should match the input data

    74          * picture size, optionally with padding to meet coding

    75          * standard requirements.

    76          */

    77         TSize iBufferSize;

    78         };

    79 

    80     

    81     /** 

    82      * Sets the observer object to use. The observer gets notified

    83      * when new buffers are available and when buffers need to be

    84      * released back to the media device.

    85      *

    86      * This method can only be called before the media device has

    87      * been initialised with InitializeL().

    88      * 

    89      * @param aObserver The observer object to use.

    90      */

    91     virtual void MmvbmSetObserver(MMmfVideoBufferManagementObserver* aObserver) = 0;

    92     

    93     /** 

    94      * Enables input buffer management mode. In buffer management mode

    95      * the target media device allocates memory for input buffers and

    96      * the client can only use input buffers allocated with

    97      * MmvbmGetBufferL().

    98      *

    99      * This method can only be called before the media device has been

   100      * initialised with InitializeL(). This method must be called if

   101      * the client uses MmvbmGetBufferL().

   102      * 

   103      * @param aEnable ETrue if input buffer management mode is used.

   104      */

   105     virtual void MmvbmEnable(TBool aEnable) = 0;

   106     

   107     /** 

   108      * Sets the buffer options to use. The client can request the

   109      * number of input buffers that should be available, but typically

   110      * only few (one or two) buffers can be used.

   111      *

   112      * This method can only be called before the media device has been

   113      * initialised with InitializeL().

   114      * 

   115      * @param aOptions The buffer options to use, see TBufferOptions.

   116      *

   117      * @leave KErrNotSupported The requested buffer options are not

   118      *   supported. Typically the client has requested too many input

   119      *   buffers.

   120      */

   121     virtual void MmvbmSetBufferOptionsL(const TBufferOptions& aOptions) = 0;

   122     

   123     /** 

   124      * Gets the buffer options currently in use.

   125      *

   126      * This method can only be called before the media device has been

   127      * initialised with InitializeL().

   128      * 

   129      * @param aOptions Target buffer options data structure.

   130      */

   131     virtual void MmvbmGetBufferOptions(TBufferOptions& aOptions) = 0;

   132     

   133     /** 

   134      * Gets a new input picture buffer. The client can then write data

   135      * into the buffer and write it back to the media device with

   136      * WritePictureL().

   137      *

   138      * This method can only be called after the media device has been

   139      * initialised with InitializeL(). This method can only be called

   140      * in buffer management mode, i.e. if the client has called

   141      * MmvbmEnable(ETrue).

   142      *

   143      * Note that target-allocated and client-allocated input buffers

   144      * cannot be mixed. In buffer management mode only input buffers

   145      * allocated with this method can be sent to the media device.

   146      *

   147      * If a client has retrieved buffers with MmvbmGetBufferL(), it

   148      * must be prepated to release them synchronously at any point if

   149      * MmmfBufferManagementObserver::MmvbmoReleaseBuffers() is

   150      * called. This may happen if the target media device suddenly

   151      * loses access to the buffers due to DSA abort, resource

   152      * management conflict, or media device destruction.

   153      * 

   154      * @param aSize The requested buffer size, in pixels. The buffer

   155      *   size should match the picture size set at initialisation phase,

   156      *   or otherwise suitable buffer may not be available. If the size

   157      *   is smaller than the size set at initialisation phase, the

   158      *   allocated buffer may be larger than requested.

   159      * 

   160      * @return A new input picture buffer. If no free buffers are

   161      * available, the return value is NULL.

   162      *

   163      * @leave General The method will leave if an error occurs. Lack

   164      * of free buffers is not considered an error.

   165      */

   166     virtual TVideoPicture* MmvbmGetBufferL(const TSize& aSize) = 0;

   167     

   168     /** 

   169      * Releases an input buffer back to the media device without using

   170      * it. This method is mainly used as a response to a

   171      * MmvbmReleaseBuffers() callback.

   172      * 

   173      * @param aBuffer The buffer to release.

   174      */

   175     virtual void MmvbmReleaseBuffer(TVideoPicture* aBuffer) = 0;

   176     };

   177 

   178 

   179 /**

   180  * An observer class for the buffer management custom interface.

   181  * Clients and source media devices using the interface

   182  * must implement this class.

   183 */

   184 class MMmfVideoBufferManagementObserver

   185     {

   186 public:

   187     /**

   188      * Notifies the observer that one or more new input buffers are

   189      * available. The client can then use MmvbmGetBufferL() to get a

   190      * buffer.

   191      */

   192     virtual void MmvbmoNewBuffers() = 0;

   193 

   194     /**

   195      * Notifies the observer all outstanding input buffers must be

   196      * released immediately. The client must synchronously call

   197      * MmvbmReleaseBuffer() for all buffers it has allocated but not

   198      * returned before returning from this method. This method is

   199      * mainly used when the target media device loses access to the

   200      * buffers, as a result of a Direct Screen Access abort, resource

   201      * management override, or media device desctruction.

   202      */

   203     virtual void MmvbmoReleaseBuffers() = 0;

   204     };

   205 

   206 

   207 #endif      // BUFFERMANAGEMENTCI_H

   208             

   209 // End of File