// Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

// which accompanies this distribution, and is available

// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

#ifndef __DEVVIDEOBASE_H__

#define __DEVVIDEOBASE_H__

#include <e32base.h>

#include <w32std.h>

#include <mmf/devvideo/devvideoconstants.h>

#include <ecom/ecom.h>

/**

Panic utility function

@internalTechnology

*/

LOCAL_C void DevVideoPanic(TInt aReason)

	{

	User::Panic(KDevVideoPanicCategory, aReason);

	}

/**

A hardware device ID that identifies an instantiated video hardware device. 

Used in the playback and recording APIs to identify the component being controlled.

@publishedAll

@released

*/

typedef TInt THwDeviceId;

/**

Defines a supported scale factor for a scaling pre-processor or post-processor.

The scale factor is defined as iScaleNum/iScaleDenom, 

where the values are positive integers and relatively prime.

@publishedAll

@released

*/

class TScaleFactor

	{

public:

	/**Scale factor numerator. Non-zero.*/

	TUint iScaleNum;

	/**Scale factor denominator. Non-zero.*/

	TUint iScaleDenom;

	};

/**

A custom YUV/RGB conversion matrix. The same matrix structure is used for both conversion directions.

@publishedAll

@released

*/

class TYuvConversionMatrix

	{

public:

	/**

	Post-multiplication offset, a three-item vector.

	*/

	TReal iPostOffset[3];

	/**

	Multiplication matrix, a 3x3 matrix. iMatrix[3*i+j] contains the j:th item on the i:th row of the matrix.

	*/

	TReal iMatrix[9];

	/**

	Pre-multiplication offset, a three-item vector.

	*/

	TReal iPreOffset[3];

	};

/**

YUV (YCbCr) uncompressed image data format.

@publishedAll

@released

*/

class TYuvFormat

	{

public:

	/**

	The YUV/RGB conversion coefficients to use

	*/

	TYuvCoefficients iCoefficients;

	/**

	Luminance/chrominance sampling pattern.

	*/

	TYuvSamplingPattern iPattern;

	/**

	Data layout, specifies whether the data is stored in a planar or interleaved mode.

	*/

	TYuvDataLayout iDataLayout;

	/**

	Custom YUV to RGB conversion matrix to use. 

	Valid only if custom conversion matrix is used (iCoefficients is ECustomYuvMatrix).

	*/

	TYuvConversionMatrix* iYuv2RgbMatrix;

	/**

	Custom RGB to YUV conversion matrix to use. 

	Valid only if custom conversion matrix is used (iCoefficients is ECustomYuvMatrix).

	*/

	TYuvConversionMatrix* iRgb2YuvMatrix;

	/**

	Pixel aspect ratio numerator.

	*/

	TUint iAspectRatioNum;

	/**

	Pixel aspect ratio denominator. 

	The aspect ratio is defined as iAspectRatioNum/iAspectRatioDenom, 

	where the values are positive integers and relatively prime.

	*/

	TUint iAspectRatioDenom;

	/**

	Tests whether this TYuvFormat object is the same as aOther.

	@param  "aOther" "The object to compare."

	@return "ETrue if they are the same, EFalse if not."

	*/

	inline TBool operator==(const TYuvFormat& aOther) const;

	};

/**

Defines an uncompressed video format. 

This structure is mainly just a combination of YUV and RGB formats, defined to simplify the rest of the API.

@publishedAll

@released

*/

class TUncompressedVideoFormat

	{

public:

	/**

	The image data format. The validity of the rest of the fields depends on the data format used.

	*/

	TImageDataFormat iDataFormat;

	union

		{

		/**

		YUV picture format details, valid if iDataFormat is EYuvRawData.

		*/

		TYuvFormat iYuvFormat;

		/**

		RGB picture format details, valid if iDataFormat is ERgbRawData or ERgbFbsBitmap.

		*/

		TRgbFormat iRgbFormat;

		};

	/**

	Tests whether this TUncompressedVideoFormat object is the same as aOther.

	@param  "aOther" "The object to compare."

	@return "ETrue if they are the same, EFalse if not."

	*/

	inline TBool operator==(const TUncompressedVideoFormat& aOther) const;

	/**

	Sets this object equal to aOther.

	@param  "aOther" "The object to clone."

	*/

	inline void operator=(const TUncompressedVideoFormat& aOther);

	};

/**

Uncompressed picture data for one video picture.

@publishedAll

@released

*/

class TPictureData

	{

public:

	/**

	The image data format. The validity of the rest of the fields depends on the data format used.

	*/

	TImageDataFormat iDataFormat;

	/**

	Image data size in pixels. In decoder output pictures the actual active picture area may be smaller, 

	this is indicated using TVideoPicture.iCropRect.

	*/

	TSize iDataSize;

	union

		{

		/**

		Pointer to raw image data. Valid if iDataFormat is ERgbRawData or iYuvRawData. 

		The data layout depends on the format used.

		*/

		TPtr8* iRawData;

		/**

		Pointer to an RGB bitmap. Valid if iDataFormat is ERgbFbsBitmap.

		*/

		CFbsBitmap* iRgbBitmap;

		};

	};

