|
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 "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 #ifndef __VIDEOPLAYHWDEVICE_H__ |
|
17 #define __VIDEOPLAYHWDEVICE_H__ |
|
18 |
|
19 #include <mmf/devvideo/devvideobase.h> |
|
20 #include <mmf/devvideo/devvideoplay.h> |
|
21 #include <mmf/common/mmfvideo.h> |
|
22 |
|
23 /** |
|
24 A base class for all video playback (decoder and post-processor) hardware devices. |
|
25 Since both decoders and post-processors can implement post-processing functionality, |
|
26 this class includes all post-processing related methods. The main difference between decoder |
|
27 and post-processor devices is that decoders can input coded data and write decoded pictures |
|
28 to another device, while post-processor devices can accept decoded pictures from the client |
|
29 or from another device. |
|
30 @publishedAll |
|
31 @released |
|
32 */ |
|
33 class CMMFVideoPlayHwDevice : public CMMFVideoHwDevice |
|
34 { |
|
35 public: |
|
36 /** |
|
37 Retrieves post-processing information about this hardware device. |
|
38 The device creates a CPostProcessorInfo structure, fills it with correct data, pushes it |
|
39 to the cleanup stack and returns it. The client will delete the object when it is no |
|
40 longer needed. |
|
41 |
|
42 @return "Post-processor information as a CPostProcessorInfo object. |
|
43 The object is pushed to the cleanup stack, and must be deallocated by the caller." |
|
44 @leave "This method may leave with one of the system-wide error codes. |
|
45 */ |
|
46 virtual CPostProcessorInfo* PostProcessorInfoLC() = 0; |
|
47 |
|
48 /** |
|
49 Retrieves the list of the output formats that the device supports. The list is ordered in |
|
50 plug-in preference order, with the preferred formats at the beginning of the list. The list |
|
51 can depend on the device source format, and therefore SetSourceFormatL() must be called before |
|
52 calling this method. |
|
53 |
|
54 @param "aFormats" "An array for the result format list. The array must be created and destroyed by the caller." |
|
55 @leave "This method may leave with one of the system-wide error codes. |
|
56 @pre "This method may only be called before the hwdevice has been initialized using Initialize()." |
|
57 */ |
|
58 virtual void GetOutputFormatListL(RArray<TUncompressedVideoFormat>& aFormats) = 0; |
|
59 |
|
60 /** |
|
61 Sets the device output format. |
|
62 |
|
63 @param "aFormat" "The format to use." |
|
64 @leave "This method may leave with one of the system-wide error codes. |
|
65 @pre "This method may only be called before the hwdevice has been initialized using Initialize()." |
|
66 */ |
|
67 virtual void SetOutputFormatL(const TUncompressedVideoFormat &aFormat) = 0; |
|
68 |
|
69 /** |
|
70 Sets the clock source to use for video timing. If no clock source is set. video playback |
|
71 will not be synchronized, but will proceed as fast as possible, depending on input data |
|
72 and output buffer availability. |
|
73 |
|
74 @param "aClock" "The clock source to be used." |
|
75 @pre "This method can only be called before the hwdevice has been initialized with Initialize()." |
|
76 */ |
|
77 virtual void SetClockSource(MMMFClockSource* aClock) = 0; |
|
78 |
|
79 /** |
|
80 Sets the device video output destination. The destination can be the screen (using direct |
|
81 screen access) or memory buffers. By default memory buffers are used. If data is written |
|
82 to another device, this method is ignored, and suitable memory buffers are always used. |
|
83 |
|
84 @param "aScreen" "True if video output destination is the screen, false if memory buffers." |
|
85 @leave "This method may leave with one of the system-wide error codes. |
|
86 @pre "This method can only be called before the hwdevice has been initialized with Initialize()." |
|
87 */ |
|
88 virtual void SetVideoDestScreenL(TBool aScreen) = 0; |
|
89 |
|
90 /** |
|
91 Sets the post-processing types to be used. |
|
92 |
|
93 @param "aPostProcCombination" "The post-processing steps to perform, a bitwise OR of values from TPostProcessType." |
|
94 @leave "This method may leave with one of the system-wide error codes. |
|
95 @pre "This method can be called either before or after the hwdevice has been initialized with Initialize(). |
|
96 If called after initialization, the change must only be committed when CommitL() is called." |
|
97 */ |
|
98 virtual void SetPostProcessTypesL(TUint32 aPostProcCombination) = 0; |
|
99 |
|
100 /** |
|
101 Sets post-processing options for input (pan-scan) cropping. |
|
102 |
|
103 @param "aRect" "The cropping rectangle to use." |
|
104 @leave "This method may leave with one of the system-wide error codes. |
|
105 @pre "This method can be called either before or after the hwdevice has been initialized with Initialize(). |
|
106 If called after initialization, the change must only be committed when CommitL() is called." |
|
107 */ |
|
108 virtual void SetInputCropOptionsL(const TRect& aRect) = 0; |
|
109 |
|
110 /** |
|
111 Sets post-processing options for YUV to RGB color space conversion. |
|
112 Specifies the input YUV and output RGB formats to use explicitly. SetSourceFormatL(), |
|
113 SetOutputFormatL(), and SetPostProcessTypesL() must be called before this method is used. |
|
114 |
|
115 @param "aOptions" "The conversion options to use." |
|
116 @param "aYuvFormat" "Conversion source YUV format" |
|
117 @param "aRgbFormat" "Conversion target RGB format" |
|
118 @leave "This method may leave with one of the system-wide error codes. |
|
119 @pre "This method can be called either before or after the hwdevice has been initialized with Initialize(). |
|
120 If called after initialization, the change must only be committed when CommitL() is called." |
|
121 */ |
|
122 virtual void SetYuvToRgbOptionsL(const TYuvToRgbOptions& aOptions, const TYuvFormat& aYuvFormat, TRgbFormat aRgbFormat) = 0; |
|
123 |
|
124 /** |
|
125 Sets post-processing options for YUV to RGB color space conversion. |
|
126 Uses the device input and output formats. For decoder devices the default YUV format used is |
|
127 the format specified in the input bitstream. SetSourceFormatL(), SetOutputFormatL(), and |
|
128 SetPostProcessTypesL() must be called before this method is used. |
|
129 |
|
130 @param "aOptions" "The conversion options to use." |
|
131 @leave "This method may leave with one of the system-wide error codes. |
|
132 @pre "This method can be called either before or after the hwdevice has been initialized with Initialize(). |
|
133 If called after initialization, the change must only be committed when CommitL() is called." |
|
134 */ |
|
135 virtual void SetYuvToRgbOptionsL(const TYuvToRgbOptions& aOptions) = 0; |
|
136 |
|
137 /** |
|
138 Sets post-processing options for rotation. SetPostProcessTypesL() must be called before |
|
139 this method is used. |
|
140 |
|
141 @param "aRotationType" "The rotation to perform." |
|
142 @leave "This method may leave with one of the system-wide error codes. |
|
143 @pre "This method can be called either before or after the hwdevice has been initialized with Initialize(). |
|
144 If called after initialization, the change must only be committed when CommitL() is called." |
|
145 */ |
|
146 virtual void SetRotateOptionsL(TRotationType aRotationType) = 0; |
|
147 |
|
148 /** |
|
149 Sets post-processing options for scaling. SetPostProcessTypesL() must be called before |
|
150 this method is used. |
|
151 |
|
152 @param "aTargetSize" "Scaling target size. If a fixed scale factor size is used, |
|
153 the new dimensions must be set to width=floor(factor*width), |
|
154 height=floor(factor*height). For example, scaling a |
|
155 QCIF (176x144) picture up by a factor of 4/3 yields a size |
|
156 of 234x192." |
|
157 @param "aAntiAliasFiltering" "True if anti-aliasing filtering should be used. |
|
158 If the post-processor does not support anti-aliased scaling, |
|
159 or supports anti-aliased scaling only, this argument is ignored." |
|
160 @leave "This method may leave with one of the system-wide error codes. |
|
161 @pre "This method can be called either before or after the hwdevice has been initialized with Initialize(). |
|
162 If called after initialization, the change must only be committed when CommitL() is called." |
|
163 */ |
|
164 virtual void SetScaleOptionsL(const TSize& aTargetSize, TBool aAntiAliasFiltering) = 0; |
|
165 |
|
166 /** |
|
167 Sets post-processing options for output cropping. SetPostProcessTypesL() must be called before |
|
168 this method is used. |
|
169 |
|
170 @param "aRect" "Output cropping area." |
|
171 @leave "This method may leave with one of the system-wide error codes. |
|
172 @pre "This method can be called either before or after the hwdevice has been initialized with Initialize(). |
|
173 If called after initialization, the change must only be committed when CommitL() is called." |
|
174 */ |
|
175 virtual void SetOutputCropOptionsL(const TRect& aRect) = 0; |
|
176 |
|
177 /** |
|
178 Sets post-processing plug-in specific options. SetPostProcessTypesL() must be called before |
|
179 this method is used. |
|
180 |
|
181 @param "aOptions" "The options. The format is plug-in specific." |
|
182 @leave "This method may leave with one of the system-wide error codes. |
|
183 @pre "This method can be called either before or after the hwdevice has been initialized with Initialize(). |
|
184 If called after initialization, the change must only be committed when CommitL() is called." |
|
185 */ |
|
186 virtual void SetPostProcSpecificOptionsL(const TDesC8& aOptions) = 0; |
|
187 |
|
188 /** |
|
189 Initializes the device. This method is asynchronous, the device will call |
|
190 MMFVideoPlayProxy::MdvppInitializeComplete() after initialization has completed. After this |
|
191 method has successfully completed, further configuration changes are not possible except where |
|
192 separately noted. |
|
193 */ |
|
194 virtual void Initialize() = 0; |
|
195 |
|
196 /** |
|
197 Commit all changes since the last CommitL(), Revert() or Initialize() |
|
198 to the hardware device. This only applies to methods which can be called both |
|
199 before AND after DevVideoPlay has been initialized. |
|
200 |
|
201 @see SetPostProcessTypesL |
|
202 @see SetInputCropOptionsL |
|
203 @see SetYuvToRgbOptionsL |
|
204 @see SetRotateOptionsL |
|
205 @see SetScaleOptionsL |
|
206 @see SetOutputCropOptionsL |
|
207 @see SetPostProcSpecificOptionsL |
|
208 |
|
209 @leave "The method will leave if an error occurs." |
|
210 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
211 */ |
|
212 virtual void CommitL() = 0; |
|
213 |
|
214 /** |
|
215 Revert all changes since the last CommitL(), Revert() or Initialize() |
|
216 back to their previous settings. This only applies to methods which can |
|
217 be called both before AND after DevVideoPlay has been initialized. |
|
218 |
|
219 @see SetPostProcessTypesL |
|
220 @see SetInputCropOptionsL |
|
221 @see SetYuvToRgbOptionsL |
|
222 @see SetRotateOptionsL |
|
223 @see SetScaleOptionsL |
|
224 @see SetOutputCropOptionsL |
|
225 @see SetPostProcSpecificOptionsL |
|
226 |
|
227 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
228 */ |
|
229 virtual void Revert() = 0; |
|
230 |
|
231 /** |
|
232 Starts writing output directly to the display frame buffer using Direct Screen Access. |
|
233 |
|
234 @param "aVideoRect" "The video output rectangle on screen." |
|
235 @param "aScreenDevice" "The screen device to use. The screen device object must be valid in the current thread." |
|
236 @param "aClipRegion" "Initial clipping region to use." |
|
237 |
|
238 @leave "This method may leave with one of the system-wide error codes. |
|
239 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
240 */ |
|
241 virtual void StartDirectScreenAccessL(const TRect& aVideoRect, |
|
242 CFbsScreenDevice& aScreenDevice, const TRegion& aClipRegion) = 0; |
|
243 |
|
244 /** |
|
245 Sets a new clipping region for Direct Screen Access. After the method returns, no video will |
|
246 be drawn outside of the region. If clipping is not supported, or the clipping region is too |
|
247 complex, either playback will pause or will resume without video display, depending on the |
|
248 current setting of SetPauseOnClipFail(), and the result can be verified with IsPlaying(). |
|
249 Clipping can be disabled by setting a new clipping region that includes the whole video window. |
|
250 |
|
251 @param "aRegion" "The new clipping region. After the method returns, no video will be drawn outside the region." |
|
252 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
253 */ |
|
254 virtual void SetScreenClipRegion(const TRegion& aRegion) = 0; |
|
255 |
|
256 /** |
|
257 Sets whether the system should pause playback when it gets a clipping region it cannot handle, |
|
258 or Direct Screen Access is aborted completely. If not, processing will proceed normally, but no |
|
259 video will be drawn. By default, playback is paused. |
|
260 |
|
261 @param "aPause" "True if playback should be paused when clipping fails, false if not. |
|
262 If playback is not paused, it will be continued without video display." |
|
263 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
264 */ |
|
265 virtual void SetPauseOnClipFail(TBool aPause) = 0; |
|
266 |
|
267 /** |
|
268 Aborts Direct Screen Access completely, to be called from MAbortDirectScreenAccess::AbortNow() |
|
269 and similar methods. DSA can be resumed by calling StartDirectScreenAccessL(). |
|
270 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
271 */ |
|
272 virtual void AbortDirectScreenAccess() = 0; |
|
273 |
|
274 /** |
|
275 Indicates whether playback is proceeding. This method can be used to check whether playback was |
|
276 paused or not in response to a new clipping region or DSA abort. |
|
277 |
|
278 @return "ETrue if video is still being played (even if not necessarily displayed)." |
|
279 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
280 */ |
|
281 virtual TBool IsPlaying() = 0; |
|
282 |
|
283 /** |
|
284 Re-draws the latest video picture. Only available when DSA is being used. If DSA is aborted or a |
|
285 non-supported clipping region has been set, the request may be ignored. |
|
286 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
287 */ |
|
288 virtual void Redraw() = 0; |
|
289 |
|
290 |
|
291 /** |
|
292 Starts video playback, including decoding, post-processing, and rendering. Playback will proceed |
|
293 until it has been stopped or paused, or the end of the bitstream is reached. |
|
294 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
295 */ |
|
296 virtual void Start() = 0; |
|
297 |
|
298 /** |
|
299 Stops video playback. No new pictures will be decoded, post-processed, or rendered. |
|
300 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
301 */ |
|
302 virtual void Stop() = 0; |
|
303 |
|
304 /** |
|
305 Pauses video playback, including decoding, post-processing, and rendering. No pictures will be |
|
306 decoded, post-processed, or rendered until playback has been resumed. |
|
307 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
308 */ |
|
309 virtual void Pause() = 0; |
|
310 |
|
311 /** |
|
312 Resumes video playback after a pause. |
|
313 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
314 */ |
|
315 virtual void Resume() = 0; |
|
316 |
|
317 /** |
|
318 Changes to a new decoding and playback position, used for randomly accessing (seeking) the |
|
319 input stream. The position change flushes all input and output buffers. Pre-decoder and |
|
320 post-decoder buffering are handled as if a new bitstream was being decoded. If the device still has buffered |
|
321 pictures that precede the new playback position, they will be discarded. If playback is |
|
322 synchronized to a clock source, the client is responsible for setting the clock source to the |
|
323 new position. |
|
324 |
|
325 @param "aPlaybackPosition" "The new playback position in the video stream." |
|
326 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
327 */ |
|
328 virtual void SetPosition(const TTimeIntervalMicroSeconds& aPlaybackPosition) = 0; |
|
329 |
|
330 /** |
|
331 Freezes a picture on the screen. After the picture has been frozen, no new pictures are |
|
332 displayed until the freeze is released with ReleaseFreeze(). If the device output is being |
|
333 written to memory buffers or to another plug-in, instead of the screen, no decoded pictures |
|
334 will be delivered while the freeze is active, and they are simply discarded. |
|
335 |
|
336 @param "aTimestamp" "The presentation timestamp of the picture to freeze. The frozen picture |
|
337 will be the first picture with a timestamp greater than or equal to this |
|
338 parameter." |
|
339 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
340 */ |
|
341 virtual void FreezePicture(const TTimeIntervalMicroSeconds& aTimestamp) = 0; |
|
342 |
|
343 /** |
|
344 Releases a picture frozen with FreezePicture(). |
|
345 |
|
346 @param "aTimestamp" "The presentation timestamp of the picture to release. The first picture |
|
347 displayed after the release will be the first picture with a timestamp |
|
348 greater than or equal to this parameter. To release the freeze immediately, |
|
349 set the timestamp to zero." |
|
350 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
351 */ |
|
352 virtual void ReleaseFreeze(const TTimeIntervalMicroSeconds& aTimestamp) = 0; |
|
353 |
|
354 |
|
355 /** |
|
356 Returns the current playback position, i.e. the timestamp for the most recently displayed or |
|
357 virtually displayed picture. If the device output is written to another device, the most recent |
|
358 output picture is used. |
|
359 |
|
360 @return "Current playback position." |
|
361 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
362 */ |
|
363 virtual TTimeIntervalMicroSeconds PlaybackPosition() = 0; |
|
364 |
|
365 /** |
|
366 Returns the total amount of memory allocated for uncompressed pictures. This figure only |
|
367 includes the pictures actually allocated by the plug-in itself, so that the total number of |
|
368 bytes allocated in the system can be calculated by taking the sum of the values from all plug-ins. |
|
369 |
|
370 @return "Total number of bytes of memory allocated for uncompressed pictures." |
|
371 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
372 */ |
|
373 virtual TUint PictureBufferBytes() = 0; |
|
374 |
|
375 /** |
|
376 Reads various counters related to decoded pictures. The counters are reset when Initialize() |
|
377 or this method is called, and thus they only include pictures processed since the last call. |
|
378 |
|
379 Post-processor devices return the number of input pictures in iPicturesDecoded and |
|
380 iTotalPictures. If the decoded pictures are written to another plug-in, they are considered |
|
381 to be "virtually displayed". |
|
382 |
|
383 @param "aCounters" "The counter structure to fill." |
|
384 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
385 */ |
|
386 virtual void GetPictureCounters(CMMFDevVideoPlay::TPictureCounters& aCounters) = 0; |
|
387 |
|
388 |
|
389 /** |
|
390 Sets the computational complexity level to use. If separate complexity levels are not available, |
|
391 the method call is ignored. If the level specified is not available, the results are undefined. |
|
392 Typically the device will either ignore the request or use the nearest suitable level. |
|
393 |
|
394 The complexity level can be changed at any point during playback. |
|
395 |
|
396 @param "aLevel" "The computational complexity level to use. Level zero (0) is the most complex |
|
397 one, with the highest quality. Higher level numbers require less processing |
|
398 and may have lower quality." |
|
399 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
400 */ |
|
401 virtual void SetComplexityLevel(TUint aLevel) = 0; |
|
402 |
|
403 /** |
|
404 Gets the number of complexity levels available. |
|
405 |
|
406 @return "The number of complexity control levels available, or zero if the information is not |
|
407 available yet. The information may not be available if the number of levels depends on |
|
408 the input data, and enough input data has not been read yet. In that case, using level |
|
409 zero is safe." |
|
410 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
411 */ |
|
412 virtual TUint NumComplexityLevels() = 0; |
|
413 |
|
414 /** |
|
415 Gets information about a computational complexity level. This method can be called after |
|
416 NumComplexityLevels() has returned a non-zero value - at that point the information is guaranteed |
|
417 to be available. Some hardware device implementations may not be able to provide all values, |
|
418 in that case the values will be approximated. |
|
419 |
|
420 @param "aLevel" "The computational complexity level to query. The level numbers range from zero |
|
421 (the most complex) to NumComplexityLevels()-1." |
|
422 @param "aInfo" "The information structure to fill." |
|
423 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
424 */ |
|
425 virtual void GetComplexityLevelInfo(TUint aLevel, CMMFDevVideoPlay::TComplexityLevelInfo& aInfo) = 0; |
|
426 |
|
427 /** |
|
428 Returns a picture back to the device. This method is called by CMMFDevVideoPlay to return pictures |
|
429 from the client (after they have been written with NewPicture()), or by the output device when |
|
430 it has finished using a picture. |
|
431 |
|
432 @param "aPicture" "The picture to return. The device can re-use the memory for the picture." |
|
433 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
434 */ |
|
435 virtual void ReturnPicture(TVideoPicture* aPicture) = 0; |
|
436 |
|
437 /** |
|
438 Gets a copy of the latest picture sent to output. |
|
439 |
|
440 @param "aPictureData" "Target picture. The memory for the picture must be allocated by the |
|
441 caller, and initialized properly. The data formats must match the snapshot |
|
442 format requested." |
|
443 @param "aFormat" "The picture format to use for the snapshot." |
|
444 |
|
445 @return "ETrue if the snapshot was taken, EFalse if a picture is not available. The picture may not |
|
446 be available if decoding has not progressed far enough yet." |
|
447 |
|
448 @leave "The method will leave if an error occurs. Typical error codes used: |
|
449 * KErrNotSupported - The requested data format or picture size is not supported, or the |
|
450 plug-in does not support snapshots." |
|
451 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
452 */ |
|
453 virtual TBool GetSnapshotL(TPictureData& aPictureData, const TUncompressedVideoFormat& aFormat) = 0; |
|
454 |
|
455 /** |
|
456 When the snapshot is available, it will be returned to the client using the TimedSnapshotComplete() |
|
457 callback. To cancel a timed snapshot request, use CancelTimedSnapshot(). Only one timed snapshot |
|
458 request can be active at a time. |
|
459 |
|
460 @param "aPictureData" "Target picture. The memory for the picture must be allocated by |
|
461 the caller, and initialized properly. The data formats must match |
|
462 the snapshot format requested. The picture must remain valid until |
|
463 the snapshot has been taken or until the request has been cancelled |
|
464 with CancelTimedSnapshot()." |
|
465 @param "aFormat" "The picture format to use for the snapshot." |
|
466 @param "aPresentationTimestamp" "Presentation timestamp for the picture to copy." |
|
467 |
|
468 @leave "The method will leave if an error occurs. Typical error codes used: |
|
469 * KErrNotSupported - The requested data format or picture size is not supported or |
|
470 the plug-in does not support timed snapshots." |
|
471 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
472 */ |
|
473 virtual void GetTimedSnapshotL(TPictureData* aPictureData, const TUncompressedVideoFormat& aFormat, |
|
474 const TTimeIntervalMicroSeconds& aPresentationTimestamp) = 0; |
|
475 |
|
476 /** |
|
477 When the snapshot is available, it will be returned to the client using the TimedSnapshotComplete() |
|
478 callback. To cancel a timed snapshot request, use CancelTimedSnapshot(). Only one timed snapshot |
|
479 request can be active at a time. |
|
480 |
|
481 @param "aPictureData" "Target picture. The memory for the picture must be allocated by |
|
482 the caller, and initialized properly. The data formats must match |
|
483 the snapshot format requested. The picture must remain valid until |
|
484 the snapshot has been taken or until the request has been cancelled |
|
485 with CancelTimedSnapshot()." |
|
486 @param "aFormat" "The picture format to use for the snapshot." |
|
487 @param "aPictureId" "Picture identifier for the picture to copy." |
|
488 |
|
489 @leave "The method will leave if an error occurs. Typical error codes used: |
|
490 * KErrNotSupported - The requested data format or picture size is not supported or |
|
491 the plug-in does not support timed snapshots." |
|
492 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
493 */ |
|
494 virtual void GetTimedSnapshotL(TPictureData* aPictureData, const TUncompressedVideoFormat& aFormat, |
|
495 const TPictureId& aPictureId) = 0; |
|
496 |
|
497 /** |
|
498 Cancels a timed snapshot request. |
|
499 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
500 */ |
|
501 virtual void CancelTimedSnapshot() = 0; |
|
502 |
|
503 /** |
|
504 Gets a list of the supported snapshot picture formats. |
|
505 |
|
506 @param "aFormats" "An array for the result format list. The array must be created and destroyed by |
|
507 the caller." |
|
508 |
|
509 @leave "This method may leave with one of the standard error codes." |
|
510 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
511 */ |
|
512 virtual void GetSupportedSnapshotFormatsL(RArray<TUncompressedVideoFormat>& aFormats) = 0; |
|
513 |
|
514 |
|
515 /** |
|
516 |
|
517 Notifies the hardware device that the end of input data has been reached and no more input data |
|
518 will be written. The hardware device can use this signal to ensure that the remaining data gets |
|
519 processed, without waiting for new data. For example when the data type is not EDuCodedPicture, |
|
520 calling this method is necessary otherwise a hardware device implementation might be looking for |
|
521 the start code for the next picture to ensure it has a complete picture before starting to decode |
|
522 the previous one. |
|
523 |
|
524 |
|
525 After the remaining data has been processed (and displayed, if applicable), the hardware |
|
526 device must notify the proxy with the MdvppStreamEnd() callback. |
|
527 |
|
528 DevVideo clients are encouraged to call this method, but its use is not mandatory for synchronized |
|
529 processing. For synchronized playback, all video pictures are processed or discarded according to |
|
530 their timestamps, and so the client can easily infer when processing is complete. However, it |
|
531 should be noted that the last picture might not be displayed if this method is not called and the |
|
532 input data type is not EDuCodedPicture. |
|
533 |
|
534 For non-synchronized playback (e.g. file conversion), a client must call this method otherwise it |
|
535 will never find out when the hardware device has finished processing the data. |
|
536 |
|
537 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
538 */ |
|
539 virtual void InputEnd() = 0; |
|
540 }; |
|
541 |
|
542 |
|
543 |
|
544 |
|
545 /** |
|
546 CMMFVideoDecodeHwDevice is the MSL video decoder hardware device interface. |
|
547 All video decoders must implement this interface. |
|
548 @publishedAll |
|
549 @released |
|
550 */ |
|
551 class CMMFVideoDecodeHwDevice : public CMMFVideoPlayHwDevice |
|
552 { |
|
553 public: |
|
554 /** |
|
555 Creates a new video decoder hardware device object, based on the implementation UID. |
|
556 |
|
557 @param "aUid" "Decoder implementation UID." |
|
558 @param "aProxy" "The proxy implementation to use." |
|
559 @return "A new CMMFVideoDecodeHwDevice object." |
|
560 @leave "This method may leave with one of the system-wide error codes. |
|
561 */ |
|
562 IMPORT_C static CMMFVideoDecodeHwDevice* NewL(TUid aUid, MMMFDevVideoPlayProxy& aProxy); |
|
563 |
|
564 /** |
|
565 Creates a new video decoder hardware device adapter object, based on the Implementation Information of a Processing Unit. |
|
566 |
|
567 @param "aImplInfo" "The registration data relating to the Interface Implementation of the Processing Unit." |
|
568 @param "aProxy" "The proxy implementation to use." |
|
569 @return "A new CMMFVideoDecodeHwDevice object." |
|
570 @leave "This method will leave if an error occurs." |
|
571 */ |
|
572 IMPORT_C static CMMFVideoDecodeHwDevice* NewPuAdapterL(const CImplementationInformation& aImplInfo, MMMFDevVideoPlayProxy& aProxy); |
|
573 |
|
574 |
|
575 /** |
|
576 Destructor. |
|
577 */ |
|
578 IMPORT_C virtual ~CMMFVideoDecodeHwDevice(); |
|
579 |
|
580 |
|
581 /** |
|
582 Retrieves decoder information about this hardware device. The device creates a CVideoDecoderInfo |
|
583 structure, fills it with correct data, pushes it to the cleanup stack and returns it. The client |
|
584 will delete the object when it is no longer needed. |
|
585 |
|
586 @return "Decoder information as a CVideoDecoderInfo object. The object is pushed to the cleanup |
|
587 stack, and must be deallocated by the caller." |
|
588 @leave "This method may leave with one of the system-wide error codes." |
|
589 |
|
590 @see CVideoDecoderInfo |
|
591 */ |
|
592 virtual CVideoDecoderInfo* VideoDecoderInfoLC() = 0; |
|
593 |
|
594 /** |
|
595 Reads header information from a coded data unit. |
|
596 @param "aDataUnitType" "The type of the coded data unit that is contained in aDataUnit. If the data is a |
|
597 simple piece of bitstream, use EDuArbitraryStreamSection." |
|
598 @param "aEncapsulation" "The encapsulation type used for the coded data. If the data is a |
|
599 simple piece of bitstream, use EDuElementaryStream." |
|
600 @param "aDataUnit" "The coded data unit, contained in a TVideoInputBuffer." |
|
601 @return "Header information for the data unit, or NULL if the coded data unit did not contain |
|
602 enough data to parse the header. The header data must be returned to the device using |
|
603 ReturnHeader() before Initialize() is called or the decoder is destroyed. The data remains |
|
604 valid until it is returned." |
|
605 @leave "The method will leave if an error occurs. Running out of data is not considered an error, |
|
606 as described above. Typical error codes used: |
|
607 * KErrNotSupported - The data is not in a supported format. |
|
608 * KErrCorrupt - The data appears to be in a supported format, but is corrupted." |
|
609 */ |
|
610 virtual TVideoPictureHeader* GetHeaderInformationL(TVideoDataUnitType aDataUnitType, |
|
611 TVideoDataUnitEncapsulation aEncapsulation, TVideoInputBuffer* aDataUnit) = 0; |
|
612 |
|
613 |
|
614 /** |
|
615 Returns a header from GetHeaderInformationL() back to the decoder so that the memory can be freed. |
|
616 |
|
617 @param "aHeader" "The header to return." |
|
618 @pre "This method can only be called before the hwdevice has been initialized with Initialize()." |
|
619 */ |
|
620 virtual void ReturnHeader(TVideoPictureHeader* aHeader) = 0; |
|
621 |
|
622 /** |
|
623 Sets the device input format to a compressed video format. |
|
624 |
|
625 @param "aFormat" "The input format to use." |
|
626 @param "aDataUnitType" "The data unit type for input data." |
|
627 @param "aEncapsulation" "The encapsulation type used for the coded data." |
|
628 @param "aDataInOrder" "ETrue if the input data is written in correct decoding order, |
|
629 EFalse if will be written in arbitrary order." |
|
630 @leave "The method will leave if an error occurs. Typical error codes used: |
|
631 * KErrNotSupported - The source format is not supported." |
|
632 |
|
633 @pre "This method can only be called before the hwdevice has been initialized with Initialize()." |
|
634 */ |
|
635 virtual void SetInputFormatL(const CCompressedVideoFormat& aFormat, |
|
636 TVideoDataUnitType aDataUnitType, TVideoDataUnitEncapsulation aEncapsulation, |
|
637 TBool aDataInOrder) = 0; |
|
638 |
|
639 /** |
|
640 Sets whether decoding should be synchronized to the current clock source, if any, or if pictures |
|
641 should instead be decoded as soon as possible. If decoding is synchronized, decoding timestamps |
|
642 are used if available, presentation timestamps are used if not. When decoding is not synchronized, |
|
643 pictures are decoded as soon as source data is available for them, and the decoder has a free |
|
644 output buffer. If a clock source is not available, decoding will not be synchronized. |
|
645 |
|
646 @param "aSynchronize" "True if decoding should be synchronized to a clock source." |
|
647 @pre "This method can only be called before the hwdevice has been initialized with Initialize()." |
|
648 */ |
|
649 virtual void SynchronizeDecoding(TBool aSynchronize) = 0; |
|
650 |
|
651 /** |
|
652 Sets decoder buffering options. See [3] for a description of the options available. |
|
653 |
|
654 @param "aOptions" "Buffering options." |
|
655 @leave "The method will leave if an error occurs. Typical error codes used: |
|
656 * KErrNotSupported - The specified buffering options are not supported. |
|
657 If the client receives this error code, it can call GetBufferOptions() |
|
658 to determine the options the decoder is able to support." |
|
659 |
|
660 @pre "This method can only be called before the hwdevice has been initialized with Initialize()." |
|
661 */ |
|
662 virtual void SetBufferOptionsL(const CMMFDevVideoPlay::TBufferOptions& aOptions) = 0; |
|
663 |
|
664 /** |
|
665 Gets the video decoder buffer options actually in use. This can be used before calling |
|
666 SetBufferOptions() to determine the default options, or afterwards to check the values |
|
667 actually in use (if some default values were used). |
|
668 |
|
669 @param "aOptions" "Buffering options structure to fill." |
|
670 @pre "This method can only be called before the hwdevice has been initialized with Initialize()." |
|
671 */ |
|
672 virtual void GetBufferOptions(CMMFDevVideoPlay::TBufferOptions& aOptions) = 0; |
|
673 |
|
674 /** |
|
675 Indicates which HRD/VBV specification is fulfilled in the input stream and any related parameters. |
|
676 |
|
677 @param "aHrdVbvSpec" "The HRD/VBV specification fulfilled." |
|
678 @param "aHrdVbvParams" "HRD/VBV parameters. The data format depends on the parameters chosen. |
|
679 For 3GPP TS 26.234 parameters (aHrdVbvSpec=EHrdVbv3GPP), the data in the |
|
680 descriptor is a package of type TPckC<T3gppHrdVbvParams> |
|
681 (see T3gppHrdVbvParams). If no HRD/VBV parameters are used, the descriptor |
|
682 is zero length." |
|
683 @see THrdVbvSpecification |
|
684 @pre "This method can only be called before the hwdevice has been initialized with Initialize()." |
|
685 */ |
|
686 virtual void SetHrdVbvSpec(THrdVbvSpecification aHrdVbvSpec, const TDesC8& aHrdVbvParams) = 0; |
|
687 |
|
688 /** |
|
689 Sets the output post-processor device to use. If an output device is set, all decoded pictures |
|
690 are delivered to that device, and not drawn on screen or returned to the client. Pictures are |
|
691 written using CMMDVideoPostProcDevice::WritePictureL() or a custom interface after they have been |
|
692 decoded. The post-processor must then synchronize rendering to the clock source if necessary. |
|
693 |
|
694 @param "aDevice" "The output post-processor device to use." |
|
695 @pre "This method can only be called before the hwdevice has been initialized with Initialize()." |
|
696 */ |
|
697 virtual void SetOutputDevice(CMMFVideoPostProcHwDevice* aDevice) = 0; |
|
698 |
|
699 /** |
|
700 Returns the current decoding position, i.e. the timestamp for the most recently decoded picture. |
|
701 |
|
702 @return "Current decoding position." |
|
703 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
704 */ |
|
705 virtual TTimeIntervalMicroSeconds DecodingPosition() = 0; |
|
706 |
|
707 /** |
|
708 Returns the current pre-decoder buffer size. |
|
709 |
|
710 @return "The number of bytes of data in the pre-decoder buffer." |
|
711 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
712 */ |
|
713 virtual TUint PreDecoderBufferBytes() = 0; |
|
714 |
|
715 /** |
|
716 Reads various counters related to the received input bitstream and coded data units. The counters |
|
717 are reset when Initialize() or this method is called, and thus they only include data processed |
|
718 since the last call. |
|
719 |
|
720 @param "aCounters" "The counter structure to fill." |
|
721 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
722 */ |
|
723 virtual void GetBitstreamCounters(CMMFDevVideoPlay::TBitstreamCounters& aCounters) = 0; |
|
724 |
|
725 /** |
|
726 Retrieves the number of free input buffers the decoder has available. |
|
727 |
|
728 @return "Number of free input buffers the decoder has available." |
|
729 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
730 */ |
|
731 virtual TUint NumFreeBuffers() = 0; |
|
732 |
|
733 /** |
|
734 Retrieves an empty video input buffer from the decoder. After input data has been written to the |
|
735 buffer, it can be written to the decoder using WriteCodedDataL(). The number of buffers the decoder |
|
736 must be able to provide before expecting any back, and the maximum size for each buffer, are |
|
737 specified in the buffer options. |
|
738 |
|
739 The decoder maintains ownership of the buffers even while they have been retrieved by the client, |
|
740 and will take care of deallocating them. |
|
741 |
|
742 @param "aBufferSize" "Required buffer size, in bytes. The resulting buffer can be larger than |
|
743 this, but not smaller." |
|
744 @return "A new input data buffer. The buffer is at least as large as requested, but it may be |
|
745 larger. If no free buffers are available, the return value is NULL." |
|
746 @leave "The method will leave if an error occurs. Lack of free buffers is not considered an error." |
|
747 */ |
|
748 virtual TVideoInputBuffer* GetBufferL(TUint aBufferSize) = 0; |
|
749 |
|
750 /** |
|
751 Writes a piece of coded video data to the decoder. The data buffer must be retrieved from the |
|
752 decoder with GetBufferL(). |
|
753 |
|
754 @param "aBuffer" "The coded data unit to write." |
|
755 @leave "This method may leave with one of the system-wide error codes." |
|
756 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
757 */ |
|
758 virtual void WriteCodedDataL(TVideoInputBuffer* aBuffer) = 0; |
|
759 |
|
760 /** |
|
761 Configures the Decoder using header information known by the client. |
|
762 @param "aVideoPictureHeader" "Header information to configure the decoder with" |
|
763 @leave "The method will leave if an error occurs. Running out of data is not considered an error, |
|
764 as described above. |
|
765 @pre "This method can only be called before the hwdevice has been initialized with Initialize()." |
|
766 */ |
|
767 virtual void ConfigureDecoderL(const TVideoPictureHeader& aVideoPictureHeader); |
|
768 |
|
769 |
|
770 |
|
771 protected: |
|
772 /** |
|
773 Constructor. |
|
774 */ |
|
775 IMPORT_C CMMFVideoDecodeHwDevice(); |
|
776 |
|
777 /** |
|
778 Set the proxy implementation to be used. Called just after the object is constructed. |
|
779 @param "aProxy" "The proxy to use." |
|
780 */ |
|
781 virtual void SetProxy(MMMFDevVideoPlayProxy& aProxy) = 0; |
|
782 private: |
|
783 TUid iDtor_ID_Key; |
|
784 }; |
|
785 |
|
786 |
|
787 /** |
|
788 CMMFVideoPostProcHwDevice is the MSL video post-processor plug-in interface. All MSL video |
|
789 post-processors must implement this interface. |
|
790 @publishedAll |
|
791 @released |
|
792 */ |
|
793 class CMMFVideoPostProcHwDevice : public CMMFVideoPlayHwDevice |
|
794 { |
|
795 public: |
|
796 /** |
|
797 Creates a new video post-processor hardware device object, based on the implementation UID. |
|
798 |
|
799 @param "aUid" "Post-processor implementation UID." |
|
800 @param "aProxy" "The proxy implementation to use." |
|
801 @return "A new CMMFVideoPostProcHwDevice object." |
|
802 @leave "This method may leave with one of the system-wide error codes." |
|
803 */ |
|
804 IMPORT_C static CMMFVideoPostProcHwDevice* NewL(TUid aUid, MMMFDevVideoPlayProxy& aProxy); |
|
805 |
|
806 /** |
|
807 Destructor. |
|
808 */ |
|
809 IMPORT_C virtual ~CMMFVideoPostProcHwDevice(); |
|
810 |
|
811 /** |
|
812 Sets the device input format to an uncompressed video format. |
|
813 |
|
814 @param "aFormat" "The input format to use." |
|
815 @leave "The method will leave if an error occurs. Typical error codes used: |
|
816 * KErrNotSupported - The input format is not supported." |
|
817 @pre "This method can only be called before the hwdevice has been initialized with Initialize()." |
|
818 */ |
|
819 virtual void SetInputFormatL(const TUncompressedVideoFormat& aFormat) = 0; |
|
820 |
|
821 /** |
|
822 Sets the decoder device that will write data to this post-processor. Decoded pictures will be |
|
823 written with WritePictureL() or through a custom interface. After pictures have been processed, |
|
824 they must be returned to the decoder using ReturnPicture(). |
|
825 |
|
826 @param "aDevice" "The decoder source plug-in to use." |
|
827 @pre "This method can only be called before the hwdevice has been initialized with Initialize()." |
|
828 */ |
|
829 virtual void SetInputDevice(CMMFVideoDecodeHwDevice* aDevice) = 0; |
|
830 |
|
831 /** |
|
832 Writes an uncompressed video picture to the post-processor. The picture must be returned to the |
|
833 client or source plug-in after it has been used. |
|
834 |
|
835 @param "aPicture" "The picture to write." |
|
836 @leave "This method may leave with one of the system-wide error codes." |
|
837 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
838 */ |
|
839 virtual void WritePictureL(TVideoPicture* aPicture) = 0; |
|
840 protected: |
|
841 /** |
|
842 Constructor. |
|
843 */ |
|
844 IMPORT_C CMMFVideoPostProcHwDevice(); |
|
845 |
|
846 /** |
|
847 Set the proxy implementation to be used. Called just after the object is constructed. |
|
848 @param "aProxy" "The proxy to use." |
|
849 */ |
|
850 virtual void SetProxy(MMMFDevVideoPlayProxy& aProxy) = 0; |
|
851 private: |
|
852 TUid iDtor_ID_Key; |
|
853 }; |
|
854 |
|
855 |
|
856 |
|
857 /** |
|
858 A custom interface extending the functionality of CMMFVideoPlayHwDevice, adding support for the decoder to handle the |
|
859 copying of the bitstream data into the buffers, combining this with a scan of the data and support for the passing of |
|
860 information from the client to the decoder describing what part of a frame the data contains. |
|
861 @publishedAll |
|
862 @released |
|
863 */ |
|
864 class MMMFVideoPlayHwDeviceExtensionScanCopy |
|
865 { |
|
866 public: |
|
867 /** |
|
868 Writes a piece of coded video data to the decoder. The data buffer must be retrieved from the |
|
869 decoder with GetBufferL(). |
|
870 |
|
871 @param "aBuffer" "The coded data unit to write." |
|
872 @param "aPortion" "The portion of the frame that the data contains. Defaults to EFramePortionUnknown." |
|
873 @leave "This method may leave with one of the system-wide error codes." |
|
874 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
875 */ |
|
876 virtual void WriteCodedDataL(TVideoInputBuffer* aBuffer, TFramePortion aPortion = EFramePortionUnknown) = 0; |
|
877 /** |
|
878 Passes a pointer to a piece of coded video data to the decoder. The data buffer, which is left empty by the client, |
|
879 must be retrieved from the decoder with GetBufferL(). |
|
880 |
|
881 @param "aCodedData" "A pointer to the coded data unit to scan and copy." |
|
882 @param "aBuffer" "The empty data buffer." |
|
883 @param "aPortion" "The portion of the frame that the data contains. Defaults to EFramePortionUnknown." |
|
884 @leave "This method may leave with one of the system-wide error codes." |
|
885 @pre "This method can only be called after the hwdevice has been initialized with Initialize()." |
|
886 */ |
|
887 virtual void ScanAndCopyCodedDataL(TPtr8 aCodedData, TVideoInputBuffer* aBuffer, TInt& aConsumed, TFramePortion aPortion = EFramePortionUnknown) = 0; |
|
888 }; |
|
889 |
|
890 inline void CMMFVideoDecodeHwDevice::ConfigureDecoderL(const TVideoPictureHeader& /*aVideoPictureHeader*/) |
|
891 { |
|
892 User::Leave(KErrNotSupported); |
|
893 } |
|
894 |
|
895 |
|
896 |
|
897 #endif |