/*

* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "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:

*

* Description:     Header file for S60 display posting API

*

*/

#ifndef __POSTING_SURFACE_H__

#define __POSTING_SURFACE_H__

//- Include Files  ----------------------------------------------------------

#include <e32base.h>

#include <e32cmn.h>

#include <gdi.h>

//- Namespace ---------------------------------------------------------------

//- Constants ---------------------------------------------------------------

///Little endian bit mask

const TUint KPostFormatLE    = 0x01000000;

///Big endian bit mask

const TUint KPostFormatBE    = 0x02000000;

///Color range 0-255 bit mask

const TUint KPostColorRange0 = 0x00000010;

///Color range 16-235 bit mask

const TUint KPostColorRange1 = 0x00000020;

///ITU-R BT.709-5 standard bit mask

const TUint KPost709         = 0x00000100;

///ITU-R BT.601-5 standard bit mask

const TUint KPost601         = 0x00000200;

///Posting RGB format RGB565 bit mask

const TUint KPostRGB565      = 0x00000001;

///Posting RGB format RGB888 (24bit) bit mask

const TUint KPostRGB888      = 0x00000002;

///Posting RGB format RGBx888 (32bit) bit mask

const TUint KPostRGBx888     = 0x00000004;

///Posting YUV 420 Planar format

const TUint KPostYUV420Planar= 0x00001000;

///Platform specific

const TUint KPostPlatformDependent = 0x10000000;

//- Forward Declarations ----------------------------------------------------

class CPostingSurface;

class TPostingBuff;

//- Class Definitions -------------------------------------------------------

/**

*  CPostingSurface

*

*  Contains core data structures and member functions in the display posting API

*/

class CPostingSurface : public CBase

{

public:

    /**

    *  TPostingFormat

    *

    *  Specifies the data format. Also sampling pattern, data layout and YUV-RGB conversion coefficients for YUV data.

    */

    enum TPostingFormat

    {

            EFormatInvalidValue   = 0x00000000,     //Initialisation value, do not use

            ERgb16bit565Le        = KPostRGB565  | KPostFormatLE,

            ERgb24bit888Le        = KPostRGB888  | KPostFormatLE,

            ERgb32bit888Le        = KPostRGBx888 | KPostFormatLE,

            EYuv422LeBt709Range0  = KPost709     | KPostFormatLE | KPostColorRange0,

            EYuv422LeBt709Range1  = KPost709     | KPostFormatLE | KPostColorRange1,

            EYuv422BeBt709Range0  = KPost709     | KPostFormatBE | KPostColorRange0,

            EYuv422BeBt709Range1  = KPost709     | KPostFormatBE | KPostColorRange1,

            EYuv422LeBt601Range0  = KPost601     | KPostFormatLE | KPostColorRange0,

            EYuv422LeBt601Range1  = KPost601     | KPostFormatLE | KPostColorRange1,

            EYuv422BeBt601Range0  = KPost601     | KPostFormatBE | KPostColorRange0,

            EYuv422BeBt601Range1  = KPost601     | KPostFormatBE | KPostColorRange1,

            EYuv420PlanarBt709Range0 = KPost709     | KPostYUV420Planar | KPostColorRange0,

            EYuv420PlanarBt709Range1 = KPost709     | KPostYUV420Planar | KPostColorRange1,

            EYuv420PlanarBt601Range0 = KPost601     | KPostYUV420Planar | KPostColorRange0,

            EYuv420PlanarBt601Range1 = KPost601     | KPostYUV420Planar | KPostColorRange1,

            EYuvPlatformDependent    = KPostPlatformDependent,

            };

    /**

    *  TRotationType

    *

    *  Rotation types as defined in [MDF Video Common Elements]

    */

    enum TRotationType

    {

            ENoRotation            = 0x00000000, //0Deg

            ERotate90ClockWise     = 0x00000001, //90Deg

            ERotate180             = 0x00000002, //180Deg

            ERotate90AntiClockWise = 0x00000004, //270Deg

            };

    /**

    *  TPostingBuffering

    *

    *  Bitmask value describing how the display posting is done and how the frames should be handled.

    */

    enum TPostingBuffering

    {

            EBufferingInvalid  = 0x00000000,    //Initialisation value, do not use

            ESingleBuffering   = 0x00000004,

            EDoubleBuffering   = 0x00000001,

            ETripleBuffering   = 0x00000002,

            EProgressiveFrames = 0x00000010,

            EInterlacedFrames  = 0x00000020,

            EDisAllowFrameSkip = 0x00000100,

            EAllowFrameSkip    = 0x00000200,

            EInternalBuffers   = 0x00001000,

            EExternalBuffers   = 0x00002000,

            };

    /**

    *  TPostageUsageHint

    *

    *  Tells the intended usage of the posting surface. The display driver uses these hints to prioritize the HW usage and route content.

    *  Vendor specific meanings may be added to the end of the enum space.

    */

    enum TPostingUsageHint

    {

            EUsageInvalid   = 0x00000000,   //Initialisation value, do not use

