Microsoft DirectX 8.0 |
Base class for implementing renderer filters. It supports one input pin, implemented by the CRendererInputPin class.
Declaration: Renbase.h
To use this class, declare a derived class that inherits CBaseRenderer. At a minimum, the derived class must implement the following methods, which are declared as pure virtual in the base class:
The base class handles state changes and synchronization issues. It also schedules samples for rendering, although it does not implement any quality-control measures.
The base class also declares several "handler" methods. These are methods that the filter calls at specific points in the streaming process. They do nothing in the base class, but the derived class can override them. In the table that follows, they are listed under the heading Public Methods: Handlers.
The OnReceiveFirstSample handler deserves special mention. The filter calls this method if it receives a sample while the filter is paused. That can occur if the graph switches from stopped to paused, or if the graph is seeked while paused. Video renderers typically use the sample to display a still frame. When the filter switches from paused to running, it sends the same sample to the DoRenderSample method, as the first sample in the stream.
Scheduling
When the upstream filter calls the input pin's IMemInputPin::Receive method to deliver a sample, the pin passes this call to the filter's Receive method. The filter either drops the sample, renders it immediately, or schedules it for rendering.
If the sample has no time stamps, or if no reference clock is available, the filter renders the sample immediately. Otherwise, the filter calls the ShouldDrawSampleNow method to determine what to do. By default, the sample is scheduled based on its time stamps. The derived class can override ShouldDrawSampleNow to support quality control.
To schedule a sample, the filter calls the IReferenceClock::AdviseTime method, which creates an advise request. The Receive method then blocks until the scheduled time, or until the filter changes state. Blocking prevents the upstream filter from delivering more samples until the current sample is rendered.
When the upstream filter calls the IPin::EndOfStream method to signal the end of the stream, the filter sends an EC_COMPLETE event to the filter graph manager. The filter waits for the current sample's stop time before sending the event.
Protected Member Variables | |
---|---|
m_bAbort | Flag that indicates whether to stop rendering and reject further samples. |
m_bEOS | Flag that indicates whether end-of-stream was reached. |
m_bEOSDelivered | Flag that indicates whether the filter has posted the EC_COMPLETE event. |
m_bInReceive | Flag that indicates whether the filter is processing a Receive call. |
m_bRepaintStatus | Flag that enables or disables repaint events. |
m_bStreaming | Flag that indicates whether the filter is streaming data. |
m_dwAdvise | Identifier of the timer event that schedules rendering. |
m_EndOfStreamTimer | Timer-event identifier, for scheduling EC_COMPLETE notifications. |
m_evComplete | Event that is signaled when a state transition is complete. |
m_InterfaceLock | Filter-state lock. |
m_pInputPin | Pointer to the filter's input pin. |
m_pMediaSample | Pointer to the current media sample. |
m_pPosition | Helper object to pass seek commands upstream. |
m_pQSink | Pointer to the object that receives quality-control messages. |
m_RendererLock | Streaming lock. |
m_RenderEvent | Event used to schedule rendering. |
m_SignalTime | Stop time on the current sample. |
m_ThreadSignal | Event used to release the streaming thread. |
Public Methods | |
CancelNotification | Cancels the timer event that schedules rendering. Virtual. |
CBaseRenderer | Constructor method. |
~CBaseRenderer | Destructor method. |
GetMediaPositionInterface | Retrieves the filter's IMediaPosition and IMediaSeeking interface pointers. Virtual. |
GetPin | Retrieves a pin. Virtual. |
GetPinCount | Retrieves the number of pins. Virtual. |
GetSampleTimes | Retrieves the time stamps from a sample. Virtual. |
OnDisplayChange | Posts an EC_DISPLAY_CHANGED event to the filter graph manager. |
PrepareReceive | Prepares to render a sample. Virtual. |
Receive | Receives the next media sample in the stream. Virtual. |
Render | Renders a sample. Virtual. |
ScheduleSample | Schedules a sample for rendering. Virtual. |
SendNotifyWindow | Notifies the upstream filter of the video window handle. |
SendRepaint | Sends a repaint event to the filter graph manager. |
SetMediaType | Called when the pin's media type is set. Virtual. |
SignalTimerFired | Clears the timer identifier used to schedule rendering. |
SourceThreadCanWait | Holds or releases the streaming thread. Virtual. |
WaitForReceiveToComplete | Waits for the Receive method to complete. |
WaitForRenderTime | Waits for the current sample's presentation time. Virtual. |
Public Methods: Accessor Methods | |
ClearPendingSample | Releases the current sample. Virtual. |
GetCurrentSample | Retrieves the current sample. Virtual. |
GetRealState | Retrieves the filter state. |
GetRenderEvent | Retrieves the event that schedules rendering. |
HaveCurrentSample | Determines whether the filter has a sample. Virtual. |
IsEndOfStream | Queries whether the end-of-stream notification was received. |
IsEndOfStreamDelivered | Queries whether the EC_COMPLETE event has been delivered to the filter graph manager. |
IsStreaming | Queries whether the filter is streaming data. |
SetAbortSignal | Sets the abort flag, which indicates whether to stop rendering and reject further samples. |
SetRepaintStatus | Enables or disables repaint events. |
Public Methods: State-Change Methods | |
Active | Called when the state is switched to paused or running. Virtual. |
BeginFlush | Begins a flush operation. Virtual. |
BreakConnect | Releases the input pin from a connection. Virtual. |
CheckReady | Queries whether a state transition is complete. |
CompleteConnect | Completes the input pin's connection to another pin. Virtual. |
CompleteStateChange | Determines whether a transition to the paused state is complete. Virtual. |
EndFlush | Ends a flush operation. Virtual. |
Inactive | Called when the state is switched to stopped. Virtual. |
NotReady | Signals that a state transition is not yet complete. |
Ready | Signals that a state transition is complete. |
StartStreaming | Initiates streaming when the filter switches to a running state. Virtual. |
StopStreaming | Halts streaming when the filter switches out of the running state. Virtual. |
Public Methods: End-Of-Stream Methods | |
EndOfStream | Notifies the filter that the input pin received an end-of-stream notification. Virtual. |
NotifyEndOfStream | Posts an EC_COMPLETE event to the filter graph manager. |
ResetEndOfStream | Resets the end-of-stream flags. |
ResetEndOfStreamTimer | Cancels the timer that schedules EC_COMPLETE notifications. Virtual. |
SendEndOfStream | If end-of-stream was reached, schedules an EC_COMPLETE event for the filter graph manager. Virtual. |
TimerCallback | Callback method for the end-of-stream timer event. |
Public Methods: Handlers | |
OnReceiveFirstSample | Called when the filter receives a sample while paused. Virtual. |
OnRenderEnd | Called after a sample is rendered. Virtual. |
OnRenderStart | Called when rendering is about to start. Virtual. |
OnStartStreaming | Called when the filter begins streaming. Virtual. |
OnStopStreaming | Called when the filter stops streaming. Virtual. |
OnWaitEnd | Called when the filter starts waiting for a sample's presentation time. Virtual. |
OnWaitStart | Called when the filter is done waiting for a sample's presentation time. Virtual. |
PrepareRender | Called before the filter renders a sample. Virtual. |
ShouldDrawSampleNow | Determines how a sample is scheduled for rendering. Virtual. |
Pure Virtual Methods | |
CheckMediaType | Determines if the filter accepts a specific media type. |
DoRenderSample | Renders a sample. |
IMediaFilter Methods | |
GetState | Retrieves the filter's state (running, stopped, or paused). |
Pause | Pauses the filter. |
Run | Runs the filter. |
Stop | Stops the filter. |
IBaseFilter Methods | |
FindPin | Retrieves the pin with the specified identifier. |
Flag that indicates whether to stop rendering and reject further samples.
Syntax
BOOL m_bAbort;
Flag that indicates whether end-of-stream was reached.
Syntax
BOOL m_bEOS;
Flag that indicates whether the filter has posted the EC_COMPLETE event.
Syntax
BOOL m_bEOSDelivered;
Flag that indicates whether the filter is processing a Receive call.
Syntax
BOOL m_bInReceive;
Flag that enables or disables repaint events.
Syntax
BOOL m_bRepaintStatus;
Flag that indicates whether the filter is streaming data.
Syntax
BOOL m_bStreaming;
Identifier of the timer event that schedules rendering.
Syntax
DWORD_PTR m_dwAdvise;
Timer-event identifier, for scheduling EC_COMPLETE notifications.
Syntax
UINT m_EndOfStreamTimer;
Event that is signaled when a state transition is complete.
Syntax
CAMEvent m_evComplete;
Filter-state lock.
Syntax
CCritSec m_InterfaceLock;
Pointer to the filter's input pin.
Syntax
CRendererInputPin *m_pInputPin;
Pointer to the current media sample.
Syntax
IMediaSample *m_pMediaSample;
Helper object to pass seek commands upstream.
Syntax
CRendererPosPassThru *m_pPosition;
Pointer to the object that receives quality-control messages.
Syntax
IQualityControl *m_pQSink;
Remarks
The base class does not implement quality control. This member variable defaults to NULL.
Streaming lock.
Syntax
CCritSec m_RendererLock;
Event used to schedule rendering.
Syntax
CAMEvent m_RenderEvent;
Stop time on the current sample.
Syntax
REFERENCE_TIME m_SignalTime;
Event used to release the streaming thread.
Syntax
CAMEvent m_ThreadSignal;
Called when the state is switched to paused or running.
Syntax
virtual HRESULT Active(void);
Return Value
Returns S_OK.
Remarks
The input pin calls this method from its own CRendererInputPin::Active method. This method does nothing in the base class.
Begins a flush operation.
Syntax
virtual HRESULT BeginFlush(void);
Return Value
Returns S_OK.
Remarks
The filter's input pin calls this method when it receives a call to the IPin::BeginFlush method. The filter releases the streaming thread, and releases any sample that it was holding for rendering.
Releases the input pin from a connection.
Syntax
virtual HRESULT BreakConnect(void);
Return Value
Returns one of the HRESULT values shown in the following table.
S_FALSE The pin was not connected. S_OK Success. VFW_E_NOT_STOPPED The filter is still active.
Remarks
The filter's input pin calls this method from inside its own BreakConnect method. (For more information, see CBasePin::BreakConnect.) The filter performs some internal bookkeeping, such as resetting the end-of-stream flag.
Cancels the timer event that schedules rendering.
Syntax
virtual HRESULT CancelNotification(void);
Return Value
Returns one of the HRESULT values shown in the following table.
S_FALSE There was no pending timer event. S_OK Success.
Remarks
The filter calls this method when streaming stops. The method cancels any scheduled rendering.
Constructor method.
Syntax
CBaseRenderer( REFCLSID RenderClass, TCHAR *pName, LPUNKNOWN pUnk, HRESULT *phr );
Parameters
- RenderClass
- Class identifier of the renderer.
- pName
- Pointer to a string containing the name of the filter, for debugging purposes.
- pUnk
- Pointer to the owner of this object. If the object is aggregated, pass a pointer to the aggregating object's IUnknown interface. Otherwise, set this parameter to NULL.
- phr
- Pointer to an HRESULT variable. (Ignored.)
Destructor method.
Syntax
~CBaseRenderer(void);
Determines if the filter accepts a specific media type.
Syntax
virtual HRESULT CheckMediaType( const CMediaType *pmt ) PURE;
Parameters
- pmt
- Pointer to a CMediaType object that contains the proposed media type.
Return Value
Returns S_OK if the proposed media type is acceptable. Otherwise, returns S_FALSE or an error code.
Remarks
The input pin calls this method from its own CBasePin::CheckMediaType method. The derived class must implement this method.
Queries whether a state transition is complete.
Syntax
BOOL CheckReady(void);
Return Value
Returns TRUE if the state transition is complete, or FALSE if the filter is still transitioning to a new state.
See Also
Releases the current sample.
Syntax
virtual HRESULT ClearPendingSample(void);
Return Value
Returns S_OK.
Completes the input pin's connection to another pin.
Syntax
virtual HRESULT CompleteConnect( IPin *pReceivePin );
Parameters
- pReceivePin
- Pointer to the output pin's IPin interface.
Return Value
Returns S_OK.
Remarks
The filter's input pin calls this method from inside its own CompleteConnect method, which is called in order to complete a pin connection. (For more information, see CBasePin::CompleteConnect.) The filter calls the SetRepaintStatus method to enable EC_REPAINT events.
Determines whether a transition to the paused state is complete.
Syntax
virtual HRESULT CompleteStateChange( FILTER_STATE OldState );
Parameters
- OldState
- State prior to the transition.
Return Value
Returns S_OK if the transition is complete. Otherwise, returns S_FALSE.
Remarks
The Pause method calls this method to update the state-transition status. In general, the transition to paused does not finish until the filter receives a sample. However, in some situations the transition completes immediately: for example, if the filter is unconnected, or if the end of the stream was reached. This method checks the various criteria and then calls the Ready method or the NotReady method to update the transition status.
Renders a sample.
Syntax
virtual HRESULT DoRenderSample( IMediaSample *pMediaSample ) PURE;
Parameters
- pMediaSample
- Pointer to the sample's IMediaSample interface.
Return Value
Returns an HRESULT value.
Remarks
The derived class must implement this method. The behavior depends entirely on the type of filter being implemented. A video renderer, for example, would draw the video image contained in the sample.
Ends a flush operation.
Syntax
virtual HRESULT EndFlush(void);
Return Value
Returns S_OK.
Remarks
The filter's input pin calls this method when it receives a call to the IPin::EndFlush method.
Notifies the filter that the input pin received an end-of-stream notification.
Syntax
HRESULT EndOfStream(void);
Return Value
Returns S_OK.
Remarks
The filter's input pin calls this method when it receives an end-of-stream notification.
This method sets the m_bEOS flag to TRUE and calls the SendEndOfStream method to schedule an EC_COMPLETE event. If the filter is paused and waiting for a sample, this method completes the state transition.
Retrieves the pin with the specified identifier.
Syntax
HRESULT FindPin( LPCWSTR Id, IPin **ppPin );
Parameters
- Id
- Pointer to a constant, null-terminated Unicode string that identifies the pin. Must be L"In".
- ppPin
- Address of a variable that receives a pointer to the pin's IPin interface. If the method fails, *ppPin is set to NULL.
Return Value
Returns one of the HRESULT values shown in the following table.
S_OK Success. E_POINTER NULL pointer argument. VFW_E_NOT_FOUND Not found.
Remarks
This method overrides the CBaseFilter::FindPin method. The filter's only pin (the input pin) is named In.
Retrieves the current sample.
Syntax
virtual IMediaSample *GetCurrentSample(void);
Return Value
Returns a pointer to the sample's IMediaSample interface, or NULL if no sample is available.
Remarks
If the return value is non-NULL, the IMediaSample pointer has an outstanding reference count. Be sure to release it.
Retrieves the filter's IMediaPosition and IMediaSeeking interface pointers.
Syntax
virtual HRESULT GetMediaPositionInterface( REFIID riid, void **ppv );
Parameters
- riid
- Reference identifier of the interface.
- ppv
- Address of a variable that receives the interface pointer.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. E_OUTOFMEMORY Insufficient memory. E_NOINTERFACE Interface not supported.
Remarks
The filter delegates all seeking commands to a CRendererPosPassThru object, which passes them upstream. This method creates the CRendererPosPassThru object, if it does not yet exist, and queries it for the requested interface.
The m_pPosition member variable stores a pointer to the CRendererPosPassThru object.
Retrieves a pin.
Syntax
virtual CBasePin *GetPin( int n );
Parameters
- n
- Number of the specified pin. Must be zero.
Return Value
Returns the m_pInputPin pointer.
Remarks
This method implements the CBaseFilter::GetPin method, which is pure virtual in the CBaseFilter class. The filter supports exactly one pin (the input pin). The first time this method is called, it creates the pin as a new CRendererInputPin object.
Retrieves the number of pins.
Syntax
virtual int GetPinCount(void);
Return Value
Returns 1.
Remarks
This method implements the CBaseFilter::GetPinCount method, which is pure virtual in the CBaseFilter class.
Retrieves the filter state.
Syntax
FILTER_STATE GetRealState(void);
Return Value
Returns the value of CBaseFilter.m_State. The value is a member of the FILTER_STATE enumerated type.
Remarks
This method provides a simpler alternative to the GetState method, for internal use.
Retrieves the event that schedules rendering.
Syntax
CAMEvent *GetRenderEvent(void);
Return Value
Returns a pointer to the m_RenderEvent event.
Retrieves the time stamps from a sample.
Syntax
virtual HRESULT GetSampleTimes( IMediaSample *pMediaSample, REFERENCE_TIME *pStartTime, REFERENCE_TIME *pEndTime );
Parameters
- pMediaSample
- Pointer to the sample's IMediaSample interface.
- pStartTime
- Pointer to a variable that receives the start time.
- pEndTime
- Pointer to a variable that receives the end time.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK The sample should be rendered immediately. S_FALSE The sample should be scheduled for rendering, based on the time stamps. E_FAIL Do not render this sample. VFW_E_START_TIME_AFTER_END Bad time stamp: The end time is earlier than the start time.
Remarks
The filter calls this method to determine how it should handle a sample. If the return value is S_OK, the filter renders the sample immediately. If the return value is S_FALSE, the filter schedules the sample for rendering, based on the time stamps. If the return value is an error code, the filter rejects the sample.
This method returns S_OK if the sample has no time stamps, or if the filter does not have a reference clock. Otherwise, it returns the value of the ShouldDrawSampleNow method. In the base class, ShouldDrawSampleNow always returns S_FALSE. The derived class can override this behavior. For example, if the derived class implements quality control management, it might return E_FAIL to drop a sample.
Retrieves the filters's state (running, stopped, or paused).
Syntax
HRESULT GetState( DWORD dwMilliSecsTimeout, FILTER_STATE *State );
Parameters
- dwMilliSecsTimeout
- Time-out interval, in milliseconds.
- State
- Pointer to a variable that receives a member of the FILTER_STATE enumerated type, indicating the filter's state.
Return Value
Returns one of the HRESULT values shown in the following table.
S_OK Success. VFW_S_STATE_INTERMEDIATE The filter is transitioning to the indicated state. E_POINTER NULL pointer argument.
Remarks
This method overrides the CBaseFilter::GetState method. When the renderer is paused, it does not complete the state transition until it receives a sample to render. If the time-out expires before the state transition is complete, the method returns VFW_S_STATE_INTERMEDIATE.
Determines whether the filter has a sample.
Syntax
virtual BOOL HaveCurrentSample(void);
Return Value
Returns TRUE if the filter has a sample, or FALSE otherwise.
Called when the state is switched to stopped.
Syntax
virtual HRESULT Inactive(void);
Return Value
Returns S_OK.
Remarks
The input pin calls this method from its own CRendererInputPin::Inactive method. The filter calls the ClearPendingSample method to release the most recent sample.
Queries whether the end-of-stream notification was received.
Syntax
BOOL IsEndOfStream(void);
Return Value
Returns the m_bEOS flag.
Queries whether the EC_COMPLETE event has been delivered to the filter graph manager.
Syntax
BOOL IsEndOfStreamDelivered(void);
Return Value
Returns the m_bEOSDelivered flag.
Queries whether the filter is streaming data.
Syntax
BOOL IsStreaming(void);
Return Value
Returns the m_bStreaming flag.
Signals that a state transition is not yet complete.
Syntax
void NotReady(void);
Remarks
This method causes the GetState method to return VFW_S_STATE_INTERMEDIATE, which indicates that the filter is still transitioning to its current state. The filter calls this method whenever a state transition is pending. (This occurs when the filter pauses, until it receives a sample.)
See Also
Posts an EC_COMPLETE event to the filter graph manager.
Syntax
void NotifyEndOfStream(void);
See Also
Posts an EC_DISPLAY_CHANGED event to the filter graph manager.
Syntax
BOOL CBaseRenderer::OnDisplayChange(void);
Return Value
Returns TRUE if the event was posted, or FALSE otherwise.
Remarks
Video renderers should call this method in response to WM_DISPLAYCHANGE messages. If the input pin is connected, the method sends an EC_DISPLAY_CHANGED event to the filter graph manager.
Called when the filter receives a sample while paused.
Syntax
virtual void OnReceiveFirstSample( IMediaSample *pMediaSample );
Parameters
- pMediaSample
- Pointer to the sample's IMediaSample interface.
Remarks
The Receive method calls this method. It does nothing in the base class, but the derived class can override it. This method is intended primarily for video renderers. When a video renderer is paused, it typically displays the first sample as a still image.
Seeking the graph while paused also causes this method to be called.
Called after a sample is rendered.
Syntax
virtual void OnRenderEnd( IMediaSample *pMediaSample );
Parameters
- pMediaSample
- Pointer to the sample's IMediaSample interface.
Remarks
The Render method calls this method. It does nothing in the base class, but the derived class can override it; for example, to collect quality-control data.
Called when rendering is about to start.
Syntax
virtual void OnRenderStart( IMediaSample *pMediaSample );
Parameters
- pMediaSample
- Pointer to the sample's IMediaSample interface.
Remarks
The Render method calls this method. It does nothing in the base class, but the derived class can override it; for example, to collect quality-control data.
Called when the filter begins streaming.
Syntax
virtual HRESULT OnStartStreaming(void);
Return Value
Returns S_OK.
Remarks
The StartStreaming method calls this method. It does nothing in the base class, but the derived class can override it.
Called when the filter stops streaming.
Syntax
virtual HRESULT OnStopStreaming(void);
Return Value
Returns S_OK.
Remarks
The StopStreaming method calls this method. It does nothing in the base class, but the derived class can override it.
Called when the filter is done waiting for a sample's presentation time.
Syntax
virtual void OnWaitEnd(void);
Remarks
The WaitForRenderTime method calls this method when it has finished waiting for a sample's presentation time. This method does not do anything in the base class, but the derived class can override it.
If you are implementing quality control, you might override this method along with the OnWaitStart method. You can use these methods to track the filter's performance.
Called when the filter starts waiting for a sample's presentation time.
Syntax
virtual void OnWaitStart(void);
Remarks
The WaitForRenderTime method calls this method when it begins waiting for a sample's presentation time. This method does not do anything in the base class, but the derived class can override it.
If you are implementing quality control, you might override this method along with the OnEndStart method. You can use these methods to track the filter's performance.
Pauses the filter.
Syntax
HRESULT Pause(void);
Return Value
Returns an HRESULT value. Possible values include those in the following table.
S_OK The transition is complete. S_FALSE Transition is not complete.
Remarks
This method overrides the CBaseFilter::Pause method. It performs the following steps:
- Calls the CBaseFilter::Pause method.
- Commits the allocator. (See IMemAllocator::Commit.)
- If the previous state was stopped, the filter releases any sample it is holding. (The sample is no longer valid.)
- Calls the CompleteStateChange method and returns the value.
Prepares to render a sample.
Syntax
virtual HRESULT PrepareReceive( IMediaSample *pMediaSample );
Parameters
- pMediaSample
- Pointer to the sample's IMediaSample interface.
Return Value
Returns an HRESULT value. Possible values include those in the following table.
S_OK Success. E_FAIL Failed. E_UNEXPECTED Unexpected error. VFW_E_SAMPLE_REJECTED Filter is dropping this sample.
Remarks
The filter calls this method from inside the Receive method, before it renders a sample. If the filter is running, this method schedules the sample for rendering.
If the filter already has a pending sample, or if the end-of-stream was already reached, the method returns E_UNEXPECTED. Possibly the upstream filter is not serializing its streaming calls correctly.
If the scheduling algorithm determines that the sample should be dropped (see ScheduleSample), the method returns VFW_E_SAMPLE_REJECTED. However, the input pin's IMemInputPin::Receive method does not pass this error code to the upstream filter, because dropping a sample is not an error.
Called before the filter renders a sample.
Syntax
virtual void PrepareRender(void);
Remarks
The filter calls this method before it calls the OnReceiveFirstSample method or the Render method. PrepareRender does not do anything in the base class. The derived class can override it to perform any actions required before rendering. For example, a video renderer can override this method to realize its palette.
Signals that a state transition is complete.
Syntax
void Ready(void);
Remarks
This method causes the GetState method to return S_OK, which indicates that the filter has completed the transition to its current state. The filter calls this method whenever it completes a state transition.
See Also
Receives the next media sample in the stream.
Syntax
virtual HRESULT Receive( IMediaSample *pMediaSample );
Parameters
- pMediaSample
- Pointer to the sample's IMediaSample interface.
Return Value
Returns S_OK if successful, or an HRESULT value indicating the cause of the error.
Remarks
The input pin calls this method when it receives a sample from the upstream filter.
If the filter is running, this method performs the following steps:
- Schedules the sample for rendering (PrepareReceive).
- Waits for the scheduled time (WaitForRenderTime).
- Renders the sample (Render).
- Releases the sample (ClearPendingSample).
If the filter is paused, the method performs the following steps:
- Notifies the derived class that a sample is available (OnReceiveFirstSample).
- Waits for the scheduled time.
- Renders the sample.
- Releases the sample.
While paused, the method waits in step 2 until the filter switches to a running state. At that point, the filter schedules the sample.
In the base class, the OnReceiveFirstSample method does nothing. The derived class can override it. For example, when a video renderer is paused, it displays the first sample as a still image.
Renders a sample.
Syntax
virtual HRESULT Render( IMediaSample *pMediaSample );
Parameters
- pMediaSample
- Pointer to the sample's IMediaSample interface.
Return Value
Returns an HRESULT value. Possible values include those in the following table.
S_FALSE The filter is stopped, or pMediaSample is NULL. S_OK Success.
Remarks
This method calls the pure virtual method DoRenderSample, which does the real work. The derived class must implement DoRenderSample.
Immediately before calling DoRenderSample, this method calls the OnRenderStart method. Immediately after, it calls the OnRenderEnd method. The derived class can override those two methods as needed.
Resets the end-of-stream flags.
Syntax
virtual HRESULT ResetEndOfStream(void);
Return Value
Returns S_OK.
Remarks
This method clears the previous end-of-stream condition. At that point, the filter can receive new data. The Stop and BeginFlush methods call this method.
Cancels the timer that schedules EC_COMPLETE notifications.
Syntax
void ResetEndOfStreamTimer(void);
See Also
Runs the filter.
Syntax
HRESULT Run(void);
Return Value
Returns S_OK if successful, or an HRESULT value indicating the cause of the error.
Remarks
This method overrides the CBaseFilter::Run method. It performs the following actions:
- Calls the CBaseFilter::Run method.
- Commits the allocator. (See IMemAllocator::Commit.)
- If the previous state was stopped, the filter releases any sample it is holding. (The sample is no longer valid.)
- Calls the StartStreaming method and returns the result. If a sample is pending, the StartStreaming method schedules it for rendering.
If the filter is not connected, it posts an EC_COMPLETE event immediately.
Schedules a sample for rendering.
Syntax
virtual BOOL ScheduleSample( IMediaSample *pMediaSample );
Parameters
- pMediaSample
- Pointer to the sample's IMediaSample interface.
Return Value
Returns TRUE if the sample was scheduled, or FALSE if the sample was dropped.
Remarks
This method first determines whether the sample should be rendered immediately, rendered in the future, or dropped. (To do so, it calls the GetSampleTimes method.) If the sample should be rendered immediately, the method signals the m_RenderEvent event. If the sample should be rendered in the future, the method calls the IReferenceClock::AdviseTime method for scheduling.
If end-of-stream was reached, schedules an EC_COMPLETE event for the filter graph manager.
Syntax
virtual HRESULT SendEndOfStream(void);
Return Value
Returns an HRESULT value. Possible values include those in the following table.
S_FALSE The filter graph manager is not accepting event notifications. S_OK Success.
Remarks
The filter might receive an end-of-stream notification before the current sample's stop time. If so, the filter should wait before posting an EC_COMPLETE notification to the filter graph manager.
Therefore:
- If the filter has received an early end-of-stream (EOS) notification, this method schedules a timer event. When the timer event is activated, the filter posts the EC_COMPLETE event.
- If the filter has received an EOS notification that was not early, this method posts the EC_COMPLETE event immediately.
- If the filter does not have any pending EOS notification, the method returns without doing anything.
The timer callback method is TimerCallback. To deliver the EC_COMPLETE event, the filter calls the NotifyEndOfStream method.
Notifies the upstream filter of the video window handle.
Syntax
void SendNotifyWindow( IPin *pPin, HWND hwnd );
Parameters
- pPin
- Pointer to the IPin interface of the upstream filter's output pin.
- hwnd
- Handle to the video window, or NULL.
Return Value
No return value.
Remarks
If the output pin of the upstream filter supports the IMediaEventSink interface, this method sends it the EC_NOTIFY_WINDOW event code along with the window handle.
Video renderers can override their CompleteConnect methods to call this method. It provides a mechanism for informing the upstream filter of the window handle. If you do this, override the BreakConnect method as well, and call SendNotifyWindow with a NULL handle.
Sends a repaint event to the filter graph manager.
Syntax
void SendRepaint(void);
Remarks
This method sends an EC_REPAINT event to the filter graph manager if the following conditions are true:
- The input pin is connected.
- The filter is not flushing data.
- The end-of-stream was not reached.
- The m_bAbort flag is FALSE.
- The m_bRepaintStatus flag is TRUE.
Depending on the state of the graph, the EC_REPAINT event can cause the upstream filter to re-send a sample; the filter graph to seek to its current location; or the filter graph manager to pause momentarily. (See EC_REPAINT.) This event is potentially inefficient, so it should be used sparingly. However, video renderers sometimes need to refresh the display.
Sets the abort flag, which indicates whether to stop rendering and reject further samples.
Syntax
void SetAbortSignal( BOOL bAbort );
Parameters
- bAbort
- Boolean value indicating whether to stop rendering. If TRUE, the filter will not render any more samples.
Remarks
This method sets the m_bAbort flag.
Called when the pin's media type is set.
Syntax
virtual HRESULT SetMediaType( const CMediaType *pmt );
Parameters
- pmt
- Pointer to a CMediaType object that specifies the media type.
Return Value
Returns S_OK.
Remarks
The input pin calls this method from its own CRendererInputPin::SetMediaType method. This method does nothing in the base class.
Enables or disables repaint events.
Syntax
void SetRepaintStatus( BOOL bRepaint );
Parameters
- bRepaint
- Boolean value indicating whether repaint events are enabled. If TRUE, the filter will sent EC_REPAINT events to the filter graph manager. Otherwise, it will not send EC_REPAINT events.
Remarks
This method ensures that the filter graph manager is not flooded with redundant EC_REPAINT events. After the filter sends an EC_REPAINT event, it calls this method with the value TRUE. The filter does not send more EC_REPAINT events until it receives more data.
Determines how a sample is scheduled for rendering.
Syntax
virtual HRESULT ShouldDrawSampleNow( IMediaSample *pMediaSample, REFERENCE_TIME *pStartTime, REFERENCE_TIME *pEndTime );
Parameters
- pMediaSample
- Pointer to the sample's IMediaSample interface.
- pStartTime
- Pointer to a variable that contains the sample's start time.
- pEndTime
- Pointer to a variable that contains the sample's end time.
Return Value
Returns S_FALSE. If the derived class overrides this method, return one of the values shown in the following table.
S_OK The sample should be rendered immediately. S_FALSE The sample should be scheduled for rendering, based on the time stamps. Error code Do not render this sample.
Remarks
The GetSampleTimes method calls this method. By default, samples are always scheduled for rendering based on their time stamps. The derived class can override this method; for example, to implement quality control.
Clears the timer identifier used to schedule rendering.
Syntax
virtual void SignalTimerFired(void);
Remarks
The filter calls this method when the rendering timer activates (see WaitForRenderTime) or when the timer is canceled (see CancelNotification). The method resets the m_dwAdvise member variable to zero.
Holds or releases the streaming thread.
Syntax
virtual HRESULT SourceThreadCanWait( BOOL bCanWait );
Parameters
- bCanWait
- Boolean value indicating whether to hold the streaming thread. If TRUE, the streaming thread is blocked while the filter waits to render the next samples. If FALSE, the streaming thread is released.
Return Value
Returns S_OK.
Remarks
Calling the SourceThreadCanWait method with the value FALSE forces the filter to return from a blocked IMemInputPin::Receive call. When the filter is running, it blocks Receive calls until the current sample's presentation time. When the filter is paused, it blocks Receive calls indefinitely. This behavior regulates the flow of data in the stream. When the filter is stopped or flushing, however, it should not block.
The blocking is controlled by the WaitForRenderTime method, which waits on two events: m_RenderEvent and m_ThreadSignal. The m_RenderEvent event is signaled when the presentation time arrives. The m_ThreadSignal event is signaled when SourceThreadCanWait is called with the value FALSE. Calling SourceThreadCanWait with the value TRUE resets the event.
The Stop and BeginFlush methods call SourceThreadCanWait with the value FALSE (releasing the streaming thread). The Pause, Run, and EndFlush methods call SourceThreadCanWait with the value TRUE.
Initiates streaming when the filter switches to a running state.
Syntax
virtual HRESULT StartStreaming(void);
Return Value
Returns S_OK or another HRESULT value.
Remarks
If the filter has a sample, it schedules the sample for rendering. Otherwise, if there is a pending end-of-stream notification, the filter sends an EC_COMPLETE event to the filter graph manager.
This method calls the OnStartStreaming method. That method does nothing in the base class, but the derived class can override it.
Stops the filter.
Syntax
HRESULT Stop(void);
Return Value
Returns S_OK.
Remarks
This method overrides the CBaseFilter::Stop method. It performs the following actions:
- Calls CBaseFilter::Stop.
- Decommits the allocator. (See IMemAllocator::Decommit.)
- Cancels any scheduled rendering and releases the streaming thread.
- Waits for any pending Receive call to complete.
Halts streaming when the filter switches out of the running state.
Syntax
virtual HRESULT StopStreaming(void);
Return Value
Returns S_OK.
Remarks
This method calls the OnStopStreaming method. That method does nothing in the base class, but the derived class can override it.
Callback method for the end-of-stream timer event.
Syntax
void TimerCallback(void);
Remarks
The SendEndOfStream method uses a timer event to schedule EC_COMPLETE notifications. The TimerCallback method is the callback function for the timer event. The TimerCallback method calls SendEndOfStream again, and SendEndOfStream determines whether to send the EC_COMPLETE notification or set another timer.
The ResetEndOfStreamTimer method cancels the timer event.
Waits for the Receive method to complete.
Syntax
void WaitForReceiveToComplete(void);
Remarks
The Stop and BeginFlush methods call this method to synchronize the state change with the Receive method.
Specifically, this method dispatches messages while it waits for the m_bInReceive flag to become FALSE. The flag becomes TRUE in the PrepareReceive method and switches back to FALSE after the Receive method calls the PrepareRender method. The derived class can use PrepareRender to set the palette. Waiting for PrepareRender to complete ensures that palette-change messages are dispatched before the state change occurs. This avoids a potential deadlock.
Waits for the current sample's presentation time.
Syntax
virtual HRESULT WaitForRenderTime(void);
Return Value
Returns one of the following HRESULT values.
S_OK Success. VFW_E_STATE_CHANGED The filter state changed before the presentation time arrived.
Remarks
This method waits until one of the following occurs:
- The sample's presentation time arrives, at which point the sample can be rendered.
- The filter stops or begins flushing data.
If the presentation time arrives, the m_RenderEvent event is signaled. If the state changes, the m_ThreadSignal event is signaled. This method waits on both events. The derived class can override this method to wait on additional events, if necessary.
This method calls the OnWaitStart method when the wait begins, and the OnWaitEnd method when the wait is done. Neither method does anything in the base class, but the derived class can override them.