epoc32/include/mmf/devvideo/videorecordhwdevice.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
williamr@2
     1
// Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2
     2
// All rights reserved.
williamr@2
     3
// This component and the accompanying materials are made available
williamr@2
     4
// 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
williamr@2
     5
// which accompanies this distribution, and is available
williamr@2
     6
// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2
     7
//
williamr@2
     8
// Initial Contributors:
williamr@2
     9
// Nokia Corporation - initial contribution.
williamr@2
    10
//
williamr@2
    11
// Contributors:
williamr@2
    12
//
williamr@2
    13
// Description:
williamr@2
    14
//
williamr@2
    15
williamr@2
    16
#ifndef __VIDEORECORDHWDEVICE_H__
williamr@2
    17
#define __VIDEORECORDHWDEVICE_H__
williamr@2
    18
williamr@2
    19
#include <mmf/devvideo/devvideobase.h>
williamr@2
    20
#include <mmf/devvideo/devvideorecord.h>
williamr@2
    21
williamr@2
    22
/**
williamr@2
    23
A base class for all video recording (encoding and pre-processing) hardware devices. Since both encoders 
williamr@2
    24
and pre-processors can implement pre-processing functionality, this class includes all pre-processing 
williamr@2
    25
related methods.
williamr@2
    26
@publishedAll
williamr@2
    27
@released
williamr@2
    28
*/
williamr@2
    29
