1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/mm/mmhais/videohai/devvideo/inc/videoplayhwdevice.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,897 @@
1.4 +// Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#ifndef __VIDEOPLAYHWDEVICE_H__
1.20 +#define __VIDEOPLAYHWDEVICE_H__
1.21 +
1.22 +#include <mmf/devvideo/devvideobase.h>
1.23 +#include <mmf/devvideo/devvideoplay.h>
1.24 +#include <mmf/common/mmfvideo.h>
1.25 +
1.26 +/**
1.27 +A base class for all video playback (decoder and post-processor) hardware devices.
1.28 +Since both decoders and post-processors can implement post-processing functionality,
1.29 +this class includes all post-processing related methods. The main difference between decoder
1.30 +and post-processor devices is that decoders can input coded data and write decoded pictures
1.31 +to another device, while post-processor devices can accept decoded pictures from the client
1.32 +or from another device.
1.33 +@publishedAll
1.34 +@released
1.35 +*/
1.36 +class CMMFVideoPlayHwDevice : public CMMFVideoHwDevice
1.37 + {
1.38 +public:
1.39 + /**
1.40 + Retrieves post-processing information about this hardware device.
1.41 + The device creates a CPostProcessorInfo structure, fills it with correct data, pushes it
1.42 + to the cleanup stack and returns it. The client will delete the object when it is no
1.43 + longer needed.
1.44 +
1.45 + @return "Post-processor information as a CPostProcessorInfo object.
1.46 + The object is pushed to the cleanup stack, and must be deallocated by the caller."
1.47 + @leave "This method may leave with one of the system-wide error codes.
1.48 + */
1.49 + virtual CPostProcessorInfo* PostProcessorInfoLC() = 0;
1.50 +
1.51 + /**
1.52 + Retrieves the list of the output formats that the device supports. The list is ordered in
1.53 + plug-in preference order, with the preferred formats at the beginning of the list. The list
1.54 + can depend on the device source format, and therefore SetSourceFormatL() must be called before
1.55 + calling this method.
1.56 +
1.57 + @param "aFormats" "An array for the result format list. The array must be created and destroyed by the caller."
1.58 + @leave "This method may leave with one of the system-wide error codes.
1.59 + @pre "This method may only be called before the hwdevice has been initialized using Initialize()."
1.60 + */
1.61 + virtual void GetOutputFormatListL(RArray<TUncompressedVideoFormat>& aFormats) = 0;
1.62 +
1.63 + /**
1.64 + Sets the device output format.
1.65 +
1.66 + @param "aFormat" "The format to use."
1.67 + @leave "This method may leave with one of the system-wide error codes.
1.68 + @pre "This method may only be called before the hwdevice has been initialized using Initialize()."
1.69 + */
1.70 + virtual void SetOutputFormatL(const TUncompressedVideoFormat &aFormat) = 0;
1.71 +
1.72 + /**
1.73 + Sets the clock source to use for video timing. If no clock source is set. video playback
1.74 + will not be synchronized, but will proceed as fast as possible, depending on input data
1.75 + and output buffer availability.
1.76 +
1.77 + @param "aClock" "The clock source to be used."
1.78 + @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
1.79 + */
1.80 + virtual void SetClockSource(MMMFClockSource* aClock) = 0;
1.81 +
1.82 + /**
1.83 + Sets the device video output destination. The destination can be the screen (using direct
1.84 + screen access) or memory buffers. By default memory buffers are used. If data is written
1.85 + to another device, this method is ignored, and suitable memory buffers are always used.
1.86 +
1.87 + @param "aScreen" "True if video output destination is the screen, false if memory buffers."
1.88 + @leave "This method may leave with one of the system-wide error codes.
1.89 + @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
1.90 + */
1.91 + virtual void SetVideoDestScreenL(TBool aScreen) = 0;
1.92 +
1.93 + /**
1.94 + Sets the post-processing types to be used.
1.95 +
1.96 + @param "aPostProcCombination" "The post-processing steps to perform, a bitwise OR of values from TPostProcessType."
1.97 + @leave "This method may leave with one of the system-wide error codes.
1.98 + @pre "This method can be called either before or after the hwdevice has been initialized with Initialize().
1.99 + If called after initialization, the change must only be committed when CommitL() is called."
1.100 + */
1.101 + virtual void SetPostProcessTypesL(TUint32 aPostProcCombination) = 0;
1.102 +
1.103 + /**
1.104 + Sets post-processing options for input (pan-scan) cropping.
1.105 +
1.106 + @param "aRect" "The cropping rectangle to use."
1.107 + @leave "This method may leave with one of the system-wide error codes.
1.108 + @pre "This method can be called either before or after the hwdevice has been initialized with Initialize().
1.109 + If called after initialization, the change must only be committed when CommitL() is called."
1.110 + */
1.111 + virtual void SetInputCropOptionsL(const TRect& aRect) = 0;
1.112 +
1.113 + /**
1.114 + Sets post-processing options for YUV to RGB color space conversion.
1.115 + Specifies the input YUV and output RGB formats to use explicitly. SetSourceFormatL(),
1.116 + SetOutputFormatL(), and SetPostProcessTypesL() must be called before this method is used.
1.117 +
1.118 + @param "aOptions" "The conversion options to use."
1.119 + @param "aYuvFormat" "Conversion source YUV format"
1.120 + @param "aRgbFormat" "Conversion target RGB format"
1.121 + @leave "This method may leave with one of the system-wide error codes.
1.122 + @pre "This method can be called either before or after the hwdevice has been initialized with Initialize().
1.123 + If called after initialization, the change must only be committed when CommitL() is called."
1.124 + */
1.125 + virtual void SetYuvToRgbOptionsL(const TYuvToRgbOptions& aOptions, const TYuvFormat& aYuvFormat, TRgbFormat aRgbFormat) = 0;
1.126 +
1.127 + /**
1.128 + Sets post-processing options for YUV to RGB color space conversion.
1.129 + Uses the device input and output formats. For decoder devices the default YUV format used is
1.130 + the format specified in the input bitstream. SetSourceFormatL(), SetOutputFormatL(), and
1.131 + SetPostProcessTypesL() must be called before this method is used.
1.132 +
1.133 + @param "aOptions" "The conversion options to use."
1.134 + @leave "This method may leave with one of the system-wide error codes.
1.135 + @pre "This method can be called either before or after the hwdevice has been initialized with Initialize().
1.136 + If called after initialization, the change must only be committed when CommitL() is called."
1.137 + */
1.138 + virtual void SetYuvToRgbOptionsL(const TYuvToRgbOptions& aOptions) = 0;
1.139 +
1.140 + /**
1.141 + Sets post-processing options for rotation. SetPostProcessTypesL() must be called before
1.142 + this method is used.
1.143 +
1.144 + @param "aRotationType" "The rotation to perform."
1.145 + @leave "This method may leave with one of the system-wide error codes.
1.146 + @pre "This method can be called either before or after the hwdevice has been initialized with Initialize().
1.147 + If called after initialization, the change must only be committed when CommitL() is called."
1.148 + */
1.149 + virtual void SetRotateOptionsL(TRotationType aRotationType) = 0;
1.150 +
1.151 + /**
1.152 + Sets post-processing options for scaling. SetPostProcessTypesL() must be called before
1.153 + this method is used.
1.154 +
1.155 + @param "aTargetSize" "Scaling target size. If a fixed scale factor size is used,
1.156 + the new dimensions must be set to width=floor(factor*width),
1.157 + height=floor(factor*height). For example, scaling a
1.158 + QCIF (176x144) picture up by a factor of 4/3 yields a size
1.159 + of 234x192."
1.160 + @param "aAntiAliasFiltering" "True if anti-aliasing filtering should be used.
1.161 + If the post-processor does not support anti-aliased scaling,
1.162 + or supports anti-aliased scaling only, this argument is ignored."
1.163 + @leave "This method may leave with one of the system-wide error codes.
1.164 + @pre "This method can be called either before or after the hwdevice has been initialized with Initialize().
1.165 + If called after initialization, the change must only be committed when CommitL() is called."
1.166 + */
1.167 + virtual void SetScaleOptionsL(const TSize& aTargetSize, TBool aAntiAliasFiltering) = 0;
1.168 +
1.169 + /**
1.170 + Sets post-processing options for output cropping. SetPostProcessTypesL() must be called before
1.171 + this method is used.
1.172 +
1.173 + @param "aRect" "Output cropping area."
1.174 + @leave "This method may leave with one of the system-wide error codes.
1.175 + @pre "This method can be called either before or after the hwdevice has been initialized with Initialize().
1.176 + If called after initialization, the change must only be committed when CommitL() is called."
1.177 + */
1.178 + virtual void SetOutputCropOptionsL(const TRect& aRect) = 0;
1.179 +
1.180 + /**
1.181 + Sets post-processing plug-in specific options. SetPostProcessTypesL() must be called before
1.182 + this method is used.
1.183 +
1.184 + @param "aOptions" "The options. The format is plug-in specific."
1.185 + @leave "This method may leave with one of the system-wide error codes.
1.186 + @pre "This method can be called either before or after the hwdevice has been initialized with Initialize().
1.187 + If called after initialization, the change must only be committed when CommitL() is called."
1.188 + */
1.189 + virtual void SetPostProcSpecificOptionsL(const TDesC8& aOptions) = 0;
1.190 +
1.191 + /**
1.192 + Initializes the device. This method is asynchronous, the device will call
1.193 + MMFVideoPlayProxy::MdvppInitializeComplete() after initialization has completed. After this
1.194 + method has successfully completed, further configuration changes are not possible except where
1.195 + separately noted.
1.196 + */
1.197 + virtual void Initialize() = 0;
1.198 +
1.199 + /**
1.200 + Commit all changes since the last CommitL(), Revert() or Initialize()
1.201 + to the hardware device. This only applies to methods which can be called both
1.202 + before AND after DevVideoPlay has been initialized.
1.203 +
1.204 + @see SetPostProcessTypesL
1.205 + @see SetInputCropOptionsL
1.206 + @see SetYuvToRgbOptionsL
1.207 + @see SetRotateOptionsL
1.208 + @see SetScaleOptionsL
1.209 + @see SetOutputCropOptionsL
1.210 + @see SetPostProcSpecificOptionsL
1.211 +
1.212 + @leave "The method will leave if an error occurs."
1.213 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.214 + */
1.215 + virtual void CommitL() = 0;
1.216 +
1.217 + /**
1.218 + Revert all changes since the last CommitL(), Revert() or Initialize()
1.219 + back to their previous settings. This only applies to methods which can
1.220 + be called both before AND after DevVideoPlay has been initialized.
1.221 +
1.222 + @see SetPostProcessTypesL
1.223 + @see SetInputCropOptionsL
1.224 + @see SetYuvToRgbOptionsL
1.225 + @see SetRotateOptionsL
1.226 + @see SetScaleOptionsL
1.227 + @see SetOutputCropOptionsL
1.228 + @see SetPostProcSpecificOptionsL
1.229 +
1.230 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.231 + */
1.232 + virtual void Revert() = 0;
1.233 +
1.234 + /**
1.235 + Starts writing output directly to the display frame buffer using Direct Screen Access.
1.236 +
1.237 + @param "aVideoRect" "The video output rectangle on screen."
1.238 + @param "aScreenDevice" "The screen device to use. The screen device object must be valid in the current thread."
1.239 + @param "aClipRegion" "Initial clipping region to use."
1.240 +
1.241 + @leave "This method may leave with one of the system-wide error codes.
1.242 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.243 + */
1.244 + virtual void StartDirectScreenAccessL(const TRect& aVideoRect,
1.245 + CFbsScreenDevice& aScreenDevice, const TRegion& aClipRegion) = 0;
1.246 +
1.247 + /**
1.248 + Sets a new clipping region for Direct Screen Access. After the method returns, no video will
1.249 + be drawn outside of the region. If clipping is not supported, or the clipping region is too
1.250 + complex, either playback will pause or will resume without video display, depending on the
1.251 + current setting of SetPauseOnClipFail(), and the result can be verified with IsPlaying().
1.252 + Clipping can be disabled by setting a new clipping region that includes the whole video window.
1.253 +
1.254 + @param "aRegion" "The new clipping region. After the method returns, no video will be drawn outside the region."
1.255 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.256 + */
1.257 + virtual void SetScreenClipRegion(const TRegion& aRegion) = 0;
1.258 +
1.259 + /**
1.260 + Sets whether the system should pause playback when it gets a clipping region it cannot handle,
1.261 + or Direct Screen Access is aborted completely. If not, processing will proceed normally, but no
1.262 + video will be drawn. By default, playback is paused.
1.263 +
1.264 + @param "aPause" "True if playback should be paused when clipping fails, false if not.
1.265 + If playback is not paused, it will be continued without video display."
1.266 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.267 + */
1.268 + virtual void SetPauseOnClipFail(TBool aPause) = 0;
1.269 +
1.270 + /**
1.271 + Aborts Direct Screen Access completely, to be called from MAbortDirectScreenAccess::AbortNow()
1.272 + and similar methods. DSA can be resumed by calling StartDirectScreenAccessL().
1.273 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.274 + */
1.275 + virtual void AbortDirectScreenAccess() = 0;
1.276 +
1.277 + /**
1.278 + Indicates whether playback is proceeding. This method can be used to check whether playback was
1.279 + paused or not in response to a new clipping region or DSA abort.
1.280 +
1.281 + @return "ETrue if video is still being played (even if not necessarily displayed)."
1.282 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.283 + */
1.284 + virtual TBool IsPlaying() = 0;
1.285 +
1.286 + /**
1.287 + Re-draws the latest video picture. Only available when DSA is being used. If DSA is aborted or a
1.288 + non-supported clipping region has been set, the request may be ignored.
1.289 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.290 + */
1.291 + virtual void Redraw() = 0;
1.292 +
1.293 +
1.294 + /**
1.295 + Starts video playback, including decoding, post-processing, and rendering. Playback will proceed
1.296 + until it has been stopped or paused, or the end of the bitstream is reached.
1.297 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.298 + */
1.299 + virtual void Start() = 0;
1.300 +
1.301 + /**
1.302 + Stops video playback. No new pictures will be decoded, post-processed, or rendered.
1.303 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.304 + */
1.305 + virtual void Stop() = 0;
1.306 +
1.307 + /**
1.308 + Pauses video playback, including decoding, post-processing, and rendering. No pictures will be
1.309 + decoded, post-processed, or rendered until playback has been resumed.
1.310 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.311 + */
1.312 + virtual void Pause() = 0;
1.313 +
1.314 + /**
1.315 + Resumes video playback after a pause.
1.316 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.317 + */
1.318 + virtual void Resume() = 0;
1.319 +
1.320 + /**
1.321 + Changes to a new decoding and playback position, used for randomly accessing (seeking) the
1.322 + input stream. The position change flushes all input and output buffers. Pre-decoder and
1.323 + post-decoder buffering are handled as if a new bitstream was being decoded. If the device still has buffered
1.324 + pictures that precede the new playback position, they will be discarded. If playback is
1.325 + synchronized to a clock source, the client is responsible for setting the clock source to the
1.326 + new position.
1.327 +
1.328 + @param "aPlaybackPosition" "The new playback position in the video stream."
1.329 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.330 + */
1.331 + virtual void SetPosition(const TTimeIntervalMicroSeconds& aPlaybackPosition) = 0;
1.332 +
1.333 + /**
1.334 + Freezes a picture on the screen. After the picture has been frozen, no new pictures are
1.335 + displayed until the freeze is released with ReleaseFreeze(). If the device output is being
1.336 + written to memory buffers or to another plug-in, instead of the screen, no decoded pictures
1.337 + will be delivered while the freeze is active, and they are simply discarded.
1.338 +
1.339 + @param "aTimestamp" "The presentation timestamp of the picture to freeze. The frozen picture
1.340 + will be the first picture with a timestamp greater than or equal to this
1.341 + parameter."
1.342 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.343 + */
1.344 + virtual void FreezePicture(const TTimeIntervalMicroSeconds& aTimestamp) = 0;
1.345 +
1.346 + /**
1.347 + Releases a picture frozen with FreezePicture().
1.348 +
1.349 + @param "aTimestamp" "The presentation timestamp of the picture to release. The first picture
1.350 + displayed after the release will be the first picture with a timestamp
1.351 + greater than or equal to this parameter. To release the freeze immediately,
1.352 + set the timestamp to zero."
1.353 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.354 + */
1.355 + virtual void ReleaseFreeze(const TTimeIntervalMicroSeconds& aTimestamp) = 0;
1.356 +
1.357 +
1.358 + /**
1.359 + Returns the current playback position, i.e. the timestamp for the most recently displayed or
1.360 + virtually displayed picture. If the device output is written to another device, the most recent
1.361 + output picture is used.
1.362 +
1.363 + @return "Current playback position."
1.364 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.365 + */
1.366 + virtual TTimeIntervalMicroSeconds PlaybackPosition() = 0;
1.367 +
1.368 + /**
1.369 + Returns the total amount of memory allocated for uncompressed pictures. This figure only
1.370 + includes the pictures actually allocated by the plug-in itself, so that the total number of
1.371 + bytes allocated in the system can be calculated by taking the sum of the values from all plug-ins.
1.372 +
1.373 + @return "Total number of bytes of memory allocated for uncompressed pictures."
1.374 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.375 + */
1.376 + virtual TUint PictureBufferBytes() = 0;
1.377 +
1.378 + /**
1.379 + Reads various counters related to decoded pictures. The counters are reset when Initialize()
1.380 + or this method is called, and thus they only include pictures processed since the last call.
1.381 +
1.382 + Post-processor devices return the number of input pictures in iPicturesDecoded and
1.383 + iTotalPictures. If the decoded pictures are written to another plug-in, they are considered
1.384 + to be "virtually displayed".
1.385 +
1.386 + @param "aCounters" "The counter structure to fill."
1.387 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.388 + */
1.389 + virtual void GetPictureCounters(CMMFDevVideoPlay::TPictureCounters& aCounters) = 0;
1.390 +
1.391 +
1.392 + /**
1.393 + Sets the computational complexity level to use. If separate complexity levels are not available,
1.394 + the method call is ignored. If the level specified is not available, the results are undefined.
1.395 + Typically the device will either ignore the request or use the nearest suitable level.
1.396 +
1.397 + The complexity level can be changed at any point during playback.
1.398 +
1.399 + @param "aLevel" "The computational complexity level to use. Level zero (0) is the most complex
1.400 + one, with the highest quality. Higher level numbers require less processing
1.401 + and may have lower quality."
1.402 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.403 + */
1.404 + virtual void SetComplexityLevel(TUint aLevel) = 0;
1.405 +
1.406 + /**
1.407 + Gets the number of complexity levels available.
1.408 +
1.409 + @return "The number of complexity control levels available, or zero if the information is not
1.410 + available yet. The information may not be available if the number of levels depends on
1.411 + the input data, and enough input data has not been read yet. In that case, using level
1.412 + zero is safe."
1.413 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.414 + */
1.415 + virtual TUint NumComplexityLevels() = 0;
1.416 +
1.417 + /**
1.418 + Gets information about a computational complexity level. This method can be called after
1.419 + NumComplexityLevels() has returned a non-zero value - at that point the information is guaranteed
1.420 + to be available. Some hardware device implementations may not be able to provide all values,
1.421 + in that case the values will be approximated.
1.422 +
1.423 + @param "aLevel" "The computational complexity level to query. The level numbers range from zero
1.424 + (the most complex) to NumComplexityLevels()-1."
1.425 + @param "aInfo" "The information structure to fill."
1.426 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.427 + */
1.428 + virtual void GetComplexityLevelInfo(TUint aLevel, CMMFDevVideoPlay::TComplexityLevelInfo& aInfo) = 0;
1.429 +
1.430 + /**
1.431 + Returns a picture back to the device. This method is called by CMMFDevVideoPlay to return pictures
1.432 + from the client (after they have been written with NewPicture()), or by the output device when
1.433 + it has finished using a picture.
1.434 +
1.435 + @param "aPicture" "The picture to return. The device can re-use the memory for the picture."
1.436 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.437 + */
1.438 + virtual void ReturnPicture(TVideoPicture* aPicture) = 0;
1.439 +
1.440 + /**
1.441 + Gets a copy of the latest picture sent to output.
1.442 +
1.443 + @param "aPictureData" "Target picture. The memory for the picture must be allocated by the
1.444 + caller, and initialized properly. The data formats must match the snapshot
1.445 + format requested."
1.446 + @param "aFormat" "The picture format to use for the snapshot."
1.447 +
1.448 + @return "ETrue if the snapshot was taken, EFalse if a picture is not available. The picture may not
1.449 + be available if decoding has not progressed far enough yet."
1.450 +
1.451 + @leave "The method will leave if an error occurs. Typical error codes used:
1.452 + * KErrNotSupported - The requested data format or picture size is not supported, or the
1.453 + plug-in does not support snapshots."
1.454 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.455 + */
1.456 + virtual TBool GetSnapshotL(TPictureData& aPictureData, const TUncompressedVideoFormat& aFormat) = 0;
1.457 +
1.458 + /**
1.459 + When the snapshot is available, it will be returned to the client using the TimedSnapshotComplete()
1.460 + callback. To cancel a timed snapshot request, use CancelTimedSnapshot(). Only one timed snapshot
1.461 + request can be active at a time.
1.462 +
1.463 + @param "aPictureData" "Target picture. The memory for the picture must be allocated by
1.464 + the caller, and initialized properly. The data formats must match
1.465 + the snapshot format requested. The picture must remain valid until
1.466 + the snapshot has been taken or until the request has been cancelled
1.467 + with CancelTimedSnapshot()."
1.468 + @param "aFormat" "The picture format to use for the snapshot."
1.469 + @param "aPresentationTimestamp" "Presentation timestamp for the picture to copy."
1.470 +
1.471 + @leave "The method will leave if an error occurs. Typical error codes used:
1.472 + * KErrNotSupported - The requested data format or picture size is not supported or
1.473 + the plug-in does not support timed snapshots."
1.474 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.475 + */
1.476 + virtual void GetTimedSnapshotL(TPictureData* aPictureData, const TUncompressedVideoFormat& aFormat,
1.477 + const TTimeIntervalMicroSeconds& aPresentationTimestamp) = 0;
1.478 +
1.479 + /**
1.480 + When the snapshot is available, it will be returned to the client using the TimedSnapshotComplete()
1.481 + callback. To cancel a timed snapshot request, use CancelTimedSnapshot(). Only one timed snapshot
1.482 + request can be active at a time.
1.483 +
1.484 + @param "aPictureData" "Target picture. The memory for the picture must be allocated by
1.485 + the caller, and initialized properly. The data formats must match
1.486 + the snapshot format requested. The picture must remain valid until
1.487 + the snapshot has been taken or until the request has been cancelled
1.488 + with CancelTimedSnapshot()."
1.489 + @param "aFormat" "The picture format to use for the snapshot."
1.490 + @param "aPictureId" "Picture identifier for the picture to copy."
1.491 +
1.492 + @leave "The method will leave if an error occurs. Typical error codes used:
1.493 + * KErrNotSupported - The requested data format or picture size is not supported or
1.494 + the plug-in does not support timed snapshots."
1.495 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.496 + */
1.497 + virtual void GetTimedSnapshotL(TPictureData* aPictureData, const TUncompressedVideoFormat& aFormat,
1.498 + const TPictureId& aPictureId) = 0;
1.499 +
1.500 + /**
1.501 + Cancels a timed snapshot request.
1.502 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.503 + */
1.504 + virtual void CancelTimedSnapshot() = 0;
1.505 +
1.506 + /**
1.507 + Gets a list of the supported snapshot picture formats.
1.508 +
1.509 + @param "aFormats" "An array for the result format list. The array must be created and destroyed by
1.510 + the caller."
1.511 +
1.512 + @leave "This method may leave with one of the standard error codes."
1.513 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.514 + */
1.515 + virtual void GetSupportedSnapshotFormatsL(RArray<TUncompressedVideoFormat>& aFormats) = 0;
1.516 +
1.517 +
1.518 + /**
1.519 +
1.520 + Notifies the hardware device that the end of input data has been reached and no more input data
1.521 + will be written. The hardware device can use this signal to ensure that the remaining data gets
1.522 + processed, without waiting for new data. For example when the data type is not EDuCodedPicture,
1.523 + calling this method is necessary otherwise a hardware device implementation might be looking for
1.524 + the start code for the next picture to ensure it has a complete picture before starting to decode
1.525 + the previous one.
1.526 +
1.527 +
1.528 + After the remaining data has been processed (and displayed, if applicable), the hardware
1.529 + device must notify the proxy with the MdvppStreamEnd() callback.
1.530 +
1.531 + DevVideo clients are encouraged to call this method, but its use is not mandatory for synchronized
1.532 + processing. For synchronized playback, all video pictures are processed or discarded according to
1.533 + their timestamps, and so the client can easily infer when processing is complete. However, it
1.534 + should be noted that the last picture might not be displayed if this method is not called and the
1.535 + input data type is not EDuCodedPicture.
1.536 +
1.537 + For non-synchronized playback (e.g. file conversion), a client must call this method otherwise it
1.538 + will never find out when the hardware device has finished processing the data.
1.539 +
1.540 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.541 + */
1.542 + virtual void InputEnd() = 0;
1.543 + };
1.544 +
1.545 +
1.546 +
1.547 +
1.548 +/**
1.549 +CMMFVideoDecodeHwDevice is the MSL video decoder hardware device interface.
1.550 +All video decoders must implement this interface.
1.551 +@publishedAll
1.552 +@released
1.553 +*/
1.554 +class CMMFVideoDecodeHwDevice : public CMMFVideoPlayHwDevice
1.555 + {
1.556 +public:
1.557 + /**
1.558 + Creates a new video decoder hardware device object, based on the implementation UID.
1.559 +
1.560 + @param "aUid" "Decoder implementation UID."
1.561 + @param "aProxy" "The proxy implementation to use."
1.562 + @return "A new CMMFVideoDecodeHwDevice object."
1.563 + @leave "This method may leave with one of the system-wide error codes.
1.564 + */
1.565 + IMPORT_C static CMMFVideoDecodeHwDevice* NewL(TUid aUid, MMMFDevVideoPlayProxy& aProxy);
1.566 +
1.567 + /**
1.568 + Creates a new video decoder hardware device adapter object, based on the Implementation Information of a Processing Unit.
1.569 +
1.570 + @param "aImplInfo" "The registration data relating to the Interface Implementation of the Processing Unit."
1.571 + @param "aProxy" "The proxy implementation to use."
1.572 + @return "A new CMMFVideoDecodeHwDevice object."
1.573 + @leave "This method will leave if an error occurs."
1.574 + */
1.575 + IMPORT_C static CMMFVideoDecodeHwDevice* NewPuAdapterL(const CImplementationInformation& aImplInfo, MMMFDevVideoPlayProxy& aProxy);
1.576 +
1.577 +
1.578 + /**
1.579 + Destructor.
1.580 + */
1.581 + IMPORT_C virtual ~CMMFVideoDecodeHwDevice();
1.582 +
1.583 +
1.584 + /**
1.585 + Retrieves decoder information about this hardware device. The device creates a CVideoDecoderInfo
1.586 + structure, fills it with correct data, pushes it to the cleanup stack and returns it. The client
1.587 + will delete the object when it is no longer needed.
1.588 +
1.589 + @return "Decoder information as a CVideoDecoderInfo object. The object is pushed to the cleanup
1.590 + stack, and must be deallocated by the caller."
1.591 + @leave "This method may leave with one of the system-wide error codes."
1.592 +
1.593 + @see CVideoDecoderInfo
1.594 + */
1.595 + virtual CVideoDecoderInfo* VideoDecoderInfoLC() = 0;
1.596 +
1.597 + /**
1.598 + Reads header information from a coded data unit.
1.599 + @param "aDataUnitType" "The type of the coded data unit that is contained in aDataUnit. If the data is a
1.600 + simple piece of bitstream, use EDuArbitraryStreamSection."
1.601 + @param "aEncapsulation" "The encapsulation type used for the coded data. If the data is a
1.602 + simple piece of bitstream, use EDuElementaryStream."
1.603 + @param "aDataUnit" "The coded data unit, contained in a TVideoInputBuffer."
1.604 + @return "Header information for the data unit, or NULL if the coded data unit did not contain
1.605 + enough data to parse the header. The header data must be returned to the device using
1.606 + ReturnHeader() before Initialize() is called or the decoder is destroyed. The data remains
1.607 + valid until it is returned."
1.608 + @leave "The method will leave if an error occurs. Running out of data is not considered an error,
1.609 + as described above. Typical error codes used:
1.610 + * KErrNotSupported - The data is not in a supported format.
1.611 + * KErrCorrupt - The data appears to be in a supported format, but is corrupted."
1.612 + */
1.613 + virtual TVideoPictureHeader* GetHeaderInformationL(TVideoDataUnitType aDataUnitType,
1.614 + TVideoDataUnitEncapsulation aEncapsulation, TVideoInputBuffer* aDataUnit) = 0;
1.615 +
1.616 +
1.617 + /**
1.618 + Returns a header from GetHeaderInformationL() back to the decoder so that the memory can be freed.
1.619 +
1.620 + @param "aHeader" "The header to return."
1.621 + @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
1.622 + */
1.623 + virtual void ReturnHeader(TVideoPictureHeader* aHeader) = 0;
1.624 +
1.625 + /**
1.626 + Sets the device input format to a compressed video format.
1.627 +
1.628 + @param "aFormat" "The input format to use."
1.629 + @param "aDataUnitType" "The data unit type for input data."
1.630 + @param "aEncapsulation" "The encapsulation type used for the coded data."
1.631 + @param "aDataInOrder" "ETrue if the input data is written in correct decoding order,
1.632 + EFalse if will be written in arbitrary order."
1.633 + @leave "The method will leave if an error occurs. Typical error codes used:
1.634 + * KErrNotSupported - The source format is not supported."
1.635 +
1.636 + @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
1.637 + */
1.638 + virtual void SetInputFormatL(const CCompressedVideoFormat& aFormat,
1.639 + TVideoDataUnitType aDataUnitType, TVideoDataUnitEncapsulation aEncapsulation,
1.640 + TBool aDataInOrder) = 0;
1.641 +
1.642 + /**
1.643 + Sets whether decoding should be synchronized to the current clock source, if any, or if pictures
1.644 + should instead be decoded as soon as possible. If decoding is synchronized, decoding timestamps
1.645 + are used if available, presentation timestamps are used if not. When decoding is not synchronized,
1.646 + pictures are decoded as soon as source data is available for them, and the decoder has a free
1.647 + output buffer. If a clock source is not available, decoding will not be synchronized.
1.648 +
1.649 + @param "aSynchronize" "True if decoding should be synchronized to a clock source."
1.650 + @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
1.651 + */
1.652 + virtual void SynchronizeDecoding(TBool aSynchronize) = 0;
1.653 +
1.654 + /**
1.655 + Sets decoder buffering options. See [3] for a description of the options available.
1.656 +
1.657 + @param "aOptions" "Buffering options."
1.658 + @leave "The method will leave if an error occurs. Typical error codes used:
1.659 + * KErrNotSupported - The specified buffering options are not supported.
1.660 + If the client receives this error code, it can call GetBufferOptions()
1.661 + to determine the options the decoder is able to support."
1.662 +
1.663 + @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
1.664 + */
1.665 + virtual void SetBufferOptionsL(const CMMFDevVideoPlay::TBufferOptions& aOptions) = 0;
1.666 +
1.667 + /**
1.668 + Gets the video decoder buffer options actually in use. This can be used before calling
1.669 + SetBufferOptions() to determine the default options, or afterwards to check the values
1.670 + actually in use (if some default values were used).
1.671 +
1.672 + @param "aOptions" "Buffering options structure to fill."
1.673 + @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
1.674 + */
1.675 + virtual void GetBufferOptions(CMMFDevVideoPlay::TBufferOptions& aOptions) = 0;
1.676 +
1.677 + /**
1.678 + Indicates which HRD/VBV specification is fulfilled in the input stream and any related parameters.
1.679 +
1.680 + @param "aHrdVbvSpec" "The HRD/VBV specification fulfilled."
1.681 + @param "aHrdVbvParams" "HRD/VBV parameters. The data format depends on the parameters chosen.
1.682 + For 3GPP TS 26.234 parameters (aHrdVbvSpec=EHrdVbv3GPP), the data in the
1.683 + descriptor is a package of type TPckC<T3gppHrdVbvParams>
1.684 + (see T3gppHrdVbvParams). If no HRD/VBV parameters are used, the descriptor
1.685 + is zero length."
1.686 + @see THrdVbvSpecification
1.687 + @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
1.688 + */
1.689 + virtual void SetHrdVbvSpec(THrdVbvSpecification aHrdVbvSpec, const TDesC8& aHrdVbvParams) = 0;
1.690 +
1.691 + /**
1.692 + Sets the output post-processor device to use. If an output device is set, all decoded pictures
1.693 + are delivered to that device, and not drawn on screen or returned to the client. Pictures are
1.694 + written using CMMDVideoPostProcDevice::WritePictureL() or a custom interface after they have been
1.695 + decoded. The post-processor must then synchronize rendering to the clock source if necessary.
1.696 +
1.697 + @param "aDevice" "The output post-processor device to use."
1.698 + @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
1.699 + */
1.700 + virtual void SetOutputDevice(CMMFVideoPostProcHwDevice* aDevice) = 0;
1.701 +
1.702 + /**
1.703 + Returns the current decoding position, i.e. the timestamp for the most recently decoded picture.
1.704 +
1.705 + @return "Current decoding position."
1.706 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.707 + */
1.708 + virtual TTimeIntervalMicroSeconds DecodingPosition() = 0;
1.709 +
1.710 + /**
1.711 + Returns the current pre-decoder buffer size.
1.712 +
1.713 + @return "The number of bytes of data in the pre-decoder buffer."
1.714 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.715 + */
1.716 + virtual TUint PreDecoderBufferBytes() = 0;
1.717 +
1.718 + /**
1.719 + Reads various counters related to the received input bitstream and coded data units. The counters
1.720 + are reset when Initialize() or this method is called, and thus they only include data processed
1.721 + since the last call.
1.722 +
1.723 + @param "aCounters" "The counter structure to fill."
1.724 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.725 + */
1.726 + virtual void GetBitstreamCounters(CMMFDevVideoPlay::TBitstreamCounters& aCounters) = 0;
1.727 +
1.728 + /**
1.729 + Retrieves the number of free input buffers the decoder has available.
1.730 +
1.731 + @return "Number of free input buffers the decoder has available."
1.732 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.733 + */
1.734 + virtual TUint NumFreeBuffers() = 0;
1.735 +
1.736 + /**
1.737 + Retrieves an empty video input buffer from the decoder. After input data has been written to the
1.738 + buffer, it can be written to the decoder using WriteCodedDataL(). The number of buffers the decoder
1.739 + must be able to provide before expecting any back, and the maximum size for each buffer, are
1.740 + specified in the buffer options.
1.741 +
1.742 + The decoder maintains ownership of the buffers even while they have been retrieved by the client,
1.743 + and will take care of deallocating them.
1.744 +
1.745 + @param "aBufferSize" "Required buffer size, in bytes. The resulting buffer can be larger than
1.746 + this, but not smaller."
1.747 + @return "A new input data buffer. The buffer is at least as large as requested, but it may be
1.748 + larger. If no free buffers are available, the return value is NULL."
1.749 + @leave "The method will leave if an error occurs. Lack of free buffers is not considered an error."
1.750 + */
1.751 + virtual TVideoInputBuffer* GetBufferL(TUint aBufferSize) = 0;
1.752 +
1.753 + /**
1.754 + Writes a piece of coded video data to the decoder. The data buffer must be retrieved from the
1.755 + decoder with GetBufferL().
1.756 +
1.757 + @param "aBuffer" "The coded data unit to write."
1.758 + @leave "This method may leave with one of the system-wide error codes."
1.759 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.760 + */
1.761 + virtual void WriteCodedDataL(TVideoInputBuffer* aBuffer) = 0;
1.762 +
1.763 + /**
1.764 + Configures the Decoder using header information known by the client.
1.765 + @param "aVideoPictureHeader" "Header information to configure the decoder with"
1.766 + @leave "The method will leave if an error occurs. Running out of data is not considered an error,
1.767 + as described above.
1.768 + @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
1.769 + */
1.770 + virtual void ConfigureDecoderL(const TVideoPictureHeader& aVideoPictureHeader);
1.771 +
1.772 +
1.773 +
1.774 +protected:
1.775 + /**
1.776 + Constructor.
1.777 + */
1.778 + IMPORT_C CMMFVideoDecodeHwDevice();
1.779 +
1.780 + /**
1.781 + Set the proxy implementation to be used. Called just after the object is constructed.
1.782 + @param "aProxy" "The proxy to use."
1.783 + */
1.784 + virtual void SetProxy(MMMFDevVideoPlayProxy& aProxy) = 0;
1.785 +private:
1.786 + TUid iDtor_ID_Key;
1.787 + };
1.788 +
1.789 +
1.790 +/**
1.791 +CMMFVideoPostProcHwDevice is the MSL video post-processor plug-in interface. All MSL video
1.792 +post-processors must implement this interface.
1.793 +@publishedAll
1.794 +@released
1.795 +*/
1.796 +class CMMFVideoPostProcHwDevice : public CMMFVideoPlayHwDevice
1.797 + {
1.798 +public:
1.799 + /**
1.800 + Creates a new video post-processor hardware device object, based on the implementation UID.
1.801 +
1.802 + @param "aUid" "Post-processor implementation UID."
1.803 + @param "aProxy" "The proxy implementation to use."
1.804 + @return "A new CMMFVideoPostProcHwDevice object."
1.805 + @leave "This method may leave with one of the system-wide error codes."
1.806 + */
1.807 + IMPORT_C static CMMFVideoPostProcHwDevice* NewL(TUid aUid, MMMFDevVideoPlayProxy& aProxy);
1.808 +
1.809 + /**
1.810 + Destructor.
1.811 + */
1.812 + IMPORT_C virtual ~CMMFVideoPostProcHwDevice();
1.813 +
1.814 + /**
1.815 + Sets the device input format to an uncompressed video format.
1.816 +
1.817 + @param "aFormat" "The input format to use."
1.818 + @leave "The method will leave if an error occurs. Typical error codes used:
1.819 + * KErrNotSupported - The input format is not supported."
1.820 + @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
1.821 + */
1.822 + virtual void SetInputFormatL(const TUncompressedVideoFormat& aFormat) = 0;
1.823 +
1.824 + /**
1.825 + Sets the decoder device that will write data to this post-processor. Decoded pictures will be
1.826 + written with WritePictureL() or through a custom interface. After pictures have been processed,
1.827 + they must be returned to the decoder using ReturnPicture().
1.828 +
1.829 + @param "aDevice" "The decoder source plug-in to use."
1.830 + @pre "This method can only be called before the hwdevice has been initialized with Initialize()."
1.831 + */
1.832 + virtual void SetInputDevice(CMMFVideoDecodeHwDevice* aDevice) = 0;
1.833 +
1.834 + /**
1.835 + Writes an uncompressed video picture to the post-processor. The picture must be returned to the
1.836 + client or source plug-in after it has been used.
1.837 +
1.838 + @param "aPicture" "The picture to write."
1.839 + @leave "This method may leave with one of the system-wide error codes."
1.840 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.841 + */
1.842 + virtual void WritePictureL(TVideoPicture* aPicture) = 0;
1.843 +protected:
1.844 + /**
1.845 + Constructor.
1.846 + */
1.847 + IMPORT_C CMMFVideoPostProcHwDevice();
1.848 +
1.849 + /**
1.850 + Set the proxy implementation to be used. Called just after the object is constructed.
1.851 + @param "aProxy" "The proxy to use."
1.852 + */
1.853 + virtual void SetProxy(MMMFDevVideoPlayProxy& aProxy) = 0;
1.854 +private:
1.855 + TUid iDtor_ID_Key;
1.856 + };
1.857 +
1.858 +
1.859 +
1.860 +/**
1.861 +A custom interface extending the functionality of CMMFVideoPlayHwDevice, adding support for the decoder to handle the
1.862 +copying of the bitstream data into the buffers, combining this with a scan of the data and support for the passing of
1.863 +information from the client to the decoder describing what part of a frame the data contains.
1.864 +@publishedAll
1.865 +@released
1.866 +*/
1.867 +class MMMFVideoPlayHwDeviceExtensionScanCopy
1.868 + {
1.869 +public:
1.870 + /**
1.871 + Writes a piece of coded video data to the decoder. The data buffer must be retrieved from the
1.872 + decoder with GetBufferL().
1.873 +
1.874 + @param "aBuffer" "The coded data unit to write."
1.875 + @param "aPortion" "The portion of the frame that the data contains. Defaults to EFramePortionUnknown."
1.876 + @leave "This method may leave with one of the system-wide error codes."
1.877 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.878 + */
1.879 + virtual void WriteCodedDataL(TVideoInputBuffer* aBuffer, TFramePortion aPortion = EFramePortionUnknown) = 0;
1.880 + /**
1.881 + Passes a pointer to a piece of coded video data to the decoder. The data buffer, which is left empty by the client,
1.882 + must be retrieved from the decoder with GetBufferL().
1.883 +
1.884 + @param "aCodedData" "A pointer to the coded data unit to scan and copy."
1.885 + @param "aBuffer" "The empty data buffer."
1.886 + @param "aPortion" "The portion of the frame that the data contains. Defaults to EFramePortionUnknown."
1.887 + @leave "This method may leave with one of the system-wide error codes."
1.888 + @pre "This method can only be called after the hwdevice has been initialized with Initialize()."
1.889 + */
1.890 + virtual void ScanAndCopyCodedDataL(TPtr8 aCodedData, TVideoInputBuffer* aBuffer, TInt& aConsumed, TFramePortion aPortion = EFramePortionUnknown) = 0;
1.891 + };
1.892 +
1.893 +inline void CMMFVideoDecodeHwDevice::ConfigureDecoderL(const TVideoPictureHeader& /*aVideoPictureHeader*/)
1.894 + {
1.895 + User::Leave(KErrNotSupported);
1.896 + }
1.897 +
1.898 +
1.899 +
1.900 +#endif