Microsoft DirectX 8.0 |
Output pin for the CSource filter class.
Declaration: Source.h
For information on using this class, see CSource. This class inherits the CAMThread class, which provides a worker thread for streaming data from the pin. The CSourceStream class implements the following helper methods to send requests to the thread:
The first request to the thread must be Init. The Exit request terminates the thread. In practice, it is not necessary to call any of these methods directly, because the pin's Active and Inactive methods call them as needed.
The class also provides several "handler" methods:
These do nothing in the base class, but the derived class can override them.
Protected Member Variables | |
---|---|
m_pFilter | Pointer to the filter that contains this pin. |
Protected Methods | |
OnThreadCreate | Called when the streaming thread is initialized. Virtual. |
OnThreadDestroy | Called when the streaming thread is about to exit. Virtual. |
OnThreadStartPlay | Called at the start of the DoBufferProcessingLoop method. Virtual. |
Active | Notifies the pin that the filter is now active. |
Inactive | Notifies the pin that the filter is no longer active. |
GetRequest | Waits for the next thread request. |
CheckRequest | Checks if there is a thread request, without blocking. |
ThreadProc | Thread procedure. Virtual. |
DoBufferProcessingLoop | Generates media data and delivers it to the downstream input pin. Virtual. |
CheckMediaType | Determines if the pin accepts a specific media type. Virtual. |
GetMediaType | Retrieves a preferred media type. Virtual. |
Public Methods | |
CSourceStream | Constructor method. |
~CSourceStream | Destructor method. Virtual. |
Init | Initializes the streaming thread. |
Exit | Signals the streaming thread to exit. |
Run | Signals the streaming thread to run. |
Pause | Signals the streaming thread to become active. |
Stop | Signals the streaming thread to stop. |
Pure Virtual Methods | |
FillBuffer | Fills a media sample with data. |
IPin Methods | |
QueryId | Retrieves an identifier for the pin. |
Pointer to the filter that contains this pin.
Syntax
CSource *m_pFilter;
Notifies the pin that the filter is now active. Overrides the CBasePin::Active method. If the pin is connected, this method starts the streaming thread.
Syntax
HRESULT Active(void);
Return Value
Returns an HRESULT value. Possible values include those listed in the following table.
S_FALSE Pin is already active. S_OK Success. E_FAIL Could not start the thread.
Determines if the pin accepts a specific media type. Implements the pure virtual CBasePin::CheckMediaType method.
Syntax
virtual HRESULT CheckMediaType( CMediaType *pMediaType );
Parameters
- pMediaType
- Pointer to a CMediaType object that contains the proposed media type.
Return Value
Returns one of the HRESULT values shown in the following table.
S_OK This pin supports this media type. E_FAIL The pin does not support this media type.
Remarks
By default, the pin supports a single media type. This method retrieves the supported type by calling the single-parameter version of the GetMediaType method, and compares it to the proposed type. If your pin supports more than one media type, override this method.
Checks if there is a thread request, without blocking.
Syntax
BOOL CheckRequest( Command *pCom );
Parameters
- pCom
- Pointer to a variable that receives the value passed in the last call to the CAMThread::CallWorker method.
Return Value
Returns TRUE if there is a pending request, or FALSE otherwise.
Remarks
This method overrides the CAMThread::CheckRequest method to perform type-checking. The CSourceStream class defines the following enumerated type for the pCom parameter:
enum Command {CMD_INIT, CMD_PAUSE, CMD_RUN, CMD_STOP, CMD_EXIT};
Constructor method.
Syntax
CSourceStream( TCHAR *pObjectName, HRESULT *phr, CSource *pms, LPCWSTR pName );
Parameters
- pObjectName
- Pointer to a string containing the debug name of the pin.
- phr
- Pointer to a variable that receives an HRESULT value indicating the success or failure of the method. Initialize the value to S_OK before creating the object. The value is changed only if an error occurs.
- pms
- Pointer to the CSource filter that created this pin.
- pName
- Pointer to a string that contains the name of the pin.
Remarks
The string given in the pObjectName parameter is used strictly for debugging purposes. For more information, see CBaseObject.
The string given in the pName parameter is the name returned by the IPin::QueryPinInfo method. This name is not used for the pin identifier that the QueryId method returns. Instead, QueryId calculates a pin identifier based on the pin number. (Pin identifiers support graph persistence. For more information, see IPin::QueryId.)
Destructor method.
Syntax
~CSourceStream(void);
Generates media data and delivers it to the downstream input pin.
Syntax
virtual HRESULT DoBufferProcessingLoop(void);
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_FALSE Thread received a stop request. S_OK Stream ended, or downstream filter is not accepting samples.
Remarks
This method implements the main loop that processes data and delivers it downstream. Each time through the loop, the method retrieves an empty media sample from the allocator. It passes the sample to the FillBuffer method. The FillBuffer methodwhich the derived class must implementthen generates media data and moves it into the sample buffer.
The loop ends when any of the following occurs:
- The input pin's IMemInputPin::Receive method rejects a sample.
- The FillBuffer method returns S_FALSE, indicating the end of the stream, or returns an error code.
- The thread receives a Stop request.
The DoBufferProcessingLoop method handles the end-of-stream notification. If an error occurs, it sends an EC_ERRORABORT event to the filter graph manager.
Signals the streaming thread to exit.
Syntax
HRESULT Exit(void);
Return Value
Returns S_OK or E_UNEXPECTED.
Remarks
The Inactive method calls this method.
Fills a media sample with data.
Syntax
virtual HRESULT FillBuffer( IMediaSample *pSample ) PURE;
Parameters
- pSample
- Pointer to the sample's IMediaSample interface.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_FALSE End of stream S_OK Success
Remarks
The derived class must implement this method.
The media sample given to this method has no time stamps. The derived class should call the IMediaSample::SetTime method to set the time stamps. If appropriate for the media type, the derived class should also set the media times, by calling the IMediaSample::SetMediaTime method. For more information, see Time and Clocks in DirectShow.
Retrieves a preferred media type.
Syntax
virtual HRESULT GetMediaType( int iPosition, CMediaType *pMediaType ); virtual HRESULT GetMediaType( CMediaType *pMediaType );
Parameters
- iPosition
- Zero-based index value.
- pMediaType
- Pointer to a CMediaType object that receives the media type.
Return Value
Returns one of the HRESULT values shown in the following table.
S_OK Success. VFW_S_NO_MORE_ITEMS Index out of range. E_INVALIDARG Index less than zero. E_UNEXPECTED Unexpected error.
Remarks
There are two versions of this method. One version overrides the CBasePin::GetMediaType method and takes an index value as a parameter. The other version is designed to retrieve a single media type, so it lacks the index parameter.
The single-parameter method returns E_UNEXPECTED. The two-parameter method checks that the iPosition parameter is 1, and then calls the single-parameter version. Depending on the number of media types the pin supports, you must override one of these methods:
- If the pin supports exactly one media type, override the single-parameter version. Fill in the media type that the pin supports.
- If the pin supports more than one media type, override the two-parameter version. Also override the CheckMediaType method.
Waits for the next thread request.
Syntax
Command GetRequest(void);
Return Value
Returns the next thread request.
Remarks
This method overrides the CAMThread::GetRequest method. The return value is cast to the following enumerated type:
enum Command {CMD_INIT, CMD_PAUSE, CMD_RUN, CMD_STOP, CMD_EXIT};
Notifies the pin that the filter is no longer active. Overrides the CBasePin::Inactive method. If the streaming thread is active, this method stops it and waits for the thread to exit.
Syntax
HRESULT Inactive(void);
Return Value
Returns S_OK or another HRESULT value.
Initializes the streaming thread.
Syntax
HRESULT Init(void);
Return Value
Returns S_OK, or another HRESULT value.
Remarks
This method must be the first thread request sent to the ThreadProc method. The Active method calls this method.
Called when the streaming thread is initialized.
Syntax
virtual HRESULT OnThreadCreate(void);
Return Value
Returns S_OK.
Remarks
The thread procedure, ThreadProc, calls this method when it first receives an Init request. The method does nothing in the base class. The derived class can override this method to perform thread initializations. If the derived class returns an error code, the thread exits with an error.
Called when the streaming thread is about to exit.
Syntax
virtual HRESULT OnThreadDestroy(void);
Return Value
Returns S_OK.
Remarks
The thread procedure, ThreadProc, calls this method before it exits. The method does nothing in the base class; it is available for the derived class to override. If the derived class returns an error code, the thread exits with an error.
Called at the start of the DoBufferProcessingLoop method.
Syntax
virtual HRESULT OnThreadStartPlay(void);
Return Value
Returns S_OK.
Remarks
This method does nothing in the base class; it is available for the derived class to override.
Signals the streaming thread to become active.
Syntax
HRESULT Pause(void);
Return Value
Returns S_OK or E_UNEXPECTED.
Remarks
The Active method calls this method. When the ThreadProc method receives this request, it calls the DoBufferProcessingLoop method.
Retrieves an identifier for the pin.
Syntax
HRESULT QueryId( LPWSTR *Id );
Parameters
- Id
- Pointer to a variable that receives a string containing the pin identifier.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL pointer argument. VFW_E_NOT_FOUND Pin was not found on the filter.
Remarks
This method implements the IPin::QueryId method. To construct an identifier string, the pin calls the CSource::FindPinNumber method with itself as the parameter. The FindPinNumber method returns the pin number, indexed from zero. QueryId increments the return value by one and converts the result to a string. For example, the first pin becomes "1"; the second pin becomes "2"; and so forth.
If this method returns VFW_E_NOT_FOUND, it indicates that the filter's array of pins is invalid, presumably caused by a bug in the filter.
Signals the streaming thread to run.
Syntax
HRESULT Run(void);
Return Value
Returns S_OK or E_UNEXPECTED.
Remarks
In the base class, this method has the same effect as the Pause request, and is not used.
Signals the streaming thread to stop.
Syntax
HRESULT Stop(void);
Return Value
Returns S_OK or E_UNEXPECTED.
Remarks
The Inactive method calls this method.
Thread procedure. Implements the pure virtual CAMThread::ThreadProc method.
Syntax
virtual DWORD ThreadProc(void);
Return Value
Returns 0 if the thread completed successfully or 1 otherwise. If the return value is 1, the thread's resources might still be allocated.
Remarks
This method waits indefinitely for thread requests, by calling the CAMThread::GetRequest method. If it receives a Run or Pause request, it calls the DoBufferProcessingLoop method. The DoBufferProcessingLoop method pushes data until it receives a Stop request. The thread procedure exits when it receives an Exit request.