Microsoft DirectX 9.0

CCmdQueue Class

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:

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

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

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

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.