sl@0: // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: //
sl@0: 
sl@0: #ifndef DEVVIDEOPLAYRATECUSTOMINTERFACE_H
sl@0: #define DEVVIDEOPLAYRATECUSTOMINTERFACE_H
sl@0: 
sl@0: #include <mmf/common/mmfvideo.h>
sl@0: #ifdef SYMBIAN_ENABLE_SPLIT_HEADERS
sl@0: #include <mmf/common/mmfvideoenums.h>
sl@0: #endif
sl@0: 
sl@0: /**
sl@0: MMmfVideoPlayRateControl interface UID.
sl@0: 
sl@0: @publishedPartner
sl@0: @released
sl@0: */
sl@0: const TUid KUidMmfVideoPlayRateControl = { 0x10285D3C };
sl@0: 
sl@0: /**
sl@0: Video play rate observer that is used with the MMmfVideoPlayRateControl 
sl@0: custom interface. Controllers or other DevVideo clients using that custom
sl@0: interface must implement this observer interface.
sl@0: 
sl@0: @publishedPartner
sl@0: @released
sl@0: */
sl@0: class MMmfVideoPlayRateObserver
sl@0: 	{
sl@0: public:
sl@0: 	/**
sl@0: 	Indicates that a step frame request has been completed. This callback is a 
sl@0: 	response to an MmvprcStepFrameL() call.
sl@0: 
sl@0: 	@param aTimestamp The timestamp for the frame that was actually rendered as
sl@0: 			a result of the frame step operation
sl@0: 	*/
sl@0: 	virtual void MmvproStepFrameComplete(TTimeIntervalMicroSeconds aTimestamp) = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Requests that the controller should only pass key frames to DevVideo.
sl@0: 	The key frame mode will be in operation until normal playback is resumed.
sl@0: 	*/
sl@0: 	virtual void MmvproKeyFrameModeRequest() = 0;
sl@0: };
sl@0: 
sl@0: /**
sl@0: Video play rate control custom interface. Controllers or other DevVideo clients
sl@0: can use this interface for trick play control.
sl@0: 
sl@0: Note that both decoders and post-processors can implement this interface. Clients 
sl@0: must query both the decoder and the post-processor (if in use) for the custom 
sl@0: interface, and call methods on both if they implement the interface. At least 
sl@0: the rendering media device (typically the post-processor) must implement this 
sl@0: interface for playback rate control to be available.
sl@0: 
sl@0: Additionally, the timestamp returned from the clock source must reflect the 
sl@0: playback speed. For example, for 200% fast forward, the timestamps returned must 
sl@0: increase at two times the normal speed.
sl@0: 
sl@0: @publishedPartner
sl@0: @released
sl@0: */
sl@0: class MMmfVideoPlayRateControl
sl@0: 	{
sl@0: public:
sl@0: 	/**
sl@0: 	Queries the current video playback rate capabilities. The capabilities
sl@0: 	describe whether fast forward, reverse playback, slow motion, or
sl@0: 	step backward or forward is possible. The capabilities may depend on
sl@0: 	the video decoder / post processor implementation and the video stream. 
sl@0: 
sl@0: 	If an error occurs, this function leaves with any of the system wide error codes.
sl@0: 
sl@0: 	@param aCapabilities Playback rate capabilities
sl@0: 	*/
sl@0: 	virtual void MmvprcGetPlayRateCapabilitiesL(TVideoPlayRateCapabilities& aCapabilities) = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Set video playback rate relative to the normal video stream speed.
sl@0: 	This method can be used for fast forward, rewind, and slow-motion
sl@0: 	playback, depending on the capabilities of the underlying video 
sl@0: 	decoder / post processor implementation and the characteristics of 
sl@0: 	the video stream. Rate set in this call will take effect immediately. 
sl@0: 	Use	MmvprcGetPlayRateCapabilitiesL() to determine what playback modes 
sl@0: 	are	available.
sl@0: 
sl@0: 	Note that due to performance reasons, it may not be possible to perform
sl@0: 	fast forward or rewind at the requested speed. If that happens, the
sl@0: 	video decoder / post processor will use the nearest available rate. This is not
sl@0: 	considered an error and the method will not leave. DevVideo clients can query
sl@0: 	rate in effect by calling MmvprcPlayRateL().
sl@0: 
sl@0: 	The default playback rate is 100.
sl@0: 	Play rate is persistent across stop start calls on DevVideo. 
sl@0: 
sl@0: 	If an error occurs, this function leaves with any of the system wide error codes.
sl@0: 	Common error codes are listed below.
sl@0: 
sl@0: 	@param aRate Playback rate as a percentage relative to the
sl@0:                  normal video stream speed. Use 100 for normal-speed
sl@0:                  forward playback and negative value for reverse. Values above
sl@0:                  100 and below 0 correspond to fast forward and
sl@0:                  rewind respectively, while values 1 to 100 represent
sl@0:                  slow-motioned playback.
sl@0: 
sl@0: 	@pre Playback has been started, but may be paused.
sl@0: 
sl@0: 	@see MMmfVideoPlayRateControl::MmvprcGetPlayRateCapabilitiesL()
sl@0: 
sl@0: 	@leave KErrNotSupported The requested playback rate is not supported.
sl@0: 	@leave KErrNotReady Playback has not yet been started
sl@0: 	*/
sl@0: 	virtual void MmvprcSetPlayRateL(const TInt aRate) = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Returns the current playback rate. If setting play rate is
sl@0: 	not supported or rate is not set this will return default play rate
sl@0: 	100 corresponding to normal playback.
sl@0: 
sl@0: 	If implementation is not supporting the rate set with MmvprcSetPlayRateL
sl@0: 	it will default to the nearest rate. In this case this API will return
sl@0: 	the value it has defaulted to.
sl@0: 
sl@0: 	If an error occurs, this function leaves with any of the system
sl@0: 	wide error codes. Common error codes are listed below.
sl@0: 
sl@0: 	@return The current playback rate as a percentage relative to the
sl@0:         	normal video stream speed.
sl@0: 
sl@0: 	@pre Playback has been started, but may be paused.
sl@0: 
sl@0: 	@see MMmfVideoPlayRateControl::MmvprcGetPlayRateCapabilitiesL()
sl@0: 	@see MMmfVideoPlayRateControl::MmvprcSetPlayRateL()
sl@0: 
sl@0: 	@leave KErrNotReady Playback has not yet been started
sl@0: 	*/
sl@0: 	virtual TInt MmvprcPlayRateL() = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Steps the current video playback position forward or backward by a
sl@0: 	number of frames. Frame step is only available when playback is paused.
sl@0: 
sl@0: 	Support for frame stepping may depend on the underlying video decoder / 
sl@0: 	post processor implementation and the video stream open. Use 
sl@0: 	MmvprcGetPlayRateCapabilitiesL() to query if frame step is currently possible. 
sl@0: 
sl@0: 	Implementations may not be able to step exactly the number of frames
sl@0: 	requested, especially when stepping backwards. If this happens, the
sl@0: 	video decoder / post processor will step to a frame close to the one requested. 
sl@0: 	This is	not considered an error.
sl@0: 
sl@0: 	If an error occurs, this function leaves with any of the system wide error codes.
sl@0: 	Common error codes are listed below.
sl@0: 
sl@0: 	@param aStep The number of frames to step. Use positive values for
sl@0:              stepping forward and negative values for stepping back.
sl@0: 
sl@0: 	@pre Playback has been started and is currently paused. That means this API 
sl@0: 			can be called only in paused state.
sl@0: 
sl@0: 	@see MMmfVideoPlayRateControl::MmvprcGetPlayRateCapabilitiesL()
sl@0: 
sl@0: 	@leave KErrNotSupported Frame step is not supported. Note that some
sl@0:          	implementations may support step forward but not step backward.
sl@0: 	@leave KErrNotReady Playback has not yet been started or is not in paused state.
sl@0: 	*/
sl@0: 	virtual void MmvprcStepFrameL(const TInt aStep) = 0;
sl@0: 
sl@0: 	/**
sl@0: 	Sets a play rate observer
sl@0: 
sl@0: 	@param aObserver Play rate observer
sl@0: 	*/
sl@0: 	virtual void MmvprcSetObserver(MMmfVideoPlayRateObserver& aObserver) = 0;
sl@0: 	};
sl@0: 
sl@0: #endif // DEVVIDEOPLAYRATECUSTOMINTERFACE_H