--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/windowing/windowserver/inc/Graphics/openwfc/wselement.h Tue Feb 02 01:47:50 2010 +0200
@@ -0,0 +1,498 @@
+// Copyright (c) 2009 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:
+// Interface for Scene Elements
+//
+//
+
+/**
+ @publishedPartner
+ @prototype
+*/
+
+#ifndef WSELEMENT_H
+#define WSELEMENT_H
+
+#include <w32std.h>
+#include <graphics/wsgraphicdrawerinterface.h>
+#include <graphics/surface.h>
+
+/**
+ * @brief Window Server Scene Element Interface Definition
+ *
+ * This interface allows Image Sources to be associated with meta-data
+ * to define how the Image Source must be presented within a Scene.
+ *
+ * For a conceptual overview of Scenes, refer to the @c MWsScene Interface.
+ *
+ * The following aspects of Image Source presentation may be controlled:
+ * @li Source rectangular region
+ * @li Destination rectangular region
+ * @li Rotation and flipping
+ * @li Opacity
+ * @li Relative z-order (ordinal position)
+ * @li Tags to descriminate the UI from other Elements
+ *
+ * All co-ordinates are pixels offsets from (0,0) representing the
+ * top level of the Image Source or Destination Target (the screen
+ * or an off-screen buffer representing the screen), moving rightwards
+ * and downwards in x and y co-ordinates respectively.
+ *
+ * Elements can be marked with flags. There are two different consumers
+ * of flags: Target Renderers and Render Stage Plug-ins.
+ *
+ * Target Renderers are sub-systems which actually do composition and
+ * rendering on a particular display device or off-screen buffer.
+ * The EElementTransparencySource flag tells the Target Renderer that
+ * alpha blending must use the alpha channel in the Surface connected to
+ * the Element.
+ *
+ * On the other hand, Render Stage Plug-ins need flags to implement
+ * specific policies such as "UI always on top". To facilitate this,
+ * Elements have a EElementIsIndirectlyRenderedUserInterface or a
+ * EElementIsDirectlyRenderedUserInterface optionally set. This
+ * flag allows Render Stage Plug-ins to keep the relative z-order
+ * of Elements aligned to this policy.
+ *
+ * To allow compatible updates to be made to flags, all Render Stage
+ * Plug-ins must preserve the flags in Elements which they do not operate
+ * upon. Target Renderers may ignore the flags in Elements which they
+ * do not operate on.
+ *
+ * <h2>Intial State</h2>
+ *
+ * The initial state for an Element is:
+ * @li Fully opaque
+ * @li No rotation, nor flipped
+ * @li Not part of the Committed Scene
+ * @li No connected Surface
+ * @li All flags reset
+ * @li Local error value set as KErrNone
+ * @li Source Rectangle and Destination Rectangle is (0,0,0,0)
+ * @il Destination Clipping Rectangle is (0,0,0,0)
+ *
+ * When an Image Source is connected, the initial state becomes:
+ * @li Source Rectangle is the extent of the Image Source
+ * @li Destination Rectangle is set at origin (0,0), whose sized equals the
+ * Image Source size truncated the the target screen size.
+ * @li Destination Clipping Rectangle is (0,0,0,0) to represent the entire
+ * area of the target screen.
+ *
+ * <h2>Special Rectangle Values</h2>
+ *
+ * Sometimes it is desirable to reset a Source, Destination, or Clipping
+ * Rectangle so that the actual value used matches the corresponding Source
+ * Image or Target Screen size. In such cases rectangle (0,0,0,0) is used to
+ * represent this.
+ *
+ * <h2>Extending this interface</h2>
+ *
+ * This interface can be extended in two different ways
+ * @li Creating optional extension interfaces with
+ * MWsElement::MWsObjectProvider::ResolveObjectInterface()
+ * @li Defining new TElementFlags flag settings; Render Stage Plug-ins
+ * preserve the value of these across the Render Stage Pipeline.
+ *
+ * <h2>Committed Elements versus Pending Elements</h2>
+ *
+ * This interface allows Elements to be modified in terms of their
+ * own flag settings, and rotation, as well as their relative position
+ * with other Elements. Queries return the pending values for such
+ * Elements. Any modifications are marked Pending, and affect the Scene
+ * according to the rules described by "Rendering" in @c MWsScene.
+ *
+ * <h2>Order in which transformations are applied</h2>
+ *
+ * A number of different transformations may be specified for an Element.
+ * The order in which these are applied to arrive at the view seen in
+ * the target is:
+ * -# SetSourceRectangle (Cropping)
+ * -# SetSourceFlipping (Flipping)
+ * -# SetSourceRotation (Rotation)
+ * -# SetDestinationRectangle (Scaling and Positioning)
+ * -# SetDestinationClippingRectangle (Scaling and Positioning)
+ * -# SetGlobalAlpha (Blending)
+ */
+class MWsElement : public MWsObjectProvider
+ {
+public:
+
+ /**
+ * @brief Flags used by Target Renderers.
+ */
+ enum TElementTargetRendererFlags
+ {
+ /**
+ * Target renderer must treat the Element as Opaque.
+ */
+ EElementTransparencyNone = 0,
+ /**
+ * Target renderer must use the Global Alpha Transparency value
+ * from the Element
+ */
+ EElementTransparencyGlobalAlpha = (1 << 0),
+ /**
+ * Target renderer must use the Alpha Transparency Channel from
+ * the Element
+ */
+ EElementTransparencySource = (1 << 1),
+ /**
+ * Reserved flag value; this must not be set.
+ */
+ EElementTargetRendererReserved = (1 << 2)
+ };
+
+ /**
+ * @brief Flags used by Render Stages.
+ */
+ enum TElementRenderStageFlags
+ {
+ /**
+ * No flag value set for Render Stage Plug-in
+ */
+ EElementRenderStageNone = 0,
+ /**
+ * Indirectly Rendered User Interface, i.e. rendering via
+ * MWsGraphicsContext calls originating from client CWindowGc
+ * commands
+ */
+ EElementIsIndirectlyRenderedUserInterface = (1 << 0),
+ /**
+ * Directly Render User Interface, i.e. rendering where Window
+ * Server does not see the graphics commands, as is the case for
+ * Direct Screen Access clients.
+ */
+ EElementIsDirectlyRenderedUserInterface = (1 << 1),
+ /**
+ * Reserved values for future Render Stage Plug-in usage
+ */
+ EElementRenderStageReserved = (1 << 2)
+ };
+
+ /**
+ * Amount of rotation of pixel data to apply to the Image Source
+ * to obtain the Target Image
+ */
+ enum TElementRotation
+ {
+ EElementAntiClockwise0 = 0, /** No rotation */
+ EElementAntiClockwise90 = 1, /** 90 Degrees Anti-clockwise in target */
+ EElementAntiClockwise180 = 2, /** 180 Degrees Anti-clockwise in target */
+ EElementAntiClockwise270 = 3 /** 270 Degrees Anti-clockwise in target */
+ };
+
+public:
+ /**
+ * @brief Set which portion of the image source is used.
+ *
+ * Set which rectangular portion of the connected image source
+ * will be used when displaying this Element.
+ *
+ * @param aSrc The source rectangle of pixels from the connected Image Source.
+ * This rectangle must not include any pixels outside the Image
+ * Source. (0,0,0,0) means the entire size of the Image Source.
+ * @pre An Image Source must have been connected; @see ConnectSurface()
+ * @return One of the system-wide error codes.
+ * KErrGeneral, if there is no image source connected.
+ * KErrArgument, if the source rectangle includes pixels not in the
+ * connected image source, or has negative width or height.
+ * KErrNone, if successful.
+ */
+ virtual TInt SetSourceRectangle(const TRect& aSrc) = 0;
+
+ /**
+ * @brief Get the portion of the Image Source being used.
+ *
+ * Get the portion of the connected Image Source being used. The default
+ * value is the entire extent of the connected Image Source.
+ *
+ * @param aSrc The source rectangle is updated with the current rectangular
+ * region being used within the Image Source.
+ * @pre An Image Source must have been connected; @see ConnectSurface()
+ * @return One of the system-wide error codes.
+ * KErrGeneral, if no Image Source has been connected.
+ * KErrNone, if successful.
+ */
+ virtual TInt GetSourceRectangle(TRect& aSrc) = 0;
+
+ /**
+ * @brief Set the target area where the Image Source should appear.
+ *
+ * Set the target area in the target screen (or off-screen buffer)
+ * where the Image Source should appear. Scaling may result if
+ * the source and destination rectangles differ. A platform specific
+ * algorithm will be used to interpolate the scaled image.
+ *
+ * @param aDest The destination rectangle in the target.
+ * @pre An Image Source must have been connected; @see ConnectSurface()
+ * @return One of the system-wide error codes.
+ * KErrGeneral, if there is no image source connected.
+ * KErrArgument, if the destination rectangle has negative width or
+ * height.
+ * KErrNone, if successful.
+ */
+ virtual TInt SetDestinationRectangle(const TRect& aDest) = 0;
+
+ /**
+ * @brief Get the target area where the Image Source would appear.
+ *
+ * Get the target area where the Image Source would appear. The default
+ * value is at (0,0) sized to the Image Source clipped to the size
+ * of the target.
+ *
+ * @param aDest The destination rectangle is updated with the current
+ * region used in the target screen.
+ * @pre An Image Source must have been connected; @see ConnectSurface()
+ * @return One of the system-wide error codes.
+ * KErrGeneral, if no Image Source has been connected.
+ * KErrNone, if successful.
+ */
+ virtual TInt GetDestinationRectangle(TRect& aDest) const = 0;
+
+ /**
+ * @brief Clip the target area where the Image Source would appear.
+ *
+ * Set clipping area where the Image Source would appear. The default
+ * value is the area of the target screen.
+ *
+ * @param aDestClipRect The clipping rectangle in the target. (0,0,0,0)
+ * means the entire size of the Target Screen.
+ * @return One of the system-wide error codes.
+ * KErrGeneral, if no Image Source has been connected.
+ * KErrArgument, if the rectangle has negative width or height
+ * KErrNone, if successful.
+ */
+ virtual TInt SetDestinationClippingRect(const TRect& aDestClipRect) = 0;
+
+ /**
+ * @brief Get the clipping area in the target.
+ *
+ * Get the clipping area which limits where in the target screen the
+ * element may appear.
+ *
+ * @param aDestClipRect The clipping rectangle is updated with the current
+ * clipping area used in the target screen.
+ * @return One of the system-wide error codes. KErrGeneral means no Image
+ * Source has been connected. KErrNone is returned upon success.
+ */
+ virtual TInt GetDestinationClippingRect(TRect& aDestClipRect) const = 0;
+
+ /**
+ * @brief Set the rotation that should appear in the target for the
+ * Image Source.
+ *
+ * Set the rotation which describes how the connected Image Source
+ * should be rotated to appear in the target.
+ *
+ * @param aElementRotation The amount of rotation in the target.
+ * @pre An Image Source must have been connected; @see ConnectSurface()
+ * @return One of the system-wide error codes.
+ * KErrGeneral, if no Image Source has been connected.
+ * KErrArgument, if an out of bounds rotation value has been
+ * supplied.
+ * KErrNone, if successful.
+ */
+ virtual TInt SetSourceRotation(const TElementRotation aElementRotation) = 0;
+
+ /**
+ * @brief Get the pending rotation setting as it would appear in the target.
+ *
+ * Get the pending rotation setting for the connected Image Source.
+ * By default, the rotation is EElementAntiClockwise0 and this is returned
+ * if there is no connected Image Source.
+ *
+ * @return The pending rotation setting.
+ */
+ virtual TElementRotation SourceRotation() const = 0 ;
+
+ /**
+ * @brief Set flipping about the image horizontal centerline.
+ *
+ * Set the pending flipping setting for the connected Image Source.
+ * When flipped, the Image Source appears in the target as inverted
+ * about its horizontal centerline. This effect can be combined
+ * with rotation effects.
+ * By default, the Image Source is not flipped.
+ *
+ * @param aFlip If ETrue, the connected Image is flipped, else
+ * it is not flipped.
+ * @pre An Image Source must have been connected; @see ConnectSurface()
+ * @return One of the system-wide error codes.
+ * KErrGeneral, if no Image Source has been connceted.
+ * KErrNotSupported, if the platform does not support the feature.
+ * KErrNone, if successful.
+ */
+ virtual TInt SetSourceFlipping(const TBool aFlip) = 0;
+
+ /**
+ * @brief Get the pending flipping setting.
+ *
+ * Get the pending flipping setting for the connected Image Source.
+ * By default, the image is not flipped.
+ *
+ * @return The pending flipping setting. If no Image is connected, return
+ * EFalse.
+ */
+ virtual TBool SourceFlipping() const = 0 ;
+
+ /**
+ * @brief Set Target Renderer Flags associated with this Element
+ *
+ * Set the Target Renderer flags to be associated with this Element.
+ *
+ * @note Flags which are not recognised by an implementation must
+ * be kept to allow the interface to be extended in a
+ * compatible manner.
+ * @param aTargetRendererFlags Flags to set for Target Renderer;
+ * @see TElementTargetRendererFlags
+ * @return One of the system-wide error codes.
+ * KErrNotSupported, if the platform does not support the given
+ * flags.
+ * KErrArgument, if incompatible flag settings have been made.
+ * KErrNone, if successful.
+ */
+ virtual TInt SetTargetRendererFlags(const TUint32& aTargetRendererFlags) = 0;
+
+ /**
+ * @brief Set Render Stage Flags associated with this Element
+ *
+ * Set the Render Stage flags to be associated with this Element.
+ *
+ * @note Flags which are not recognised by an implementation must
+ * be kept to allow the interface to be extended in a
+ * compatible manner.
+ * @param aRenderStageFlags Flags to set for Render Stage Plug-ins;
+ * @see TElementRenderStageFlags
+ * @return One of the system-wide error codes.
+ * KErrNotSupported, if the platform does not support the given
+ * flags.
+ * KErrArgument, if incompatible flag settings have been requested.
+ * KErrNone, if successful.
+ */
+ virtual TInt SetRenderStageFlags(const TUint32& aRenderStageFlags) = 0;
+
+ /**
+ * @brief Get Target Renderer Flags associated with this Element
+ *
+ * Get the Target Renderer flags associated with this Element.
+ *
+ * @note Flags which are not recognised by an implementation must
+ * be kept to allow the interface to be extended in a
+ * compatible manner.
+ * @param aTargetRendererFlags Variable to receive TElementTargetRendererFlags
+ */
+ virtual void GetTargetRendererFlags(TUint32& aTargetRendererFlags) const = 0;
+
+ /**
+ * @brief Get Render Stage Flags associated with this Element
+ *
+ * Get the Render Stage flags associated with this Element.
+ *
+ * @note Flags which are not recognised by an implementation must
+ * be kept to allow the interface to be extended in a
+ * compatible manner.
+ * @param aRenderStageFlags Variable to receive TElementRenderStageFlags
+ */
+ virtual void GetRenderStageFlags(TUint32& aRenderStageFlags) const = 0;
+
+ /**
+ * @brief Get the Element above this Element.
+ *
+ * Get the Element which is above this Element in the Pending Scene.
+ * If the Element is the top-most element, NULL is returned. If the
+ * Element is not in the Scene, NULL is returned.
+ *
+ * @return Element above, or NULL.
+ */
+ virtual MWsElement *ElementAbove() = 0;
+
+ /**
+ * @brief Get the Element below this Element.
+ *
+ * Get the Element which is below this Element in the Pending Scene.
+ * If the Element is the bottom-most element, NULL is returned. If the
+ * Element is not in the Scene, NULL is returned.
+ *
+ * @return Element below, or NULL.
+ */
+ virtual MWsElement *ElementBelow() = 0;
+
+ /**
+ * @brief Connect or re-Connect a Surface to this Element.
+ *
+ * Connect the given Surface to this Element, or re-Connect a new
+ * Surface to this Element which already has a connected Surface.
+ * The Element does not need to be in the Scene when this call is made.
+ *
+ * @note The Source Rectangle of the Element is updated to correspond
+ * to match the Source Rectangle of the Surface. Thus any
+ * prior Source Rectangle setting will be overwritten.
+ *
+ * @param aSurface Surface to connect to. If this is the Null
+ * Surface, then the Source Rectangle of the
+ * Element is set to (0,0,0,0).
+ * @return One of the system-wide error codes.
+ * KErrArgument, if supplied Surface cannot be connected. For
+ * example the Element has a flag indicating it has an Alpha
+ * Channel but the Surface does not.
+ * KErrNone, if successful.
+ */
+ virtual TInt ConnectSurface(const TSurfaceId& aSurface) = 0;
+
+ /**
+ * @brief Get the Surface connected to this Element
+ *
+ * @return The Surface Identifier of the Connected Surface. This
+ * identifier may represent the Null Surface Id if there
+ * was no Surface connected in the Pending Scene for this
+ * Element.
+ */
+ virtual const TSurfaceId& ConnectedSurface() const = 0;
+
+ /**
+ * @brief Set the Global Alpha Transparency value
+ *
+ * Sets the Global Alpha Transparency value for this Element. Elements
+ * are by default fully opaque, represented by opacity 255. On platforms
+ * that support it, the Alpha Transparency value can be reduced down
+ * to 0 representing fully transparent. The purpose of this is to
+ * allow the fading in and fading out of Elements into the Scene.
+ *
+ * @param aAlpha The Alpha Transparency value desired. Values
+ * are clamped to be within the range [0, 255] where 0
+ * represents fully transparent, and 255 represents
+ * fully opaque.
+ * @note This setting has no effect unless the flag
+ * Target Renderer flag EElementTransparencyGlobalAlpha
+ * is set; @see SetTargetRendererFlags()
+ * @note Out of range values are clamped silently, and do not cause
+ * error conditions.
+ * @return One of the system-wide error codes.
+ * KErrNotSupported, if the supplied value, once clamped, is not
+ * supported on the platform.
+ * KErrNone, if successful.
+ */
+ virtual TInt SetGlobalAlpha(const TInt aAlpha) = 0;
+
+ /**
+ * @brief Get the Global Alpha Transparency value
+ *
+ * Gets the Global Alpha Transparency value for this Element. Elements
+ * are by default fully opaque, represented by opacity 255.
+ *
+ * @param aAlpha Variable which receives the Global Alpha Transparency
+ * value.
+ */
+ virtual void GlobalAlpha(TInt& aAlpha) const = 0;
+ };
+#endif // WSELEMENT_H