// Copyright (c) 2009-2010 Nokia Corporation and/or its subsidiary(-ies).

//

// Permission is hereby granted, free of charge, to any person obtaining a

// copy of this software and/or associated documentation files (the

// "Materials"), to deal in the Materials without restriction, including

// without limitation the rights to use, copy, modify, merge, publish,

// distribute, sublicense, and/or sell copies of the Materials, and to

// permit persons to whom the Materials are furnished to do so, subject to

// the following conditions:

//

// The above copyright notice and this permission notice shall be included

// in all copies or substantial portions of the Materials.

//

// THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

// IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY

// CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,

// TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE

// MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.

//

// Description:

// Display Update Abstract Interface

// 

//

#ifndef OPENWFC_RI_DISPLAY_UPDATE_H

#define OPENWFC_RI_DISPLAY_UPDATE_H

#include <e32base.h>

#include <graphics/symbianstream.h>

/**

 * \brief   Abstract interface used by OPENWF-C SI in order to display

 * the composed content

 *

 */

class MOpenWFC_RI_Display_Update

    {

public:

    /**

     * Retrieves one of the display attributes

     *

     * @param   aAttributeId   The attribute ID to be retrieved.

     * @param   aAttribute   Pointer to the attribute to be retrieved

     * @param   aAttributeSize   Size in bytes of attribute to be retrieved

     *

     * @return  KErrNone or a system wide error

     */

    virtual TInt GetAttribute(TInt aAttributeId, TAny* aAttribute, TInt aAttributeSize) = 0;

    /**

     * Sets one of the display attributes

     *

     * @param   aAttributeId   The attribute ID to be retrieved.

     * @param   aAttribute   Pointer to the attribute to be retrieved

     * @param   aAttributeSize   Size in bytes of attribute to be retrieved

     *

     * @return  KErrNone or a system wide error

     */

    virtual TInt SetAttribute(TInt aAttributeId, TAny* aAttribute, TInt aAttributeSize) = 0;

    /**

     * Commits the display attribute.

     *

     * @return  KErrNone or a system wide error

     */

    virtual TInt CommitAttribute() = 0;

    /**

     * Associates a stream with the topmost display layer (overlay).

     * Must have been called successfully before calling UpdateDisplay.

     * Also used to specify the composed output stream as the display layer.

     * Note that currently this method is called each composition, 

     * but it is only necessary to call it when the top stream changes.

     * 

     * This method may fail if any attributes of the stream cannot be handled by the display device.

     * The aNonTrivialAttributes is a zero-terminated list of attribute keys and values 

     * that do not match the trivial cases for direct composition, but that some devices may support,

     * representing eg mirror, scale, rotation, offset, or oversize cases. 

     * The implementation of this method will stop processing the list and fail if it does not recogise

     * any of the keys or cannot accept the value associated with that key for direct display.

     * All platforms should accept an empty or NULL list, but some may simply fail if the list is non-empty, 

     * so the caller should keep the list brief.

     *  

     * If the method fails, then the caller must compose the content into a simpler format, 

     * and call SetTopLayerSurface again before calling UpdateDisplay.

     * It is expected that there will be at least 1 pre-determined simpler format or stream handle that will always succeed.  

     * 

     * @param   aStream   The stream Id to be associated with the topmost layer

     * @param   aNonTrivialAttributes   Attribute integer pair list of any non-trivial attribute values. 

     *

     * @return  KErrNone or a system wide error

     */

    virtual TInt SetTopLayerSurface(SymbianStreamType aStream,TInt* aNonTrivialAttributes=NULL) = 0;   

    /**

     * Associates a stream with a specific layer.

     * Must have been called successfully before calling UpdateDisplay.

     * Note that currently this method is called each composition, 

     * but it is only necessary to call it when the stream stack changes,

     * when all layers should be re-specified in turn before the next UpdateDisplay call.

     * 

     * This method may fail if any attributes of the stream cannot be handled by the display device.

     * The aNonTrivialAttributes is a zero-terminated list of attribute keys and values 

     * that do not match the trivial cases for direct composition, but that some devices may support,

     * representing eg mirror, scale, rotation, offset, undersize or oversize cases,

     * and could be used to represent multiple layers. 

     * The implementation of this method will fail if it does not recogise any of the keys 

     * or cannot accept the value associated with that key for direct display.

     * All platforms should accept an empty or NULL list, but some may simply fail if the list is non-empty, 

     * so the caller should keep the list brief.

     * 

     * If the method fails, then the caller must compose the content into a simpler format,

     * and call SetTopLayerSurface (or SetLayerSurface) again before calling UpdateDisplay.

     * 

     * @param   aLayer   The layer id. The layer number "0" is the topmost layer.

     * @param   aStream  The stream Id to be associated with the specified layer, or SYMBIAN_INVALID_HANDLE.

     * @param   aNonTrivialAttributes   Attribute integer pair list of any non-trivial attribute values. 

     *

     * @return  KErrNone or a system wide error

     */

    virtual TInt SetLayerSurface(TInt aLayer, SymbianStreamType aStream,TInt* aNonTrivialAttributes=NULL) = 0;

    /**

     * Update (flush/post) the screen

     * 

     * @return  KErrNone or a system wide error

     */

    virtual TInt UpdateDisplay() = 0;

    };

#endif // OPENWFC_RI_DISPLAY_UPDATE_H