Doxygen comments for used DirectShow methods.

Info was got from DirectShow SDK.



git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@22046 b3059339-0415-0410-9bf9-f77b7e298cf2

2 files changed, 969 insertions, 2 deletions

diff --git a/loader/dshow/cmediasample.c b/loader/dshow/cmediasample.c
index 3237a06f88..4444c65204 100644
--- a/loader/dshow/cmediasample.c
+++ b/loader/dshow/cmediasample.c
@@ -17,6 +17,18 @@
  */
 static const int SAFETY_ACEL = 1024;
 
+/**
+ * \brief IPin::QueryInternalConnections (retries pin's internal connections)
+ *
+ * \param[in]     This  pointer to IPin interface
+ * \param[out]    apPin Array that receives pins, internally connected to this
+ * \param[in,out] nPint Size of an array
+ *
+ * \return S_OK - success
+ * \return S_FALSE - pin rejects media type
+ * \return E_NOTIMPL - not implemented
+ *
+ */
 static long STDCALL CMediaSample_QueryInterface(IUnknown* This,
 						/* [in] */ const GUID* iid,
 						/* [iid_is][out] */ void **ppv)
@@ -39,6 +51,17 @@ static long STDCALL CMediaSample_QueryInterface(IUnknown* This,
     return E_NOINTERFACE;
 }
 
+/**
+ * \brief IUnknown::AddRef (increases reference counter for interface)
+ *
+ * \param[in]  This pointer to IUnknown class
+ *
+ * \return new value of reference counter
+ *
+ * \remarks
+ * Return value should be used only for debug purposes
+ *
+ */
 static long STDCALL CMediaSample_AddRef(IUnknown* This)
 {
     Debug printf("CMediaSample_AddRef(%p) called\n", This);
@@ -46,6 +69,12 @@ static long STDCALL CMediaSample_AddRef(IUnknown* This)
     return 0;
 }
 
+/**
+ * \brief CMediaSample destructor
+ *
+ * \param[in] This pointer to CMediaSample object
+ *
+ */
 void CMediaSample_Destroy(CMediaSample* This)
 {
 
@@ -57,6 +86,18 @@ void CMediaSample_Destroy(CMediaSample* This)
     free(This);
 }
 
+/**
+ * \brief IUnknown::Release (desreases reference counter for interface)
+ *
+ * \param[in]  This pointer to IUnknown class
+ *
+ * \return new value of reference counter
+ *
+ * \remarks
+ * When reference counter reaches zero calls destructor
+ * Return value should be used only for debug purposes
+ *
+ */
 static long STDCALL CMediaSample_Release(IUnknown* This)
 {
     CMediaSample* parent = (CMediaSample*)This;
@@ -71,6 +112,18 @@ static long STDCALL CMediaSample_Release(IUnknown* This)
     return 0;
 }
 
