The Media Kit: BMediaDecoder

The Media Kit Table of Contents | The Media Kit Index

# BMediaDecoder

Derived from: none

Declared in: be/media/MediaDecoder.h

Library: libmedia.so

###### Summary

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`)`

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.

The Media Kit Table of Contents | The Media Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..