os/graphics/graphicscomposition/openwfcompositionengine/inc/openwfc_ri_display_update.h
1 // Copyright (c) 2009-2010 Nokia Corporation and/or its subsidiary(-ies).
3 // Permission is hereby granted, free of charge, to any person obtaining a
4 // copy of this software and/or associated documentation files (the
5 // "Materials"), to deal in the Materials without restriction, including
6 // without limitation the rights to use, copy, modify, merge, publish,
7 // distribute, sublicense, and/or sell copies of the Materials, and to
8 // permit persons to whom the Materials are furnished to do so, subject to
9 // the following conditions:
11 // The above copyright notice and this permission notice shall be included
12 // in all copies or substantial portions of the Materials.
14 // THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15 // EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
17 // IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
18 // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
19 // TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
20 // MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
23 // Display Update Abstract Interface
27 #ifndef OPENWFC_RI_DISPLAY_UPDATE_H
28 #define OPENWFC_RI_DISPLAY_UPDATE_H
31 #include <graphics/symbianstream.h>
34 * \brief Abstract interface used by OPENWF-C SI in order to display
35 * the composed content
39 class MOpenWFC_RI_Display_Update
43 * Retrieves one of the display attributes
45 * @param aAttributeId The attribute ID to be retrieved.
46 * @param aAttribute Pointer to the attribute to be retrieved
47 * @param aAttributeSize Size in bytes of attribute to be retrieved
49 * @return KErrNone or a system wide error
51 virtual TInt GetAttribute(TInt aAttributeId, TAny* aAttribute, TInt aAttributeSize) = 0;
54 * Sets one of the display attributes
56 * @param aAttributeId The attribute ID to be retrieved.
57 * @param aAttribute Pointer to the attribute to be retrieved
58 * @param aAttributeSize Size in bytes of attribute to be retrieved
60 * @return KErrNone or a system wide error
62 virtual TInt SetAttribute(TInt aAttributeId, TAny* aAttribute, TInt aAttributeSize) = 0;
65 * Commits the display attribute.
67 * @return KErrNone or a system wide error
69 virtual TInt CommitAttribute() = 0;
72 * Associates a stream with the topmost display layer (overlay).
73 * Must have been called successfully before calling UpdateDisplay.
74 * Also used to specify the composed output stream as the display layer.
75 * Note that currently this method is called each composition,
76 * but it is only necessary to call it when the top stream changes.
78 * This method may fail if any attributes of the stream cannot be handled by the display device.
79 * The aNonTrivialAttributes is a zero-terminated list of attribute keys and values
80 * that do not match the trivial cases for direct composition, but that some devices may support,
81 * representing eg mirror, scale, rotation, offset, or oversize cases.
82 * The implementation of this method will stop processing the list and fail if it does not recogise
83 * any of the keys or cannot accept the value associated with that key for direct display.
84 * All platforms should accept an empty or NULL list, but some may simply fail if the list is non-empty,
85 * so the caller should keep the list brief.
87 * If the method fails, then the caller must compose the content into a simpler format,
88 * and call SetTopLayerSurface again before calling UpdateDisplay.
89 * It is expected that there will be at least 1 pre-determined simpler format or stream handle that will always succeed.
91 * @param aStream The stream Id to be associated with the topmost layer
92 * @param aNonTrivialAttributes Attribute integer pair list of any non-trivial attribute values.
94 * @return KErrNone or a system wide error
96 virtual TInt SetTopLayerSurface(SymbianStreamType aStream,TInt* aNonTrivialAttributes=NULL) = 0;
99 * Associates a stream with a specific layer.
100 * Must have been called successfully before calling UpdateDisplay.
101 * Note that currently this method is called each composition,
102 * but it is only necessary to call it when the stream stack changes,
103 * when all layers should be re-specified in turn before the next UpdateDisplay call.
105 * This method may fail if any attributes of the stream cannot be handled by the display device.
106 * The aNonTrivialAttributes is a zero-terminated list of attribute keys and values
107 * that do not match the trivial cases for direct composition, but that some devices may support,
108 * representing eg mirror, scale, rotation, offset, undersize or oversize cases,
109 * and could be used to represent multiple layers.
110 * The implementation of this method will fail if it does not recogise any of the keys
111 * or cannot accept the value associated with that key for direct display.
112 * All platforms should accept an empty or NULL list, but some may simply fail if the list is non-empty,
113 * so the caller should keep the list brief.
115 * If the method fails, then the caller must compose the content into a simpler format,
116 * and call SetTopLayerSurface (or SetLayerSurface) again before calling UpdateDisplay.
118 * @param aLayer The layer id. The layer number "0" is the topmost layer.
119 * @param aStream The stream Id to be associated with the specified layer, or SYMBIAN_INVALID_HANDLE.
120 * @param aNonTrivialAttributes Attribute integer pair list of any non-trivial attribute values.
122 * @return KErrNone or a system wide error
124 virtual TInt SetLayerSurface(TInt aLayer, SymbianStreamType aStream,TInt* aNonTrivialAttributes=NULL) = 0;
127 * Update (flush/post) the screen
129 * @return KErrNone or a system wide error
131 virtual TInt UpdateDisplay() = 0;
133 #endif // OPENWFC_RI_DISPLAY_UPDATE_H