CBaseRenderer Class

CBaseRenderer class hierarchy

CBaseRenderer is the base renderer class for writing renderers. This class handles a single input pin, all state changes, and synchronization.

Protected Data Members

m_bAbort Stop rendering data.
m_bEOS Indicator for whether there are more samples in the stream.
m_bEOSDelivered Indicator for whether an EC_COMPLETE event has been delivered.
m_bRepaintStatus Flag to determine if an EC_REPAINT message can be signaled.
m_bStreaming Indicator for whether the filter graph is currently streaming.
m_dwAdvise Timer advise token returned by the clock.
m_EndOfStreamTimer Time that specifies the end of the stream.
m_evComplete Event signaled when the pause state is complete.
m_InterfaceLock Critical section for interfaces.
m_pInputPin Renderer input pin object.
m_pMediaSample Current media sample about to be, or being rendered.
m_pPosition CRendererPosPassThru object for passing positioning data upstream.
m_pQSink Quality control sink.
m_RendererLock Controller for access to current media sample.
m_RenderEvent Used to signal timer events.
m_SignalTime Amount of time that must elapse before CBaseRenderer returns EC_COMPLETE.
m_ThreadSignal Event signaled to release the source filter thread.

Member Functions

Active Called when the state is switched to paused or running. Override to add functionality.
CBaseRenderer Constructs a CBaseRenderer object.
CheckReady Determines if the event is set.
DisplayRendererState Displays the status of the video renderer. This function is available only in debug mode.
GetRealState Retrieves the actual state of the renderer.
GetRenderEvent Retrieves the event to render.
IsEndOfStream Determines if the end of the stream has been reached.
IsEndOfStreamDelivered Determines if the end of the stream has been delivered to the filter graph manager.
IsStreaming Determines if the filter is currently rendering data.
NotifyEndOfStream Sends an EC_COMPLETE event to the filter graph manager.
NotReady Forces the m_evComplete event into a nonsignaled state.
Ready Puts the m_evComplete event into a signaled state.
ResetEndOfStreamTimer Sets the end of stream timer to zero.
ScheduleSample Sets up an advise link with the clock.
SendNotifyWindow Passes the notification window handle to the upstream filter.
SendRepaint Conditionally signals an EC_REPAINT message to the filter graph.
SetAbortSignal Sets the abort signal flag.
SetRepaintStatus Resets the repaint status flag.
SignalTimerFired Resets the current advise time to zero after a timer fires.
TimerCallback Checks if it is time to signal the end of the current data stream.

Overridable Member Functions

BeginFlush Signals the start of flushing on the input pin.
BreakConnect Breaks the input pin connection and resets the end-of-stream flags.
CancelNotification Cancels any currently scheduled notification with the clock.
CheckMediaType Determines if the renderer will accept a given media type.
ClearPendingSample Called to release the pending sample after it has been rendered.
CompleteConnect Called as part of the connection protocol. Override to add functionality.
CompleteStateChange Ensures that a sample is waiting before allowing a pause.
DoRenderSample Called when a sample is ready to render.
EndFlush Called when the input pin receives an end-flush notification.
EndOfStream Called when the input pin receives an end-of-stream notification.
GetCurrentSample Retrieves the current sample waiting at the video renderer.
GetPin Returns a CBasePin object to the renderer.
GetPinCount Returns the number of input pins supported.
GetMediaPositionInterface Retrieves IMediaPosition and IMediaSeeking interfaces for the video renderer.
GetSampleTimes Retrieves sample time information for this sample.
HaveCurrentSample Determines if a sample is waiting at the renderer.
Inactive Called when going into a stopped state. Override to add functionality.
NonDelegatingQueryInterface Returns an interface and increments the reference count.
OnReceiveFirstSample Provides derived classes with an opportunity to render static data.
OnRenderEnd Notifies the derived class that a sample has just finished rendering.
OnRenderStart Notifies the derived class that a sample is about to be rendered.
OnStartStreaming Notifies the derived class that rendering has started.
OnStopStreaming Notifies the derived class that rendering has stopped.
OnWaitEnd Notifies the derived class that a wait for a rendering time has just ended.
OnWaitStart Notifies the derived class that a wait for a rendering time is about to start.
Pause Tells the renderer to transition to the new (paused) state.
PrepareReceive Called to schedule a clock time when the renderer receives a sample.
PrepareRender Allows derived classes to set themselves just before a sample is rendered.
Receive Called by the source filter when a sample is available to render.
Render Asks the derived class to render the sample.
ResetEndOfStream Resets the end-of-stream flag.
Run Transitions the renderer to State_Running if it is not already in this state.
SendEndOfStream Sets the end-of-stream flag.
SetMediaType Informs the derived class of the selected media type.
ShouldDrawSampleNow Determines if the sample should be drawn between the start and stop times given.
SourceThreadCanWait Sets or resets the thread event.
StartStreaming Called to schedule any pending sample with the clock, and to display any timing information.
Stop Tells the renderer to transition to the new (stopped) state.
StopStreaming Sets an internal flag to indicate not to schedule arrival of any more samples.
WaitForRenderTime Waits for either the time to arrive or for rendering to be stopped.

