1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/graphics/windowing/windowserver/inc/Graphics/openwfc/wselement.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,498 @@
1.4 +// Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// Interface for Scene Elements
1.18 +//
1.19 +//
1.20 +
1.21 +/**
1.22 + @publishedPartner
1.23 + @prototype
1.24 +*/
1.25 +
1.26 +#ifndef WSELEMENT_H
1.27 +#define WSELEMENT_H
1.28 +
1.29 +#include <w32std.h>
1.30 +#include <graphics/wsgraphicdrawerinterface.h>
1.31 +#include <graphics/surface.h>
1.32 +
1.33 +/**
1.34 + * @brief Window Server Scene Element Interface Definition
1.35 + *
1.36 + * This interface allows Image Sources to be associated with meta-data
1.37 + * to define how the Image Source must be presented within a Scene.
1.38 + *
1.39 + * For a conceptual overview of Scenes, refer to the @c MWsScene Interface.
1.40 + *
1.41 + * The following aspects of Image Source presentation may be controlled:
1.42 + * @li Source rectangular region
1.43 + * @li Destination rectangular region
1.44 + * @li Rotation and flipping
1.45 + * @li Opacity
1.46 + * @li Relative z-order (ordinal position)
1.47 + * @li Tags to descriminate the UI from other Elements
1.48 + *
1.49 + * All co-ordinates are pixels offsets from (0,0) representing the
1.50 + * top level of the Image Source or Destination Target (the screen
1.51 + * or an off-screen buffer representing the screen), moving rightwards
1.52 + * and downwards in x and y co-ordinates respectively.
1.53 + *
1.54 + * Elements can be marked with flags. There are two different consumers
1.55 + * of flags: Target Renderers and Render Stage Plug-ins.
1.56 + *
1.57 + * Target Renderers are sub-systems which actually do composition and
1.58 + * rendering on a particular display device or off-screen buffer.
1.59 + * The EElementTransparencySource flag tells the Target Renderer that
1.60 + * alpha blending must use the alpha channel in the Surface connected to
1.61 + * the Element.
1.62 + *
1.63 + * On the other hand, Render Stage Plug-ins need flags to implement
1.64 + * specific policies such as "UI always on top". To facilitate this,
1.65 + * Elements have a EElementIsIndirectlyRenderedUserInterface or a
1.66 + * EElementIsDirectlyRenderedUserInterface optionally set. This
1.67 + * flag allows Render Stage Plug-ins to keep the relative z-order
1.68 + * of Elements aligned to this policy.
1.69 + *
1.70 + * To allow compatible updates to be made to flags, all Render Stage
1.71 + * Plug-ins must preserve the flags in Elements which they do not operate
1.72 + * upon. Target Renderers may ignore the flags in Elements which they
1.73 + * do not operate on.
1.74 + *
1.75 + * <h2>Intial State</h2>
1.76 + *
1.77 + * The initial state for an Element is:
1.78 + * @li Fully opaque
1.79 + * @li No rotation, nor flipped
1.80 + * @li Not part of the Committed Scene
1.81 + * @li No connected Surface
1.82 + * @li All flags reset
1.83 + * @li Local error value set as KErrNone
1.84 + * @li Source Rectangle and Destination Rectangle is (0,0,0,0)
1.85 + * @il Destination Clipping Rectangle is (0,0,0,0)
1.86 + *
1.87 + * When an Image Source is connected, the initial state becomes:
1.88 + * @li Source Rectangle is the extent of the Image Source
1.89 + * @li Destination Rectangle is set at origin (0,0), whose sized equals the
1.90 + * Image Source size truncated the the target screen size.
1.91 + * @li Destination Clipping Rectangle is (0,0,0,0) to represent the entire
1.92 + * area of the target screen.
1.93 + *
1.94 + * <h2>Special Rectangle Values</h2>
1.95 + *
1.96 + * Sometimes it is desirable to reset a Source, Destination, or Clipping
1.97 + * Rectangle so that the actual value used matches the corresponding Source
1.98 + * Image or Target Screen size. In such cases rectangle (0,0,0,0) is used to
1.99 + * represent this.
1.100 + *
1.101 + * <h2>Extending this interface</h2>
1.102 + *
1.103 + * This interface can be extended in two different ways
1.104 + * @li Creating optional extension interfaces with
1.105 + * MWsElement::MWsObjectProvider::ResolveObjectInterface()
1.106 + * @li Defining new TElementFlags flag settings; Render Stage Plug-ins
1.107 + * preserve the value of these across the Render Stage Pipeline.
1.108 + *
1.109 + * <h2>Committed Elements versus Pending Elements</h2>
1.110 + *
1.111 + * This interface allows Elements to be modified in terms of their
1.112 + * own flag settings, and rotation, as well as their relative position
1.113 + * with other Elements. Queries return the pending values for such
1.114 + * Elements. Any modifications are marked Pending, and affect the Scene
1.115 + * according to the rules described by "Rendering" in @c MWsScene.
1.116 + *
1.117 + * <h2>Order in which transformations are applied</h2>
1.118 + *
1.119 + * A number of different transformations may be specified for an Element.
1.120 + * The order in which these are applied to arrive at the view seen in
1.121 + * the target is:
1.122 + * -# SetSourceRectangle (Cropping)
1.123 + * -# SetSourceFlipping (Flipping)
1.124 + * -# SetSourceRotation (Rotation)
1.125 + * -# SetDestinationRectangle (Scaling and Positioning)
1.126 + * -# SetDestinationClippingRectangle (Scaling and Positioning)
1.127 + * -# SetGlobalAlpha (Blending)
1.128 + */
1.129 +class MWsElement : public MWsObjectProvider
1.130 + {
1.131 +public:
1.132 +
1.133 + /**
1.134 + * @brief Flags used by Target Renderers.
1.135 + */
1.136 + enum TElementTargetRendererFlags
1.137 + {
1.138 + /**
1.139 + * Target renderer must treat the Element as Opaque.
1.140 + */
1.141 + EElementTransparencyNone = 0,
1.142 + /**
1.143 + * Target renderer must use the Global Alpha Transparency value
1.144 + * from the Element
1.145 + */
1.146 + EElementTransparencyGlobalAlpha = (1 << 0),
1.147 + /**
1.148 + * Target renderer must use the Alpha Transparency Channel from
1.149 + * the Element
1.150 + */
1.151 + EElementTransparencySource = (1 << 1),
1.152 + /**
1.153 + * Reserved flag value; this must not be set.
1.154 + */
1.155 + EElementTargetRendererReserved = (1 << 2)
1.156 + };
1.157 +
1.158 + /**
1.159 + * @brief Flags used by Render Stages.
1.160 + */
1.161 + enum TElementRenderStageFlags
1.162 + {
1.163 + /**
1.164 + * No flag value set for Render Stage Plug-in
1.165 + */
1.166 + EElementRenderStageNone = 0,
1.167 + /**
1.168 + * Indirectly Rendered User Interface, i.e. rendering via
1.169 + * MWsGraphicsContext calls originating from client CWindowGc
1.170 + * commands
1.171 + */
1.172 + EElementIsIndirectlyRenderedUserInterface = (1 << 0),
1.173 + /**
1.174 + * Directly Render User Interface, i.e. rendering where Window
1.175 + * Server does not see the graphics commands, as is the case for
1.176 + * Direct Screen Access clients.
1.177 + */
1.178 + EElementIsDirectlyRenderedUserInterface = (1 << 1),
1.179 + /**
1.180 + * Reserved values for future Render Stage Plug-in usage
1.181 + */
1.182 + EElementRenderStageReserved = (1 << 2)
1.183 + };
1.184 +
1.185 + /**
1.186 + * Amount of rotation of pixel data to apply to the Image Source
1.187 + * to obtain the Target Image
1.188 + */
1.189 + enum TElementRotation
1.190 + {
1.191 + EElementAntiClockwise0 = 0, /** No rotation */
1.192 + EElementAntiClockwise90 = 1, /** 90 Degrees Anti-clockwise in target */
1.193 + EElementAntiClockwise180 = 2, /** 180 Degrees Anti-clockwise in target */
1.194 + EElementAntiClockwise270 = 3 /** 270 Degrees Anti-clockwise in target */
1.195 + };
1.196 +
1.197 +public:
1.198 + /**
1.199 + * @brief Set which portion of the image source is used.
1.200 + *
1.201 + * Set which rectangular portion of the connected image source
1.202 + * will be used when displaying this Element.
1.203 + *
1.204 + * @param aSrc The source rectangle of pixels from the connected Image Source.
1.205 + * This rectangle must not include any pixels outside the Image
1.206 + * Source. (0,0,0,0) means the entire size of the Image Source.
1.207 + * @pre An Image Source must have been connected; @see ConnectSurface()
1.208 + * @return One of the system-wide error codes.
1.209 + * KErrGeneral, if there is no image source connected.
1.210 + * KErrArgument, if the source rectangle includes pixels not in the
1.211 + * connected image source, or has negative width or height.
1.212 + * KErrNone, if successful.
1.213 + */
1.214 + virtual TInt SetSourceRectangle(const TRect& aSrc) = 0;
1.215 +
1.216 + /**
1.217 + * @brief Get the portion of the Image Source being used.
1.218 + *
1.219 + * Get the portion of the connected Image Source being used. The default
1.220 + * value is the entire extent of the connected Image Source.
1.221 + *
1.222 + * @param aSrc The source rectangle is updated with the current rectangular
1.223 + * region being used within the Image Source.
1.224 + * @pre An Image Source must have been connected; @see ConnectSurface()
1.225 + * @return One of the system-wide error codes.
1.226 + * KErrGeneral, if no Image Source has been connected.
1.227 + * KErrNone, if successful.
1.228 + */
1.229 + virtual TInt GetSourceRectangle(TRect& aSrc) = 0;
1.230 +
1.231 + /**
1.232 + * @brief Set the target area where the Image Source should appear.
1.233 + *
1.234 + * Set the target area in the target screen (or off-screen buffer)
1.235 + * where the Image Source should appear. Scaling may result if
1.236 + * the source and destination rectangles differ. A platform specific
1.237 + * algorithm will be used to interpolate the scaled image.
1.238 + *
1.239 + * @param aDest The destination rectangle in the target.
1.240 + * @pre An Image Source must have been connected; @see ConnectSurface()
1.241 + * @return One of the system-wide error codes.
1.242 + * KErrGeneral, if there is no image source connected.
1.243 + * KErrArgument, if the destination rectangle has negative width or
1.244 + * height.
1.245 + * KErrNone, if successful.
1.246 + */
1.247 + virtual TInt SetDestinationRectangle(const TRect& aDest) = 0;
1.248 +
1.249 + /**
1.250 + * @brief Get the target area where the Image Source would appear.
1.251 + *
1.252 + * Get the target area where the Image Source would appear. The default
1.253 + * value is at (0,0) sized to the Image Source clipped to the size
1.254 + * of the target.
1.255 + *
1.256 + * @param aDest The destination rectangle is updated with the current
1.257 + * region used in the target screen.
1.258 + * @pre An Image Source must have been connected; @see ConnectSurface()
1.259 + * @return One of the system-wide error codes.
1.260 + * KErrGeneral, if no Image Source has been connected.
1.261 + * KErrNone, if successful.
1.262 + */
1.263 + virtual TInt GetDestinationRectangle(TRect& aDest) const = 0;
1.264 +
1.265 + /**
1.266 + * @brief Clip the target area where the Image Source would appear.
1.267 + *
1.268 + * Set clipping area where the Image Source would appear. The default
1.269 + * value is the area of the target screen.
1.270 + *
1.271 + * @param aDestClipRect The clipping rectangle in the target. (0,0,0,0)
1.272 + * means the entire size of the Target Screen.
1.273 + * @return One of the system-wide error codes.
1.274 + * KErrGeneral, if no Image Source has been connected.
1.275 + * KErrArgument, if the rectangle has negative width or height
1.276 + * KErrNone, if successful.
1.277 + */
1.278 + virtual TInt SetDestinationClippingRect(const TRect& aDestClipRect) = 0;
1.279 +
1.280 + /**
1.281 + * @brief Get the clipping area in the target.
1.282 + *
1.283 + * Get the clipping area which limits where in the target screen the
1.284 + * element may appear.
1.285 + *
1.286 + * @param aDestClipRect The clipping rectangle is updated with the current
1.287 + * clipping area used in the target screen.
1.288 + * @return One of the system-wide error codes. KErrGeneral means no Image
1.289 + * Source has been connected. KErrNone is returned upon success.
1.290 + */
1.291 + virtual TInt GetDestinationClippingRect(TRect& aDestClipRect) const = 0;
1.292 +
1.293 + /**
1.294 + * @brief Set the rotation that should appear in the target for the
1.295 + * Image Source.
1.296 + *
1.297 + * Set the rotation which describes how the connected Image Source
1.298 + * should be rotated to appear in the target.
1.299 + *
1.300 + * @param aElementRotation The amount of rotation in the target.
1.301 + * @pre An Image Source must have been connected; @see ConnectSurface()
1.302 + * @return One of the system-wide error codes.
1.303 + * KErrGeneral, if no Image Source has been connected.
1.304 + * KErrArgument, if an out of bounds rotation value has been
1.305 + * supplied.
1.306 + * KErrNone, if successful.
1.307 + */
1.308 + virtual TInt SetSourceRotation(const TElementRotation aElementRotation) = 0;
1.309 +
1.310 + /**
1.311 + * @brief Get the pending rotation setting as it would appear in the target.
1.312 + *
1.313 + * Get the pending rotation setting for the connected Image Source.
1.314 + * By default, the rotation is EElementAntiClockwise0 and this is returned
1.315 + * if there is no connected Image Source.
1.316 + *
1.317 + * @return The pending rotation setting.
1.318 + */
1.319 + virtual TElementRotation SourceRotation() const = 0 ;
1.320 +
1.321 + /**
1.322 + * @brief Set flipping about the image horizontal centerline.
1.323 + *
1.324 + * Set the pending flipping setting for the connected Image Source.
1.325 + * When flipped, the Image Source appears in the target as inverted
1.326 + * about its horizontal centerline. This effect can be combined
1.327 + * with rotation effects.
1.328 + * By default, the Image Source is not flipped.
1.329 + *
1.330 + * @param aFlip If ETrue, the connected Image is flipped, else
1.331 + * it is not flipped.
1.332 + * @pre An Image Source must have been connected; @see ConnectSurface()
1.333 + * @return One of the system-wide error codes.
1.334 + * KErrGeneral, if no Image Source has been connceted.
1.335 + * KErrNotSupported, if the platform does not support the feature.
1.336 + * KErrNone, if successful.
1.337 + */
1.338 + virtual TInt SetSourceFlipping(const TBool aFlip) = 0;
1.339 +
1.340 + /**
1.341 + * @brief Get the pending flipping setting.
1.342 + *
1.343 + * Get the pending flipping setting for the connected Image Source.
1.344 + * By default, the image is not flipped.
1.345 + *
1.346 + * @return The pending flipping setting. If no Image is connected, return
1.347 + * EFalse.
1.348 + */
1.349 + virtual TBool SourceFlipping() const = 0 ;
1.350 +
1.351 + /**
1.352 + * @brief Set Target Renderer Flags associated with this Element
1.353 + *
1.354 + * Set the Target Renderer flags to be associated with this Element.
1.355 + *
1.356 + * @note Flags which are not recognised by an implementation must
1.357 + * be kept to allow the interface to be extended in a
1.358 + * compatible manner.
1.359 + * @param aTargetRendererFlags Flags to set for Target Renderer;
1.360 + * @see TElementTargetRendererFlags
1.361 + * @return One of the system-wide error codes.
1.362 + * KErrNotSupported, if the platform does not support the given
1.363 + * flags.
1.364 + * KErrArgument, if incompatible flag settings have been made.
1.365 + * KErrNone, if successful.
1.366 + */
1.367 + virtual TInt SetTargetRendererFlags(const TUint32& aTargetRendererFlags) = 0;
1.368 +
1.369 + /**
1.370 + * @brief Set Render Stage Flags associated with this Element
1.371 + *
1.372 + * Set the Render Stage flags to be associated with this Element.
1.373 + *
1.374 + * @note Flags which are not recognised by an implementation must
1.375 + * be kept to allow the interface to be extended in a
1.376 + * compatible manner.
1.377 + * @param aRenderStageFlags Flags to set for Render Stage Plug-ins;
1.378 + * @see TElementRenderStageFlags
1.379 + * @return One of the system-wide error codes.
1.380 + * KErrNotSupported, if the platform does not support the given
1.381 + * flags.
1.382 + * KErrArgument, if incompatible flag settings have been requested.
1.383 + * KErrNone, if successful.
1.384 + */
1.385 + virtual TInt SetRenderStageFlags(const TUint32& aRenderStageFlags) = 0;
1.386 +
1.387 + /**
1.388 + * @brief Get Target Renderer Flags associated with this Element
1.389 + *
1.390 + * Get the Target Renderer flags associated with this Element.
1.391 + *
1.392 + * @note Flags which are not recognised by an implementation must
1.393 + * be kept to allow the interface to be extended in a
1.394 + * compatible manner.
1.395 + * @param aTargetRendererFlags Variable to receive TElementTargetRendererFlags
1.396 + */
1.397 + virtual void GetTargetRendererFlags(TUint32& aTargetRendererFlags) const = 0;
1.398 +
1.399 + /**
1.400 + * @brief Get Render Stage Flags associated with this Element
1.401 + *
1.402 + * Get the Render Stage flags associated with this Element.
1.403 + *
1.404 + * @note Flags which are not recognised by an implementation must
1.405 + * be kept to allow the interface to be extended in a
1.406 + * compatible manner.
1.407 + * @param aRenderStageFlags Variable to receive TElementRenderStageFlags
1.408 + */
1.409 + virtual void GetRenderStageFlags(TUint32& aRenderStageFlags) const = 0;
1.410 +
1.411 + /**
1.412 + * @brief Get the Element above this Element.
1.413 + *
1.414 + * Get the Element which is above this Element in the Pending Scene.
1.415 + * If the Element is the top-most element, NULL is returned. If the
1.416 + * Element is not in the Scene, NULL is returned.
1.417 + *
1.418 + * @return Element above, or NULL.
1.419 + */
1.420 + virtual MWsElement *ElementAbove() = 0;
1.421 +
1.422 + /**
1.423 + * @brief Get the Element below this Element.
1.424 + *
1.425 + * Get the Element which is below this Element in the Pending Scene.
1.426 + * If the Element is the bottom-most element, NULL is returned. If the
1.427 + * Element is not in the Scene, NULL is returned.
1.428 + *
1.429 + * @return Element below, or NULL.
1.430 + */
1.431 + virtual MWsElement *ElementBelow() = 0;
1.432 +
1.433 + /**
1.434 + * @brief Connect or re-Connect a Surface to this Element.
1.435 + *
1.436 + * Connect the given Surface to this Element, or re-Connect a new
1.437 + * Surface to this Element which already has a connected Surface.
1.438 + * The Element does not need to be in the Scene when this call is made.
1.439 + *
1.440 + * @note The Source Rectangle of the Element is updated to correspond
1.441 + * to match the Source Rectangle of the Surface. Thus any
1.442 + * prior Source Rectangle setting will be overwritten.
1.443 + *
1.444 + * @param aSurface Surface to connect to. If this is the Null
1.445 + * Surface, then the Source Rectangle of the
1.446 + * Element is set to (0,0,0,0).
1.447 + * @return One of the system-wide error codes.
1.448 + * KErrArgument, if supplied Surface cannot be connected. For
1.449 + * example the Element has a flag indicating it has an Alpha
1.450 + * Channel but the Surface does not.
1.451 + * KErrNone, if successful.
1.452 + */
1.453 + virtual TInt ConnectSurface(const TSurfaceId& aSurface) = 0;
1.454 +
1.455 + /**
1.456 + * @brief Get the Surface connected to this Element
1.457 + *
1.458 + * @return The Surface Identifier of the Connected Surface. This
1.459 + * identifier may represent the Null Surface Id if there
1.460 + * was no Surface connected in the Pending Scene for this
1.461 + * Element.
1.462 + */
1.463 + virtual const TSurfaceId& ConnectedSurface() const = 0;
1.464 +
1.465 + /**
1.466 + * @brief Set the Global Alpha Transparency value
1.467 + *
1.468 + * Sets the Global Alpha Transparency value for this Element. Elements
1.469 + * are by default fully opaque, represented by opacity 255. On platforms
1.470 + * that support it, the Alpha Transparency value can be reduced down
1.471 + * to 0 representing fully transparent. The purpose of this is to
1.472 + * allow the fading in and fading out of Elements into the Scene.
1.473 + *
1.474 + * @param aAlpha The Alpha Transparency value desired. Values
1.475 + * are clamped to be within the range [0, 255] where 0
1.476 + * represents fully transparent, and 255 represents
1.477 + * fully opaque.
1.478 + * @note This setting has no effect unless the flag
1.479 + * Target Renderer flag EElementTransparencyGlobalAlpha
1.480 + * is set; @see SetTargetRendererFlags()
1.481 + * @note Out of range values are clamped silently, and do not cause
1.482 + * error conditions.
1.483 + * @return One of the system-wide error codes.
1.484 + * KErrNotSupported, if the supplied value, once clamped, is not
1.485 + * supported on the platform.
1.486 + * KErrNone, if successful.
1.487 + */
1.488 + virtual TInt SetGlobalAlpha(const TInt aAlpha) = 0;
1.489 +
1.490 + /**
1.491 + * @brief Get the Global Alpha Transparency value
1.492 + *
1.493 + * Gets the Global Alpha Transparency value for this Element. Elements
1.494 + * are by default fully opaque, represented by opacity 255.
1.495 + *
1.496 + * @param aAlpha Variable which receives the Global Alpha Transparency
1.497 + * value.
1.498 + */
1.499 + virtual void GlobalAlpha(TInt& aAlpha) const = 0;
1.500 + };
1.501 +#endif // WSELEMENT_H