class CMMFVideoRecordHwDevice : public CMMFVideoHwDevice
williamr@2
    30
	{
williamr@2
    31
public:
williamr@2
    32
	/**
williamr@2
    33
	Retrieves information about the pre-processing capabilities of this hardware device.
williamr@2
    34
williamr@2
    35
	@return	"Pre-processor information as a CPreProcessorInfo object. The object is pushed to the 
williamr@2
    36
			cleanup stack, and must be deallocated by the client."
williamr@2
    37
	@leave	"The method will leave if an error occurs."
williamr@2
    38
	*/
williamr@2
    39
	virtual CPreProcessorInfo* PreProcessorInfoLC() = 0;
williamr@2
    40
williamr@2
    41
	/**
williamr@2
    42
	Sets the hardware device input format. If both a pre-processor and an encoder are used, the 
williamr@2
    43
	pre-processor output format and the encoder input format must be the same. The input format for 
williamr@2
    44
	the first device in the system is the input format for video input data. The method has to be called 
williamr@2
    45
	for both direct capture as well as memory buffer input.
williamr@2
    46
williamr@2
    47
	@param	"aFormat"		"The input format to use."
williamr@2
    48
	@param	"aPictureSize"	"The input picture size in pixels."
williamr@2
    49
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
    50
				- KErrNotSupported - The input format specified is not supported."
williamr@2
    51
	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."
williamr@2
    52
	*/
williamr@2
    53
	virtual void SetInputFormatL(const TUncompressedVideoFormat& aFormat, const TSize& aPictureSize) = 0;
williamr@2
    54
williamr@2
    55
	/**
williamr@2
    56
	Sets the data source to be a camera, and sets the device to use direct capture for input.
williamr@2
    57
williamr@2
    58
	@param	"aCameraHandle"	"A camera handle for the camera to use. The handle is passed 
williamr@2
    59
							to CCamera::NewDuplicateL() in the camera API "
williamr@2
    60
	@param	"aPictureRate"	"Video capture picture rate."
williamr@2
    61
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
    62
				- KErrNotSupported - Direct capture is not supported or the picture rate specified is not 
williamr@2
    63
									 supported."
williamr@2
    64
	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."
williamr@2
    65
	*/
williamr@2
    66
	virtual void SetSourceCameraL(TInt aCameraHandle, TReal aPictureRate) = 0;
williamr@2
    67
williamr@2
    68
	/**
williamr@2
    69
	Sets the data source to be memory buffers.
williamr@2
    70
williamr@2
    71
	@param	"aMaxPictureRate"		"The maximum picture rate for input pictures."
williamr@2
    72
	@param	"aConstantPictureRate"	"True if the input picture rate is constant. In that case, 
williamr@2
    73
									aMaxPictureRate specifies the picture rate."
williamr@2
    74
	@param	"aProcessRealtime"		"True if real-time processing is needed, false if not. Real-time 
williamr@2
    75
									processing is typically neede for video recording applications, while
williamr@2
    76
									video conversion and off-line processing applications do not require it."
williamr@2
    77
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
    78
				- KErrNotSupported - The picture rate specified is not supported."
williamr@2
    79
	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."
williamr@2
    80
	*/
williamr@2
    81
	virtual void SetSourceMemoryL(TReal aMaxPictureRate, TBool aConstantPictureRate, TBool aProcessRealtime) = 0;
williamr@2
    82
williamr@2
    83
	/**
williamr@2
    84
	Sets the clock source to use for video timing. When video recording is synchronized with audio, 
williamr@2
    85
	the clock source is implemented by the audio playback subsystem, otherwise the clock source should 
williamr@2
    86
	get the time from the system clock.
williamr@2
    87
williamr@2
    88
	If no clock source is set, video recording will not be synchronized, but will proceed as fast as
williamr@2
    89
	possible, depending on input data and output buffer availability. If direct capturing is used without
williamr@2
    90
	a clock source, the timestamps in the output data may not be valid.
williamr@2
    91
williamr@2
    92
	@param	"aClock"	"The clock source to use."
williamr@2
    93
	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."
williamr@2
    94
	*/
williamr@2
    95
	virtual void SetClockSource(MMMFClockSource* aClock) = 0;
williamr@2
    96
williamr@2
    97
	/**
williamr@2
    98
	Sets pre-processing options for RGB to YUV color space conversion. By default, input RGB data is 
williamr@2
    99
	assumed to use the full value range ([0…255]), and the output YUV format is the hardware device output 
williamr@2
   100
	format, so typically calling this method is not necessary.
williamr@2
   101
williamr@2
   102
	@param	"aRange"		"Input RGB data range"
williamr@2
   103
	@param	"aOutputFormat"	"Conversion output YUV format."
williamr@2
   104
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   105
				- KErrNotSupported - The formats specified are not supported"
williamr@2
   106
	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."
williamr@2
   107
	*/
williamr@2
   108
	virtual void SetRgbToYuvOptionsL(TRgbRange aRange, const TYuvFormat& aOutputFormat) = 0;
williamr@2
   109
williamr@2
   110
	/**
williamr@2
   111
	Sets pre-processing options for YUV to YUV data format conversion. By default, the hardware device input 
williamr@2
   112
	and output data formats are used. For encoder devices, the device input format and a the closest matching
williamr@2
   113
	format supported by the encoding process are used. Typically calling this method is not necessary.
williamr@2
   114
williamr@2
   115
	@param	"aInputFormat"	"Conversion input format."
williamr@2
   116
	@param	"aOutputFormat"	"Conversion output format."
williamr@2
   117
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   118
				- KErrNotSupported - The formats specified are not supported"
williamr@2
   119
	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."
williamr@2
   120
	*/
williamr@2
   121
	virtual void SetYuvToYuvOptionsL(const TYuvFormat& aInputFormat, const TYuvFormat& aOutputFormat) = 0;
williamr@2
   122
williamr@2
   123
	/**
williamr@2
   124
	Sets the pre-processing types to be used.
williamr@2
   125
williamr@2
   126
	@param	"aPreProcessTypes"	"The pre-processing steps to perform, a bitwise OR of values from
williamr@2
   127
								TPrePostProcessType."
williamr@2
   128
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   129
				- KErrNotSupported - The pre-processing combination is not supported"
williamr@2
   130
	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().
williamr@2
   131
			If called after initialization, the change must only be committed when CommitL() is called."
williamr@2
   132
	*/
williamr@2
   133
	virtual void SetPreProcessTypesL(TUint32 aPreProcessTypes) = 0;
williamr@2
   134
williamr@2
   135
	/**
williamr@2
   136
	Sets pre-processing options for rotation.
williamr@2
   137
williamr@2
   138
	@param	"aRotationType"	"The rotation to perform."
williamr@2
   139
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   140
				- KErrNotSupported - The rotation type is not supported."
williamr@2
   141
	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().
williamr@2
   142
			If called after initialization, the change must only be committed when CommitL() is called."
williamr@2
   143
	*/
williamr@2
   144
	virtual void SetRotateOptionsL(TRotationType aRotationType) = 0;
williamr@2
   145
williamr@2
   146
	/**
williamr@2
   147
	Sets pre-processing options for scaling.
williamr@2
   148
williamr@2
   149
	@param	"aTargetSize"			"Target picture size. If a fixed scale factor size is used, the new 
williamr@2
   150
									dimensions must be set to: 
williamr@2
   151
										width=floor(factor*width), height=floor(factor*height). 
williamr@2
   152
									For example, scaling a QCIF (176x144) picture up by a factor of 4/3 
williamr@2
   153
									yields a size of 234x192."
williamr@2
   154
	@param	"aAntiAliasFiltering"	"True if anti-aliasing filtering should be used. If the pre-processor 
williamr@2
   155
									does not support anti-aliased scaling, or supports anti-aliased scaling
williamr@2
   156
									only, this argument is ignored."
williamr@2
   157
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   158
				- KErrNotSupported - The specified target size is not supported."
williamr@2
   159
	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().
williamr@2
   160
			If called after initialization, the change must only be committed when CommitL() is called."
williamr@2
   161
	*/
williamr@2
   162
	virtual void SetScaleOptionsL(const TSize& aTargetSize, TBool aAntiAliasFiltering) = 0;
williamr@2
   163
williamr@2
   164
	/**
williamr@2
   165
	Sets pre-processing options for input cropping. Input cropping is typically used for digital zooming.
williamr@2
   166
williamr@2
   167
	@param	"aRect"	"The input cropping rectangle specifying the area of the picture to use. The rectangle 
williamr@2
   168
					must fit completely inside the input picture."
williamr@2
   169
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   170
				- KErrNotSupported - The specified cropping rectangle is not supported."
williamr@2
   171
	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().
williamr@2
   172
			If called after initialization, the change must only be committed when CommitL() is called."
williamr@2
   173
	*/
williamr@2
   174
	virtual void SetInputCropOptionsL(const TRect& aRect) = 0;
williamr@2
   175
williamr@2
   176
	/**
williamr@2
   177
	Sets pre-processing options for output cropping. Output cropping is performed after other 
williamr@2
   178
	pre-processing operations but before output padding. Output cropping and padding can be used in 
williamr@2
   179
	combination to prepare the picture size to suit the encoder, typically video encoders only support
williamr@2
   180
	picture sizes that are multiples of 16 pixels.
williamr@2
   181
williamr@2
   182
	@param	"aRect"	"The output cropping rectangle specifying the area of the picture to use. The 
williamr@2
   183
					rectangle must fit completely inside the picture."
williamr@2
   184
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   185
				- KErrNotSupported - The specified cropping rectangle is not supported."
williamr@2
   186
	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().
williamr@2
   187
			If called after initialization, the change must only be committed when CommitL() is called."
williamr@2
   188
	*/
williamr@2
   189
	virtual void SetOutputCropOptionsL(const TRect& aRect) = 0;
williamr@2
   190
williamr@2
   191
	/**
williamr@2
   192
	Sets pre-processing options for output padding. Output padding is performed as the last pre-processing 
williamr@2
   193
	operation, and typically used to prepare the picture size to suit the encoder. The image is padded with 
williamr@2
   194
	black pixels.
williamr@2
   195
williamr@2
   196
	@param	"aOutputSize"	"The padded output picture size. The output size must be large enough for the 
williamr@2
   197
							picture in its new position."
williamr@2
   198
	@param	"aPicturePos"	"The position for the original picture in the new padded picture. The original 
williamr@2
   199
							picture in its new position must fit completely inside the new picture."
williamr@2
   200
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   201
				- KErrNotSupported - The specified padding settings are not supported."
williamr@2
   202
	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().
williamr@2
   203
			If called after initialization, the change must only be committed when CommitL() is called."
williamr@2
   204
	*/
williamr@2
   205
	virtual void SetOutputPadOptionsL(const TSize& aOutputSize, const TPoint& aPicturePos) = 0;
williamr@2
   206
williamr@2
   207
	/**
williamr@2
   208
	Sets color enhancement pre-processing options.
williamr@2
   209
williamr@2
   210
	@param	"aOptions"	"Color enchancement options."
williamr@2
   211
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   212
				- KErrNotSupported - The specified settings are not supported."
williamr@2
   213
	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().
williamr@2
   214
			If called after initialization, the change must only be committed when CommitL() is called."
williamr@2
   215
	*/
williamr@2
   216
	virtual void SetColorEnhancementOptionsL(const TColorEnhancementOptions& aOptions) = 0;
williamr@2
   217
williamr@2
   218
	/**
williamr@2
   219
	Sets frame stabilisation options.
williamr@2
   220
williamr@2
   221
	@param	"aOutputSize"			"Output picture size. The output picture size must be smaller than 
williamr@2
   222
									or equal to the hardware device input picture size."
williamr@2
   223
	@param	"aFrameStabilisation"	"True if frame stabilisation should be used. By default stabilisation is 
williamr@2
   224
									not used."
williamr@2
   225
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   226
				- KErrNotSupported - The specified settings are not supported."
williamr@2
   227
	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().
williamr@2
   228
			If called after initialization, the change must only be committed when CommitL() is called."
williamr@2
   229
	*/
williamr@2
   230
	virtual void SetFrameStabilisationOptionsL(const TSize& aOutputSize, TBool aFrameStabilisation) = 0;
williamr@2
   231
williamr@2
   232
	/**
williamr@2
   233
	Sets custom implementation-specific pre-processing options.
williamr@2
   234
williamr@2
   235
	@param	"aOptions"	"Post-processing options. The data format is implementation-specific."
williamr@2
   236
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   237
				- KErrNotSupported - The options are not supported."
williamr@2
   238
	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().
williamr@2
   239
			If called after initialization, the change must only be committed when CommitL() is called."
williamr@2
   240
	*/
williamr@2
   241
	virtual void SetCustomPreProcessOptionsL(const TDesC8& aOptions) = 0;
williamr@2
   242
williamr@2
   243
	/**
williamr@2
   244
	Initializes the device, and reserves hardware resources. If direct capture is used, this method also 
williamr@2
   245
	prepares the camera API for capture by calling PrepareVideoCaptureL(). This method is asynchronous, 
williamr@2
   246
	the device will call MMMFDevVideoRecordProxy::MdvrpInitializeComplete() after initialization has completed.
williamr@2
   247
	Video capturing and encoding can be started with Start() with a relatively low delay since the hardware
williamr@2
   248
	has already been set up.
williamr@2
   249
williamr@2
   250
	Error handling: Errors are reported using the MdvrpInitializeComplete() callback method. Typical error 
williamr@2
   251
	codes used:
williamr@2
   252
		- KErrHardwareNotAvailable - Not enough free video processing hardware resources
williamr@2
   253
		- KErrNotSupported - The current configuration is not supported.
williamr@2
   254
	@pre	"This method can only be called before the hwdevice has been initialized."
williamr@2
   255
	*/
williamr@2
   256
	virtual void Initialize() = 0;
williamr@2
   257
williamr@2
   258
	/**
williamr@2
   259
	Commit all changes since the last CommitL(), Revert() or Initialize()
williamr@2
   260
	to the hardware device.  This only applies to methods which can be called both
williamr@2
   261
	before AND after DevVideoPlay has been initialized.
williamr@2
   262
williamr@2
   263
	@see	CMMFVideoEncodeHwDevice::SetOutputRectL
williamr@2
   264
	@see	CMMFVideoRecordHwDevice::SetPreProcessTypesL
williamr@2
   265
	@see	CMMFVideoRecordHwDevice::SetRotateOptionsL
williamr@2
   266
	@see	CMMFVideoRecordHwDevice::SetScaleOptionsL
williamr@2
   267
	@see	CMMFVideoRecordHwDevice::SetInputCropOptionsL
williamr@2
   268
	@see	CMMFVideoRecordHwDevice::SetOutputCropOptionsL
williamr@2
   269
	@see	CMMFVideoRecordHwDevice::SetOutputPadOptionsL
williamr@2
   270
	@see	CMMFVideoRecordHwDevice::SetColorEnhancementOptionsL
williamr@2
   271
	@see	CMMFVideoRecordHwDevice::SetFrameStabilisationOptionsL
williamr@2
   272
	@see	CMMFVideoRecordHwDevice::SetCustomPreProcessOptionsL
williamr@2
   273
	@see	CMMFVideoEncodeHwDevice::SetCodingStandardSpecificOptionsL
williamr@2
   274
	@see	CMMFVideoEncodeHwDevice::SetImplementationSpecificEncoderOptionsL
williamr@2
   275
williamr@2
   276
	@leave  "The method will leave if an error occurs."
williamr@2
   277
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   278
	*/
williamr@2
   279
	virtual void CommitL() = 0;
williamr@2
   280
williamr@2
   281
	/**
williamr@2
   282
	Revert all changes since the last CommitL(), Revert() or Initialize()
williamr@2
   283
	back to their previous settings.  This only applies to methods which can 
williamr@2
   284
	be called both before AND after DevVideoPlay has been initialized.
williamr@2
   285
williamr@2
   286
	@see	CMMFVideoEncodeHwDevice::SetOutputRectL
williamr@2
   287
	@see	CMMFVideoRecordHwDevice::SetPreProcessTypesL
williamr@2
   288
	@see	CMMFVideoRecordHwDevice::SetRotateOptionsL
williamr@2
   289
	@see	CMMFVideoRecordHwDevice::SetScaleOptionsL
williamr@2
   290
	@see	CMMFVideoRecordHwDevice::SetInputCropOptionsL
williamr@2
   291
	@see	CMMFVideoRecordHwDevice::SetOutputCropOptionsL
williamr@2
   292
	@see	CMMFVideoRecordHwDevice::SetOutputPadOptionsL
williamr@2
   293
	@see	CMMFVideoRecordHwDevice::SetColorEnhancementOptionsL
williamr@2
   294
	@see	CMMFVideoRecordHwDevice::SetFrameStabilisationOptionsL
williamr@2
   295
	@see	CMMFVideoRecordHwDevice::SetCustomPreProcessOptionsL
williamr@2
   296
	@see	CMMFVideoEncodeHwDevice::SetCodingStandardSpecificOptionsL
williamr@2
   297
	@see	CMMFVideoEncodeHwDevice::SetImplementationSpecificEncoderOptionsL
williamr@2
   298
williamr@2
   299
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   300
	*/
williamr@2
   301
	virtual void Revert() = 0;
williamr@2
   302
williamr@2
   303
	/**
williamr@2
   304
	Writes an uncompressed input picture. When the picture has been used, it must be returned to the client
williamr@2
   305
	with MMMFDevVideoRecordProxy::MdvrpReturnPicture(). This method must not be called if direct capture is 
williamr@2
   306
	used.
williamr@2
   307
williamr@2
   308
	@param	"aPicture"	"The picture to write."
williamr@2
   309
	@leave	"The method will leave if an error occurs."
williamr@2
   310
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   311
	*/
williamr@2
   312
	virtual void WritePictureL(TVideoPicture* aPicture) = 0;
williamr@2
   313
williamr@2
   314
	/**
williamr@2
   315
	Notifies the hardware device that the end of input data has been reached and no more input pictures
williamr@2
   316
	will be written. The hardware device can use this signal to ensure that the remaining data gets 
williamr@2
   317
	processed, without waiting for new data. After the remaining data has been processed, the hardware
williamr@2
   318
	device must call the proxy callback MdvrpStreamEnd().
williamr@2
   319
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   320
	*/
williamr@2
   321
	virtual void InputEnd() = 0;
williamr@2
   322
williamr@2
   323
	/**
williamr@2
   324
	Starts recording video. This includes capturing pictures from the camera (if direct capture is used), 
williamr@2
   325
	pre-processing and encoding. Recording will proceed until it is stopped or paused. Initally recording 
williamr@2
   326
	is stopped.
williamr@2
   327
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   328
	*/
williamr@2
   329
	virtual void Start() = 0;
williamr@2
   330
williamr@2
   331
	/**
williamr@2
   332
	Stops recording video. No new pictures will be captured, pre-processed, or encoded. If input pictures
williamr@2
   333
	are written while recording is stopped, they will be returned immediately.
williamr@2
   334
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   335
	*/
williamr@2
   336
	virtual void Stop() = 0;
williamr@2
   337
williamr@2
   338
	/**
williamr@2
   339
	Pauses video recording. Recording can be resumed using Resume().
williamr@2
   340
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   341
	*/
williamr@2
   342
	virtual void Pause() = 0;
williamr@2
   343
williamr@2
   344
	/**
williamr@2
   345
	Resumes video recording after a pause.
williamr@2
   346
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   347
	*/
williamr@2
   348
	virtual void Resume() = 0;
williamr@2
   349
williamr@2
   350
	/**
williamr@2
   351
	Freezes the input picture. Normal encoding can be continued using ReleaseFreeze().
williamr@2
   352
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   353
	*/
williamr@2
   354
	virtual void Freeze() = 0;
williamr@2
   355
williamr@2
   356
	/**
williamr@2
   357
	Releases a frozen input picture. Video capturing and encoding continues normally.
williamr@2
   358
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   359
	*/
williamr@2
   360
	virtual void ReleaseFreeze() = 0;
williamr@2
   361
williamr@2
   362
	/**
williamr@2
   363
	Returns the current recording position. The position is the capture timestamp from the latest input 
williamr@2
   364
	picture, or the capture timestamp for the latest picture captured from the camera when direct capture
williamr@2
   365
	is used.
williamr@2
   366
williamr@2
   367
	@return	"The current recording position."
williamr@2
   368
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   369
	*/
williamr@2
   370
	virtual TTimeIntervalMicroSeconds RecordingPosition() = 0;
williamr@2
   371
williamr@2
   372
	/**
williamr@2
   373
	Reads various counters related to processed video pictures. See the definition of TPictureCounters
williamr@2
   374
	for a description of the counters. The counters are reset when Initialize() or this method is called,
williamr@2
   375
	and thus they only include pictures processed since the last call.
williamr@2
   376
williamr@2
   377
	@param	"aCounters"	"The counter structure to fill."
williamr@2
   378
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   379
	*/
williamr@2
   380
	virtual void GetPictureCounters(CMMFDevVideoRecord::TPictureCounters& aCounters) = 0;
williamr@2
   381
williamr@2
   382
	/**
williamr@2
   383
	Reads the frame stabilisation output picture position. This information can be used for positioning the
williamr@2
   384
	viewfinder. The position returned is the stabilisation result for the most recent input picture.
williamr@2
   385
williamr@2
   386
	@param	""aRect	"The position of the stabilisation output picture inside the input picture. If frame 
williamr@2
   387
					stabilisation is not used, the rectangle is set to cover the entire input picture."
williamr@2
   388
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   389
	*/
williamr@2
   390
	virtual void GetFrameStabilisationOutput(TRect& aRect) = 0;
williamr@2
   391
williamr@2
   392
	/**
williamr@2
   393
	Retrieves the number of complexity control levels available for this hardware device. Devices can 
williamr@2
   394
	support processing the same input data with different computational complexity levels. The complexity
williamr@2
   395
	level can affect, for example, the motion vector search range used in an encoder.
williamr@2
   396
williamr@2
   397
	@return	"The number of complexity control levels available, one if multiple levels are not supported."
williamr@2
   398
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   399
	*/
williamr@2
   400
	virtual TUint NumComplexityLevels() = 0;
williamr@2
   401
williamr@2
   402
	/**
williamr@2
   403
	Sets the complexity level to use for video processing in a hardware device. The level can be changed 
williamr@2
   404
	at any time.
williamr@2
   405
williamr@2
   406
	@param	"aLevel"	"The computational complexity level to use. Level zero (0) is the most complex one, 
williamr@2
   407
						with the highest quality. Higher level numbers require less processing and may have
williamr@2
   408
						lower quality."
williamr@2
   409
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   410
	*/
williamr@2
   411
	virtual void SetComplexityLevel(TUint aLevel) = 0;
williamr@2
   412
	};