Implemented IMediaFilter Methods

GetState Determines the state of the renderer.

Implemented IBaseFilter Methods

FindPin Retrieves a pointer to the pin with the specified identifier. (There is only one pin.)

Helper Function

WaitForReceiveToComplete Waits for the CBaseRenderer::Receive method to complete.

CBaseRenderer::Active

CBaseRenderer Class

Called when the state is switched to paused or running.

Syntax

virtual HRESULT Active(void);

Return Value

Returns an HRESULT value. Returns NOERROR by default.

Remarks

This member function does nothing by default. Derived classes can optionally override this member function to add functionality.

CBaseRenderer::BeginFlush

CBaseRenderer Class

Informs the renderer that flushing has started.

Syntax

virtual HRESULT BeginFlush(void);

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This member function is called by CRendererInputPin::BeginFlush when informed of a flush from the upstream filter. It releases the source thread and signals the start of flushing on the input pin. Any samples received by the renderer when it is in a flushing state will be rejected.

CBaseRenderer::BreakConnect

CBaseRenderer Class

Called when a connection is broken.

Syntax

virtual HRESULT BreakConnect(void);

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This member function resets the end-of-stream flag and checks for a valid connection, or that the filter is in a stopped state. Override to customize.

CBaseRenderer::CancelNotification

CBaseRenderer Class

Cancels any currently scheduled notification.

Syntax

virtual HRESULT CancelNotification(void);

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This member function is called when the renderer is told to stop streaming. If there is no timer link outstanding, calling this member function does nothing; otherwise, this function stops the advise link and resets the render event. The typical process when running is to receive a sample, wait until it is time to render it and then render it. The clock is given an event to signal when the desired time arrives.

CBaseRenderer::CBaseRenderer

CBaseRenderer Class

Constructs a CBaseRenderer object.

Syntax

CBaseRenderer(
    REFCLSID RenderClass,
    TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr
);

Parameters

RenderClass
Class identifier for this renderer.
pName
Pointer to the name used for debugging purposes.
pUnk
Pointer to the owner object.
phr
Pointer to the HRESULT return code.

Return Value

No return value.

CBaseRenderer::CheckMediaType

CBaseRenderer Class

Determines if the renderer will accept a given media type.

Syntax

virtual HRESULT CheckMediaType(
    const CMediaType *pmt
    ) PURE;

Parameters

pmt
Pointer to a media type object that contains the proposed media type.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This member function must be overridden and implemented, typically to return the media type of the display. It is called from the CRendererInputPin::CheckMediaType member function during the connection process.

CBaseRenderer::CheckReady

CBaseRenderer Class

Determines if the renderer is ready to process the next sample.

Syntax

BOOL CheckReady(void);

Return Value

Returns TRUE if the m_evComplete event is currently set, but does not block.

Remarks

This member function calls the CAMEvent::Check member function. This is mainly used in transitioning to paused states. When a renderer is paused, it should not complete the state change until it has received some data. So although the call to IMediaFilter::Pause completes immediately, if the application calls IMediaFilter::GetState it will return VFW_S_STATE_INTERMEDIATE. When a sample arrives at the renderer, the event that is initially reset during the pause call will be signaled. At this point, an application calling IMediaFilter::GetState will return NOERROR. This process enables an application to pause a filter graph and then wait until data is actually queued and ready to be rendered.

CBaseRenderer::ClearPendingSample

CBaseRenderer Class

Called to clear the pending sample when in a stopped or inactivated state.

Syntax

virtual HRESULT ClearPendingSample(void);

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This member function releases the IMediaSample interface. This enables the allocator to reuse it and allocate it to the upstream filter again. If the state is being changed to inactive, IMemAllocator::GetBuffer will return an error. This function also resets the current media sample to NULL to indicate that no data is now available.

CBaseRenderer::CompleteConnect

CBaseRenderer Class

Called as part of the connection protocol.

Syntax

virtual HRESULT CompleteConnect(
    IPin *pReceivePin
);

Parameters

pReceivePin
Pointer to the connecting pin.

Return Value

Returns an HRESULT value (NOERROR by default).

Remarks

This member function calls the SetRepaintStatus member function to set the m_bRepaintStatus data member to TRUE so that EC_REPAINT notifications can be sent in the future. (To prevent unnecessary EC_REPAINT notifications from being sent, m_bRepaintStatus is set to FALSE when an end-of-stream notification arrives.)

CBaseRenderer::CompleteStateChange

CBaseRenderer Class

Ensures that a sample is waiting before allowing a pause.

Syntax

virtual HRESULT CompleteStateChange(
    FILTER_STATE OldState
);

Parameters

OldState
State prior to the transition.

Return Value

Returns S_OK if the filter can be paused; otherwise, returns S_FALSE.

Remarks

This member function is called from the CBaseRenderer::Pause member function. If the filter is being paused and there is no sample waiting, the transition is not completed and the function returns S_FALSE until the first sample arrives. However, if the m_bAbort flag has been set, all samples are rejected so there is no point waiting for one. If a sample is available, this member function returns NOERROR.

