epoc32/include/mmf/server/mmfswcodecwrapper.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
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 __MMFSWCODECWRAPPER_H__
williamr@2
    17
#define __MMFSWCODECWRAPPER_H__
williamr@2
    18
williamr@2
    19
#include <mmf/server/mmfhwdevice.h>
williamr@2
    20
#include <mmf/server/mmfhwdevicesetup.h>
williamr@2
    21
williamr@2
    22
class CMMFSwCodecDataPath; //forward reference
williamr@2
    23
williamr@2
    24
/** 
williamr@2
    25
@publishedAll
williamr@2
    26
@released
williamr@2
    27
williamr@2
    28
Class for a software codec used by the CMMFSwCodecWrapper class to make the CMMFSwCodec a 
williamr@2
    29
CMMFHwDevice plugin. The CMMFSwCodec processes source data in a certain fourCC coding type and
williamr@2
    30
converts it to a destination buffer of another fourCC coding type.
williamr@2
    31
williamr@2
    32
A CMMFSwCodec object would usually not be instantiated directly
williamr@2
    33
but instead would be instantiated via the CMMFSwCodecWrapper class's Codec()
williamr@2
    34
method.
williamr@2
    35
williamr@2
    36
The processing of the data is handled by the codecs ProcessL() member.
williamr@2
    37
The intention is that the source buffer for conversion is converted to the appropriate coding type
williamr@2
    38
in the destination buffer.  The size of the buffers passed in are determined by SourceBufferSize()
williamr@2
    39
and SinkBufferSize() methods.  The buffer sizes should be chosen such that
williamr@2
    40
the ProcessL() method can be guaranteed to have enough destination buffer to
williamr@2
    41
completely process one source buffer.
williamr@2
    42
williamr@2
    43
The ProcessL should return a TCodecProcessResult returning the number of source bytes processed
williamr@2
    44
and the number of destination bytes processed along with a process result code defined thus:
williamr@2
    45
- EProcessComplete: the codec processed all the source data into the sink buffer
williamr@2
    46
- EProcessIncomplete: the codec filled sink buffer before all the source buffer was processed
williamr@2
    47
- EDstNotFilled: the codec processed the source buffer but the sink buffer was not filled
williamr@2
    48
- EEndOfData: the codec detected the end data - all source data in processed but sink may not be full
williamr@2
    49
- EProcessError: the codec process error condition
williamr@2
    50
williamr@2
    51
Unlike the 7.0s CMMFCodec::ProcessL method, the CMMFSwCodec::ProcessL method
williamr@2
    52
should not return EProcessIncomplete as this case is not handled by the
williamr@2
    53
CMMFSwCodecWrapper.
williamr@2
    54
*/
williamr@2
    55
