Qt API | Qtopia API | Qtopia Documentation |

# MediaPlayerDecoder Class Reference

The MediaPlayerDecoder class provides an abstract base class for Qtopia MediaPlayer decoder plugins. More...

`#include <qtopia/mediaplayerplugininterface.h>`

Inherited by MediaPlayerDecoder_1_6, LibFlashPlugin, LibMadPlugin and MediaPlayerDecoder_1_6.

List of all member functions.

## Public Members

- virtual ~MediaPlayerDecoder ()
- virtual const char * pluginName () = 0
- virtual const char * pluginComment () = 0
- virtual double pluginVersion () = 0
- virtual bool isFileSupported ( const QString & file ) = 0
- virtual bool open ( const QString & file ) = 0
- virtual bool close () = 0
- virtual bool isOpen () = 0
- virtual const QString & fileInfo () = 0
- virtual int audioStreams () = 0
- virtual int audioChannels ( int stream ) = 0
- virtual int audioFrequency ( int stream ) = 0
- virtual int audioSamples ( int stream ) = 0
- virtual bool audioSetSample ( long sample, int stream ) = 0
- virtual long audioGetSample ( int stream ) = 0
- virtual bool audioReadSamples ( short * samples, int channels, long sampleCount, long & samplesRead, int stream ) = 0
- virtual int videoStreams () = 0
- virtual int videoWidth ( int stream ) = 0
- virtual int videoHeight ( int stream ) = 0
- virtual double videoFrameRate ( int stream ) = 0
- virtual int videoFrames ( int stream ) = 0
- virtual bool videoSetFrame ( long frame, int stream ) = 0
- virtual long videoGetFrame ( int stream ) = 0
- virtual bool videoReadFrame ( unsigned char **, int, int, int, int, ColorFormat, int ) = 0
- virtual bool videoReadScaledFrame ( unsigned char ** output_rows, int in_x, int in_y, int in_w, int in_h, int out_w, int out_h, ColorFormat color_model, int stream ) = 0
- virtual bool videoReadYUVFrame ( char *, char *, char *, int, int, int, int, int ) = 0
- virtual double getTime () = 0
- virtual bool setSMP ( int CPUs ) = 0
- virtual bool setMMX ( bool useMMX ) = 0
- virtual bool supportsAudio () = 0
- virtual bool supportsVideo () = 0
- virtual bool supportsYUV () = 0
- virtual bool supportsMMX () = 0
- virtual bool supportsSMP () = 0
- virtual bool supportsStereo () = 0
- virtual bool supportsScaling () = 0
- virtual long getPlayTime ()

## Detailed Description

The MediaPlayerDecoder class provides an abstract base class for Qtopia MediaPlayer decoder plugins.

Writing a decoder plugin is achieved by subclassing this base class, reimplementing the pure virtual functions and exporting the class with the `Q_EXPORT_PLUGIN` macro. See the Plugins documentation for details.

See also Qtopia Classes.

## Member Function Documentation

### MediaPlayerDecoder::~MediaPlayerDecoder ()`[virtual]`

This function is called when a decoder plugin object is deleted. It closes any open streams, and releases any memory which has been allocated for decoding.

### int MediaPlayerDecoder::audioChannels ( int stream )`[pure virtual]`

Returns the number of audio channels for the given stream. A mono file will return 1, stereo returns 2, and so on.

(The Qtopia MediaPlayer currently only supports decoding up to the first 2 channels of audio, however it is quite possible for a stream to have up to 6 channels, and for those to be decoded when audioReadSamples is called with 6 channels requested.)

### int MediaPlayerDecoder::audioFrequency ( int stream )`[pure virtual]`

Returns the frequency of the audio stream. A typical value is 44100 which represents that there are 44100 audio samples per second per channel (for example, if it is 16-bit stereo, then there will be a total of 44100*2*2 bytes available per second).

### long MediaPlayerDecoder::audioGetSample ( int stream )`[pure virtual]`

This function retrieves the decoders sample postion in the given stream. The sample position can change due to audioReadSamples() being called or if supported, from audioSetSample() being called.

### bool MediaPlayerDecoder::audioReadSamples ( short * samples, int channels, long sampleCount, long & samplesRead, int stream )`[pure virtual]`

This function reads sampleCount number of samples in to the samples buffer from the given stream.

The samples buffer is filled with 16 bit wide values, therefore if the samples are only 8 bit, they are expanded to shorts before being stored by the decoder. The channels value specifies how many channels to decoded.

The samples for multiple channels are placed together, for example in the following order:

sample1channel1, sample1channel2, sample2channel1, sample2channel2 etc.

On success, TRUE is returned, otherwise FALSE is returned which indicates the end of the file has been reached. The value in samplesRead on return contains the number of samples actually read.

In the case of streamed media, when no input is currently available, a return value of TRUE is returned, however samplesRead is set to 0 after a suitable timeout has elapsed and no samples have been able to be read.

