// Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// which accompanies this distribution, and is available

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

#ifndef __VIDEOPLAYHWDEVICE_H__

#define __VIDEOPLAYHWDEVICE_H__

#include <mmf/devvideo/devvideobase.h>

#include <mmf/devvideo/devvideoplay.h>

/**

A base class for all video playback (decoder and post-processor) hardware devices. 

Since both decoders and post-processors can implement post-processing functionality, 

this class includes all post-processing related methods. The main difference between decoder 

and post-processor devices is that decoders can input coded data and write decoded pictures 

to another device, while post-processor devices can accept decoded pictures from the client 

or from another device.

@publishedAll

@released

*/

class CMMFVideoPlayHwDevice : public CMMFVideoHwDevice

	{

public:

	/**

	Retrieves post-processing information about this hardware device. 

	The device creates a CPostProcessorInfo structure, fills it with correct data, pushes it 

	to the cleanup stack and returns it. The client will delete the object when it is no 

	longer needed.

	@return "Post-processor information as a CPostProcessorInfo object. 

			The object is pushed to the cleanup stack, and must be deallocated by the caller."

	@leave  "This method may leave with one of the system-wide error codes.

	*/

	virtual CPostProcessorInfo* PostProcessorInfoLC() = 0;

	/**

	Retrieves the list of the output formats that the device supports. The list is ordered in 

	plug-in preference order, with the preferred formats at the beginning of the list. The list 

	can depend on the device source format, and therefore SetSourceFormatL() must be called before 

	calling this method.

	@param "aFormats" "An array for the result format list. The array must be created and destroyed by the caller."

	@leave  "This method may leave with one of the system-wide error codes.

	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."

	*/

	virtual void GetOutputFormatListL(RArray<TUncompressedVideoFormat>& aFormats) = 0;

	/**

	Sets the device output format.

	@param  "aFormat" "The format to use."

	@leave  "This method may leave with one of the system-wide error codes.

	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."

	*/

	virtual void SetOutputFormatL(const TUncompressedVideoFormat &aFormat) = 0;

	/**

	Sets the clock source to use for video timing. If no clock source is set. video playback 

	will not be synchronized, but will proceed as fast as possible, depending on input data 

	and output buffer availability.	

	@param  "aClock" "The clock source to be used."

	@pre	"This method can only be called before the hwdevice has been initialized with Initialize()."

	*/

	virtual void SetClockSource(MMMFClockSource* aClock) = 0;

	/**

	Sets the device video output destination. The destination can be the screen (using direct 

	screen access) or memory buffers. By default memory buffers are used. If data is written 

	to another device, this method is ignored, and suitable memory buffers are always used.

	@param  "aScreen" "True if video output destination is the screen, false if memory buffers."

	@leave  "This method may leave with one of the system-wide error codes.

	@pre	"This method can only be called before the hwdevice has been initialized with Initialize()."

	*/

	virtual void SetVideoDestScreenL(TBool aScreen) = 0;

	/**

	Sets the post-processing types to be used.

	@param  "aPostProcCombination" "The post-processing steps to perform, a bitwise OR of values from TPostProcessType."

	@leave  "This method may leave with one of the system-wide error codes.

	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().

			If called after initialization, the change must only be committed when CommitL() is called."

	*/

	virtual void SetPostProcessTypesL(TUint32 aPostProcCombination) = 0;

	/**

	Sets post-processing options for input (pan-scan) cropping.

	@param  "aRect" "The cropping rectangle to use."

	@leave  "This method may leave with one of the system-wide error codes.

	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().

			If called after initialization, the change must only be committed when CommitL() is called."

	*/

	virtual void SetInputCropOptionsL(const TRect& aRect) = 0;

	/**

	Sets post-processing options for YUV to RGB color space conversion. 

	Specifies the input YUV and output RGB formats to use explicitly. SetSourceFormatL(), 

	SetOutputFormatL(), and SetPostProcessTypesL() must be called before this method is used.

	@param  "aOptions"		"The conversion options to use."

	@param  "aYuvFormat"	"Conversion source YUV format"

	@param  "aRgbFormat"	"Conversion target RGB format"

	@leave  "This method may leave with one of the system-wide error codes.

	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().

			If called after initialization, the change must only be committed when CommitL() is called."

	*/

	virtual void SetYuvToRgbOptionsL(const TYuvToRgbOptions& aOptions, const TYuvFormat& aYuvFormat, TRgbFormat aRgbFormat) = 0;

	/**

	Sets post-processing options for YUV to RGB color space conversion.

	Uses the device input and output formats. For decoder devices the default YUV format used is 

	the format specified in the input bitstream. SetSourceFormatL(), SetOutputFormatL(), and 

	SetPostProcessTypesL() must be called before this method is used.

	@param  "aOptions"		"The conversion options to use."

	@leave  "This method may leave with one of the system-wide error codes.

	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().

			If called after initialization, the change must only be committed when CommitL() is called."

	*/

	virtual void SetYuvToRgbOptionsL(const TYuvToRgbOptions& aOptions) = 0;

	/**

	Sets post-processing options for rotation. SetPostProcessTypesL() must be called before 

	this method is used.

	@param  "aRotationType" "The rotation to perform."	

	@leave  "This method may leave with one of the system-wide error codes.

	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().

			If called after initialization, the change must only be committed when CommitL() is called."

	*/

	virtual void SetRotateOptionsL(TRotationType aRotationType) = 0;

	/**

	Sets post-processing options for scaling. SetPostProcessTypesL() must be called before 

	this method is used.

	@param  "aTargetSize"			"Scaling target size. If a fixed scale factor size is used, 

									the new dimensions must be set to width=floor(factor*width), 

									height=floor(factor*height). For example, scaling a 

									QCIF (176x144) picture up by a factor of 4/3 yields a size 

									of 234x192."

	@param  "aAntiAliasFiltering"	"True if anti-aliasing filtering should be used. 

									If the post-processor does not support anti-aliased scaling, 

									or supports anti-aliased scaling only, this argument is ignored."

	@leave  "This method may leave with one of the system-wide error codes.

	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().

			If called after initialization, the change must only be committed when CommitL() is called."

	*/

	virtual void SetScaleOptionsL(const TSize& aTargetSize, TBool aAntiAliasFiltering) = 0;

	/**

	Sets post-processing options for output cropping. SetPostProcessTypesL() must be called before 

	this method is used.

	@param  "aRect" "Output cropping area."

	@leave  "This method may leave with one of the system-wide error codes.

	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().

			If called after initialization, the change must only be committed when CommitL() is called."

	*/

	virtual void SetOutputCropOptionsL(const TRect& aRect) = 0;

	/**

	Sets post-processing plug-in specific options. SetPostProcessTypesL() must be called before 

	this method is used.

	@param  "aOptions" "The options. The format is plug-in specific."

	@leave  "This method may leave with one of the system-wide error codes.

	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().

			If called after initialization, the change must only be committed when CommitL() is called."

	*/

	virtual void SetPostProcSpecificOptionsL(const TDesC8& aOptions) = 0;

	/**

	Initializes the device. This method is asynchronous, the device will call 

	MMFVideoPlayProxy::MdvppInitializeComplete() after initialization has completed. After this 

	method has successfully completed, further configuration changes are not possible except where 

	separately noted.

	*/

	virtual void Initialize() = 0;

	/**

	Commit all changes since the last CommitL(), Revert() or Initialize()

	to the hardware device.  This only applies to methods which can be called both

	before AND after DevVideoPlay has been initialized.

	@see	SetPostProcessTypesL

	@see	SetInputCropOptionsL

	@see	SetYuvToRgbOptionsL

	@see	SetRotateOptionsL

	@see	SetScaleOptionsL

	@see	SetOutputCropOptionsL

	@see	SetPostProcSpecificOptionsL

	@leave  "The method will leave if an error occurs."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void CommitL() = 0;

	/**

	Revert all changes since the last CommitL(), Revert() or Initialize()

	back to their previous settings.  This only applies to methods which can 

	be called both before AND after DevVideoPlay has been initialized.

	@see	SetPostProcessTypesL

	@see	SetInputCropOptionsL

	@see	SetYuvToRgbOptionsL

	@see	SetRotateOptionsL

	@see	SetScaleOptionsL

	@see	SetOutputCropOptionsL

	@see	SetPostProcSpecificOptionsL

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void Revert() = 0;

	/**

	Starts writing output directly to the display frame buffer using Direct Screen Access.

	@param  "aVideoRect"	"The video output rectangle on screen."

	@param  "aScreenDevice"	"The screen device to use. The screen device object must be valid in the current thread."

	@param  "aClipRegion"	"Initial clipping region to use."

	@leave  "This method may leave with one of the system-wide error codes.

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void StartDirectScreenAccessL(const TRect& aVideoRect, 

		CFbsScreenDevice& aScreenDevice, const TRegion& aClipRegion) = 0;

	/**

	Sets a new clipping region for Direct Screen Access. After the method returns, no video will 

	be drawn outside of the region. If clipping is not supported, or the clipping region is too 

	complex, either playback will pause or will resume without video display, depending on the 

	current setting of SetPauseOnClipFail(), and the result can be verified with IsPlaying(). 

	Clipping can be disabled by setting a new clipping region that includes the whole video window.

	@param  "aRegion" "The new clipping region. After the method returns, no video will be drawn outside the region."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void SetScreenClipRegion(const TRegion& aRegion) = 0;

	/**

	Sets whether the system should pause playback when it gets a clipping region it cannot handle, 

	or Direct Screen Access is aborted completely. If not, processing will proceed normally, but no 

	video will be drawn. By default, playback is paused.

	@param "aPause" "True if playback should be paused when clipping fails, false if not. 

					If playback is not paused, it will be continued without video display."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void SetPauseOnClipFail(TBool aPause) = 0;

	/**

	Aborts Direct Screen Access completely, to be called from MAbortDirectScreenAccess::AbortNow() 

	and similar methods. DSA can be resumed by calling StartDirectScreenAccessL().

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void AbortDirectScreenAccess() = 0;

	/**

	Indicates whether playback is proceeding. This method can be used to check whether playback was 

	paused or not in response to a new clipping region or DSA abort.

	@return "ETrue if video is still being played (even if not necessarily displayed)."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual TBool IsPlaying() = 0;

	/**

	Re-draws the latest video picture. Only available when DSA is being used. If DSA is aborted or a 

	non-supported clipping region has been set, the request may be ignored.

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void Redraw() = 0;

	/**

	Starts video playback, including decoding, post-processing, and rendering. Playback will proceed 

	until it has been stopped or paused, or the end of the bitstream is reached.

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void Start() = 0;

	/**

	Stops video playback. No new pictures will be decoded, post-processed, or rendered.

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void Stop() = 0;

	/**

	Pauses video playback, including decoding, post-processing, and rendering. No pictures will be 

	decoded, post-processed, or rendered until playback has been resumed.

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void Pause() = 0;

	/**

	Resumes video playback after a pause.

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void Resume() = 0;

	/**

	Changes to a new decoding and playback position, used for randomly accessing (seeking) the 

	input stream. The position change flushes all input and output buffers. Pre-decoder and 

	post-decoder buffering are handled as if a new bitstream was being decoded. If the device still has buffered 

	pictures that precede the new playback position, they will be discarded. If playback is 

	synchronized to a clock source, the client is responsible for setting the clock source to the 

	new position.

	@param "aPlaybackPosition" "The new playback position in the video stream."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void SetPosition(const TTimeIntervalMicroSeconds& aPlaybackPosition) = 0;

	/**

	Freezes a picture on the screen. After the picture has been frozen, no new pictures are 

	displayed until the freeze is released with ReleaseFreeze(). If the device output is being 

	written to memory buffers or to another plug-in, instead of the screen, no decoded pictures 

	will be delivered while the freeze is active, and they are simply discarded.

	@param "aTimestamp" "The presentation timestamp of the picture to freeze. The frozen picture 

						will be the first picture with a timestamp greater than or equal to this 

						parameter."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void FreezePicture(const TTimeIntervalMicroSeconds& aTimestamp) = 0;

	/**

	Releases a picture frozen with FreezePicture().

	@param "aTimestamp" "The presentation timestamp of the picture to release. The first picture 

						displayed after the release will be the first picture with a timestamp 

						greater than or equal to this parameter. To release the freeze immediately, 

						set the timestamp to zero."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void ReleaseFreeze(const TTimeIntervalMicroSeconds& aTimestamp) = 0;

	/**

	Returns the current playback position, i.e. the timestamp for the most recently displayed or 

	virtually displayed picture. If the device output is written to another device, the most recent 

	output picture is used.

	@return "Current playback position."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual TTimeIntervalMicroSeconds PlaybackPosition() = 0;

	/**

	Returns the total amount of memory allocated for uncompressed pictures. This figure only 

	includes the pictures actually allocated by the plug-in itself, so that the total number of 

	bytes allocated in the system can be calculated by taking the sum of the values from all plug-ins.

	@return "Total number of bytes of memory allocated for uncompressed pictures."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual TUint PictureBufferBytes() = 0;

	/**

	Reads various counters related to decoded pictures. The counters are reset when Initialize() 

	or this method is called, and thus they only include pictures processed since the last call.

	Post-processor devices return the number of input pictures in iPicturesDecoded and 

	iTotalPictures. If the decoded pictures are written to another plug-in, they are considered 

	to be "virtually displayed".

	@param "aCounters" "The counter structure to fill."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void GetPictureCounters(CMMFDevVideoPlay::TPictureCounters& aCounters) = 0;

	/**

	Sets the computational complexity level to use. If separate complexity levels are not available, 

	the method call is ignored. If the level specified is not available, the results are undefined. 

	Typically the device will either ignore the request or use the nearest suitable level.

	The complexity level can be changed at any point during playback.

	@param "aLevel" "The computational complexity level to use. Level zero (0) is the most complex 

					one, with the highest quality. Higher level numbers require less processing 

					and may have lower quality."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void SetComplexityLevel(TUint aLevel) = 0;

	/**

	Gets the number of complexity levels available.

	@return "The number of complexity control levels available, or zero if the information is not 

			available yet. The information may not be available if the number of levels depends on 

			the input data, and enough input data has not been read yet. In that case, using level 

			zero is safe."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual TUint NumComplexityLevels() = 0;

	/**

	Gets information about a computational complexity level. This method can be called after 

	NumComplexityLevels() has returned a non-zero value - at that point the information is guaranteed 

	to be available. Some hardware device implementations may not be able to provide all values, 

	in that case the values will be approximated.

	@param "aLevel"	"The computational complexity level to query. The level numbers range from zero 

					(the most complex) to NumComplexityLevels()-1."

	@param "aInfo"	"The information structure to fill."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void GetComplexityLevelInfo(TUint aLevel, CMMFDevVideoPlay::TComplexityLevelInfo& aInfo) = 0;

	/**

	Returns a picture back to the device. This method is called by CMMFDevVideoPlay to return pictures 

	from the client (after they have been written with NewPicture()), or by the output device when 

	it has finished using a picture.

	@param "aPicture" "The picture to return. The device can re-use the memory for the picture."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void ReturnPicture(TVideoPicture* aPicture) = 0;

	/**

	Gets a copy of the latest picture sent to output.

	@param "aPictureData"	"Target picture. The memory for the picture must be allocated by the 

							caller, and initialized properly. The data formats must match the snapshot 

							format requested."

	@param "aFormat"		"The picture format to use for the snapshot."

	@return "ETrue if the snapshot was taken, EFalse if a picture is not available. The picture may not 

			be available if decoding has not progressed far enough yet."

	@leave	"The method will leave if an error occurs. Typical error codes used:

			* KErrNotSupported - The requested data format or picture size is not supported, or the 

			plug-in does not support snapshots."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual TBool GetSnapshotL(TPictureData& aPictureData, const TUncompressedVideoFormat& aFormat) = 0;

	/**

	When the snapshot is available, it will be returned to the client using the TimedSnapshotComplete()

	callback. To cancel a timed snapshot request, use CancelTimedSnapshot(). Only one timed snapshot 

	request can be active at a time.

	@param "aPictureData"			"Target picture. The memory for the picture must be allocated by 

									the caller, and initialized properly. The data formats must match 

									the snapshot format requested. The picture must remain valid until 

									the snapshot has been taken or until the request has been cancelled 

									with CancelTimedSnapshot()."

	@param "aFormat"				"The picture format to use for the snapshot."

	@param "aPresentationTimestamp"	"Presentation timestamp for the picture to copy."

	@leave	"The method will leave if an error occurs. Typical error codes used:

			* KErrNotSupported - The requested data format or picture size is not supported or 

			the plug-in does not support timed snapshots."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void GetTimedSnapshotL(TPictureData* aPictureData, const TUncompressedVideoFormat& aFormat, 

		const TTimeIntervalMicroSeconds& aPresentationTimestamp) = 0;

	/**

	When the snapshot is available, it will be returned to the client using the TimedSnapshotComplete()

	callback. To cancel a timed snapshot request, use CancelTimedSnapshot(). Only one timed snapshot 

	request can be active at a time.

	@param "aPictureData"			"Target picture. The memory for the picture must be allocated by 

									the caller, and initialized properly. The data formats must match 

									the snapshot format requested. The picture must remain valid until 

									the snapshot has been taken or until the request has been cancelled 

									with CancelTimedSnapshot()."

	@param "aFormat"				"The picture format to use for the snapshot."

	@param "aPictureId"				"Picture identifier for the picture to copy."

	@leave	"The method will leave if an error occurs. Typical error codes used:

			* KErrNotSupported - The requested data format or picture size is not supported or 

			the plug-in does not support timed snapshots."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void GetTimedSnapshotL(TPictureData* aPictureData, const TUncompressedVideoFormat& aFormat, 

		const TPictureId& aPictureId) = 0;

	/**

	Cancels a timed snapshot request.

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void CancelTimedSnapshot() = 0;

	/**

	Gets a list of the supported snapshot picture formats.

	@param "aFormats" "An array for the result format list. The array must be created and destroyed by 

	the caller."

	@leave "This method may leave with one of the standard error codes."

	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."

	*/

	virtual void GetSupportedSnapshotFormatsL(RArray<TUncompressedVideoFormat>& aFormats) = 0;

	/**

	Notifies the hardware device that the end of input data has been reached and no more input data 

	will be written. The hardware device can use this signal to ensure that the remaining data gets 

	processed, without waiting for new data. For example when the data type is not EDuCodedPicture,

	calling this method is necessary otherwise a hardware device implementation might be looking for 

	the start code for the next picture to ensure it has a complete picture before starting to decode

	the previous one. 

	After the remaining data has been processed (and displayed, if applicable), the hardware 

	device must notify the proxy with the MdvppStreamEnd() callback.

	DevVideo clients are encouraged to call this method, but its use is not mandatory for synchronized