## CBaseVideoRenderer Class

This base class is used for building video renderer filters.

Protected Data Members

Name | Description
m_bDrawLateFrames | Flag to signal that no frames are to be dropped. Debug only. This destroys synchronization.
m_bSupplierHandlingQuality | TRUE indicates quality control messages are being handled. This lets the renderer know to wait until as late as possible to drop frames itself, and to display the next frame very early after the supplier has dropped a frame.
m_cFramesDrawn | Total number of frames that have been drawn since streaming started.
m_cFramesDropped | Cumulative frames that have been dropped in the renderer since streaming started. Frames can also be dropped upstream without the renderer recognizing them.
m_idDecision | MSR_id for the decision code of ShouldDrawSampleNow.
m_idDuration | MSR_id for the duration of a frame.
m_idFrameAccuracy | Performance log identifier for the time in milliseconds that the frame was late.
m_idFrameAvg | Performance log identifier for the average frame time that is used for synchronization and quality control.
m_idQualityRate | MSR_id for the quality rate requested.
m_idQualityTime | MSR_id for the quality time requested.
m_idRenderAvg | Performance log identifier for the average renderer time recorded.
m_idSchLateTime | MSR_id for how late the frame was when scheduled.
m_idSendQuality | MSR_id for timing the notifications (unused).
m_idTimeStamp | MSR_id for a frame time stamp.
m_idWait | Performance log identifier for the recorded wait time (unused).
m_idWaitReal | Performance log identifier for the true wait time.
m_iSumFrameTime | Sum of the interframe times; needed for the property page.
m_iSumSqAcc | Sum of the squares of the accuracies (in milliseconds) needed for the property page.
m_iSumSqFrameTime | Sum of the squares of interframe times; needed for the property page.
m_iTotAcc | Sum of the accuracies (in milliseconds) needed for the property page.
m_nNormal | Number of consecutive frames drawn at their scheduled time. A negative number indicates that a frame has just been dropped by the renderer.
m_trDuration | Duration of the last frame (difference between the start and end times).
m_trEarliness | How early a frame is allowed to be played when a frame has just been dropped.
m_trFrame | Most recently recorded time between frames. Used in statistical measurements.
m_trFrameAvg | Average interframe time in reference time units.
m_trLastDraw | Time of previous frame. Used for interframe time references.
m_trLate | Amount of time that the current frame was late. Used in statistical measurements.
m_trRenderAvg | Time that frames are taking to perform the bit-block transfer.
m_trRenderLast | Time for the last frame bit-block transfer.
m_trRenderStart | Time the bit-block transfer started. Used to get m_trRenderLast.
m_trThrottle | Period to insert after rendering each frame, typically used when audio quality has been increased and video performance must be decreased to allow this.
m_trWaitAvg | Average wait time in reference time units.
m_tStreamingStart | Used for property page statistics. Represents the start time of the current streaming process or the previous streaming process if not currently streaming.

Member Functions

Name | Description
CBaseVideoRenderer | Constructs a CBaseVideoRenderer object.
GetStdDev | Estimates the standard deviation in milliseconds between when each frame is due and when it is actually rendered, for per-frame statistics.
PreparePerformanceData | Sets the m_trLate and m_trFrame values of the current frame.
ThrottleWait | Inserts a wait period after each frame.

Overridable Member Functions

Name | Description
JoinFilterGraph | Sends EC_WINDOW_DESTROYED event notification when filter is removed from the filter graph.
OnDirectRender | Collects timing information that controls synchronization and quality control.
OnRenderEnd | Records information for quality control and synchronization.
OnRenderStart | Records information for quality control and synchronization.
OnStartStreaming | Resets all times that control streaming.
OnStopStreaming | Called at the end of streaming to fix times for the property page report.
OnWaitEnd | Called when a wait time ends. Performance logging only.
OnWaitStart | Updates times spent waiting and not waiting. Performance logging only.
RecordFrameLateness | Records how timely the rendering occurred and gathers statistics for the property page.
ResetStreamingTimes | Resets all times that control the streaming.
ScheduleSample | Sets up an advise link with the clock.
SendQuality | Sends a quality message to indicate what the supplier should do about quality.
ShouldDrawSampleNow | Determines if the video should be drawn when it is due, without setting a timer advise link with the clock.

Implemented IQualProp Methods

