os/graphics/graphicscomposition/openwfcompositionengine/inc/openwfc_ri_display_update.h
changeset 0 bde4ae8d615e
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/os/graphics/graphicscomposition/openwfcompositionengine/inc/openwfc_ri_display_update.h	Fri Jun 15 03:10:57 2012 +0200
     1.3 @@ -0,0 +1,133 @@
     1.4 +// Copyright (c) 2009-2010 Nokia Corporation and/or its subsidiary(-ies).
     1.5 +//
     1.6 +// Permission is hereby granted, free of charge, to any person obtaining a
     1.7 +// copy of this software and/or associated documentation files (the
     1.8 +// "Materials"), to deal in the Materials without restriction, including
     1.9 +// without limitation the rights to use, copy, modify, merge, publish,
    1.10 +// distribute, sublicense, and/or sell copies of the Materials, and to
    1.11 +// permit persons to whom the Materials are furnished to do so, subject to
    1.12 +// the following conditions:
    1.13 +//
    1.14 +// The above copyright notice and this permission notice shall be included
    1.15 +// in all copies or substantial portions of the Materials.
    1.16 +//
    1.17 +// THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    1.18 +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    1.19 +// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    1.20 +// IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    1.21 +// CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    1.22 +// TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    1.23 +// MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
    1.24 +//
    1.25 +// Description:
    1.26 +// Display Update Abstract Interface
    1.27 +// 
    1.28 +//
    1.29 +
    1.30 +#ifndef OPENWFC_RI_DISPLAY_UPDATE_H
    1.31 +#define OPENWFC_RI_DISPLAY_UPDATE_H
    1.32 +
    1.33 +#include <e32base.h>
    1.34 +#include <graphics/symbianstream.h>
    1.35 +
    1.36 +/**
    1.37 + * \brief   Abstract interface used by OPENWF-C SI in order to display
    1.38 + * the composed content
    1.39 + *
    1.40 + */
    1.41 +
    1.42 +class MOpenWFC_RI_Display_Update
    1.43 +    {
    1.44 +public:
    1.45 +    /**
    1.46 +     * Retrieves one of the display attributes
    1.47 +     *
    1.48 +     * @param   aAttributeId   The attribute ID to be retrieved.
    1.49 +     * @param   aAttribute   Pointer to the attribute to be retrieved
    1.50 +     * @param   aAttributeSize   Size in bytes of attribute to be retrieved
    1.51 +     *
    1.52 +     * @return  KErrNone or a system wide error
    1.53 +     */
    1.54 +    virtual TInt GetAttribute(TInt aAttributeId, TAny* aAttribute, TInt aAttributeSize) = 0;
    1.55 +    
    1.56 +    /**
    1.57 +     * Sets one of the display attributes
    1.58 +     *
    1.59 +     * @param   aAttributeId   The attribute ID to be retrieved.
    1.60 +     * @param   aAttribute   Pointer to the attribute to be retrieved
    1.61 +     * @param   aAttributeSize   Size in bytes of attribute to be retrieved
    1.62 +     *
    1.63 +     * @return  KErrNone or a system wide error
    1.64 +     */
    1.65 +    virtual TInt SetAttribute(TInt aAttributeId, TAny* aAttribute, TInt aAttributeSize) = 0;
    1.66 +    
    1.67 +    /**
    1.68 +     * Commits the display attribute.
    1.69 +     *
    1.70 +     * @return  KErrNone or a system wide error
    1.71 +     */
    1.72 +    virtual TInt CommitAttribute() = 0;
    1.73 +    
    1.74 +    /**
    1.75 +     * Associates a stream with the topmost display layer (overlay).
    1.76 +     * Must have been called successfully before calling UpdateDisplay.
    1.77 +     * Also used to specify the composed output stream as the display layer.
    1.78 +     * Note that currently this method is called each composition, 
    1.79 +     * but it is only necessary to call it when the top stream changes.
    1.80 +     * 
    1.81 +     * This method may fail if any attributes of the stream cannot be handled by the display device.
    1.82 +     * The aNonTrivialAttributes is a zero-terminated list of attribute keys and values 
    1.83 +     * that do not match the trivial cases for direct composition, but that some devices may support,
    1.84 +     * representing eg mirror, scale, rotation, offset, or oversize cases. 
    1.85 +     * The implementation of this method will stop processing the list and fail if it does not recogise
    1.86 +     * any of the keys or cannot accept the value associated with that key for direct display.
    1.87 +     * All platforms should accept an empty or NULL list, but some may simply fail if the list is non-empty, 
    1.88 +     * so the caller should keep the list brief.
    1.89 +     *  
    1.90 +     * If the method fails, then the caller must compose the content into a simpler format, 
    1.91 +     * and call SetTopLayerSurface again before calling UpdateDisplay.
    1.92 +     * It is expected that there will be at least 1 pre-determined simpler format or stream handle that will always succeed.  
    1.93 +     * 
    1.94 +     * @param   aStream   The stream Id to be associated with the topmost layer
    1.95 +     * @param   aNonTrivialAttributes   Attribute integer pair list of any non-trivial attribute values. 
    1.96 +     *
    1.97 +     * @return  KErrNone or a system wide error
    1.98 +     */
    1.99 +    virtual TInt SetTopLayerSurface(SymbianStreamType aStream,TInt* aNonTrivialAttributes=NULL) = 0;   
   1.100 +
   1.101 +    /**
   1.102 +     * Associates a stream with a specific layer.
   1.103 +     * Must have been called successfully before calling UpdateDisplay.
   1.104 +     * Note that currently this method is called each composition, 
   1.105 +     * but it is only necessary to call it when the stream stack changes,
   1.106 +     * when all layers should be re-specified in turn before the next UpdateDisplay call.
   1.107 +     * 
   1.108 +     * This method may fail if any attributes of the stream cannot be handled by the display device.
   1.109 +     * The aNonTrivialAttributes is a zero-terminated list of attribute keys and values 
   1.110 +     * that do not match the trivial cases for direct composition, but that some devices may support,
   1.111 +     * representing eg mirror, scale, rotation, offset, undersize or oversize cases,
   1.112 +     * and could be used to represent multiple layers. 
   1.113 +     * The implementation of this method will fail if it does not recogise any of the keys 
   1.114 +     * or cannot accept the value associated with that key for direct display.
   1.115 +     * All platforms should accept an empty or NULL list, but some may simply fail if the list is non-empty, 
   1.116 +     * so the caller should keep the list brief.
   1.117 +     * 
   1.118 +     * If the method fails, then the caller must compose the content into a simpler format,
   1.119 +     * and call SetTopLayerSurface (or SetLayerSurface) again before calling UpdateDisplay.
   1.120 +     * 
   1.121 +     * @param   aLayer   The layer id. The layer number "0" is the topmost layer.
   1.122 +     * @param   aStream  The stream Id to be associated with the specified layer, or SYMBIAN_INVALID_HANDLE.
   1.123 +     * @param   aNonTrivialAttributes   Attribute integer pair list of any non-trivial attribute values. 
   1.124 +     *
   1.125 +     * @return  KErrNone or a system wide error
   1.126 +     */
   1.127 +    virtual TInt SetLayerSurface(TInt aLayer, SymbianStreamType aStream,TInt* aNonTrivialAttributes=NULL) = 0;
   1.128 +    
   1.129 +    /**
   1.130 +     * Update (flush/post) the screen
   1.131 +     * 
   1.132 +     * @return  KErrNone or a system wide error
   1.133 +     */
   1.134 +    virtual TInt UpdateDisplay() = 0;
   1.135 +    };
   1.136 +#endif // OPENWFC_RI_DISPLAY_UPDATE_H