Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: videoplayhwdevice.h

This item is not part of the S60 3rd Edition SDK for Symbian OS, Feature Pack 2.

Class CMMFVideoPlayHwDevice

class CMMFVideoPlayHwDevice : public CMMFVideoHwDevice;

Description

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.

Derivation

Members

Defined in CMMFVideoPlayHwDevice:
AbortDirectScreenAccess(), CancelTimedSnapshot(), CommitL(), FreezePicture(), GetComplexityLevelInfo(), GetOutputFormatListL(), GetPictureCounters(), GetSnapshotL(), GetSupportedSnapshotFormatsL(), GetTimedSnapshotL(), GetTimedSnapshotL(), Initialize(), InputEnd(), IsPlaying(), NumComplexityLevels(), Pause(), PictureBufferBytes(), PlaybackPosition(), PostProcessorInfoLC(), Redraw(), ReleaseFreeze(), Resume(), ReturnPicture(), Revert(), SetClockSource(), SetComplexityLevel(), SetInputCropOptionsL(), SetOutputCropOptionsL(), SetOutputFormatL(), SetPauseOnClipFail(), SetPosition(), SetPostProcSpecificOptionsL(), SetPostProcessTypesL(), SetRotateOptionsL(), SetScaleOptionsL(), SetScreenClipRegion(), SetVideoDestScreenL(), SetYuvToRgbOptionsL(), SetYuvToRgbOptionsL(), Start(), StartDirectScreenAccessL(), Stop()

Inherited from CBase:
Delete(), Extension_(), operator new()

Inherited from CMMFVideoHwDevice:
CustomInterface()


Member functions


PostProcessorInfoLC()

virtual CPostProcessorInfo *PostProcessorInfoLC()=0;

Description

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 value

CPostProcessorInfo *

"Post-processor information as a CPostProcessorInfo object. The object is pushed to the cleanup stack, and must be deallocated by the caller."

Leave codes

"This

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


GetOutputFormatListL()

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

Pre-Condition

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

Description

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.

Parameters

RArray< TUncompressedVideoFormat > &aFormats

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

Leave codes

"This

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


SetOutputFormatL()

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

Pre-Condition

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

Description

Sets the device output format.

Parameters

const TUncompressedVideoFormat &aFormat

"The format to use."

Leave codes

"This

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


SetClockSource()

virtual void SetClockSource(MMMFClockSource *aClock)=0;

Pre-Condition

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

Description

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.

Parameters

MMMFClockSource *aClock

"The clock source to be used."


SetVideoDestScreenL()

virtual void SetVideoDestScreenL(TBool aScreen)=0;

Pre-Condition

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

Description

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.

Parameters

TBool aScreen

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

Leave codes

"This

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


SetPostProcessTypesL()

virtual void SetPostProcessTypesL(TUint32 aPostProcCombination)=0;

Pre-Condition

"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."

Description

Sets the post-processing types to be used.

Parameters

TUint32 aPostProcCombination

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

Leave codes

"This

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


SetInputCropOptionsL()

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

Pre-Condition

"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."

Description

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

Parameters

const TRect &aRect

"The cropping rectangle to use."

Leave codes

"This

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


SetYuvToRgbOptionsL()

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

Pre-Condition

"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."

Description

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.

Parameters

const TYuvToRgbOptions &aOptions

"The conversion options to use."

const TYuvFormat &aYuvFormat

"Conversion source YUV format"

TRgbFormat aRgbFormat

"Conversion target RGB format"

Leave codes

"This

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


SetYuvToRgbOptionsL()

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

Pre-Condition

"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."

Description

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.

Parameters

const TYuvToRgbOptions &aOptions

"The conversion options to use."

Leave codes

"This

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


SetRotateOptionsL()

virtual void SetRotateOptionsL(TRotationType aRotationType)=0;

Pre-Condition

"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."

Description

Sets post-processing options for rotation. SetPostProcessTypesL() must be called before this method is used.

Parameters

TRotationType aRotationType

"The rotation to perform."

Leave codes

"This

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


SetScaleOptionsL()

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

Pre-Condition

"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."

Description

Sets post-processing options for scaling. SetPostProcessTypesL() must be called before this method is used.

Parameters

const TSize &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."

TBool 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 codes

"This

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


SetOutputCropOptionsL()

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

Pre-Condition

"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."

Description

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

Parameters

const TRect &aRect

"Output cropping area."

Leave codes

"This

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


SetPostProcSpecificOptionsL()

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

Pre-Condition

"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."

Description

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

Parameters

const TDesC8 &aOptions

"The options. The format is plug-in specific."

Leave codes

"This

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


Initialize()

virtual void Initialize()=0;

Description

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.


CommitL()

virtual void CommitL()=0;

Pre-Condition

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

Description

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.

Leave codes

"The

method will leave if an error occurs."


Revert()

virtual void Revert()=0;

Pre-Condition

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

Description

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.


StartDirectScreenAccessL()

virtual void StartDirectScreenAccessL(const TRect &aVideoRect, CFbsScreenDevice &aScreenDevice, const TRegion &aClipRegion)=0;

Pre-Condition

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

Description

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

Parameters

const TRect &aVideoRect

"The video output rectangle on screen."

CFbsScreenDevice &aScreenDevice

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