Name | Description
get_AvgFrameRate | Retrieves the average frame rate since streaming started in frames per 100 seconds.
get_AvgSyncOffset | Retrieves the average of the time in milliseconds between when each frame was due and when it was actually rendered. This applies to all frames since streaming started.
get_DevSyncOffset | Retrieves the standard deviation of the time in milliseconds between when each frame was due and when it was actually rendered for all frames since streaming started.
get_FramesDrawn | Retrieves the number of frames drawn since streaming started.
get_FramesDroppedInRenderer | Retrieves the number of frames dropped by the renderer. Frames can also be dropped upstream.
get_Jitter | Retrieves the standard deviation of the time in milliseconds between each frame and the next. This applies to all frames since streaming started.

Implemented INonDelegatingUnknown Methods

Name | Description
NonDelegatingQueryInterface | Provides access to other interfaces, particularly the property page.

Implemented IQualityControl Methods

Name | Description
Notify | Notifies the recipient that a quality change is requested.
SetSink | Sets the IQualityControl object that will receive quality messages.

###

CBaseVideoRenderer::CBaseVideoRenderer

CBaseVideoRenderer Class

Constructs a CBaseVideoRenderer object.

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

##### Parameters

RenderClass
  Class identifier for this renderer.
pName
  Description used for debugging purposes.
pUnk
  Pointer to the aggregated owner object.
phr
  Pointer to an HRESULT value.

##### Return Values

No return value.

###

CBaseVideoRenderer::get_AvgFrameRate

CBaseVideoRenderer Class

Calculates and retrieves the average frame rate achieved.

HRESULT get_AvgFrameRate(
int *piAvgFrameRate
);

##### Parameters

piAvgFrameRate
  Number of frames per second since streaming began.

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function implements the IQualProp::get_AvgFrameRate method.

###

CBaseVideoRenderer::get_AvgSyncOffset

CBaseVideoRenderer Class

Retrieves the average of the time in milliseconds between when each frame was due and when it was actually rendered for all frames since streaming started.

HRESULT get_AvgSyncOffset(
int *piAvg
);

##### Parameters

piAvg
  Pointer to the average of the time as previously described.

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function implements the IQualProp::get_AvgSyncOffset method.

###

CBaseVideoRenderer::get_DevSyncOffset

CBaseVideoRenderer Class

Retrieves the standard deviation of the time in milliseconds between when each frame was due and when it was actually rendered, for all frames since streaming started.

HRESULT get_DevSyncOffset(
int *piDev
);

##### Parameters

piDev
  Pointer to the standard deviation of the time as previously described.

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function implements the IQualProp::get_DevSyncOffset method.

###

CBaseVideoRenderer::get_FramesDrawn

CBaseVideoRenderer Class

Retrieves the m_cFramesDrawn member variable, giving the number of frames drawn since streaming started.

HRESULT get_FramesDrawn(
int *pcFramesDrawn
);

##### Parameters

pcFramesDrawn
  Number of frames drawn.

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function implements the IQualProp::get_FramesDrawn method.

###

CBaseVideoRenderer::get_FramesDroppedInRenderer

CBaseVideoRenderer Class

Retrieves the number of frames dropped by the renderer.

HRESULT get_FramesDroppedInRenderer(
int *pcFramesDropped
);

##### Parameters

pcFramesDropped
  Number of frames dropped.

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function implements the IQualProp::get_FramesDroppedInRenderer method. This is how the property page retrieves the data from the scheduler. Note that frames can also be dropped upstream without the renderer even seeing them.

###

CBaseVideoRenderer::get_Jitter

CBaseVideoRenderer Class

Retrieves the standard deviation of time in milliseconds between each frame and the next for all frames since streaming started.

HRESULT get_Jitter(
int *piJitter
);

##### Parameters

piJitter
  Standard deviation of the interframe time in milliseconds.

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function implements the IQualProp::get_Jitter method.

###

CBaseVideoRenderer::GetStdDev

CBaseVideoRenderer Class

Estimates the standard deviation in milliseconds between when each frame is due and when it is actually rendered, for per-frame statistics.

HRESULT GetStdDev(
int nSamples,
int *piResult,
LONGLONG llSumSq,
LONGLONG iTot
);

##### Parameters

nSamples
  Integer value that contains the number of video samples received by the video renderer.
piResult
  Pointer to an integer value that will contain the standard deviation.
