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

`MediaOutput`

Functions for filter with an output channel

Synopsis:

static MediaOutput media_output =
{
    IterateChannels,
    AcquireChannel,
    ReleaseChannel,
    GetStreamer,
    IterateFormats,
    VerifyFormat,
    SetFormat,
    NextBuffer,
    ReleaseBuffer,
    DestroyBuffers
};

Description:

This interface defines the functionality required by any filter that allows a MediaInput to get its input data from the filter, either streaming or buffered.

IterateChannels()

MmChannel_t *(*IterateChannels)(const MmFilter_t *filter,
                                int32_t * const cookie);

This function should iterate through all the output channels in the filter. Set the value of cookie to 0 for the first call. IterateChannels() should return NULL when there are no more channels. This function doesn't discriminate between acquired and nonacquired channels. To determine whether a channel is acquired, check its flags member. See MmChannel_t in the Multimedia Library Structure Reference chapter for more information.

If your filter has only one output channel you can use singleIterateOutputChannels() from the convenience library. This function returns the output channel on the first call, and returns NULL on subsequent calls.

MmChannel_t *singleIterateOutputChannels(const MmFilter_t *f,
                                         int32_t * const cookie);

AcquireChannel()

int32_t (*AcquireChannel)(MmChannel_t *channel);

This function should acquire the channel. This locks the channel for exclusive use. You can release it with ReleaseChannel().

If successful, this function should return 0.

ReleaseChannel()

int32_t (*ReleaseChannel)(MmChannel_t *channel);

This function should release the channel.

If successful, this function should return 0.

GetStreamer()

AOIStream_t (*GetStreamer)(MmChannel_t *channel);

This function should return the streamer for the channel, if it's a streaming channel.

If your filter doesn't provide streaming output, it can use the placeholder noGetStreamer() from the convenience library. It returns NULL.

AOIStream_t *noGetStreamer(MmChannel_t *c);

IterateFormats()

int32_t (*IterateFormats)(MmChannel_t *channel,
                          MmFormat_t *mf,
                          int32_t * const cookie);

This function should iterate through the possible output formats (mf) for this channel. The cookie argument is an opaque variable, and should be initialized to 0 for the first call. IterateFormats() should return 0 until there are no more formats to iterate through.

You don't need to implement this method for output channels that are streamers. In that case, you can use the placeholder method from the multimedia convienience library: noIterateFormats()

int32_t noIterateFormats(MmChannel_t *channel,
                         MmFormat_t *fmt,
                         int32_t * const cookie);

VerifyFormat()

int32_t (*VerifyFormat)(MmChannel_t *channel,
                        const MmFormat_t *format);

This function should return a rating for the format. This is the last chance for the filter to reject or rate a given format. The best-rated format is chosen.

If your filter doesn't need to have a last-chance verification of a format, you can use acceptVerifyOutputFormats() from the convenience library. This method simply accepts the proposed format.

int32_t acceptVerifyOutputFormats(MmChannel_t *c,
                                  const MmFormat_t *fl);

SetFormat()

int32_t (*SetFormat)(MmChannel_t *channel,
                     const MmFormat_t *format,
                     const MediaBufferAllocator *mba,
                     MmChannel_t *mbac);

This function should set the channel's data format and buffer allocator mba. The buffer allocator is the interface/channel that originally allocated the buffer data. It's used to acquire/lock and release/unlock buffers.

If you don't need to implement this method, you can use the placehoder noSetOutputFormat() from the convenience library (include mmconvenience.h):

int32_t noSetOutputFormat(MmChannel_t *c,
                          const MmFormat_t *fo,
                          const MediaBufferAllocator *mba,
                          MmChannel_t *mbac);

NextBuffer()

int32_t (*NextBuffer)(MmChannel_t *channel,
                      MmTime_t media_time,
                      MmBuffer_t **buffer);

This function should return the next buffer. If media_time is nonzero and buffers are retrievable based on the timestamp, the function returns the appropriate timestamp's buffer.

Usually, you ask a previous link for its buffer with the given timestamp. The value returned is one of MM_STATUS_*: MM_STATUS_PLAYING if a buffer was returned, and MM_STATUS_PAUSED, MM_STATUS_EOF, etc., if for whatever reason a buffer wasn't returned. If the buffer is timed out (optional), you can return MM_STATUS_TIMEDOUT.

If you don't need to implement this method, you can use the placehoder noNextBuffer() from the convenience library (include mmconvenience.h):

int32_t noNextBuffer(MmChannel_t *c,
                     MmTime_t t,
                     MmBuffer_t **buffer);

ReleaseBuffer()

int32_t (*ReleaseBuffer)(MmChannel_t *channel,
                         MmBuffer_t *buffer);

This function should release the buffer so that it can be reused in a future NextBuffer() call.

If successful, this function should return 0.

If you don't need to implement this method, you can use the placeholder noReleaseBuffer() from the convenience library:

int32_t noReleaseBuffer(MmChannel_t *c,
                        MmBuffer_t *b);

DestroyBuffers()

This function should free any buffer resources.

If you don't need to implement this method, you can use a pointer to the placeholder noDestroyBuffers() from the convenience library:

int32_t noDestroyBuffers(MmChannel_t *c);

Classification:

Neutrino