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