class CMMFSwCodec : public CBase
williamr@2
    56
	{
williamr@2
    57
public:
williamr@2
    58
	/**
williamr@2
    59
	@publishedAll
williamr@2
    60
	@released
williamr@2
    61
williamr@2
    62
	Indicates the result of processing data from the source buffer to a destination buffer
williamr@2
    63
	and provides functions to compare the result code.
williamr@2
    64
	The CMMFSwCodec buffer sizes should be set to return EProcessComplete
williamr@2
    65
	The other return codes are to keep the ProcessL method compatible with
williamr@2
    66
	the 7.0s CMMFCodec API.
williamr@2
    67
	*/
williamr@2
    68
	class TCodecProcessResult
williamr@2
    69
		{
williamr@2
    70
	public:
williamr@2
    71
		/**
williamr@2
    72
		Flag to track the codec's processing status.
williamr@2
    73
		*/
williamr@2
    74
		enum TCodecProcessResultStatus
williamr@2
    75
			{
williamr@2
    76
			/** The codec has successfully completed its processing. */
williamr@2
    77
			EProcessComplete,
williamr@2
    78
			/** Could not empty the source buffer because the destination buffer became full. */
williamr@2
    79
			EProcessIncomplete,
williamr@2
    80
			/** Codec came across an end of data. */
williamr@2
    81
			EEndOfData,
williamr@2
    82
			/** Could not fill the destination buffer because the source buffer has been emptied. */
williamr@2
    83
			EDstNotFilled,
williamr@2
    84
			/** An error occured. */
williamr@2
    85
			EProcessError
williamr@2
    86
			};
williamr@2
    87
williamr@2
    88
		/** Overloaded operator to test equality. */
williamr@2
    89
		TBool operator==(const TCodecProcessResultStatus aStatus) const {return (iCodecProcessStatus == aStatus);}
williamr@2
    90
		/** Overloaded operator to test inequality. */
williamr@2
    91
		TBool operator!=(const TCodecProcessResultStatus aStatus) const {return (iCodecProcessStatus != aStatus);}
williamr@2
    92
williamr@2
    93
		/**
williamr@2
    94
		Default constructor.
williamr@2
    95
		*/
williamr@2
    96
		TCodecProcessResult()
williamr@2
    97
			:iCodecProcessStatus(EProcessError), iSrcBytesProcessed(0), iDstBytesAdded(0) {};
williamr@2
    98
williamr@2
    99
		public:
williamr@2
   100
		/**
williamr@2
   101
		The codec's processing status
williamr@2
   102
williamr@2
   103
		@see enum TCodecProcessResultStatus
williamr@2
   104
		*/
williamr@2
   105
		TCodecProcessResultStatus iCodecProcessStatus;
williamr@2
   106
williamr@2
   107
		/** The number of source bytes processed */
williamr@2
   108
		TUint iSrcBytesProcessed;
williamr@2
   109
williamr@2
   110
		/** The number of bytes added to the destination buffer */
williamr@2
   111
		TUint iDstBytesAdded;
williamr@2
   112
		};
williamr@2
   113
public:
williamr@2
   114
williamr@2
   115
	/**
williamr@2
   116
	Processes the data in the specified source buffer and writes the processed data to
williamr@2
   117
	the specified destination buffer.
williamr@2
   118
williamr@2
   119
	This function is synchronous, when the function returns the data has been processed.
williamr@2
   120
	This is a virtual function that each derived class must implement.
williamr@2
   121
williamr@2
   122
	@param	aSource
williamr@2
   123
			The source buffer containing data to encode or decode.
williamr@2
   124
	@param	aDest
williamr@2
   125
	 		The destination buffer to hold the data after encoding or decoding.
williamr@2
   126
williamr@2
   127
	@return	The result of the processing.
williamr@2
   128
williamr@2
   129
	@see    TCodecProcessResult
williamr@2
   130
	*/
williamr@2
   131
	virtual TCodecProcessResult ProcessL(const CMMFBuffer& aSource, CMMFBuffer& aDest) = 0;
williamr@2
   132
williamr@2
   133
	/**
williamr@2
   134
	Gets the max size of the source buffer passed into the
williamr@2
   135
	CMMFSwCodec::ProcessL function. 
williamr@2
   136
williamr@2
   137
	Note that this means that this is the Max size of each buffer passed to the codec.  The actual 
williamr@2
   138
	size of the data could be less than the max size. This is a virtual function that each derived 
williamr@2
   139
	class must implement.
williamr@2
   140
williamr@2
   141
	@return The max size of the source buffer in bytes.
williamr@2
   142
	*/
williamr@2
   143
	virtual TUint SourceBufferSize() = 0;
williamr@2
   144
williamr@2
   145
	/**
williamr@2
   146
	Gets the max size of the sink (destination) buffer passed into the
williamr@2
   147
	CMMFSwCodec::ProcessL method.  
williamr@2
   148
williamr@2
   149
	Note that this means that this is the Max size of each buffer passed to the codec.  The actual 
williamr@2
   150
	size of the data written to this buffer could be less than the max size. This is a virtual 
williamr@2
   151
	function that each derived class must implement.
williamr@2
   152
williamr@2
   153
	@return The max size of the sink buffer in bytes.
williamr@2
   154
	*/
williamr@2
   155
	virtual TUint SinkBufferSize() = 0;
williamr@2
   156
williamr@2
   157
	/**
williamr@2
   158
	@internalAll
williamr@2
   159
williamr@2
   160
	Function that needs to be overriden if the codec is a 'Null' codec
williamr@2
   161
	ie. it does not perform any data type transformation.  The 'Null' codec
williamr@2
   162
	should override this to return ETrue and provide a dummy
williamr@2
   163
	ProcessL. The CMMFSwCodecWrapper will then use the same buffer
williamr@2
   164
	for both the source and the sink. Null codecs should return the same
williamr@2
   165
	buffer size for both the Source and SinkBufferSize methods.
williamr@2
   166
	Since most CMMFSwCodec implementations will not be null codecs
williamr@2
   167
	this method can be ignored.
williamr@2
   168
williamr@2
   169
	Would not normally expect 3rd parties to have to implement this.
williamr@2
   170
	*/
williamr@2
   171
	virtual TBool IsNullCodec() {return EFalse;};
williamr@2
   172
	};
williamr@2
   173
williamr@2
   174