williamr@2
   413
williamr@2
   414
williamr@2
   415
/**
williamr@2
   416
CMMFVideoEncodeHwDevice is the MSL video encoder hardware device interface. All video encoders must 
williamr@2
   417
implement this interface.
williamr@2
   418
@publishedAll
williamr@2
   419
@released
williamr@2
   420
*/
williamr@2
   421
class CMMFVideoEncodeHwDevice : public CMMFVideoRecordHwDevice
williamr@2
   422
	{
williamr@2
   423
public:
williamr@2
   424
	/**
williamr@2
   425
	Creates a new video encoder hardware device object, based on the implementation UID.
williamr@2
   426
williamr@2
   427
	@param	"aUid"		"Encoder implementation UID."
williamr@2
   428
	@param	"aProxy"	"The proxy implementation to use."
williamr@2
   429
	@return	"A new CMMFVideoEncodeHwDevice object."
williamr@2
   430
	@leave	"This method will leave if an error occurs."
williamr@2
   431
	*/
williamr@2
   432
	IMPORT_C static CMMFVideoEncodeHwDevice* NewL(TUid aUid, MMMFDevVideoRecordProxy& aProxy);
williamr@2
   433
williamr@2
   434
	/**
williamr@2
   435
	Creates a new video encoder hardware device adapter object, based on the Interface Implementation of a Processing Unit.
williamr@2
   436
williamr@2
   437
	@param	"aImplInfo"	"The registration data relating to the Interface Implementation of the Processing Unit."
williamr@2
   438
	@param	"aProxy"	"The proxy implementation to use."
williamr@2
   439
	@return	"A new CMMFVideoEncodeHwDevice object."
williamr@2
   440
	@leave	"This method will leave if an error occurs."
williamr@2
   441
	*/
williamr@2
   442
	IMPORT_C static CMMFVideoEncodeHwDevice* NewPuAdapterL(const CImplementationInformation& aImplInfo, MMMFDevVideoRecordProxy& aProxy);
williamr@2
   443
williamr@2
   444
	/**
williamr@2
   445
	Destructor.
williamr@2
   446
	*/
williamr@2
   447
	IMPORT_C virtual ~CMMFVideoEncodeHwDevice();
williamr@2
   448
williamr@2
   449
	/**
williamr@2
   450
	Retrieves information about the video encoder.
williamr@2
   451
williamr@2
   452
	@return	"Encoder information as a CVideoEncoderInfo object. The object is pushed to the cleanup stack,
williamr@2
   453
			and must be deallocated by the caller."
williamr@2
   454
	@leave	"This method will leave if an error occurs."
williamr@2
   455
	*/
williamr@2
   456
	virtual CVideoEncoderInfo* VideoEncoderInfoLC() = 0;
williamr@2
   457
williamr@2
   458
	/**
williamr@2
   459
	Sets the encoder output format. The picture size depends on the input data format and possible 
williamr@2
   460
	scaling performed.
williamr@2
   461
williamr@2
   462
	@param	"aFormat"				"The video format to use."
williamr@2
   463
	@param	"aDataUnitType"			"The type of output coded data units."
williamr@2
   464
	@param	"aDataEncapsulation"	"Data encapsulation type for output encoded data units."
williamr@2
   465
	@param	"aSegmentationAllowed"	"True if a coded data unit can be segmented into multiple output buffers
williamr@2
   466
									if a single buffer is not large enough."
williamr@2
   467
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   468
				- KErrNotSupported - The format specified is not supported."
williamr@2
   469
	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."
williamr@2
   470
	*/
williamr@2
   471
	virtual void SetOutputFormatL(const CCompressedVideoFormat& aFormat, 
williamr@2
   472
								  TVideoDataUnitType aDataUnitType, 
williamr@2
   473
								  TVideoDataUnitEncapsulation aDataEncapsulation,
williamr@2
   474
								  TBool aSegmentationAllowed=EFalse) = 0;
williamr@2
   475
williamr@2
   476
	/**
williamr@2
   477
	Sets the pre-processor device that will write data to this encoder. Uncompressed pictures will be 
williamr@2
   478
	written with WritePictureL() or through a custom interface. After pictures have been processed, 
williamr@2
   479
	they must be returned to the pre-processor using ReturnPicture().
williamr@2
   480
williamr@2
   481
	@param	"aDevice"	"The input pre-processor device to use."
williamr@2
   482
	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."
williamr@2
   483
	*/
williamr@2
   484
	virtual void SetInputDevice(CMMFVideoPreProcHwDevice* aDevice) = 0;
williamr@2
   485
williamr@2
   486
	/**
williamr@2
   487
	Sets the number of bit-rate scalability layers to use. Set to 1 to disable layered scalability. 
williamr@2
   488
williamr@2
   489
	Bit-rate scalability refers to the ability of a coded stream to be decoded at different bit-rates. 
williamr@2
   490
	Scalable video is typically ordered into hierarchical layers of data. A base layer contains an 
williamr@2
   491
	individual representation of a video stream and enhancement layers contain refinement data in addition
williamr@2
   492
	to the base layer. The quality of the decoded video stream progressively improves as enhancement layers
williamr@2
   493
	are added to the base layer.
williamr@2
   494
williamr@2
   495
	@param	"aNumLayers"	"The number of bit-rate scalability layers to use, set to 1 to disable 
williamr@2
   496
							scalability."
williamr@2
   497
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   498
				- KErrNotSupported - The scalability layers are not supported or too many layers specified."
williamr@2
   499
	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."
williamr@2
   500
	*/
williamr@2
   501
	virtual void SetNumBitrateLayersL(TUint aNumLayers) = 0;
williamr@2
   502
williamr@2
   503
	/**
williamr@2
   504
	Sets the scalability type for a bit-rate scalability layer.
williamr@2
   505
williamr@2
   506
	@param	"aLayer"			"Layer number. Layers are numbered [0...n-1], where n is the number of layers
williamr@2
   507
	available. The				first layer is the base layer, it can be decoded independently from the other
williamr@2
   508
								layers, and it has the lowest total bitrate."
williamr@2
   509
	@param	"aScalabilityType"	"Layer scalability type."
williamr@2
   510
	@leave	" The method will leave if an error occurs. Typical error codes used:
williamr@2
   511
				- KErrNotSupported - The scalability layers or the specified scalability type are not 
williamr@2
   512
									 supported."
williamr@2
   513
	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."
williamr@2
   514
	*/
williamr@2
   515
	virtual void SetScalabilityLayerTypeL(TUint aLayer, TScalabilityType aScalabilityType) = 0;
williamr@2
   516
williamr@2
   517
	/**
williamr@2
   518
	Sets the reference picture options to be used for all scalability layers. The settings can be overridden
williamr@2
   519
	for an individual scalability layer by using SetLayerReferenceOptions().
williamr@2
   520
williamr@2
   521
	@param	"aMaxReferencePictures"	"The maximum number of reference pictures to be used. More than one 
williamr@2
   522
									reference frame can be used in the H.264 | MPEG-4 AVC and in some 
williamr@2
   523
									advanced profiles of MPEG-4 Part 2 and H.263. The minimum value is one."
williamr@2
   524
	@param	"aMaxPictureOrderDelay"	"The maximum picture order delay, in number of pictures. This specifies
williamr@2
   525
									the maximum amount of  pictures that precede any picture in the sequence
williamr@2
   526
									in decoding order and follow the picture in presentation order. Pictures
williamr@2
   527
									may be coded/decoded in different order from their capture/display order.
williamr@2
   528
									Thus, decoded pictures have to be buffered to order them in correct 
williamr@2
   529
									display order. For example, if one conventional B picture is coded 
williamr@2
   530
									between P pictures, a one-picture display ordering delay has to be 
williamr@2
   531
									applied in the decoder. The minimum value is zero, which indicates 
williamr@2
   532
									that pictures must be coded in capture/display order."
williamr@2
   533
	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."
williamr@2
   534
	*/
williamr@2
   535
	virtual void SetGlobalReferenceOptions(TUint aMaxReferencePictures, TUint aMaxPictureOrderDelay) = 0;
williamr@2
   536
williamr@2
   537
	/**
williamr@2
   538
	Sets the reference picture options to be used for a single scalability layer. These settings override 
williamr@2
   539
	those set with SetGlobalReferenceOptions().
williamr@2
   540
williamr@2
   541
	@param	"aLayer"				"Layer number."
williamr@2
   542
	@param	"aMaxReferencePictures"	"The maximum number of reference pictures to be used."
williamr@2
   543
	@param	"aMaxPictureOrderDelay"	"The maximum picture order delay, in number of pictures."
williamr@2
   544
	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."
williamr@2
   545
	*/
williamr@2
   546
	virtual void SetLayerReferenceOptions(TUint aLayer, TUint aMaxReferencePictures, TUint aMaxPictureOrderDelay) = 0;
williamr@2
   547
williamr@2
   548
	/**
williamr@2
   549
	Sets encoder buffering options.
williamr@2
   550
williamr@2
   551
	@param	"aOptions"	"The buffering options."
williamr@2
   552
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   553
				- KErrNotSupported - The specified settings are not supported."
williamr@2
   554
	@pre	"This method may only be called before the hwdevice has been initialized using Initialize()."
williamr@2
   555
	*/
williamr@2
   556
	virtual void SetBufferOptionsL(const TEncoderBufferOptions& aOptions) = 0;
williamr@2
   557
williamr@2
   558
	/**
williamr@2
   559
	Sets the encoder output rectangle. This rectangle specifies the part of the input and output pictures 
williamr@2
   560
	which is displayed after encoding. Many video codecs process data in 16x16 pixel units but enable 
williamr@2
   561
	specifying and coding the encoder output rectangle for image sizes that are not multiple of 16 pixels 
williamr@2
   562
	(e.g 160x120).
williamr@2
   563
williamr@2
   564
	@param	"aRect"	"The encoder output rectangle."
williamr@2
   565
	@leave	"The method will leave if an error occurs."
williamr@2
   566
	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().
williamr@2
   567
			If called after initialization, the change must only be committed when CommitL() is called."
williamr@2
   568
	*/
williamr@2
   569
	virtual void SetOutputRectL(const TRect& aRect) = 0;
williamr@2
   570
williamr@2
   571
	/**
williamr@2
   572
	Sets whether bit errors or packets losses can be expected in the video transmission. The video encoder 
williamr@2
   573
	can use this information to optimize the bitstream.
williamr@2
   574
williamr@2
   575
	@param	"aBitErrors"	"True if bit errors can be expected."
williamr@2
   576
	@param	"aPacketLosses"	"True if packet losses can be expected."
williamr@2
   577
	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().
williamr@2
   578
			If called after initialization, the change must only be committed when CommitL() is called."
williamr@2
   579
	*/
williamr@2
   580
	virtual void SetErrorsExpected(TBool aBitErrors, TBool aPacketLosses) = 0;
williamr@2
   581
williamr@2
   582
	/**
williamr@2
   583
	Sets the minimum frequency (in time) for instantaneous random access points in the bitstream. An 
williamr@2
   584
	instantaneous random access point is such where the decoder can achieve a full output picture 
williamr@2
   585
	immediately by decoding data starting from the random access point. The random access point frequency 
williamr@2
   586
	may be higher than signalled, if the sequence contains scene cuts which typically cause a coding 
williamr@2
   587
	of a random access point.
williamr@2
   588
williamr@2
   589
	@param	"aRate"	"Random access point rate, in pictures per second. For example, to request a random 
williamr@2
   590
					access point every ten seconds, set the value to 0.1."
williamr@2
   591
	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().
williamr@2
   592
			If called after initialization, the change must only be committed when CommitL() is called."
williamr@2
   593
	*/
williamr@2
   594
	virtual void SetMinRandomAccessRate(TReal aRate) = 0;
williamr@2
   595
williamr@2
   596
	/**
williamr@2
   597
	Sets coding-standard specific encoder options.
williamr@2
   598
williamr@2
   599
	@param	"aOptions"	"The options to use. The data format for the options is coding-standard specific, 
williamr@2
   600
						and defined separately."
williamr@2
   601
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   602
				- KErrNotSupported - The specified settings are not supported."
williamr@2
   603
	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().
williamr@2
   604
			If called after initialization, the change must only be committed when CommitL() is called."
williamr@2
   605
	*/
williamr@2
   606
	virtual void SetCodingStandardSpecificOptionsL(const TDesC8& aOptions) = 0;
williamr@2
   607
williamr@2
   608
	/**
williamr@2
   609
	Sets implementation-specific encoder options.
williamr@2
   610
williamr@2
   611
	@param	"aOptions"	"The options to use. The data format for the options is specific to the encoder 
williamr@2
   612
						implementation, and defined separately by the encoder implementer."
williamr@2
   613
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   614
				- KErrNotSupported - The specified settings are not supported."
williamr@2
   615
	@pre	"This method can be called either before or after the hwdevice has been initialized with Initialize().
williamr@2
   616
			If called after initialization, the change must only be committed when CommitL() is called."
williamr@2
   617
	*/
williamr@2
   618
	virtual void SetImplementationSpecificEncoderOptionsL(const TDesC8& aOptions) = 0;
williamr@2
   619
williamr@2
   620
	/**
williamr@2
   621
	Returns coding-standard specific initialization output from the encoder. The information can contain, 
williamr@2
   622
	for example, the MPEG-4 VOL header. This method can be called after Initialize() has been called.
williamr@2
   623
williamr@2
   624
	@return	"Coding-standard specific initialization output. The data format is coding-standard specific 
williamr@2
   625
			and defined separately. The buffer is pushed to the cleanup stack, and the caller is responsible
williamr@2
   626
			for deallocating it."
williamr@2
   627
	@leave	"The method will leave if an error occurs."
williamr@2
   628
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   629
	*/
williamr@2
   630
	virtual HBufC8* CodingStandardSpecificInitOutputLC() = 0;
williamr@2
   631
williamr@2
   632
	/**
williamr@2
   633
	Returns implementation-specific initialization output from the encoder. This method can be called after
williamr@2
   634
	Initialize() has been called.
williamr@2
   635
williamr@2
   636
	@return	"Implementation-specific initialization output. The data format is specific to the encoder 
williamr@2
   637
			implementation, and defined by the encoder supplier. The buffer is pushed to the cleanup stack,
williamr@2
   638
			and the caller is responsible for deallocating it."
williamr@2
   639
	@leave	"The method will leave if an error occurs."
williamr@2
   640
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   641
	*/
williamr@2
   642
	virtual HBufC8* ImplementationSpecificInitOutputLC() = 0;
williamr@2
   643
williamr@2
   644
	/**
williamr@2
   645
	Sets the number of unequal error protection levels. By default unequal error protection is not used.
williamr@2
   646
williamr@2
   647
	@param	"aNumLevels"		"The number of unequal error protection levels. To disable unequal error
williamr@2
   648
								protection, set this value to one"
williamr@2
   649
	@param	"aSeparateBuffers"	"True if each unequal error protection level of a coded data unit shall be
williamr@2
   650
								encapsulated in its own output buffer. Ignored if unequal error protection
williamr@2
   651
								is not used."
williamr@2
   652
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   653
				- KErrNotSupported - Unequal error protection is not supported."
williamr@2
   654
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   655
	*/
williamr@2
   656
	virtual void SetErrorProtectionLevelsL(TUint aNumLevels, TBool aSeparateBuffers) = 0;
williamr@2
   657
williamr@2
   658
	/**
williamr@2
   659
	Sets up an unequal error protection level. If unequal error protection is not used, this method can be
williamr@2
   660
	used to control settings for the whole encoded bitstream.
williamr@2
   661
williamr@2
   662
	@param	"aLevel"	"Error protection level number. This argument is ignored if unequal error protection
williamr@2
   663
						is not in use."
williamr@2
   664
	@param	"aBitrate"	"Target bit-rate for this error protection level."
williamr@2
   665
	@param	"aStrength"	"Forward error control strength for this error protection level. The strength
williamr@2
   666
						can be specified using values from TErrorControlStrength (EFecStrengthNone, 
williamr@2
   667
						EFecStrengthLow, EFecStrengthNormal, EFecStrengthHigh), or with intermediate 
williamr@2
   668
						values between those constants."
williamr@2
   669
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   670
				- KErrNotSupported - The specified bit-rate cannot be supported. "
williamr@2
   671
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   672
	*/
williamr@2
   673
	virtual void SetErrorProtectionLevelL(TUint aLevel, TUint aBitrate, TUint aStrength) = 0;
williamr@2
   674
williamr@2
   675
	/**
williamr@2
   676
	Sets the expected or prevailing channel conditions for an unequal error protection level, in terms of 
williamr@2
   677
	expected packet loss rate. The video encoder can use this information to optimize the generated bitstream.
williamr@2
   678
williamr@2
   679
	@param	"aLevel"			"Error protection level number. This argument is ignored if unequal error 
williamr@2
   680
								protection is not in use."
williamr@2
   681
	@param	"aLossRate"			"Packet loss rate, in number of packets lost per second. Set to 0.0 if
williamr@2
   682
								packet losses are not expected."
williamr@2
   683
	@param	"aLossBurstLength"	"Expected average packet loss burst length. Set to zero if the information is 
williamr@2
   684
								not available."
williamr@2
   685
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   686
	*/
williamr@2
   687
	virtual void SetChannelPacketLossRate(TUint aLevel, 
williamr@2
   688
										  TReal aLossRate, 
williamr@2
   689
										  TTimeIntervalMicroSeconds32 aLossBurstLength) = 0;
williamr@2
   690
williamr@2
   691
	/**
williamr@2
   692
	Sets the expected or prevailing channel conditions for an unequal error protection level, in terms of 
williamr@2
   693
	expected bit error rate. The video encoder can use this information to optimize the generated bitstream.
williamr@2
   694
williamr@2
   695
	@param	"aLevel"		"Error protection level number. This argument is ignored if unequal error 
williamr@2
   696
							protection is not in use."
williamr@2
   697
	@param	"aErrorRate"	"Expected bit error rate, as a fraction of the total bits transmitted. Set 
williamr@2
   698
							to 0.0 if bit errors are not expected."
williamr@2
   699
	@param	"aStdDeviation"	"Expected bit error rate standard deviation."
williamr@2
   700
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   701
	*/
williamr@2
   702
	virtual void SetChannelBitErrorRate(TUint aLevel, TReal aErrorRate, TReal aStdDeviation) = 0;
williamr@2
   703
williamr@2
   704
	/**
williamr@2
   705
	Sets the target size of each coded video segment. The segment target size can be specified in terms of 
williamr@2
   706
	number of bytes per segment, number of macroblocks per segment, or both.
williamr@2
   707
williamr@2
   708
	@param	"aLayer"			"Layer number. Layers are numbered [0...n-1], where n is the number of 
williamr@2
   709
								layers available. Use zero if layered bit-rate scalability is not used."
williamr@2
   710
	@param	"aSizeBytes"		"Segment target size in bytes. Set to zero to use unlimited segment size. The
williamr@2
   711
								segment size in bytes should include all data that is typically stored or
williamr@2
   712
								transmitted for each segment in the format currently in use. This includes all
williamr@2
   713
								related headers."
williamr@2
   714
	@param	"aSizeMacroblocks"	"Segment target size in number of macroblocks per segment. Set to zero to
williamr@2
   715
								use unlimited segment size."
williamr@2
   716
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   717
	*/
williamr@2
   718
	virtual void SetSegmentTargetSize(TUint aLayer, TUint aSizeBytes, TUint aSizeMacroblocks) = 0;
williamr@2
   719
williamr@2
   720
	/**
williamr@2
   721
	Sets the bit-rate control options for a layer. If layered bit-rate scalability is not used, the options
williamr@2
   722
	are set for the whole bitstream.
williamr@2
   723
williamr@2
   724
	@param	"aLayer"	"Layer number. Layers are numbered [0...n-1], where n is the number of layers 
williamr@2
   725
						available. Use zero if layered bit-rate scalability is not used."
williamr@2
   726
	@param	"aOptions"	"Bit-rate control options."
williamr@2
   727
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   728
	*/
williamr@2
   729
	virtual void SetRateControlOptions(TUint aLayer, const TRateControlOptions& aOptions) = 0;
williamr@2
   730
williamr@2
   731
	/**
williamr@2
   732
	Sets in-layer scalability options for a layer. In-layer bit-rate scalability refers to techniques where
williamr@2
   733
	a specific part of a single-layer coded stream can be decoded correctly without decoding the leftover 
williamr@2
   734
	part. For example, B-pictures can be used for this. By default in-layer scalability is not used.
williamr@2
   735
williamr@2
   736
	@param	"aLayer"			"Layer number. Layers are numbered [0…n-1], where n is the number of layers
williamr@2
   737
								available. Use zero if layered bit-rate scalability is not used."
williamr@2
   738
	@param	"aNumSteps"			"The number of in-layer scalability steps to use. Set to one to disable 
williamr@2
   739
								in-layer scalability."
williamr@2
   740
	@param	"aScalabilityType"	"The scalability type to use."
williamr@2
   741
	@param	"aBitrateShare"		"Bit-rate share for each scalability step. The bit-rate shares are defined 
williamr@2
   742
								as fractions of total layer bit-rate, with the share for one layer being 
williamr@2
   743
								aBitrateShare[i]/sum(aBitrateShare). For example, to use 2/3 of the total
williamr@2
   744
								bitrate for the first layer and the remaining 1/3 for the second, the array
williamr@2
   745
								contents would be {2,1}."
williamr@2
   746
	@param	"aPictureShare"		"Picture rate share for each scalability step. The picture rate shares are 
williamr@2
   747
								defined similarly to the bit-rate shares. For example, a client wishing to
williamr@2
   748
								use two B-pictures between each pair of reference pictures should set the 
williamr@2
   749
								array contents to {1,2}."
williamr@2
   750
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   751
				- KErrNotSupported	- In-layer scalability is not supported.
williamr@2
   752
				- KErrArgument		- Some of the arguments are out of range. For example, it is not
williamr@2
   753
									  possible to use the specified in-layer scalability setup due to other 
williamr@2
   754
									  constraints (such as the maximum picture order delay)."
williamr@2
   755
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   756
	*/
williamr@2
   757
	virtual void SetInLayerScalabilityL(TUint aLayer, 
williamr@2
   758
										TUint aNumSteps,
williamr@2
   759
										TInLayerScalabilityType aScalabilityType,
williamr@2
   760
										const TArray<TUint>& aBitrateShare,
williamr@2
   761
										const TArray<TUint>& aPictureShare) = 0;
williamr@2
   762
williamr@2
   763
	/**
williamr@2
   764
	Sets the period for layer promotions points for a scalability layer. A layer promotion point is a 
williamr@2
   765
	picture where it is possible to start decoding this enhancement layer if only the lower layers were 
williamr@2
   766
	decoded earlier.
williamr@2
   767
williamr@2
   768
	@param	"aLayer"	"Layer number."
williamr@2
   769
	@param	"aPeriod"	"Layer promotion point period. A value of one signals that each picture should be a
williamr@2
   770
						layer promotion point, value two that there is one picture between each promotion
williamr@2
   771
						point etc."
williamr@2
   772
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   773
	*/
williamr@2
   774
	virtual void SetLayerPromotionPointPeriod(TUint aLayer, TUint aPeriod) = 0;
williamr@2
   775
williamr@2
   776
	/**
williamr@2
   777
	Returns coding-standard specific settings output from the encoder. The information can contain, for 
williamr@2
   778
	example, some bitstream headers that can change based on settings modified while encoding is in progress.
williamr@2
   779
williamr@2
   780
	@return	"Coding-standard specific initialization output. The data format is coding-standard specific 
williamr@2
   781
			and defined separately. The buffer is pushed to the cleanup stack, and the caller is responsible 
williamr@2
   782
			for deallocating it."
williamr@2
   783
	@leave	"The method will leave if an error occurs."
williamr@2
   784
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   785
	*/
williamr@2
   786
	virtual HBufC8* CodingStandardSpecificSettingsOutputLC() = 0;
williamr@2
   787
williamr@2
   788
	/**
williamr@2
   789
	Returns implementation-specific settings output from the encoder. The information can contain, for
williamr@2
   790
	example, some bitstream headers that can change based on settings modified while encoding is in progress.
williamr@2
   791
williamr@2
   792
	@return	"Implementation-specific initialization output. The data format is implementation-specific and 
williamr@2
   793
			defined separately by the encoder supplier. The buffer is pushed to the cleanup stack, and the
williamr@2
   794
			caller is responsible for deallocating it."
williamr@2
   795
	@leave	"The method will leave if an error occurs."
williamr@2
   796
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   797
	*/
williamr@2
   798
	virtual HBufC8* ImplementationSpecificSettingsOutputLC() = 0;
williamr@2
   799
williamr@2
   800
	/**
williamr@2
   801
	Requests the encoder to sends supplemental information in the bitstream. The information data format is 
williamr@2
   802
	coding-standard dependent. Only one supplemental information send request can be active at a time. This
williamr@2
   803
	variant encodes the information to the next possible picture.
williamr@2
   804
williamr@2
   805
	The client must be notified after then information has been sent by calling 
williamr@2
   806
	MMMFDevVideoRecordProxy::MdvrpSupplementalInfoSent().
williamr@2
   807
williamr@2
   808
	@param	"aData"	"Supplemental information data to send."
williamr@2
   809
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   810
				- KErrNotSupported - Supplemental information is not supported"
williamr@2
   811
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   812
	*/
williamr@2
   813
	virtual void SendSupplementalInfoL(const TDesC8& aData) = 0;
williamr@2
   814
williamr@2
   815
	/**
williamr@2
   816
	Requests the encoder to sends supplemental information in the bitstream. The information data format is
williamr@2
   817
	coding-standard dependent. Only one supplemental information send request can be active at a time. This
williamr@2
   818
	variant encodes the information to the picture specified.
williamr@2
   819
williamr@2
   820
	@param	"aData"			"Supplemental information data to send."
williamr@2
   821
	@param	"aTimestamp"	"Timestamp for the picture in which the supplemental information should be 
williamr@2
   822
							included. If a picture with the matching timestamp is never encoded, or the
williamr@2
   823
							timestamp is in the past, the supplemental information will not be sent."
williamr@2
   824
	@leave	"The method will leave if an error occurs. Typical error codes used:
williamr@2
   825
				- KErrNotSupported - Supplemental information is not supported"
williamr@2
   826
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   827
	*/
williamr@2
   828
	virtual void SendSupplementalInfoL(const TDesC8& aData, const TTimeIntervalMicroSeconds& aTimestamp) = 0;
williamr@2
   829
williamr@2
   830
	/**
williamr@2
   831
	Cancels the current supplemental information send request. The memory buffer reserved for supplemental 
williamr@2
   832
	information data can be reused or deallocated after the method returns.
williamr@2
   833
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   834
	*/
williamr@2
   835
	virtual void CancelSupplementalInfo() = 0;
williamr@2
   836
williamr@2
   837
	/**
williamr@2
   838
	Gets the current output buffer status. The information includes the number of free output buffers and 
williamr@2
   839
	the total size of free buffers in bytes.
williamr@2
   840
williamr@2
   841
	@param	"aNumFreeBuffers"	"Target for the number of free output buffers."
williamr@2
   842
	@param	"aTotalFreeBytes"	"Target for the total free buffer size in bytes."
williamr@2
   843
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   844
	*/
williamr@2
   845
	virtual void GetOutputBufferStatus(TUint& aNumFreeBuffers, TUint& aTotalFreeBytes) = 0;
williamr@2
   846
williamr@2
   847
	/**
williamr@2
   848
	Returns a used output buffer back to the encoder. The buffer can be reused or deallocated.
williamr@2
   849
williamr@2
   850
	@param	"aBuffer"	"The buffer to return."
williamr@2
   851
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   852
	*/
williamr@2
   853
	virtual void ReturnBuffer(TVideoOutputBuffer* aBuffer) = 0;
williamr@2
   854
williamr@2
   855
	/**
williamr@2
   856
	Indicates a picture loss to the encoder, without specifying the lost picture. The encoder can react 
williamr@2
   857
	to this by transmitting an intra-picture.
williamr@2
   858
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   859
	*/
williamr@2
   860
	virtual void PictureLoss() = 0;
williamr@2
   861
williamr@2
   862
	/**
williamr@2
   863
	Indicates to the encoder the pictures that have been lost. The encoder can react to this by
williamr@2
   864
	transmitting an intra-picture.
williamr@2
   865
	@param	"aPictures"	"Picture identifiers for the lost pictures."
williamr@2
   866
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   867
	*/
williamr@2
   868
	virtual void PictureLoss(const TArray<TPictureId>& aPictures) = 0;
williamr@2
   869
williamr@2
   870
	/**
williamr@2
   871
	Indicates a slice loss to the encoder.
williamr@2
   872
williamr@2
   873
	@param	"aFirstMacroblock"	"The first lost macroblock. The macroblocks are numbered such
williamr@2
   874
								that the macroblock in the upper left corner of the picture is considered 
williamr@2
   875
								macroblock number 1 and the number for each macroblock increases from left
williamr@2
   876
								to right and then from top to bottom in raster-scan order."
williamr@2
   877
	@param	"aNumMacroblocks"	"The number of macroblocks in the lost slice."
williamr@2
   878
	@param	"aPicture"			"The picture identified for the picture where the slice was lost. If the 
williamr@2
   879
								picture is not known, aPicture.iIdType is set to ENone."
williamr@2
   880
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   881
	*/
williamr@2
   882
	virtual void SliceLoss(TUint aFirstMacroblock, TUint aNumMacroblocks, const TPictureId& aPicture) = 0;
williamr@2
   883
williamr@2
   884
	/**
williamr@2
   885
	Sends a reference picture selection request to the encoder. The request is delivered as a 
williamr@2
   886
	coding-standard specific binary message. Reference picture selection can be used to select a previous
williamr@2
   887
	correctly transmitted picture to use as a reference in case later pictures have been lost.
williamr@2
   888
williamr@2
   889
	@param	"aSelectionData"	"The reference picture selection request message. The message format is 
williamr@2
   890
								coding-standard specific, and defined separately."
williamr@2
   891
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   892
	*/
williamr@2
   893
	virtual void ReferencePictureSelection(const TDesC8& aSelectionData) = 0;
williamr@2
   894
williamr@2
   895
protected:
williamr@2
   896
	/**
williamr@2
   897
	Constructor.
williamr@2
   898
	*/
williamr@2
   899
	IMPORT_C CMMFVideoEncodeHwDevice();
williamr@2
   900
williamr@2
   901
	/**
williamr@2
   902
	Set the proxy implementation to be used. Called just after the object is constructed.
williamr@2
   903
	@param	"aProxy"	"The proxy to use."
williamr@2
   904
	*/
williamr@2
   905
	virtual void SetProxy(MMMFDevVideoRecordProxy& aProxy) = 0;
williamr@2
   906
private:
williamr@2
   907
	TUid iDtor_ID_Key;
williamr@2
   908
	};
