CMMFDevVideoPlay Class Reference

Destructor.

Commit all configuration changes since the last CommitL(), Revert() or Initialize(). This only applies to methods that can be called both before AND after DevVideoPlay has been initialized. See the following methods for details.

See also: SetPostProcessTypesL SetInputCropOptionsL SetYuvToRgbOptionsL SetRotateOptionsL SetScaleOptionsL SetOutputCropOptionsL SetPostProcSpecificOptionsL

leave

"The method will leave if an error occurs."

Pre-condition

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

Retrieves a custom interface to the specified hardware device.

Finds a common format from two lists of uncompressed video formats. Used typically to find a suitable intermediate format between a video decoder and a post-processor. If multiple common formats are available, the lowest-cost format is selected, assuming that the cost of each format is equal to its position in the input array.

Finds all available decoders for a given video type with support for certain post-processing operations. The video type is specified using its MIME type, which may include parameters specifying the supported level, version, and other information. Decoder HW devices can use wildcards when listing the supported video types in the ECom registration information, so it is possible that all the decoders returned do not support the specified submode, e.g. profile and level, unless aExactMatch is set. The decoder capabilities can be checked with VideoCodecInfoLC().

Freezes a picture on the screen. After the picture has been frozen, no picture is displayed until the freeze is released with ReleaseFreeze(). If the video output is being written to memory buffers, not the screen, decoded pictures will not be delivered to the client when a freeze is active, but are simply discarded.

Retrieves an empty video input buffer from the decoder. After input data has been written to the buffer, it can be written to the decoder using WriteCodedDataL(). The maximum number of buffers the client can retrieve before returning any to the decoder is determined by the TBufferOptions.iMinNumInputBuffers value set with SetBufferOptionsL().

If a buffer is not immediately available, the client can wait for a MdvpoNewBuffers() callback before trying again, or poll for new buffer availability after a delay. Note that video decoding may be performed in the same thread, in a separate active object, so the client must not block the active scheduler while waiting for buffers to become available, otherwise the system can deadlock. Assuming that the client does not keep too many buffers retrieved and playback is in progress, new buffers will be available after some time.

The decoder maintains ownership of the buffers even while they have been retrieved by the client, and will take care of deallocating them. The client must not destroy the buffer objects, even if it has retrieved buffers and it is being shut down. The buffers will be destroyed by the decoder, and will not be valid after the decoder has been shut down.

Gets information about new decoded pictures. "New decoded pictures" are pictures that have not been returned to the caller using NextPicture(). This method can only be called if video destination is memory buffers, i.e. Direct Screen Access is not used.

Retrieves a list of available video post-processors in the system.

Gets a copy of a specified picture. Timed snapshots are required for implementing the video telephony use-case. Simply using the latest picture may not work, since the latest picture is typically not the one whose supplemental information is being processed.

The picture is specified using its presentation timestamp. The timestamp must match the timestamp in the picture exactly, otherwise no snapshot will be taken. The timestamp must refer to the currently displayed picture or a future picture. Typically the timestamp is received with supplemental information (with the MdvpoSupplementalInformation() callback) indicating a snapshot picture.

When the snapshot is available, it will be returned to the client using the MdvpoTimedSnapshotComplete() callback. To cancel a timed snapshot request, use CancelTimedSnapshot(). Only one timed snapshot request can be active at a time.

Gets a copy of a specified picture. Timed snapshots are required for implementing the video telephony use-case. Simply using the latest picture may not work, since the latest picture is typically not the one whose supplemental information is being processed.

The picture is specified using either its picture identifier. The id must refer to the currently displayed picture or a future picture. Typically the picture ID is received with supplemental information (with the MdvpoSupplementalInformation() callback) indicating a snapshot picture.

When the snapshot is available, it will be returned to the client using the MdvpoTimedSnapshotComplete() callback. To cancel a timed snapshot request, use CancelTimedSnapshot(). Only one timed snapshot request can be active at a time.

Initializes the video device. This method is asynchronous, DevVideoPlay will call MMMFDevVideoPlayObserver::MdvpoInitializeComplete() after initialization has completed. No DevVideoPlay method may be called while initialization is in progress, the initialization process can only be cancelled by destroying the DevVideoPlay object. After this initialization has been successfully completed, further configuration changes are not possible except where separately noted.

If initialization fails for any reason, the DevVideoPlay object must be destroyed and set up from scratch.

Notifies the system that the end of input data has been reached.

The decoder and post-processor 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 decoder implementation might be waiting 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 client gets notified with the MdvpoStreamEnd() callback. The client must then call Stop() on the interface.

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.

Constructs a new MSL video client instance. Each client instance supports a single video bitstream.

Gets the number of complexity levels available.

Releases a picture frozen with FreezePicture().

Revert any configuration changes that have not yet been committed using CommitL(). This only applies to methods that can be called both before AND after DevVideoPlay has been initialized. See the following methods for details.

See also: SetPostProcessTypesL SetInputCropOptionsL SetYuvToRgbOptionsL SetRotateOptionsL SetScaleOptionsL SetOutputCropOptionsL SetPostProcSpecificOptionsL

Pre-condition

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

Selects the video decoder to be used. This method must be called before any other video decoder related methods are used. The decoder to use can be changed by calling this method again before the API has been initialized with Initialize(). All video decoder settings are reset to their default values, which are up to the implementation to decide if not specified in any of the MSL specifications. By default no post-processing is performed.

Selects the video post-processor to be used. This method must be called before any other post-processor related methods are used. The post-processor to use can be changed by calling this method again before the API has been initialized with Initialize(). All post-processor settings are reset to their default values, which are up to the implementation to decide if not specified in any of the MSL specifications.

Sets the clock source to use for video timing. When video playback is synchronized with audio, the clock source is implemented by the audio playback subsystem, otherwise the clock source should get the time from the system clock. 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. This method can be called after all hardware devices have been selected, but before calling Initialize().

All decoders must support synchronization with an external clock source, as well as unsynchronized non-realtime operation. When a clock source is set, the decoder can skip pictures to maintain synchronization. When non-realtime operation is used and no clock source has been set, pictures may not be skipped unless a lower complexity level is used that requires this.

Sets the computational complexity level to use. The level can be set separately for each hardware device in 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.

Indicates which HRD/VBV specification is fulfilled in the input stream and any related parameters.

Sets the output format for a hardware device. If a decoder and a post-processor are used, the decoder output format must match the post-processor source format.

If direct screen access is being used, then it is not necessary to call this method on the hwdevice performing the direct screen access.

Sets the post-processing types to be used. This method, like all post-processing configuration methods, must be called before Initialize().

Post-processing operations are carried out in the following order: 1. Input cropping 2. Mirroring 3. Rotating 4. Scaling 5. Output cropping Color space conversion can be performed at any point in the post-processing flow.

Sets a new clipping region for Direct Screen Access. After the method returns, no video will be drawn outside of the region. (Note that in Symbian OS clipping regions are "positive" - that is, they define the legal area inside which an application may draw.)

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.

Sets whether the decoder should synchronize decoding to the current clock source, if any, or should decode all pictures as soon as possible. If decoding is synchronized, decoding timestamps are used if available, presentation timestamps are used if not. When decoding is not synchronized, pictures are decoded as soon as source data is available for them and the decoder has a free output buffer. If a clock source is not available, decoding will not be synchronized.