epoc32/include/mmf/devvideo/videoplayhwdevice.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     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