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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
16 #ifndef __VIDEOPLAYHWDEVICE_H__
17 #define __VIDEOPLAYHWDEVICE_H__
19 #include <mmf/devvideo/devvideobase.h>
20 #include <mmf/devvideo/devvideoplay.h>
21 #include <mmf/common/mmfvideo.h>
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.
33 class CMMFVideoPlayHwDevice : public CMMFVideoHwDevice
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
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.
46 virtual CPostProcessorInfo* PostProcessorInfoLC() = 0;
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
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()."
58 virtual void GetOutputFormatListL(RArray<TUncompressedVideoFormat>& aFormats) = 0;
61 Sets the device output format.
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()."
67 virtual void SetOutputFormatL(const TUncompressedVideoFormat &aFormat) = 0;
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.
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()."
77 virtual void SetClockSource(MMMFClockSource* aClock) = 0;
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.
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()."
88 virtual void SetVideoDestScreenL(TBool aScreen) = 0;
91 Sets the post-processing types to be used.
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."
98 virtual void SetPostProcessTypesL(TUint32 aPostProcCombination) = 0;
101 Sets post-processing options for input (pan-scan) cropping.
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."
108 virtual void SetInputCropOptionsL(const TRect& aRect) = 0;
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.
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."
122 virtual void SetYuvToRgbOptionsL(const TYuvToRgbOptions& aOptions, const TYuvFormat& aYuvFormat, TRgbFormat aRgbFormat) = 0;
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.
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."
135 virtual void SetYuvToRgbOptionsL(const TYuvToRgbOptions& aOptions) = 0;
138 Sets post-processing options for rotation. SetPostProcessTypesL() must be called before
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."
146 virtual void SetRotateOptionsL(TRotationType aRotationType) = 0;
149 Sets post-processing options for scaling. SetPostProcessTypesL() must be called before
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
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."
164 virtual void SetScaleOptionsL(const TSize& aTargetSize, TBool aAntiAliasFiltering) = 0;
167 Sets post-processing options for output cropping. SetPostProcessTypesL() must be called before
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."
175 virtual void SetOutputCropOptionsL(const TRect& aRect) = 0;
178 Sets post-processing plug-in specific options. SetPostProcessTypesL() must be called before
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."
186 virtual void SetPostProcSpecificOptionsL(const TDesC8& aOptions) = 0;
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
194 virtual void Initialize() = 0;
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.
201 @see SetPostProcessTypesL
202 @see SetInputCropOptionsL
203 @see SetYuvToRgbOptionsL
204 @see SetRotateOptionsL
205 @see SetScaleOptionsL
206 @see SetOutputCropOptionsL
207 @see SetPostProcSpecificOptionsL
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()."
212 virtual void CommitL() = 0;
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.
219 @see SetPostProcessTypesL
220 @see SetInputCropOptionsL
221 @see SetYuvToRgbOptionsL
222 @see SetRotateOptionsL
223 @see SetScaleOptionsL
224 @see SetOutputCropOptionsL
225 @see SetPostProcSpecificOptionsL
227 @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
229 virtual void Revert() = 0;
232 Starts writing output directly to the display frame buffer using Direct Screen Access.
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."
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()."
241 virtual void StartDirectScreenAccessL(const TRect& aVideoRect,
242 CFbsScreenDevice& aScreenDevice, const TRegion& aClipRegion) = 0;
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.
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()."
254 virtual void SetScreenClipRegion(const TRegion& aRegion) = 0;
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.
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()."
265 virtual void SetPauseOnClipFail(TBool aPause) = 0;
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()."
272 virtual void AbortDirectScreenAccess() = 0;
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.
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()."
281 virtual TBool IsPlaying() = 0;
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()."
288 virtual void Redraw() = 0;
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()."
296 virtual void Start() = 0;
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()."
302 virtual void Stop() = 0;
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()."
309 virtual void Pause() = 0;
312 Resumes video playback after a pause.
313 @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
315 virtual void Resume() = 0;
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
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()."
328 virtual void SetPosition(const TTimeIntervalMicroSeconds& aPlaybackPosition) = 0;
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.
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
339 @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
341 virtual void FreezePicture(const TTimeIntervalMicroSeconds& aTimestamp) = 0;
344 Releases a picture frozen with FreezePicture().
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()."
352 virtual void ReleaseFreeze(const TTimeIntervalMicroSeconds& aTimestamp) = 0;
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.
360 @return "Current playback position."
361 @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
363 virtual TTimeIntervalMicroSeconds PlaybackPosition() = 0;
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.
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()."
373 virtual TUint PictureBufferBytes() = 0;
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.
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".
383 @param "aCounters" "The counter structure to fill."
384 @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
386 virtual void GetPictureCounters(CMMFDevVideoPlay::TPictureCounters& aCounters) = 0;
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.
394 The complexity level can be changed at any point during playback.
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()."
401 virtual void SetComplexityLevel(TUint aLevel) = 0;
404 Gets the number of complexity levels available.
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
410 @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
412 virtual TUint NumComplexityLevels() = 0;
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.
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()."
425 virtual void GetComplexityLevelInfo(TUint aLevel, CMMFDevVideoPlay::TComplexityLevelInfo& aInfo) = 0;
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.
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()."
435 virtual void ReturnPicture(TVideoPicture* aPicture) = 0;
438 Gets a copy of the latest picture sent to output.
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
443 @param "aFormat" "The picture format to use for the snapshot."
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."
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()."
453 virtual TBool GetSnapshotL(TPictureData& aPictureData, const TUncompressedVideoFormat& aFormat) = 0;
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.
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."
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()."
473 virtual void GetTimedSnapshotL(TPictureData* aPictureData, const TUncompressedVideoFormat& aFormat,
474 const TTimeIntervalMicroSeconds& aPresentationTimestamp) = 0;
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.
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."
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()."
494 virtual void GetTimedSnapshotL(TPictureData* aPictureData, const TUncompressedVideoFormat& aFormat,
495 const TPictureId& aPictureId) = 0;
498 Cancels a timed snapshot request.
499 @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
501 virtual void CancelTimedSnapshot() = 0;
504 Gets a list of the supported snapshot picture formats.
506 @param "aFormats" "An array for the result format list. The array must be created and destroyed by
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()."
512 virtual void GetSupportedSnapshotFormatsL(RArray<TUncompressedVideoFormat>& aFormats) = 0;
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
525 After the remaining data has been processed (and displayed, if applicable), the hardware
526 device must notify the proxy with the MdvppStreamEnd() callback.
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.
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.
537 @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
539 virtual void InputEnd() = 0;
546 CMMFVideoDecodeHwDevice is the MSL video decoder hardware device interface.
547 All video decoders must implement this interface.
551 class CMMFVideoDecodeHwDevice : public CMMFVideoPlayHwDevice
555 Creates a new video decoder hardware device object, based on the implementation UID.
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.
562 IMPORT_C static CMMFVideoDecodeHwDevice* NewL(TUid aUid, MMMFDevVideoPlayProxy& aProxy);
565 Creates a new video decoder hardware device adapter object, based on the Implementation Information of a Processing Unit.
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."
572 IMPORT_C static CMMFVideoDecodeHwDevice* NewPuAdapterL(const CImplementationInformation& aImplInfo, MMMFDevVideoPlayProxy& aProxy);
578 IMPORT_C virtual ~CMMFVideoDecodeHwDevice();
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.
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."
590 @see CVideoDecoderInfo
592 virtual CVideoDecoderInfo* VideoDecoderInfoLC() = 0;
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."
610 virtual TVideoPictureHeader* GetHeaderInformationL(TVideoDataUnitType aDataUnitType,
611 TVideoDataUnitEncapsulation aEncapsulation, TVideoInputBuffer* aDataUnit) = 0;
615 Returns a header from GetHeaderInformationL() back to the decoder so that the memory can be freed.
617 @param "aHeader" "The header to return."
618 @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
620 virtual void ReturnHeader(TVideoPictureHeader* aHeader) = 0;
623 Sets the device input format to a compressed video format.
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."
633 @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
635 virtual void SetInputFormatL(const CCompressedVideoFormat& aFormat,
636 TVideoDataUnitType aDataUnitType, TVideoDataUnitEncapsulation aEncapsulation,
637 TBool aDataInOrder) = 0;
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.
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()."
649 virtual void SynchronizeDecoding(TBool aSynchronize) = 0;
652 Sets decoder buffering options. See [3] for a description of the options available.
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."
660 @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
662 virtual void SetBufferOptionsL(const CMMFDevVideoPlay::TBufferOptions& aOptions) = 0;
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).
669 @param "aOptions" "Buffering options structure to fill."
670 @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
672 virtual void GetBufferOptions(CMMFDevVideoPlay::TBufferOptions& aOptions) = 0;
675 Indicates which HRD/VBV specification is fulfilled in the input stream and any related parameters.
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
683 @see THrdVbvSpecification
684 @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
686 virtual void SetHrdVbvSpec(THrdVbvSpecification aHrdVbvSpec, const TDesC8& aHrdVbvParams) = 0;
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.
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()."
697 virtual void SetOutputDevice(CMMFVideoPostProcHwDevice* aDevice) = 0;
700 Returns the current decoding position, i.e. the timestamp for the most recently decoded picture.
702 @return "Current decoding position."
703 @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
705 virtual TTimeIntervalMicroSeconds DecodingPosition() = 0;
708 Returns the current pre-decoder buffer size.
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()."
713 virtual TUint PreDecoderBufferBytes() = 0;
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
720 @param "aCounters" "The counter structure to fill."
721 @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
723 virtual void GetBitstreamCounters(CMMFDevVideoPlay::TBitstreamCounters& aCounters) = 0;
726 Retrieves the number of free input buffers the decoder has available.
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()."
731 virtual TUint NumFreeBuffers() = 0;
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.
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.
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."
748 virtual TVideoInputBuffer* GetBufferL(TUint aBufferSize) = 0;
751 Writes a piece of coded video data to the decoder. The data buffer must be retrieved from the
752 decoder with GetBufferL().
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()."
758 virtual void WriteCodedDataL(TVideoInputBuffer* aBuffer) = 0;
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,
765 @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
767 virtual void ConfigureDecoderL(const TVideoPictureHeader& aVideoPictureHeader);
775 IMPORT_C CMMFVideoDecodeHwDevice();
778 Set the proxy implementation to be used. Called just after the object is constructed.
779 @param "aProxy" "The proxy to use."
781 virtual void SetProxy(MMMFDevVideoPlayProxy& aProxy) = 0;
788 CMMFVideoPostProcHwDevice is the MSL video post-processor plug-in interface. All MSL video
789 post-processors must implement this interface.
793 class CMMFVideoPostProcHwDevice : public CMMFVideoPlayHwDevice
797 Creates a new video post-processor hardware device object, based on the implementation UID.
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."
804 IMPORT_C static CMMFVideoPostProcHwDevice* NewL(TUid aUid, MMMFDevVideoPlayProxy& aProxy);
809 IMPORT_C virtual ~CMMFVideoPostProcHwDevice();
812 Sets the device input format to an uncompressed video format.
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()."
819 virtual void SetInputFormatL(const TUncompressedVideoFormat& aFormat) = 0;
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().
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()."
829 virtual void SetInputDevice(CMMFVideoDecodeHwDevice* aDevice) = 0;
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.
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()."
839 virtual void WritePictureL(TVideoPicture* aPicture) = 0;
844 IMPORT_C CMMFVideoPostProcHwDevice();
847 Set the proxy implementation to be used. Called just after the object is constructed.
848 @param "aProxy" "The proxy to use."
850 virtual void SetProxy(MMMFDevVideoPlayProxy& aProxy) = 0;
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.
864 class MMMFVideoPlayHwDeviceExtensionScanCopy
868 Writes a piece of coded video data to the decoder. The data buffer must be retrieved from the
869 decoder with GetBufferL().
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()."
876 virtual void WriteCodedDataL(TVideoInputBuffer* aBuffer, TFramePortion aPortion = EFramePortionUnknown) = 0;
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().
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()."
887 virtual void ScanAndCopyCodedDataL(TPtr8 aCodedData, TVideoInputBuffer* aBuffer, TInt& aConsumed, TFramePortion aPortion = EFramePortionUnknown) = 0;
890 inline void CMMFVideoDecodeHwDevice::ConfigureDecoderL(const TVideoPictureHeader& /*aVideoPictureHeader*/)
892 User::Leave(KErrNotSupported);