llSumSq
  Value that represents the standard deviation, in milliseconds, of all rendered video samples. The lower the value, the more consistent the rendering.
iTot
  Value that represents the mean value, in milliseconds, between the stamped time and rendered time for all rendered video samples.

##### Return Values

Returns NOERROR.

###

CBaseVideoRenderer::JoinFilterGraph

CBaseVideoRenderer Class

Sends EC_WINDOW_DESTROYED event notification when a filter is removed from the filter graph.

HRESULT JoinFilterGraph(
IBaseFilterGraph * pGraph,
LPCWSTR pName
);

##### Parameters

pGraph
  Pointer to the filter graph to join.
pName
  [in, string] Name of the filter being added.

##### Return Values

No return value.

##### Remarks

This member function overrides the CBaseFilter::JoinFilterGraph member function. If this function determines that the filter is being notified that it is leaving the filter graph (pGraph is null, but m_pGraph is not), it sends an EC_WINDOW_DESTROYED event notification so that the resource manager does not hold on to the renderer as a focus object.

###

CBaseVideoRenderer::NonDelegatingQueryInterface

CBaseVideoRenderer Class

Returns an interface and increments the reference count.

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

##### Parameters

riid
  Reference identifier.
ppv
  Pointer to the interface.

##### Return Values

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

##### Remarks

Override this member function to publish the interface.

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method. It exposes the IQualProp interface and then calls CBaseRenderer::NonDelegatingQueryInterface to expose interfaces implemented in the base classes.

###

CBaseVideoRenderer::Notify

CBaseVideoRenderer Class

Receives a notification that a quality change is requested.

HRESULT Notify(
IBaseFilter * pSelf,
Quality q
);

##### Parameters

pSelf
  [in] Pointer to the filter that is sending the quality notification.
q
  [in] Quality notification structure.

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function implements the IQualityControl::Notify method on the video renderer. This is called, typically by the filter graph manager, when the quality must be cut back. This might occur when the quality of audio playback has been increased to the point that the video playback quality must be decreased.

Notify sets the m_trThrottle data member to a delay value to be inserted between frames by ThrottleWait.

###

CBaseVideoRenderer::OnDirectRender

CBaseVideoRenderer Class

Collects timing information that controls synchronization and quality control.

virtual void OnDirectRender(
IMediaSample *pMediaSample
);

##### Parameters

pMediaSample
  Media sample.

##### Return Values

Returns an HRESULT value.

##### Remarks

Call this member function instead of OnRenderStart and OnRenderEnd. This is used by the Microsoft® DirectDraw® video renderer.

###

CBaseVideoRenderer::OnRenderEnd

CBaseVideoRenderer Class

Performs smoothing for cases where the rendering time varies due to interruptions.

void OnRenderEnd(
IMediaSample *pMediaSample
);

##### Parameters

pMediaSample
  Media sample.

##### Return Values

No return value.

##### Remarks

This member function should be called just after drawing an image.

This member function overrides CBaseRenderer::OnRenderEnd.

###

CBaseVideoRenderer::OnRenderStart

CBaseVideoRenderer Class

Sets information for rendering.

void OnRenderStart(
IMediaSample *pMediaSample
);

##### Parameters

pMediaSample
  Media sample.

##### Return Values

No return value.

##### Remarks

This member function retrieves the current clock time from the system and stores it in a member variable to be used when the drawing is complete. The function also performs performance logging. This member function should be called just before drawing starts.

This member function overrides CBaseRenderer::OnRenderStart.

###

CBaseVideoRenderer::OnStartStreaming

CBaseVideoRenderer Class

Resets all times that control streaming.

HRESULT OnStartStreaming(void);

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function overrides CBaseRenderer::OnStartStreaming.

###

CBaseVideoRenderer::OnStopStreaming

CBaseVideoRenderer Class

Called at the end of streaming to fix times for the property page report.

HRESULT OnStopStreaming(void);

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function is called twice, once when pausing and again when the stream is actually stopped.

This member function overrides CBaseRenderer::OnStopStreaming.

###

CBaseVideoRenderer::OnWaitEnd

CBaseVideoRenderer Class

Called when a wait time ends.

void OnWaitEnd(void);

##### Return Values

No return value.

##### Remarks

This member function does only performance logging. It is called when the thread is awoken from waiting in the window, or when the next sample is due to be rendered. It could eventually be used to gather information that controls synchronization.

