CSourceStream Class

CSourceStream class hierarchy

Derive from the CSourceStream 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.

Override the CSourceStream::GetMediaType member function to report the supported output format.
Override the CSourceStream::FillBuffer member function with a means of filling out each IMediaSample object with data.

To use the CSourceStream class, supporting multiple media types, carry out the following steps.

Override the CSourceStream::CheckMediaType and CSourceStream::GetMediaType member functions to report the supported media types (for more information, see the CBaseMediaFilter class).
Override the CSourceStream::FillBuffer member function with a means of filling out each IMediaSample object with data.

For an example of a pin supporting multiple types, see the files in the Samples\Multimedia\DShow\Src\Ball subdirectory in the DirectX Media Software Development Kit (SDK).

If you want more complex management of your worker thread, you can override most of the associated member functions. For an example, see Samples\Multimedia\DShow\Src\Vidcap in the DirectX Media SDK.

Member Functions

Active Called by the CBaseMediaFilter class to start the worker thread.
CheckRequest Determines if a command is waiting for the thread.
CSourceStream Constructs a CSourceStream object.
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

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

QueryId Retrieves an identifier for the pin.

CSourceStream::Active

CSourceStream Class

Starts the worker thread.

Syntax

HRESULT Active(void);

Return Value

Returns an HRESULT, which can be one of the following:
E_FAIL Thread could not start.
S_FALSE Pin is already active.
S_OK Thread was started successfully.

CSourceStream::CheckMediaType

CSourceStream Class

Determines if this pin supports the supplied media type.

Syntax

virtual HRESULT CheckMediaType(
    CMediaType *pMediaType
    );

Parameters

pMediaType
Pointer to the media type to check.

Return Value

Returns S_OK if the media type is supported, S_FALSE if it isn't, or E_INVALIDARG if pMediaType is invalid.

Remarks

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.

CSourceStream::CheckRequest

CSourceStream Class

Determines if a command is waiting for the thread.

Syntax

BOOL CheckRequest(
    Command *pCom
    );

Parameters

pCom
Pointer to the location to which to return a command, if any.

Return Value

Returns TRUE if the pCom parameter contains a command; otherwise, returns FALSE.

Remarks

This member function does not block. This is a type safe override of the method in the CAMThread class.

CSourceStream::CSourceStream

CSourceStream Class

Creates a CSourceStream object.

Syntax

CSourceStream(
    TCHAR *pObjectName,
    HRESULT *phr,
    CSource *pms,
    LPCWSTR pName
    );

Parameters

pObjectName
Pointer to the name of the object.
phr
Pointer to the resulting value for this constructor.
pms
Pointer for the CSource object.
pName
Pointer to the name of the pin.

Return Value

No return value.

CSourceStream::DoBufferProcessingLoop

CSourceStream Class

Loops, collecting a buffer and calling the CSourceStream::FillBuffer processing function.

Syntax

virtual HRESULT DoBufferProcessingLoop(void);

Return Value

Returns an HRESULT value.

CSourceStream::Exit

CSourceStream Class

Causes the thread to exit.

Syntax

HRESULT Exit(void);

Return Value

Returns NOERROR if the member function was received.

Remarks

If the thread returns an error, it sets the return value of the CSourceStream::ThreadProc member function.

CSourceStream::FillBuffer

CSourceStream Class

Fills the stream buffer during the creation of a media sample that the current pin provides.

Syntax

virtual HRESULT FillBuffer(
    IMediaSample *pSample
    ) PURE;

Parameters

pSample
Pointer to the IMediaSample buffer to contain the data.

Return Value

Returns an HRESULT value.

Remarks

The CSourceStream::ThreadProc member function calls the CSourceStream::FillBuffer member function. The derived class must supply an implementation of this member function.

CSourceStream::GetMediaType

CSourceStream Class

Fills out the fields of the CMediaType object to the supported media type.

Syntax

virtual HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
    );

virtual HRESULT GetMediaType(
    CMediaType *pMediaType
    );

Parameters

iPosition
Position of the media type within a list of multiple media types. Range is zero through n.
pMediaType
Pointer to a CMediaType object to be set to the requested format.

Return Value

Returns one of the following HRESULT values.
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.

Remarks

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.

CSourceStream::GetRequest

CSourceStream Class

Retrieves the next command for the thread.

Syntax

Command GetRequest(void);

Return Value

Returns the next command.

Remarks

This member function blocks until a command is available. It is a type safe override of the member function in the CAMThread class.

CSourceStream::Inactive

CSourceStream Class

Identifies a pin as inactive and shuts down the worker thread.

Syntax

HRESULT Inactive(void);

Return Value

Returns an HRESULT value, including the following values.
S_OK Thread exited successfully.
S_FALSE Pin is already inactive.

CSourceStream::Init

CSourceStream Class

Initializes the worker thread.

Syntax

HRESULT Init(void);

Return Value

Returns an HRESULT value, including the following values.
S_OK Thread was initialized successfully.
S_FALSE Thread was already initialized.

Remarks

The CSourceStream::Active member function calls this member function.

CSourceStream::OnThreadCreate

CSourceStream Class

Starts or stops a process upon the creation of a thread.

Syntax

virtual HRESULT OnThreadCreate(void);

Return Value

Returns an HRESULT value, including the following values.
NOERROR No error occurred.
Error code Thread should exit.

CSourceStream::OnThreadDestroy

CSourceStream Class

Starts or stops a process upon the destruction of a thread.

Syntax

virtual HRESULT OnThreadDestroy(void);

Return Value

Returns either NOERROR or an HRESULT value (greater than zero) that indicates an error.

CSourceStream::OnThreadStartPlay

CSourceStream Class

Starts a process upon the beginning of the playing of the thread.

Syntax

virtual HRESULT OnThreadStartPlay(void);

Return Value

Default implementation returns NOERROR.

CSourceStream::Pause

CSourceStream Class

Pauses a media sample stream.

Syntax

HRESULT Pause(void);

Return Value

Returns S_OK if the thread paused successfully. Returns E_FAIL if the thread doesn't exist; otherwise, returns an HRESULT value describing the error.

CSourceStream::Run

CSourceStream Class

Starts a media sample stream.

Syntax

HRESULT Run(void);

Return Value

Returns S_OK if successful; otherwise, returns an HRESULT error value.

CSourceStream::Stop

CSourceStream Class

Stops a media sample stream.

Syntax

HRESULT Stop(void);

Return Value

Returns S_OK if successful; otherwise, returns an HRESULT error value.

CSourceStream::ThreadProc

CSourceStream Class

Implements the thread procedure.

Syntax

virtual DWORD ThreadProc(void);

Return Value

Returns 0 if the thread completed successfully or 1 otherwise. If 1, the thread's resources might still be allocated.

Remarks

When this member function returns, the thread exits. Override this member function if the provided version is not sophisticated enough.
See Samples\Multimedia\DShow\Src\Vidcap in the DirectX Media SDK for an example.

Active	Called by the CBaseMediaFilter class to start the worker thread.
CheckRequest	Determines if a command is waiting for the thread.
CSourceStream	Constructs a CSourceStream object.
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.

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.

E_FAIL	Thread could not start.
S_FALSE	Pin is already active.
S_OK	Thread was started successfully.

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.

S_OK	Thread exited successfully.
S_FALSE	Pin is already inactive.

S_OK	Thread was initialized successfully.
S_FALSE	Thread was already initialized.