// 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