|
1 // Copyright (c) 2003-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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef __DEVVIDEOBASE_H__ |
|
17 #define __DEVVIDEOBASE_H__ |
|
18 |
|
19 #include <e32base.h> |
|
20 #include <w32std.h> |
|
21 #include <mmf/devvideo/devvideoconstants.h> |
|
22 #include <ecom/ecom.h> |
|
23 |
|
24 |
|
25 /** |
|
26 Panic utility function |
|
27 @internalTechnology |
|
28 */ |
|
29 LOCAL_C void DevVideoPanic(TInt aReason) |
|
30 { |
|
31 User::Panic(KDevVideoPanicCategory, aReason); |
|
32 } |
|
33 |
|
34 |
|
35 /** |
|
36 A hardware device ID that identifies an instantiated video hardware device. |
|
37 Used in the playback and recording APIs to identify the component being controlled. |
|
38 @publishedAll |
|
39 @released |
|
40 */ |
|
41 typedef TInt THwDeviceId; |
|
42 |
|
43 |
|
44 /** |
|
45 Defines a supported scale factor for a scaling pre-processor or post-processor. |
|
46 |
|
47 The scale factor is defined as iScaleNum/iScaleDenom, |
|
48 where the values are positive integers and relatively prime. |
|
49 @publishedAll |
|
50 @released |
|
51 */ |
|
52 class TScaleFactor |
|
53 { |
|
54 public: |
|
55 /**Scale factor numerator. Non-zero.*/ |
|
56 TUint iScaleNum; |
|
57 /**Scale factor denominator. Non-zero.*/ |
|
58 TUint iScaleDenom; |
|
59 }; |
|
60 |
|
61 |
|
62 /** |
|
63 A custom YUV/RGB conversion matrix. The same matrix structure is used for both conversion directions. |
|
64 @publishedAll |
|
65 @released |
|
66 */ |
|
67 class TYuvConversionMatrix |
|
68 { |
|
69 public: |
|
70 /** |
|
71 Post-multiplication offset, a three-item vector. |
|
72 */ |
|
73 TReal iPostOffset[3]; |
|
74 |
|
75 /** |
|
76 Multiplication matrix, a 3x3 matrix. iMatrix[3*i+j] contains the j:th item on the i:th row of the matrix. |
|
77 */ |
|
78 TReal iMatrix[9]; |
|
79 |
|
80 /** |
|
81 Pre-multiplication offset, a three-item vector. |
|
82 */ |
|
83 TReal iPreOffset[3]; |
|
84 }; |
|
85 |
|
86 |
|
87 /** |
|
88 YUV (YCbCr) uncompressed image data format. |
|
89 @publishedAll |
|
90 @released |
|
91 */ |
|
92 class TYuvFormat |
|
93 { |
|
94 public: |
|
95 /** |
|
96 The YUV/RGB conversion coefficients to use |
|
97 */ |
|
98 TYuvCoefficients iCoefficients; |
|
99 |
|
100 /** |
|
101 Luminance/chrominance sampling pattern. |
|
102 */ |
|
103 TYuvSamplingPattern iPattern; |
|
104 |
|
105 /** |
|
106 Data layout, specifies whether the data is stored in a planar or interleaved mode. |
|
107 */ |
|
108 TYuvDataLayout iDataLayout; |
|
109 |
|
110 /** |
|
111 Custom YUV to RGB conversion matrix to use. |
|
112 Valid only if custom conversion matrix is used (iCoefficients is ECustomYuvMatrix). |
|
113 */ |
|
114 TYuvConversionMatrix* iYuv2RgbMatrix; |
|
115 |
|
116 /** |
|
117 Custom RGB to YUV conversion matrix to use. |
|
118 Valid only if custom conversion matrix is used (iCoefficients is ECustomYuvMatrix). |
|
119 */ |
|
120 TYuvConversionMatrix* iRgb2YuvMatrix; |
|
121 |
|
122 /** |
|
123 Pixel aspect ratio numerator. |
|
124 */ |
|
125 TUint iAspectRatioNum; |
|
126 |
|
127 /** |
|
128 Pixel aspect ratio denominator. |
|
129 The aspect ratio is defined as iAspectRatioNum/iAspectRatioDenom, |
|
130 where the values are positive integers and relatively prime. |
|
131 */ |
|
132 TUint iAspectRatioDenom; |
|
133 |
|
134 /** |
|
135 Tests whether this TYuvFormat object is the same as aOther. |
|
136 @param "aOther" "The object to compare." |
|
137 @return "ETrue if they are the same, EFalse if not." |
|
138 */ |
|
139 inline TBool operator==(const TYuvFormat& aOther) const; |
|
140 }; |
|
141 |
|
142 /** |
|
143 Defines an uncompressed video format. |
|
144 This structure is mainly just a combination of YUV and RGB formats, defined to simplify the rest of the API. |
|
145 @publishedAll |
|
146 @released |
|
147 */ |
|
148 class TUncompressedVideoFormat |
|
149 { |
|
150 public: |
|
151 /** |
|
152 The image data format. The validity of the rest of the fields depends on the data format used. |
|
153 */ |
|
154 TImageDataFormat iDataFormat; |
|
155 union |
|
156 { |
|
157 /** |
|
158 YUV picture format details, valid if iDataFormat is EYuvRawData. |
|
159 */ |
|
160 TYuvFormat iYuvFormat; |
|
161 |
|
162 /** |
|
163 RGB picture format details, valid if iDataFormat is ERgbRawData or ERgbFbsBitmap. |
|
164 */ |
|
165 TRgbFormat iRgbFormat; |
|
166 }; |
|
167 |
|
168 /** |
|
169 Tests whether this TUncompressedVideoFormat object is the same as aOther. |
|
170 @param "aOther" "The object to compare." |
|
171 @return "ETrue if they are the same, EFalse if not." |
|
172 */ |
|
173 inline TBool operator==(const TUncompressedVideoFormat& aOther) const; |
|
174 |
|
175 /** |
|
176 Sets this object equal to aOther. |
|
177 @param "aOther" "The object to clone." |
|
178 */ |
|
179 inline void operator=(const TUncompressedVideoFormat& aOther); |
|
180 }; |
|
181 |
|
182 |
|
183 /** |
|
184 Uncompressed picture data for one video picture. |
|
185 @publishedAll |
|
186 @released |
|
187 */ |
|
188 class TPictureData |
|
189 { |
|
190 public: |
|
191 /** |
|
192 The image data format. The validity of the rest of the fields depends on the data format used. |
|
193 */ |
|
194 TImageDataFormat iDataFormat; |
|
195 |
|
196 /** |
|
197 Image data size in pixels. In decoder output pictures the actual active picture area may be smaller, |
|
198 this is indicated using TVideoPicture.iCropRect. |
|
199 */ |
|
200 TSize iDataSize; |
|
201 |
|
202 union |
|
203 { |
|
204 /** |
|
205 Pointer to raw image data. Valid if iDataFormat is ERgbRawData or iYuvRawData. |
|
206 The data layout depends on the format used. |
|
207 */ |
|
208 TPtr8* iRawData; |
|
209 |
|
210 /** |
|
211 Pointer to an RGB bitmap. Valid if iDataFormat is ERgbFbsBitmap. |
|
212 */ |
|
213 CFbsBitmap* iRgbBitmap; |
|
214 }; |
|
215 }; |
|
216 |
|
217 /** |
|
218 Header information for one decoded picture. |
|
219 The header information is returned alongside with decoded pictures, |
|
220 or it can be read separately when DevVideoPlay is being initialized. |
|
221 |
|
222 @publishedAll |
|
223 @released |
|
224 */ |
|
225 class TVideoPictureHeader |
|
226 { |
|
227 public: |
|
228 /** |
|
229 */ |
|
230 enum THeaderOptions |
|
231 { |
|
232 /** Decoding timestamp is valid |
|
233 */ |
|
234 EDecodingTimestamp = 0x00000001, |
|
235 /** Presentation timestamp is valid |
|
236 */ |
|
237 EPresentationTimestamp = 0x00000002, |
|
238 /** Pre-decoder buffersize is valid |
|
239 */ |
|
240 EPreDecoderBufferSize = 0x00000004, |
|
241 /** Post-decoder buffersize is valid |
|
242 */ |
|
243 EPostDecoderBufferSize = 0x00000008, |
|
244 /** Picture number field is valid |
|
245 */ |
|
246 EPictureNumber = 0x00000010, |
|
247 /** Layered coding is used and the layer number field is valid |
|
248 */ |
|
249 ELayeredCoding = 0x00000020, |
|
250 /** Supplemental data is available |
|
251 */ |
|
252 ESupplementalData = 0x00000040, |
|
253 /** Random access buffering period is valid |
|
254 */ |
|
255 ERandomAccessBufferingPeriod = 0x00000080, |
|
256 /** Random access buffer occupancy is valid |
|
257 */ |
|
258 ERandomAccessBufferOccupancy = 0x00000100 |
|
259 }; |
|
260 |
|
261 /** |
|
262 Header options. The value is a bitfield combined from values from THeaderOptions. |
|
263 */ |
|
264 TUint32 iOptions; |
|
265 |
|
266 /** |
|
267 Video codec profile used. Use -1 if not applicable or not defined. |
|
268 */ |
|
269 TInt iProfile; |
|
270 |
|
271 /** |
|
272 Video codec level. Use -1 if not applicable or not defined. |
|
273 */ |
|
274 TInt iLevel; |
|
275 |
|
276 /** |
|
277 Video codec version. Use -1 if not applicable or not defined. |
|
278 */ |
|
279 TInt iVersion; |
|
280 |
|
281 /** |
|
282 Pointer to a descriptor that contains optional codec-specific features. Set to NULL if not used. |
|
283 The format of the data is codec-specific. The pointer and descriptor data are valid as long as |
|
284 the header information structure is valid. |
|
285 */ |
|
286 const TDesC8* iOptional; |
|
287 |
|
288 /** |
|
289 Image size in memory, in pixels. May be larger than the displayed picture. |
|
290 */ |
|
291 TSize iSizeInMemory; |
|
292 |
|
293 /** |
|
294 The portion of the full image to display. |
|
295 */ |
|
296 TRect iDisplayedRect; |
|
297 |
|
298 /** |
|
299 Picture presentation timestamp. Valid only if EPresentationTimestamp is set in the options. |
|
300 The clock frequency is stored in the timestamp structure. |
|
301 */ |
|
302 TTimeIntervalMicroSeconds iPresentationTimestamp; |
|
303 |
|
304 /** |
|
305 Picture decoding timestamp. Valid only if EDecodingTimestamp is set in the options. |
|
306 */ |
|
307 TTimeIntervalMicroSeconds iDecodingTimestamp; |
|
308 |
|
309 /** |
|
310 Expected pre-decoder buffer size in bytes. Valid only if EPreDecoderBufferSize is set in the options. |
|
311 */ |
|
312 TUint iPreDecoderBufferSize; |
|
313 |
|
314 /** |
|
315 Expected post-decoder buffer size in bytes. Valid only if EPostDecoderBufferSize is set in the options. |
|
316 It is assumed that a frame buffer to be displayed is returned before the decoding of the next frame |
|
317 is started. If this is not the case, a larger post-decoder buffer may actually be needed. |
|
318 */ |
|
319 TUint iPostDecoderBufferSize; |
|
320 |
|
321 /** |
|
322 Picture number, valid only if EPictureNumber is set in the options. |
|
323 This field is used to indicate one of the following: picture number or long-term picture index for H.263, |
|
324 vop_id for MPEG-4 Visual, picture number or long-term picture number for AVC. |
|
325 */ |
|
326 TUint iPictureNumber; |
|
327 |
|
328 /** |
|
329 Picture layer number if layered coding is used, valid only if ELayeredCoding is set in the options. |
|
330 Layers are numbered [0…n-1], where n is the number of layers available. The first layer (layer zero) |
|
331 is the base layer, it can be decoded independently from the other layers, and it has the lowest total bitrate. |
|
332 */ |
|
333 TUint iPictureLayer; |
|
334 |
|
335 /** |
|
336 Picture supplemental data, valid only if ESupplementalData is set in the options. |
|
337 The pointer and descriptor data are valid as long as the header information structure is valid. |
|
338 */ |
|
339 const TDesC8* iSupplementalData; |
|
340 |
|
341 /** |
|
342 True if the picture is a random-accessible picture. |
|
343 */ |
|
344 TBool iIsRandomAccessible; |
|
345 |
|
346 /** |
|
347 The expected initial pre-decoder buffering period before starting the playback from this picture. |
|
348 Valid only if this picture is randomly accessible (iIsRandomAccessible is true) and |
|
349 ERandomAccessBufferingPeriod is set in the options. MPEG-2 and H.264 | MPEG-4 AVC use this value. |
|
350 */ |
|
351 TTimeIntervalMicroSeconds32 iRandomAccessBufferingPeriod; |
|
352 |
|
353 /** |
|
354 The expected initial pre-decoder buffer occupancy in bytes before starting the playback |
|
355 from this picture. Valid if this picture is randomly accessible (iIsRandomAccessible is true) and |
|
356 ERandomAccessBufferOccupancy is set in the options. MPEG-4 Visual uses this value. |
|
357 */ |
|
358 TUint iRandomAccessBufferOccupancy; |
|
359 }; |
|
360 |
|
361 |
|
362 |
|
363 /** |
|
364 One uncompressed video picture. Used for both decoded picture output as well as uncompressed picture input. |
|
365 |
|
366 @publishedAll |
|
367 @released |
|
368 */ |
|
369 class TVideoPicture |
|
370 { |
|
371 public: |
|
372 /** |
|
373 */ |
|
374 enum TVideoPictureOptions |
|
375 { |
|
376 /** The timestamp field is valid. |
|
377 */ |
|
378 ETimestamp = 0x00000001, |
|
379 /** The crop rectangle field is valid. |
|
380 */ |
|
381 ECropRect = 0x00000002, |
|
382 /** Picture header information is present. |
|
383 */ |
|
384 EHeader = 0x00000004, |
|
385 /** The layer bit count targets field is valid. |
|
386 */ |
|
387 EBitTargets = 0x00000008, |
|
388 /** Set in encoder input to request an instantaneous decoder refresh. |
|
389 As a response, the encoder should code an intra frame and no consecutive |
|
390 frame should refer to any frame before the encoded intra frame (in coding order). |
|
391 */ |
|
392 EReqInstantRefresh = 0x00000010, |
|
393 /** Set in encoder input to indicate a scene cut in the picture stream. |
|
394 */ |
|
395 ESceneCut = 0x00000020, |
|
396 /** Set if a picture effect is in use and the picture effect field is valid. |
|
397 */ |
|
398 EPictureEffect = 0x00000040, |
|
399 /** Set if picture effect parameters are valid. |
|
400 */ |
|
401 EEffectParameters = 0x00000080 |
|
402 }; |
|
403 |
|
404 /** |
|
405 The picture data. The picture data, including all pointers, must remain valid until |
|
406 the picture has been returned to its originator. |
|
407 */ |
|
408 TPictureData iData; |
|
409 |
|
410 /** |
|
411 Picture options. The value is a bitfield combined from values from TVideoPictureOptions. |
|
412 */ |
|
413 TUint32 iOptions; |
|
414 |
|
415 /** |
|
416 Picture timestamp. Valid if ETimestamp is set in the options. |
|
417 Used for presentation timestamps in video playback and capture timestamps in uncompressed video |
|
418 input for recording. If the timestamp is not specified for decoded video input for playback, |
|
419 the picture is displayed immediately. For decoded video output in playback and uncompressed |
|
420 video input for recording, the timestamp must always be set. |
|
421 */ |
|
422 TTimeIntervalMicroSeconds iTimestamp; |
|
423 |
|
424 /** |
|
425 Pan-scan cropping rectangle. Defines the area of the picture used for further processing. |
|
426 Only used for decoded video output. |
|
427 */ |
|
428 TRect iCropRect; |
|
429 |
|
430 /** |
|
431 Picture header information. Valid if EHeader is set in the options. |
|
432 Normally this field is only used in decoded pictures returned from the playback API. |
|
433 In that case the header info pointer is valid until the picture is returned to the API. |
|
434 */ |
|
435 TVideoPictureHeader* iHeader; |
|
436 |
|
437 /** |
|
438 The target number of bits for each bit-rate scalability layer, valid when EBitTargets is set in the options. |
|
439 Used in video encoding when the caller controls the bit-rate for each picture separately. |
|
440 The field points to a table containing the target number of bits to use for each layer when |
|
441 encoding this picture, starting from the lowest layer. The bit count for an enhancement layer |
|
442 includes all lower layers. For example, if the client uses two layers, and reserves 1.5 kilobits |
|
443 for the base layer and three kilobits for the whole picture, this field is set to {1500, 3000}. |
|
444 */ |
|
445 RArray<TUint>* iLayerBitRates; |
|
446 |
|
447 /** |
|
448 The picture effect in use when capturing this picture, valid when EPictureEffect is set in the options. |
|
449 This information can be used when encoding the picture. Note that setting a picture effect does not |
|
450 imply that the encoder should modify the picture data based on the effect. Instead, it can be used as |
|
451 an encoding hint. For example, fade to black implies that the global picture brightness has been decreased, |
|
452 and this knowledge can be used to aid motion prediction. |
|
453 @see TPictureEffects |
|
454 */ |
|
455 TPictureEffect iEffect; |
|
456 |
|
457 /** |
|
458 Picture effect parameter for fade to/from black, valid when EEffectParameters is set in the options |
|
459 and iEffect is EEffectFadeFromBlack or EEffectFadeToBlack. The value range is [0…65536], with zero |
|
460 indicating the picture is black and 65536 indicating that the lightness of the picture is unchanged. |
|
461 If the parameter is not given, the caller is unaware of the proper value or the value fluctuates spatially. |
|
462 */ |
|
463 TUint iFadeParam; |
|
464 |
|
465 /** |
|
466 A pointer for free-form user data. The pointer is set by the module that created the buffer, and is |
|
467 usually used for memory management purposes. |
|
468 */ |
|
469 TAny* iUser; |
|
470 |
|
471 /** |
|
472 A queue link used internally by the MSL video components. |
|
473 */ |
|
474 TDblQueLink iLink; |
|
475 }; |
|
476 |
|
477 /** |
|
478 Identifies a video picture in feedback messages. |
|
479 |
|
480 @publishedAll |
|
481 @released |
|
482 */ |
|
483 class TPictureId |
|
484 { |
|
485 public: |
|
486 enum TPictureIdType |
|
487 { |
|
488 /** Unidentified picture. */ |
|
489 ENone, |
|
490 /** The picture is identified using its temporal reference. */ |
|
491 ETemporalReference, |
|
492 /** The picture is identified using its picture number. Picture numbers are used in H.263 annex U and H.264 | MPEG-4 AVC, for example.. */ |
|
493 EPictureNumber |
|
494 }; |
|
495 |
|
496 /** Picture identified type. */ |
|
497 TPictureIdType iIdType; |
|
498 |
|
499 /** The picture identifier. The interpretation of this field depends on the value iIdType */ |
|
500 TUint32 iId; |
|
501 }; |
|
502 |
|
503 |
|
504 /** |
|
505 Defines a compressed video format. The format is identified by its MIME type, which may include |
|
506 parameters that describe the used format profile and level. The MIME type used for H.263 |
|
507 is video/H263-2000, specified in TS 26.234, and the type for MPEG-4 is video/MP4V-ES, specified in RFC 3016. |
|
508 |
|
509 @publishedAll |
|
510 @released |
|
511 */ |
|
512 class CCompressedVideoFormat : public CBase |
|
513 { |
|
514 public: |
|
515 /** |
|
516 Static factory function for creating new CCompressedVideoFormat objects. |
|
517 |
|
518 @param "aMimeType" "Video codec MIME type, including optional parameters for profile, |
|
519 level and version information. The CCompressedVideoFormat object creates |
|
520 and owns a copy of this buffer and takes care of deallocation." |
|
521 |
|
522 @param "aOptionalData" "Reference to a descriptor that contains optional codec-specific data. |
|
523 Set to KNullDesC8 if not used. [The format of the data is codec-specific, typically |
|
524 a package buffer containing a data structure may be used. The pointer lifetime |
|
525 and validity requirements are specified with each method that uses this structure." |
|
526 |
|
527 @return "Pointer to a fully constructed CCompressedVideoFormat object." |
|
528 @leave "This method may leave with one of the system-wide error codes." |
|
529 */ |
|
530 IMPORT_C static CCompressedVideoFormat* NewL(const TDesC8& aMimeType, const TDesC8& aOptionalData = KNullDesC8); |
|
531 |
|
532 /** |
|
533 Static factory function for creating a copy of an existing CCompressedVideoFormat object. |
|
534 |
|
535 @param "aFormat" "The CCompressedVideoFormat object to copy." |
|
536 |
|
537 @return Pointer to a fully constructed CCompressedVideoFormat object. |
|
538 @leave This method may leave with one of the system-wide error codes. |
|
539 */ |
|
540 IMPORT_C static CCompressedVideoFormat* NewL(const CCompressedVideoFormat& aFormat); |
|
541 |
|
542 /** |
|
543 Virtual destructor. Destroys iMimeType. |
|
544 */ |
|
545 IMPORT_C virtual ~CCompressedVideoFormat(); |
|
546 |
|
547 /** |
|
548 Returns the video codec MIME type. |
|
549 |
|
550 @return "Reference to a descriptor that contains the video codec MIME type." |
|
551 */ |
|
552 IMPORT_C const TDesC8& MimeType() const; |
|
553 |
|
554 /** |
|
555 Returns the optional data. |
|
556 |
|
557 @return "Reference to a descriptor that contains optional codec-specific data. |
|
558 Zero length if not used. The format of the data is codec-specific, typically a package buffer |
|
559 containing a data structure may be used." |
|
560 */ |
|
561 IMPORT_C const TDesC8& OptionalData() const; |
|
562 |
|
563 /** |
|
564 Tests whether this CCompressedVideoFormat is identical to aOther or not. |
|
565 @return "ETrue if the two objects are identical, EFalse if not." |
|
566 */ |
|
567 IMPORT_C TBool operator==(const CCompressedVideoFormat& aOther) const; |
|
568 protected: |
|
569 /** |
|
570 @internalTechnology |
|
571 */ |
|
572 CCompressedVideoFormat(); |
|
573 |
|
574 /** |
|
575 @internalTechnology |
|
576 */ |
|
577 void ConstructL(const TDesC8& aMimeType, const TDesC8& aOptionalData); |
|
578 private: |
|
579 HBufC8* iMimeType; |
|
580 HBufC8* iOptionalData; |
|
581 }; |
|
582 |
|
583 |
|
584 /** |
|
585 Specifies the HRD/VBV parameters used when 3GPP TS 26.234 annex G HRD/VBV settings are used (EHrdVbv3GPP). |
|
586 See TS 26.234 Release 5 for details. |
|
587 @publishedAll |
|
588 @released |
|
589 */ |
|
590 class T3gppHrdVbvParams |
|
591 { |
|
592 public: |
|
593 /** Initial pre-decoder buffering period. */ |
|
594 TTimeIntervalMicroSeconds iInitialPreDecoderBufferPeriod; |
|
595 |
|
596 /** Initial post-decoder buffering period. */ |
|
597 TTimeIntervalMicroSeconds iInitialPostDecoderBufferPeriod; |
|
598 |
|
599 /** Hypothetical pre-decoder buffer size, in bytes. */ |
|
600 TUint iPreDecoderBufferSize; |
|
601 |
|
602 /** Peak decoding byte rate. By default, the peak decoding byte rate is |
|
603 defined according to the video coding profile and level in use. */ |
|
604 TUint iPeakDecodingByteRate; |
|
605 |
|
606 /** Decoding macroblock rate. The default decoding macroblock rate is defined |
|
607 according to the video coding profile and level in use. */ |
|
608 TUint iDecodingMacroblockRate; |
|
609 }; |
|
610 |
|
611 |
|
612 /** |
|
613 YUV to RGB post-processing options. |
|
614 @publishedAll |
|
615 @released |
|
616 */ |
|
617 class TYuvToRgbOptions |
|
618 { |
|
619 public: |
|
620 /** |
|
621 Lightness setting. The value range is [-100 … 100], with -100 corresponding to minimum setting, |
|
622 100 to maximum setting, and 0 to no change in lightness. The actual lightness change formula |
|
623 used is hardware device specific. |
|
624 */ |
|
625 TInt iLightness; |
|
626 |
|
627 /** |
|
628 Saturation setting. The value range is [-100 … 100], with -100 corresponding to minimum setting, |
|
629 100 to maximum setting, and 0 to no change in saturation. The actual saturation formula used |
|
630 is hardware device specific. |
|
631 */ |
|
632 TInt iSaturation; |
|
633 |
|
634 /** |
|
635 Contrast setting. The value range is [-100 … 100], with -100 corresponding to minimum setting, |
|
636 100 to maximum setting, and 0 to no change in contrast. The actual contrast change formula |
|
637 used is hardware device specific. |
|
638 */ |
|
639 TInt iContrast; |
|
640 |
|
641 /** |
|
642 Gamma setting for conversion. Ignored if the converter does not support gamma correction. |
|
643 The gamma correction is defined as x' = x^(1/g), where x' refers to the corrected value, |
|
644 x to the original input value and g to this field. Gamma correction is performed on the RGB values. |
|
645 Set gamma to 1.0 to disable gamma correction. |
|
646 */ |
|
647 TReal iGamma; |
|
648 |
|
649 /** |
|
650 The dithering type to use. |
|
651 */ |
|
652 TDitherType iDitherType; |
|
653 }; |
|
654 |
|
655 /** |
|
656 Pre-processing options for color enhancement. |
|
657 The value ranges have been chosen to match those in the Onboard Camera API. |
|
658 @publishedAll |
|
659 @released |
|
660 */ |
|
661 class TColorEnhancementOptions |
|
662 { |
|
663 public: |
|
664 /** |
|
665 Lightness setting. The value range is [-100 … 100], with -100 corresponding to minimum setting, |
|
666 100 to maximum setting, and 0 to no change in lightness. |
|
667 */ |
|
668 TInt iLightness; |
|
669 |
|
670 /** |
|
671 Saturation setting. The value range is [-100 … 100], with -100 corresponding to minimum setting, |
|
672 100 to maximum setting, and 0 to no change in saturation. |
|
673 */ |
|
674 TInt iSaturation; |
|
675 |
|
676 /** |
|
677 Contrast setting. The value range is [-100 … 100], with -100 corresponding to minimum setting, |
|
678 100 to maximum setting, and 0 to no change in contrast. |
|
679 */ |
|
680 TInt iContrast; |
|
681 }; |
|
682 |
|
683 /** |
|
684 Describes the YUV to RGB color conversion capabilities of a post-processor. |
|
685 @publishedAll |
|
686 @released |
|
687 */ |
|
688 class TYuvToRgbCapabilities |
|
689 { |
|
690 public: |
|
691 /** |
|
692 Input YUV sampling patterns supported, a bitfield combination (bitwise OR) of TYuvSamplingPattern. |
|
693 */ |
|
694 TUint32 iSamplingPatterns; |
|
695 |
|
696 /** |
|
697 YUV to RGB conversion coefficients supported, a bitfield combination of TYuvCoefficients. |
|
698 */ |
|
699 TUint32 iCoefficients; |
|
700 |
|
701 /** |
|
702 Output RGB formats supported, a bitfield combination of TRgbFormat. |
|
703 */ |
|
704 TUint32 iRgbFormats; |
|
705 |
|
706 /** |
|
707 True if lightness control is supported. |
|
708 */ |
|
709 TBool iLightnessControl; |
|
710 |
|
711 /** |
|
712 True if saturation control is supported. |
|
713 */ |
|
714 TBool iSaturationControl; |
|
715 |
|
716 /** |
|
717 True if contrast control is supported. |
|
718 */ |
|
719 TBool iContrastControl; |
|
720 |
|
721 /** |
|
722 True if gamma correction is supported. |
|
723 */ |
|
724 TBool iGammaCorrection; |
|
725 |
|
726 /** |
|
727 Dithering types supported, a bitfield combination of TDitherType. |
|
728 */ |
|
729 TUint32 iDitherTypes; |
|
730 }; |
|
731 |
|
732 /** |
|
733 Specifies the YUV-to-YUV conversion capabilities for a plug-in. |
|
734 @publishedAll |
|
735 @released |
|
736 */ |
|
737 class TYuvToYuvCapabilities |
|
738 { |
|
739 public: |
|
740 /** |
|
741 The YUV sampling patterns supported for input data, a combination (binary OR) of values from TYuvSamplingPatterns. |
|
742 */ |
|
743 TUint32 iInputSamplingPatterns; |
|
744 |
|
745 /** |
|
746 The YUV data layouts supported for input data, a combination (binary OR) of values from TYuvDataLayout. |
|
747 */ |
|
748 TUint32 iInputDataLayouts; |
|
749 |
|
750 /** |
|
751 The YUV sampling patterns supported for output data, a combination (binary OR) of values from TYuvSamplingPatterns. |
|
752 */ |
|
753 TUint32 iOutputSamplingPatterns; |
|
754 |
|
755 /** |
|
756 The YUV data layouts supported for output data, a combination (binary OR) of values from TYuvDataLayout. |
|
757 */ |
|
758 TUint32 iOutputDataLayouts; |
|
759 }; |
|
760 |
|
761 /** |
|
762 Structure to combine a picture rate and size. Used when defining the maximum rate/size combinations |
|
763 available. |
|
764 @publishedAll |
|
765 @released |
|
766 */ |
|
767 class TPictureRateAndSize |
|
768 { |
|
769 public: |
|
770 /** The picture rate. */ |
|
771 TReal iPictureRate; |
|
772 |
|
773 /** The picture size. */ |
|
774 TSize iPictureSize; |
|
775 }; |
|
776 |
|
777 /** |
|
778 CMMFVideoHwDevice is a base class for all video hardware devices. |
|
779 @publishedAll |
|
780 @released |
|
781 */ |
|
782 class CMMFVideoHwDevice : public CBase |
|
783 { |
|
784 public: |
|
785 /** |
|
786 Retrieves a custom interface to the device. |
|
787 @param "aInterface" "Interface UID, defined with the custom interface." |
|
788 @return "Pointer to the interface implementation, or NULL if the device does not |
|
789 implement the interface requested. The return value must be cast to the |
|
790 correct type by the user." |
|
791 */ |
|
792 virtual TAny* CustomInterface(TUid aInterface) = 0; |
|
793 }; |
|
794 |
|
795 |
|
796 |
|
797 /** |
|
798 Defines the interface that video clock sources must to implement. |
|
799 |
|
800 A clock source can be used to synchronize video processing to some other processing entity, |
|
801 for example an audio stream. The clock source is created and controlled by the DevVideo client, |
|
802 and passed to the video hwdevices via the DevVideo interface. This allows the hwdevice to query |
|
803 the current stream time, so it can ascertain which frame should be processed at any given moment. |
|
804 |
|
805 "Stream time" is defined as the current position in the media stream. For example, when playing |
|
806 a video clip, the stream time will always equal the current position in the clip. So, when the |
|
807 clip is repositioned, the stream time will be equal to the new clip position. When the clip is |
|
808 paused, the stream time will pause too. |
|
809 |
|
810 Many hwdevice implementations will use extra threads to perform the video processing, so it is |
|
811 essential that all implementations of the MMMFClockSource interface can be used from multiple |
|
812 threads. A hwdevice that receives a clock source from the DevVideo client must be able to |
|
813 assume that it can pass a pointer to the clock source object into another thread and use the |
|
814 object directly from there. |
|
815 |
|
816 All clock source implementations must protect the methods defined in the MMMFClockSource interface |
|
817 so they can be called from any thread within the current process. Practically speaking, this means |
|
818 using mutexes and critical sections to protect member data from being accessed from multiple threads |
|
819 simultaneously. Also, any use of thread-specific handles (e.g. a CMMFDevSound object) must be |
|
820 avoided from within these methods. |
|
821 |
|
822 It can be assumed that any methods defined outside the MMMFClockSource interface (for example |
|
823 methods used to control the clock source) will only be executed within the DevVideo client's thread, |
|
824 so do not require protection. |
|
825 |
|
826 @publishedAll |
|
827 @released |
|
828 */ |
|
829 class MMMFClockSource |
|
830 { |
|
831 public: |
|
832 /** |
|
833 Retrieves a custom interface for the clock source. |
|
834 |
|
835 This method can be called from any thread running inside the process in which the concrete |
|
836 clock source was created. Note that this does not mean that all methods in the custom |
|
837 interface can be called from any thread - that will be specified by the custom interface itself. |
|
838 |
|
839 @param "aInterface" "Interface UID, defined by the entity specifying the interface." |
|
840 @return "Pointer to the interface implementation, or NULL if the interface is not available. |
|
841 The pointer must be cast to the appropriate interface class." |
|
842 */ |
|
843 virtual TAny* CustomInterface(TUid aInterface) = 0; |
|
844 |
|
845 /** |
|
846 Retrieves the current stream time. For example, if a clip is being played, the stream time will |
|
847 be equal to the current position in the clip. |
|
848 |
|
849 This method can be called from any thread running inside the process in which the concrete clock |
|
850 source was created. |
|
851 |
|
852 @return "The number of microseconds passed in the clock compared to the reference time." |
|
853 */ |
|
854 virtual TTimeIntervalMicroSeconds Time() = 0; |
|
855 }; |
|
856 |
|
857 /** |
|
858 The CSystemClockSource provides a basic clock source implementation based on the system clock. |
|
859 It will count microseconds since the object was created or Reset() was last called, and return |
|
860 that count from Time(). It does not implement any custom interfaces. |
|
861 @publishedAll |
|
862 @released |
|
863 */ |
|
864 class CSystemClockSource : public CBase, public MMMFClockSource |
|
865 { |
|
866 public: |
|
867 /** |
|
868 Creates a new CSystemClockSource object. |
|
869 @return "A new clock source object." |
|
870 @leave "This method may leave with one of the system-wide error codes." |
|
871 */ |
|
872 IMPORT_C static CSystemClockSource* NewL(); |
|
873 |
|
874 /** |
|
875 Destructor. |
|
876 */ |
|
877 IMPORT_C ~CSystemClockSource(); |
|
878 |
|
879 // Control methods |
|
880 /** |
|
881 Resets the clock source to zero. Typically called by the DevVideo client at stream start. |
|
882 */ |
|
883 IMPORT_C void Reset(); |
|
884 |
|
885 /** |
|
886 Resets the clock source to a user-defined offset. Typically called by the DevVideo client |
|
887 when seeking in a file. |
|
888 |
|
889 @param "aOffset" "The clock offset." |
|
890 */ |
|
891 IMPORT_C void Reset(const TTimeIntervalMicroSeconds& aOffset); |
|
892 |
|
893 /** |
|
894 Suspends the clock source. The clock time will not increment until the clock has been resumed. |
|
895 This method is used when pausing playback. |
|
896 */ |
|
897 IMPORT_C void Suspend(); |
|
898 |
|
899 /** |
|
900 Resumes the clock source after a Suspend() method call. This method is used when resuming playback. |
|
901 */ |
|
902 IMPORT_C void Resume(); |
|
903 |
|
904 // Implementation of MMMFClockSource |
|
905 /** |
|
906 No custom interfaces are implemented by this clock source, so this method will always return NULL. |
|
907 @param "aInterface" "The interface" |
|
908 @return "NULL" |
|
909 */ |
|
910 virtual TAny* CustomInterface(TUid aInterface); |
|
911 /** |
|
912 Retrieves the time that has elapsed since Reset() was last called, subtracting any time |
|
913 during which the clock was suspended. |
|
914 |
|
915 @return "The number of microseconds that have elapsed in the stream." |
|
916 */ |
|
917 virtual TTimeIntervalMicroSeconds Time(); |
|
918 |
|
919 private: |
|
920 CSystemClockSource(); |
|
921 void ConstructL(); |
|
922 private: |
|
923 TTime iStartTime; |
|
924 TTime iCurrentTime; |
|
925 |
|
926 TTimeIntervalMicroSeconds iOffset; |
|
927 |
|
928 TTime iTimeWhenSuspended; |
|
929 TTimeIntervalMicroSeconds iTimeSuspended; |
|
930 TBool iSuspended; |
|
931 |
|
932 RCriticalSection iCriticalSection; |
|
933 }; |
|
934 |
|
935 |
|
936 /** |
|
937 Observer class to be used with class CMMFClockSourcePeriodicUtility. |
|
938 @publishedAll |
|
939 @released |
|
940 */ |
|
941 class MMMFClockSourcePeriodicUtilityObserver |
|
942 { |
|
943 public: |
|
944 /** |
|
945 Notifies the observer that the specified period has elapsed. |
|
946 @param "aTime" "The current time, queried from the clock source." |
|
947 */ |
|
948 virtual void MmcspuoTick(const TTimeIntervalMicroSeconds& aTime) = 0; |
|
949 }; |
|
950 |
|
951 /** |
|
952 Utility class that can be used by video HW devices to receive periodic callbacks with the current time. |
|
953 Note that the exact timing of the callbacks cannot be guaranteed due to other things pre-empting |
|
954 the execution of the active object or thread. |
|
955 @publishedAll |
|
956 @released |
|
957 */ |
|
958 class CMMFClockSourcePeriodicUtility : public CBase |
|
959 { |
|
960 public: |
|
961 /** |
|
962 Creates a new clock source periodic utility object. |
|
963 |
|
964 @param "aClockSource" "A reference to the clock source to be used to query the current time." |
|
965 @param "aObserver" "A reference to the observer of the utility that will receive callbacks |
|
966 each time the specified period elapses." |
|
967 @return "A new clock source periodic utility object." |
|
968 @leave "The method will leave if an error occurs." |
|
969 */ |
|
970 IMPORT_C static CMMFClockSourcePeriodicUtility* NewL(MMMFClockSource& aClockSource, MMMFClockSourcePeriodicUtilityObserver& aObserver); |
|
971 |
|
972 /** |
|
973 Starts the clock source periodic utility. The utility will call MmcspuoTick on its observer |
|
974 every aPeriod microseconds until Stop() is called. Note that the utility will not stop |
|
975 automatically when the clock source is stopped. |
|
976 |
|
977 @param "aPeriod" "Defines the period with which the observer will receive callbacks." |
|
978 */ |
|
979 IMPORT_C void Start(TTimeIntervalMicroSeconds32 aPeriod); |
|
980 |
|
981 /** |
|
982 Stops the clock source periodic utility. No more callbacks will be made after this method has |
|
983 been called. |
|
984 */ |
|
985 IMPORT_C void Stop(); |
|
986 |
|
987 /** |
|
988 Destructor. |
|
989 */ |
|
990 IMPORT_C ~CMMFClockSourcePeriodicUtility(); |
|
991 private: |
|
992 CMMFClockSourcePeriodicUtility(MMMFClockSource& aClockSource, MMMFClockSourcePeriodicUtilityObserver& aObserver); |
|
993 void ConstructL(); |
|
994 static TInt Callback(TAny* aAny); |
|
995 void DoCallback(); |
|
996 private: |
|
997 CPeriodic* iTimer; |
|
998 MMMFClockSource& iClockSource; |
|
999 MMMFClockSourcePeriodicUtilityObserver& iObserver; |
|
1000 }; |
|
1001 |
|
1002 |
|
1003 /** |
|
1004 Specifies the encoder buffering options. |
|
1005 @publishedAll |
|
1006 @released |
|
1007 */ |
|
1008 class TEncoderBufferOptions |
|
1009 { |
|
1010 public: |
|
1011 /** |
|
1012 The maximum number of pictures in the pre-encoder buffer. |
|
1013 */ |
|
1014 TUint iMaxPreEncoderBufferPictures; |
|
1015 |
|
1016 /** |
|
1017 The HRD/VBV specification that shall be fullfilled. |
|
1018 */ |
|
1019 THrdVbvSpecification iHrdVbvSpec; |
|
1020 |
|
1021 /** |
|
1022 The HRD/VBV buffering parameters. The data format depends on the parameters chosen. For |
|
1023 3GPP TS 26.234 parameters (iHrdVbvSpec=EHrdVbv3GPP), the data in the descriptor is a package of type |
|
1024 TPckC<T3gppHrdVbvParams> (see T3gppHrdVbvParams). If no HRD/VBV parameters are used, the |
|
1025 descriptor is empty. |
|
1026 */ |
|
1027 TPtrC8 iHrdVbvParams; |
|
1028 |
|
1029 /** |
|
1030 The maximum size of an output buffer, in bytes. Use KMaxTUint for an unlimited size. |
|
1031 */ |
|
1032 TUint iMaxOutputBufferSize; |
|
1033 |
|
1034 /** |
|
1035 The maximum size of a coded picture, in bytes. Use KMaxTUint for an unlimited size. |
|
1036 */ |
|
1037 TUint iMaxCodedPictureSize; |
|
1038 |
|
1039 /** |
|
1040 The maximum size of a coded video segment, in bytes. Use KMaxTUint for an unlimited size. |
|
1041 */ |
|
1042 TUint iMaxCodedSegmentSize; |
|
1043 |
|
1044 /** |
|
1045 The mimimum number of output buffers. |
|
1046 */ |
|
1047 TUint iMinNumOutputBuffers; |
|
1048 }; |
|
1049 |
|
1050 /** |
|
1051 Specifies the video encoder bit-rate control options. |
|
1052 @publishedAll |
|
1053 @released |
|
1054 */ |
|
1055 class TRateControlOptions |
|
1056 { |
|
1057 public: |
|
1058 /** |
|
1059 Defines the bit-rate control type. |
|
1060 */ |
|
1061 TBitrateControlType iControl; |
|
1062 |
|
1063 /** |
|
1064 The target bit-rate, in bits per second. Used if bit-rate control type is EBrControlStream. |
|
1065 If specified for an enhancement layer, the target bit-rate includes all lower layers. For example, |
|
1066 if the client uses two layers, with the base layer using 64000 bps and the whole stream 192000 bps, |
|
1067 this field is set to 64000 for layer zero and 192000 for layer one. |
|
1068 */ |
|
1069 TUint iBitrate; |
|
1070 |
|
1071 /** |
|
1072 The target picture quality. The value range is [0…100], with 0 corresponding to minimum quality |
|
1073 and 100 to lossless coding (or the closest equivalent supported). |
|
1074 */ |
|
1075 TUint iPictureQuality; |
|
1076 |
|
1077 /** |
|
1078 The target picture rate, in pictures per second. If specified for an enhancement layer, the target |
|
1079 frame rate includes all lower layers. |
|
1080 */ |
|
1081 TReal iPictureRate; |
|
1082 |
|
1083 /** |
|
1084 The quality/temporal tradeoff for bit-rate control. The value range is [0.0…1.0]. Value 0.0 |
|
1085 specifies that picture quality should be maintained as well as possible, sacrificing picture rate. |
|
1086 Value 1.0 specifies that picture rate should be maintained as well as possible, sacrificing |
|
1087 picture quality. |
|
1088 */ |
|
1089 TReal iQualityTemporalTradeoff; |
|
1090 |
|
1091 /** |
|
1092 The latency/quality tradeoff for bit-rate control. The value range is [0.0…1.0]. Value 0.0 |
|
1093 specifies that the transmission delay and the decoder input buffer occupancy level caused by |
|
1094 the bit-rate control is minimized, i.e. the actual coded bit-rate follows the target bit-rate |
|
1095 as closely as possible. 1.0 specifies that the transmission delay caused by the bit-rate control |
|
1096 should be as high as needed to guarantee a constant picture quality and frame rate as long as |
|
1097 the coded data conforms to the given HRD/VBV parameters (if any). |
|
1098 */ |
|
1099 TReal iLatencyQualityTradeoff; |
|
1100 }; |
|
1101 |
|
1102 /** |
|
1103 Custom interface Uid for setting up the DevVideo hw device adapter |
|
1104 */ |
|
1105 const TInt KUidDevVideoHwDeviceAdapterSetup = 0x102737EF; |
|
1106 |
|
1107 /** |
|
1108 Custom interface for setting up the DevVideo hw device adapter |
|
1109 @publishedPartner |
|
1110 @prototype |
|
1111 */ |
|
1112 class MDevVideoHwDeviceAdapterSetup |
|
1113 { |
|
1114 public: |
|
1115 /** |
|
1116 Set the Uid of the processing unit into the hw device adapter |
|
1117 */ |
|
1118 virtual void LoadProcessingUnitL(const CImplementationInformation& aImplInfo) = 0; |
|
1119 }; |
|
1120 |
|
1121 #include <mmf/devvideo/devvideobase.inl> |
|
1122 |
|
1123 #endif |