1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/mm/mmhais/videohai/devvideo/inc/devvideoplay.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,2071 @@
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 __DEVVIDEOPLAY_H__
1.20 +#define __DEVVIDEOPLAY_H__
1.21 +
1.22 +#include <e32std.h>
1.23 +#include <mmf/devvideo/devvideobase.h>
1.24 +
1.25 +class MMMFDevVideoPlayObserver;
1.26 +class CMMFVideoPlayHwDevice;
1.27 +class CMMFVideoDecodeHwDevice;
1.28 +class CMMFVideoPostProcHwDevice;
1.29 +
1.30 +
1.31 +/**
1.32 +MMMFDevVideoPlayProxy is the interface to the CMMFDevVideoPlay API implementation that the hardware devices
1.33 +use to deliver data back to the client and report their progress to the API implementation.
1.34 +@publishedAll
1.35 +@released
1.36 +*/
1.37 +class MMMFDevVideoPlayProxy
1.38 + {
1.39 +public:
1.40 + /**
1.41 + Delivers a new decoded picture to the client. The CMMFDevVideoPlay implementation will maintain
1.42 + a list of decoded pictures and implement GetNewPictureInfo() and NextPictureL() based on those.
1.43 + The pictures will be returned back to the hardware device using ReturnPicture().
1.44 +
1.45 + @param "aPicture" "The newly processed picture."
1.46 + */
1.47 + virtual void MdvppNewPicture(TVideoPicture* aPicture) = 0;
1.48 +
1.49 + /**
1.50 + Notifies the client that one or more new empty input buffers are available. Called by the decoder
1.51 + hardware device.
1.52 + */
1.53 + virtual void MdvppNewBuffers() = 0;
1.54 +
1.55 + /**
1.56 + Returns a used input video picture back to the caller. Called by a post-processor hardware device
1.57 + after the picture has been processed and the picture source was the client, not another plug-in.
1.58 +
1.59 + @param "aPicture" "The picture to return."
1.60 + */
1.61 + virtual void MdvppReturnPicture(TVideoPicture* aPicture) = 0;
1.62 +
1.63 + /**
1.64 + Delivers supplemental information from a decoder hardware device to the client.
1.65 + The information is codec-dependent. The method is synchronous - the client
1.66 + MMMFDevVideoPlayObserver::MdvppSupplementalInformation() method is called immediately,
1.67 + and the memory for the supplemental information can be re-used when the call returns.
1.68 +
1.69 + @param "aData" "The supplemental data."
1.70 + @param "aTimestamp" "The presentation timestamp for the picture that the supplemental data is part of."
1.71 + @param "aPictureId" "Picture identifier for the picture. If a picture ID is not available,
1.72 + aPictureId.iIdType is set to ENone."
1.73 + */
1.74 + virtual void MdvppSupplementalInformation(const TDesC8& aData,
1.75 + const TTimeIntervalMicroSeconds& aTimestamp, const TPictureId& aPictureId) = 0;
1.76 +
1.77 + /**
1.78 + Back channel information, indicating a picture loss without specifying the lost picture.
1.79 + */
1.80 + virtual void MdvppPictureLoss() = 0;
1.81 +
1.82 + /**
1.83 + Back channel information, indicating the pictures that have been lost.
1.84 +
1.85 + @param "aPictures" "Picture identifiers for the lost pictures. The reference is only valid
1.86 + until the method returns."
1.87 + */
1.88 + virtual void MdvppPictureLoss(const TArray<TPictureId>& aPictures) = 0;
1.89 +
1.90 + /**
1.91 + Back channel information, indicating the loss of consecutive macroblocks in raster scan order.
1.92 +
1.93 + @param "aFirstMacroblock" "The first lost macroblock. The macroblocks are numbered
1.94 + such that the macroblock in the upper left corner of the picture is
1.95 + considered macroblock number 1 and the number for each macroblock increases
1.96 + from left to right and then from top to bottom in raster-scan order."
1.97 + @param "aNumMacroblocks" "The number of lost macroblocks that are consecutive in raster-scan order."
1.98 + @param "aPicture" "The picture identifier for the picture where the macroblocks were lost.
1.99 + If the picture is not known, aPicture.iIdType is set to ENone. The
1.100 + reference is only valid until the method returns."
1.101 + */
1.102 + virtual void MdvppSliceLoss(TUint aFirstMacroblock, TUint aNumMacroblocks, const TPictureId& aPicture)= 0;
1.103 +
1.104 + /**
1.105 + Back channel information from the decoder, indicating a reference picture selection request.
1.106 + The request is delivered as a coding-standard specific binary message. Reference picture selection
1.107 + can be used to select a pervious correctly transmitted picture to use as a reference in case later
1.108 + pictures have been lost.
1.109 +
1.110 + @param "aSelectionData" "The reference picture selection request message. The message format is
1.111 + coding-standard specific, and defined separately. The reference is only
1.112 + valid until the method returns."
1.113 + */
1.114 + virtual void MdvppReferencePictureSelection(const TDesC8& aSelectionData)= 0;
1.115 +
1.116 + /**
1.117 + Delivers a timed snapshot result to the client. The memory reserved for the snapshot picture
1.118 + can no longer be used in the device.
1.119 +
1.120 + @param "aError" "An error code, KErrNone if no errors occurred.
1.121 + If an error occurred, the data in the snapshot may not be valid,
1.122 + but the memory can still be freed."
1.123 + @param "aPictureData" "The snapshot picture data."
1.124 + @param "aPresentationTimestamp" "The presentation timestamp for the snapshot picture."
1.125 + @param "aPictureId" "Picture identifier for the picture. If a picture ID is not
1.126 + available, aPictureId.iIdType is set to ENone."
1.127 + */
1.128 + virtual void MdvppTimedSnapshotComplete(TInt aError, TPictureData* aPictureData,
1.129 + const TTimeIntervalMicroSeconds& aPresentationTimestamp, const TPictureId& aPictureId) = 0;
1.130 +
1.131 + /**
1.132 + Reports a fatal error to the client. The device must automatically stop processing
1.133 + video data when such errors occur, and may not do further processing before it has
1.134 + been deleted and re-created.
1.135 +
1.136 + @param "aDevice" "The device that reported the error."
1.137 + @param "aError" "The error code."
1.138 + */
1.139 + virtual void MdvppFatalError(CMMFVideoHwDevice* aDevice, TInt aError) = 0;
1.140 +
1.141 + /**
1.142 + Reports that an asynchronous Initialize() method has completed.
1.143 + The device is now ready for playback.
1.144 +
1.145 + @param "aDevice" "The device that was initialzied."
1.146 + @param "aError" "Initialization result error code, KErrNone if initialization was successful."
1.147 + */
1.148 + virtual void MdvppInitializeComplete(CMMFVideoHwDevice* aDevice, TInt aError) = 0;
1.149 +
1.150 + /**
1.151 + Reports that the input video stream end has been reached and all pictures have been processed.
1.152 + Called by each hardware device after their InputEnd() methods have been called and all data has
1.153 + been processed. The proxy implementation will notify the client about stream end when all
1.154 + hardware devices have called this method.
1.155 + */
1.156 + virtual void MdvppStreamEnd() = 0;
1.157 + };
1.158 +
1.159 +
1.160 +/**
1.161 +A buffer for compressed video data, contains one coded data unit. Video buffers are used for writing
1.162 +video data to the API.
1.163 +
1.164 +@publishedAll
1.165 +@released
1.166 +*/
1.167 +class TVideoInputBuffer
1.168 + {
1.169 +public:
1.170 + /**
1.171 + Default constructor. Zeroes all members (including iData which will point to garbage until manually
1.172 + set to point to the real video buffer memory data area by the user).
1.173 + */
1.174 + IMPORT_C TVideoInputBuffer();
1.175 +
1.176 +public:
1.177 + /**
1.178 + */
1.179 + enum TVideoBufferOptions
1.180 + {
1.181 + /** The sequence number field is valid. */
1.182 + ESequenceNumber = 0x00000001,
1.183 + /** The decoding timestamp field is valid */
1.184 + EDecodingTimestamp = 0x00000002,
1.185 + /** The presentation timestamp field is valid.*/
1.186 + EPresentationTimestamp = 0x00000004,
1.187 + /** Content protected pictures cannot be displayed on unprotected
1.188 + external displays such as TV-out.
1.189 + */
1.190 + EContentProtected = 0x00000008
1.191 + };
1.192 +
1.193 + /**
1.194 + Pointer to the video data.
1.195 + */
1.196 + TPtr8 iData;
1.197 +
1.198 + /**
1.199 + Data unit options. The value is a bitfield combined from values from TVideoBufferOptions.
1.200 + @see TVideoBufferOptions
1.201 + */
1.202 + TUint32 iOptions;
1.203 +
1.204 + /**
1.205 + Data unit decoding timestamp. Valid if EDecodingTimestamp is set in the options.
1.206 + */
1.207 + TTimeIntervalMicroSeconds iDecodingTimestamp;
1.208 +
1.209 + /**
1.210 + Data unit presentation timestamp. Valid if EPresentationTimestamp is set in the options.
1.211 + If the input bitstream does not contain timestamp information, this field should be valid,
1.212 + otherwise pictures cannot be displayed at the correct time. If the input bitstream contains
1.213 + timestamp information (such as the TR syntax element of H.263 bitstreams) and valid
1.214 + iPresentationTimestamp is provided, the value of iPresentationTimestamp is used in playback.
1.215 + */
1.216 + TTimeIntervalMicroSeconds iPresentationTimestamp;
1.217 +
1.218 + /**
1.219 + True if the data is part of a pre-roll period and may not be drawn. The decoder may skip
1.220 + display-related operations, but must still decode normally since pre-roll may not end in a key
1.221 + frame.
1.222 + */
1.223 + TBool iPreRoll;
1.224 +
1.225 + /**
1.226 + Data unit sequence number. Valid if ESequenceNumber is set in the options. If present, the
1.227 + sequence number is incremented once per coded data unit, a gap in the numbers indicates missing
1.228 + data.
1.229 + */
1.230 + TUint iSequenceNumber;
1.231 +
1.232 + /**
1.233 + True if the data unit is known to contain erroneous data.
1.234 + */
1.235 + TBool iError;
1.236 +
1.237 + /**
1.238 + A queue link used internally by the MSL API. The field must not be modified while the buffer is
1.239 + in the MSL API, but can be used by the client before the buffer has been written and after the
1.240 + buffer has been returned.
1.241 + */
1.242 + TDblQueLink iLink;
1.243 +
1.244 + /**
1.245 + A pointer for free-form user data. The pointer is set by the module that created the buffer, and
1.246 + is usually used for memory management purposes.
1.247 + */
1.248 + TAny* iUser;
1.249 + };
1.250 +
1.251 +
1.252 +/**
1.253 +This class contains information about the post-processing functionality that a single post-processor
1.254 +or decoder hardware device has. Although it mainly contains static data, it is defined as a complete
1.255 +CBase-derived class since the data is relatively complex and proper memory management is necessary.
1.256 +
1.257 +The objects are created by the post-processor or decoder devices, and used by the MSL video client code.
1.258 +@publishedAll
1.259 +@released
1.260 +*/
1.261 +class CPostProcessorInfo : public CBase
1.262 + {
1.263 +public:
1.264 + /**
1.265 + Creates and returns a new CPostProcessorInfo object.
1.266 +
1.267 + @param "aUid" "The UID of the post-processor."
1.268 + @param "aManufacturer" "The manufacturer of the post-processor hw device."
1.269 + @param "aIdentifier" "The post-processor hw device manufacturer-specific
1.270 + identifier."
1.271 + @param "aVersion" "The post-processor version."
1.272 + @param "aSupportedFormats" "The source formats supported by the post-processor."
1.273 + @param "aSupportedCombinations" "The supported post-processing combinations. An array of
1.274 + values created by the bitwise OR-ing of values from
1.275 + TPrePostProcessType."
1.276 + @param "aAccelerated" "Whether the post processor is hardware-accelerated.
1.277 + Accelerated post-processors can run on an application DSP
1.278 + or dedicated hardware."
1.279 + @param "aSupportsDirectDisplay" "Whether the hw device supports output directly to the
1.280 + screen."
1.281 + @param "aYuvToRgbCapabilities" "The post-processor YUV to RGB conversion capabilities."
1.282 + @param "aSupportedRotations" "A bitwise OR of values of TRotationType to indicate the
1.283 + supported rotation types."
1.284 + @param "aSupportArbitraryScaling" "Whether the post-processor supports arbitrary scaling."
1.285 + @param "aSupportedScaleFactors" "A list of the discrete scaling factors supported. If the
1.286 + post-processor supports arbitrary scaling, this list should
1.287 + be left zero-length."
1.288 + @param "aAntiAliasedScaling" "Whether anti-aliasing filtering for scaling is supported."
1.289 + @param "aImplementationSpecificInfo" "Implementation-specific information."
1.290 +
1.291 + @return "A new CPostProcessorInfo object."
1.292 + @leave "This method may leave with one of the system-wide error codes."
1.293 + */
1.294 + IMPORT_C static CPostProcessorInfo* NewL(TUid aUid,
1.295 + const TDesC& aManufacturer,
1.296 + const TDesC& aIdentifier,
1.297 + TVersion aVersion,
1.298 + const TArray<TUncompressedVideoFormat>& aSupportedFormats,
1.299 + const TArray<TUint32>& aSupportedCombinations,
1.300 + TBool aAccelerated,
1.301 + TBool aSupportsDirectDisplay,
1.302 + const TYuvToRgbCapabilities& aYuvToRgbCapabilities,
1.303 + TUint32 aSupportedRotations,
1.304 + TBool aSupportArbitraryScaling,
1.305 + const TArray<TScaleFactor>& aSupportedScaleFactors,
1.306 + TBool aAntiAliasedScaling,
1.307 + const TDesC8& aImplementationSpecificInfo = KNullDesC8);
1.308 +
1.309 + /**
1.310 + Destructor
1.311 + */
1.312 + IMPORT_C ~CPostProcessorInfo();
1.313 +
1.314 + /**
1.315 + Returns the post-processor UID.
1.316 + @return "Post-processor UID"
1.317 + */
1.318 + IMPORT_C TUid Uid() const;
1.319 +
1.320 + /**
1.321 + Returns the post-processor hardware device manufacturer.
1.322 + @return "The manufacturer name as a standard Symbian descriptor. The reference is valid until the
1.323 + CPostProcessorInfo object is destroyed."
1.324 + */
1.325 + IMPORT_C const TDesC& Manufacturer() const;
1.326 +
1.327 + /**
1.328 + Returns the post-processor hardware device manufacturer-specific identifier.
1.329 + The combination of the manufacturer and identifier uniquely identifies the device.
1.330 + @return "The identifier as a standard Symbian descriptor. The reference is valid until the
1.331 + CPostProcessorInfo object is destroyed."
1.332 + */
1.333 + IMPORT_C const TDesC& Identifier() const;
1.334 +
1.335 + /**
1.336 + Returns the post-processor version.
1.337 + @return "Post-processor version."
1.338 + */
1.339 + IMPORT_C TVersion Version() const;
1.340 +
1.341 + /**
1.342 + Checks if the post-processor supports the given format as a source format.
1.343 + @param "aFormat" "The format to check. The reference is not used after the method returns."
1.344 + @return "ETrue if the post-processor supports the given format, EFalse if not."
1.345 + */
1.346 + IMPORT_C TBool SupportsFormat(const TUncompressedVideoFormat& aFormat) const;
1.347 +
1.348 + /**
1.349 + Lists the source formats supported by the post-processor.
1.350 + @return "A RArray table of supported video formats (TUncompressedVideoFormat). The reference is
1.351 + valid until the CPostProcessorInfo object is destroyed."
1.352 + */
1.353 + IMPORT_C const RArray<TUncompressedVideoFormat>& SupportedFormats() const;
1.354 +
1.355 + /**
1.356 + Checks if the post-processor supports the given post-processing combination.
1.357 + @param "aCombination" "Post-processing combination, a bitwise OR of values from TPrePostProcessType."
1.358 + @return "ETrue if the post-processing combination is supported, EFalse if not."
1.359 + */
1.360 + IMPORT_C TBool SupportsCombination(TUint32 aCombination) const;
1.361 +
1.362 + /**
1.363 + Lists all supported post-processing combinations.
1.364 + @return "A RArray table or post-processing combinations. Each value is a bitwise OR of values from
1.365 + TPrePostProcessType. The reference is valid until the CPostProcessorInfo object is destroyed."
1.366 + */
1.367 + IMPORT_C const RArray<TUint32>& SupportedCombinations() const;
1.368 +
1.369 + /**
1.370 + Returns whether the hardware device is hardware-accelerated. Hardware-accelerated post-processors
1.371 + can run on an application DSP or dedicated hardware.
1.372 + @return "ETrue if the device is hardware-accelerated."
1.373 + */
1.374 + IMPORT_C TBool Accelerated() const;
1.375 +
1.376 + /**
1.377 + Returns whether the hardware device supports output directly to the screen. Output to memory buffers
1.378 + is always supported.
1.379 + @return "ETrue if the post-processor supports direct screen output."
1.380 + */
1.381 + IMPORT_C TBool SupportsDirectDisplay() const;
1.382 +
1.383 + /**
1.384 + Returns the post-processor YUV to RGB color conversion capabilities.
1.385 + @return "The conversion capabilities as a TYuvToRgbCapabilities structure. The reference is valid
1.386 + until the CPostProcessorInfo object is destroyed. If the post-processor does not support
1.387 + YUV to RGB conversion, the contents are undefined."
1.388 + */
1.389 + IMPORT_C const TYuvToRgbCapabilities& YuvToRgbCapabilities() const;
1.390 +
1.391 + /**
1.392 + Returns the rotation types the post-processor supports.
1.393 + @return "The supported rotation types as a bitwise OR of TRotationType values. If the
1.394 + post-processor does not support rotation, the return value is zero."
1.395 + */
1.396 + IMPORT_C TUint32 SupportedRotations() const;
1.397 +
1.398 + /**
1.399 + Returns whether the post-processor supports arbitrary scaling. If arbitrary scaling is not
1.400 + supported, a limited selection of scaling factors may still be available, use
1.401 + SupportedScaleFactors() to retrieve those.
1.402 + @return "ETrue if the post-processor supports arbitrary scaling, EFalse if not."
1.403 + */
1.404 + IMPORT_C TBool SupportsArbitraryScaling() const;
1.405 +
1.406 + /**
1.407 + Returns the scaling factors the post-processor supports. If the post-processor supports arbitrary
1.408 + scaling the list is empty - use SupportsArbitraryScaling() first.
1.409 + @return "A RArray list of supported scale factors (TScaleFactor). The reference is valid until the
1.410 + CPostProcessorInfo object is destroyed. If the post-processor supports arbitrary scaling
1.411 + or no scaling at all, the list is empty."
1.412 + */
1.413 + IMPORT_C const RArray<TScaleFactor>& SupportedScaleFactors() const;
1.414 +
1.415 + /**
1.416 + Returns whether the hardware device supports anti-aliasing filtering for scaling.
1.417 + @return "True if anti-aliasing filtering is supported."
1.418 + */
1.419 + IMPORT_C TBool AntiAliasedScaling() const;
1.420 +
1.421 + /**
1.422 + Returns implementation-specific information about the post-processor.
1.423 + @return "Implementation- specific information about the post-processor. The data format is
1.424 + implementation-specific, and defined separately by the post-processor supplier. The
1.425 + reference is valid until the CPostProcessorInfo object is destroyed."
1.426 + */
1.427 + IMPORT_C const TDesC8& ImplementationSpecificInfo() const;
1.428 +
1.429 + /**
1.430 + Adds the screen number into the list of screens supported by the post processor.
1.431 + @leave "KErrNoMemory when there is no memory to expand the list of supported screens.
1.432 + KErrNotSupported if the secondary screen display is not supported in Multimedia Framework."
1.433 + */
1.434 + IMPORT_C void AddSupportedScreenL(TInt aScreenNo);
1.435 +
1.436 + /**
1.437 + Lists the screens supported by the post processor.
1.438 + @param "aSupportedScreens" "An array to retrieve the list of supported screens.
1.439 + This method resets the array before adding elements to it.
1.440 + The array must be created and destroyed by the caller."
1.441 + @leave "KErrNotSupported if the secondary screen display is not supported in Multimedia Framework.
1.442 + KErrNoMemory when there is no memory to expand the list."
1.443 + */
1.444 + IMPORT_C void GetSupportedScreensL(RArray<TInt>& aSupportedScreens) const;
1.445 +
1.446 + /** Sets a flag indicating whether the PostProcessor supports per picture content protection.
1.447 + E.g. Where content protection within a video stream can alter.
1.448 + @param "aSetting" "Set to TRUE to indicate PostProcessor supports content protection.
1.449 + @See TVideoPicture::TVideoPictureOptions::EContentProtected
1.450 + @See TVideoInputBuffer::TVideoBufferOptions::EContentProtected
1.451 + */
1.452 + IMPORT_C void SetSupportsContentProtected(const TBool aSetting);
1.453 +
1.454 + /** Returns whether the PostProcessor supports per picture content protection.
1.455 + E.g. Where content protection within a video stream can alter.
1.456 + @return "True if the PostProcessor supports Content Protection."
1.457 + @See TVideoPicture::TVideoPictureOptions::EContentProtected
1.458 + @See TVideoInputBuffer::TVideoBufferOptions::EContentProtected
1.459 + */
1.460 + IMPORT_C TBool SupportsContentProtected() const;
1.461 +
1.462 +private:
1.463 + CPostProcessorInfo(TUid aUid,
1.464 + TVersion aVersion,
1.465 + TBool aAccelerated,
1.466 + TBool aSupportDirectDisplay,
1.467 + const TYuvToRgbCapabilities& aYuvToRgbCapabilities,
1.468 + TUint32 aSupportedRotations,
1.469 + TBool aSupportArbitraryScaling,
1.470 + TBool aAntiAliasedScaling);
1.471 +
1.472 + void ConstructL(const TDesC& aManufacturer,
1.473 + const TDesC& aIdentifier,
1.474 + const TArray<TUncompressedVideoFormat>& aSupportedFormats,
1.475 + const TArray<TUint32>& aSupportedCombinations,
1.476 + const TArray<TScaleFactor>& aSupportedScaleFactors,
1.477 + const TDesC8& aImplementationSpecificInfo);
1.478 +private:
1.479 + TUid iUid;
1.480 + TVersion iVersion;
1.481 + TBool iAccelerated;
1.482 + TBool iSupportDirectDisplay;
1.483 + TYuvToRgbCapabilities iYuvToRgbCapabilities;
1.484 + TUint32 iSupportedRotations;
1.485 + TBool iSupportArbitraryScaling;
1.486 + TBool iAntiAliasedScaling;
1.487 + HBufC* iManufacturer;
1.488 + HBufC* iIdentifier;
1.489 + HBufC8* iImplementationSpecificInfo;
1.490 + RArray<TUncompressedVideoFormat> iSupportedFormats;
1.491 + RArray<TUint32> iSupportedCombinations;
1.492 + RArray<TScaleFactor> iSupportedScaleFactors;
1.493 + RArray<TInt> iSupportedScreens;
1.494 + TBool iSupportsContentProtected;
1.495 + };
1.496 +
1.497 +
1.498 +/**
1.499 +This class contains information about a single video decoder. Although it mainly contains static data,
1.500 +it is defined as a complete CBase-derived class since the data is relatively complex and proper memory
1.501 +management is necessary.
1.502 +
1.503 +The objects are created by the video decoder hardware devices, and used by the MSL video client code.
1.504 +@publishedAll
1.505 +@released
1.506 +*/
1.507 +class CVideoDecoderInfo : public CBase
1.508 + {
1.509 +public:
1.510 + /**
1.511 + Creates and returns a new CVideoDecoderInfo object.
1.512 +
1.513 + @param "aUid" "The uid of the decoder."
1.514 + @param "aManufacturer" "The video decoder manufacturer."
1.515 + @param "aIdentifier" "The manufacturer-specific identifier for this video decoder."
1.516 + @param "aVersion" "The version of this video decoder."
1.517 + @param "aSupportedFormats" "An array of the formats supported by the decoder.
1.518 + A copy will be taken of the array and the referenced
1.519 + CCompressedVideoFormat objects"
1.520 + @param "aAccelerated" "Whether this decoder is accelerated or not."
1.521 + @param "aSupportsDirectDisplay" "Whether this decoder supports direct display or not."
1.522 + @param "aMaxPictureSize" "The maximum picture size supported by the decoder."
1.523 + @param "aMaxBitrate" "The maximum bit rate supported by the decoder. Use KMaxTUint32 if there are no bit-rate restrictions."
1.524 + @param "aMaxPictureRates" "An array of the maximum picture size/rate combinations supported by the decoder."
1.525 + @param "aSupportsPictureLoss" "Whether the decoder supports picture loss indications."
1.526 + @param "aSupportsSliceLoss" "Whether the decoder supports slice loss indications."
1.527 + @param "aCodingStandardSpecificInfo" "Coding-standard specific information about the decoder."
1.528 + @param "aImplementationSpecificInfo" "Implementation-specific information about the decoder."
1.529 +
1.530 + @return "A new CVideoDecoderInfo object."
1.531 + @leave "This method may leave with one of the system-wide error codes."
1.532 + */
1.533 + IMPORT_C static CVideoDecoderInfo* NewL(TUid aUid,
1.534 + const TDesC& aManufacturer,
1.535 + const TDesC& aIdentifier,
1.536 + TVersion aVersion,
1.537 + const TArray<CCompressedVideoFormat*>& aSupportedFormats,
1.538 + TBool aAccelerated,
1.539 + TBool aSupportsDirectDisplay,
1.540 + const TSize& aMaxPictureSize,
1.541 + TUint aMaxBitrate,
1.542 + const TArray<TPictureRateAndSize>& aMaxPictureRates,
1.543 + TBool aSupportsPictureLoss,
1.544 + TBool aSupportsSliceLoss,
1.545 + const TDesC8& aCodingStandardSpecificInfo = KNullDesC8,
1.546 + const TDesC8& aImplementationSpecificInfo = KNullDesC8);
1.547 +
1.548 + /**
1.549 + Destructor.
1.550 + */
1.551 + IMPORT_C ~CVideoDecoderInfo();
1.552 +
1.553 + /**
1.554 + Checks if the decoder supports the given format.
1.555 + @param "aFormat" "The format to check. The reference is not used after the method returns."
1.556 + @return "ETrue if the codec supports the given format, EFalse if not."
1.557 + */
1.558 + IMPORT_C TBool SupportsFormat(const CCompressedVideoFormat& aFormat) const;
1.559 +
1.560 + /**
1.561 + Lists the video formats, including submodes, supported by the decoder.
1.562 + @return "A RPointerArray table of supported video formats (CCompressedVideoFormat). The reference
1.563 + is valid until the CVideoDecoderInfo object is destroyed."
1.564 + */
1.565 + IMPORT_C const RPointerArray<CCompressedVideoFormat>& SupportedFormats() const;
1.566 +
1.567 + /**
1.568 + Returns the codec device manufacturer.
1.569 + @return "The manufacturer name as a standard Symbian descriptor. The reference is valid until the
1.570 + CVideoDecoderInfo object is destroyed."
1.571 + */
1.572 + IMPORT_C const TDesC& Manufacturer() const;
1.573 +
1.574 + /**
1.575 + Returns the codec device manufacturer-specific identifier. The combination of the manufacturer
1.576 + and identifier uniquely identifies the hardware device.
1.577 + @return "The identifier as a standard Symbian descriptor. The reference is valid until the
1.578 + CVideoDecoderInfo object is destroyed."
1.579 + */
1.580 + IMPORT_C const TDesC& Identifier() const;
1.581 +
1.582 + /**
1.583 + Returns the decoder version.
1.584 + @return "Decoder version."
1.585 + */
1.586 + IMPORT_C TVersion Version() const;
1.587 +
1.588 + /**
1.589 + Returns the decoder UID.
1.590 + @return "Decoder UID."
1.591 + */
1.592 + IMPORT_C TUid Uid() const;
1.593 +
1.594 + /**
1.595 + Returns whether the decoder is hardware-accelerated. A hardware-accelerated decoder can run on
1.596 + an application DSP or dedicated hardware.
1.597 + @return "True if the decoder is hardware-accelerated."
1.598 + */
1.599 + IMPORT_C TBool Accelerated() const;
1.600 +
1.601 + /**
1.602 + Returns whether the hardware device supports output directly to the screen. Output to memory
1.603 + buffers is always supported.
1.604 + @return "True if the hardware device supports direct screen output."
1.605 + */
1.606 + IMPORT_C TBool SupportsDirectDisplay() const;
1.607 +
1.608 + /**
1.609 + Returns the maximum picture size the decoder supports.
1.610 +
1.611 + Note that if the decoder reports that it supports a certain profile and level, then it
1.612 + shall support all bitstreams corresponding to that profile/level. This method can be used
1.613 + to specify capabilities that are beyond the standard levels (for example some MPEG-4 bitstreams
1.614 + are encoded with picture sizes that are larger than those specified by the profile/level of the
1.615 + bitstream).
1.616 +
1.617 + @return "The maximum picture size supported. The reference is valid until the CVideoDecoderInfo
1.618 + object is destroyed."
1.619 + */
1.620 + IMPORT_C const TSize& MaxPictureSize() const;
1.621 +
1.622 + /**
1.623 + Returns the maximum bit-rate supported by the decoder.
1.624 +
1.625 + Note that if the decoder reports that it supports a certain profile and level, then it shall
1.626 + support all bitstreams corresponding to that profile/level. This method can be used to
1.627 + specify capabilities that are beyond the standard levels (for example some MPEG-4 bitstreams
1.628 + are encoded with bit rates that are higher than those specified by the profile/level of the
1.629 + bitstream).
1.630 +
1.631 + @return "Maximum bit-rate supported, in bits per second. KMaxTUint32 can be used if the decoder
1.632 + has no bit-rate restrictions."
1.633 + */
1.634 + IMPORT_C TUint MaxBitrate() const;
1.635 +
1.636 + /**
1.637 + Returns the maximum picture size/rate combinations supported by the decoder.
1.638 +
1.639 + Video decoders can have different maximum picture rate limitations depending on the picture size used.
1.640 + Note that if the decoder reports that it supports a certain profile and level, then it shall
1.641 + support all bitstreams corresponding to that profile/level. This method can be used to specify
1.642 + capabilities that are beyond the standard levels (for example some MPEG-4 bitstreams are encoded
1.643 + with picture rates that are beyond those specified by the profile/level of the bitstream).
1.644 +
1.645 + @return "A reference to an array of picture size/rate combinations. The reference remains valid
1.646 + until this object is deleted."
1.647 + */
1.648 + IMPORT_C const RArray<TPictureRateAndSize>& MaxPictureRates() const;
1.649 +
1.650 + /**
1.651 + Returns whether the decoder supports picture loss indications. If true, the decoder indicates
1.652 + lost pictures by calling MdvpoPictureLoss().
1.653 +
1.654 + @return "True if the decoder supports picture loss indications."
1.655 + */
1.656 + IMPORT_C TBool SupportsPictureLoss() const;
1.657 +
1.658 + /**
1.659 + Returns whether the decoder supports slice loss indications. If true, the decoder indicates
1.660 + lost macroblocks by calling MdvpoSliceLoss().
1.661 +
1.662 + @return "True if the decoder supports slice loss indications."
1.663 + */
1.664 + IMPORT_C TBool SupportsSliceLoss() const;
1.665 +
1.666 + /**
1.667 + Returns coding-standard specific information about the decoder.
1.668 + @return "Coding-standard specific information about the decoder. The data format is coding-standard
1.669 + specific, and defined separately. The reference is valid until the CVideoDecoderInfo object
1.670 + is destroyed."
1.671 + */
1.672 + IMPORT_C const TDesC8& CodingStandardSpecificInfo() const;
1.673 +
1.674 + /**
1.675 + Returns implementation-specific information about the decoder.
1.676 + @return "Implementation- specific information about the decoder. The data format is
1.677 + implementation-specific, and defined separately by the decoder supplier. The reference
1.678 + is valid until the CVideoDecoderInfo object is destroyed."
1.679 + */
1.680 + IMPORT_C const TDesC8& ImplementationSpecificInfo() const;
1.681 +
1.682 + /**
1.683 + Adds the screen number into the list of screens supported by the decoder.
1.684 + @leave "KErrNoMemory when there is no memory to expand the list of supported screens.
1.685 + KErrNotSupported if the secondary screen display is not supported in Multimedia Framework."
1.686 + */
1.687 + IMPORT_C void AddSupportedScreenL(TInt aScreenNo);
1.688 +
1.689 + /**
1.690 + Lists the screens supported by the decoder.
1.691 + @param "aSupportedScreens" "An array to retrieve the list of supported screens.
1.692 + This method resets the array before adding elements to it.
1.693 + The array must be created and destroyed by the caller."
1.694 + @leave "KErrNotSupported if the secondary screen display is not supported in Multimedia Framework.
1.695 + KErrNoMemory when there is no memory to expand the list."
1.696 + */
1.697 + IMPORT_C void GetSupportedScreensL(RArray<TInt>& aSupportedScreens) const;
1.698 +
1.699 + /** Sets a flag indicating whether the Decoder supports per picture content protection.
1.700 + E.g. Where content protection within a video stream can alter.
1.701 + @param "aSetting" "Set to TRUE to indicate decoder supports content protection.
1.702 + @See TVideoPicture::TVideoPictureOptions::EContentProtected
1.703 + @See TVideoInputBuffer::TVideoBufferOptions::EContentProtected
1.704 + */
1.705 + IMPORT_C void SetSupportsContentProtected(const TBool aSetting);
1.706 +
1.707 + /** Returns whether the Decoder supports per picture content protection.
1.708 + E.g. Where content protection within a video stream can alter.
1.709 + @return "True if the Decoder supports Content Protection."
1.710 + @See TVideoPicture::TVideoPictureOptions::EContentProtected
1.711 + @See TVideoInputBuffer::TVideoBufferOptions::EContentProtected
1.712 + */
1.713 + IMPORT_C TBool SupportsContentProtected() const;
1.714 +
1.715 +private:
1.716 + CVideoDecoderInfo(TUid aUid,
1.717 + TVersion aVersion,
1.718 + TBool aAccelerated,
1.719 + TBool aSupportsDirectDisplay,
1.720 + const TSize& aMaxPictureSize,
1.721 + TUint aMaxBitrate,
1.722 + TBool aSupportsPictureLoss,
1.723 + TBool aSupportsSliceLoss);
1.724 +
1.725 + void ConstructL(const TDesC& aManufacturer,
1.726 + const TDesC& aIdentifier,
1.727 + const TArray<CCompressedVideoFormat*>& aSupportedFormats,
1.728 + const TArray<TPictureRateAndSize>& aMaxPictureRates,
1.729 + const TDesC8& aCodingStandardSpecificInfo,
1.730 + const TDesC8& aImplementationSpecificInfo);
1.731 +private:
1.732 + TUid iUid;
1.733 + TVersion iVersion;
1.734 + TBool iAccelerated;
1.735 + TBool iSupportsDirectDisplay;
1.736 + TSize iMaxPictureSize;
1.737 + TUint iMaxBitrate;
1.738 + TBool iSupportsPictureLoss;
1.739 + TBool iSupportsSliceLoss;
1.740 + HBufC* iManufacturer;
1.741 + HBufC* iIdentifier;
1.742 + RPointerArray<CCompressedVideoFormat> iSupportedFormats;
1.743 + RArray<TPictureRateAndSize> iMaxPictureRates;
1.744 + HBufC8* iCodingStandardSpecificInfo;
1.745 + HBufC8* iImplementationSpecificInfo;
1.746 + RArray<TInt> iSupportedScreens;
1.747 + TBool iSupportsContentProtected;
1.748 + };
1.749 +
1.750 +
1.751 +
1.752 +
1.753 +/**
1.754 +CMMFDevVideoPlay is the main client API for DevVideoPlay.
1.755 +@publishedAll
1.756 +@released
1.757 +*/
1.758 +class CMMFDevVideoPlay : public CBase, private MMMFDevVideoPlayProxy
1.759 + {
1.760 +public:
1.761 + /**
1.762 + Picture statistic counters. Used for following playback progress. The counters can be retrieved
1.763 + using GetPictureCounters() and are reset after each call. The client must keep track of the
1.764 + cumulative values for counters and picture processing rates itself if necessary.
1.765 + */
1.766 + class TPictureCounters
1.767 + {
1.768 + public:
1.769 + /**
1.770 + Default constructor. Zeros all members.
1.771 + */
1.772 + inline TPictureCounters();
1.773 + public:
1.774 + /**
1.775 + The number of pictures skipped due to lack of processing power. This does not include pictures
1.776 + inside data bytes discarded due to buffer overflows, but includes all pictures skipped at
1.777 + picture decoding, post-processing and rendering phase.
1.778 + */
1.779 + TUint iPicturesSkipped;
1.780 +
1.781 + /**
1.782 + The number of pictures decoded.
1.783 + */
1.784 + TUint iPicturesDecoded;
1.785 +
1.786 + /**
1.787 + The number of pictures "virtually" displayed. "Virtually" displayed pictures are pictures
1.788 + that have been drawn on the screen, when using direct rendering, or pictures that have been
1.789 + decoded, processed, and delivered to the client when not using direct rendering.
1.790 + */
1.791 + TUint iPicturesDisplayed;
1.792 +
1.793 + /**
1.794 + The total number of pictures in the input bitstream. This figure does not include pictures that
1.795 + have been lost due to transmission errors, since those have not been processed by the MSL
1.796 + hardware devices, but does include pictures that have been discarded by the HW devices due
1.797 + to buffer overflows or other reasons.
1.798 + */
1.799 + TUint iTotalPictures;
1.800 + };
1.801 +
1.802 + /**
1.803 + Bitstream statistic counters, used for following decoding progress. The counters can be retrieved
1.804 + using GetBitstreamCounters() and are reset after each call. The client must keep track of the
1.805 + cumulative values for counters itself if necessary.
1.806 + */
1.807 + class TBitstreamCounters
1.808 + {
1.809 + public:
1.810 + /**
1.811 + Default constructor. Zeros all members.
1.812 + */
1.813 + inline TBitstreamCounters();
1.814 + public:
1.815 + /**
1.816 + Number of lost packets. This figure includes all packets that have been dropped by the hardware
1.817 + devices due to buffer overruns, but it does not include packets lost due to transmission errors.
1.818 + */
1.819 + TUint iLostPackets;
1.820 +
1.821 + /**
1.822 + Total number of packets. This figure includes all the packets that have been received by the
1.823 + decoder, including packets that have been dropped due to buffer overruns.
1.824 + */
1.825 + TUint iTotalPackets;
1.826 + };
1.827 +
1.828 + /**
1.829 + Buffer options used with SetBufferOptionsL().
1.830 + */
1.831 + class TBufferOptions
1.832 + {
1.833 + public:
1.834 + /**
1.835 + Default constructor. Zeros all members.
1.836 + */
1.837 + inline TBufferOptions();
1.838 +
1.839 + public:
1.840 + /**
1.841 + Pre-decoder buffer size in bytes. Set to zero to use decoder default value.
1.842 + */
1.843 + TUint iPreDecodeBufferSize;
1.844 +
1.845 + /**
1.846 + Maximum post-decoder buffer size in bytes. Set to zero to remove limitations.
1.847 + */
1.848 + TUint iMaxPostDecodeBufferSize;
1.849 +
1.850 + /**
1.851 + Initial pre-decoder buffering period, the amount of coded data to be buffered before decoding
1.852 + starts. If the value is set to zero, decoding begins immediately when all data associated with
1.853 + the first decoding timestamp is received. Default value is zero.
1.854 + */
1.855 + TTimeIntervalMicroSeconds iPreDecoderBufferPeriod;
1.856 +
1.857 + /**
1.858 + The amount of data buffered after the decoding before playback starts. If the value is zero,
1.859 + playback begins immediately when the first picture has been decoded. The default value is zero.
1.860 + */
1.861 + TTimeIntervalMicroSeconds iPostDecoderBufferPeriod;
1.862 +
1.863 + /**
1.864 + The maximum input buffer size that the client will request. If the buffer options have been
1.865 + set successfully, the decoder must be able to supply buffers of this size. If no information
1.866 + is available about the bitstream, the client may have to set this value to a relatively large
1.867 + value, and thus the decoder should not by default allocate buffers of this size before they
1.868 + are explicitly requested.
1.869 + */
1.870 + TUint iMaxInputBufferSize;
1.871 +
1.872 + /**
1.873 + The minimum number of input buffers the decoder needs to have available. This is the number of
1.874 + buffers the client can request through GetBufferL() before writing any back using
1.875 + WriteCodedDataL().
1.876 + */
1.877 + TUint iMinNumInputBuffers;
1.878 + };
1.879 +
1.880 + /**
1.881 + Information about a single computational complexity level.
1.882 + */
1.883 + class TComplexityLevelInfo
1.884 + {
1.885 + public:
1.886 + enum TOptions
1.887 + {
1.888 + /** The average picture rate field is valid. */
1.889 + EAvgPictureRate = 0x00000001,
1.890 + /** The picture size field is valid. */
1.891 + EPictureSize = 0x00000002,
1.892 + /** The relative image quality field is valid. */
1.893 + ERelativeImageQuality = 0x00000004,
1.894 + /** The required MIPS field is valid. */
1.895 + ERequiredMIPS = 0x00000008,
1.896 + /** The relative processing time field is valid. */
1.897 + ERelativeProcessTime = 0x00000010
1.898 + };
1.899 + /**
1.900 + Structure options. The value is a bitfield combined from values from TOptions.
1.901 + */
1.902 + TUint32 iOptions;
1.903 +
1.904 + /**
1.905 + The average picture rate, in pictures per second. Valid only if EAvgPictureRate is set in the
1.906 + options. This value depends on the input bitstream, and may not be available if enough
1.907 + bitstream has not been read.
1.908 + */
1.909 + TReal iAvgPictureRate;
1.910 +
1.911 + /**
1.912 + Picture size (spatial resolution), in pixels. Valid only if EPictureSize is set in the options.
1.913 + */
1.914 + TSize iPictureSize;
1.915 +
1.916 + /**
1.917 + Relative image quality, compared to the best available level. 1.0 is the quality at the
1.918 + maximum quality level (level zero). Valid only if ERelativeImageQuality is set in the options.
1.919 + */
1.920 + TReal iRelativeImageQuality;
1.921 +
1.922 + /**
1.923 + The number of MIPS required to process the data. Valid only if ERequiredMIPS is set in
1.924 + the options.
1.925 + */
1.926 + TUint iRequiredMIPS;
1.927 +
1.928 + /**
1.929 + Relative amount of processing time needed compared to standard-compliant decoding of all data.
1.930 + 1.0 is the processing time required for full processing, which usually corresponds to
1.931 + complexity level zero. Valid only if ERelativeProcessTime is set in the options.
1.932 + */
1.933 + TReal iRelativeProcessTime;
1.934 + };
1.935 +
1.936 +public:
1.937 +
1.938 + /**
1.939 + Constructs a new MSL video client instance. Each client instance supports a single video bitstream.
1.940 +
1.941 + @param aObserver
1.942 + The observer object to use.
1.943 +
1.944 + @return A pointer to a new CMMFDevVideoPlay object.
1.945 + @leave This method may leave with one of the system-wide error codes.
1.946 + */
1.947 + IMPORT_C static CMMFDevVideoPlay* NewL(MMMFDevVideoPlayObserver& aObserver);
1.948 +
1.949 + /**
1.950 + Destructor.
1.951 + */
1.952 + IMPORT_C ~CMMFDevVideoPlay();
1.953 +
1.954 + /**
1.955 + Finds a common format from two lists of uncompressed video formats. Used typically to find a
1.956 + suitable intermediate format between a video decoder and a post-processor. If multiple common
1.957 + formats are available, the lowest-cost format is selected, assuming that the cost of each format
1.958 + is equal to its position in the input array.
1.959 + @param "aFormats1" "The first format list."
1.960 + @param "aFormats2" "The second format list."
1.961 + @param "aCommonFormat" "The target variable where the common format found (if any) is stored."
1.962 + @return "True if a common format was found, false if not. If no common format was found,
1.963 + aCommonFormat is not modified."
1.964 + */
1.965 + IMPORT_C static TBool FindCommonFormat(const TArray<TUncompressedVideoFormat>& aFormats1,
1.966 + const TArray<TUncompressedVideoFormat>& aFormats2,
1.967 + TUncompressedVideoFormat& aCommonFormat);
1.968 +
1.969 + /**
1.970 + Finds all available decoders for a given video type with support for certain post-processing
1.971 + operations. The video type is specified using its MIME type, which may include parameters
1.972 + specifying the supported level, version, and other information. Decoder HW devices can use
1.973 + wildcards when listing the supported video types in the ECom registration information, so it is
1.974 + possible that all the decoders returned do not support the specified submode, e.g. profile and
1.975 + level, unless aExactMatch is set.
1.976 + The decoder capabilities can be checked with VideoCodecInfoLC().
1.977 +
1.978 + @param "aMimeType" "The video type that will be decoded."
1.979 + @param "aPostProcType" "The post-processing types that the decoder has to support, a binary OR
1.980 + of TPrePostProcessType values. If no post-processing support is needed,
1.981 + set this value to zero."
1.982 + @param "aDecoders" "An array for the result decoder UIDs. The array must be created and
1.983 + destroyed by the caller."
1.984 + @param "aExactMatch" "True if exact matching should be used. In this only decoders that support
1.985 + exactly the MIME-type given will be returned. Since verifying this may
1.986 + require loading the decoders into memory, this can be a fairly expensive
1.987 + operation, and if the user needs to verify their capabilities further in
1.988 + any case this parameter should be set to EFalse."
1.989 + @leave "This method may leave with one of the system-wide error codes. Typical error codes used:
1.990 + * KErrNotFound: No decoders were found matching the search parameters."
1.991 + */
1.992 + IMPORT_C void FindDecodersL(const TDesC8& aMimeType,
1.993 + TUint32 aPostProcType,
1.994 + RArray<TUid>& aDecoders,
1.995 + TBool aExactMatch=ETrue);
1.996 +
1.997 + /**
1.998 + Finds all available post-processors for a given set of post-processing operations.
1.999 + @param "aPostProcType" "The post-processing types that the hardware device has to support,
1.1000 + a binary OR of TPrePostProcessType values."
1.1001 + @param "aPostProcessors" "An array for the result post-processor UIDs. The array must be
1.1002 + created and destroyed by the caller."
1.1003 + @leave "This method may leave with one of the system-wide error codes. Typical error codes used:
1.1004 + * KErrNotFound: No post-processors were found matching the search parameters."
1.1005 + */
1.1006 + IMPORT_C void FindPostProcessorsL(TUint32 aPostProcType, RArray<TUid>& aPostProcessors);
1.1007 +
1.1008 + /**
1.1009 + Retrieves a list of available video decoders in the system.
1.1010 + @param "aDecoders" "An array for the result decoder UIDs. The array must be created and
1.1011 + destroyed by the caller."
1.1012 + @leave "This method may leave with one of the system-wide error codes. Not finding any decoders
1.1013 + is not treated as an error condition: in this situation, aDecoders will be empty."
1.1014 + */
1.1015 + IMPORT_C void GetDecoderListL(RArray<TUid>& aDecoders);
1.1016 +
1.1017 + /**
1.1018 + Retrieves a list of available video post-processors in the system.
1.1019 +
1.1020 + @param aPostProcessors
1.1021 + An array for the result post-processor UIDs. The array must be created and
1.1022 + destroyed by the caller.
1.1023 +
1.1024 + @leave This method may leave with one of the system-wide error codes. Not finding any post-processors
1.1025 + is not treated as an error condition: in this situation, aDecoders will be empty.
1.1026 + */
1.1027 + IMPORT_C void GetPostProcessorListL(RArray<TUid>& aPostProcessors);
1.1028 +
1.1029 + /**
1.1030 + Retrieves information about an installed video decoder. Note that this method will need to load
1.1031 + the codec hardware device into memory, and can thus be relatively expensive.
1.1032 + @param "aVideoDecoder" "The video decoder to query."
1.1033 + @return "Decoder information as a CVideoDecoderInfo object. The object is pushed to the cleanup
1.1034 + stack, and must be deallocated by the caller."
1.1035 + @leave "This method may leave with one of the system-wide error codes."
1.1036 + */
1.1037 + IMPORT_C CVideoDecoderInfo* VideoDecoderInfoLC(TUid aVideoDecoder);
1.1038 +
1.1039 + /**
1.1040 + Retrieves information about the post-processing capabilities of an installed post-processor or
1.1041 + decoder hardware device. Note that this method will need to load the device into memory, and can
1.1042 + thus be relatively expensive.
1.1043 + @param "aPostProcessor" "The post-processor to query."
1.1044 + @return "Post-processor information as a CPostProcessorInfo object. The object is pushed to the
1.1045 + cleanup stack, and must be deallocated by the caller."
1.1046 + @leave "This method may leave with one of the system-wide error codes."
1.1047 + */
1.1048 + IMPORT_C CPostProcessorInfo* PostProcessorInfoLC(TUid aPostProcessor);
1.1049 +
1.1050 + /**
1.1051 + Selects the video decoder to be used. This method must be called before any other video decoder
1.1052 + related methods are used. The decoder to use can be changed by calling this method again before
1.1053 + the API has been initialized with Initialize().
1.1054 + All video decoder settings are reset to their default values, which are up to the implementation
1.1055 + to decide if not specified in any of the MSL specifications. By default no post-processing is
1.1056 + performed.
1.1057 +
1.1058 + @param "aDecoder" "The video decoder to use."
1.1059 + @return "Hardware device ID, used in other methods for configuring the decoder."
1.1060 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1061 + * KErrNotFound - No decoder was found with the given UID"
1.1062 + @pre "This method can only be called before the API has been initialized with Initialize()."
1.1063 + */
1.1064 + IMPORT_C THwDeviceId SelectDecoderL(TUid aDecoder);
1.1065 +
1.1066 + /**
1.1067 + Selects the video post-processor to be used. This method must be called before any other
1.1068 + post-processor related methods are used. The post-processor to use can be changed by calling
1.1069 + this method again before the API has been initialized with Initialize().
1.1070 + All post-processor settings are reset to their default values, which are up to the implementation
1.1071 + to decide if not specified in any of the MSL specifications.
1.1072 +
1.1073 + @param "aPostProcessor" "The post-processor to use."
1.1074 + @return "Hardware device ID, used in other methods for configuring the post-processor."
1.1075 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1076 + * KErrNotFound - No post-processor was found with the given UID"
1.1077 + @pre "This method can only be called before the API has been initialized with Initialize()."
1.1078 + */
1.1079 + IMPORT_C THwDeviceId SelectPostProcessorL(TUid aPostProcessor);
1.1080 +
1.1081 + /**
1.1082 + Reads header information from a coded data unit. [1 #59] This method can be called only after
1.1083 + SelectDecoderL().
1.1084 + @param "aDataUnitType" "The type of coded data unit that is contained in aDataUnit. If the
1.1085 + data is a simple piece of bitstream, use
1.1086 + EDuArbitraryStreamSection."
1.1087 + @param "aDataUnitEncapsulation" "The encapsulation type used for the coded data. If the data
1.1088 + is a simple piece of bitstream, use EDuElementaryStream."
1.1089 + @param "aDataUnit" "The coded data unit, contained in a TVideoInputBuffer."
1.1090 + @return "Header information for the data unit, or NULL if the coded data unit did not contain
1.1091 + enough data to parse the header. The header data must be returned to the API using
1.1092 + ReturnHeader() before the API is shut down or the decoder is changed. The data remains
1.1093 + valid until it is returned."
1.1094 + @leave "The method will leave if an error occurs. Running out of data is not considered an error,
1.1095 + as described above. Typical error codes used:
1.1096 + * KErrNotSupported - The data is not in a supported format.
1.1097 + * KErrCorrupt - The data appears to be in a supported format, but is corrupted."
1.1098 + */
1.1099 + IMPORT_C TVideoPictureHeader* GetHeaderInformationL(TVideoDataUnitType aDataUnitType,
1.1100 + TVideoDataUnitEncapsulation aDataUnitEncapsulation,
1.1101 + TVideoInputBuffer* aDataUnit);
1.1102 +
1.1103 + IMPORT_C void ConfigureDecoderL(const TVideoPictureHeader& aVideoPictureHeader);
1.1104 +
1.1105 + /**
1.1106 + Returns a header from GetHeaderInformationL() back to the decoder so that the memory can be freed.
1.1107 + @param "aHeader" "The header to return."
1.1108 + @pre "This method can only be called before the API has been initialized with Initialize()."
1.1109 + */
1.1110 + IMPORT_C void ReturnHeader(TVideoPictureHeader* aHeader);
1.1111 +
1.1112 + /**
1.1113 + Sets a hardware device input format to an uncompressed video format. Only post-processors support
1.1114 + uncompressed video input.
1.1115 + @param "aHwDevice" "The hardware device to configure. The value is returned from
1.1116 + SelectPostProcessorL() when the device is selected."
1.1117 + @param "aFormat" "The input format to use."
1.1118 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1119 + * KErrNotSupported - The input format is not supported."
1.1120 + @pre "This method can only be called before the API has been initialized with Initialize()."
1.1121 + */
1.1122 + IMPORT_C void SetInputFormatL(THwDeviceId aHwDevice, const TUncompressedVideoFormat& aFormat);
1.1123 +
1.1124 + /**
1.1125 + Sets a hardware device Input format to a compressed video format. Only decoders support compressed
1.1126 + video input.
1.1127 + @param "aHwDevice" "The hardware device to configure. The value is returned from
1.1128 + SelectDecoderL() when the device is selected."
1.1129 + @param "aFormat" "The input format to use."
1.1130 + @param "aDataUnitType" "The data unit type for input data."
1.1131 + @param "aEncapsulation" "The encapsulation type used for the coded data."
1.1132 + @param "aDataInOrder" "True if the input data is written in correct decoding order, false if
1.1133 + the input data may be written in arbitrary order."
1.1134 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1135 + * KErrNotSupported - The input format is not supported."
1.1136 + @pre "This method can only be called before the API has been initialized with Initialize()."
1.1137 + */
1.1138 + IMPORT_C void SetInputFormatL(THwDeviceId aHwDevice,
1.1139 + const CCompressedVideoFormat& aFormat,
1.1140 + TVideoDataUnitType aDataUnitType,
1.1141 + TVideoDataUnitEncapsulation aEncapsulation,
1.1142 + TBool aDataInOrder);
1.1143 +
1.1144 + /**
1.1145 + Retrieves the list of the output formats a hardware device supports. The list is ordered in
1.1146 + preference order, with the preferred formats at the beginning of the list. The list can depend
1.1147 + on the device source format, and therefore SetSourceFormatL() must be called for the device
1.1148 + before calling this method.
1.1149 + @param "aHwDevice" "The hardware device to configure. The value is returned from SelectDecoderL()
1.1150 + or SelectPostProcessorL() when the device is selected."
1.1151 + @param "aFormats" "An array for the result format list. The array must be created and destroyed
1.1152 + by the caller."
1.1153 + @leave "This method may leave with one of the system-wide error codes."
1.1154 + @pre "This method can only be called before the API has been initialized with Initialize()."
1.1155 + */
1.1156 + IMPORT_C void GetOutputFormatListL(THwDeviceId aHwDevice, RArray<TUncompressedVideoFormat>& aFormats);
1.1157 +
1.1158 + /**
1.1159 + Sets the output format for a hardware device. If a decoder and a post-processor are used, the
1.1160 + decoder output format must match the post-processor source format.
1.1161 +
1.1162 + If direct screen access is being used, then it is not necessary to call this method on the
1.1163 + hwdevice performing the direct screen access.
1.1164 +
1.1165 + @param "aHwDevice" "The hardware device to configure. The value is returned from SelectDecoderL()
1.1166 + or SelectPostProcessorL() when the device is selected."
1.1167 + @param "aFormat" "The format to use."
1.1168 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1169 + * KErrNotSupported - The output format is not supported."
1.1170 + @pre "This method can only be called before the API has been initialized with Initialize()."
1.1171 + */
1.1172 + IMPORT_C void SetOutputFormatL(THwDeviceId aHwDevice, const TUncompressedVideoFormat &aFormat);
1.1173 +
1.1174 + /**
1.1175 + Sets the clock source to use for video timing. When video playback is synchronized with audio, the
1.1176 + clock source is implemented by the audio playback subsystem, otherwise the clock source should get
1.1177 + the time from the system clock. If no clock source is set, video playback will not be synchronized,
1.1178 + but will proceed as fast as possible, depending on input data and output buffer availability. This
1.1179 + method can be called after all hardware devices have been selected, but before calling Initialize().
1.1180 +
1.1181 + All decoders must support synchronization with an external clock source, as well as unsynchronized
1.1182 + non-realtime operation. When a clock source is set, the decoder can skip pictures to maintain
1.1183 + synchronization. When non-realtime operation is used and no clock source has been set, pictures
1.1184 + may not be skipped unless a lower complexity level is used that requires this.
1.1185 +
1.1186 + @param "aClock" "The clock source to use"
1.1187 + @pre "This method can only be called before the API has been initialized with Initialize()."
1.1188 + */
1.1189 + IMPORT_C void SetClockSource(MMMFClockSource* aClock);
1.1190 +
1.1191 + /**
1.1192 + Sets the video output destination. The destination can be the screen (using direct screen access)
1.1193 + or memory buffers. By default memory buffers are used. This method must be called after the
1.1194 + decoder and post-processor have been selected and their options set, since support for direct
1.1195 + screen access can vary between hardware devices.
1.1196 + @param "aScreen" "True if video output destination is the screen, false if memory buffers."
1.1197 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1198 + * KErrNotSupported - The selected video destination is not supported with the
1.1199 + current codec and post-processor settings."
1.1200 + @pre "This method can only be called before the API has been initialized with Initialize()."
1.1201 + */
1.1202 + IMPORT_C void SetVideoDestScreenL(TBool aScreen);
1.1203 +
1.1204 + /**
1.1205 + Sets whether the decoder should synchronize decoding to the current clock source, if any, or
1.1206 + should decode all pictures as soon as possible. If decoding is synchronized, decoding timestamps
1.1207 + are used if available, presentation timestamps are used if not. When decoding is not synchronized,
1.1208 + pictures are decoded as soon as source data is available for them and the decoder has a free
1.1209 + output buffer. If a clock source is not available, decoding will not be synchronized.
1.1210 +
1.1211 + @param "aSynchronize" "True if decoding should be synchronized to a clock source."
1.1212 + @pre "This method can only be called before the API has been initialized with Initialize()."
1.1213 + */
1.1214 + IMPORT_C void SynchronizeDecoding(TBool aSynchronize);
1.1215 +
1.1216 + /**
1.1217 + Sets video decoder buffering options.
1.1218 + @param "aOptions" "Buffering options."
1.1219 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1220 + * KErrNotSupported - The specified buffering options are not supported. If the
1.1221 + client receives this error code, it can call GetBufferOptions() to determine
1.1222 + the options the decoder is able to support."
1.1223 + @pre "This method can only be called before the API has been initialized with Initialize()."
1.1224 + */
1.1225 + IMPORT_C void SetBufferOptionsL(const TBufferOptions& aOptions);
1.1226 +
1.1227 + /**
1.1228 + Gets the video decoder buffer options actually in use. This can be used before calling
1.1229 + SetBufferOptionsL() to determine the default options, or afterwards to check the values actually
1.1230 + in use (if some default values were used).
1.1231 + @param "aOptions" "Buffering options structure to fill."
1.1232 + @pre "This method can only be called before the API has been initialized with Initialize()."
1.1233 + */
1.1234 + IMPORT_C void GetBufferOptions(TBufferOptions& aOptions);
1.1235 +
1.1236 + /**
1.1237 + Indicates which HRD/VBV specification is fulfilled in the input stream and any related parameters.
1.1238 + @param "aHrdVbvSpec" "The HRD/VBV specification fulfilled, see the definition of
1.1239 + THrdVbvSpecification for details."
1.1240 + @param "aHrdVbvParams" "HRD/VBV parameters. The data format depends on the parameters chosen.
1.1241 + For 3GPP TS 26.234 parameters (aHrdVbvSpec=EHrdVbv3GPP), the data in the
1.1242 + descriptor is a package of type TPckC<T3gppHrdVbvParams>
1.1243 + (see T3gppHrdVbvParams). If no HRD/VBV parameters are used, the descriptor
1.1244 + is empty."
1.1245 + @pre "This method can only be called before the API has been initialized with Initialize()."
1.1246 + */
1.1247 + IMPORT_C void SetHrdVbvSpec(THrdVbvSpecification aHrdVbvSpec, const TDesC8& aHrdVbvParams);
1.1248 +
1.1249 + /**
1.1250 + Sets the post-processing types to be used. This method, like all post-processing configuration
1.1251 + methods, must be called before Initialize().
1.1252 +
1.1253 + Post-processing operations are carried out in the following order:
1.1254 + 1. Input cropping
1.1255 + 2. Mirroring
1.1256 + 3. Rotating
1.1257 + 4. Scaling
1.1258 + 5. Output cropping
1.1259 + Color space conversion can be performed at any point in the post-processing flow.
1.1260 +
1.1261 + @param "aHwDevice" "The hardware device to configure. The value is returned from
1.1262 + SelectDecoderL() or SelectPostProcessorL() when the device is
1.1263 + selected."
1.1264 + @param "aPostProcCombination" "The post-processing steps to perform, a bitwise OR of values
1.1265 + from TPrePostProcessType."
1.1266 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1267 + * KErrNotSupported - The post-processing combination is not supported"
1.1268 + @pre "This method can be called either before or after the API has been initialized with Initialize().
1.1269 + If called after initialization, the change will only be committed once CommitL() is called."
1.1270 + */
1.1271 + IMPORT_C void SetPostProcessTypesL(THwDeviceId aHwDevice, TUint32 aPostProcCombination);
1.1272 +
1.1273 + /**
1.1274 + Sets post-processing options for input (pan-scan) cropping. SetPostProcessTypesL() must be called
1.1275 + before this method is used.
1.1276 + @param "aHwDevice" "The hardware device to configure. The value is returned from SelectDecoderL()
1.1277 + or SelectPostProcessorL() when the device is selected."
1.1278 + @param "aRect" "The cropping rectangle to use."
1.1279 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1280 + * KErrNotSupported - Pan-scan cropping is not supported"
1.1281 + @pre "This method can be called either before or after the API has been initialized with Initialize().
1.1282 + If called after initialization, the change will only be committed once CommitL() is called."
1.1283 + */
1.1284 + IMPORT_C void SetInputCropOptionsL(THwDeviceId aHwDevice, const TRect& aRect);
1.1285 +
1.1286 + /**
1.1287 + Sets post-processing options for YUV to RGB color space conversion. Specifies the input YUV and
1.1288 + output RGB formats to use explicitly. SetSourceFormatL() and SetOutputFormatL(), and
1.1289 + SetPostProcessTypesL() must be called before this method is used.
1.1290 + @param "aHwDevice" "The hardware device to configure. The value is returned from
1.1291 + SelectDecoderL() or SelectPostProcessorL() when the device is selected."
1.1292 + @param "aOptions" "The conversion options to use."
1.1293 + @param "aYuvFormat" "Conversion source YUV format."
1.1294 + @param "aRgbFormat" "Conversion target RGB format."
1.1295 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1296 + * KErrNotSupported - The conversion options are not supported."
1.1297 + @pre "This method can be called either before or after the API has been initialized with Initialize().
1.1298 + If called after initialization, the change will only be committed once CommitL() is called."
1.1299 + */
1.1300 + IMPORT_C void SetYuvToRgbOptionsL(THwDeviceId aHwDevice,
1.1301 + const TYuvToRgbOptions& aOptions,
1.1302 + const TYuvFormat& aYuvFormat,
1.1303 + TRgbFormat aRgbFormat);
1.1304 +
1.1305 + /**
1.1306 + Sets post-processing options for YUV to RGB color space conversion. Uses the device input and
1.1307 + output formats. For decoders the default YUV format used is the format specified in the input
1.1308 + bitstream. SetSourceFormatL() and SetOutputFormatL(), and SetPostProcessTypesL() must be called
1.1309 + before this method is used.
1.1310 + @param "aHwDevice" "The hardware device to configure. The value is returned from
1.1311 + SelectDecoderL() or SelectPostProcessorL() when the device is selected."
1.1312 + @param "aOptions" "The conversion options to use."
1.1313 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1314 + * KErrNotSupported - The conversion options are not supported."
1.1315 + @pre "This method can be called either before or after the API has been initialized with Initialize().
1.1316 + If called after initialization, the change will only be committed once CommitL() is called."
1.1317 + */
1.1318 + IMPORT_C void SetYuvToRgbOptionsL(THwDeviceId aHwDevice, const TYuvToRgbOptions& aOptions);
1.1319 +
1.1320 + /**
1.1321 + Sets post-processing options for rotation. SetPostProcessTypesL() must be called before this
1.1322 + method is used.
1.1323 + @param "aHwDevice" "The hardware device to configure. The value is returned from
1.1324 + SelectDecoderL() or SelectPostProcessorL() when the device is selected."
1.1325 + @param "aRotationType" "The rotation to perform."
1.1326 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1327 + * KErrNotSupported - The rotation options are not supported."
1.1328 + @pre "This method can be called either before or after the API has been initialized with Initialize().
1.1329 + If called after initialization, the change will only be committed once CommitL() is called."
1.1330 + */
1.1331 + IMPORT_C void SetRotateOptionsL(THwDeviceId aHwDevice, TRotationType aRotationType);
1.1332 +
1.1333 + /**
1.1334 + Sets post-processing options for scaling. SetPostProcessTypesL() must be called before this method
1.1335 + is used.
1.1336 + @param "aHwDevice" "The hardware device to configure. The value is returned from
1.1337 + SelectDecoderL() or SelectPostProcessorL() when the device is
1.1338 + selected."
1.1339 + @param "aTargetSize" "Scaling target size. If a fixed scale factor size is used, the
1.1340 + new dimensions must be set to width=floor(factor*width),
1.1341 + height=floor(factor*height). For example, scaling a QCIF (176x144)
1.1342 + picture up by a factor of 4/3 yields a size of 234x192."
1.1343 + @param "aAntiAliasFiltering" "True if anti-aliasing filtering should be used. If the
1.1344 + post-processor does not support anti-aliased scaling, or supports
1.1345 + anti-aliased scaling only, this argument is ignored."
1.1346 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1347 + * KErrNotSupported - The scale options are not supported."
1.1348 + @pre "This method can be called either before or after the API has been initialized with Initialize().
1.1349 + If called after initialization, the change will only be committed once CommitL() is called."
1.1350 + */
1.1351 + IMPORT_C void SetScaleOptionsL(THwDeviceId aHwDevice,
1.1352 + const TSize& aTargetSize,
1.1353 + TBool aAntiAliasFiltering);
1.1354 +
1.1355 + /**
1.1356 + Sets post-processing options for output cropping. SetPostProcessTypesL() must be called before this
1.1357 + method is used.
1.1358 + @param "aHwDevice" "The hardware device to configure. The value is returned from SelectDecoderL()
1.1359 + # SelectPostProcessorL() when the device is selected."
1.1360 + @param "aRect" "Output cropping area."
1.1361 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1362 + * KErrNotSupported - Output cropping is not supported."
1.1363 + @pre "This method can be called either before or after the API has been initialized with Initialize().
1.1364 + If called after initialization, the change will only be committed once CommitL() is called."
1.1365 + */
1.1366 + IMPORT_C void SetOutputCropOptionsL(THwDeviceId aHwDevice, const TRect& aRect);
1.1367 +
1.1368 + /**
1.1369 + Sets post-processing hardware device specific options. SetPostProcessTypesL() must be called
1.1370 + before this method is used.
1.1371 + @param "aHwDevice" "The hardware device to configure. The value is returned from SelectDecoderL()
1.1372 + or SelectPostProcessorL() when the device is selected."
1.1373 + @param "aOptions" "The options. The format is plug-in specific."
1.1374 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1375 + * KErrNotSupported - The options are not supported."
1.1376 + @pre "This method can be called either before or after the API has been initialized with Initialize().
1.1377 + If called after initialization, the change will only be committed once CommitL() is called."
1.1378 + */
1.1379 + IMPORT_C void SetPostProcSpecificOptionsL(THwDeviceId aHwDevice, const TDesC8& aOptions);
1.1380 +
1.1381 + /**
1.1382 + Initializes the video device. This method is asynchronous, DevVideoPlay will call
1.1383 + MMMFDevVideoPlayObserver::MdvpoInitializeComplete() after initialization has completed. No
1.1384 + DevVideoPlay method may be called while initialization is in progress, the initialization process
1.1385 + can only be cancelled by destroying the DevVideoPlay object. After this initialization has been
1.1386 + successfully completed, further configuration changes are not possible except where separately
1.1387 + noted.
1.1388 +
1.1389 + If initialization fails for any reason, the DevVideoPlay object must be destroyed and set up from
1.1390 + scratch.
1.1391 + */
1.1392 + IMPORT_C void Initialize();
1.1393 +
1.1394 + /**
1.1395 + Commit all configuration changes since the last CommitL(), Revert() or Initialize(). This only applies
1.1396 + to methods that can be called both before AND after DevVideoPlay has been initialized.
1.1397 + See the following methods for details.
1.1398 +
1.1399 + @see SetPostProcessTypesL
1.1400 + @see SetInputCropOptionsL
1.1401 + @see SetYuvToRgbOptionsL
1.1402 + @see SetRotateOptionsL
1.1403 + @see SetScaleOptionsL
1.1404 + @see SetOutputCropOptionsL
1.1405 + @see SetPostProcSpecificOptionsL
1.1406 +
1.1407 + @leave "The method will leave if an error occurs."
1.1408 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1409 + */
1.1410 + IMPORT_C void CommitL();
1.1411 +
1.1412 + /**
1.1413 + Revert any configuration changes that have not yet been committed using CommitL(). This only applies
1.1414 + to methods that can be called both before AND after DevVideoPlay has been initialized.
1.1415 + See the following methods for details.
1.1416 +
1.1417 + @see SetPostProcessTypesL
1.1418 + @see SetInputCropOptionsL
1.1419 + @see SetYuvToRgbOptionsL
1.1420 + @see SetRotateOptionsL
1.1421 + @see SetScaleOptionsL
1.1422 + @see SetOutputCropOptionsL
1.1423 + @see SetPostProcSpecificOptionsL
1.1424 +
1.1425 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1426 + */
1.1427 + IMPORT_C void Revert();
1.1428 +
1.1429 + /**
1.1430 + Starts video decoding directly to the display frame buffer using Direct Screen Access.
1.1431 + Playback to the display can start immediately.
1.1432 + @param "aVideoRect" "The video output rectangle on screen. The rectangle size should be the
1.1433 + same as the output video size, otherwise results are undefined. Some
1.1434 + decoders may set limitations to the position and alignment of the
1.1435 + rectangle. The rectangle must be aligned to a 32-bit boundary on screen
1.1436 + (even X-coordinate on 12-bpp and 16-bpp displays) and must fit completely
1.1437 + on the screen."
1.1438 + @param "aScreenDevice" "The screen device to use. The screen device will supply frame buffer
1.1439 + information, and is used to update the frame buffer to screen. The screen
1.1440 + device object must be valid in the current thread."
1.1441 + @param "aClipRegion" "Initial clipping region to use."
1.1442 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1443 + *KErrNotSupported - Direct Screen Access is not supported"
1.1444 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1445 + */
1.1446 + IMPORT_C void StartDirectScreenAccessL(const TRect& aVideoRect,
1.1447 + CFbsScreenDevice& aScreenDevice,
1.1448 + const TRegion& aClipRegion);
1.1449 +
1.1450 + /**
1.1451 + Sets a new clipping region for Direct Screen Access. After the method returns, no video will be
1.1452 + drawn outside of the region. (Note that in Symbian OS clipping regions are "positive" - that is,
1.1453 + they define the legal area inside which an application may draw.)
1.1454 +
1.1455 + If clipping is not supported, or the clipping region is too complex, either playback will pause
1.1456 + or will resume without video display, depending on the current setting of SetPauseOnClipFail(),
1.1457 + and the result can be verified with IsPlaying(). Clipping can be disabled by setting a new
1.1458 + clipping region that includes the whole video window.
1.1459 +
1.1460 + @param "aRegion" "The new clipping region. After the method returns, no video will be drawn
1.1461 + outside the region."
1.1462 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1463 + */
1.1464 + IMPORT_C void SetScreenClipRegion(const TRegion& aRegion);
1.1465 +
1.1466 + /**
1.1467 + Sets whether the system should pause playback when it gets a clipping region it cannot handle,
1.1468 + or Direct Screen Access is aborted completely. If not, decoding will proceed normally, but no
1.1469 + video will be drawn. By default, playback is paused.
1.1470 + @param "aPause" "True if playback should be paused when clipping fails, false if not. If
1.1471 + playback is not paused, it will be continued without video display."
1.1472 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1473 + */
1.1474 + IMPORT_C void SetPauseOnClipFail(TBool aPause);
1.1475 +
1.1476 + /**
1.1477 + Aborts Direct Screen Access completely, to be called from MAbortDirectScreenAccess::AbortNow() and
1.1478 + similar methods. DSA can be resumed by calling StartDirectScreenAccessL().
1.1479 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1480 + */
1.1481 + IMPORT_C void AbortDirectScreenAccess();
1.1482 +
1.1483 + /**
1.1484 + Indicates whether playback is proceeding. This method can be used to check whether playback was
1.1485 + paused or not in response to a new clipping region or DSA abort.
1.1486 + @return "ETrue if video is still being played (even if not necessarily displayed)."
1.1487 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1488 + */
1.1489 + IMPORT_C TBool IsPlaying();
1.1490 +
1.1491 + /**
1.1492 + Re-draws the latest video picture. Only available when DSA is being used. If DSA is aborted
1.1493 + or a non-supported clipping region has been set, the request may be ignored.
1.1494 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1495 + */
1.1496 + IMPORT_C void Redraw();
1.1497 +
1.1498 + /**
1.1499 + Starts video playback, including decoding, post-processing, and rendering. Playback will proceed
1.1500 + until it has been stopped or paused, or the end of the bitstream is reached.
1.1501 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1502 + */
1.1503 + IMPORT_C void Start();
1.1504 +
1.1505 + /**
1.1506 + Stops video playback. No new pictures will be decoded, post-processed, or rendered.
1.1507 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1508 + */
1.1509 + IMPORT_C void Stop();
1.1510 +
1.1511 + /**
1.1512 + Pauses video playback, including decoding, post-processing, and rendering. No pictures will be
1.1513 + decoded, post-processed, or rendered until playback has been resumed. The client is responsible
1.1514 + for pausing the clock source (typically by pausing audio output) if necessary.
1.1515 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1516 + */
1.1517 + IMPORT_C void Pause();
1.1518 +
1.1519 + /**
1.1520 + Resumes video playback after a pause. The client is responsible for restarting the clock source
1.1521 + if necessary.
1.1522 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1523 + */
1.1524 + IMPORT_C void Resume();
1.1525 +
1.1526 + /**
1.1527 + Changes to a new decoding and playback position, used for randomly accessing (seeking) the input
1.1528 + stream. The position change flushes all input and output buffers. Pre-decoder and post-decoder
1.1529 + buffering are handled as if a new bitstream was started. If the MSL video subsystem still has
1.1530 + buffered pictures that precede the new playback position, they will be discarded. If playback is
1.1531 + synchronized to a clock source, the client is responsible for setting the clock source to the new
1.1532 + position.
1.1533 + @param "aPlaybackPosition" "The new playback position in the video stream."
1.1534 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1535 + */
1.1536 + IMPORT_C void SetPosition(const TTimeIntervalMicroSeconds& aPlaybackPosition);
1.1537 +
1.1538 + /**
1.1539 + Freezes a picture on the screen. After the picture has been frozen, no picture is displayed until
1.1540 + the freeze is released with ReleaseFreeze(). If the video output is being written to memory
1.1541 + buffers, not the screen, decoded pictures will not be delivered to the client when a freeze is
1.1542 + active, but are simply discarded.
1.1543 + @param "aPlaybackPosition" "The presentation timestamp of the picture to freeze. The frozen
1.1544 + picture will be the first picture with a timestamp greater than or
1.1545 + equal to this parameter."
1.1546 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1547 + */
1.1548 + IMPORT_C void FreezePicture(const TTimeIntervalMicroSeconds& aPlaybackPosition);
1.1549 +
1.1550 + /**
1.1551 + Releases a picture frozen with FreezePicture().
1.1552 + @param "aPlaybackPosition" "The presentation timestamp of the picture to release. The first
1.1553 + picture displayed after the release will be the first picture with a
1.1554 + timestamp greater than or equal to this parameter. To release the
1.1555 + freeze immediately, set the timestamp to zero."
1.1556 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1557 + */
1.1558 + IMPORT_C void ReleaseFreeze(const TTimeIntervalMicroSeconds& aPlaybackPosition);
1.1559 +
1.1560 + /**
1.1561 + Returns the current decoding position, i.e. the timestamp for the most recently decoded picture.
1.1562 + @return "Current decoding position."
1.1563 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1564 + */
1.1565 + IMPORT_C TTimeIntervalMicroSeconds DecodingPosition();
1.1566 +
1.1567 + /**
1.1568 + Returns the current playback position, i.e. the timestamp for the most recently displayed or
1.1569 + virtually displayed picture.
1.1570 + @return "Current playback position."
1.1571 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1572 + */
1.1573 + IMPORT_C TTimeIntervalMicroSeconds PlaybackPosition();
1.1574 +
1.1575 + /**
1.1576 + Returns the current pre-decoder buffer size.
1.1577 + @return "The number of bytes of data in the pre-decoder buffer."
1.1578 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1579 + */
1.1580 + IMPORT_C TUint PreDecoderBufferBytes();
1.1581 +
1.1582 + /**
1.1583 + Returns the total amount of memory allocated for uncompressed pictures.
1.1584 + @return "Total number of bytes of memory allocated for uncompressed pictures."
1.1585 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1586 + */
1.1587 + IMPORT_C TUint PictureBufferBytes();
1.1588 +
1.1589 + /**
1.1590 + Reads various counters related to decoded pictures. See the definition of TPictureCounters for a
1.1591 + description of the counters. The counters are reset when Initialize() or this method is called,
1.1592 + and thus they only include pictures processed since the last call.
1.1593 + @param "aCounters" "The counter structure to fill."
1.1594 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1595 + */
1.1596 + IMPORT_C void GetPictureCounters(TPictureCounters& aCounters);
1.1597 +
1.1598 + /**
1.1599 + Reads various counters related to the received input bitstream and coded data units. See the
1.1600 + definition of TBitstreamCounters for a description about the counters. The counters are reset
1.1601 + when Initialize() or this method is called, and thus they only include data processed since the
1.1602 + last call.
1.1603 + @param "aCounters" "The counter structure to fill."
1.1604 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1605 + */
1.1606 + IMPORT_C void GetBitstreamCounters(TBitstreamCounters& aCounters);
1.1607 +
1.1608 + /**
1.1609 + Retrieves the number of free input buffers the decoder has available. If only a post-processor
1.1610 + is used, the return value is undefined.
1.1611 + @return "Number of free input buffers the decoder has available."
1.1612 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1613 + */
1.1614 + IMPORT_C TUint NumFreeBuffers();
1.1615 +
1.1616 + /**
1.1617 + Sets the computational complexity level to use. The level can be set separately for each hardware
1.1618 + device in use. If separate complexity levels are not available, the method call is ignored. If the
1.1619 + level specified is not available, the results are undefined. Typically the device will either
1.1620 + ignore the request or use the nearest suitable level.
1.1621 +
1.1622 + The complexity level can be changed at any point during playback.
1.1623 +
1.1624 + @param "aHwDevice" "The plug-in to control. The value is returned from SelectDecoderL()or
1.1625 + SelectPostProcessorL() when the device is selected."
1.1626 + @param "aLevel" "The computational complexity level to use. Level zero (0) is the most
1.1627 + complex one, with the highest quality. Higher level numbers require less
1.1628 + processing and may have lower quality."
1.1629 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1630 + */
1.1631 + IMPORT_C void SetComplexityLevel(THwDeviceId aHwDevice, TUint aLevel);
1.1632 +
1.1633 + /**
1.1634 + Gets the number of complexity levels available.
1.1635 + @param "aHwDevice" "The plug-in to query. The value is returned from SelectDecoderL()or
1.1636 + SelectPostProcessorL() when the device is selected."
1.1637 + @return "The number of complexity control levels available, or zero if the information is not
1.1638 + available yet. The information may not be available if the number of levels depends on
1.1639 + the input data, and enough input data has not been read yet. In that case, using level
1.1640 + zero is safe."
1.1641 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1642 + */
1.1643 + IMPORT_C TUint NumComplexityLevels(THwDeviceId aHwDevice);
1.1644 +
1.1645 + /**
1.1646 + Gets information about a computational complexity level. This method can be called after
1.1647 + NumComplexityLevels() has returned a non-zero value - at that point the information is guaranteed
1.1648 + to be available. Some hardware device implementations may not be able to provide all values,
1.1649 + in that case the values will be approximated.
1.1650 + @param "aHwDevice" "The hw device to query. The value is returned from SelectDecoderL()or
1.1651 + SelectPostProcessorL() when the device is selected."
1.1652 + @param "aLevel" "The computational complexity level to query. The level numbers range from
1.1653 + zero (the most complex) to NumComplexityLevels()-1."
1.1654 + @param "aInfo" "The information structure to fill."
1.1655 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1656 + */
1.1657 + IMPORT_C void GetComplexityLevelInfo(THwDeviceId aHwDevice, TUint aLevel, TComplexityLevelInfo& aInfo);
1.1658 +
1.1659 + /**
1.1660 + Retrieves an empty video input buffer from the decoder. After input data has been written to the
1.1661 + buffer, it can be written to the decoder using WriteCodedDataL(). The maximum number of buffers
1.1662 + the client can retrieve before returning any to the decoder is determined by the
1.1663 + TBufferOptions.iMinNumInputBuffers value set with SetBufferOptionsL().
1.1664 +
1.1665 + If a buffer is not immediately available, the client can wait for a MdvpoNewBuffers() callback
1.1666 + before trying again, or poll for new buffer availability after a delay. Note that video decoding
1.1667 + may be performed in the same thread, in a separate active object, so the client must not block
1.1668 + the active scheduler while waiting for buffers to become available, otherwise the system can
1.1669 + deadlock. Assuming that the client does not keep too many buffers retrieved and playback is in
1.1670 + progress, new buffers will be available after some time.
1.1671 +
1.1672 + The decoder maintains ownership of the buffers even while they have been retrieved by the client,
1.1673 + and will take care of deallocating them. The client must not destroy the buffer objects, even if
1.1674 + it has retrieved buffers and it is being shut down. The buffers will be destroyed by the decoder,
1.1675 + and will not be valid after the decoder has been shut down.
1.1676 +
1.1677 + @param "aBufferSize" "Required buffer size, in bytes. The resulting buffer can be larger than
1.1678 + this, but not smaller"
1.1679 + @return "A new input data buffer. The buffer is at least as large as requested, but it may be
1.1680 + larger. If no free buffers are available, the return value is NULL."
1.1681 + @leave "The method will leave if an error occurs. Lack of free buffers is not considered an error."
1.1682 + */
1.1683 + IMPORT_C TVideoInputBuffer* GetBufferL(TUint aBufferSize);
1.1684 +
1.1685 + /**
1.1686 + Writes a piece of coded video data. The data will be passed to the video decoder and
1.1687 + post-processor to be used in video playback. The data buffer must be retrieved from the decoder
1.1688 + with GetBufferL().
1.1689 + @param "aBuffer" "The coded data unit to write."
1.1690 + @leave "The method will leave if an error occurs."
1.1691 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1692 + */
1.1693 + IMPORT_C void WriteCodedDataL(TVideoInputBuffer* aBuffer);
1.1694 +
1.1695 + /**
1.1696 + Writes an uncompressed video picture. The picture must remain valid and unmodified until it is
1.1697 + returned with the MdvpoReturnPicture() callback.
1.1698 + @param "aPicture" "The picture to write."
1.1699 + @leave "The method will leave if an error occurs."
1.1700 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1701 + */
1.1702 + IMPORT_C void WritePictureL(TVideoPicture* aPicture);
1.1703 +
1.1704 + /**
1.1705 + Notifies the system that the end of input data has been reached.
1.1706 +
1.1707 + The decoder and post-processor can use this signal to ensure that the remaining data gets processed,
1.1708 + without waiting for new data. For example when the data type is not EDuCodedPicture, calling this
1.1709 + method is necessary otherwise a decoder implementation might be waiting for the start code for the
1.1710 + next picture to ensure it has a complete picture before starting to decode the previous one.
1.1711 +
1.1712 +
1.1713 + After the remaining data has been processed (and displayed, if applicable), the client gets
1.1714 + notified with the MdvpoStreamEnd() callback. The client must then call Stop() on the interface.
1.1715 +
1.1716 + DevVideo clients are encouraged to call this method, but its use is not mandatory for synchronized
1.1717 + processing. For synchronized playback, all video pictures are processed or discarded according to
1.1718 + their timestamps, and so the client can easily infer when processing is complete. However, it
1.1719 + should be noted that the last picture might not be displayed if this method is not called and the
1.1720 + input data type is not EDuCodedPicture.
1.1721 +
1.1722 + For non-synchronized playback (e.g. file conversion), a client must call this method otherwise it
1.1723 + will never find out when the hardware device has finished processing the data.
1.1724 +
1.1725 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1726 + */
1.1727 + IMPORT_C void InputEnd();
1.1728 +
1.1729 + /**
1.1730 + Gets information about new decoded pictures. "New decoded pictures" are pictures that have not
1.1731 + been returned to the caller using NextPicture(). This method can only be called if video
1.1732 + destination is memory buffers, i.e. Direct Screen Access is not used.
1.1733 + @param "aNumPictures" "Target for the number of new decoded pictures. If no pictures are
1.1734 + available, the value written is zero, and the timestamps are not
1.1735 + valid."
1.1736 + @param "aEarliestTimestamp" "Timestamp for the earliest available new decoded picture. If the
1.1737 + number of new decoded pictures (aNumPictures) is zero, the
1.1738 + timestamp is not valid."
1.1739 + @param "aLatestTimestamp" "Timestamp for the latest available new decoded picture. If the
1.1740 + number of new decoded pictures (aNumPictures) is zero, the
1.1741 + timestamp is not valid."
1.1742 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1743 + */
1.1744 + IMPORT_C void GetNewPictureInfo(TUint& aNumPictures,
1.1745 + TTimeIntervalMicroSeconds& aEarliestTimestamp,
1.1746 + TTimeIntervalMicroSeconds& aLatestTimestamp);
1.1747 +
1.1748 + /**
1.1749 + Gets the next (in displaying order) new decoded picture. Only one picture can be retrieved at a
1.1750 + time, the current picture must be returned with ReturnPicture() before a new one can be read.
1.1751 + @return "The next new decoded picture. The pointer and the related data is valid until the picture
1.1752 + is returned using ReturnPicture(), or the API is shut down. If no new picture is available,
1.1753 + the method returns NULL."
1.1754 + @leave "The method will leave if an error occurs."
1.1755 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1756 + */
1.1757 + IMPORT_C TVideoPicture* NextPictureL();
1.1758 +
1.1759 + /**
1.1760 + Returns a picture from NextPicture() back to the device. The picture data cannot be used afterwards.
1.1761 + @param "aPicture" "The picture to return. After this method returns, the pointer is no longer
1.1762 + valid and the picture data cannot be used."
1.1763 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1764 + */
1.1765 + IMPORT_C void ReturnPicture(TVideoPicture* aPicture);
1.1766 +
1.1767 + /**
1.1768 + Gets a copy of the latest picture displayed.
1.1769 + @param "aPictureData" "Target picture. The memory for the picture must be allocated by the
1.1770 + caller, and initialized properly. The data formats must match the snapshot
1.1771 + format requested."
1.1772 + @param "aFormat" "The picture format to use for the snapshot."
1.1773 + @return "ETrue if the snapshot was taken, EFalse if a picture is not available. The picture may not
1.1774 + be available if decoding has not progressed far enough yet."
1.1775 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1776 + *KErrNotSupported - The requested data format or picture size is not supported."
1.1777 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1778 + */
1.1779 + IMPORT_C TBool GetSnapshotL(TPictureData& aPictureData, const TUncompressedVideoFormat& aFormat);
1.1780 +
1.1781 + /**
1.1782 + Gets a copy of a specified picture. Timed snapshots are required for implementing the video
1.1783 + telephony use-case. Simply using the latest picture may not work, since the latest picture
1.1784 + is typically not the one whose supplemental information is being processed.
1.1785 +
1.1786 + The picture is specified using its presentation timestamp. The timestamp must match the timestamp
1.1787 + in the picture exactly, otherwise no snapshot will be taken. The timestamp must refer to the
1.1788 + currently displayed picture or a future picture. Typically the timestamp is received with
1.1789 + supplemental information (with the MdvpoSupplementalInformation() callback) indicating a snapshot
1.1790 + picture.
1.1791 +
1.1792 + When the snapshot is available, it will be returned to the client using the
1.1793 + MdvpoTimedSnapshotComplete() callback. To cancel a timed snapshot request, use
1.1794 + CancelTimedSnapshot(). Only one timed snapshot request can be active at a time.
1.1795 +
1.1796 + @param "aPictureData" "Target picture. The memory for the picture must be allocated
1.1797 + by the caller, and initialized properly. The data formats must
1.1798 + match the snapshot format requested. The picture must remain
1.1799 + valid until the snapshot has been taken or until the request
1.1800 + has been cancelled with CancelTimedSnapshot()."
1.1801 + @param "aFormat" "The picture format to use for the snapshot."
1.1802 + @param "aPresentationTimestamp" "Presentation timestamp for the picture to copy. The timestamp
1.1803 + must match the timestamp in the picture exactly"
1.1804 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1805 + *KErrNotSupported - The requested data format or picture size is not supported."
1.1806 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1807 + */
1.1808 + IMPORT_C void GetTimedSnapshotL(TPictureData* aPictureData,
1.1809 + const TUncompressedVideoFormat& aFormat,
1.1810 + const TTimeIntervalMicroSeconds& aPresentationTimestamp);
1.1811 +
1.1812 + /**
1.1813 + Gets a copy of a specified picture. Timed snapshots are required for implementing the video
1.1814 + telephony use-case. Simply using the latest picture may not work, since the latest picture
1.1815 + is typically not the one whose supplemental information is being processed.
1.1816 +
1.1817 + The picture is specified using either its picture identifier. The id must refer to the currently
1.1818 + displayed picture or a future picture. Typically the picture ID is received with supplemental
1.1819 + information (with the MdvpoSupplementalInformation() callback) indicating a snapshot picture.
1.1820 +
1.1821 + When the snapshot is available, it will be returned to the client using the
1.1822 + MdvpoTimedSnapshotComplete() callback. To cancel a timed snapshot request, use
1.1823 + CancelTimedSnapshot(). Only one timed snapshot request can be active at a time.
1.1824 +
1.1825 + @param "aPictureData" "Target picture. The memory for the picture must be allocated by the
1.1826 + caller, and initialized properly. The data formats must match the snapshot
1.1827 + format requested. The picture must remain valid until the snapshot has been
1.1828 + taken or until the request has been cancelled with CancelTimedSnapshot()."
1.1829 + @param "aFormat" "The picture format to use for the snapshot."
1.1830 + @param "aPictureId" "Picture identifier for the picture to copy."
1.1831 + @leave "The method will leave if an error occurs. Typical error codes used:
1.1832 + *KErrNotSupported - The requested data format or picture size is not supported."
1.1833 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1834 + */
1.1835 + IMPORT_C void GetTimedSnapshotL(TPictureData* aPictureData,
1.1836 + const TUncompressedVideoFormat& aFormat,
1.1837 + const TPictureId& aPictureId);
1.1838 +
1.1839 + /**
1.1840 + Cancels a timed snapshot request.
1.1841 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1842 + */
1.1843 + IMPORT_C void CancelTimedSnapshot();
1.1844 +
1.1845 + /**
1.1846 + Gets a list of the supported snapshot picture formats.
1.1847 + @param "aFormats" "An array for the result format list. The array must be created and destroyed by the caller."
1.1848 + @leave "The method will leave if an error occurs."
1.1849 + @pre "This method can only be called after the API has been initialized with Initialize()."
1.1850 + */
1.1851 + IMPORT_C void GetSupportedSnapshotFormatsL(RArray<TUncompressedVideoFormat>& aFormats);
1.1852 +
1.1853 + /**
1.1854 + Retrieves a custom interface to the specified hardware device.
1.1855 + @param "aHwDevice" "The hardware device from which the custom interface shall be requested.
1.1856 + The value is returned from SelectDecoderL() or SelectPostProcessorL() when
1.1857 + the device is selected."
1.1858 + @param "aInterface" "Interface UID, defined with the custom interface."
1.1859 + @return "Pointer to the interface implementation, or NULL if the device does not
1.1860 + implement the interface requested. The return value must be cast to the
1.1861 + correct type by the user."
1.1862 + */
1.1863 + IMPORT_C TAny* CustomInterface(THwDeviceId aHwDevice, TUid aInterface);
1.1864 +
1.1865 +private:
1.1866 + enum TInitializationState
1.1867 + {
1.1868 + ENotInitialized = 0x01,
1.1869 + EInitializing = 0x02,
1.1870 + EInitialized = 0x04,
1.1871 + EInitializationFailed = 0x08
1.1872 + };
1.1873 +private:
1.1874 + CMMFDevVideoPlay(MMMFDevVideoPlayObserver& aObserver);
1.1875 +
1.1876 + // Methods to check aHwDevice is valid and return the appropriate HwDevice
1.1877 + CMMFVideoPlayHwDevice& VideoPlayHwDevice(THwDeviceId aHwDevice) const;
1.1878 + CMMFVideoPlayHwDevice& RenderingHwDevice() const; //returns the last plugin in the chain
1.1879 + CMMFVideoDecodeHwDevice& VideoDecodeHwDevice(THwDeviceId aHwDevice) const;// Checks that aHwDevice is valid
1.1880 + CMMFVideoPostProcHwDevice& VideoPostProcHwDevice(THwDeviceId aHwDevice) const;// Checks that aHwDevice is valid
1.1881 + CMMFVideoDecodeHwDevice& VideoDecodeHwDevice() const;
1.1882 + CMMFVideoPostProcHwDevice& VideoPostProcHwDevice() const;
1.1883 + CMMFVideoHwDevice& VideoHwDevice(THwDeviceId aHwDevice) const;
1.1884 +
1.1885 + // Connects the plugins together
1.1886 + void ConnectPlugins();
1.1887 +
1.1888 + // Check that we are in a valid initialization state
1.1889 + // Panics if iInitializationState is not one of aExpected
1.1890 + void CheckInitializationState(TUint aExpected);
1.1891 +
1.1892 + // Methods to handle init complete callbacks from the hw devices
1.1893 + void HandlePostProcInitializeComplete(TInt aError);
1.1894 + void HandleDecodeInitializeComplete(TInt aError);
1.1895 +
1.1896 + CMMFVideoDecodeHwDevice* CreateDecoderL(TUid aVideoDecoder);
1.1897 +
1.1898 +
1.1899 + // From MMMFDevVideoPlayProxy
1.1900 + virtual void MdvppNewPicture(TVideoPicture* aPicture);
1.1901 + virtual void MdvppNewBuffers();
1.1902 + virtual void MdvppReturnPicture(TVideoPicture* aPicture);
1.1903 + virtual void MdvppSupplementalInformation(const TDesC8& aData,
1.1904 + const TTimeIntervalMicroSeconds& aTimestamp,
1.1905 + const TPictureId& aPictureId);
1.1906 + virtual void MdvppPictureLoss();
1.1907 + virtual void MdvppPictureLoss(const TArray<TPictureId>& aPictures);
1.1908 + virtual void MdvppSliceLoss(TUint aFirstMacroblock, TUint aNumMacroblocks, const TPictureId& aPicture);
1.1909 + virtual void MdvppReferencePictureSelection(const TDesC8& aSelectionData);
1.1910 + virtual void MdvppTimedSnapshotComplete(TInt aError,
1.1911 + TPictureData* aPictureData,
1.1912 + const TTimeIntervalMicroSeconds& aPresentationTimestamp,
1.1913 + const TPictureId& aPictureId);
1.1914 + virtual void MdvppFatalError(CMMFVideoHwDevice* aDevice, TInt aError);
1.1915 + virtual void MdvppInitializeComplete(CMMFVideoHwDevice* aDevice, TInt aError);
1.1916 + virtual void MdvppStreamEnd();
1.1917 +
1.1918 +private:
1.1919 + MMMFDevVideoPlayObserver& iObserver;
1.1920 + CMMFVideoDecodeHwDevice* iVideoDecodeHwDevice;
1.1921 + CMMFVideoPostProcHwDevice* iVideoPostProcHwDevice;
1.1922 + TUint iInitializationState;
1.1923 +
1.1924 + TDblQue<TVideoPicture> iVideoPictureQue;
1.1925 + TDblQueIter<TVideoPicture> iVideoPictureQueIter;
1.1926 + TUint iNumberOfVideoPictures;
1.1927 + // Not to be used, but kept for BC purposes
1.1928 + TInt iReserved;
1.1929 +
1.1930 + TUint iNumberOfMdvppStreamEndCallbacks;
1.1931 + TBool iIsDecodeComplete;
1.1932 +
1.1933 +#ifdef SYMBIAN_MULTIMEDIA_CODEC_API
1.1934 + RImplInfoPtrArray iPuImplementations;
1.1935 + TBool iPuListCreated;
1.1936 +#endif // SYMBIAN_MULTIMEDIA_CODEC_API
1.1937 + };
1.1938 +
1.1939 +
1.1940 +/**
1.1941 +The MMMFDevVideoPlayObserver mixin class defines a set of callback functions that the client using
1.1942 +the MSL video API needs to implement. The callbacks are called in the context of the same thread that
1.1943 +uses the API. DevVideo API methods can be safely called from the callbacks.
1.1944 +@publishedAll
1.1945 +@released
1.1946 +*/
1.1947 +class MMMFDevVideoPlayObserver
1.1948 + {
1.1949 +public:
1.1950 + /**
1.1951 + Notifies the client that one or more new empty input buffers are available. The client can fetch
1.1952 + the input buffer with GetBufferL().
1.1953 + */
1.1954 + virtual void MdvpoNewBuffers() = 0;
1.1955 +
1.1956 + /**
1.1957 + Returns a used input video picture back to the caller. The picture memory can be re-used or freed.
1.1958 + @param "aPicture" "The picture to return."
1.1959 + */
1.1960 + virtual void MdvpoReturnPicture(TVideoPicture* aPicture) = 0;
1.1961 +
1.1962 + /**
1.1963 + Delivers supplemental information from a coded data unit. The information is codec-dependent.
1.1964 + @param "aData" "The supplemental data. The reference is only valid until the method
1.1965 + returns, and thus the data must be processed or copied immediately."
1.1966 + @param "aTimestamp" "The presentation timestamp for the picture that the supplemental data
1.1967 + is part of."
1.1968 + @param "aPictureId" "Picture identifier for the picture. If a picture ID is not available,
1.1969 + aPictureId.iIdType is set to ENone."
1.1970 + */
1.1971 + virtual void MdvpoSupplementalInformation(const TDesC8& aData,
1.1972 + const TTimeIntervalMicroSeconds& aTimestamp,
1.1973 + const TPictureId& aPictureId) = 0;
1.1974 +
1.1975 + /**
1.1976 + Back channel information from the decoder, indicating a picture loss without specifying the lost picture.
1.1977 + */
1.1978 + virtual void MdvpoPictureLoss() = 0;
1.1979 +
1.1980 + /**
1.1981 + Back channel information from the decoder, indicating the pictures that have been lost.
1.1982 +
1.1983 + @param "aPictures" "Picture identifiers for the lost pictures. The reference is only valid until the
1.1984 + method returns, and thus the data must be processed or copied immediately."
1.1985 + */
1.1986 + virtual void MdvpoPictureLoss(const TArray<TPictureId>& aPictures) = 0;
1.1987 +
1.1988 + /**
1.1989 + Back channel information from the decoder, indicating the loss of consecutive macroblocks in raster
1.1990 + scan order.
1.1991 +
1.1992 + @param "aFirstMacroblock" "The first lost macroblock. The macroblocks are numbered such
1.1993 + that the macroblock in the upper left corner of the picture is considered
1.1994 + macroblock number 1 and the number for each macroblock increases from left
1.1995 + to right and then from top to bottom in raster-scan order."
1.1996 + @param "aNumMacroblocks" "The number of lost macroblocks that are consecutive in raster-scan order."
1.1997 + @param "aPicture" "The picture identifier for the picture where the macroblocks were lost.
1.1998 + If the picture is not known, aPicture.iIdType is set to ENone. The reference
1.1999 + is only valid until the method returns."
1.2000 + */
1.2001 + virtual void MdvpoSliceLoss(TUint aFirstMacroblock, TUint aNumMacroblocks, const TPictureId& aPicture)= 0;
1.2002 +
1.2003 + /**
1.2004 + Back channel information from the decoder, indicating a reference picture selection request. The
1.2005 + request is delivered as a coding-standard specific binary message. Reference picture selection can
1.2006 + be used to select a pervious correctly transmitted picture to use as a reference in case later pictures
1.2007 + have been lost.
1.2008 +
1.2009 + @param "aSelectionData" "The reference picture selection request message. The message format is
1.2010 + coding-standard specific, and defined separately. The reference is only
1.2011 + valid until the method returns, and thus the data must be processed or
1.2012 + copied immediately."
1.2013 + */
1.2014 + virtual void MdvpoReferencePictureSelection(const TDesC8& aSelectionData)= 0;
1.2015 +
1.2016 + /**
1.2017 + Called when a timed snapshot request has been completed. When this method is called, the snapshot
1.2018 + has been taken, and the memory reserved for the picture can be re-used or freed.
1.2019 + @param "aError" "An error code, KErrNone if no errors occurred. If an error
1.2020 + occurred, the data in the snapshot may not be valid, but the
1.2021 + memory can still be freed."
1.2022 + @param "aPictureData" "The snapshot picture data."
1.2023 + @param "aPresentationTimestamp" "The presentation timestamp for the snapshot picture. "
1.2024 + @param "aPictureId" "Picture identifier for the picture. If a picture ID is not
1.2025 + available, aPictureId.iIdType is set to ENone."
1.2026 + */
1.2027 + virtual void MdvpoTimedSnapshotComplete(TInt aError,
1.2028 + TPictureData* aPictureData,
1.2029 + const TTimeIntervalMicroSeconds& aPresentationTimestamp,
1.2030 + const TPictureId& aPictureId) = 0;
1.2031 +
1.2032 + /**
1.2033 + Notifies the client that one or more new output pictures are available. The client can then use
1.2034 + GetNewPictureInfo() and NextPicture() to fetch the pictures.
1.2035 + */
1.2036 + virtual void MdvpoNewPictures() = 0;
1.2037 +
1.2038 + /**
1.2039 + Reports a fatal decoding or playback error to the client. When these errors
1.2040 + occur, decoding and playback is stopped automatically. The client must
1.2041 + destroy the CMMFDevVideoPlay object and create a new instance before
1.2042 + attempting to continue. Note that scenarios have been identified where
1.2043 + MdvpoFatalError may get referenced at some point during the execution of a
1.2044 + CMMFDevVideoPlay procedure. Therefore CMMFDevVideoPlay object should be
1.2045 + deleted outside of MdvpoFatalError context in order to avoid accidental
1.2046 + access to de-allocated CMMFDevVideoPlay data members.
1.2047 +
1.2048 + Note that running out of processing power or encountering corrupted
1.2049 + bitstream data should not be classified as errors if the decoder and
1.2050 + post-processor can recover automatically.
1.2051 +
1.2052 + @param "aError" "The error code."
1.2053 + */
1.2054 + virtual void MdvpoFatalError(TInt aError) = 0;
1.2055 +
1.2056 + /**
1.2057 + Reports that DevVideoPlay initialization has completed. The interface can now be used for video
1.2058 + playback.
1.2059 + @param "aError" "Initialization error code, KErrNone if no error occurred."
1.2060 + */
1.2061 + virtual void MdvpoInitComplete(TInt aError) = 0;
1.2062 +
1.2063 + /**
1.2064 + Reports that the input video stream end has been reached and all pictures have been processed.
1.2065 + This method is only called after the client has called InputEnd(). No more output pictures will
1.2066 + be available.
1.2067 + */
1.2068 + virtual void MdvpoStreamEnd() = 0;
1.2069 + };
1.2070 +
1.2071 +
1.2072 +#include <mmf/devvideo/devvideoplay.inl>
1.2073 +
1.2074 +#endif