This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

MediaControl

Functions to control a filter

Synopsis:

static MediaControl media_control =
{
  Start,
  Stop,
  Pause,
  Resume,
  Status
};

Description:

This interface defines the functions required to control a filter. Filter control is usually necessary only for final output filters, such as audio output or video display, but may also be required if your filter spawns worker threads you'd like to start, stop, pause, or resume.

Start()

int32_t (*Start)(MmFilter_t *filter,
                 MmTime_t start_time);

This function should start the filter in a paused state. Don't think of this as starting the decoding. This function is called when a graph has been constructed and it's ready to go. Once it's started, you can use Resume() to begin decoding/playback.

If the start_time is nonzero, the filter should seek to the given time, if it can.

If successful, this function should return 0.

Stop()

int32_t (*Stop)(MmFilter_t *filter); 

This function should stop the filter. Use Stop() only when you're about to remove or delete the filter. You should signal any running threads to stop at the point when you call Stop().

If successful, this function should return 0.

Pause()

int32_t (*Pause)(MmFilter_t *filter);

This function should pause playback of the filter temporarily. If you are going to call Seek() on a filter, you should first Pause(), then Seek(), and then Resume().

If the filter has a running thread, it will most likely set its status to MM_STATUS_PAUSING in the Pause() function, which the thread will recognize, and change to MM_STATUS_PAUSED. The filter then enters a paused state.

If successful, this function should return 0.

Resume()

int32_t (*Resume)(MmFilter_t *filter,
                  MmTime_t media_time,
                  MmTime_t real_time);

This function should resume playback of the filter. Each paused filter is given the same real_time value and media_time value so that they can stay synchronized. "Media time" is the elapsed media file time, while "real time" is the system clock time. Both values are of type MmTime_t, an int_64 that stores time in microseconds.

---

Don't use media_time for seeking; it's meant only for making slight synchronization adjustments.

---

If successful, this function should return 0.

Status()

int32_t (*Status)(MmFilter_t *filter);

This function should return the status of the filter. This should be one of:

• MM_STATUS_PLAYING -- the filter is processing data normally.
• MM_STATUS_PAUSING -- the graph is in a paused state, and has requested each filter to pause. The filter is finishing any processing it needs to complete before pausing.
• MM_STATUS_PAUSED -- the filter is in a paused state.
• MM_STATUS_STOPPING -- the graph is in a stopped state, and has requested each filter to stop. The filter is finishing any processing it needs to complete before stopping.
• MM_STATUS_STOPPED -- the filter is in a stopped state.
• MM_STATUS_EOF -- the filter is at the end of a file (buffer or stream).
• MM_STATUS_TIMEDOUT -- the filter has some data to process, but can't continue processing for some reason (for example, there's not enough input data to fill the output buffer).

  ---

  None of the current QNX-provided filters set their status to MM_STATUS_TIMEDOUT.

  ---

• a negative number signifying an error.

Classification:

Neutrino

See also:

MediaSeeker.

Extending the Multimedia Framework.