+/**
+ * \brief IMediaSample::GetPointer (retrieves a read/write pointer to the media sample's buffer)
+ *
+ * \param[in] This pointer to CMediaSample object
+ * \param[out] address of variable that receives pointer to sample's buffer
+ *
+ * \return S_OK success
+ * \return apropriate error otherwise 
+ *
+ * \note The calles should not free or reallocate buffer
+ *
+ */
 static HRESULT STDCALL CMediaSample_GetPointer(IMediaSample* This,
 					       /* [out] */ BYTE** ppBuffer)
 {
@@ -81,12 +134,35 @@ static HRESULT STDCALL CMediaSample_GetPointer(IMediaSample* This,
     return 0;
 }
 
+/**
+ * \brief IMediaSample::GetSize (retrieves a size of buffer in bytes)
+ *
+ * \param[in] This pointer to CMediaSample object
+ *
+ * \return size of buffer in bytes
+ *
+ */
 static long STDCALL CMediaSample_GetSize(IMediaSample * This)
 {
     Debug printf("CMediaSample_GetSize(%p) called -> %d\n", This, ((CMediaSample*) This)->size);
     return ((CMediaSample*) This)->size;
 }
 
+/**
+ * \brief IMediaSample::GetTime (retrieves a stream time at wich sample sould start and finish)
+ *
+ * \param[in] This pointer to CMediaSample object
+ * \param[out] pTimeStart pointer to variable that receives start time
+ * \param[out] pTimeEnd pointer to variable that receives end time
+ *
+ * \return S_OK success
+ * \return VFW_E_NO_STOP_TIME The sample has valid start time, but no stop time
+ * \return VFW_E_SAMPLE_TIME_NOT_SET The sample is not time-stamped 
+ *
+ * \remarks
+ * Both values are relative to stream time
+ *
+ */
 static HRESULT STDCALL CMediaSample_GetTime(IMediaSample * This,
 					    /* [out] */ REFERENCE_TIME *pTimeStart,
 					    /* [out] */ REFERENCE_TIME *pTimeEnd)
@@ -95,6 +171,22 @@ static HRESULT STDCALL CMediaSample_GetTime(IMediaSample * This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IMediaSample::SetTime (sets a stream time at wich sample sould start and finish)
+ *
+ * \param[in] This pointer to CMediaSample object
+ * \param[out] pTimeStart pointer to variable that contains start time
+ * \param[out] pTimeEnd pointer to variable that contains end time
+ *
+ * \return S_OK success
+ * \return apropriate error otherwise
+ *
+ * \remarks
+ * Both values are relative to stream time
+ * To invalidate the stream times set pTimeStart and pTimeEnd to NULL. this will cause
+ * IMEdiaSample::GetTime to return VFW_E_SAMPLE_TIME_NOT_SET
+ *
+ */
 static HRESULT STDCALL CMediaSample_SetTime(IMediaSample * This,
 					    /* [in] */ REFERENCE_TIME *pTimeStart,
 					    /* [in] */ REFERENCE_TIME *pTimeEnd)
@@ -103,6 +195,18 @@ static HRESULT STDCALL CMediaSample_SetTime(IMediaSample * This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IMediaSample::IsSyncPoint (determines if start of this sample is sync point)
+ *
+ * \param[in] This pointer to CMediaSample object
+ *
+ * \return S_OK start of this sample is sync point
+ * \return S_FALSE start of this sample is not sync point
+ *
+ * \remarks
+ * If bTemporalCompression of AM_MEDIA_TYPE is FALSE, all samples are sync points.
+ *
+ */
 static HRESULT STDCALL CMediaSample_IsSyncPoint(IMediaSample * This)
 {
     Debug printf("CMediaSample_IsSyncPoint(%p) called\n", This);
@@ -111,6 +215,16 @@ static HRESULT STDCALL CMediaSample_IsSyncPoint(IMediaSample * This)
     return 1;
 }
 
+/**
+ * \brief IMediaSample::SetSyncPoint (specifies if start of this sample is sync point)
+ *
+ * \param[in] This pointer to CMediaSample object
+ * \param[in] bIsSyncPoint specifies whether this is sync point or not
+ *
+ * \return S_OK success
+ * \return apropriate error code otherwise
+ *
+ */
 static HRESULT STDCALL CMediaSample_SetSyncPoint(IMediaSample * This,
 						 long bIsSyncPoint)
 {
@@ -119,6 +233,19 @@ static HRESULT STDCALL CMediaSample_SetSyncPoint(IMediaSample * This,
     return 0;
 }
 
+/**
+ * \brief IMediaSample::IsPreroll (determines if this sample is preroll sample)
+ *
+ * \param[in] This pointer to CMediaSample object
+ *
+ * \return S_OK if this sample is preroll sample
+ * \return S_FALSE if this sample is not preroll sample
+ *
+ * \remarks
+ * Preroll samples are processed but  not displayed. They are lokated in media stream
+ * before displayable samples.
+ *
+ */
 static HRESULT STDCALL CMediaSample_IsPreroll(IMediaSample * This)
 {
     Debug printf("CMediaSample_IsPreroll(%p) called\n", This);
@@ -129,6 +256,20 @@ static HRESULT STDCALL CMediaSample_IsPreroll(IMediaSample * This)
     return 1;//S_FALSE
 }
 
+/**
+ * \brief IMediaSample::SetPreroll (specifies if this sample is preroll sample)
+ *
+ * \param[in] This pointer to CMediaSample object
+ * \param[in] bIsPreroll specifies whether this sample is preroll sample or not
+ *
+ * \return S_OK success
+ * \return apropriate error code otherwise
+ *
+ * \remarks
+ * Preroll samples are processed but  not displayed. They are lokated in media stream
+ * before displayable samples.
+ *
+ */
 static HRESULT STDCALL CMediaSample_SetPreroll(IMediaSample * This,
 					       long bIsPreroll)
 {
@@ -137,12 +278,30 @@ static HRESULT STDCALL CMediaSample_SetPreroll(IMediaSample * This,
     return 0;
 }
 
+/**
+ * \brief IMediaSample::GetActualDataLength (retrieves the length of valid data in the buffer)
+ *
+ * \param[in] This pointer to CMediaSample object
+ *
+ * \return length of valid data in buffer in bytes
+ *
+ */
 static long STDCALL CMediaSample_GetActualDataLength(IMediaSample* This)
 {
     Debug printf("CMediaSample_GetActualDataLength(%p) called -> %d\n", This, ((CMediaSample*)This)->actual_size);
     return ((CMediaSample*)This)->actual_size;
 }
 
+/**
+ * \brief IMediaSample::SetActualDataLength (specifies the length of valid data in the buffer)
+ *
+ * \param[in] This pointer to CMediaSample object
+ * \param[in]  __MIDL_0010 length of data in sample in bytes
+ *
+ * \return S_OK success
+ * \return VFW_E_BUFFER_OVERFLOW length specified by parameter is larger than buffer size
+ *
+ */
 static HRESULT STDCALL CMediaSample_SetActualDataLength(IMediaSample* This,
 							long __MIDL_0010)
 {
@@ -163,6 +322,21 @@ static HRESULT STDCALL CMediaSample_SetActualDataLength(IMediaSample* This,
     return 0;
 }
 
+/**
+ * \brief IMediaSample::GetMediaType (retrieves media type, if it changed from previous sample)
+ *
+ * \param[in] This pointer to CMediaSample object
+ * \param[out] ppMediaType address of variable that receives pointer to AM_MEDIA_TYPE.
+ *
+ * \return S_OK success
+ * \return S_FALSE Media type was not changed from previous sample
+ * \return E_OUTOFMEMORY Insufficient memory
+ *
+ * \remarks
+ * If media type is not changed from previous sample, ppMediaType is null
+ * If method returns S_OK caller should free memory allocated for structure 
+ * including pbFormat block
+ */
 static HRESULT STDCALL CMediaSample_GetMediaType(IMediaSample* This,
 						 AM_MEDIA_TYPE** ppMediaType)
 {
@@ -186,6 +360,16 @@ static HRESULT STDCALL CMediaSample_GetMediaType(IMediaSample* This,
     return 0;
 }
 
+/**
+ * \brief IMediaType::SetMediaType (specifies media type for sample)
+ *
+ * \param[in] This pointer to CMediaSample object
+ * \param[in] pMediaType pointer to AM_MEDIA_TYPE specifies new media type
+ *
+ * \return S_OK success
+ * \return E_OUTOFMEMORY insufficient memory
+ *
+ */
 static HRESULT STDCALL CMediaSample_SetMediaType(IMediaSample * This,
 						 AM_MEDIA_TYPE *pMediaType)
 {
@@ -209,12 +393,37 @@ static HRESULT STDCALL CMediaSample_SetMediaType(IMediaSample * This,
     return 0;
 }
 
+/**
+ * \brief IMediaSample::IsDiscontinuity (determines if this sample represents data break 
+ *        in stream)
+ *
+ * \param[in] This pointer to CMediaSample object
+ *
+ * \return S_OK if this sample is break in data stream
+ * \return S_FALSE otherwise
+ *
+ * \remarks 
+ * Discontinuity occures when filter seeks to different place in the stream or when drops
+ * samples.
+ *
+ */
 static HRESULT STDCALL CMediaSample_IsDiscontinuity(IMediaSample * This)
 {
     Debug printf("CMediaSample_IsDiscontinuity(%p) called\n", This);
     return ((CMediaSample*) This)->isDiscontinuity;
 }
 
+/**
+ * \brief IMediaSample::IsDiscontinuity (specifies whether this sample represents data break 
+ *        in stream)
+ *
+ * \param[in] This pointer to CMediaSample object
+ * \param[in] bDiscontinuity if TRUE this sample represents discontinuity with previous sample
+ *
+ * \return S_OK success
+ * \return apropriate error code otherwise
+ *
+ */
 static HRESULT STDCALL CMediaSample_SetDiscontinuity(IMediaSample * This,
 						     long bDiscontinuity)
 {
@@ -223,6 +432,17 @@ static HRESULT STDCALL CMediaSample_SetDiscontinuity(IMediaSample * This,
     return 0;
 }
 
+/**
+ * \brief IMediaSample::GetMediaTime (retrieves the media times of this sample)
+ *
+ * \param[in] This pointer to CMediaSample object
+ * \param[out] pTimeStart pointer to variable that receives start time
+ * \param[out] pTimeEnd pointer to variable that receives end time
+ *
+ * \return S_OK success
+ * \return VFW_E_MEDIA_TIME_NOT_SET The sample is not time-stamped 
+ *
+ */
 static HRESULT STDCALL CMediaSample_GetMediaTime(IMediaSample * This,
 						 /* [out] */ LONGLONG *pTimeStart,
 						 /* [out] */ LONGLONG *pTimeEnd)
@@ -235,6 +455,20 @@ static HRESULT STDCALL CMediaSample_GetMediaTime(IMediaSample * This,
     return 0;
 }
 
+/**
+ * \brief IMediaSample::GetMediaTime (retrieves the media times of this sample)
+ *
+ * \param[in] This pointer to CMediaSample object
+ * \param[out] pTimeStart pointer to variable that specifies start time
+ * \param[out] pTimeEnd pointer to variable that specifies end time
+ *
+ * \return S_OK success
+ * \return apropriate error code otherwise
+ *
+ * \remarks
+ * To invalidate the media times set pTimeStart and pTimeEnd to NULL. this will cause
+ * IMEdiaSample::GetTime to return VFW_E_MEDIA_TIME_NOT_SET
+ */
 static HRESULT STDCALL CMediaSample_SetMediaTime(IMediaSample * This,
 						 /* [in] */ LONGLONG *pTimeStart,
 						 /* [in] */ LONGLONG *pTimeEnd)
@@ -247,7 +481,13 @@ static HRESULT STDCALL CMediaSample_SetMediaTime(IMediaSample * This,
     return 0;
 }
 
-// extension for direct memory write or decompressed data
+/**
+ * \brief CMediaSample::SetPointer (extension for direct memory write of decompressed data)
+ *
+ * \param[in] This pointer to CMediaSample object
+ * \param[in] pointer pointer to an external buffer to store data to
+ *
+ */
 static void CMediaSample_SetPointer(CMediaSample* This, char* pointer)
 {
     Debug printf("CMediaSample_SetPointer(%p) called  -> %p\n", This, pointer);
@@ -257,12 +497,27 @@ static void CMediaSample_SetPointer(CMediaSample* This, char* pointer)
 	This->block = This->own_block;
 }
 
+/**
+ * \brief CMediaSample::SetPointer (resets pointer to external buffer with internal one)
+ *
+ * \param[in] This pointer to CMediaSample object
+ *
+ */
 static void CMediaSample_ResetPointer(CMediaSample* This)
 {
     Debug printf("CMediaSample_ResetPointer(%p) called\n", This);
     This->block = This->own_block;
 }
 
+/**
+ * \brief CMediaSample constructor
+ *
+ * \param[in] allocator IMemallocator interface of allocator to use
+ * \param[in] _size size of internal buffer
+ *
+ * \return pointer to CMediaSample object of NULL if error occured
+ *
+ */
 CMediaSample* CMediaSampleCreate(IMemAllocator* allocator, int _size)
 {
     CMediaSample* This = (CMediaSample*) malloc(sizeof(CMediaSample));
diff --git a/loader/dshow/inputpin.c b/loader/dshow/inputpin.c
index 88aa19b372..7ad56669ac 100644
--- a/loader/dshow/inputpin.c
+++ b/loader/dshow/inputpin.c
@@ -30,6 +30,21 @@ typedef struct
     GUID interfaces[2];
 } CEnumPins;
 
+/**
+ * \brief IEnumPins:Next (retrives a specified number of pins )
+ *
+ * \param[in]  This pointer to CEnumPins object
+ * \param[in]  cMediaTypes number of pins to retrive
+ * \param[out] ppMediaTypes array of IPin interface pointers of size cMediaTypes
+ * \param[out] pcFetched address of variables that receives number of returned pins
+ *
+ * \return S_OK - success
+ * \return S_FALSE - did not return as meny pins as requested
+ * \return E_INVALIDARG Invalid argument
+ * \return E_POINTER Null pointer
+ * \return VFW_E_ENUM_OUT_OF_SYNC - filter's state has changed and is now inconsistent with enumerator
+ *
+ */
 static long STDCALL CEnumPins_Next(IEnumPins* This,
 				   /* [in] */ unsigned long cMediaTypes,
 				   /* [size_is][out] */ IPin** ppMediaTypes,
@@ -74,6 +89,17 @@ static long STDCALL CEnumPins_Next(IEnumPins* This,
     return 1;
 }
 
+/**
+ * \brief IEnumPins::Skip (skips over a specified number of pins)
+ *
+ * \param[in]  This pointer to CEnumPinss object
+ * \param[in]  cMediaTypes number of pins to skip
+ *
+ * \return S_OK - success
+ * \return S_FALSE - skipped past the end of the sequence
+ * \return VFW_E_ENUM_OUT_OF_SYNC - filter's state has changed and is now inconsistent with enumerator
+ *
+ */
 static long STDCALL CEnumPins_Skip(IEnumPins* This,
 				   /* [in] */ unsigned long cMediaTypes)
 {
@@ -81,6 +107,14 @@ static long STDCALL CEnumPins_Skip(IEnumPins* This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IEnumPins::Reset (resets enumeration sequence to beginning)
+ *
+ * \param[in]  This pointer to CEnumPins object
+ *
+ * \return S_OK - success
+ *
+ */
 static long STDCALL CEnumPins_Reset(IEnumPins* This)
 {
     Debug printf("CEnumPins_Reset(%p) called\n", This);
@@ -88,6 +122,19 @@ static long STDCALL CEnumPins_Reset(IEnumPins* This)
     return 0;
 }
 
+/**
+ * \brief IEnumPins::Clone (makes a copy of enumerator, returned object
+ *        starts at the same position as original)
+ *
+ * \param[in]  This pointer to CEnumPins object
+ * \param[out] ppEnum address of variable that receives pointer to IEnumPins interface
+ *
+ * \return S_OK - success
+ * \return E_OUTOFMEMRY - Insufficient memory
+ * \return E_POINTER - Null pointer
+ * \return VFW_E_ENUM_OUT_OF_SYNC - filter's state has changed and is now inconsistent with enumerator
+ *
+ */
 static long STDCALL CEnumPins_Clone(IEnumPins* This,
 				    /* [out] */ IEnumPins** ppEnum)
 {
@@ -95,6 +142,12 @@ static long STDCALL CEnumPins_Clone(IEnumPins* This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief CEnumPins destructor
+ *
+ * \param[in]  This pointer to CEnumPins object
+ *
+ */
 static void CEnumPins_Destroy(CEnumPins* This)
 {
     free(This->vt);
@@ -103,6 +156,15 @@ static void CEnumPins_Destroy(CEnumPins* This)
 
 IMPLEMENT_IUNKNOWN(CEnumPins)
 
+/**
+ * \brief CEnumPins constructor
+ *
+ * \param[in]  p first pin for enumerator
+ * \param[in]  pp second pin for enumerator
+ *
+ * \return pointer to CEnumPins object or NULL if error occured
+ *
+ */
 static CEnumPins* CEnumPinsCreate(IPin* p, IPin* pp)
 {
     CEnumPins* This = (CEnumPins*) malloc(sizeof(CEnumPins));
@@ -139,8 +201,26 @@ static CEnumPins* CEnumPinsCreate(IPin* p, IPin* pp)
 
 /***********
  * InputPin
+ *
+ * WARNING:
+ * This is implementation of OUTPUT pin in DirectShow's terms
+ *
  ***********/
 
+/**
+ * \brief IPin::Connect (connects pin to another pin)
+ *
+ * \param[in] This          pointer to IPin interface
+ * \param[in] pReceivePin   pointer to IPin interface of remote pin
+ * \param[in] pmt           suggested media type for link. Can be NULL (any media type)
+ *
+ * \return S_OK - success.
+ * \return VFW_E_ALREADY_CONNECTED - pin already connected
+ * \return VFW_E_NOT_STOPPED - filter is active
+ * \return VFW_E_TYPE_NOT_ACCEPT - type is not acceptable
+ * \return Apropriate error code otherwise.
+ *
+ */
 static long STDCALL CInputPin_Connect(IPin* This,
 				      /* [in] */ IPin* pReceivePin,
 				      /* [in] */ AM_MEDIA_TYPE* pmt)
@@ -149,6 +229,25 @@ static long STDCALL CInputPin_Connect(IPin* This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IPin::ReceiveConnection (accepts a connection from another pin)
+ *
+ * \param[in] This       pointer to IPin interface
+ * \param[in] pConnector connecting pin's IPin interface
+ * \param[in] pmt        suggested media type for connection
+ *
+ * \return S_OK - success
+ * \return E_POINTER - Null pointer
+ * \return VFW_E_ALREADY_CONNECTED - pin already connected
+ * \return VFW_E_NOT_STOPPED - filter is active
+ * \return VFW_E_TYPE_NOT_ACCEPT - type is not acceptable
+ *
+ * \note
+ * When returning S_OK method should also do the following:
+ *  - store media type and return the same type in IPin::ConnectionMediaType
+ *  - store pConnector and return it in IPin::ConnectedTo
+ *
+ */
 static long STDCALL CInputPin_ReceiveConnection(IPin* This,
 						/* [in] */ IPin* pConnector,
 						/* [in] */ const AM_MEDIA_TYPE *pmt)
@@ -157,12 +256,37 @@ static long STDCALL CInputPin_ReceiveConnection(IPin* This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IPin::Disconnect (accepts a connection from another pin)
+ *
+ * \param[in] This pointer to IPin interface
+ *
+ * \return S_OK - success
+ * \return S_FALSE - pin was not connected
+ * \return VFW_E_NOT_STOPPED - filter is active
+ *
+ * \note
+ *   To break connection you have to also call Disconnect on other pin
+ */
 static long STDCALL CInputPin_Disconnect(IPin* This)
 {
     Debug unimplemented("CInputPin_Disconnect", This);
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IPin::ConnectedTo (retrieves pointer to the connected pin, if such exist)
+ *
+ * \param[in]  This pointer to IPin interface
+ * \param[out] pPin pointer to remote pin's IPin interface
+ *
+ * \return S_OK - success
+ * \return E_POINTER - Null pointer
+ * \return VFW_E_NOT_CONNECTED - pin is not connected
+ *
+ * \note
+ * Caller must call Release on received IPin, when done
+ */
 static long STDCALL CInputPin_ConnectedTo(IPin* This,
 					  /* [out] */ IPin** pPin)
 {
@@ -170,6 +294,17 @@ static long STDCALL CInputPin_ConnectedTo(IPin* This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IPin::ConnectionMediaType (retrieves media type for connection, if such exist)
+ *
+ * \param[in]  This pointer to IPin interface
+ * \param[out] pmt pointer to AM_MEDIA_TYPE,  that receives connection media type
+ *
+ * \return S_OK - success
+ * \return E_POINTER - Null pointer
+ * \return VFW_E_NOT_CONNECTED - pin is not connected
+ *
+ */
 static long STDCALL CInputPin_ConnectionMediaType(IPin* This,
 						  /* [out] */ AM_MEDIA_TYPE *pmt)
 {
@@ -185,6 +320,19 @@ static long STDCALL CInputPin_ConnectionMediaType(IPin* This,
     return 0;
 }
 
+/**
+ * \brief IPin::QueryPinInfo (retrieves information about the pin)
+ *
+ * \param[in]  This  pointer to IPin interface
+ * \param[out] pInfo pointer to PIN_INFO structure, that receives pin info
+ *
+ * \return S_OK - success
+ * \return E_POINTER - Null pointer
+ *
+ * \note
+ * If pInfo->pFilter is not NULL, then caller must call Release on pInfo->pFilter when done
+ *
+ */
 static long STDCALL CInputPin_QueryPinInfo(IPin* This,
 					   /* [out] */ PIN_INFO *pInfo)
 {
@@ -197,6 +345,16 @@ static long STDCALL CInputPin_QueryPinInfo(IPin* This,
     return 0;
 }
 
+/**
+ * \brief IPin::QueryDirection (retrieves pin direction)
+ *
+ * \param[in]  This    pointer to IPin interface
+ * \param[out] pPinDir pointer to variable, that receives pin direction (PINDIR_INPUT,PINDIR_OUTPUT)
+ *
+ * \return S_OK - success
+ * \return E_POINTER - Null pointer
+ *
+ */
 static long STDCALL CInputPin_QueryDirection(IPin* This,
 					      /* [out] */ PIN_DIRECTION *pPinDir)
 {
@@ -205,6 +363,20 @@ static long STDCALL CInputPin_QueryDirection(IPin* This,
     return 0;
 }
 
+/**
+ * \brief IPin::QueryId (retrieves pin identificator)
+ *
+ * \param[in]  This pointer to IPin interface
+ * \param[out] Id   adress of variable, that receives string with pin's Id.
+ *
+ * \return S_OK - success
+ * \return E_OUTOFMEMORY - Insufficient memory
+ * \return E_POINTER     - Null pointer
+ *
+ * \note
+ * Pin's Id is not the same as pin's name
+ *
+ */
 static long STDCALL CInputPin_QueryId(IPin* This,
 				       /* [out] */ unsigned short* *Id)
 {
@@ -212,6 +384,16 @@ static long STDCALL CInputPin_QueryId(IPin* This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IPin::QueryAccept (determines can media type be accepted or not)
+ *
+ * \param[in] This  pointer to IPin interface
+ * \param[in] pmt   Media type to check
+ *
+ * \return S_OK - success
+ * \return S_FALSE - pin rejects media type
+ *
+ */
 static long STDCALL CInputPin_QueryAccept(IPin* This,
 					  /* [in] */ const AM_MEDIA_TYPE* pmt)
 {
@@ -219,6 +401,20 @@ static long STDCALL CInputPin_QueryAccept(IPin* This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IPin::EnumMediaTypes (enumerates the pin's preferred media types)
+ *
+ * \param[in] This  pointer to IPin interface
+ * \param[out] ppEnum adress of variable that receives pointer to IEnumMEdiaTypes interface
+ *
+ * \return S_OK - success
+ * \return E_OUTOFMEMORY - Insufficient memory
+ * \return E_POINTER     - Null pointer
+ *
+ * \note
+ * Caller must call Release on received interface when done
+ *
+ */
 static long STDCALL CInputPin_EnumMediaTypes(IPin* This,
 					     /* [out] */ IEnumMediaTypes** ppEnum)
 {
@@ -226,6 +422,18 @@ static long STDCALL CInputPin_EnumMediaTypes(IPin* This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IPin::QueryInternalConnections (retries pin's internal connections)
+ *
+ * \param[in]     This  pointer to IPin interface
+ * \param[out]    apPin Array that receives pins, internally connected to this
+ * \param[in,out] nPint Size of an array
+ *
+ * \return S_OK - success
+ * \return S_FALSE - pin rejects media type
+ * \return E_NOTIMPL - not implemented
+ *
+ */
 static long STDCALL CInputPin_QueryInternalConnections(IPin* This,
 						       /* [out] */ IPin** apPin,
 						       /* [out][in] */ unsigned long *nPin)
@@ -234,6 +442,22 @@ static long STDCALL CInputPin_QueryInternalConnections(IPin* This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IPin::EndOfStream (notifies pin, that no data is expected, until new run command)
+ *
+ * \param[in] This  pointer to IPin interface
+ *
+ * \return S_OK - success
+ * \return E_UNEXPECTED - The pin is output pin
+ *
+ * \note 
+ * IMemoryInputPin::Receive,IMemoryInputPin::ReceiveMultiple, IMemoryInputPin::EndOfStream, 
+ * IMemAllocator::GetBuffer runs in different (streaming) thread then other 
+ * methods (application thread).
+ * IMemoryInputPin::NewSegment runs either in streaming or application thread.
+ * Developer must use critical sections for thread-safing work.
+ *
+ */
 static long STDCALL CInputPin_EndOfStream(IPin * This)
 {
     Debug unimplemented("CInputPin_EndOfStream", This);
@@ -241,6 +465,15 @@ static long STDCALL CInputPin_EndOfStream(IPin * This)
 }
 
 
+/**
+ * \brief IPin::BeginFlush (begins a flush operation)
+ *
+ * \param[in] This  pointer to IPin interface
+ *
+ * \return S_OK - success
+ * \return E_UNEXPECTED - The pin is output pin
+ *
+ */
 static long STDCALL CInputPin_BeginFlush(IPin * This)
 {
     Debug unimplemented("CInputPin_BeginFlush", This);
@@ -248,12 +481,34 @@ static long STDCALL CInputPin_BeginFlush(IPin * This)
 }
 
 
+/**
+ * \brief IPin::EndFlush (ends a flush operation)
+ *
+ * \param[in] This  pointer to IPin interface
+ *
+ * \return S_OK - success
+ * \return E_UNEXPECTED - The pin is output pin
+ *
+ */
 static long STDCALL CInputPin_EndFlush(IPin* This)
 {
     Debug unimplemented("CInputPin_EndFlush", This);
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IPin::NewSegment (media sample received after this call grouped as segment with common
+ *        start,stop time and rate)
+ *
+ * \param[in] This   pointer to IPin interface
+ * \param[in] tStart start time of new segment
+ * \param[in] tStop  end time of new segment
+ * \param[in] dRate  rate at wich segment should be processed
+ *
+ * \return S_OK - success
+ * \return E_UNEXPECTED - The pin is output pin
+ *
+ */
 static long STDCALL CInputPin_NewSegment(IPin* This,
 					  /* [in] */ REFERENCE_TIME tStart,
 					  /* [in] */ REFERENCE_TIME tStop,
@@ -263,6 +518,12 @@ static long STDCALL CInputPin_NewSegment(IPin* This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief CInputPin destructor
+ *
+ * \param[in]  This pointer to CInputPin class
+ *
+ */
 static void CInputPin_Destroy(CInputPin* This)
 {
     free(This->vt);
@@ -271,6 +532,15 @@ static void CInputPin_Destroy(CInputPin* This)
 
 IMPLEMENT_IUNKNOWN(CInputPin)
 
+/**
+ * \brief CInputPin constructor
+ *
+ * \param[in]  amt media type for pin
+ *
+ * \return pointer to CInputPin if success
+ * \return NULL if error occured
+ *
+ */
 CInputPin* CInputPinCreate(CBaseFilter* p, const AM_MEDIA_TYPE* amt)
 {
     CInputPin* This = (CInputPin*) malloc(sizeof(CInputPin));
@@ -326,24 +596,84 @@ static long STDCALL CBaseFilter_GetClassID(IBaseFilter * This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IMediaFilter::Stop  (stops the filter)
+ *
+ * \param[in] This pointer to IBaseFilter interface
+ *
+ * \return S_OK success
+ * \return S_FALSE transition is not complete
+ *
+ * \remarks
+ * When filter is stopped it does onot deliver or process any samples and rejects any samples
+ * from upstream filter. 
+ * Transition may be asynchronous. In this case method should return S_FALSE.
+ * Method always sets filter's state to State_Stopped even if error occured.
+ *
+ */
 static long STDCALL CBaseFilter_Stop(IBaseFilter* This)
 {
     Debug unimplemented("CBaseFilter_Stop", This);
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IMediaFilter::Pause (pauses filter)
+ *
+ * \param[in] This pointer to IBaseFilter interface
+ *
+ * \return S_OK success
+ * \return S_FALSE transition is not complete
+ *
+ * \remarks
+ * When filter is paused it can receive, process and deliver samples.
+ * Live source filters do not deliver any samples while paused.
+ * Transition may be asynchronous. In this case method should return S_FALSE.
+ * Method always sets filter's state to State_Stopped even if error occured.
+ *
+ */
 static long STDCALL CBaseFilter_Pause(IBaseFilter* This)
 {
     Debug unimplemented("CBaseFilter_Pause", This);
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IMediaFilter::Run (runs the filter)
+ *
+ * \param[in] This pointer to IBaseFilter interface
+ * \param[in] tStart Reference time corresponding to stream time 0.
+ *
+ * \return S_OK success
+ * \return S_FALSE transition is not complete
+ *
+ * \remarks
+ * When filter is running it can receive, process and deliver samples. Source filters
+ * generatesnew  samples, and renderers renders them.
+ * Stream time is calculated as the current reference time minus tStart.
+ * Graph Manager sets tStart slightly in the future according to graph latency.
+ *
+ */
 static long STDCALL CBaseFilter_Run(IBaseFilter* This, REFERENCE_TIME tStart)
 {
     Debug unimplemented("CBaseFilter_Run", This);
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IMediaFilter::GetState (retrieves the filter's state (running, stopped or paused))
+ *
+ * \param[in] This pointer to IBaseFilter interface
+ * \param[in] dwMilliSecsTimeout Timeout interval in milliseconds. To block indifinitely pass
+ *            INFINITE.
+ * \param[out] State pointer to variable that receives a member of FILTER_STATE enumeration.
+ *
+ * \return S_OK success
+ * \return E_POINTER Null pointer
+ * \return VFW_S_STATE_INTERMEDATE Intermediate state
+ * \return VFW_S_CANT_CUE The filter is active, but cannot deliver data.
+ *
+ */
 static long STDCALL CBaseFilter_GetState(IBaseFilter* This,
 					 /* [in] */ unsigned long dwMilliSecsTimeout,
 					 // /* [out] */ FILTER_STATE *State)
@@ -353,6 +683,16 @@ static long STDCALL CBaseFilter_GetState(IBaseFilter* This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IMediaFilter::SetSyncSource (sets the reference clock)
+ *
+ * \param[in] This pointer to IBaseFilter interface
+ * \param[in] pClock IReferenceClock interface of reference clock
+ *
+ * \return S_OK success
+ * \return apripriate error otherwise
+ *
+ */
 static long STDCALL CBaseFilter_SetSyncSource(IBaseFilter* This,
 					      /* [in] */ IReferenceClock *pClock)
 {
@@ -360,6 +700,17 @@ static long STDCALL CBaseFilter_SetSyncSource(IBaseFilter* This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IMediafilter::GetSyncSource (gets current reference clock)
+ *
+ * \param[in] This pointer to IBaseFilter interface
+ * \param[out] pClock address of variable that receives pointer to clock's 
+ *  IReferenceClock interface 
+ *
+ * \return S_OK success
+ * \return E_POINTER Null pointer
+ *
+ */
 static long STDCALL CBaseFilter_GetSyncSource(IBaseFilter* This,
 					      /* [out] */ IReferenceClock **pClock)
 {
@@ -368,6 +719,17 @@ static long STDCALL CBaseFilter_GetSyncSource(IBaseFilter* This,
 }
 
 
+/**
+ * \brief IBaseFilter::EnumPins (enumerates the pins of this filter)
+ *
+ * \param[in] This pointer to IBaseFilter interface
+ * \param[out] ppEnum address of variable that receives pointer to IEnumPins interface
+ *
+ * \return S_OK success
+ * \return E_OUTOFMEMORY Insufficient memory
+ * \return E_POINTER Null pointer
+ *
+ */
 static long STDCALL CBaseFilter_EnumPins(IBaseFilter* This,
 					 /* [out] */ IEnumPins **ppEnum)
 {
@@ -376,6 +738,21 @@ static long STDCALL CBaseFilter_EnumPins(IBaseFilter* This,
     return 0;
 }
 
+/**
+ * \brief IBaseFilter::FindPin (retrieves the pin with specified id)
+ *
+ * \param[in] This pointer to IBaseFilter interface
+ * \param[in] Id  constant wide string, containing pin id
+ * \param[out] ppPin address of variable that receives pointer to pin's IPin interface
+ *
+ * \return S_OK success
+ * \return E_POINTER Null pointer
+ * \return VFW_E_NOT_FOUND Could not find a pin with specified id
+ *
+ * \note
+ * Be sure to release the interface after use.
+ *
+ */
 static long STDCALL CBaseFilter_FindPin(IBaseFilter* This,
 					/* [string][in] */ const unsigned short* Id,
 					/* [out] */ IPin **ppPin)
@@ -384,6 +761,19 @@ static long STDCALL CBaseFilter_FindPin(IBaseFilter* This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IBaseFilter::QueryFilterInfo (retrieves information aboud the filter)
+ *
+ * \param[in] This pointer to IBaseFilter interface
+ * \param[out] pInfo pointer to FILTER_INFO structure
+ *
+ * \return S_OK success
+ * \return E_POINTER Null pointer
+ *
+ * \note
+ * If pGraph member of FILTER_INFO is not NULL, be sure to release IFilterGraph interface after use.
+ *
+ */
 static long STDCALL CBaseFilter_QueryFilterInfo(IBaseFilter* This,
 						// /* [out] */ FILTER_INFO *pInfo)
 						void* pInfo)
@@ -392,6 +782,22 @@ static long STDCALL CBaseFilter_QueryFilterInfo(IBaseFilter* This,
     return E_NOTIMPL;
 }
 
+/**
+ * \brief IBaseFilter::JoinFilterGraph (notifies the filter that it has joined of left filter graph)
+ *
+ * \param[in] This pointer to IBaseFilter interface
+ * \param[in] pInfo pointer to graph's IFilterGraph interface or NULL if filter is leaving graph