Mercurial > mplayer.hg
changeset 22028:24dc4ec0d08d
Doxygen comments for used DirectShow methods.
Info was got from DirectShow SDK.
| author | voroshil |
|---|---|
| date | Sun, 28 Jan 2007 16:53:33 +0000 |
| parents | 0b262e00bc99 |
| children | 2fbe2debf5e6 |
| files | loader/dshow/cmediasample.c loader/dshow/inputpin.c |
| diffstat | 2 files changed, 969 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/loader/dshow/cmediasample.c Sun Jan 28 16:48:01 2007 +0000 +++ b/loader/dshow/cmediasample.c Sun Jan 28 16:53:33 2007 +0000 @@ -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 @@ 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 @@ return 0; } +/** + * \brief CMediaSample destructor + * + * \param[in] This pointer to CMediaSample object + * + */ void CMediaSample_Destroy(CMediaSample* This) { @@ -57,6 +86,18 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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));
--- a/loader/dshow/inputpin.c Sun Jan 28 16:48:01 2007 +0000 +++ b/loader/dshow/inputpin.c Sun Jan 28 16:53:33 2007 +0000 @@ -30,6 +30,21 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ /*********** * 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ } +/** + * \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 @@ } +/** + * \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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ } +/** + * \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 @@ 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 @@ 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 @@ 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 + * \param[in] pName pointer to wide character string that specifies a name for the filter + * + * \return S_OK success + * \return apropriate error code otherwise + * + * \remarks + * Filter should not call to graph's AddRef method. + * The IFilterGraph is guaranteed to be valid until graph manager calls this method again with + * the value NULL. + * + */ static long STDCALL CBaseFilter_JoinFilterGraph(IBaseFilter* This, /* [in] */ IFilterGraph* pGraph, /* [string][in] */ const unsigned short* pName) @@ -400,6 +806,20 @@ return E_NOTIMPL; } +/** + * \brief IBaseFilter::QueryVendorInfo (retrieves a string containing vendor info) + * + * \param[in] This pointer to IBaseFilter interface + * \param[out] address of variable that receives pointer to a string containing vendor info + * + * \return S_OK success + * \return E_POINTER Null pointer + * \return E_NOTIMPL Not implemented + * + * \remarks + * Call to CoTaskMemFree to free memory allocated for string + * + */ static long STDCALL CBaseFilter_QueryVendorInfo(IBaseFilter* This, /* [string][out] */ unsigned short** pVendorInfo) { @@ -407,16 +827,38 @@ return E_NOTIMPL; } +/** + * \brief CBaseFilter::GetPin (gets used pin) + * + * \param[in] This pointer to CBaseFilter object + * + * \return pointer to used pin's IPin interface + * + */ static IPin* CBaseFilter_GetPin(CBaseFilter* This) { return This->pin; } +/** + * \brief CBaseFilter::GetUnusedPin (gets used pin) + * + * \param[in] This pointer to CBaseFilter object + * + * \return pointer to unused pin's IPin interface + * + */ static IPin* CBaseFilter_GetUnusedPin(CBaseFilter* This) { return This->unused_pin; } +/** + * \brief CBaseFilter destructor + * + * \param[in] This pointer to CBaseFilter object + * + */ static void CBaseFilter_Destroy(CBaseFilter* This) { if (This->vt) @@ -430,6 +872,15 @@ IMPLEMENT_IUNKNOWN(CBaseFilter) +/** + * \brief CBaseFilter constructor + * + * \param[in] type Pointer to media type for connection + * \param[in] parent Pointer to parent CBaseFilter2 object + * + * \return pointer to CBaseFilter object or NULL if error occured + * + */ CBaseFilter* CBaseFilterCreate(const AM_MEDIA_TYPE* type, CBaseFilter2* parent) { CBaseFilter* This = (CBaseFilter*) malloc(sizeof(CBaseFilter)); @@ -486,18 +937,64 @@ 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 CBaseFilter2_Stop(IBaseFilter* This) { Debug unimplemented("CBaseFilter2_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 CBaseFilter2_Pause(IBaseFilter* This) { Debug unimplemented("CBaseFilter2_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 CBaseFilter2_Run(IBaseFilter* This, REFERENCE_TIME tStart) { Debug unimplemented("CBaseFilter2_Run", This); @@ -505,6 +1002,20 @@ } +/** + * \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 CBaseFilter2_GetState(IBaseFilter* This, /* [in] */ unsigned long dwMilliSecsTimeout, // /* [out] */ FILTER_STATE *State) @@ -514,6 +1025,16 @@ 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 CBaseFilter2_SetSyncSource(IBaseFilter* This, /* [in] */ IReferenceClock* pClock) { @@ -521,6 +1042,17 @@ 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 CBaseFilter2_GetSyncSource(IBaseFilter* This, /* [out] */ IReferenceClock** pClock) { @@ -528,6 +1060,17 @@ return E_NOTIMPL; } +/** + * \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 CBaseFilter2_EnumPins(IBaseFilter* This, /* [out] */ IEnumPins** ppEnum) { @@ -536,6 +1079,21 @@ 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 CBaseFilter2_FindPin(IBaseFilter* This, /* [string][in] */ const unsigned short* Id, /* [out] */ IPin** ppPin) @@ -544,6 +1102,19 @@ 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 CBaseFilter2_QueryFilterInfo(IBaseFilter* This, // /* [out] */ FILTER_INFO *pInfo) void* pInfo) @@ -552,6 +1123,22 @@ 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 + * \param[in] pName pointer to wide character string that specifies a name for the filter + * + * \return S_OK success + * \return apropriate error code otherwise + * + * \remarks + * Filter should not call to graph's AddRef method. + * The IFilterGraph is guaranteed to be valid until graph manager calls this method again with + * the value NULL. + * + */ static long STDCALL CBaseFilter2_JoinFilterGraph(IBaseFilter* This, /* [in] */ IFilterGraph* pGraph, /* [string][in] */ @@ -561,6 +1148,20 @@ return E_NOTIMPL; } +/** + * \brief IBaseFilter::QueryVendorInfo (retrieves a string containing vendor info) + * + * \param[in] This pointer to IBaseFilter interface + * \param[out] address of variable that receives pointer to a string containing vendor info + * + * \return S_OK success + * \return E_POINTER Null pointer + * \return E_NOTIMPL Not implemented + * + * \remarks + * Call to CoTaskMemFree to free memory allocated for string + * + */ static long STDCALL CBaseFilter2_QueryVendorInfo(IBaseFilter* This, /* [string][out] */ unsigned short** pVendorInfo) @@ -569,11 +1170,25 @@ return E_NOTIMPL; } +/** + * \brief CBaseFilter2::GetPin (gets used pin) + * + * \param[in] This pointer to CBaseFilter2 object + * + * \return pointer to used pin's IPin interface + * + */ static IPin* CBaseFilter2_GetPin(CBaseFilter2* This) { return This->pin; } +/** + * \brief CBaseFilter2 destructor + * + * \param[in] This pointer to CBaseFilter2 object + * + */ static void CBaseFilter2_Destroy(CBaseFilter2* This) { Debug printf("CBaseFilter2_Destroy(%p) called\n", This); @@ -588,11 +1203,19 @@ static GUID CBaseFilter2_interf1 = {0x76c61a30, 0xebe1, 0x11cf, {0x89, 0xf9, 0x00, 0xa0, 0xc9, 0x03, 0x49, 0xcb}}; +/// IID_IAMNetShowPreroll static GUID CBaseFilter2_interf2 = {0xaae7e4e2, 0x6388, 0x11d1, {0x8d, 0x93, 0x00, 0x60, 0x97, 0xc9, 0xa2, 0xb2}}; +/// IID_IAMRebuild static GUID CBaseFilter2_interf3 = {0x02ef04dd, 0x7580, 0x11d1, {0xbe, 0xce, 0x00, 0xc0, 0x4f, 0xb6, 0xe9, 0x37}}; +/** + * \brief CBaseFilter2 constructor + * + * \return pointer to CBaseFilter2 object or NULL if error occured + * + */ CBaseFilter2* CBaseFilter2Create() { CBaseFilter2* This = (CBaseFilter2*) malloc(sizeof(CBaseFilter2)); @@ -645,6 +1268,19 @@ *************/ +/** + * \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 CRemotePin_ConnectedTo(IPin* This, /* [out] */ IPin** pPin) { Debug printf("CRemotePin_ConnectedTo(%p) called\n", This); @@ -655,6 +1291,16 @@ 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 CRemotePin_QueryDirection(IPin* This, /* [out] */ PIN_DIRECTION* pPinDir) { @@ -665,12 +1311,36 @@ return 0; } +/** + * \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 CRemotePin_ConnectionMediaType(IPin* This, /* [out] */ AM_MEDIA_TYPE* pmt) { Debug unimplemented("CRemotePin_ConnectionMediaType", This); return E_NOTIMPL; } +/** + * \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 CRemotePin_QueryPinInfo(IPin* This, /* [out] */ PIN_INFO* pInfo) { CBaseFilter* lparent = ((CRemotePin*)This)->parent; @@ -682,6 +1352,12 @@ return 0; } +/** + * \brief CRemotePin destructor + * + * \param[in] This pointer to CRemotePin object + * + */ static void CRemotePin_Destroy(CRemotePin* This) { Debug printf("CRemotePin_Destroy(%p) called\n", This); @@ -691,6 +1367,15 @@ IMPLEMENT_IUNKNOWN(CRemotePin) +/** + * \brief CRemotePin constructor + * + * \param[in] pt parent filter + * \param[in] rpin remote pin + * + * \return pointer to CRemotePin or NULL if error occured + * + */ CRemotePin* CRemotePinCreate(CBaseFilter* pt, IPin* rpin) { CRemotePin* This = (CRemotePin*) malloc(sizeof(CRemotePin)); @@ -732,6 +1417,19 @@ *************/ +/** + * \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 CRemotePin2_QueryPinInfo(IPin* This, /* [out] */ PIN_INFO* pInfo) { @@ -744,7 +1442,13 @@ return 0; } -// FIXME - not being released! +/** + * \brief CremotePin2 destructor + * + * \param This pointer to CRemotePin2 object + * + * FIXME - not being released! + */ static void CRemotePin2_Destroy(CRemotePin2* This) { Debug printf("CRemotePin2_Destroy(%p) called\n", This); @@ -754,6 +1458,14 @@ IMPLEMENT_IUNKNOWN(CRemotePin2) +/** + * \brief CRemotePin2 contructor + * + * \param[in] p pointer to parent CBaseFilter2 object + * + * \return pointer to CRemotePin2 object or NULL if error occured + * + */ CRemotePin2* CRemotePin2Create(CBaseFilter2* p) { CRemotePin2* This = (CRemotePin2*) malloc(sizeof(CRemotePin2));