###

CBaseVideoRenderer::OnWaitStart

CBaseVideoRenderer Class

Updates times spent waiting and not waiting.

void OnWaitStart(void);

##### Return Values

No return value.

##### Remarks

This member function is called when starting to wait for a rendering event. It is used only for performance measurements.

###

CBaseVideoRenderer::PreparePerformanceData

CBaseVideoRenderer Class

Sets the m_trLate and m_trFrame values of the current frame.

void PreparePerformanceData(
int trLate,
int trFrame
);

##### Parameters

trLate
  How late the sample was beyond its due time, in reference time units.
trFrame
  Interframe time, in reference time units.

##### Return Values

No return value.

##### Remarks

This member function sets m_trLate to the value of trLate and m_trFrame to the value of trFrame.

When the CBaseVideoRenderer::RecordFrameLateness member function is called from either CBaseVideoRenderer::OnRenderStart or CBaseVideoRenderer::OnDirectRender, it passes the values of m_trLate and m_trFrame for it to update the statistics. PreparePerformanceData is called from CBaseVideoRenderer::OnWaitEnd to set these data member values.

###

CBaseVideoRenderer::RecordFrameLateness

CBaseVideoRenderer Class

Records how timely the rendering occurred and gathers statistics for the property page.

virtual void RecordFrameLateness(
int trLate,
int trFrame
);

##### Parameters

trLate
  How late the sample was beyond its due time, in reference time units.
trFrame
  Interframe time, in reference time units.

##### Return Values

No return value.

###

CBaseVideoRenderer::ResetStreamingTimes

CBaseVideoRenderer Class

Resets all times that control the streaming.

virtual HRESULT ResetStreamingTimes(void);

##### Return Values

Returns an HRESULT value.

##### Remarks

The times are set so that frames will not be initially dropped and so that the first frame will be drawn.

###

CBaseVideoRenderer::ScheduleSample

CBaseVideoRenderer Class

Overrides the base class that does the main work to keep a count of samples drawn and dropped (which are used by the IQualProp implementation).

BOOL ScheduleSample(
IMediaSample *pMediaSample
);

##### Parameters

pMediaSample
  Media sample.

##### Return Values

Returns TRUE if the sample is scheduled; otherwise, returns FALSE.

###

CBaseVideoRenderer::SendQuality

CBaseVideoRenderer Class

Sends a quality message to indicate what the supplier should do about quality.

virtual HRESULT SendQuality(
REFERENCE_TIME trLate,
REFERENCE_TIME trRealStream
);

##### Parameters

trLate
  Amount of time by which the frame is late.
trRealStream
  Current stream time.

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function sends a quality control message upstream to control quality management. The nature of the quality message (that is, whether to reduce or increase the number of samples) is determined in the quality management implementation in this derived class (see CBaseVideoRenderer::ShouldDrawSampleNow).

###

CBaseVideoRenderer::SetSink

CBaseVideoRenderer Class

Sets the IQualityControl object that will receive quality messages.

HRESULT SetSink(
IQualityControl *piqc
);

##### Parameters

piqc
  Pointer to the IQualityControl object to which the notifications should be sent.

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function implements the IQualityControl::SetSink method on the video renderer.

###

CBaseVideoRenderer::ShouldDrawSampleNow

CBaseVideoRenderer Class

Determines if the video should be drawn without setting a timer advise link with the clock.

virtual HRESULT ShouldDrawSampleNow(
IMediaSample *pMediaSample,
REFERENCE_TIME *ptrStart,
REFERENCE_TIME *ptrEnd
);

##### Parameters

pMediaSample
  IMediaSample interface for the sample.
ptrStart
  Time to begin rendering.
ptrEnd
  Time to stop rendering.

##### Return Values

Returns an HRESULT value. Returns S_OK to mean draw at once without waiting, S_FALSE to mean draw at time ptrStart, or error to mean do not draw the sample; that is, skip it to save time.

##### Remarks

This member function overrides CBaseRenderer::ShouldDrawSampleNow.

###

CBaseVideoRenderer::ThrottleWait

CBaseVideoRenderer Class

Inserts a wait period after each frame.

void ThrottleWait(void);

##### Return Values

No return value.

##### Remarks

This member function waits for a time period obtained from the m_trThrottle data member.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.