// Copyright (c) 2007-2010 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:

// Surface Manager API

//

#ifndef __SURFACE_HINTS_H__

#define __SURFACE_HINTS_H__

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

#include <e32cmn.h>

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

namespace surfaceHints

{

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

/** Hint of the surface content.

    @see TSurfaceContent for possible values

*/

const TInt KSurfaceContent = 0x1;

/** Hint of the expected update rate of the surface content.

    Value for a surface containing e.g. 25 fps video the value should be 25.

    For a static UI element the value should be 0.

    @see TSurfaceUpdate

*/

const TInt KSurfaceUpdate = 0x2;

/** Hint whether the surface content is copy protected and can it be

    shown on external displays.

    @see TSurfaceProtection for possible values.

*/

const TInt KSurfaceProtection = 0x3;

/** Hint about the surface’s characteristics or properties,

   For example if a surface can be persisted by the effects engine.

   @see TSurfaceCharacteristics for possible values.

*/

const TInt KSurfaceCharacteristics = 0x4;

/** Values used for the KSurfaceContent key */

enum TSurfaceContent

    {

    /** No specific use-case */

    EGeneric,

    /** Camera viewfinder frames */

    EViewFinder,

    /** Images captured by camera */

    EStillImage,

    /** Decoded video frames */

    EVideoPlayback,

    /** Video frames from video telephony */

    EVideoTelephony,

    /** EGL surface */

    EGfx,

    /** Main UI surface */

    EUi,

    /** Composition target surface */

    ECompositionTarget,

    /** Indicates that the surface has to accessible by ARM.

        This can be orr'ed with other TSurfaceContent enumerations. */

    EArmAccess = 0x80000000

    };

/** Values used for the KSurfaceProtection key. The values are bitmasks and can be combined

* e.g. EAllowAnalogProtectionRequired | EAllowDigitalProtectionRequired.

*/

enum TSurfaceProtection

    {

    /**

    * Not allowed on external outputs

    */

    EAllowInternalOnly                  = 0x00000000,

    /**

    * Allowed on all external outputs

    */

    EAllowAllExternals                  = 0xFFFFFFFF,

    /**

    * Allow passing content over analog outputs,

    * e.g. composite and S-video

    */

    EAllowAnalog                        = 0x00000010,

    /**

    * Allow output over an analog output channel which has a protection

    * mechanism

    */

    EAllowAnalogProtectionRequired      = 0x00000020,

    /**

    * Allow passing content over digital outputs,

    * e.g. DVI and HDMI

    */

    EAllowDigital                       = 0x00000200,

    /**

    * Licensed product must attempt to engage HDCP to protect the content.

    * However it should be passed through to HDMI even if HDCP is not engaged or fails to engage.

    */

    EAllowDigitalProtectionRequested    = 0x00000400,

    /**

    * Licensed product is required to engage HDCP to protect the content.

    * If HDCP is not engaged or can not be engaged the content must not be passed through to HDMI.

    */

    EAllowDigitalProtectionRequired     = 0x00000800,

    };

/** Values used for the KSurfaceCharacteristics key. The values are bitmasks and can be combined.

*/

enum TSurfaceCharacteristics

    {

    /**

    * Surface cannot be persisted once it has been closed by the creator

    */

    ENotPersistable = 1,

    };

class TSurfaceUpdate

    {

    /** Constructor.

        @param aUpdateRate   How often the surface content is redrawn per second.

        @param aTearingFree  When ETrue surface updates should be synchronized

                             with display refresh rate, otherwise surface can

                             be updated as fast as possible.

    */

    inline TSurfaceUpdate(TUint aUpdateRate, TBool aTearingFree);

    /** Converts a value to TSurfaceUpdate */

    inline TSurfaceUpdate(TInt aValue);

    /** Converts TSurfaceUpdate to a signed integer, so it can be used as

        a value for KSurfaceUpdate key. */

    inline operator TInt() const;

    /** Getter for surface update rate.

        @return updates per second

    */

    inline TUint UpdateRate() const;

    /** Getter for surface update synchronization.

        @return ETrue - updates should be synchronized with display refresh rate,

                EFalse - surface can be updated as fast as possible.

    */

    inline TBool TearingFree() const;

    private:

        TUint iValue;

    };

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

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

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

TSurfaceUpdate::TSurfaceUpdate(TUint aUpdateRate, TBool aTearingFree)

    : iValue( ( aUpdateRate & 0xFFFF ) | ( aTearingFree ? 0x80000000 : 0x0 ) )

    {

    }

TSurfaceUpdate::TSurfaceUpdate(TInt aValue)

    : iValue( static_cast<TUint>( aValue ) )

    {

    }

TSurfaceUpdate::operator TInt() const

    {

    return static_cast<TInt>( iValue );

    }

TUint TSurfaceUpdate::UpdateRate() const

    {

    return ( iValue & 0xFFFF );

    }

TBool TSurfaceUpdate::TearingFree() const

    {

    return ( iValue & 0x80000000 ) ? ETrue : EFalse;

    }

} //namespace surfaceHints

#endif //__SURFACE_HINTS_H__

// End of File