CCmdQueue class

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The CCmdQueue class is a base class that provides a queue of CDeferredCommand objects and member functions to add, remove, check status, and invoke the queued commands. A CCmdQueue object is a part of an object that implements IQueueCommand methods. The filter graph manager implements IQueueCommand methods so that applications can queue commands to the filter graph. Filters that implement the IQueueCommand interface directly use this class. If you want to use CDeferredCommand objects, your queue must be derived from this class.

There are two modes of synchronization: coarse and accurate. In coarse mode, the application waits until a specified time arrives and then executes the command. In accurate mode, the application waits until processing begins on the sample that appears at the time, and then executes the command. The filter determines which one it will implement. The filter graph manager always implements coarse mode for commands that are queued at the filter graph manager.

If you want coarse synchronization, you probably want to wait until there is a command due, and then execute it. You can do this by calling CCmdQueue::GetDueCommand. If you have several things to wait for, get the event handle from CCmdQueue::GetDueHandle and then call CCmdQueue::GetDueCommand when this is signaled. stream time will advance only between calls to the CCmdQueue::Run and CCmdQueue::EndRun member functions. There is no guarantee that if the handle is set, there will be a command ready. Each time the event is signaled, call the GetDueCommand member function (probably with a time-out of zero); this can return E_ABORT if no command is ready.

If you want accurate synchronization, call the CCmdQueue::GetCommandDueFor member function and pass the samples you are about to process as a parameter. This returns the following:

• A stream-time command due at or before that stream time.
• A presentation-time command due at or before the presentation of the stream time. Do this only between the CCmdQueue::Run and CCmdQueue::EndRun member functions, because outside of this, the mapping from stream time to presentation time is not known.
• Any presentation-time command due now.

If you want accurate synchronization for samples that might be processed during paused mode, you must use stream-time commands.

In all cases, commands remain queued until called or canceled. The setting and resetting of the event handle is managed entirely by this queue object.

Protected Data Members	Description
m_bRunning	Flag for running state; set TRUE when running.
m_dwAdvise	Advise identifier from the reference clock (zero if no outstanding advise).
m_evDue	Sets the time when any commands are due.
m_listPresentation	Stores commands queued in presentation time.
m_listStream	Stores commands queued in stream time.
m_Lock	Protects access to lists.
m_pClock	Current reference clock.
m_StreamTimeOffset	Contains the stream time offset when m_bRunning is TRUE.
m_StreamTimeOffset	Contains the stream time offset when m_bRunning is TRUE.
Member Functions	Description
CCmdQueue	Constructs a CCmdQueue object.
CheckTime	Determines if a given time is due.
GetDueHandle	Retrieves the event handle that will be signaled.
Overridable Member Functions	Description
EndRun	Switches to stopped or paused mode.
GetCommandDueFor	Retrieves a deferred command that is scheduled at a specified time.
GetDueCommand	Retrieves a pointer to the next command that is due.
Insert	Adds the CDeferredCommand object to the queue.
New	Initializes a command to be run and returns a new CDeferredCommand object.
Remove	Removes the CDeferredCommand object from the queue.
Run	Switches to running mode.
SetSyncSource	Sets the clock used for timing.
SetTimeAdvise	Sets up a timer event with the reference clock.