CFbsRasterizer Class Reference

class CFbsRasterizer : public CBase

CFbsRasterizer represents the system's rasterizer that has the ability to generate standard pixel data from data stored in proprietary formats.

Multiple formats of proprietary data may be supported by the rasterizer. Formats are identified by UID. Support for formats is platform-specific and controlled by the platform vendor. The OS does not mandate that the system's rasterizer must support any specific data formats.

CFbsRasterizer is used solely by the Font & Bitmap Server component to simulate pixel access to extended bitmaps, i.e. bitmaps created using CFbsBitmap::CreateExtendedBitmap(). CFbsRasterizer is not intended for use by applications.

CFbsRasterizer is intended to be implemented by licensees through derivation from the abstract base class. If a licensee wishes to provide a rasterizer implementation, they should create a rasterizer dll that is exported as "fbsrasterizer.dll" and include it in their ROM. Note that a stub rasterizer is exported to "fbsrasterizer.dll" and is loaded by the Font & Bitmap server by default to prevent a rogue dll being loaded in the rasterizer's place from the C:\ drive or removable media. Licensees can override this by using the following build option: -DFBSRASTERIZER_DLL <rasterizer_dll_name> where <rasterizer_dll_name> is the name of the licensee rasterizer dll.

CFbsRasterizer will be instantiated in client threads that use the Font & Bitmap Server, including the Window Server's main thread. Therefore the implementation of the rasterizer must be robust. Rasterizer functions should never lead to process termination, even when invalid proprietary data is passed in. Instances of CFbsRasterizer are not intended to be shared between threads.

The CFbsRasterizer interface has been designed to allow the implementation to optimise certain access patterns for performance. For example, the implementation might prepare for sequential access to a region by rasterizing the entire region inside a private scratch buffer. A further opportunity would be to take advantage of the immutability of extended bitmaps by maintaining rasterized scratch buffers for the most recently used bitmaps.

Inherits from

Nested Classes and Structures

Member Functions Documentation

BeginBitmap(TInt64, const TBitmapDesc &, const TRegion *)

void BeginBitmap ( TInt64 aBitmapId,
const TBitmapDesc & aBitmapDesc,
const TRegion * aRegionOfInterest
) [pure virtual]

Registers an extended bitmap so that scanline access requests can be made on the bitmap. The same bitmap may be registered multiple times. The rasterizer instance must be able to maintain at least 3 registrations simultaneously. This is to support BitGDI drawing operations that make use of 3 source bitmaps.

EndBitmap() ScanLine()
Post-condition
The rasterizer is able to satisfy scanline requests for the bitmap identified by aBitmapId.

Parameters

TInt64 aBitmapId A unique identifier for the bitmap that is being registered. This identifier is never reused for other bitmaps.
const TBitmapDesc & aBitmapDesc A full description of the bitmap including the proprietary data. The description and proprietary data associated with a particular value of aBitmapId never changes. This allows the implementation to cache this information even after a bitmap has been unregistered.
const TRegion * aRegionOfInterest The region within which scanline access requests will be made, if known. A value of NULL implies that the user does not have any useful information to contribute and the implementation must be prepared to accept scanline requests anywhere inside the bitmap. If the rasterizer uses the region of interest after the call to BeginBitmap() then it must make a copy of it, since the region pointed to by aRegionOfInterest is valid only during the call to BeginBitmap().

EndBitmap(TInt64)

void EndBitmap ( TInt64 aBitmapId ) [pure virtual]

Unregisters a bitmap previously registered using BeginBitmap() . The rasterizer should access the proprietary data of a bitmap only between calls to BeginBitmap() and EndBitmap() , since a bitmap can be destroyed without notifying the rasterizer after the call to EndBitmap() .

BeginBitmap() ScanLine()
Pre-condition
aBitmapId is registered with this rasterizer.
Post-condition
aBitmapId is unregistered once from this rasterizer. If all registrations for aBitmapId have been removed, scanline access for aBitmapId is no longer supported and any scanline pointers previously returned by ScanLine() become invalid.

Parameters

TInt64 aBitmapId A unique identifier for the bitmap that is being unregistered.

GetInterface(TUid, TAny *&)

TInt GetInterface ( TUid aInterfaceId,
TAny *& aInterface
) [pure virtual]

Returns a pointer to an extension interface. Allows extension of the CFbsRasterizer interface without breaking compatibility with existing implementations.

Post-condition
If successful, KErrNone is returned and aInterface can be cast into a pointer to the M-class associated with the specified extension UID.

Parameters

TUid aInterfaceId A UID defined by the OS identifying a specific extension interface.
TAny *& aInterface A pointer that will be set to the extension interface.

New()

IMPORT_C CFbsRasterizer * New ( ) [static]

Create a new rasterizer.

ScanLine(TInt64, const TPoint &, TInt)

const TUint32 * ScanLine ( TInt64 aBitmapId,
const TPoint & aPixel,
TInt aLength
) [pure virtual]

Requests a pointer to a scanline containing pixel data for a specified bitmap.

BeginBitmap() EndBitmap()
Pre-condition
aBitmapId must be registered with this rasterizer. The sequence of pixels identified by aPixel and aLength must lie entirely inside the conceptual width and height of the bitmap, i.e. the bounds specified by the bitmap's TBitmapDesc::iSizeInPixels .
Post-condition
Any scanline address previously returned by this rasterizer is not guaranteed to be valid. If successful, the returned pointer references the start of a scanline buffer, the full length of which can hold an entire row of pixels. The pixel range within the scanline buffer specified by the user (aPixel.iX...aPixel.iX+aLength) will contain accurate pixel values.

Parameters

TInt64 aBitmapId The unique identifier of the bitmap to extract the scanline from.
const TPoint & aPixel An co-ordinate within the bitmap of the first pixel to retrieve.
TInt aLength The number of pixels to retrieve.