CBaseRenderer::DisplayRendererState

CBaseRenderer Class

Displays the status of the video renderer. This function is available only in debug mode.

Syntax

void DisplayRendererState(void);

Return Value

No return value.

Remarks

Use this function to monitor the activity of the video renderer. The following is a sample output of this function.

Timed out in WaitForRenderTime
Signal sanity check 0
Filter state 1
Abort flag 0
Streaming flag 0
Clock advise link 0
Current media sample 0
EOS signalled 0
EOS delivered 0
Repaint status 1
End of stream timer 0
Deliver time 0x000000000
Flushing sanity check 0
Last run time 0x000000000
Clock time 0x22C2CD23430
Time difference 238875379ms

CBaseRenderer::DoRenderSample

CBaseRenderer Class

Called when a sample is ready to render.

Syntax

virtual HRESULT DoRenderSample(
    IMediaSample *pMediaSample
    ) PURE;

Parameters

pMediaSample
Pointer to the media sample.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This member function must be overridden in the derived class. It is called by CBaseRenderer::Render.
The derived class should render the object at this time. For example, the sample video renderer (SAMPVID) calls its drawing object (a CDrawImage object):
// Have the drawing object render the current image.

HRESULT CVideoRenderer::DoRenderSample(IMediaSample *pMediaSample)
{
    return m_DrawImage.DrawImage(pMediaSample);
}

CBaseRenderer::EndFlush

CBaseRenderer Class

Called when the input pin receives an end-flush notification.

Syntax

virtual HRESULT EndFlush(void);

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This member function is called from the CRendererInputPin::EndFlush member function. It calls CBaseRenderer::SourceThreadCanWait with a TRUE value to allow the upstream filter's thread to wait in CBaseRenderer::Receive again.

CBaseRenderer::EndOfStream

CBaseRenderer Class

Called when the input pin receives an end-of-stream notification.

Syntax

HRESULT EndOfStream(void);

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

If all received samples have been rendered, this member function notifies EC_COMPLETE. If samples have been received and not yet rendered, this function sets m_bEOS and checks for it on completing samples. If the filter is waiting to be paused, this function completes the transition to paused state by setting the state event.

CBaseRenderer::FindPin

CBaseRenderer Class

Retrieves a pointer to the pin with the specified identifier.

Syntax

HRESULT FindPin(
    LPCWSTR Id,
    IPin **ppPin
);

Parameters

Id
Identifier of the pin.
ppPin
Address of a pointer to the IPin interface for this pin after the renderer has been restored.

Return Value

Returns NOERROR if successful; otherwise, returns VFW_E_NOT_FOUND.

Remarks

This member function implements the IBaseFilter::FindPin method. It assumes that the default pin name is "In" and checks for this. If the pin is found, its reference count is incremented. The ppPin parameter is set to NULL if the identifier cannot be matched.

CBaseRenderer::GetCurrentSample

CBaseRenderer Class

Retrieves the current sample waiting at the video renderer, or NULL if there is not one.

Syntax

virtual IMediaSample *GetCurrentSample(void);

Return Value

Returns a pointer to the sample.

Remarks

The reference count for the sample is incremented before returning. This is so that if the sample comes due for rendering, it is not added back to the allocator free list until the caller of this member function releases it.

CBaseRenderer::GetMediaPositionInterface

CBaseRenderer Class

Retrieves IMediaPosition and IMediaSeeking interfaces for the video renderer.

Syntax

virtual HRESULT GetMediaPositionInterface(
    REFIID riid,
    void **ppv
);

Parameters

riid
Reference identifier.
ppv
Address of a pointer to the interface.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

A CRendererPosPassThru helper object is created dynamically when this is called to support passing the IMediaPosition or IMediaSeeking interface calls from the filter graph manager to the upstream filter.

CBaseRenderer::GetPin

CBaseRenderer Class

Returns a CBasePin object on the renderer.

Syntax

virtual CBasePin *GetPin(
    int n
);

Parameters

n
Number of the specified pin, which is always zero in the case of the renderer.

Return Value

Returns a pointer to the pin specified by the n parameter.

Remarks

This member function overrides CBaseFilter::GetPin. Only one pin is supported on the renderer; it is numbered zero. A call to this member function with n equal to zero will result in an input pin of type CRendererInputPin being returned. It will be created if it does not yet exist.

CBaseRenderer::GetPinCount

CBaseRenderer Class

Retrieves the number of input pins supported.

Syntax

virtual int GetPinCount(void);

Return Value

The default implementation returns 1, because only one pin is supported. Override to support more than one pin. However, because the base renderer class is designed specifically for single-pin operation, considerably more of the base class functionality would have to be changed to make a multipin renderer. Future versions of the SDK might provide this functionality.

Remarks

This member function overrides CBaseFilter::GetPinCount.

CBaseRenderer::GetRealState

CBaseRenderer Class

Retrieves the actual state of the renderer.

Syntax

FILTER_STATE GetRealState(void);

Return Value

Returns m_State, the state flag for the renderer.

Remarks

