1 /*

     2 * Copyright (c) 2006-2007 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Defines interface for HUITK render surfaces. The rendering 

    15 *                surface is a destination where rendered graphics will 

    16 *                ultimately end up.

    17 *

    18 */

    19 

    20 

    21 

    22 #ifndef __HUIRENDERSURFACE_H__

    23 #define __HUIRENDERSURFACE_H__

    24 

    25 

    26 #include <e32base.h>

    27 

    28 

    29 /* Forward declarations. */

    30 class MHuiSegmentedTexture;

    31 class MHuiTargetBitmap;

    32 class CFbsBitGc;

    33 

    34 

    35 /**

    36  * The render surface is a destination where rendered graphics will ultimately

    37  * end up. This may be, e.g., the display frame buffer or a bitmap in memory.

    38  */

    39 class MHuiRenderSurface

    40     {

    41 public:

    42 

    43 	/** Render surface flags */

    44 	enum TFlags

    45     	{

    46     	EFlagNone =                            0x0,

    47 		/** Surface uses double buffering. */    	

    48 		EFlagUseDoubleBuffering =              0x1,

    49 		/** Surface uses dirty rects. */    	

    50     	EFlagUseDirtyRects =                   0x2,

    51     	/** Surface uses transformed clipping rects. */

    52     	EFlagUsetransformedClippingRects =     0x4,

    53     	/** Surface uses Symbian graphics context rects. */

    54     	EFlagUseSymbianGC =                    0x8

    55     	};

    56 

    57 public:

    58 

    59     /**

    60      * Virtual destructor.

    61      */

    62     IMPORT_C virtual ~MHuiRenderSurface();

    63     

    64     /**

    65      * Returns the flags of the render surface.

    66      * @return Flags.

    67      */

    68     virtual TUint Flags() const = 0;

    69     

    70     /**

    71      * Determines the location of the rendering surface on the screen.

    72      *

    73      * @param aOrigin  Top left corner coordinates returned here, in absolute screen

    74      *                 coordinates. The top left corner of the screen is (0, 0).

    75      *

    76      * @return  If location successfully determined, returns <code>ETrue</code>.

    77      *          If the surface is an off-screen surface, returns <code>EFalse</code>.

    78      */

    79     virtual TBool GetScreenOrigin(TPoint& aOrigin) const = 0;

    80 

    81     /**

    82      * Determines the size of the surface.

    83      *

    84      * @return  Size of the surface in pixels.

    85      */

    86     virtual TSize Size() const = 0;

    87 

    88     /**

    89      * Changes the size of the surface.

    90      *

    91      * @param aSize  Size of surface in pixels.

    92      */

    93     virtual void SetSizeL(const TSize& aSize) = 0;

    94 

    95     /**

    96      * Makes this the current rendering surface for any drawing operations.

    97      * Call CHuiStatic::SetCurrentRenderSurface().

    98      */

    99     virtual void MakeCurrent() = 0;

   100 

   101     /**

   102      * Swaps the back buffer to the front.

   103      */

   104     virtual void SwapBuffers() = 0;

   105 

   106     /**

   107      * Binds a texture to the surface to be used during subsequent drawing

   108      * operations.

   109      *

   110      * In practice, the texture is bound to the rendering context

   111      * of this render surface. When something is drawn in the surface's 

   112      * rendering context, the texture specified here is used.

   113      *

   114      * @param aTextureUnit Texture unit number to bind the texture to. Binding

   115      * to different units enables multitexturing, but using multiple texture

   116      * units (multitexturing) may not be supported.

   117      * @param aTexture The texture to be bound.

   118      * @param activeTextureSegment Index of the texture segment to be bound.

   119      * operations. 

   120      */

   121     virtual void BindTexture(TInt aTextureUnit,

   122                              const MHuiSegmentedTexture& aTexture,

   123                              TInt activeTextureSegment) = 0;

   124 

   125     /**

   126      * Handles change in surface visibility. This method is called if surface is either

   127      * hidden or shown.

   128      *

   129      * @param aIsVisible ETrue if surface becomes visible. EFalse if surface is hidden.

   130      */

   131     virtual void HandleVisibilityEvent(TBool aIsVisible) = 0;

   132 

   133     /**

   134     * Temporarily release the resources of this rendering surface. You

   135     * can call this method to free up resources related to the rendering surface,

   136     * for example when the display goes to background (ie. render surface is not needed).

   137     * @see RestoreL() 

   138     */

   139     virtual void Release() = 0;

   140     

   141     /**

   142     * Recreate any released resources of this rendering surface. You

   143     * can call this method to recreate resources related to rendering surface,

   144     * for example, when the display comes back to foreground (ie. becomes visible).

   145     * @see Release() 

   146     */

   147     virtual void RestoreL() = 0;

   148 

   149     /**

   150     * Handles change in the intended usage of display. Most render surfaces do not

   151     * have any special functionality for different display usage scenarios.

   152     */

   153     virtual void HandleDisplayUsageChangeL() = 0;

   154 

   155 

   156     /**

   157     * Sets the dirty region i.e. the rectangular area that needs to be updated.

   158     * 

   159     * Writing a real implementation for this might not be needed if the renderer

   160     * does not support dirty region handling.

   161     * 

   162     * @param aRect The rectangular area that is dirty

   163     */

   164     virtual void SetDirtyRect(const TRect& aRect) = 0;

   165     

   166     /**

   167      * Returns the back buffer bitmap.

   168      * 

   169      * Writing a real implementation for this might not be needed if the renderer

   170      * does not support symbian graphics context.

   171      *

   172      * @return  Back buffer bitmap.

   173      */

   174     virtual MHuiTargetBitmap* BackBuffer() = 0;

   175 

   176     /**

   177      * Provides expandability, helps keeping the binary compatibility. Since virtual

   178      * table is now exported and this class is dll derivable and the implementation

   179      * is more difficult to change, hence this method, which can provide additional

   180      * extension APIs.

   181      * 

   182      * @param aExtensionUid     UID, which is being used for recognizing the extension

   183      * @param aExtensionParams  Return pointer to the extension API, once recognized from the extension uid

   184      */

   185     virtual void RenderSurfaceExtension(const TUid& aExtensionUid, TAny** aExtensionParams) = 0;

   186     };

   187 

   188 

   189 #endif