williamr@2
   909
williamr@2
   910
williamr@2
   911
/**
williamr@2
   912
CMMFVideoPreProcHwDevice is the MSL video pre-processor plug-in interface. All MSL video pre-processors 
williamr@2
   913
must implement this interface.
williamr@2
   914
@publishedAll
williamr@2
   915
@released
williamr@2
   916
*/
williamr@2
   917
class CMMFVideoPreProcHwDevice : public CMMFVideoRecordHwDevice
williamr@2
   918
	{
williamr@2
   919
public:
williamr@2
   920
	/**
williamr@2
   921
	Creates a new video pre-processor hardware device object, based on the implementation UID.
williamr@2
   922
	@param	"aUid"		"Pre-processor implementation UID."
williamr@2
   923
	@param	"aProxy"	"The proxy implementation to use."
williamr@2
   924
	@return	"A new CMMFVideoPreProcHwDevice object."
williamr@2
   925
	@leave	"This method will leave if an error occurs."
williamr@2
   926
	*/
williamr@2
   927
	IMPORT_C static CMMFVideoPreProcHwDevice* NewL(TUid aUid, MMMFDevVideoRecordProxy& aProxy);
williamr@2
   928
williamr@2
   929
	/**
williamr@2
   930
	Destructor.
williamr@2
   931
	*/
williamr@2
   932
	IMPORT_C virtual ~CMMFVideoPreProcHwDevice();
williamr@2
   933
williamr@2
   934
	/**
williamr@2
   935
	Sets the device output format. The picture size depends on the input data format and possible 
williamr@2
   936
	scaling performed.
williamr@2
   937
williamr@2
   938
	@param	"aFormat"	"The video format to use."
williamr@2
   939
	@leave	" The method will leave if an error occurs. Typical error codes used:
williamr@2
   940
				- KErrNotSupported - The format specified is not supported."
williamr@2
   941
	@pre	"This method can only be called before the hwdevice has been initialized with Initialize()."
williamr@2
   942
	*/
williamr@2
   943
	virtual void SetOutputFormatL(const TUncompressedVideoFormat& aFormat) = 0;
williamr@2
   944
williamr@2
   945
	/**
williamr@2
   946
	Sets the video encoder device that will receive data from this pre-processor. Pre-processed pictures 
williamr@2
   947
	will be written with WritePictureL() or through a custom interface, and the encoder will return used 
williamr@2
   948
	pictures using ReturnPicture().
williamr@2
   949
williamr@2
   950
	@param	"aDevice"	"The output encoder device to use."
williamr@2
   951
	@pre	"This method can only be called before the hwdevice has been initialized with Initialize()."
williamr@2
   952
	*/
williamr@2
   953
	virtual void SetOutputDevice(CMMFVideoEncodeHwDevice* aDevice) = 0;
williamr@2
   954
williamr@2
   955
	/**
williamr@2
   956
	Returns a used picture back to the pre-processor. Called by an encoder device when used as output 
williamr@2
   957
	device from a pre-processor.
williamr@2
   958
williamr@2
   959
	@param	"aPicture"	"The picture to return."
williamr@2
   960
	@pre	"This method can only be called after the hwdevice has been initialized with Initialize()."
williamr@2
   961
	*/
williamr@2
   962
	virtual void ReturnPicture(TVideoPicture* aPicture) = 0;
williamr@2
   963
williamr@2
   964
protected:
williamr@2
   965
	/**
williamr@2
   966
	Constructor.
williamr@2
   967
	*/
williamr@2
   968
	IMPORT_C CMMFVideoPreProcHwDevice();
williamr@2
   969
williamr@2
   970
	/**
williamr@2
   971
	Set the proxy implementation to be used. Called just after the object is constructed.
williamr@2
   972
	@param	"aProxy"	"The proxy to use."
williamr@2
   973
	*/
williamr@2
   974
	virtual void SetProxy(MMMFDevVideoRecordProxy& aProxy) = 0;
williamr@2
   975
private:
williamr@2
   976
	TUid iDtor_ID_Key;
williamr@2
   977
	};
williamr@2
   978
williamr@2
   979
#endif