This member function provides an internal way of getting the real state. Calling through the IBaseFilter interface to get the state would require the main filter critical section to be taken; this internal method does not do this.

CBaseRenderer::GetRenderEvent

CBaseRenderer Class

Retrieves the event to render.

Syntax

CAMEvent *GetRenderEvent(void);

Return Value

Returns the value of m_RenderEvent.

CBaseRenderer::GetSampleTimes

CBaseRenderer Class

Retrieves sample time information for this sample.

Syntax

virtual HRESULT GetSampleTimes(
    IMediaSample *pMediaSample,
    REFERENCE_TIME *pStartTime,
    REFERENCE_TIME *pEndTime
);

Parameters

pMediaSample
Pointer to the media sample.
pStartTime
Pointer to the start time.
pEndTime
Pointer to the end time.

Return Value

Returns S_FALSE if the sample should be scheduled according to the times specified in the sample; returns S_OK to indicate that the sample should be rendered immediately.

Remarks

The sample times are passed in by reference, not value.

CBaseRenderer::GetState

CBaseRenderer Class

Determines the state of the renderer.

Syntax

HRESULT GetState(
    DWORD dwMilliSecsTimeout,
    FILTER_STATE *State
);

Parameters

dwMilliSecsTimeout
Duration of the time-out, in milliseconds.
State
Pointer to the returned state of the renderer.

Return Value

Returns an HRESULT value. Returns VFW_S_STATE_INTERMEDIATE if paused and waiting for a sample; otherwise, returns NOERROR.

Remarks

This member function overrides the CBaseFilter::GetState member function. It returns the value of m_State. Because the renderer does not complete the full transition to the paused state until it has a sample to render, if the state is requested while it is waiting for a sample, it will return VFW_S_STATE_INTERMEDIATE along with the state.

CBaseRenderer::HaveCurrentSample

CBaseRenderer Class

Determines if a sample is waiting at the renderer.

Syntax

virtual BOOL HaveCurrentSample(void);

Return Value

Returns TRUE if a sample is ready to be rendered, or FALSE if no data is available.

CBaseRenderer::Inactive

CBaseRenderer Class

Called when going into a stopped state.

Syntax

virtual HRESULT Inactive(void);

Return Value

Returns NOERROR by default; overriding member function should return a valid HRESULT value.

Remarks

This member function is a placeholder that derived classes can optionally override to add functionality when the filter is stopped.

CBaseRenderer::IsEndOfStream

CBaseRenderer Class

Determines if the end of the stream has been reached.

Syntax

BOOL IsEndOfStream(void);

Return Value

Returns TRUE if the stream's end has been reached, or FALSE if it hasn't.

Remarks

The default implementation returns m_bEOS.

CBaseRenderer::IsEndOfStreamDelivered

CBaseRenderer Class

Determines if the end of the stream has been delivered to the filter graph manager.

Syntax

BOOL IsEndOfStreamDelivered(void);

Return Value

Returns TRUE if the stream's end has been delivered, or FALSE if it hasn't.

Remarks

The default implementation returns m_bEOSDelivered. This is used by the base renderer class so that only one EC_COMPLETE message is sent to the filter graph manager each time it is run, regardless of the number of times EndOfStream is called.

CBaseRenderer::IsStreaming

CBaseRenderer Class

Determines if the filter is streaming data.

Syntax

BOOL IsStreaming(void);

Return Value

Returns TRUE if the filter is rendering, or FALSE if it isn't.

Remarks

The default implementation returns m_bStreaming. In the base renderer class, "streaming" and "rendering" are used in the same context as "running".

CBaseRenderer::NonDelegatingQueryInterface

CBaseRenderer Class

Retrieves an interface and increments the reference count.

Syntax

HRESULT NonDelegatingQueryInterface(
    REFIID riid,
    void **ppv
);

Parameters

riid
Reference identifier.
ppv
Address of a pointer to the interface.

Return Value

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function overrides CBaseFilter::NonDelegatingQueryInterface. It exposes the IMediaPosition and IMediaSeeking interfaces and then calls CBaseFilter::NonDelegatingQueryInterface for interfaces implemented in the base classes.

CBaseRenderer::NotReady

CBaseRenderer Class

Forces the m_evComplete event into a nonsignaled state.

Syntax

void NotReady(void);

Return Value

No return value.

Remarks

This member function calls the CAMEvent::Reset member function of the m_evComplete event object.

CBaseRenderer::NotifyEndOfStream

CBaseRenderer Class

Sends an EC_COMPLETE event to the filter graph manager.

Syntax

void NotifyEndOfStream(void);

Return Value

No return value.

CBaseRenderer::OnReceiveFirstSample

CBaseRenderer Class

Provides derived classes with an opportunity to render static data.

Syntax

virtual void OnReceiveFirstSample(
    IMediaSample *pMediaSample
);

Parameters

pMediaSample
Pointer to the media sample.

Return Value

No return value.

Remarks

This member function is unimplemented. It is primarily used by video renderers. When they receive their first sample while paused, they typically draw the frame as a poster image. This virtual method is called by the base classes when the first sample arrives.