const TRegion &aClipRegion

"Initial clipping region to use."

Leave codes

"This

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


SetScreenClipRegion()

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

Pre-Condition

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

Description

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.

Parameters

const TRegion &aRegion

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


SetPauseOnClipFail()

virtual void SetPauseOnClipFail(TBool aPause)=0;

Pre-Condition

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

Description

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.

Parameters

TBool 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."


AbortDirectScreenAccess()

virtual void AbortDirectScreenAccess()=0;

Pre-Condition

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

Description

Aborts Direct Screen Access completely, to be called from MAbortDirectScreenAccess::AbortNow() and similar methods. DSA can be resumed by calling StartDirectScreenAccessL().


IsPlaying()

virtual TBool IsPlaying()=0;

Pre-Condition

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

Description

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 value

TBool

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


Redraw()

virtual void Redraw()=0;

Pre-Condition

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

Description

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.


Start()

virtual void Start()=0;

Pre-Condition

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

Description

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.


Stop()

virtual void Stop()=0;

Pre-Condition

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

Description

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


Pause()

virtual void Pause()=0;

Pre-Condition

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

Description

Pauses video playback, including decoding, post-processing, and rendering. No pictures will be decoded, post-processed, or rendered until playback has been resumed.


Resume()

virtual void Resume()=0;

Pre-Condition

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

Description

Resumes video playback after a pause.


SetPosition()

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

Pre-Condition

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

Description

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.

Parameters

const TTimeIntervalMicroSeconds &aPlaybackPosition

"The new playback position in the video stream."


FreezePicture()

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

Pre-Condition

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

Description

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.

Parameters

const TTimeIntervalMicroSeconds &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."


ReleaseFreeze()

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

Pre-Condition

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

Description

Releases a picture frozen with FreezePicture().

Parameters

const TTimeIntervalMicroSeconds &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."


PlaybackPosition()

virtual TTimeIntervalMicroSeconds PlaybackPosition()=0;

Pre-Condition

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

Description

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 value

TTimeIntervalMicroSeconds

"Current playback position."


PictureBufferBytes()

virtual TUint PictureBufferBytes()=0;

Pre-Condition

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

Description

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 value

TUint

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


GetPictureCounters()

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

Pre-Condition

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

Description

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".

Parameters

CMMFDevVideoPlay::TPictureCounters &aCounters

"The counter structure to fill."


SetComplexityLevel()

virtual void SetComplexityLevel(TUint aLevel)=0;

Pre-Condition

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

Description

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.

Parameters

TUint 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."


NumComplexityLevels()

virtual TUint NumComplexityLevels()=0;

Pre-Condition

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

Description

Gets the number of complexity levels available.

Return value

TUint

"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."


GetComplexityLevelInfo()

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

Pre-Condition

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

Description

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.

Parameters

TUint aLevel

"The computational complexity level to query. The level numbers range from zero (the most complex) to NumComplexityLevels()-1."

CMMFDevVideoPlay::TComplexityLevelInfo &aInfo

"The information structure to fill."


ReturnPicture()

virtual void ReturnPicture(TVideoPicture *aPicture)=0;

Pre-Condition

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

Description

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.

Parameters

TVideoPicture *aPicture

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


GetSnapshotL()

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

Pre-Condition

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

Description

Gets a copy of the latest picture sent to output.

Parameters

TPictureData &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."

const TUncompressedVideoFormat &aFormat

"The picture format to use for the snapshot."

Return value

TBool

"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 codes

"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."


GetTimedSnapshotL()

virtual void GetTimedSnapshotL(TPictureData *aPictureData, const TUncompressedVideoFormat &aFormat, const TTimeIntervalMicroSeconds &aPresentationTimestamp)=0;

Pre-Condition

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

Description

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.

Parameters

TPictureData *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()."

const TUncompressedVideoFormat &aFormat

"The picture format to use for the snapshot."

const TTimeIntervalMicroSeconds &aPresentationTimestamp

"Presentation timestamp for the picture to copy."

Leave codes

"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."


GetTimedSnapshotL()

virtual void GetTimedSnapshotL(TPictureData *aPictureData, const TUncompressedVideoFormat &aFormat, const TPictureId &aPictureId)=0;

Pre-Condition

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

Description

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.

Parameters

TPictureData *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()."

const TUncompressedVideoFormat &aFormat

"The picture format to use for the snapshot."

const TPictureId &aPictureId

"Picture identifier for the picture to copy."

Leave codes

"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."


CancelTimedSnapshot()

virtual void CancelTimedSnapshot()=0;

Pre-Condition

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

Description

Cancels a timed snapshot request.


GetSupportedSnapshotFormatsL()

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

Pre-Condition

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

Description

Gets a list of the supported snapshot picture formats.

Parameters

RArray< TUncompressedVideoFormat > &aFormats

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

Leave codes

"This

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


InputEnd()

virtual void InputEnd()=0;

Pre-Condition

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

Description

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 processing. For synchronized playback, all video pictures are processed or discarded according to their timestamps, and so the client can easily infer when processing is complete. However, it should be noted that the last picture might not be displayed if this method is not called and the input data type is not EDuCodedPicture.

For non-synchronized playback (e.g. file conversion), a client must call this method otherwise it will never find out when the hardware device has finished processing the data.