|
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 // |
|
15 |
|
16 /** |
|
17 @file |
|
18 @publishedPartner |
|
19 @prototype |
|
20 */ |
|
21 |
|
22 #ifndef FBSRASTERIZER_H |
|
23 #define FBSRASTERIZER_H |
|
24 |
|
25 #include <e32base.h> |
|
26 #include <gdi.h> |
|
27 |
|
28 /** CFbsRasterizer represents the system's rasterizer that has the ability to generate |
|
29 standard pixel data from data stored in proprietary formats. |
|
30 |
|
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. |
|
35 |
|
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. |
|
39 |
|
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. |
|
49 |
|
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. |
|
55 |
|
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 }; |
|
82 |
|
83 public: |
|
84 /** Create a new rasterizer. |
|
85 */ |
|
86 IMPORT_C static CFbsRasterizer* New(); |
|
87 |
|
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. |
|
92 |
|
93 @see EndBitmap() |
|
94 @see ScanLine() |
|
95 |
|
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(). |
|
108 |
|
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; |
|
114 |
|
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(). |
|
119 |
|
120 @see BeginBitmap() |
|
121 @see ScanLine() |
|
122 |
|
123 @param aBitmapId A unique identifier for the bitmap that is being unregistered. |
|
124 |
|
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; |
|
131 |
|
132 /** Requests a pointer to a scanline containing pixel data for a specified bitmap. |
|
133 |
|
134 @see BeginBitmap() |
|
135 @see EndBitmap() |
|
136 |
|
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. |
|
140 |
|
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. |
|
146 |
|
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; |
|
159 |
|
160 /** Returns a pointer to an extension interface. Allows extension of the CFbsRasterizer |
|
161 interface without breaking compatibility with existing implementations. |
|
162 |
|
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. |
|
165 |
|
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. |
|
171 |
|
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 }; |
|
177 |
|
178 /** The UID3 value in the compound identifier of the extended bitmap rasterizer DLL. |
|
179 */ |
|
180 const TUid KFbsRasterizerLibraryUid = {0x10285EAE}; |
|
181 |
|
182 #endif // FBSRASTERIZER_H |