CBaseRenderer::OnRenderEnd

CBaseRenderer Class

Notifies the derived class that rendering has finished.

Syntax

virtual void OnRenderEnd(
    IMediaSample *pMediaSample
);

Parameters

pMediaSample
Pointer to the media sample.

Return Value

No return value.

Remarks

This member function is available for quality management and performance measuring. It is called immediately after the sample is rendered.
Quality management implementations typically need to know how long it takes the renderer to render the data.

CBaseRenderer::OnRenderStart

CBaseRenderer Class

Notifies the derived class that rendering is about to start.

Syntax

virtual void OnRenderStart(
    IMediaSample *pMediaSample
);

Parameters

pMediaSample
Pointer to the media sample.

Return Value

No return value.

Remarks

This member function is available for quality management and performance measuring. It is called immediately before the sample is rendered.
Quality management implementations typically need to know how long it takes the renderer to render the data.

CBaseRenderer::OnStartStreaming

CBaseRenderer Class

Notifies the derived class that streaming has started.

Syntax

virtual HRESULT OnStartStreaming(void);

Return Value

Returns NOERROR in the default implementation.

Remarks

This member function is called from CBaseRenderer::StartStreaming. Override this in your derived class to provide special handling when streaming starts.

CBaseRenderer::OnStopStreaming

CBaseRenderer Class

Notifies the derived class that streaming has stopped.

Syntax

virtual HRESULT OnStopStreaming(void);

Return Value

Returns NOERROR in the default implementation.

Remarks

This member function is called from CBaseRenderer::StopStreaming. Override this in your derived class to provide special handling when streaming stops.

CBaseRenderer::OnWaitEnd

CBaseRenderer Class

Notifies the derived class that a wait for a rendering time has just ended.

Syntax

virtual void OnWaitEnd(void);

Return Value

No return value.

Remarks

This member function is available for quality control and is called from CBaseRenderer::WaitForRenderTime just after waiting for the presentation time for a sample. Override this member function to obtain performance measurements in a derived class.

CBaseRenderer::OnWaitStart

CBaseRenderer Class

Notifies the derived class that a wait for a rendering time is about to start.

Syntax

virtual void OnWaitStart(void);

Return Value

No return value.

Remarks

This member function is available for quality control and is called from CBaseRenderer::WaitForRenderTime just before waiting for the presentation time for a sample. Override this member function to obtain performance measurements in a derived class.

CBaseRenderer::Pause

CBaseRenderer Class

Changes the renderer to State_Paused if it isn't already.

Syntax

HRESULT Pause(void);

Return Value

Returns S_OK if the transition is complete; otherwise, returns one of the following values.

Error value Transition failed.
S_FALSE Transition is not complete, but no error has occurred.

Remarks

The following steps comprise a pause operation.

Commit the allocator used for the connection.
Allow the thread for the upstream filter to wait in Receive.
Cancel any outstanding clock advise links.
Check to see if the renderer is connected and allow a state change.
If a sample is available, complete the state change to State_Paused.

If the member function succeeds, Microsoft® DirectShow® sets the filter's m_State member variable to State_Paused. If the renderer is in the State_Stopped state, DirectShow calls the CBasePin::Active member function for each of the renderer's connected pins.
This member function overrides CBaseFilter::Pause.

CBaseRenderer::PrepareReceive

CBaseRenderer Class

Ensures that a sample can be rendered.

Syntax

virtual HRESULT PrepareReceive(
    IMediaSample *pMediaSample
);

Parameters

pMediaSample
Pointer to the media sample.

Return Value

Returns NOERROR if successful, VFW_E_SAMPLE_REJECTED if the delivered sample is later than the sample's time stamp, or E_UNEXPECTED if a renderable sample is already available.

Remarks

This member function is called when the upstream filter delivers a sample. If the upstream filter is running (streaming), the sample is scheduled with the reference clock. If the upstream filter is not streaming, a sample in paused mode has been received, so any state transition can be completed. On leaving this function, everything will be unlocked so an application thread can get in and change the state to stopped. In this case, it will also signal the thread event so that the wait call is stopped.
This function is typically called from the IMemInputPin::Receive method on the renderer's input pin. Although PrepareReceive returns VFW_E_SAMPLE_REJECTED if the sample was delivered too late to be useful, the IMemInputPin::Receive method should not pass the VFW_E_SAMPLE_REJECTED error on to the upstream filter in this case. Instead, IMemInputPin::Receive should return NOERROR, because no error occurred.

CBaseRenderer::PrepareRender

CBaseRenderer Class

Provides an opportunity for the derived class to prepare itself for rendering a sample.

Syntax

virtual void PrepareRender(void);

Return Value

No return value.

Remarks

This member function is called from CBaseRenderer::Receive before rendering each frame. A derived class can take this opportunity to prepare itself for rendering. For example, a video renderer might realize its palette. This is not implemented in the base class.

CBaseRenderer::Ready

CBaseRenderer Class

Puts the m_evComplete event into a signaled state.

Syntax

void Ready(void);

Return Value

No return value.

Remarks