            EGeneric        = 0x00000001,

            E3D             = 0x00000002,

            EVideoPlayback  = 0x00000004,

            EVideoCapture   = 0x00000008,

            EViewfinder     = 0x00000010,

            EStillImage     = 0x00000011,

            EVendorSpecific = 0x80000000,

            };

    /**

    *  TPostingCapab

    *

    *  Describes the Posting buffer size restrictions and posting processing capabilities.

    */

    class TPostingCapab

    {

        public:

            inline TPostingCapab();

        public:

            /** Maximum buffer size in bytes */

            TUint iMaxSourceSize;

            /** Hw limits for source size, normally cannot allocated whole this size */

            TSize iMaxPixelSize;

            /** Bit mask of supported rotations */

            TUint iSupportedRotations;

            /** ETrue when horizontal mirroring is supported */

            TBool iSupportsMirroring;

            /** ETrue when rational scales is supported */

            TBool iSupportsScaling;

            /** ETrue when brightness tuning is supported */

            TBool iSupportsBrightnessControl;

            /** ETrue when contrast tuning is supported */

            TBool iSupportsContrastControl;

            /** Bitmask (TPostingBuffering) */

            TUint iSupportedPostingBuffering;

            /** Bitmask (TBufferType) */

            TUint iSupportedBufferTypes;

    };

    enum TBufferType

    {

            EBufferTypeInvalid = 0x00000000,    //Initialisation value, do not use

            EStandardBuffer    = 0x00000001,    //Direct address

            EChunkBuffer       = 0x00000002,//RChunk handle

            EExternalBuffer    = 0x00000004,//External buffers

    };

    /**

    *  TPostingSourceParams

    *

    *  Describes the source content and buffering parameters. These values are fixed in the initialization phase.

    */

    class TPostingSourceParams

    {

        public:

                inline TPostingSourceParams();

        public:

            /** Buffering usage mode (TPostingBuffering) */

            TUint iPostingBuffering;

            /** Indicates the type of buffer requested */

            TBufferType iBufferType;

            /** Purpose of buffer (TPostingUsageHint) */

            TUint iPostingUsage;

            /** Source resolution. Values must be even */

            TSize iSourceImageSize;

            /** Source's pixel format */

            TPostingFormat iPostingFormat;

            /** Source pixel aspect ratio (width), Scaling factor = Numerator/Denominator. Tv out only */

            TUint16 iPixelAspectRatioNum;

            /** Source pixel aspect ratio (width) */

            TUint16 iPixelAspectRatioDenom;

            /**

            *  ETrue when copy protection enabled

            *  indicates if the content has copy protection restrictions. true: Restricted

            */

            TBool iContentCopyRestricted;

    };

    /**

    *  TPostingParams

    *

    *  Speficies window properties and required processing types for the posting buffer before it can be displayed on the screen.

    */

    class TPostingParams

    {

        public:

            inline TPostingParams();

        public:

            /** Size and position of the rectangle on phone's display. Even. Ui-orientation parameters.

            *   Does not affect Tv-out

            */

            TRect iDisplayedRect;

			/** Output size in pixels, defines scaling.  Relative to iDisplayedRect and must not

			*   exceed those boundaries

			*/

			TRect iScaleToRect;

            /** Required cropping for the content before applying other processing. Even.

            *   This is <= iSourceImageSize. This is Tv-out crop too

            */

            TRect iInputCrop;

            /** ETrue when horizontal mirroring. Does not affect Tv-out */

            TBool iMirror;

            /** Orientation of content compared to symbian videobuffer. Does not affect Tv-out */

            TRotationType iRotation;

            /** Brightness value on screen, [-100,100]%, may be ignored by the driver */

            TInt16 iBrightness;

            /** Contrast value on screen, [-100,100]% */

            TInt16 iContrast;

            /** Defined background color. Give in same format what symbian videobuffer currently is */

            TRgb iBackGround;

    };

    /**

    *  TPostingBuff

    *

    *  Contains information about the posting buffer.

    */

    class TPostingBuff

    {

        public:

            /** @return EBufferTypeInvalid or EChunkBuffer (iType) */

            IMPORT_C virtual TBufferType GetType();

            /** @return Direct address of buffer (0,0) (iBuffer) */

            IMPORT_C virtual TAny* GetBuffer();

            /** @return buffer size in pixels */

            IMPORT_C virtual TSize GetSize();

            /** @return scanline length in bytes (width*bytes_per_pixel + some_offset) */

            IMPORT_C virtual TUint GetStride();

        protected:

            /** Hidden constructor, user should never use this */

            IMPORT_C TPostingBuff();

        protected:

            /** Type of this TPostingBuff */

            TBufferType iType;

            /** Pointer to buffer */

            TAny*  iBuffer;

            /** Size of frame in pixels */

            TSize  iSize;

            /** Scanline length in bytes (width*bytes_per_pixel + some_offset) */

            TUint iStride;

    };

