Microsoft DirectX 8.0

CBaseRenderer Class

CBaseRenderer class hierarchy

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_bAbortFlag that indicates whether to stop rendering and reject further samples.
m_bEOSFlag that indicates whether end-of-stream was reached.
m_bEOSDeliveredFlag that indicates whether the filter has posted the EC_COMPLETE event.
m_bInReceiveFlag that indicates whether the filter is processing a Receive call.
m_bRepaintStatusFlag that enables or disables repaint events.
m_bStreamingFlag that indicates whether the filter is streaming data.
m_dwAdviseIdentifier of the timer event that schedules rendering.
m_EndOfStreamTimerTimer-event identifier, for scheduling EC_COMPLETE notifications.
m_evCompleteEvent that is signaled when a state transition is complete.
m_InterfaceLockFilter-state lock.
m_pInputPinPointer to the filter's input pin.
m_pMediaSamplePointer to the current media sample.
m_pPositionHelper object to pass seek commands upstream.
m_pQSinkPointer to the object that receives quality-control messages.
m_RendererLockStreaming lock.
m_RenderEventEvent used to schedule rendering.
m_SignalTimeStop time on the current sample.
m_ThreadSignalEvent used to release the streaming thread.
Public Methods
CancelNotificationCancels the timer event that schedules rendering. Virtual.
CBaseRendererConstructor method.
~CBaseRendererDestructor method.
GetMediaPositionInterfaceRetrieves the filter's IMediaPosition and IMediaSeeking interface pointers. Virtual.
GetPinRetrieves a pin. Virtual.
GetPinCountRetrieves the number of pins. Virtual.
GetSampleTimesRetrieves the time stamps from a sample. Virtual.
OnDisplayChangePosts an EC_DISPLAY_CHANGED event to the filter graph manager.
PrepareReceivePrepares to render a sample. Virtual.
ReceiveReceives the next media sample in the stream. Virtual.
RenderRenders a sample. Virtual.
ScheduleSampleSchedules a sample for rendering. Virtual.
SendNotifyWindowNotifies the upstream filter of the video window handle.
SendRepaintSends a repaint event to the filter graph manager.
SetMediaTypeCalled when the pin's media type is set. Virtual.
SignalTimerFiredClears the timer identifier used to schedule rendering.
SourceThreadCanWaitHolds or releases the streaming thread. Virtual.
WaitForReceiveToCompleteWaits for the Receive method to complete.
WaitForRenderTimeWaits for the current sample's presentation time. Virtual.
Public Methods: Accessor Methods
ClearPendingSampleReleases the current sample. Virtual.
GetCurrentSampleRetrieves the current sample. Virtual.
GetRealStateRetrieves the filter state.
GetRenderEventRetrieves the event that schedules rendering.
HaveCurrentSampleDetermines whether the filter has a sample. Virtual.
IsEndOfStreamQueries whether the end-of-stream notification was received.
IsEndOfStreamDeliveredQueries whether the EC_COMPLETE event has been delivered to the filter graph manager.
IsStreamingQueries whether the filter is streaming data.
SetAbortSignalSets the abort flag, which indicates whether to stop rendering and reject further samples.
SetRepaintStatusEnables or disables repaint events.
Public Methods: State-Change Methods
ActiveCalled when the state is switched to paused or running. Virtual.
BeginFlushBegins a flush operation. Virtual.
BreakConnectReleases the input pin from a connection. Virtual.
CheckReadyQueries whether a state transition is complete.
CompleteConnectCompletes the input pin's connection to another pin. Virtual.
CompleteStateChangeDetermines whether a transition to the paused state is complete. Virtual.
EndFlushEnds a flush operation. Virtual.
InactiveCalled when the state is switched to stopped. Virtual.
NotReadySignals that a state transition is not yet complete.
ReadySignals that a state transition is complete.
StartStreamingInitiates streaming when the filter switches to a running state. Virtual.
StopStreamingHalts streaming when the filter switches out of the running state. Virtual.
Public Methods: End-Of-Stream Methods
EndOfStreamNotifies the filter that the input pin received an end-of-stream notification. Virtual.
NotifyEndOfStreamPosts an EC_COMPLETE event to the filter graph manager.
ResetEndOfStreamResets the end-of-stream flags.
ResetEndOfStreamTimerCancels the timer that schedules EC_COMPLETE notifications. Virtual.
SendEndOfStreamIf end-of-stream was reached, schedules an EC_COMPLETE event for the filter graph manager. Virtual.
TimerCallbackCallback method for the end-of-stream timer event.
Public Methods: Handlers
OnReceiveFirstSampleCalled when the filter receives a sample while paused. Virtual.
OnRenderEndCalled after a sample is rendered. Virtual.
OnRenderStartCalled when rendering is about to start. Virtual.
OnStartStreamingCalled when the filter begins streaming. Virtual.
OnStopStreamingCalled when the filter stops streaming. Virtual.
OnWaitEndCalled when the filter starts waiting for a sample's presentation time. Virtual.
OnWaitStartCalled when the filter is done waiting for a sample's presentation time. Virtual.
PrepareRenderCalled before the filter renders a sample. Virtual.
ShouldDrawSampleNowDetermines how a sample is scheduled for rendering. Virtual.
Pure Virtual Methods
CheckMediaTypeDetermines if the filter accepts a specific media type.
DoRenderSampleRenders a sample.
IMediaFilter Methods
GetStateRetrieves the filter's state (running, stopped, or paused).
PausePauses the filter.
RunRuns the filter.
StopStops the filter.
IBaseFilter Methods
FindPinRetrieves the pin with the specified identifier.

