CBaseRenderer class

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

cbaserenderer class hierarchy

The CBaseRenderer class is a base class for implementing renderer filters. It supports one input pin, implemented by the CRendererInputPin class. 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 CBaseRenderer::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 CBaseRenderer::DoRenderSample method, as the first sample in the stream.

The CBaseRenderer class exposes the IMediaSeeking and IMediaPosition interfaces through the CRendererPosPassThru object. It passes all seek requests to the next filter upstream.

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 CBaseRenderer::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 CBaseRenderer::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 Description
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_ObjectCreationLock Lock to protect the creation of objects inside the filter.
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 Description
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 CBaseRenderer::Receive method to complete.
WaitForRenderTime Waits for the current sample's presentation time. Virtual.
Public Methods: Accessor Methods Description
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 a flag which indicates whether to stop rendering and reject further samples.
SetRepaintStatus Enables or disables repaint events.
Public Methods: State-Change Methods Description
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 Description
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 Description
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 is done waiting for a sample's presentation time. Virtual.
OnWaitStart Called when the filter starts 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 Description
CheckMediaType Determines if the filter accepts a specific media type.
DoRenderSample Renders a sample.
IMediaFilter Methods Description
GetState Retrieves the filter's state (running, stopped, or paused).
Pause Pauses the filter.
Run Runs the filter.
Stop Stops the filter.
IBaseFilter Methods Description
FindPin Retrieves the pin with the specified identifier.

Requirements

Requirement Value
Header
Renbase.h (include Streams.h)
Library
Strmbase.lib (retail builds);
Strmbasd.lib (debug builds)