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