The m_evComplete event is of type CAMEvent. This function calls m_evComplete's Set member function.

CBaseRenderer::Receive

CBaseRenderer Class

Called by the upstream filter when a sample is available to render.

Syntax

virtual HRESULT Receive(
    IMediaSample *pMediaSample
);

Parameters

pMediaSample
Pointer to the media sample.

Return Value

Returns an HRESULT value.

Remarks

This member function sets an advise link with the clock, waits for the time to arrive, and then renders the data by calling the pure virtual DoRenderSample member function that the derived class will have overridden. After rendering the sample, the end of stream can also be signaled if it was the last one sent before EndOfStream was called.

CBaseRenderer::Render

CBaseRenderer Class

Asks the derived class to render the sample.

Syntax

virtual HRESULT Render(
    IMediaSample *pMediaSample
);

Parameters

pMediaSample
Pointer to the media sample.

Return Value

Returns an HRESULT value.

Remarks

This member function is called when the derived class should render the sample. The action taken is dependent on the nature of the renderer; a video renderer will typically draw the image in a window. This class calls the pure virtual DoRenderSample to be implemented by the derived class.

CBaseRenderer::ResetEndOfStream

CBaseRenderer Class

Resets the end-of-stream flag.

Syntax

virtual HRESULT ResetEndOfStream(void);

Return Value

Returns an HRESULT value.

Remarks

This member function is typically called when changing to stopped states. A renderer must keep track of when it gets told that no more data is going to arrive (this is done when the sourcing filter calls IPin::EndOfStream). At this point the renderer finishes rendering any data it has and then sends an EC_COMPLETE event to the filter graph manager.
However, when the filter is stopped, the whole state is cleared. When the filter is subsequently run, the source filter will signal the end of stream again if it has no data to send. In this case, the renderer should signal another EC_COMPLETE event to the filter graph manager. This member function resets the state so that when next requested it will send an EC_COMPLETE event.

CBaseRenderer::ResetEndOfStreamTimer

CBaseRenderer Class

If the end-of-stream timer is nonzero, this function sets it to zero.

Syntax

void ResetEndOfStreamTimer(void);

Return Value

No return value.

CBaseRenderer::Run

CBaseRenderer Class

Transitions the renderer to State_Running if it is not in this state already.

Syntax

HRESULT Run(void);

Return Value

Returns an HRESULT value.

Remarks

If the renderer is in the State_Stopped state, the CBaseRenderer::Pause member function is called first to transition the renderer to the State_Paused state, which has the effect of activating any of the filter's connected pins. If this member function succeeds, the renderer's m_State member variable is set to State_Running.
This member function overrides CBaseFilter::Run.

CBaseRenderer::ScheduleSample

CBaseRenderer Class

Schedules the sample for rendering.

Syntax

virtual BOOL ScheduleSample(
    IMediaSample *pMediaSample
);

Parameters

pMediaSample
Pointer to the media sample.

Return Value

No return value.

Remarks

One of the main purposes of the renderer base class is to manage the timing and synchronization of the samples it is sent; that is, the timely presentation of data. It also must look after quality management, which might involve dropping samples or rendering them earlier than indicated in the time stamps on the sample. This method and its overrides in derived classes manage the setting up of advise links with the clock, so that the samples can be rendered at the appropriate time.

CBaseRenderer::SendEndOfStream

CBaseRenderer Class

Signals an EC_COMPLETE event to the filter graph manager.

Syntax

virtual HRESULT SendEndOfStream(void);

Return Value

Returns an HRESULT value.

Remarks

When the renderer receives an end-of-stream notification, it will finish rendering any data it currently has and then send an EC_COMPLETE event to the filter graph manager.

CBaseRenderer::SendNotifyWindow

CBaseRenderer Class

Passes the notification window handle to the upstream filter.

Syntax

void SendNotifyWindow(
    IPin *pPin,
    HWND hwnd
);

Parameters

pPin
Pointer to the IPin interface of the upstream pin.
hwnd
Handle of the notification window.

Return Value

No return value.

Remarks

If the output pin of the upstream filter supports the IMediaEventSink interface, this member function sends it the EC_NOTIFY_WINDOW event code with the window handle in hwnd.

CBaseRenderer::SendRepaint

CBaseRenderer Class

Signals an EC_REPAINT message to the filter graph.

Syntax

void SendRepaint(void);

Return Value

No return value.

Remarks

This should be used with some care. EC_REPAINT events are processed by the filter graph manager by setting the current position to the same position that the graph is currently in. This has the effect of sending the same data through the graph again, which is an expensive operation. Video renderers are the main users of this event, because they sometimes need the same image sent again to refresh the display.

CBaseRenderer::SetAbortSignal

CBaseRenderer Class

Sets the m_bAbort abort signal flag.

Syntax

void SetAbortSignal(
    BOOL bAbort
);

Parameters

bAbort
Abort value to be set.

Return Value

Returns an HRESULT value.

CBaseRenderer::SetMediaType

CBaseRenderer Class

Informs the derived class of the selected media type.

Syntax

virtual HRESULT SetMediaType(
    const CMediaType *pmt
);