    /**

	* TPostingBuffExt

	*

    * Extension for TPostingBuff class. Allows external buffers to be set.

    */

    class TPostingBuffExt : public TPostingBuff

        {

        public:

            ///Set pointer to external buffer

            IMPORT_C virtual void SetBuffer(TAny* aBuffer);

            ///Set size of buffer in pixels

            IMPORT_C virtual void SetSize(TSize aSize);

            ///Set scanline length in bytes

            IMPORT_C virtual void SetStride(TUint aStride);

        protected:

            ///Hidden constructor, user should never use this

            IMPORT_C TPostingBuffExt();

        };

    /**

    *  TPostingBufferChunk

    *

    *  the chunk buffer should be requested by the client if the client application must pass the buffer across a process boundary.

    */

    class TPostingBufferChunk : public TPostingBuff

    {

        public:

            /** @return Handle to DChunk (iChunk) */

            IMPORT_C virtual RChunk GetChunk();

            /** @return buffer start address offset in chunk, (iOffsetInChunk) */

            IMPORT_C virtual TUint GetOffsetInChunk();

        protected:

            /** Hidden constructor */

            IMPORT_C TPostingBufferChunk();

        protected:

            /** Handle to DChunk */

            RChunk iChunk;

            /** Offset in chunk, to first pixel */

            TUint iOffsetInChunk;

    };

    public:

    /** Object destructor */

    virtual ~CPostingSurface(){};

    /**

    *   Initialises API for given parameters, and reserving posting for user (limited amount).

    *   If all success and aSource&aDest are filled correctly, posting is ready to use.

    *   @param  aSource  Source buffer information.

    *   @param  aDest    Destination parameters, @see CPostingSurface::SetPostingParameters

    *   @return Leaves when failed, with standard symbian error code

    */

    virtual void InitializeL(const TPostingSourceParams& aSource, const TPostingParams& aDest) = 0;

    /**

    *  Returns posting API provided properties to parameter

    *  @param aCaps Supported features, filled by driver

    *  @return KErrNone if success

    */

    virtual void GetCapabilities(TPostingCapab& aCaps) = 0;

    /**

    *  Queries the underlying implementation about its capability to process proposed input format.

    *  @param aFormat Format what to be asked.

    *  @return ETrue when aFormat is supported, otherwise EFalse

    */

    virtual TBool FormatSupported(TPostingFormat aFormat) = 0;

    /**

    *  Asynchronous freeing of reservation of posting.

    *  @param  aComplete -parameter is status of destroying, driver completes it when complete

    */

    virtual void  Destroy ( TRequestStatus& aComplete)= 0;

    /**

    *  Synchronic version of Destroy(TRequestStatus& aComplete),

    *  Note, this method can take same time what previous version takes

    */

    virtual void Destroy() = 0;

    /**

    *  Starts a wait for next free buffer

    *  It is allowed for an application to wait and acquire

    *  two or more buffers before actually posting the buffers.

    *  However, only one wait for next free buffer can be active at the time (!).

    *  @param  aComplete  Request to be complete when next buffer is available.

    *  @return KErrNone if success

    */

    virtual TInt WaitForNextBuffer(TRequestStatus& aComplete) = 0;

    /**

    *  Gets the next free buffer (must have been waited with WaitForNextBuffer()

    *  for before calling this!).

    *  @return  Next available buffer settings for user

    */

    virtual TPostingBuff* NextBuffer() = 0;

    /** Cancels the wait for the next free buffer. Can be ingnored by driver */

    virtual TInt CancelBuffer() = 0;

    /**

    *  Posts buffer previously got from the API.

    *  @param  aBuffer  Buffer object where driver to continues updating

    *  @return KErrNone if success

    */

    virtual TInt PostBuffer(TPostingBuff* aBuffer) = 0;

    /**

    *  This function can be used to change window

    *  properties and required processing types for the posting

    *  buffer before it can be displayed on the screen.

    *  Perhaps some limititations of parameter change can exists, then this fails.

    *  @param   aParams  New destination settings of Posting

    *  @return  KErrNone if success

    */

    virtual TInt SetPostingParameters(const TPostingParams& aParams) = 0;

    /**

    *  This function can be used to directly pass the DSA-region

    *  of the internal display down to this API if DSA-region is

    *  clipped in some way. Some implementations may support none:

    *  some may support only one or few clipping regions.

    *  In those cases the return value can be KErrNotSupported.

    *  If clipping region is supported, no image will be drawn outside

    *  of the clipping region.

    *  If iDisplayedRect is set to an empty region, then the posting is not

    *  active for the internal display. However, if display posting is still done,

    *  external display may get updated. Default: no clipping is done,

    *  but internal display is enabled.

    *  @param  aClipRegion  Rectangles of current DSA.

    *  @return  KErrNone if success

    */

    virtual TInt SetClipRegion(const TRegion& aClipRegion) = 0;

};

//- Inline Functions --------------------------------------------------------

#include "posting_surface.inl"

#endif //__POSTING_SURFACE_H__

// End of File