|
1 // Copyright (c) 2005-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 CAMERAHISTOGRAM_H |
|
23 #define CAMERAHISTOGRAM_H |
|
24 |
|
25 #include <ecam.h> |
|
26 #include <gdi.h> |
|
27 |
|
28 #include <ecam/camerasnapshot.h> |
|
29 #include <ecamcapturecontrol.h> |
|
30 #include <ecamviewfinder.h> |
|
31 |
|
32 #include <ecam/ecamcommonuids.hrh> |
|
33 |
|
34 class MHistogramBuffer; |
|
35 class MCameraHistogram; |
|
36 class MCameraV2Histogram; |
|
37 |
|
38 class MImplementationFactory; |
|
39 |
|
40 /** |
|
41 The current Version of the TDirectHistogramParameters class. |
|
42 */ |
|
43 static const TUint KECamDirectHistogramParametersCurrentVersion = 1; |
|
44 |
|
45 /** |
|
46 @deprecated use MCaptureImageObserver, MCaptureVideoObserver, MDirectViewFinderObserver, and MClientViewFinderObserver |
|
47 which have callback functions which notify the client about availability of histogram data. These are sent when |
|
48 CCameraV2Histogram::StartHistogram() is called after CCameraV2Histogram::PrepareClientHistogramL(). If |
|
49 CCameraV2Histogram::PrepareClientHistogramL() is not called first then the callback returns KErrBadHandle. |
|
50 |
|
51 Uid used to identify the event that the request for histogram has completed. |
|
52 A callback to MCameraObserver2::HandleEvent() will occur when the histogram data is ready to be retrieved. |
|
53 If a call to StartHistogram() is made without a previous successful call to PrepareHistogramL() then the callback returns KErrBadHandle. |
|
54 */ |
|
55 static const TUid KUidECamEventCameraHistogram = {KUidECamEventHistogramUidValue}; |
|
56 |
|
57 /** |
|
58 This is the UID which is used to obtain the CCameraHistogram interface, via a call to CCamera::CustomInterface(). |
|
59 |
|
60 @see KECamHistogramUidValue |
|
61 @see CCamera::CCameraHistogram |
|
62 @deprecated use KECamV2HistogramUid |
|
63 */ |
|
64 static const TUid KECamHistogramUid = {KECamHistogramUidValue}; |
|
65 |
|
66 /** |
|
67 This class allows the client to get histogram data in a specified format for an image (for example, luminance based histogram, |
|
68 average colour value histogram, etc). |
|
69 |
|
70 The data generated can be fed to some exposure based algorithm, or directly displayed in the viewfinder. |
|
71 It also allows the client to get and set the properties of a histogram. |
|
72 |
|
73 The client selects histogram parameters calling PrepareHistogramL(). It can then start and stop |
|
74 receiving notifications from the ECam implementation by calling StartHistogramL() and StopHistogramL(). |
|
75 The client application using this API should provide MCameraObserver2 interface to be signalled, |
|
76 with event KUidECamEventCameraHistogram, when histogram data is available to be retrieved from |
|
77 the ECam implementation. |
|
78 The client can then retrieve the histogram data from the ECam implementation calling HistograDataL(). |
|
79 |
|
80 @note This class provides a standardised client interface for the camera histogram. Classes cannot be derived from it. |
|
81 |
|
82 @note If the class methods leave, the output type parameter value is not guaranteed to be valid. |
|
83 |
|
84 @publishedPartner |
|
85 @deprecated use CCamera::CCameraV2Histogram |
|
86 */ |
|
87 |
|
88 class CCamera::CCameraHistogram : public CBase |
|
89 { |
|
90 |
|
91 friend class CCamera; |
|
92 |
|
93 public: |
|
94 /** Supported histogram types. */ |
|
95 enum THistogramType |
|
96 { |
|
97 /** No histogram has been specified. */ |
|
98 EHistNone = 0x0000, |
|
99 /** Luminance based histogram. */ |
|
100 ELuminance = 0x0001, |
|
101 /** The histogram is based on the average value of all three RGB colour components. */ |
|
102 EAverageRGB = 0x0002, |
|
103 /** The histogram is based on the value of the red colour component. */ |
|
104 ERedComponent = 0x0004, |
|
105 /** The histogram is based on the value of the blue colour component. */ |
|
106 EBlueComponent = 0x0008, |
|
107 /** The histogram is based on the value of the green colour component. */ |
|
108 EGreenComponent = 0x0010 |
|
109 }; |
|
110 |
|
111 public: |
|
112 IMPORT_C static CCamera::CCameraHistogram* NewL(CCamera& aCamera); |
|
113 |
|
114 IMPORT_C TUint32 SupportedHistograms(); |
|
115 IMPORT_C TUint PrepareHistogramL(CCamera::CCameraHistogram::THistogramType aType); |
|
116 IMPORT_C TUint PrepareDSAHistogramL(CCamera::CCameraHistogram::THistogramType aType, const TPoint& aPosition, const TSize& aSize, const TRgb& aColor); |
|
117 |
|
118 IMPORT_C void StartHistogramL(TUint aHistHandle); |
|
119 IMPORT_C void StopHistogramL(TUint aHistHandle); |
|
120 IMPORT_C void DestroyHistogramL(TUint aHistHandle); |
|
121 |
|
122 IMPORT_C void GetActiveHistogramsL(RArray<TUint>& aActiveHistograms); |
|
123 IMPORT_C void UpdateDSAHistogramPropertiesL(TUint aHistHandle, const TPoint& aPosition, const TSize& aSize, const TRgb& aColor); |
|
124 IMPORT_C void GetDSAHistogramPropertiesL(TUint aHistHandle, TPoint& aPosition, TSize& aSize, TRgb& aColor); |
|
125 |
|
126 IMPORT_C MHistogramBuffer& HistogramDataL(); |
|
127 IMPORT_C MHistogramBuffer& HistogramDataL(TUint aHistHandle); |
|
128 |
|
129 IMPORT_C ~CCameraHistogram(); |
|
130 |
|
131 private: |
|
132 CCameraHistogram(CCamera& aOwner); |
|
133 void ConstructL(); |
|
134 |
|
135 private: |
|
136 CCamera& iOwner; |
|
137 MCameraHistogram* iImpl; // not owned |
|
138 }; |
|
139 |
|
140 /** |
|
141 This is the UID which is used to obtain the CCameraV2Histogram interface, via a call to CCamera::CustomInterface(). |
|
142 |
|
143 @publishedPartner |
|
144 @prototype |
|
145 */ |
|
146 static const TUid KECamV2HistogramUid = {KECamV2HistogramUidValue}; |
|
147 |
|
148 /** |
|
149 This class allows the client to get histogram data in a specified format for an image (for example, luminance based histogram, |
|
150 average colour value histogram, etc). |
|
151 |
|
152 Histogram may be created for still images, video, viewfinders and snapshot. Further different types of histogram may be |
|
153 created for any of the imaging modes. |
|
154 |
|
155 The data generated can be fed to some exposure based algorithm, or directly displayed on the screen. |
|
156 It also allows the client to get and set the properties of a histogram. |
|
157 |
|
158 The client selects histogram parameters calling PrepareClientHistogramL or PrepareDirectHistogramL. It can then start and |
|
159 stop receiving notifications from the ECam implementation by calling StartHistogram() and StopHistogram(). |
|
160 The client application using this API shall provide the interfaces: MCaptureImageObserver, MCaptureVideoObserver, |
|
161 MDirectViewFinderObserver and MClientViewFinderObserver in order to receive notifications about direct histogram display |
|
162 or client histogram data availablility. |
|
163 |
|
164 Implementation shall use MHistogramV2Buffer in order to provide client histogram data. |
|
165 |
|
166 @note This class provides a standardised client interface for the camera histogram. Classes cannot be derived from it. |
|
167 |
|
168 @note If the class methods leave, the output type parameter value is not guaranteed to be valid. |
|
169 |
|
170 @publishedPartner |
|
171 @prototype |
|
172 */ |
|
173 |
|
174 class CCamera::CCameraV2Histogram : public CBase |
|
175 { |
|
176 |
|
177 friend class CCamera; |
|
178 friend CCamera::CCameraV2Histogram* CCamera::CCameraSnapshot::CreateHistogramHandleL() const; |
|
179 friend CCamera::CCameraV2Histogram* CCamera::CCameraImageCapture::CreateHistogramHandleL() const; |
|
180 friend CCamera::CCameraV2Histogram* CCamera::CCameraVideoCaptureControl::CreateHistogramHandleL() const; |
|
181 friend CCamera::CCameraV2Histogram* CCamera::CCameraV2DirectViewFinder::CreateHistogramHandleL() const; |
|
182 friend CCamera::CCameraV2Histogram* CCamera::CCameraClientViewFinder::CreateHistogramHandleL() const; |
|
183 |
|
184 public: |
|
185 /** |
|
186 Supported histogram types. |
|
187 The enumeration list may be extended in future. |
|
188 */ |
|
189 enum THistogramType |
|
190 { |
|
191 /** No histogram has been specified. */ |
|
192 EHistNone = 0x0000, |
|
193 /** Luminance based histogram. */ |
|
194 ELuminance = 0x0001, |
|
195 /** The histogram is based on the average value of all three RGB colour components. */ |
|
196 EAverageRGB = 0x0002, |
|
197 /** The histogram is based on the value of the red colour component. */ |
|
198 ERedComponent = 0x0004, |
|
199 /** The histogram is based on the value of the blue colour component. */ |
|
200 EBlueComponent = 0x0008, |
|
201 /** The histogram is based on the value of the green colour component. */ |
|
202 EGreenComponent = 0x0010, |
|
203 /** Qualitative Histogram to mark over exposed parts of image. */ |
|
204 EOverExposure = 0x0020, |
|
205 /** Qualitative Histogram to mark under exposed parts of image. */ |
|
206 EUnderExposure = 0x0040, |
|
207 }; |
|
208 |
|
209 /** |
|
210 Specifes the parameters necessary for a direct histogram. |
|
211 */ |
|
212 class TDirectHistogramParameters |
|
213 { |
|
214 public: |
|
215 IMPORT_C TDirectHistogramParameters(); |
|
216 |
|
217 IMPORT_C TUint Size() const; |
|
218 IMPORT_C TUint Version() const; |
|
219 |
|
220 private: |
|
221 //for future expansion |
|
222 TUint iSize:24; |
|
223 TUint iVersion:8; |
|
224 |
|
225 // reserved for future expansion |
|
226 TInt iReserved1; |
|
227 TInt iReserved2; |
|
228 TInt iReserved3; |
|
229 |
|
230 public: |
|
231 /** The type of histogram to be prepared. This must be one of the supported histogram types returned by |
|
232 SupportedHistograms(). */ |
|
233 THistogramType iHistogramType; |
|
234 /** The position on the screen (in pixels) where the histogram is to be displayed. */ |
|
235 TPoint iPosition; |
|
236 /** The size of histogram in pixels. */ |
|
237 TSize iHistogramSize; |
|
238 /** The colour and alpha blending with which the histogram will be displayed. */ |
|
239 TRgb iHistogramColor; |
|
240 /** The background color for the direct histogram. */ |
|
241 TRgb iBackgroundColor; |
|
242 }; |
|
243 |
|
244 public: |
|
245 |
|
246 IMPORT_C void GetSupportedHistogramsL(TUint& aSupportedHistogramType) const; |
|
247 IMPORT_C void GetDirectHistogramSupportInfoL(TBool& aIsDirectHistogramSupported) const; |
|
248 |
|
249 IMPORT_C void PrepareClientHistogramL(THistogramType aType); |
|
250 |
|
251 IMPORT_C void PrepareDirectHistogramL(const TDirectHistogramParameters& aDirectHistogramParameters); |
|
252 |
|
253 IMPORT_C void UpdateDirectHistogramPropertiesL(const TDirectHistogramParameters& aDirectHistogramParameters); |
|
254 IMPORT_C void GetDirectHistogramPropertiesL(TDirectHistogramParameters& aDirectHistogramParameters) const; |
|
255 |
|
256 IMPORT_C void StartHistogram(); |
|
257 IMPORT_C void StopHistogram(); |
|
258 |
|
259 IMPORT_C void GetHistogramStateL(TBool& aIsHistogramActive) const; |
|
260 |
|
261 IMPORT_C ~CCameraV2Histogram(); |
|
262 |
|
263 private: |
|
264 IMPORT_C static CCamera::CCameraV2Histogram* CreateL(CCamera& aCamera, MImplementationFactory& aImplFactory); |
|
265 |
|
266 CCameraV2Histogram(CCamera& aOwner); |
|
267 void ConstructL(const MImplementationFactory& aImplFactory); |
|
268 |
|
269 private: |
|
270 CCamera& iOwner; |
|
271 MCameraV2Histogram* iImpl; // not owned |
|
272 }; |
|
273 |
|
274 |
|
275 // |
|
276 // MHistogramBuffer // |
|
277 // |
|
278 |
|
279 /** |
|
280 This class is used to pass histogram data between the camera device and a client that implements MCameraObserver2. |
|
281 |
|
282 The buffer may contain multiple histograms. |
|
283 |
|
284 The class allows the client to access the data as a descriptor to a kernel chunk. |
|
285 |
|
286 @publishedPartner |
|
287 @deprecated use MHistogramV2Buffer |
|
288 */ |
|
289 class MHistogramBuffer |
|
290 { |
|
291 |
|
292 public: |
|
293 |
|
294 /** |
|
295 @deprecated Only one histogram is available per buffer in MHistogramV2Buffer |
|
296 |
|
297 Returns the number of histograms contained within the buffer. |
|
298 |
|
299 This value will not depend upon the number of images for which histograms are requested by the |
|
300 client, but on the number of histograms generated by the ECam implementation. |
|
301 In the case where the driving mode (bracket mode, video mode, etc.) returns more than one image or frame |
|
302 the ECam implementation may not generate histograms for every valid image or frame. This can happen, for example, |
|
303 if there are no changes in the histogram data or if there are performance problems. |
|
304 |
|
305 @return The number of histograms in the buffer. |
|
306 */ |
|
307 virtual TInt NumOfHistograms() = 0; |
|
308 |
|
309 /** |
|
310 @deprecated use CCamera::CCameraV2Histogram::THistogramType MHistogramV2Buffer::Type() |
|
311 |
|
312 Returns the type of histogram data that is available at the specified index within the histogram buffer. |
|
313 |
|
314 @param aIndex |
|
315 The index of the required histogram in the buffer. |
|
316 This must be between 0 and (NumOfHistograms() - 1). |
|
317 |
|
318 @leave KErrArgument if aIndex is not between 0 and (NumOfHistograms() - 1). |
|
319 |
|
320 @return The type of the histogram in the buffer at the given index. |
|
321 */ |
|
322 virtual CCamera::CCameraHistogram::THistogramType TypeL(TUint aIndex) = 0; |
|
323 |
|
324 /** |
|
325 @deprecated use TInt MHistogramV2Buffer::ElementSize() |
|
326 |
|
327 Returns the number of bits per histogram element value used to store the histogram data at a |
|
328 specified index within the histogram buffer. |
|
329 |
|
330 The number of bits per histogram element will be decided by the ECam implementation and it may vary |
|
331 for each histogram within the histogram buffer. |
|
332 |
|
333 @see NumOfElementsL() |
|
334 |
|
335 @param aIndex |
|
336 The index of the required histogram in the buffer. |
|
337 This must be between 0 and (NumOfHistograms() - 1). |
|
338 |
|
339 @leave KErrArgument if aIndex is not between 0 and (NumOfHistograms() - 1). |
|
340 |
|
341 @return The histogram element size in bits. |
|
342 */ |
|
343 virtual TInt ElementSizeL(TUint aIndex) = 0; |
|
344 |
|
345 /** |
|
346 @deprecated use TInt MHistogramV2Buffer::NumOfElements() |
|
347 |
|
348 Returns the number of elements in the histogram at a specified index within the histogram buffer. |
|
349 |
|
350 This value can be used along with the element size obtained by calling ElementSizeL(), to calculate |
|
351 the exact size of histogram data ( element-size x number-of-elements = histogram-size ). |
|
352 |
|
353 @param aIndex |
|
354 The index of the required histogram in the buffer. |
|
355 This must be between 0 and (NumOfHistograms() - 1). |
|
356 |
|
357 @leave KErrArgument if aIndex is not between 0 and (NumOfHistograms() - 1). |
|
358 |
|
359 @return The number of elements in the histogram. |
|
360 */ |
|
361 virtual TInt NumOfElementsL(TUint aIndex) = 0; |
|
362 |
|
363 /** |
|
364 @deprecated use TDesC8* MHistogramV2Buffer::DataL() |
|
365 |
|
366 Allows access to a given histogram in the histogram buffer via a descriptor. |
|
367 |
|
368 @param aIndex |
|
369 The index of the required histogram in the buffer. |
|
370 This must be between 0 and (NumOfHistograms() - 1). |
|
371 |
|
372 @leave KErrArgument if aIndex is not between 0 and (NumOfHistograms() - 1). |
|
373 |
|
374 @return A pointer to a descriptor containing the histogram data. |
|
375 */ |
|
376 virtual TDesC8* DataL(TUint aIndex) = 0; |
|
377 |
|
378 /** |
|
379 @deprecated use RChunk& MHistogramV2Buffer::ChunkL() |
|
380 |
|
381 Returns a handle to the chunk that contains the histogram data. |
|
382 The RChunk is exposed so that it can potentially be shared between multiple |
|
383 processes. |
|
384 @note The descriptor pointer returned by DataL() is effectively derived from this RChunk. |
|
385 |
|
386 @leave KErrNotSupported if the chunk is not available. |
|
387 |
|
388 @return A reference to a handle to the chunk containing the histogram data. |
|
389 */ |
|
390 virtual RChunk& ChunkL() = 0; |
|
391 |
|
392 /** |
|
393 @deprecated use TInt MHistogramV2Buffer::ChunkOffsetL() |
|
394 |
|
395 Returns the offset in the chunk (returned by ChunkL()) that contains the data for the |
|
396 histogram at a specified index within the histogram buffer. |
|
397 |
|
398 @param aIndex |
|
399 The index of the required histogram in the buffer. |
|
400 This must be between 0 and (NumOfHistograms() - 1). |
|
401 |
|
402 @leave KErrArgument if aIndex is not between 0 and (NumOfHistograms() - 1). |
|
403 |
|
404 @return The offset in the chunk that contains the start of the histogram data. |
|
405 */ |
|
406 virtual TInt ChunkOffsetL(TUint aIndex) = 0; |
|
407 |
|
408 /** |
|
409 @deprecated Only one histogram is available per buffer in MHistogramV2Buffer |
|
410 |
|
411 Returns the image number or frame index to which the histogram stored at the specified |
|
412 index within the buffer relates. |
|
413 |
|
414 @param aIndex |
|
415 The index of the required histogram in the buffer. |
|
416 This must be between 0 and (NumOfHistograms() - 1). |
|
417 |
|
418 @leave KErrArgument if aIndex is not between 0 and (NumOfHistograms() - 1). |
|
419 |
|
420 @return The image number or frame index. |
|
421 */ |
|
422 virtual TInt ImageNumberL(TUint aIndex) = 0; |
|
423 |
|
424 /** |
|
425 @deprecated Only one histogram is available per buffer in MHistogramV2Buffer |
|
426 |
|
427 Returns the handle of a particular histogram stored in the buffer. |
|
428 |
|
429 @param aIndex |
|
430 The index of the required histogram in the buffer. |
|
431 This must be between 0 and (NumOfHistograms() - 1). |
|
432 |
|
433 @leave KErrArgument if aIndex is not between 0 and (NumOfHistograms() - 1). |
|
434 |
|
435 @return The handle of the histogram on the ECam implementation. |
|
436 */ |
|
437 virtual TUint HandleL(TUint aIndex) = 0; |
|
438 |
|
439 /** |
|
440 @deprecated use void MHistogramV2Buffer::Release() |
|
441 |
|
442 Releases the buffer. Once the client has processed the histogram data it should |
|
443 use this method to signal to the camera that the buffer can be deleted or re-used. |
|
444 */ |
|
445 virtual void Release() = 0; |
|
446 }; |
|
447 |
|
448 // |
|
449 // MHistogramV2Buffer // |
|
450 // |
|
451 |
|
452 /** |
|
453 This class is used to pass histogram data between the camera device and a client that uses CCameraV2Histogram and |
|
454 implements MCaptureImageObserver, MCaptureVideoObserver, MDirectViewFinderObserver and MClientViewFinderObserver. |
|
455 |
|
456 Only one histogram data is available per buffer. ECam implementation will issue another callback once a new histogram |
|
457 data is ready. Till that time, client shall use the histogram data available from the histogram buffer currently retrieved. |
|
458 |
|
459 The class allows the client to access the data as a descriptor to a kernel chunk. |
|
460 |
|
461 @see CCameraV2Histogram |
|
462 |
|
463 @publishedPartner |
|
464 @prototype |
|
465 */ |
|
466 class MHistogramV2Buffer |
|
467 { |
|
468 |
|
469 public: |
|
470 /** |
|
471 Returns the type of histogram data that is available within the histogram buffer. |
|
472 |
|
473 @return The type of the histogram in the buffer at the given index. |
|
474 */ |
|
475 virtual CCamera::CCameraV2Histogram::THistogramType Type()=0; |
|
476 |
|
477 /** |
|
478 Returns the number of bits per histogram element value used to store the histogram data within the histogram buffer. |
|
479 |
|
480 The number of bits per histogram element will be decided by the ECam implementation. |
|
481 |
|
482 @see NumOfElementsL() |
|
483 |
|
484 @return Positive value means the histogram element size in bits. Negative value means error case. |
|
485 */ |
|
486 virtual TInt ElementSize()=0; |
|
487 |
|
488 /** |
|
489 Returns the number of elements in the histogram within the histogram buffer. |
|
490 |
|
491 This value can be used along with the element size obtained by calling ElementSizeL(), to calculate |
|
492 the exact size of histogram data ( element-size x number-of-elements = histogram-size ). |
|
493 |
|
494 @return Positive value means the number of elements in the histogram. Negative value means error case. |
|
495 */ |
|
496 virtual TInt NumOfElements()=0; |
|
497 |
|
498 /** |
|
499 Allows access to the histogram in the histogram buffer via a descriptor. |
|
500 |
|
501 @return A pointer to a descriptor containing the histogram data. |
|
502 |
|
503 @leave May Leave with any error code. |
|
504 */ |
|
505 virtual TDesC8* DataL()=0; |
|
506 |
|
507 /** |
|
508 Returns a handle to the chunk that contains the histogram data. |
|
509 The RChunk is exposed so that it can potentially be shared between multiple |
|
510 processes. |
|
511 @note The descriptor pointer returned by DataL() is effectively derived from this RChunk. |
|
512 |
|
513 @leave KErrNotSupported if the chunk is not available. May Leave with any other error code as well. |
|
514 |
|
515 @return A reference to a handle to the chunk containing the histogram data. |
|
516 */ |
|
517 virtual RChunk& ChunkL()=0; |
|
518 |
|
519 /** |
|
520 Returns the offset in the chunk (returned by ChunkL()) that contains the data for the |
|
521 histogram within the histogram buffer. |
|
522 |
|
523 @leave KErrNotSupported if the chunk is not available. May Leave with any other error code as well. |
|
524 |
|
525 @return The offset in the chunk that contains the start of the histogram data. |
|
526 */ |
|
527 virtual TInt ChunkOffsetL()=0; |
|
528 |
|
529 /** |
|
530 Releases the buffer. Once the client has processed the histogram data it should |
|
531 use this method to signal to the camera that the buffer can be deleted or re-used. |
|
532 */ |
|
533 virtual void Release()=0; |
|
534 }; |
|
535 |
|
536 #endif // CAMERAHISTOGRAM_H |