BMediaDecoder

Derived from: none
Declared in:  be/media/MediaDecoder.h Library: libmedia.so
Summary:  more...

The BMediaDecoder class is a base class from which decoder classes may be derived. It handles all the work of locating an appropriate decoder add-on and interfacing with it. All you have to do is implement the GetNextChunk() function to fetch the next chunk of encoded data to be processed.

The BMediaBufferDecoder class is provided for you; it's a derived class that implements GetNextChunk() to return data from a memory buffer.

An application that wants to decode a stream of data that's not originating from a file should use a subclass of BMediaDecoder (such as BMediaBufferDecoder) to do so.

Hook Functions

GetNextChunk()

Constructor and Destructor

BMediaDecoder()

BMediaDecoder() BMediaDecoder(const media_format *inFormat,       const void *info = NULL, size_t infoSize = 0) BMediaDecoder(const media_codec_info *mci)

The constructor sets up the BMediaDecoder. If you use the empty form of the constructor, you'll have to call SetTo() to establish the format to be decoded before calling Decode().

The second form accepts a media_format structure, inFormat, that indicates the type of media data that will be input into the decoder. info, if specified, will be filled out with text information about the node; you must specify a buffer infoSize bytes long.

The third form of the constructor accepts a media_codec_info structure, mci, that determines which codec should be used.

If you use either the media_format or media_codec_info form of the constructor, you must call InitCheck() to ensure that construction was successful before using any other functions in this class.

~BMediaDecoder()

virtual ~BMediaDecoder()

Releases the decoder add-on being used by the BMediaDecoder.

Member Functions

Decode()

status_t Decode(void *outBuffer, int64 *outFrameCount,       media_header *outMH, media_decode_info *info)

Decodes a chunk of media data into the output buffer specified by outBuffer. On return, outFrameCount is set to indicate how many frames of data were decoded, and outMH is the header for the decoded buffer.

The media_decode_info structure info is used on input to specify decoding parameters.

The amount of data decoded is part of the format determined by SetTo() or SetInputFormat(). For audio, it's the buffer_size. For video, it's one frame, which is height*row_bytes. The data to be decoded will be fetched from the source by the decoder add-on calling the derived class' GetNextChunk() function.

RETURN CODES

• B_OK. No error.

• B_NO_INIT. The BMediaDecoder hasn't been initialized.

• Other errors. The decoder's Decode() function can return errors.

GetDecoderInfo()

status_t GetDecoderInfo(media_codec_info *outInfo) const

Fills out the media_codec_info structure outInfo with information about the decoder being used by the BMediaDecoder.

RETURN CODES

• B_OK. No error.

• B_NO_INIT. The BMediaDecoder hasn't been initialized.

• Other errors. The decoder's GetCodecInfo() function can return errors.

GetNextChunk()

protected: status_t GetNextChunk(const void **chunkData, size_t *chunkLen,       media_header *mh) = 0

In derived classes, you should implement this function to fetch the media data from the source. Set chunkData to be a pointer to the next chunk of media data, and chunkLen to the size of that buffer. The media_header structure mh provides information you can use while fetching the chunk.

This hook is called by the decoder add-on in order to fetch the data from the source.

Return B_OK if the chunk is fetched safely, or an appropriate error code otherwise.

InitCheck()

status_t InitCheck(void) const

Returns a status_t value indicating whether or not construction was successful. You must call this function after construction before calling any other BMediaDecoder functions.

RETURN CODES

• B_OK. The constructor was successful.

• SetTo() errors.

SetInputFormat() , SetOutputFormat

status_t SetInputFormat(const media_format *inFormat,       const void *info = NULL, size_t infoSize = 0) status_t SetOutputFormat(media_format *outputFormat)

SetInputFormat() sets the input data format to inFormat. On return, info (if you don't specify NULL) is filled out by the decoder to contain whatever textual information the decoder wants to provide. infoSize must indicate the size of the buffer pointed to by info.

Unlike SetTo(), SetInputFormat() function does not select a codec, so the currently-selected codec will continue to be used. You should only use SetInputFormat() to refine the format settings if it will not require the use of a different decoder.

SetOutputFormat() sets the format the decoder should output. On return, the outputFormat is changed to match the actual format that will be output; this can be different if you specified any wildcards.

RETURN CODES

• B_OK. No error.

• B_NO_INIT. The BMediaDecoder hasn't been initialized yet.

• Other errors. The decoder's Sniff(), Format(), and Reset() functions can return errors through SetInputFormat().

SetOutputFormat()  see SetInputFormat()

SetTo()

status_t SetTo(const media_format *inFormat,       const void *info = NULL, size_t infoSize = 0 status_t SetTo(const media_codec_info *mci)

SetTo() sets the format of media data that will be decoded by the BMediaDecoder object. This also causes the BMediaDecoder to locate an appropriate codec to use.

The first form accepts a media_format structure, inFormat, that indicates the type of media data that will be input into the decoder. info, if specified, will be filled out with text information about the node; you must specify a buffer infoSize bytes long.

The second form of SetTo() accepts a media_codec_info structure, mci, that determines which codec should be used.

RETURN CODES

• B_OK. No error.

• B_MEDIA_BAD_FORMAT. The specified media_format isn't valid.

• B_BAD_VALUE. Something else went wrong.

• B_ERROR. Unable to instantiate the decoder.