author sl@SLION-WIN7.fritz.box
Fri, 15 Jun 2012 03:10:57 +0200
changeset 0 bde4ae8d615e
permissions -rw-r--r--
First public contribution.
     1 // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
     2 // All rights reserved.
     3 // This component and the accompanying materials are made available
     4 // under the terms of "Eclipse Public License v1.0"
     5 // which accompanies this distribution, and is available
     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
     7 //
     8 // Initial Contributors:
     9 // Nokia Corporation - initial contribution.
    10 //
    11 // Contributors:
    12 //
    13 // Description:
    14 //
    16 /**
    17  @file
    18  @publishedPartner
    19  @prototype
    20 */
    22 #ifndef FBSRASTERIZER_H
    23 #define FBSRASTERIZER_H
    25 #include <e32base.h>
    26 #include <gdi.h>
    28 /** CFbsRasterizer represents the system's rasterizer that has the ability to generate 
    29 standard pixel data from data stored in proprietary formats. 
    31 Multiple formats of proprietary data may be supported by the rasterizer.  Formats are 
    32 identified by UID.  Support for formats is platform-specific and controlled 
    33 by the platform vendor.  The OS does not mandate that the system's rasterizer must 
    34 support any specific data formats.
    36 CFbsRasterizer is used solely by the Font & Bitmap Server component to simulate pixel 
    37 access to extended bitmaps, i.e. bitmaps created using CFbsBitmap::CreateExtendedBitmap().  
    38 CFbsRasterizer is not intended for use by applications.
    40 CFbsRasterizer is intended to be implemented by licensees through derivation from the 
    41 abstract base class.  If a licensee wishes to provide a rasterizer implementation, they 
    42 should create a rasterizer dll that is exported as "fbsrasterizer.dll" and include it in 
    43 their ROM. Note that a stub rasterizer is exported to "fbsrasterizer.dll" and is loaded
    44 by the Font & Bitmap server by default to prevent a rogue dll being loaded in the rasterizer's
    45 place from the C:\ drive or removable media. Licensees can override this by using the 
    46 following build option:
    47 -DFBSRASTERIZER_DLL <rasterizer_dll_name>
    48 where <rasterizer_dll_name> is the name of the licensee rasterizer dll. 
    50 CFbsRasterizer will be instantiated in client threads that use the Font & Bitmap Server, 
    51 including the Window Server's main thread.  Therefore the implementation of the rasterizer 
    52 must be robust.  Rasterizer functions should never lead to process termination, even 
    53 when invalid proprietary data is passed in.  Instances of CFbsRasterizer are not intended 
    54 to be shared between threads.
    56 The CFbsRasterizer interface has been designed to allow the implementation to optimise 
    57 certain access patterns for performance.  For example, the implementation might prepare 
    58 for sequential access to a region by rasterizing the entire region inside a private scratch 
    59 buffer.  A further opportunity would be to take advantage of the immutability of extended 
    60 bitmaps by maintaining rasterized scratch buffers for the most recently used bitmaps.  
    61  */
    62 class CFbsRasterizer : public CBase
    63     {
    64 public:
    65 	/** Helper class for storing information about a bitmap that is being registered
    66 	with the rasterizer.
    67 	 */
    68     class TBitmapDesc
    69         {
    70     public:
    71         /** The width and height in pixels to rasterize into. */
    72         TSize        iSizeInPixels;
    73         /** The display mode to rasterize into. */
    74         TDisplayMode iDispMode;
    75         /** The UID identifying the proprietary data format. */
    76         TUid         iDataType;
    77         /** A pointer to the proprietary data. */
    78         const TAny*  iData;
    79         /** The size in bytes of the proprietary data. */
    80         TInt         iDataSize;
    81         };
    83 public:
    84 	/** Create a new rasterizer.
    85 	 */
    86     IMPORT_C static CFbsRasterizer* New();
    88     /** Registers an extended bitmap so that scanline access requests can be made on 
    89     the bitmap. The same bitmap may be registered multiple times.  The rasterizer instance 
    90     must be able to maintain at least 3 registrations simultaneously.  This is to support 
    91     BitGDI drawing operations that make use of 3 source bitmaps.
    93     @see EndBitmap()
    94     @see ScanLine()
    96     @param aBitmapId A unique identifier for the bitmap that is being registered.  This 
    97     	identifier is never reused for other bitmaps.
    98     @param aBitmapDesc A full description of the bitmap including the proprietary data.  
    99     	The description and proprietary data associated with a particular value of aBitmapId 
   100     	never changes.  This allows the implementation to cache this information even after a 
   101     	bitmap has been unregistered.
   102     @param aRegionOfInterest The region within which scanline access requests will be made, 
   103     	if known.  A value of NULL implies that the user does not have any useful information 
   104     	to contribute and the implementation must be prepared to accept scanline requests 
   105     	anywhere inside the bitmap.  If the rasterizer uses the region of interest after the 
   106     	call to BeginBitmap() then it must make a copy of it, since the region pointed to by 
   107     	aRegionOfInterest is valid only during the call to BeginBitmap().
   109     @post The rasterizer is able to satisfy scanline requests for the bitmap identified by aBitmapId.
   110      */
   111     virtual void BeginBitmap(TInt64 aBitmapId,
   112                              const TBitmapDesc& aBitmapDesc,
   113                              const TRegion* aRegionOfInterest) = 0;
   115     /** Unregisters a bitmap previously registered using BeginBitmap().
   116     The rasterizer should access the proprietary data of a bitmap only between
   117     calls to BeginBitmap() and EndBitmap(), since a bitmap can be destroyed
   118     without notifying the rasterizer after the call to EndBitmap().
   120     @see BeginBitmap()
   121     @see ScanLine()
   123     @param aBitmapId A unique identifier for the bitmap that is being unregistered.
   125     @pre aBitmapId is registered with this rasterizer.
   126 	@post aBitmapId is unregistered once from this rasterizer. If all registrations for 
   127 		aBitmapId have been removed, scanline access for aBitmapId is no longer supported 
   128 		and any scanline pointers previously returned by ScanLine() become invalid.    
   129      */
   130     virtual void EndBitmap(TInt64 aBitmapId) = 0;
   132     /** Requests a pointer to a scanline containing pixel data for a specified bitmap.
   134     @see BeginBitmap()
   135     @see EndBitmap()
   137     @param aBitmapId The unique identifier of the bitmap to extract the scanline from.
   138     @param aPixel An co-ordinate within the bitmap of the first pixel to retrieve.
   139     @param aLength The number of pixels to retrieve.
   141     @return Returns a pointer to a valid scanline, or NULL if the rasterizer can not allocate 
   142     	enough memory to return the scanline. Note that the scanline returned is always the 
   143     	length of a full scanline, where the first pixel returned represents x-coordinate zero 
   144     	(not aPixel.iX), however the only pixels that are guaranteed to be valid in the returned
   145     	scanline are from x-coordinate aPixel.iX to x-coordinate aPixel.iX+aLength-1.
   147     @pre aBitmapId must be registered with this rasterizer. The sequence of pixels identified 
   148     	by aPixel and aLength must lie entirely inside the conceptual width and height of 
   149     	the bitmap, i.e. the bounds specified by the bitmap's TBitmapDesc::iSizeInPixels.
   150     @post Any scanline address previously returned by this rasterizer is not guaranteed to be 
   151     	valid. If successful, the returned pointer references the start of a scanline buffer, 
   152     	the full length of which can hold an entire row of pixels.  The pixel range within 
   153     	the scanline buffer specified by the user (aPixel.iX...aPixel.iX+aLength) will contain 
   154     	accurate pixel values.    
   155      */
   156     virtual const TUint32* ScanLine(TInt64 aBitmapId,
   157                                     const TPoint& aPixel,
   158                                     TInt aLength) = 0;    
   160     /** Returns a pointer to an extension interface.  Allows extension of the CFbsRasterizer 
   161     interface without breaking compatibility with existing implementations.
   163     @param aInterfaceId A UID defined by the OS identifying a specific extension interface.
   164     @param aInterface A pointer that will be set to the extension interface.
   166     @return KErrNone is returned if aInterface has been set correctly to the extension interface.   
   167     	KErrExtensionNotSupported is returned if the rasterizer does not support the extension 
   168     	interface specified by aExtensionId. 
   169     	KErrNoMemory is returned if the rasterizer supports the extension interface but 
   170     	there is not enough memory to use it.
   172     @post If successful, KErrNone is returned and aInterface can be cast into a pointer to 
   173     	the M-class associated with the specified extension UID.    
   174      */
   175     virtual TInt GetInterface(TUid aInterfaceId, TAny*& aInterface) = 0;    
   176     };
   178 /** The UID3 value in the compound identifier of the extended bitmap rasterizer DLL.
   179  */
   180 const TUid KFbsRasterizerLibraryUid = {0x10285EAE};
   182 #endif // FBSRASTERIZER_H