### int MediaPlayerDecoder::audioSamples ( int stream )`[pure virtual]`

Returns the total number of audio samples in the given stream.

As an example, if there is 10 seconds of music at 44100Hz with stereo samples, this function would return 441000 samples (each sample in a stereo pair is only counted once).

If the media file is being streamed, it may not always be possible to determine the length of the streamed data (for example a radio webcast which continuously streams audio data), in which case the return value is -1 which indicates that the stream is not seekable. In such cases attempts to call audioSetSample() will most likely fail.

### bool MediaPlayerDecoder::audioSetSample ( long sample, int stream )`[pure virtual]`

This function causes the decoder to seek to the given sample postion in the media file.

If the open stream is not a file, but is instead for example a URL, then it may not be possible to seek to the given sample and FALSE will be returned, otherwise the next time either audioReadSamples() or videoReadFrame() is called, decoding will continue from the set position in the file.

Note this function repositions both the audio and video if there are also video streams to the appropriate positions.

See also videoSetFrame().

### int MediaPlayerDecoder::audioStreams ()`[pure virtual]`

If the opened file contains audio streams, the number of audio streams are returned here, otherwise zero is returned. The Qtopia MediaPlayer currently only supports opening the first stream (stream 0) from a decoder if there is more than one stream.

The return value is normally 1 or 0.

### bool MediaPlayerDecoder::close ()`[pure virtual]`

This function closes all open streams. If there is a failure or no streams are open, this function returns FALSE;

### const QString & MediaPlayerDecoder::fileInfo ()`[pure virtual]`

This function returns an internationalized QString which describes information fields which are comma seperated and paired with colons about the currently open stream.

An example would be:

            "Format: MPEG1 Layer3, Year: 1998"

The internationalization is achieved inside the plugin using the qApp->translate() function around the translatable strings.

