// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
//

#ifndef DEVVIDEOPLAYRATECUSTOMINTERFACE_H
#define DEVVIDEOPLAYRATECUSTOMINTERFACE_H

#include <mmf/common/mmfvideo.h>
#ifdef SYMBIAN_ENABLE_SPLIT_HEADERS
#include <mmf/common/mmfvideoenums.h>
#endif

/**
MMmfVideoPlayRateControl interface UID.

@publishedPartner
@released
*/
const TUid KUidMmfVideoPlayRateControl = { 0x10285D3C };

/**
Video play rate observer that is used with the MMmfVideoPlayRateControl 
custom interface. Controllers or other DevVideo clients using that custom
interface must implement this observer interface.

@publishedPartner
@released
*/
class MMmfVideoPlayRateObserver
	{
public:
	/**
	Indicates that a step frame request has been completed. This callback is a 
	response to an MmvprcStepFrameL() call.

	@param aTimestamp The timestamp for the frame that was actually rendered as
			a result of the frame step operation
	*/
	virtual void MmvproStepFrameComplete(TTimeIntervalMicroSeconds aTimestamp) = 0;

	/**
	Requests that the controller should only pass key frames to DevVideo.
	The key frame mode will be in operation until normal playback is resumed.
	*/
	virtual void MmvproKeyFrameModeRequest() = 0;
};

/**
Video play rate control custom interface. Controllers or other DevVideo clients
can use this interface for trick play control.

Note that both decoders and post-processors can implement this interface. Clients 
must query both the decoder and the post-processor (if in use) for the custom 
interface, and call methods on both if they implement the interface. At least 
the rendering media device (typically the post-processor) must implement this 
interface for playback rate control to be available.

Additionally, the timestamp returned from the clock source must reflect the 
playback speed. For example, for 200% fast forward, the timestamps returned must 
increase at two times the normal speed.

@publishedPartner
@released
*/
class MMmfVideoPlayRateControl
	{
public:
	/**
	Queries the current video playback rate capabilities. The capabilities
	describe whether fast forward, reverse playback, slow motion, or
	step backward or forward is possible. The capabilities may depend on
	the video decoder / post processor implementation and the video stream. 

	If an error occurs, this function leaves with any of the system wide error codes.

	@param aCapabilities Playback rate capabilities
	*/
	virtual void MmvprcGetPlayRateCapabilitiesL(TVideoPlayRateCapabilities& aCapabilities) = 0;

	/**
	Set video playback rate relative to the normal video stream speed.
	This method can be used for fast forward, rewind, and slow-motion
	playback, depending on the capabilities of the underlying video 
	decoder / post processor implementation and the characteristics of 
	the video stream. Rate set in this call will take effect immediately. 
	Use	MmvprcGetPlayRateCapabilitiesL() to determine what playback modes 
	are	available.

	Note that due to performance reasons, it may not be possible to perform
	fast forward or rewind at the requested speed. If that happens, the
	video decoder / post processor will use the nearest available rate. This is not
	considered an error and the method will not leave. DevVideo clients can query
	rate in effect by calling MmvprcPlayRateL().

	The default playback rate is 100.
	Play rate is persistent across stop start calls on DevVideo. 

	If an error occurs, this function leaves with any of the system wide error codes.
	Common error codes are listed below.

	@param aRate Playback rate as a percentage relative to the
                 normal video stream speed. Use 100 for normal-speed
                 forward playback and negative value for reverse. Values above
                 100 and below 0 correspond to fast forward and
                 rewind respectively, while values 1 to 100 represent
                 slow-motioned playback.

	@pre Playback has been started, but may be paused.

	@see MMmfVideoPlayRateControl::MmvprcGetPlayRateCapabilitiesL()

	@leave KErrNotSupported The requested playback rate is not supported.
	@leave KErrNotReady Playback has not yet been started
	*/
	virtual void MmvprcSetPlayRateL(const TInt aRate) = 0;

	/**
	Returns the current playback rate. If setting play rate is
	not supported or rate is not set this will return default play rate
	100 corresponding to normal playback.

	If implementation is not supporting the rate set with MmvprcSetPlayRateL
	it will default to the nearest rate. In this case this API will return
	the value it has defaulted to.

	If an error occurs, this function leaves with any of the system
	wide error codes. Common error codes are listed below.

	@return The current playback rate as a percentage relative to the
        	normal video stream speed.

	@pre Playback has been started, but may be paused.

	@see MMmfVideoPlayRateControl::MmvprcGetPlayRateCapabilitiesL()
	@see MMmfVideoPlayRateControl::MmvprcSetPlayRateL()

	@leave KErrNotReady Playback has not yet been started
	*/
	virtual TInt MmvprcPlayRateL() = 0;

	/**
	Steps the current video playback position forward or backward by a
	number of frames. Frame step is only available when playback is paused.

	Support for frame stepping may depend on the underlying video decoder / 
	post processor implementation and the video stream open. Use 
	MmvprcGetPlayRateCapabilitiesL() to query if frame step is currently possible. 

	Implementations may not be able to step exactly the number of frames
	requested, especially when stepping backwards. If this happens, the
	video decoder / post processor will step to a frame close to the one requested. 
	This is	not considered an error.

	If an error occurs, this function leaves with any of the system wide error codes.
	Common error codes are listed below.

	@param aStep The number of frames to step. Use positive values for
             stepping forward and negative values for stepping back.

	@pre Playback has been started and is currently paused. That means this API 
			can be called only in paused state.

	@see MMmfVideoPlayRateControl::MmvprcGetPlayRateCapabilitiesL()

	@leave KErrNotSupported Frame step is not supported. Note that some
         	implementations may support step forward but not step backward.
	@leave KErrNotReady Playback has not yet been started or is not in paused state.
	*/
	virtual void MmvprcStepFrameL(const TInt aStep) = 0;

	/**
	Sets a play rate observer

	@param aObserver Play rate observer
	*/
	virtual void MmvprcSetObserver(MMmfVideoPlayRateObserver& aObserver) = 0;
	};

#endif // DEVVIDEOPLAYRATECUSTOMINTERFACE_H