/**

Header information for one decoded picture. 

The header information is returned alongside with decoded pictures, 

or it can be read separately when DevVideoPlay is being initialized.

@publishedAll

@released

*/

class TVideoPictureHeader

	{

public:

	/**

	*/

	enum THeaderOptions

		{

		/** Decoding timestamp is valid

		*/

		EDecodingTimestamp		   = 0x00000001,

		/** Presentation timestamp is valid

		*/

		EPresentationTimestamp	   = 0x00000002,

		/** Pre-decoder buffersize is valid

		*/

		EPreDecoderBufferSize		= 0x00000004,

		/** Post-decoder buffersize is valid

		*/

		EPostDecoderBufferSize	   = 0x00000008,

		/** Picture number field is valid

		*/

		EPictureNumber			   = 0x00000010,

		/** Layered coding is used and the layer number field is valid

		*/

		ELayeredCoding			   = 0x00000020,

		/** Supplemental data is available

		*/

		ESupplementalData			= 0x00000040,

		/** Random access buffering period is valid

		*/

		ERandomAccessBufferingPeriod = 0x00000080,

		/** Random access buffer occupancy is valid

		*/

		ERandomAccessBufferOccupancy = 0x00000100

		};

	/**

	Header options.  The value is a bitfield combined from values from THeaderOptions.

	*/

	TUint32 iOptions;

	/**

	Video codec profile used. Use -1 if not applicable or not defined.

	*/

	TInt iProfile;

	/**

	Video codec level. Use -1 if not applicable or not defined.

	*/

	TInt iLevel;

	/**

	Video codec version. Use -1 if not applicable or not defined.

	*/

	TInt iVersion;

	/**

	Pointer to a descriptor that contains optional codec-specific features. Set to NULL if not used. 

	The format of the data is codec-specific. The pointer and descriptor data are valid as long as 

	the header information structure is valid.

	*/

	const TDesC8* iOptional;

	/**

	Image size in memory, in pixels. May be larger than the displayed picture.

	*/

	TSize iSizeInMemory;

	/**

	The portion of the full image to display.

	*/

	TRect iDisplayedRect;

	/**

	Picture presentation timestamp. Valid only if EPresentationTimestamp is set in the options. 

	The clock frequency is stored in the timestamp structure.

	*/

	TTimeIntervalMicroSeconds iPresentationTimestamp;

	/**

	Picture decoding timestamp. Valid only if EDecodingTimestamp is set in the options.

	*/

	TTimeIntervalMicroSeconds iDecodingTimestamp;

	/**

	Expected pre-decoder buffer size in bytes. Valid only if EPreDecoderBufferSize is set in the options.

	*/

	TUint iPreDecoderBufferSize;

	/**

	Expected post-decoder buffer size in bytes. Valid only if EPostDecoderBufferSize is set in the options. 

	It is assumed that a frame buffer to be displayed is returned before the decoding of the next frame 

	is started. If this is not the case, a larger post-decoder buffer may actually be needed.

	*/

	TUint iPostDecoderBufferSize;

	/**

	Picture number, valid only if EPictureNumber is set in the options. 

	This field is used to indicate one of the following: picture number or long-term picture index for H.263, 

	vop_id for MPEG-4 Visual,  picture number or long-term picture number for AVC.

	*/

	TUint iPictureNumber;

	/**

	Picture layer number if layered coding is used, valid only if ELayeredCoding is set in the options. 

	Layers are numbered [0…n-1], where n is the number of layers available. The first layer (layer zero) 

	is the base layer, it can be decoded independently from the other layers, and it has the lowest total bitrate.

	*/

	TUint iPictureLayer;

	/**

	Picture supplemental data, valid only if ESupplementalData is set in the options. 

	The pointer and descriptor data are valid as long as the header information structure is valid.

	*/

	const TDesC8* iSupplementalData;

	/**

	True if the picture is a random-accessible picture.

	*/

	TBool iIsRandomAccessible;

	/**

	The expected initial pre-decoder buffering period before starting the playback from this picture. 

	Valid only if this picture is randomly accessible (iIsRandomAccessible is true) and 

	ERandomAccessBufferingPeriod is set in the options. MPEG-2 and H.264 | MPEG-4 AVC use this value.

	*/

	TTimeIntervalMicroSeconds32 iRandomAccessBufferingPeriod;

	/**

	The expected initial pre-decoder buffer occupancy in bytes before starting the playback 

	from this picture. Valid if this picture is randomly accessible (iIsRandomAccessible is true) and 

	ERandomAccessBufferOccupancy is set in the options. MPEG-4 Visual uses this value.

	*/

	TUint iRandomAccessBufferOccupancy;

	};

/**

One uncompressed video picture. Used for both decoded picture output as well as uncompressed picture input.

@publishedAll

@released

*/