CBaseRenderer.m_bAbort

CBaseRenderer Class

Flag that indicates whether to stop rendering and reject further samples.

Syntax

BOOL m_bAbort;

CBaseRenderer.m_bEOS

CBaseRenderer Class

Flag that indicates whether end-of-stream was reached.

Syntax

BOOL m_bEOS;

CBaseRenderer.m_bEOSDelivered

CBaseRenderer Class

Flag that indicates whether the filter has posted the EC_COMPLETE event.

Syntax

BOOL m_bEOSDelivered;

CBaseRenderer.m_bInReceive

CBaseRenderer Class

Flag that indicates whether the filter is processing a Receive call.

Syntax

BOOL m_bInReceive;

CBaseRenderer.m_bRepaintStatus

CBaseRenderer Class

Flag that enables or disables repaint events.

Syntax

BOOL m_bRepaintStatus;

CBaseRenderer.m_bStreaming

CBaseRenderer Class

Flag that indicates whether the filter is streaming data.

Syntax

BOOL m_bStreaming;

CBaseRenderer.m_dwAdvise

CBaseRenderer Class

Identifier of the timer event that schedules rendering.

Syntax

DWORD_PTR m_dwAdvise;

CBaseRenderer.m_EndOfStreamTimer

CBaseRenderer Class

Timer-event identifier, for scheduling EC_COMPLETE notifications.

Syntax

UINT m_EndOfStreamTimer;

CBaseRenderer.m_evComplete

CBaseRenderer Class

Event that is signaled when a state transition is complete.

Syntax

CAMEvent m_evComplete;

CBaseRenderer.m_InterfaceLock

CBaseRenderer Class

Filter-state lock.

Syntax

CCritSec m_InterfaceLock;

CBaseRenderer.m_pInputPin

CBaseRenderer Class

Pointer to the filter's input pin.

Syntax

CRendererInputPin *m_pInputPin;

CBaseRenderer.m_pMediaSample

CBaseRenderer Class

Pointer to the current media sample.

Syntax

IMediaSample *m_pMediaSample;

CBaseRenderer.m_pPosition

CBaseRenderer Class

Helper object to pass seek commands upstream.

Syntax

CRendererPosPassThru *m_pPosition;

CBaseRenderer.m_pQSink

CBaseRenderer Class

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.

CBaseRenderer.m_RendererLock

CBaseRenderer Class

Streaming lock.

Syntax

CCritSec m_RendererLock;

CBaseRenderer.m_RenderEvent

CBaseRenderer Class

Event used to schedule rendering.

Syntax

CAMEvent m_RenderEvent;

CBaseRenderer.m_SignalTime

CBaseRenderer Class

Stop time on the current sample.

Syntax

REFERENCE_TIME m_SignalTime;

CBaseRenderer.m_ThreadSignal

CBaseRenderer Class

Event used to release the streaming thread.