Parameters

pmt
Pointer to the media type to be set.

Return Value

Returns NOERROR by default; the overriding member function should return a valid HRESULT value.

Remarks

This member function is called by the CRendererInputPin::SetMediaType member function and has no implementation in this class. Derived classes can optionally override to add functionality.

CBaseRenderer::SetRepaintStatus

CBaseRenderer Class

Resets the m_bRepaintStatus flag when EC_REPAINT has been signaled to the filter graph.

Syntax

void SetRepaintStatus(
    BOOL bRepaint
);

Parameters

bRepaint
Value assigned to the m_bRepaintStatus flag.

Return Value

No return value.

Remarks

The m_bRepaintStatus flag ensures that the filter graph is not flooded with redundant calls. After one EC_REPAINT message has been sent, no more will be sent until the renderer receives some data.

CBaseRenderer::ShouldDrawSampleNow

CBaseRenderer Class

Determines if the sample should be drawn between the start and stop times given.

Syntax

virtual HRESULT ShouldDrawSampleNow(
    IMediaSample *pMediaSample,
    REFERENCE_TIME *pStartTime,
    REFERENCE_TIME *pEndTime
);

Parameters

pMediaSample
Pointer to the media sample.
pStartTime
Pointer to the start time in question.
pEndTime
Pointer to the end time in question.

Return Value

Returns S_FALSE by default. The overriding member function can return S_OK to indicate that the sample should be drawn immediately instead of waiting for its scheduled time.

Remarks

This member function is used by the derived video renderer class for quality management.

CBaseRenderer::SignalTimerFired

CBaseRenderer Class

Resets the current advise time to zero after a timer fires.

Syntax

virtual void SignalTimerFired(void);

Return Value

No return value.

CBaseRenderer::SourceThreadCanWait

CBaseRenderer Class

Sets or resets the thread event.

Syntax

virtual HRESULT SourceThreadCanWait(
    BOOL bCanWait
);

Parameters

bCanWait
TRUE or FALSE, depending on intent.

Return Value

Returns an HRESULT value.

Remarks

In some states, such as paused or running, it is expected that the upstream filter's thread will be blocked in the call to the renderer's input pin Receive method. In other cases, such as when the renderer is stopped, the upstream filter should not be required to wait. This member function represents a manual reset event that sets this TRUE to wait, or FALSE to keep the thread from waiting.

CBaseRenderer::StartStreaming

CBaseRenderer Class

Called to schedule any pending sample with the clock, and to display timing information.

Syntax

virtual HRESULT StartStreaming(void);

Return Value

Returns an HRESULT value.

Remarks

If no sample is available but an end-of-stream flag is queued, this member function sends an EC_COMPLETE message to the filter graph manager. If a sample is available, the EC_COMPLETE message will not be sent until it has been rendered.

CBaseRenderer::Stop

CBaseRenderer Class

Transitions the renderer to State_Stopped if it is not in this state already.

Syntax

HRESULT Stop(void);

Return Value

Returns an HRESULT value.

Remarks

If the renderer is not in the State_Stopped state, the CRendererInputPin::Inactive member function is called for each of the renderer's connected pins. If this member function succeeds, the filter's m_State member variable is set to State_Stopped.
This member function overrides CBaseFilter::Stop.

CBaseRenderer::StopStreaming

CBaseRenderer Class

Sets the internal flag to indicate not to schedule arrival of any more samples.

Syntax

virtual HRESULT StopStreaming(void);

Return Value

Returns an HRESULT value.

Remarks

Call this member function when streaming stops. The state change methods in the filter implementation take care of canceling any clock advise link that has been set up and clearing any pending sample.

CBaseRenderer::TimerCallback

CBaseRenderer Class

Checks if it is time to signal the end of the current data stream.

Syntax

void TimerCallback(void);

Return Value

No return value.

Remarks

If the m_EndOfStreamTimer data member is nonzero, this function sets it to zero and calls CBaseRenderer::SendEndOfStream to signal the end of the current data stream.

CBaseRenderer::WaitForReceiveToComplete

CBaseRenderer Class

Waits for the CBaseRenderer::Receive method to complete.

Syntax

void WaitForReceiveToComplete(void);

Return Value

No return value.

Remarks

Use this method when you want to avoid deadlock that occurs when CBaseRenderer::Stop is called and the CBaseRenderer::Receive function hasn't completed.

CBaseRenderer::WaitForRenderTime

CBaseRenderer Class

Waits for either the due time for the current sample to arrive or for rendering to be stopped.

Syntax

virtual HRESULT WaitForRenderTime(void);

Return Value

Returns an HRESULT value.

Remarks

The member function is virtual because derived classes might have more events that they also want to wait on, which might interrupt the waiting process. The base class has two events: m_RenderEvent and m_ThreadSignal. The former is signaled by the clock when the sample is due for rendering. The latter is signaled by the filter when it should give up waiting and abort (making the assumption that the filter was stopped).