For the above example, the code to generate the string might be written like this:

            qApp->translate( "PluginName", "Format: MPEG1 Layer3" ) + ", " +
                qApp->translate( "PluginName", "Year: " + "1998";

Please refer to the Qt Internationalization documentation for more detailed information on creating code which makes good translations possible.

The translation files are loaded by the Qtopia MediaPlayer for the decoder plugin by searching the language directories for files matching $QPEDIR/i18n/[LANG]/[PLUGIN].qm for the supported languages.

### long MediaPlayerDecoder::getPlayTime ()`[virtual]`

This function is deprecated.

The most accurate way to get the elapsed play time for files which contain audio is to use the audioGetSample() function and derive the elapsed time from the sample rate, or for files without audio is to use videoGetFrame() and derive the elapsed time from the frame rate.

### double MediaPlayerDecoder::getTime ()`[pure virtual]`

This function is for profiling decoders. It returns the last decoded timestamp from the media stream.

Please refer to getPlayTime() for a discussion on how best to query the elapsed time.

### bool MediaPlayerDecoder::isFileSupported ( const QString & file )`[pure virtual]`

If the given file can be decoded successfully by this plugin, a return value of TRUE is returned, otherwise FALSE is returned.

### bool MediaPlayerDecoder::isOpen ()`[pure virtual]`

If a stream has been successfully opened with a call to open() and has not yet been closed with a call to close(), this function returns TRUE, otherwise it returns FALSE;

### bool MediaPlayerDecoder::open ( const QString & file )`[pure virtual]`

If the given file is opened successfully by this plugin, a return value of TRUE is returned, otherwise FALSE is returned. After this has been called, functions which return information about the stream can be used. For example, after a call to open() it is possible to query the channels, frequency, video width and height with calls to the appropriate functions.

### const char * MediaPlayerDecoder::pluginComment ()`[pure virtual]`

This function returns a string which provides copyright or a small amount of text that gives a brief description of the plugin. This string may be helpful for developers using the plugin to find out how the plugin authors might be able to be contacted, or a pointer to a web page which provides more information about the plugin.

The output of this function is not intented to be used in any user interface. Future decoder APIs may be extended to provide an additional function which should be internationalized and appropriate to be used in a user interface if nessaccery.

### const char * MediaPlayerDecoder::pluginName ()`[pure virtual]`

This function returns a string which is used to identify the plugin. The primary use of this string is for providing debug information.

The output of this function is never used in any user interface, so it is safe to provide a non-internationalized string. (Future decoder APIs will provide a replacement/additional function which will be declared const and will expect an internationalized QString return value that will be able to be used in user interfaces if nessaccery).

### double MediaPlayerDecoder::pluginVersion ()`[pure virtual]`

This function returns a number which represents the version of the decoder plugin. For example, if it is version 1.6 of the plugin, then a value of (double)1.6 would be returned.

### bool MediaPlayerDecoder::setMMX ( bool useMMX )`[pure virtual]`

This function is used as a hint to the decoder to use MMX specific optimizations if being used on an x86 processor and useMMX is true. On other binary incompatible processors, this function is interpreted to mean use the MMX equivelant optimizations for that processor family. For example on MIPS, this function translates to using MMI optimizations.

(Currently the Qtopia MediaPlayer doesn't use this function.)

### bool MediaPlayerDecoder::setSMP ( int CPUs )`[pure virtual]`

This function is used as a hint to the decoder for how many decoding threads it should consider using based on the provided number of CPUs.

(Currently the Qtopia MediaPlayer doesn't use this function.)

### bool MediaPlayerDecoder::supportsAudio ()`[pure virtual]`

This function returns the audio capability of the decoder. If audio can be decoded, this function returns TRUE, otherwise it returns FALSE. If audio is not supported, all virtual audio functions are still provided, however the return values for those functions will always be FALSE or 0 as applicable.

### bool MediaPlayerDecoder::supportsMMX ()`[pure virtual]`

This function is deprecated.

### bool MediaPlayerDecoder::supportsSMP ()`[pure virtual]`

This function is deprecated.

### bool MediaPlayerDecoder::supportsScaling ()`[pure virtual]`

This function is deprecated.

### bool MediaPlayerDecoder::supportsStereo ()`[pure virtual]`

This function is deprecated.

### bool MediaPlayerDecoder::supportsVideo ()`[pure virtual]`

This function returns the video capability of the decoder. If video can be decoded, this function returns TRUE, otherwise it returns FALSE. If video is not supported, all virtual video functions are still provided, however the return values for those functions will always be FALSE or 0 as applicable.

### bool MediaPlayerDecoder::supportsYUV ()`[pure virtual]`

This function is deprecated.

### double MediaPlayerDecoder::videoFrameRate ( int stream )`[pure virtual]`

Returns the frames per second of the given video stream.

(The Qtopia MediaPlayer makes its best effort to play the video frames at the specified rate.)

### int MediaPlayerDecoder::videoFrames ( int stream )`[pure virtual]`

Returns the total number of video frames in the given stream.

### long MediaPlayerDecoder::videoGetFrame ( int stream )`[pure virtual]`

This function retrieves the decoders frame postion in the given stream.

The frame position can change due to videoReadScaledFrame() being called or if supported, from videoSetFrame() being called.

### int MediaPlayerDecoder::videoHeight ( int stream )`[pure virtual]`

Returns the height of video frames for the given stream.

### bool MediaPlayerDecoder::videoReadFrame ( unsigned char **, int, int, int, int, ColorFormat, int )`[pure virtual]`

This function is deprecated.

Please use videoReadScaledFrame() instead.

### bool MediaPlayerDecoder::videoReadScaledFrame ( unsigned char ** output_rows, int in_x, int in_y, int in_w, int in_h, int out_w, int out_h, ColorFormat color_model, int stream )`[pure virtual]`

This function decodes the current video frame from the given stream in to the buffer at output_rows.

The in_x and in_y parameters specify where to decode from and the in_w and in_h parameters specify the width and height of the input stream to decode.

The out_w and out_h parameters specify the width and height to scale the input to.

The color_model specifies the format of the bits for color in the output_rows. A typical value for the color_model is RGB565.

This function can be used (as is done in the Qtopia MediaPlayer) to decode video directly to a frame buffer device using the QDirectPainter class or directly to a QImage. In the case of decoding to a QImage, the QImage::jumpTable() of the QImage is provided as the first parameter to this function. In the QDirectPainter case, a jump table for the frame buffer's scanlines needs to be constructed, but this is only required to be done once, and could be reused by the caller for every subsequent call to this function.

### bool MediaPlayerDecoder::videoReadYUVFrame ( char *, char *, char *, int, int, int, int, int )`[pure virtual]`

This function is deprecated.

Please use videoReadScaledFrame() instead. (Future decoder interfaces may provide a similar function to this in the future).

### bool MediaPlayerDecoder::videoSetFrame ( long frame, int stream )`[pure virtual]`

This function causes the decoder to seek to the given frame postion in the given media file's stream. If the open stream is not a file, but is instead for example a URL, then it may not be possible to seek to the given frame and FALSE will be returned, otherwise the next time either audioReadSamples() or videoReadFrame() is called, decoding will continue from the set position in the file.

Note this function repositions both the audio and video if there are also audio streams to the appropriate positions.

See also audioSetSample().

### int MediaPlayerDecoder::videoStreams ()`[pure virtual]`

If the opened file contains video streams, the number of video streams is returned, otherwise zero is returned.

(The Qtopia MediaPlayer currently only supports opening the first stream (stream 0) from a decoder if there is more than one stream.)

The return value is normally 1 or 0.

### int MediaPlayerDecoder::videoWidth ( int stream )`[pure virtual]`

Returns the width of video frames for the given stream.

This file is part of the Qtopia , copyright © 1995-2002 Trolltech, all rights reserved.