Derive from this class to provide a class that creates the data stream from one of the output pins. It should be used with an object that is derived from the CSource class derived object to provide the filter-level object.
The CSourceStream class creates a worker thread to push data downstream when the filter enters a paused or running state. The thread first calls the CSourceStream::OnThreadCreate member function. If this succeeds, it will loop, calling the CSourceStream::FillBuffer member function until the CSourceStream::Inactive member function stops it. As the thread quits, it calls the CSourceStream::OnThreadDestroy member function. If OnThreadCreate fails, OnThreadDestroy is called, and the active member function will fail.
To use the CSourceStream class, supporting a single media type, carry out the following steps.
To use the CSourceStream class, supporting multiple media types, carry out the following.
See SAMPLES\DS\BALL in the Microsoft® DirectShow™ SDK Software Development Kit (SDK) for an example of a pin supporting multiple types.
If you want more complex management of your worker thread, you can override most of the associated member functions. See Samples\DS\Vidcap in the Microsoft DirectX Media Software Development Kit (SDK) for an example.
Member Functions
| Name | Description |
| Active | Called by the CBaseMediaFilter class to start the worker thread. |
| CSourceStream | Constructs a CSourceStream object. |
| CheckRequest | Determines if a command is waiting for the thread. |
| Exit | Called by the CSourceStream::Inactive member function to exit the worker thread. |
| GetRequest | Retrieves the next command for the thread. |
| Inactive | Called by the CBaseMediaFilter member function to shut down the worker thread. |
| Init | Called by the CSourceStream::Active member function to initialize the worker thread. |
| Pause | Pauses the stream of the worker thread. This will acquire all necessary resources. |
| Run | Starts the worker thread generation of a media sample stream. |
| Stop | Stops the stream. |
Overridable Member Functions
| Name | Description |
| CheckMediaType | Determines if a specific media type is supported. Override this member function if you use multiple types. |
| DoBufferProcessingLoop | Loops, collecting a buffer and calling the CSourceStream::FillBuffer processing function. |
| FillBuffer | Override this member function to fill the stream buffer during the creation of a media sample. |
| GetMediaType | Retrieves the media type or types that this pin supports; override the appropriate version of this member function to support one or multiple media types. |
| OnThreadCreate | Called as the worker thread is created; override this member function for special processing. |
| OnThreadDestroy | Called during the destruction of a worker thread; override this member function for special processing. |
| OnThreadStartPlay | Called at the start of processing Pause or Run command; override this member function for special processing. |
| ThreadProc | Override this member function to create a custom thread procedure. |
Implemented IPin Methods
| Name | Description |
| QueryId | Retrieves an identifier for the pin. |
Starts the worker thread.
HRESULT Active(void);
Returns an HRESULT, which can be one of the following:
| Value | Meaning |
| E_FAIL | Thread could not start. |
| S_FALSE | Pin is already active. |
| S_OK | Thread was started successfully. |
Determines if this pin supports the supplied media type.
virtual HRESULT CheckMediaType(
CMediaType *pMediaType
);
Returns S_OK if the media type is supported, S_FALSE if it isn't, or E_INVALIDARG if pMediaType is invalid.
Override this member function if you support multiple media types. Test explicitly for S_OK to determine if this function succeeded; do not use the SUCCEEDED macro.
Determines if a command is waiting for the thread.
BOOL CheckRequest(
Command *pCom
);
Returns TRUE if the pCom parameter contains a command; otherwise, returns FALSE.
This member function does not block. This is a type safe override of the method in the CAMThread class.
Creates a CSourceStream object.
CSourceStream(
TCHAR *pObjectName,
HRESULT *phr,
CSource *pms,
LPCWSTR pName
);
No return value.
Loops, collecting a buffer and calling the CSourceStream::FillBuffer processing function.
virtual HRESULT DoBufferProcessingLoop(void);
Returns an HRESULT value.
Causes the thread to exit.
HRESULT Exit(void);
Returns NOERROR if the member function was received.
If the thread returns an error, it sets the return value of the CSourceStream::ThreadProc member function.
Fills the stream buffer during the creation of a media sample that the current pin provides.
virtual HRESULT FillBuffer(
IMediaSample *pSample
) PURE;
Returns an HRESULT value.
The CSourceStream::ThreadProc member function calls the CSourceStream::FillBuffer member function. The derived class must supply an implementation of this member function.
Fills out the fields of the CMediaType object to the supported media type.
virtual HRESULT GetMediaType(
int iPosition,
CMediaType *pMediaType
);
virtual HRESULT GetMediaType(
CMediaType *pMediaType
);
Returns one of the following HRESULT values.
| Value | Meaning |
| Error Code | Media type could not be set. |
| S_FALSE | Media type exists but is not currently usable. |
| S_OK | Media type was set. |
| VFW_S_NO_MORE_ITEMS | End of the list of media types has been reached. |
This member function sets the requested media type. If only a single media type is supported, override this member function with the single-parameter definition. Only the default implementations of the CSourceStream::CheckMediaType and CSourceStream::GetMediaType member functions call the single media type member function.
Override the single-version GetMediaType or the two-parameter version, CheckMediaType.
Retrieves the next command for the thread.
Command GetRequest(void);
Returns the next command.
This member function blocks until a command is available. It is a type safe override of the member function in the CAMThread class.
Identifies a pin as inactive and shuts down the worker thread.
HRESULT Inactive(void);
Returns an HRESULT value, including the following values.
| Value | Meaning |
| S_OK | Thread exited successfully. |
| S_FALSE | Pin is already inactive. |
Initializes the worker thread.
HRESULT Init(void);
Returns an HRESULT value, including the following values.
| Value | Meaning |
| S_OK | Thread was initialized successfully. |
| S_FALSE | Thread was already initialized. |
The CSourceStream::Active member function calls this member function.
Starts or stops a process upon the creation of a thread.
virtual HRESULT OnThreadCreate(void);
Returns an HRESULT value, including the following values.
| Value | Meaning |
| NOERROR | No error occurred. |
| Error code | Thread should exit. |
Starts or stops a process upon the destruction of a thread.
virtual HRESULT OnThreadDestroy(void);
Returns either NOERROR or an HRESULT value (greater than zero) that indicates an error.
Starts a process upon the beginning of the playing of the thread.
virtual HRESULT OnThreadStartPlay(void);
Default implementation returns NOERROR.
Pauses a media sample stream.
HRESULT Pause(void);
Returns an HRESULT value, including the following value.
| Value | Meaning |
| S_OK | Thread paused successfully. |
Starts a media sample stream.
HRESULT Run(void);
Returns S_OK if successful; otherwise, returns an HRESULT error value.
Stops a media sample stream.
HRESULT Stop(void);
Returns S_OK if successful; otherwise, returns an HRESULT error value.
Implements the thread procedure.
virtual DWORD ThreadProc(void);
Returns 0 if the thread completed successfully and 1 otherwise. If 1, the thread's resources might still be allocated.
When this member function returns, the thread exits. Override this member function if the provided version is not sophisticated enough.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.