m_bAbort	Stop rendering data.
m_bEOS	Indicator for whether there are more samples in the stream.
m_bEOSDelivered	Indicator for whether an EC_COMPLETE event has been delivered.
m_bRepaintStatus	Flag to determine if an EC_REPAINT message can be signaled.
m_bStreaming	Indicator for whether the filter graph is currently streaming.
m_dwAdvise	Timer advise token returned by the clock.
m_EndOfStreamTimer	Time that specifies the end of the stream.
m_evComplete	Event signaled when the pause state is complete.
m_InterfaceLock	Critical section for interfaces.
m_pInputPin	Renderer input pin object.
m_pMediaSample	Current media sample about to be, or being rendered.
m_pPosition	CRendererPosPassThru object for passing positioning data upstream.
m_pQSink	Quality control sink.
m_RendererLock	Controller for access to current media sample.
m_RenderEvent	Used to signal timer events.
m_SignalTime	Amount of time that must elapse before CBaseRenderer returns EC_COMPLETE.
m_ThreadSignal	Event signaled to release the source filter thread.

Active	Called when the state is switched to paused or running. Override to add functionality.
CBaseRenderer	Constructs a CBaseRenderer object.
CheckReady	Determines if the event is set.
DisplayRendererState	Displays the status of the video renderer. This function is available only in debug mode.
GetRealState	Retrieves the actual state of the renderer.
GetRenderEvent	Retrieves the event to render.
IsEndOfStream	Determines if the end of the stream has been reached.
IsEndOfStreamDelivered	Determines if the end of the stream has been delivered to the filter graph manager.
IsStreaming	Determines if the filter is currently rendering data.
NotifyEndOfStream	Sends an EC_COMPLETE event to the filter graph manager.
NotReady	Forces the m_evComplete event into a nonsignaled state.
Ready	Puts the m_evComplete event into a signaled state.
ResetEndOfStreamTimer	Sets the end of stream timer to zero.
ScheduleSample	Sets up an advise link with the clock.
SendNotifyWindow	Passes the notification window handle to the upstream filter.
SendRepaint	Conditionally signals an EC_REPAINT message to the filter graph.
SetAbortSignal	Sets the abort signal flag.
SetRepaintStatus	Resets the repaint status flag.
SignalTimerFired	Resets the current advise time to zero after a timer fires.
TimerCallback	Checks if it is time to signal the end of the current data stream.

BeginFlush	Signals the start of flushing on the input pin.
BreakConnect	Breaks the input pin connection and resets the end-of-stream flags.
CancelNotification	Cancels any currently scheduled notification with the clock.
CheckMediaType	Determines if the renderer will accept a given media type.
ClearPendingSample	Called to release the pending sample after it has been rendered.
CompleteConnect	Called as part of the connection protocol. Override to add functionality.
CompleteStateChange	Ensures that a sample is waiting before allowing a pause.
DoRenderSample	Called when a sample is ready to render.
EndFlush	Called when the input pin receives an end-flush notification.
EndOfStream	Called when the input pin receives an end-of-stream notification.
GetCurrentSample	Retrieves the current sample waiting at the video renderer.
GetPin	Returns a CBasePin object to the renderer.
GetPinCount	Returns the number of input pins supported.
GetMediaPositionInterface	Retrieves IMediaPosition and IMediaSeeking interfaces for the video renderer.
GetSampleTimes	Retrieves sample time information for this sample.
HaveCurrentSample	Determines if a sample is waiting at the renderer.
Inactive	Called when going into a stopped state. Override to add functionality.
NonDelegatingQueryInterface	Returns an interface and increments the reference count.
OnReceiveFirstSample	Provides derived classes with an opportunity to render static data.
OnRenderEnd	Notifies the derived class that a sample has just finished rendering.
OnRenderStart	Notifies the derived class that a sample is about to be rendered.
OnStartStreaming	Notifies the derived class that rendering has started.
OnStopStreaming	Notifies the derived class that rendering has stopped.
OnWaitEnd	Notifies the derived class that a wait for a rendering time has just ended.
OnWaitStart	Notifies the derived class that a wait for a rendering time is about to start.
Pause	Tells the renderer to transition to the new (paused) state.
PrepareReceive	Called to schedule a clock time when the renderer receives a sample.
PrepareRender	Allows derived classes to set themselves just before a sample is rendered.
Receive	Called by the source filter when a sample is available to render.
Render	Asks the derived class to render the sample.
ResetEndOfStream	Resets the end-of-stream flag.
Run	Transitions the renderer to State_Running if it is not already in this state.
SendEndOfStream	Sets the end-of-stream flag.
SetMediaType	Informs the derived class of the selected media type.
ShouldDrawSampleNow	Determines if the sample should be drawn between the start and stop times given.
SourceThreadCanWait	Sets or resets the thread event.
StartStreaming	Called to schedule any pending sample with the clock, and to display any timing information.
Stop	Tells the renderer to transition to the new (stopped) state.
StopStreaming	Sets an internal flag to indicate not to schedule arrival of any more samples.
WaitForRenderTime	Waits for either the time to arrive or for rendering to be stopped.

E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Error value	Transition failed.
S_FALSE	Transition is not complete, but no error has occurred.