/** 
williamr@2
   175
@publishedAll
williamr@2
   176
@released
williamr@2
   177
williamr@2
   178
Class to make a CMMFSwCodec into a CMMFHwDevice ECOM plugin.
williamr@2
   179
williamr@2
   180
Most of the code to make a CMMFSwCodec into a CMMFHwDevice ECOM plugin is provided
williamr@2
   181
in CMMFSwCodecWrapper.  Someone writing a plugin derrived from CMMFSwCodecWrapper
williamr@2
   182
only needs to provide the standard ECOM implementation code, constructors
williamr@2
   183
and destructors and implement the Codec() function which should return the
williamr@2
   184
appropriate CMMFSwCodec.
williamr@2
   185
williamr@2
   186
Third parties using CMMFSwCodecWrapper that do not use the RMdaDevSound API
williamr@2
   187
to talk to the sound drivers would need to port the datapaths for their own
williamr@2
   188
sound drivers. Third parties would also need to change the custom interfaces
williamr@2
   189
where necessary.
williamr@2
   190
*/
williamr@2
   191
class CMMFSwCodecWrapper : public CMMFHwDevice
williamr@2
   192
	{
williamr@2
   193
public:
williamr@2
   194
	IMPORT_C virtual ~CMMFSwCodecWrapper();
williamr@2
   195
protected:
williamr@2
   196
	IMPORT_C CMMFSwCodecWrapper();
williamr@2
   197
	IMPORT_C virtual TInt Init(THwDeviceInitParams &aDevInfo);
williamr@2
   198
	IMPORT_C virtual TInt Start(TDeviceFunc aFuncCmd, TDeviceFlow aFlowCmd);
williamr@2
   199
	IMPORT_C virtual TInt Stop();
williamr@2
   200
	IMPORT_C virtual TInt Pause();
williamr@2
   201
	IMPORT_C virtual TAny* CustomInterface(TUid aInterfaceId);
williamr@2
   202
	IMPORT_C virtual TInt ThisHwBufferFilled(CMMFBuffer& aFillBufferPtr);
williamr@2
   203
	IMPORT_C virtual TInt ThisHwBufferEmptied(CMMFBuffer& aBuffer);
williamr@2
   204
	IMPORT_C virtual TInt SetConfig(TTaskConfig& aConfig);
williamr@2
   205
	IMPORT_C virtual TInt StopAndDeleteCodec();
williamr@2
   206
	IMPORT_C virtual TInt DeleteCodec();
williamr@2
   207
	/**
williamr@2
   208
	This method must return the CMMFSwCodec used by the derived
williamr@2
   209
	CMMFSwCodecWrapper class.  The method should create the CMMFSwCodec
williamr@2
   210
	if it hasn't done so already.
williamr@2
   211
williamr@2
   212
	This is a virtual function that each derived class must implement.
williamr@2
   213
williamr@2
   214
	@return The CMMFSwCodec used by the derrived CMMFSwCodecWrapper
williamr@2
   215
	*/
williamr@2
   216
	virtual CMMFSwCodec& Codec() = 0;
williamr@2
   217
	IMPORT_C void SetVbrFlag();
williamr@2
   218
private:
williamr@2
   219
	TInt StartEncode();
williamr@2
   220
	TInt StartDecode();
williamr@2
   221
	TInt StartConvert();
williamr@2
   222
	
williamr@2
   223
protected: 
williamr@2
   224
	/** 
williamr@2
   225
	The software codec used
williamr@2
   226
	*/
williamr@2
   227
	CMMFSwCodec* iCodec;
williamr@2
   228
	
williamr@2
   229
	/** 
williamr@2
   230
	The source buffer for the codec
williamr@2
   231
	*/
williamr@2
   232
	CMMFDataBuffer* iSourceBuffer;
williamr@2
   233
	
williamr@2
   234
	/** 
williamr@2
   235
	The sink buffer for the codec
williamr@2
   236
	*/
williamr@2
   237
	CMMFDataBuffer* iSinkBuffer;
williamr@2
   238
	
williamr@2
   239
	/** 
williamr@2
   240
	The datapath used to transfer the data
williamr@2
   241
	*/
williamr@2
   242
	CMMFSwCodecDataPath* iDataPath;
williamr@2
   243
	
williamr@2
   244
	/** 
williamr@2
   245
	The play custom interface
williamr@2
   246
	*/
williamr@2
   247
	MPlayCustomInterface* iPlayCustomInterface;
williamr@2
   248
	
williamr@2
   249
	/** 
williamr@2
   250
	The record custom interface
williamr@2
   251
	*/
williamr@2
   252
	MRecordCustomInterface* iRecordCustomInterface;
williamr@2
   253
	
williamr@2
   254
	/** 
williamr@2
   255
	The buffer size of the sound device
williamr@2
   256
	*/
williamr@2
   257
	TUint iDeviceBufferSize;
williamr@2
   258
	
williamr@2
   259
	/**
williamr@2
   260
	The sample rate of the sound device
williamr@2
   261
	*/
williamr@2
   262
	TInt iSampleRate;
williamr@2
   263
williamr@2
   264
	/**
williamr@2
   265
	The number of channels of the sound device
williamr@2
   266
	*/
williamr@2
   267
	TInt iChannels;
williamr@2
   268
	};
williamr@2
   269
williamr@2
   270
#endif