This interface defines quality messages and allows a quality manager to install itself as the sink for these messages. The following structures are defined for quality management.

• QualityMessageType
  
  
• Quality
  
  

The IQualityControl::Notifymethod receives a Quality message.

A filter may call IQualityControl::Notifyto send a Quality message to another filter to ask for help in managing the graph quality (typically to achieve graceful degradation on a processor that is not powerful enough to handle all the data).

Quality messages usually flow upstream.

The IQualityControl::SetSinkmethod tells a filter where to send it. If no sink has been explicitly set or if the last SetSinkset the sink to NULL, the message should go upstream.

The filter sends a message upstream by calling QueryInterfaceon the output pin to which its input pin is connected, in order to retrieve an IQualityControlinterface.

Filters export the IQualityControlinterface through their pins.

Messages start with rendering filters, because these must run in real time. Other filters must run to keep the renderers supplied; these do not originate messages, but they can pass them on.

If a filter receives a quality message, it returns S_OK if it agrees to act on the quality message to handle the situation, or S_FALSE if it cannot handle it.

For example, if the video renderer receives S_FALSE (or failure codes), it will readily drop frames to try to maintain synchronization. If it receives S_OK, it will trust the upstream filter; it also will allow frames to be played much earlier than their due time and will allow frames to be played much later without dropping them.

Usually, the video renderer causes early frames to be blocked until their due time, but if this is the first frame after a dropped frame, the video renderer will play the frame as soon as possible so as not to lose time.

A reasonable implementation for a filter that cannot handle a message is to pass the message upstream and to pass on the result. For example:

	Copy Code
HRESULT Notify(IBaseFilter * pSelf, QualityMessage qm) { if (m_QualitySink!=NULL) // Note how pSelf has changed into pMyself return m_QualitySink->ChangeQuality(pMyself, qm); else return m_Upstream->Notify(pMyself, qm); }

A quality managing component would typically set the sink for all filters to itself. It can identify filters by their IBaseFilterinterface pointers in the Selfparameters.

A filter must always supply the same value for its IBaseFilterinterface.

The official COM way of determining if two filters are the same is to use QueryInterfaceon them both for their IUnknowninterfaces and compare those. However, because DirectShow is a real-time system, and because these calls are made during streaming, it is implemented this way for efficiency.

A quality managing component (for example, an application) typically returns S_OK when called upon to help.

However, it should be prepared to find that when it sends a message to a filter requesting help from that filter, it immediately gets a request from that filter for help, and that whatever return code it gives to that filter in response to the request immediately comes back from the filter as the reply to its original message.

This happens if the filter uses the suggested default implementation of passing the messages upstream, but with the Qualitymanaging component intercepting all the traffic.

The Qualitymessage structure is as follows.

	Copy Code
typedef enum { Famine, Flood } QualityMessageType; typedef struct { QualityMessageType Type; long Proportion; REFERENCE_TIME Late; } Quality;

The Typemember of the structure indicates which filter appears to have the problem:

• If set to Famine, the renderer is not getting enough samples and the receiver of the message should speed up by any means possible.
  
  
• If set to Flood, the sender of the message cannot keep up with the data being sent and the receiver must send less data.
  
  

Other methods of degradation are not appropriate.

The Proportionmember gives a rate (expressed in parts per thousand) to be used by a recipient that cannot seek (dropping frames is equivalent to seeking) but can only control its rate.

For example, a proportion of 823 means that it should degrade enough to go faster by a factor of 1000/823. Likewise, a proportion of 1200 means that it can improve its quality by 20 percent, even if this results in going slower.

The numbers are not cumulative.

If a filter can degrade only in steps of, say, 20 percent, and if it receives a series of Qualitymessages all with Proportionequal to 990, it should ignore them all. It should not multiply them (for example, it should not deduce that a 20 percent reduction is called for after the twenty-third message in this case).

The Latemember says how late the application is running at the moment:

• A negative value means there is some slack (probably the renderer is waiting for this time before rendering the samples).
  
  
• A positive value from an audio renderer does not necessarily mean that there is an audio break; it means that the audio renderer's buffer queue is running low and is heading for a break.
  
  

When to Implement

When to Use

Methods in Vtable Order

Requirements