Index Topic Contents | |||
Previous Topic: CSourceSeeking Class Next Topic: CSystemClock Class |
CSourceStream Class
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.
- 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.
- 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.
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. 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
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. CSourceStream Class
CSourceStream::ActiveStarts the worker thread.
HRESULT Active(void);
Return Values
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. CSourceStream Class
CSourceStream::CheckMediaTypeDetermines if this pin supports the supplied media type.
virtual HRESULT CheckMediaType(
CMediaType *pMediaType
);Parameters
- pMediaType
- Media type to check.
Return Values
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 Class
CSourceStream::CheckRequestDetermines if a command is waiting for the thread.
BOOL CheckRequest(
Command *pCom
);Parameters
- pCom
- Pointer to the location to which to return a command, if any.
Return Values
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 Class
CSourceStream::CSourceStreamCreates a CSourceStream object.
CSourceStream(
TCHAR *pObjectName,
HRESULT *phr,
CSource *pms,
LPCWSTR pName
);Parameters
- pObjectName
- Name of the object.
- phr
- Resulting value for this constructor.
- pms
- Pointer for the CSource object.
- pName
- Name of the pin.
Return Values
No return value.
CSourceStream Class
CSourceStream::DoBufferProcessingLoopLoops, collecting a buffer and calling the CSourceStream::FillBuffer processing function.
virtual HRESULT DoBufferProcessingLoop(void);
Return Values
Returns an HRESULT value.
CSourceStream Class
CSourceStream::ExitCauses the thread to exit.
HRESULT Exit(void);
Return Values
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 Class
CSourceStream::FillBufferFills the stream buffer during the creation of a media sample that the current pin provides.
virtual HRESULT FillBuffer(
IMediaSample *pSample
) PURE;Parameters
- pSample
- IMediaSample buffer to contain the data.
Return Values
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 Class
CSourceStream::GetMediaTypeFills out the fields of the CMediaType object to the supported media type.
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 Values
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. 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 Class
CSourceStream::GetRequestRetrieves the next command for the thread.
Command GetRequest(void);
Return Values
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 Class
CSourceStream::InactiveIdentifies a pin as inactive and shuts down the worker thread.
HRESULT Inactive(void);
Return Values
Returns an HRESULT value, including the following values.
Value Meaning S_OK Thread exited successfully. S_FALSE Pin is already inactive. CSourceStream Class
CSourceStream::InitInitializes the worker thread.
HRESULT Init(void);
Return Values
Returns an HRESULT value, including the following values.
Value Meaning S_OK Thread was initialized successfully. S_FALSE Thread was already initialized. Remarks
The CSourceStream::Active member function calls this member function.
CSourceStream Class
CSourceStream::OnThreadCreateStarts or stops a process upon the creation of a thread.
virtual HRESULT OnThreadCreate(void);
Return Values
Returns an HRESULT value, including the following values.
Value Meaning NOERROR No error occurred. Error code Thread should exit. CSourceStream Class
CSourceStream::OnThreadDestroyStarts or stops a process upon the destruction of a thread.
virtual HRESULT OnThreadDestroy(void);
Return Values
Returns either NOERROR or an HRESULT value (greater than zero) that indicates an error.
CSourceStream Class
CSourceStream::OnThreadStartPlayStarts a process upon the beginning of the playing of the thread.
virtual HRESULT OnThreadStartPlay(void);
Return Values
Default implementation returns NOERROR.
CSourceStream Class
CSourceStream::PausePauses a media sample stream.
HRESULT Pause(void);
Return Values
Returns an HRESULT value, including the following value.
Value Meaning S_OK Thread paused successfully. CSourceStream Class
CSourceStream::RunStarts a media sample stream.
HRESULT Run(void);
Return Values
Returns S_OK if successful; otherwise, returns an HRESULT error value.
CSourceStream Class
CSourceStream::StopStops a media sample stream.
HRESULT Stop(void);
Return Values
Returns S_OK if successful; otherwise, returns an HRESULT error value.
CSourceStream Class
CSourceStream::ThreadProcImplements the thread procedure.
virtual DWORD ThreadProc(void);
Return Values
Returns 0 if the thread completed successfully and 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.
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.