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.]
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:
- CBaseRenderer::CheckMediaType: Accepts or rejects proposed media types. The filter calls this method during the pin connection process.
- CBaseRenderer::DoRenderSample: Renders a sample. The filter calls this method for every sample that it receives while running.
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 |
|
| Library |
|