Syntax

CAMEvent m_ThreadSignal;

CBaseRenderer::Active

CBaseRenderer Class

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.

CBaseRenderer::BeginFlush

CBaseRenderer 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.

CBaseRenderer::BreakConnect

CBaseRenderer Class

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_FALSEThe pin was not connected.
S_OKSuccess.
VFW_E_NOT_STOPPEDThe 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.

CBaseRenderer::CancelNotification

CBaseRenderer Class

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_FALSEThere was no pending timer event.
S_OKSuccess.

Remarks

The filter calls this method when streaming stops. The method cancels any scheduled rendering.

CBaseRenderer::CBaseRenderer

CBaseRenderer Class

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.)

CBaseRenderer::~CBaseRenderer

CBaseRenderer Class

Destructor method.

Syntax

~CBaseRenderer(void);

CBaseRenderer::CheckMediaType

CBaseRenderer Class

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.

CBaseRenderer::CheckReady

CBaseRenderer Class

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

NotReady, Ready

CBaseRenderer::ClearPendingSample

CBaseRenderer Class

Releases the current sample.

Syntax

virtual HRESULT ClearPendingSample(void);

Return Value

Returns S_OK.

CBaseRenderer::CompleteConnect

CBaseRenderer Class

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.

CBaseRenderer::CompleteStateChange

CBaseRenderer Class

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.

CBaseRenderer::DoRenderSample

CBaseRenderer Class

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.

CBaseRenderer::EndFlush

CBaseRenderer Class

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.

CBaseRenderer::EndOfStream

CBaseRenderer Class

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.

CBaseRenderer::FindPin

CBaseRenderer Class

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_OKSuccess.
E_POINTERNULL pointer argument.
VFW_E_NOT_FOUNDNot found.

Remarks

This method overrides the CBaseFilter::FindPin method. The filter's only pin (the input pin) is named In.

CBaseRenderer::GetCurrentSample

CBaseRenderer Class

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.

CBaseRenderer::GetMediaPositionInterface

CBaseRenderer Class

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_OKSuccess.
E_OUTOFMEMORYInsufficient memory.
E_NOINTERFACEInterface 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.

CBaseRenderer::GetPin

CBaseRenderer Class

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.

CBaseRenderer::GetPinCount

CBaseRenderer Class

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.

CBaseRenderer::GetRealState

CBaseRenderer 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.

CBaseRenderer::GetRenderEvent

CBaseRenderer Class

Retrieves the event that schedules rendering.

Syntax

CAMEvent *GetRenderEvent(void);

Return Value

Returns a pointer to the m_RenderEvent event.

CBaseRenderer::GetSampleTimes

CBaseRenderer Class

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_OKThe sample should be rendered immediately.
S_FALSEThe sample should be scheduled for rendering, based on the time stamps.
E_FAILDo not render this sample.
VFW_E_START_TIME_AFTER_ENDBad 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.

CBaseRenderer::GetState

CBaseRenderer Class

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_OKSuccess.
VFW_S_STATE_INTERMEDIATEThe filter is transitioning to the indicated state.
E_POINTERNULL 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.

CBaseRenderer::HaveCurrentSample

CBaseRenderer Class

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.

CBaseRenderer::Inactive

CBaseRenderer Class

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.

CBaseRenderer::IsEndOfStream

CBaseRenderer Class

Queries whether the end-of-stream notification was received.

Syntax

BOOL IsEndOfStream(void);

Return Value

Returns the m_bEOS flag.

CBaseRenderer::IsEndOfStreamDelivered

CBaseRenderer Class

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.

CBaseRenderer::IsStreaming

CBaseRenderer Class

Queries whether the filter is streaming data.

Syntax

BOOL IsStreaming(void);

Return Value

Returns the m_bStreaming flag.

CBaseRenderer::NotReady

CBaseRenderer Class

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

CheckReady, Ready

CBaseRenderer::NotifyEndOfStream

CBaseRenderer Class

Posts an EC_COMPLETE event to the filter graph manager.

Syntax

void NotifyEndOfStream(void);

See Also

EndOfStream, SendEndOfStream

CBaseRenderer::OnDisplayChange

CBaseRenderer Class

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.

CBaseRenderer::OnReceiveFirstSample