class TVideoPicture

	{

public:

	/**

	*/

	enum TVideoPictureOptions

		{

		/** The timestamp field is valid.

		*/

		ETimestamp		 = 0x00000001,

		/** The crop rectangle field is valid.

		*/

		ECropRect		  = 0x00000002,

		/** Picture header information is present.

		*/

		EHeader			= 0x00000004,

		/** The layer bit count targets field is valid.

		*/

		EBitTargets		= 0x00000008,

		/** Set in encoder input to request an instantaneous decoder refresh. 

		As a response, the encoder should code an intra frame and no consecutive 

		frame should refer to any frame before the encoded intra frame (in coding order).

		*/

		EReqInstantRefresh = 0x00000010,

		/** Set in encoder input to indicate a scene cut in the picture stream.

		*/

		ESceneCut		  = 0x00000020,

		/** Set if a picture effect is in use and the picture effect field is valid.

		*/

		EPictureEffect	 = 0x00000040,

		/** Set if picture effect parameters are valid.

		*/

		EEffectParameters  = 0x00000080

		};

	/**

	The picture data. The picture data, including all pointers, must remain valid until 

	the picture has been returned to its originator.

	*/

	TPictureData iData;

	/**

	Picture options. The value is a bitfield combined from values from TVideoPictureOptions.

	*/

	TUint32 iOptions;

	/**

	Picture timestamp. Valid if ETimestamp is set in the options. 

	Used for presentation timestamps in video playback and capture timestamps in uncompressed video 

	input for recording. If the timestamp is not specified for decoded video input for playback, 

	the picture is displayed immediately. For decoded video output in playback and uncompressed 

	video input for recording, the timestamp must always be set.

	*/

	TTimeIntervalMicroSeconds iTimestamp;

	/**

	Pan-scan cropping rectangle. Defines the area of the picture used for further processing. 

	Only used for decoded video output.

	*/

	TRect iCropRect;

	/**

	Picture header information. Valid if EHeader is set in the options. 

	Normally this field is only used in decoded pictures returned from the playback API. 

	In that case the header info pointer is valid until the picture is returned to the API.

	*/

	TVideoPictureHeader* iHeader;

	/**

	The target number of bits for each bit-rate scalability layer, valid when EBitTargets is set in the options. 

	Used in video encoding when the caller controls the bit-rate for each picture separately.

	The field points to a table containing the target number of bits to use for each layer when 

	encoding this picture, starting from the lowest layer. The bit count for an enhancement layer 

	includes all lower layers. For example, if the client uses two layers, and reserves 1.5 kilobits 

	for the base layer and three kilobits for the whole picture, this field is set to {1500, 3000}.

	*/

	RArray<TUint>* iLayerBitRates;

	/**

	The picture effect in use when capturing this picture, valid when EPictureEffect is set in the options. 

	This information can be used when encoding the picture. Note that setting a picture effect does not 

	imply that the encoder should modify the picture data based on the effect. Instead, it can be used as 

	an encoding hint. For example, fade to black implies that the global picture brightness has been decreased, 

	and this knowledge can be used to aid motion prediction.

	@see TPictureEffects

	*/

	TPictureEffect iEffect;

	/**

	Picture effect parameter for fade to/from black, valid when EEffectParameters is set in the options 

	and iEffect is EEffectFadeFromBlack or EEffectFadeToBlack. The value range is [0…65536], with zero 

	indicating the picture is black and 65536 indicating that the lightness of the picture is unchanged. 

	If the parameter is not given, the caller is unaware of the proper value or the value fluctuates spatially.

	*/

	TUint iFadeParam;

	/**

	A pointer for free-form user data. The pointer is set by the module that created the buffer, and is 

	usually used for memory management purposes.

	*/

	TAny* iUser;

	/**

	A queue link used internally by the MSL video components.

	*/

	TDblQueLink iLink;

	};

/**

Identifies a video picture in feedback messages.

@publishedAll

@released

*/

class TPictureId

	{

public:

	enum TPictureIdType

		{

		/** Unidentified picture. */

		ENone,

		/** The picture is identified using its temporal reference. */

		ETemporalReference,

		/** The picture is identified using its picture number. Picture numbers are used in H.263 annex U and H.264 | MPEG-4 AVC, for example.. */

		EPictureNumber

		};

	/** Picture identified type. */

	TPictureIdType iIdType;	

	/** The picture identifier. The interpretation of this field depends on the value iIdType */

	TUint32 iId;

	};

/**

Defines a compressed video format. The format is identified by its MIME type, which may include 

parameters that describe the used format profile and level. The MIME type used for H.263

is video/H263-2000, specified in TS 26.234, and the type for MPEG-4 is video/MP4V-ES, specified in RFC 3016.

@publishedAll

@released

*/

class CCompressedVideoFormat : public CBase

	{

public:

	/**

	Static factory function for creating new CCompressedVideoFormat objects.

	@param "aMimeType"		"Video codec MIME type, including optional parameters for profile, 

							level and version information. The CCompressedVideoFormat object creates

							and owns a copy of this buffer and takes care of deallocation."

	@param "aOptionalData"	"Reference to a descriptor that contains optional codec-specific data. 

							Set to KNullDesC8 if not used. [The format of the data is codec-specific, typically

							a package buffer containing a data structure may be used. The pointer lifetime 

							and validity requirements are specified with each method that uses this structure."

	@return "Pointer to a fully constructed CCompressedVideoFormat object."

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