CBaseRenderer Class

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.

CBaseRenderer::OnRenderEnd

CBaseRenderer Class

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.

CBaseRenderer::OnRenderStart

CBaseRenderer Class

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.

CBaseRenderer::OnStartStreaming

CBaseRenderer Class

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.

CBaseRenderer::OnStopStreaming

CBaseRenderer Class

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.

CBaseRenderer::OnWaitEnd

CBaseRenderer Class

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.

CBaseRenderer::OnWaitStart

CBaseRenderer Class

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.

CBaseRenderer::Pause

CBaseRenderer Class

Pauses the filter.

Syntax

HRESULT Pause(void);

Return Value

Returns an HRESULT value. Possible values include those in the following table.

S_OKThe transition is complete.
S_FALSE Transition is not complete.

Remarks

This method overrides the CBaseFilter::Pause method. It performs the following steps:

CBaseRenderer::PrepareReceive

CBaseRenderer Class

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_OKSuccess.
E_FAILFailed.
E_UNEXPECTEDUnexpected error.
VFW_E_SAMPLE_REJECTEDFilter 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.

CBaseRenderer::PrepareRender

CBaseRenderer Class

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.

CBaseRenderer::Ready

CBaseRenderer Class

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

CheckReady, NotReady

CBaseRenderer::Receive

CBaseRenderer Class

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:

  1. Schedules the sample for rendering (PrepareReceive).
  2. Waits for the scheduled time (WaitForRenderTime).
  3. Renders the sample (Render).
  4. Releases the sample (ClearPendingSample).

If the filter is paused, the method performs the following steps:

  1. Notifies the derived class that a sample is available (OnReceiveFirstSample).
  2. Waits for the scheduled time.
  3. Renders the sample.
  4. 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.

CBaseRenderer::Render

CBaseRenderer Class

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_FALSEThe filter is stopped, or pMediaSample is NULL.
S_OKSuccess.

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.

CBaseRenderer::ResetEndOfStream

CBaseRenderer Class

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.

CBaseRenderer::ResetEndOfStreamTimer

CBaseRenderer Class

Cancels the timer that schedules EC_COMPLETE notifications.

Syntax

void ResetEndOfStreamTimer(void);

See Also

SendEndOfStream, TimerCallback.

CBaseRenderer::Run

CBaseRenderer Class

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:

If the filter is not connected, it posts an EC_COMPLETE event immediately.

CBaseRenderer::ScheduleSample

CBaseRenderer Class

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.

CBaseRenderer::SendEndOfStream

CBaseRenderer Class

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_FALSEThe filter graph manager is not accepting event notifications.
S_OKSuccess.

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:

The timer callback method is TimerCallback. To deliver the EC_COMPLETE event, the filter calls the NotifyEndOfStream method.

CBaseRenderer::SendNotifyWindow

CBaseRenderer Class

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.


CBaseRenderer::SendRepaint

CBaseRenderer Class

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:

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.

CBaseRenderer::SetAbortSignal

CBaseRenderer Class

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.

CBaseRenderer::SetMediaType

CBaseRenderer Class

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.

CBaseRenderer::SetRepaintStatus

CBaseRenderer 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.

CBaseRenderer::ShouldDrawSampleNow

CBaseRenderer Class

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_OKThe sample should be rendered immediately.
S_FALSEThe sample should be scheduled for rendering, based on the time stamps.
Error codeDo 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.

CBaseRenderer::SignalTimerFired

CBaseRenderer Class

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.

CBaseRenderer::SourceThreadCanWait

CBaseRenderer Class

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.

CBaseRenderer::StartStreaming

CBaseRenderer Class

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.

CBaseRenderer::Stop

CBaseRenderer Class

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:

CBaseRenderer::StopStreaming

CBaseRenderer Class

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.

CBaseRenderer::TimerCallback

CBaseRenderer Class

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.

CBaseRenderer::WaitForReceiveToComplete

CBaseRenderer Class

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.

CBaseRenderer::WaitForRenderTime

CBaseRenderer Class

Waits for the current sample's presentation time.

Syntax

virtual HRESULT WaitForRenderTime(void);

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
VFW_E_STATE_CHANGEDThe filter state changed before the presentation time arrived.

Remarks

This method waits until one of the following occurs:

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.