The Media Kit: Constants and Defined Types

The Media Kit Table of Contents | The Media Kit Index

# Constants and Defined Types

This section describes the constants and defined types that make the Media Kit tick.

## Constants

### Codec Type Info

Declared in: be/media/MediaDefs.h

Constant | Description
--- | ---
`B_CODEC_TYPE_INFO` | Data is in codec type info format.

The `B_CODEC_TYPE_INFO` constant is used to indicate that data is a codec info structure; it's used in the `user_data_type` field in the `media_format` structure, for example.

### Data Endianness

Declared in: be/media/MediaDefs.h

Constant | Description
--- | ---
`B_MEDIA_BIG_ENDIAN` | The media data is big-endian
`B_MEDIA_LITTLE_ENDIAN` | The media data is little-endian.

These values indicate whether media data is little-endian or big-endian.

In addition, `B_MEDIA_HOST_ENDIAN` is defined to be one of these values, indicating the endianness of the system on which your application is running.

### Media Message Size

Declared in: <be/media/MediaDefs.h>

       const size_t B_MEDIA_MESSAGE_SIZE = 16384;

The `B_MEDIA_MESSAGE_SIZE` constant specifies the maximum possible size a message a node's service thread can receive. 16k is an upper limit and won't be exceeded. Your thread can simply create a buffer this large, `read_port()` into it, and call `HandleMessage()` to process it.

### media_display_flags

Declared in: be/media/MediaDefs.h

Constant | Description
--- | ---
`B_F1_DOMINANT` | The first buffer sent (temporally) will be an F1 field.
`B_F2_DOMINANT` | The first buffer sent (temporally) will be an F2 field.
`B_TOP_SCANLINE_F1` | The topmost scanline of the output buffer belongs to F1.
`B_TOP_SCANLINE_F2` | The topmost scanline of the output buffer belongs to F2.

These values are used to define the order in which the F1 and F2 fields of video data are used.

### media_flags

Declared in: be/media/MediaDefs.h

Constant | Description
--- | ---
`B_MEDIA_FLAGS_VERSION` | Returns the Media Kit version as an int32 value.

The media_flags indicate values you can pass to `BMediaRoster::MediaFlags()` to get information about the version of the Media Kit that your application is running under.

### media_format_family

Declared in: be/media/MediaDefs.h

Constant | Meaning
--- | ---
`B_ANY_FORMAT_FAMILY` | Any family.
`B_BEOS_FORMAT_FAMILY` | BeOS format.
`B_QUICKTIME_FORMAT_FAMILY` | QuickTime format.
`B_AVI_FORMAT_FAMILY` | AVI format.
`B_ASF_FORMAT_FAMILY` | ASF format.
`B_MPEG_FORMAT_FAMILY` | MPEG format.
`B_WAV_FORMAT_FAMILY` | WAVE format audio.
`B_AIFF_FORMAT_FAMILY` | AIFF format audio.
`B_AVR_FORMAT_FAMILY` | AVR format audio.
`B_MISC_FORMAT_FAMILY` | Miscellaneous.

These constants indicate the media format families the BMediaFormats class can map among.

### media_format_flags

Declared in: be/media/MediaDefs.h

Constant | Description
--- | ---
`B_MEDIA_RETAINED_DATA` | Data in the buffer should be retained between calls to the decoder. A decoder that requires this behavior will set this bit in require_flags, and an application that doesn't support this behavior will set this bit in deny_flags.
`B_MEDIA_MULTIPLE_BUFFERS` | An application will set this flag in require_flags if it passes multiple buffers to the decoder; a decoder that doesn't support this will set this flag in deny_flags.
`B_MEDIA_CONTIGUOUS_BUFFER` | A decoder will set this flag in require_flags if it requires that buffers be in contiguous physical memory (for example, if it uses a hardware decoder). An application at doesn't support this should set this bit in deny_flags.
`B_MEDIA_LINEAR_UPDATES` | An application sets this flag in require_flags if it requires the decoder to write linearly (instead of randomly) into the buffer (for example, if using overlays). A decoder that really wants to write randomly should set this flag in deny_flags.
`B_MEDIA_MAUI_UNDEFINED_FLAGS` | Both applications and decoders should set this in both require_flags and deny_flags to avoid allowing or denying support for features they know nothing about.

These flags are used when specifying media_format's allow_flags or deny_flags fields, to indicate how the decoder should behave.

### media_multi_matrix

Declared in: <be/media/MediaDefs.h>

Constant | Description
--- | ---
`B_MATRIX_PROLOGIC_LR` | Dolby ProLogic matrix.
`B_MATRIX_AMBISONIC_WXYZ` | Ambisonic WXYZ matrix.

These values identify a particular multi-channel audio matrix.

### media_producer_status

Declared in: <be/media/MediaDefs.h>

Constant | Description
--- | ---
`B_DATA_NOT_AVAILABLE` | There aren't any buffers ready for the destination.
`B_DATA_AVAILABLE` | There are buffers ready for the destination.
`B_PRODUCER_STOPPED` | The producer isn't running.

These values can be specified when your producer node calls `BBufferProducer::SendDataStatus()` to tell the consumers it's feeding whether or not data is available for it to process. The `B_PRODUCER_STOPPED` code is sent to indicate to downstream consumers that it's no longer running.

Consumers receive these values in the `BBufferConsumer::ProducerDataStatus()` hook function.

### media_realtime_flags

Declared in: be/media/MediaDefs.h

Constant | Description
--- | ---
`B_MEDIA_REALTIME_ALLOCATOR` | When set, rtm_alloc() will return locked memory.
`B_MEDIA_REALTIME_AUDIO` | Audio add-ons in the Media Server are locked in memory, and should lock their thread stacks using `media_init_realtime_thread()`.
`B_MEDIA_REALTIME_VIDEO` | Video add-ons are locked in memory, and should lock their thread stacks using `media_init_realtime_thread()`.
`B_MEDIA_REALTIME_ANYKIND` | All Media add-ons are locked in memory, and should lock their thread stacks using `media_init_realtime_thread()`.

These values are passed to realtime allocator functions to indicate what types of nodes should use locked memory.

### media_type

Declared in: be/media/MediaNode.h

Constant | Description
--- | ---
`B_MEDIA_NO_TYPE` | Typeless media data.
`B_MEDIA_UNKNOWN_TYPE` | Unknown media type.
`B_MEDIA_RAW_AUDIO` | Uncompressed, linear audio.
`B_MEDIA_RAW_VIDEO` | Uncompressed, linear video.
`B_MEDIA_VBL` | Raw data from VBL area.
`B_MEDIA_TIMECODE` | Timecode data. Undetermined format.
`B_MEDIA_MIDI` | MIDI.
`B_MEDIA_TEXT` | Text data; typically closed-captioning information.
`B_MEDIA_HTML` | HTML data.
`B_MEDIA_MULTISTREAM` | Multi-stream media data, such as AVI or QuickTime.
`B_MEDIA_PARAMETERS` | BControllable change data.
`B_MEDIA_ENCODED_AUDIO` | Encoded audio (such as AC3 or DTS).
`B_MEDIA_ENCODED_VIDEO` | Encoded video (such as Indeo or MPEG).
`B_MEDIA_PRIVATE` | Base value for private Be media types.
`B_MEDIA_FIRST_USER_TYPE` | Base value for user-defined media types.

Types of media data.

### multi_media_channels

Declared in: be/media/MediaDefs.h

Constant | Description
--- | ---
`B_CHANNEL_LEFT` | The left channel.
`B_CHANNEL_RIGHT` | The right channel.
`B_CHANNEL_CENTER` | The center channel (5.1+ or fake surround)
`B_CHANNEL_SUB` | Subwoofer (5.1+).
`B_CHANNEL_REARLEFT` | Quad surround or 5.1+.
`B_CHANNEL_REARRIGHT` | Quad surround or 5.1+
`B_CHANNEL_FRONT_LEFT_CENTER` | Front-left center channel.
`B_CHANNEL_FRONT_RIGHT_CENTER` | Front-right center channel.
`B_CHANNEL_BACK_CENTER` | The rear center channel (6.1 or fake surround).
`B_CHANNEL_SIDE_LEFT` | The left side channel.
`B_CHANNEL_SIDE_RIGHT` | The right side channel.
`B_CHANNEL_TOP_CENTER` | The top center channel.
`B_CHANNEL_TOP_FRONT_LEFT` | The top front-left channel.
`B_CHANNEL_TOP_FRONT_CENTER` | The top front-center channel.
`B_CHANNEL_TOP_FRONT_RIGHT` | The top front-right channel.
`B_CHANNEL_TOP_BACK_LEFT` | The top back-left channel.
`B_CHANNEL_TOP_BACK_CENTER` | The top back-center channel.
`B_CHANNEL_TOP_BACK_RIGHT` | The top back-right channel.

Speaker positions for multi-channel audio.

### node_kind

Declared in: be/media/MediaNode.h

Constant | Description
--- | ---
`B_BUFFER_PRODUCER` | The flavor implements BBufferProducer.
`B_BUFFER_CONSUMER` | The flavor implements BBufferConsumer.
`B_TIME_SOURCE` | The flavor implements BTimeSource.
`B_CONTROLLABLE` | The flavor implements BControllable.
`B_FILE_INTERFACE` | The flavor implements BFileInterface.
`B_ENTITY_INTERFACE` | The flavor implements BEntityInterface (not available for R4).
`B_PHYSICAL_INPUT` | The flavor represents a physical input point (such as an input jack).
`B_PHYSICAL_OUTPUT` | The flavor represents a physical output point (such as line output).
`B_SYSTEM_MIXER` | The flavor represents the system mixer.

Defines the type or types of node that a particular flavor supports. Note that a flavor can implement more than one type of node, so you can combine these values using a bitwise or.

### Quality

Declared in: be/media/MediaDefs.h

Constant | Description
--- | ---
`B_MEDIA_ANY_QUALITY` | Any quality level (0.0).
`B_MEDIA_LOW_QUALITY` | Low quality (0.1).
`B_MEDIA_MEDIUM_QUALITY` | Medium quality (0.5).
`B_MEDIA_HIGH_QUALITY` | High quality (1.0).

These are default values you can use for various quality levels.

### video_orientation

Declared in: be/media/MediaNode.h

Constant | Description
--- | ---
`B_VIDEO_TOP_LEFT_RIGHT` | Typical progressive scan: top to bottom, left to right.
`B_VIDEO_BOTTOM_LEFT_RIGHT` | Bottom to top, left to right (BMP and TGA graphics are oriented this way).

Indicates the orientation of video data (whether the data is oriented top to bottom or bottom to top).

## Defined Types

### encode_parameters

Declared in: be/media/MediaDefs.h

struct `encode_parameters` {
float `quality`;
int32 `avg_field_size`;
int32 `max_field_size`;
int32 `_pad`[27];
void *`user_data`;
size_t `user_data_size`;
};

Parameters for encoding a buffer.

- quality indicates the compression quality to use. 0.0 is lowest quality, 1.0 is high quality. You can use the `B_MEDIA_ANY_QUALITY`, `B_MEDIA_LOW_QUALITY`, and so forth constants if you wish.

- avg_field_size indicates the average size of a field that should be allowed, in bytes. The encoder will try to maintain this average as it compresses.

- max_field_size indicates the maximum field size that should be allowed, in bytes. The encoder will try to encode each field to be smaller than this size.

- user_data and user_data_size indicate user-defined data.

### live_node_info

Declared in: be/media/MediaDefs.h

struct `live_node_info` {
`live_node_info()`;
`~live_node_info()`;
`media_node` `node`;
`BPoint` `hint_point`;
char `name`[`B_MEDIA_NAME_LENGTH`];
private:
`reserved`[160];
};

The live_node_info structure describes an active node, and is returned by `BMediaRoster::GetLiveNodes()`.

- node specifies which node the live_node_info structure describes.

- hint_point is reserved for future use. Pass a BPoint with x and y both set to 0.

### media_addon_id

Declared in: be/media/MediaDefs.h

typdef int32 `media_addon_id`;

A media add-on ID number.

### media_audio_header

Declared in: be/media/MediaDefs.h

struct `media_audio_header` { int32 `_reserved_`[16]; };

Defines the header of an audio buffer. There are no Be-defined fields in this structure as of the release of BeOS R4; however, you may append fields to the end of this structure if you wish.

### media_buffer_id

Declared in: be/media/MediaDefs.h

typdef int32 `media_buffer_id`;

A media buffer ID number.

### media_decode_info

Declared in: be/media/MediaDefs.h

struct `media_decode_info` {
bigtime_t `time_to_decode`;
int32 `_pad[26]`;
void *`file_format_data`;
size_t `file_format_data_size`;
void *`codec_data
` size_t `codec_data_size`;
`media_decode_info`();
};

Provides options to decoders.

- time_to_decode indicates how long, in microseconds, the decoder is allowed to take to decode the buffer. Specify 0 to do it as fast as possible, or `B_INFINITE_TIMEOUT` if you don't care.

- file_format_data is a pointer to file-format specific data, and file_format_data_size indicates the size of this buffer.

- codec_data is a pointer to a codec-specific data buffer, and codec_data_size indicates the size of the buffer.

### media_destination

Declared in: be/media/MediaDefs.h

struct `media_destination` {
`media_destination(`port_id, int32`)`;
`media_destination(`const `media_destination` &clone`)`;
`media_destination` & operator`=` (const `media_destination` &clone);
`media_destination()`;
`~media_destination()`;
port_id `port`;
int32 `id`;
static `media_destination` `null`;
private:
uint32 `_reserved_media_destination_`[2];
};

Describes the destination end of a media connection between two nodes. The port indicates the port ID on which the destination communicates. This can be different from the media_node.port value.

### media_encode_info

Declared in: be/media/MediaDefs.h

struct `media_encode_info` {
uint32 `flags`;
int32 `used_data_size`;
bigtime_t `start_time`;
bigtime_t `time_to_encode`;
int32 `_pad[22]`;
void *`file_format_data`;
size_t `file_format_data_size`;
void *`codec_data
` size_t `codec_data_size`;
`media_encode_info`();
};

Provides options to encoders and file writers about.

- flags contains flags that alter the behavior of the encoder or writer. The only defined value right now is `B_MEDIA_KEY_FRAME`.

- used_data_size is currently reserved for use by Be.

- start_time indicates the time at which the buffer being written is located, in microseconds, from the start of the file.

- time_to_encode indicates how long, in microseconds, the encoder is allowed to take to encode the buffer. Specify 0 to do it as fast as possible, or `B_INFINITE_TIMEOUT` if you don't care.

- file_format_data is a pointer to file-format specific data, and file_format_data_size indicates the size of this buffer.

- codec_data is a pointer to a codec-specific data buffer, and codec_data_size indicates the size of the buffer.

### media_encoded_audio_format

Declared in: be/media/MediaDefs.h

struct `media_encoded_audio_format` {
enum `audio_encoding` {
`B_ANY`,
};
`media_raw_audio_format` `output`;
`audio_encoding` `encoding`;
float `bit_rate`;
size_t `frame_size`;
media_multi_audio_info `multi_info`;`
` uint32`_reserved_`[3];
static `media_encoded_audio_format` `wildcard`;
};

Describes the format of encoded audio data.

- output indicates the raw audio format that results from decoding the encoded audio.

- encoding specifies the encoding format. This should just be `B_ANY`; this field, and the audio_encoding enum, are depreciated. Instead, the BMediaFormats database should be used to identify the encoding format.

- bit_rate specifies the bit rate (not byte rate) of the data stream.

- frame_size indicates the size of each frame of audio, in bytes.

- multi_info provides multi-channel information.

### media_encoded_audio_header

Declared in: be/media/MediaDefs.h

struct `media_encoded_audio_header` {
int32 `_reserved_0`[14];
uint32 `buffer_flags`;
uchar `unused_mask`;
uchar `_reserved_2`[3];
};

Defines the header of a an encoded audio buffer.

- buffer_flags contains flags that provide additional information about the buffer. The only value currently defined (other than 0) is `B_MEDIA_KEY_FRAME`, which indicates that the buffer is a key frame.

- unused_mask indicates which bits of the last byte in the buffer are unused (since encoded audio may result in a number of bits that doesn't fill up the last byte in the buffer).

If you wish, you can add more fields to the end of the header.

### media_encoded_video_format

Declared in: be/media/MediaDefs.h

struct `media_encoded_video_format` {
enum `video_encoding` {
`B_ANY`
};
`media_raw_video_format` `output`;
float `avg_bit_rate`;
float `max_bit_rate`;
`video_encoding` `encoding`;
size_t `frame_size`;
int16 `forward_history`;
int16 `backward_history`;
uint32 `_reserved_`[3];
static `media_encoded_video_format` `wildcard`;
};

Describes the format of encoded video data.

- output specifies the raw video format that results from decoding the video. Set this to `media_raw_video_format::wildcard`.

- avg_bit_rate indicates the average bit rate of the video, and max_bit_rate specifies the maximum bit rate that occurs at any point in the video.

- encoding has been depreciated, and should always be `B_ANY`; use the BMediaFormats lookup database to identify the encoding format.

- frame_size indicates the size in bytes of a frame of data.

- forward_history indicates the maximum number of future frames the encoding algorithm requires in order to decode the current frame.

- backward_history indicates the maximum number of past frames the encoding algorithm requires in order to decode the current frame.

### media_encoded_video_header

Declared in: be/media/MediaDefs.h

struct `media_encoded_video_header` {
int32 `_reserved_1`[9];
uint32 `field_flags`;
int16 `forward_history`;
int16 `backward_history`;
uchar `unsued_mask`;
uchar `_rserved_2`[3];
float `field_gamma`;
uint32 `field_sequence`;
uint16 `field_number`;
uint16 `pulldown_number`;
uint16 `first_active_line`;
uint16 `line_count`;
};

Defines the header of a video buffer. The fields in this buffer are the same as those in the `media_video_header` structure, except for the reserved fields, the forward_history and backward_history fields, the unused_mask, which indicates which bits are unused in the last byte of the video buffer, and field_flags, which can be either 0 or `B_MEDIA_KEY_FRAME` (which indicates that the field is a key frame).

The forward_history field indicates how many buffers ahead of the current one are required in order to decode the current buffer. The backward_history field indicates the number of previous buffers are required to decode the current buffer.

- field_gamma specifies the gamma at which the video was captured.

- field_sequence is an identifying number assigned to the field when it was captured. They progress in sequence; you can tell if a field was dropped by looking for skips in the sequence. Note that this value doesn't necessarily start at 0, and it can wrap back around to 0.

- field_number indicates which field of a video frame the buffer represents. It's 0 for field 1, 1 for field 2, and so forth.

- pulldown_number indicates that the field represented by the buffer is a duplicate of a field pulldown_number fields back. If this value is 0, it's not a duplicate field. This is used in cases when the video has been converted from one field rate to another, resulting in duplication of fields; these duplicated fields can be marked using pulldown numbers so video hardware and software can optimize their performance by knowing that duplicate fields exist.

- first_active_line indicates the topmost line that actually contains video data (instead of VBL data); this is an NTSC or PAL line number, which is 1-based. line_count indicates the number of active video lines in the field.

You may add fields to the end of this buffer if your video format requires them.

### media_file_format

Declared in: be/media/MediaDefs.h

struct `media_file_format` {
enum {
`B_READABLE` = 0x1,
`B_WRITABLE` = 0x2,
`B_PERFECTLY_SEEKABLE` = 0x4,
`B_IMPERFECTLY_SEEKABLE` = 0x8,
`B_KNOWS_RAW_VIDEO` = 0x10,
`B_KNOWS_RAW_AUDIO` = 0x20,
`B_KNOWS_MIDI` = 0x40,
`B_KNOWS_ENCODED_VIDEO` = 0x80,
`B_KNOWS_ENCODED_AUDIO` = 0x100,
`B_KNOWS_OTHER` = 0x1000000,
`B_KNOWS_ANYTHING` = 0x2000000
};
uint32 `capabilities`;
`media_file_format_id` `id`;
`media_format_family` `family`;
int32 `version`;
uint32 `_reserved_`[25];
char `mime_type`[64];
char `pretty_name`[64];
char `short_name`[32];
char `file_extension`[8];
char `reserved`[88];
};

Describes a media file format.

- capabilities is a bitfield providing informational flags describing the file format's capabilities.

- `B_READABLE` indicates that the file format is readable.

- id is an opaque ID used by the Media Kit to construct a BMediaFile object.

- family is one of the `media_format_family` constants.

- version should be 100.

- mime_type specifies the MIME type string that identifies the file format.

- pretty_name is a nice user-viewable name, such as "QuickTime File Format".

- short_name is a short-form name, like "QuickTime".

- file_extension specifies the file extension used on files containing this format, such as ".mov".

### media_file_format_id

Declared in: be/media/MediaDefs.h

struct `media_file_format_id` {
ino_t `node`;
dev_t `device`;
uint32 `internal_id`;
};

A simple means for identifying file formats; used by the `media_file_format` structure.

### media_format

Declared in: be/media/MediaDefs.h

       struct
    media_format
     {
          media_type
    type
    ;
          type_code
    user_data_type
    ;
          uchar
    user_data
    [48];
          uint32
    _reserved_
    [3];
          uint16
    require_flags
    ;
          uint16
    deny_flags
    ;

          private:

          void *
    meta_data
    ;
          int32
    meta_data_size
    ;
          area_id
    meta_data_area
    ;
          area_id
    use_area
    ;
          team_id
    team
    ;
          void *
    thisPtr
    ;

          public:

          union {
             media_multi_audio_format
    raw_audio
    ;
             media_raw_video_format
    raw_video
    ;
             media_multistream_format
    multistream
    ;
             media_encoded_audio_format
    encoded_audio
    ;
             media_encoded_video_format
    encoded_video
    ;
             char
    _reserved_
    [96];
          } u;

          bool
    IsVideo
    () const ;
          uint32
    Width
    () const;
          uint32
    Height
    () const;
          color_space
    ColorSpace
    () const;
          uint32 &
    Width
    ();
          uint32 &
    Height
    ();
          color_space &
    ColorSpace
    ();

          bool
    IsAudio
    () const;
          uint32 &
    AudioFormat
    ();
          uint32
    AudioFormat
    () const;

          uint32
    Encoding
    () const;

          bool
    Matches
    (const media_format *otherFormat) const;
          void
    SpecializeTo
    (const media_format *otherFormat);

          void
    SetMetaData
    (const void *data, int32 size);
          const void *
    MetaData
    () const;
          int32
    MetaDataSize
    () const;

    media_format
    ();

    media_format
    (const media_format &other);
          ~
    media_format
    ();

    media_format
     & operator=(const media_format &clone);
       };

### The media_format structure can describe any media data format the BeOS can support.

- type indicates the type of media the format describes.

- user_data_type and user_data allow the application to store custom data in the media_format structure; user_data_type specifies the type of data stored in user_data (`B_INT32_TYPE` , `B_STRING_TYPE` , etc).

- require_flags and deny_flags are media_format_flags indicating what options are required, and what options are rejected.

- meta_data, meta_data_size, meta_data_area, use_area, team, and thisPtr are currently only used by decoders when communicating with the file reader; they're not currently for public use.

- The union, u, permits the selection of a specific media format, such as raw audio or multistream data, and contains the descriptive information specific to that media format.

If any field is 0, it's treated as a wildcard.

There are several convenience functions for fetching information from the format that take care of dealing with different types automatically:

- `IsVideo()` returns true if the format represents video (either raw or encoded), otherwise it returns false.

- `Width()` returns the width of the video data; its value is undetermined if the format doesn't represent video.

- `Height()` returns the height of the video data; its value is undetermined if the format doesn't represent video.

- `ColorSpace()` returns the video's color space. Its value is undetermined if the format doesn't represent video.

- `IsAudio()` returns true if the format represents audio (either raw or encoded), otherwise it returns false.

- `AudioFormat()` returns the audio's sample format.

- `Matches()` returns `true` if the format matches the specified otherFormat, otherwise it returns `false`.

- `SpecializeTo()` adjusts the specified otherFormat as needed to match the format.

### media_header

Declared in: be/media/MediaDefs.h

struct `media_header` {
`media_type` `type`;
`media_buffer_id` `buffer`;
int32 `destination`;
`media_node_id` `time_source`;
uint32 `_depreciated_
` uint32 `size_used`;
`bigtime_t` `start_time`;
`area_id` `owner`;
enum {
`B_SEEK_TAG` = >TRST>
};
`type_code` `user_data_type`;
uchar `user_data`[64];
uint32 `_reserved_`[2];
off_t `file_pos`;
size_t `orig_size`;
uint32 `data_offset`;
union {
`media_audio_header` `raw_audio`;
`media_video_header` `raw_video`;
`media_multistream_header` `multistream`;
`media_encoded_audio_header` `encoded_audio`;
`media_encoded_video_header` `encoded_video`;
char `_reserved_`[64];
} `u`;
};

Defines the header of a media data buffer.

- type indicates the type of media the format describes.

- buffer indicates what buffer the header goes with. This field is filled out by the `BBufferProducer::SendBuffer()` function.

- destination specifies the ID number of the media_destination to which the buffer is being sent. This field is filled out by the `BBufferProducer::SendBuffer()` function.

- time_source indicates the ID number of the node that encoded the start_time.

- size_used specifies how many bytes of the buffer actually contain data.

- start_time indicates the performance time at which the buffer should be performed.

- owner specifies the area ID of the buffer's owner.

- user_data_type and user_data allow the application to store custom data in the media_format structure; user_data_type specifies the type of data stored in user_data (`B_INT32_TYPE`, `B_STRING_TYPE`, etc). The `B_SEEK_TAG` constant indicates that the user_data contains a seek tag.

- file_pos indicates where in the corresponding file the data came from, and orig_size indicates how big it was; if the data didn't come from a file, these should be zero.

- data_offset indicates the offset within the buffer to the data. This is reflected by the `BBuffer::Data()` function.

- The union, u, permits the selection of a specific media format, such as raw audio or multistream data, and contains the descriptive information specific to that media format.

### media_input

Declared in: be/media/MediaDefs.h

struct `media_input` {
`media_input()`;
`~media_input(`);
`media_node` `node`;
`media_source` `source`;
`media_destination` `destination`;
`media_format` `format`;
char `name`[`B_MEDIA_NAME_LENGTH`];
private:
`_reserved_media_input_`[4];
};

The media_input structure describes a complete connection between a media_source and media_destination, from the point-of-view of the consumer (the destination).

- node is the media_node that owns the input.

- source is the source socket from which the data is being sent.

- destination is the destination socket at which the data is arriving.

- format is the format of the data.

- name is the input's name.

### media_multistream_format

Declared in: be/media/MediaDefs.h

struct `media_multistream_format` {
enum { `B_ANY` = 0,
`B_VID` = 1,
`B_AVI`,
`B_MPEG1`,
`B_MPEG2`,
`B_QUICKTIME`,
`B_PRIVATE` = 90000,
`B_FIRST_USER_TYPE` = 100000
};
float `avg_bit_rate`;
float `max_bit_rate`;
uint32 `avg_chunk_size`;
uint32 `max_chunk_size`;
enum {
`B_HEADER_HAS_FLAGS` = 0x1,
`B_CLEAN_BUFFERS` = 0x2,
`B_HOMOGENOUS_BUFFERS` = 0x4
};
uint32 `flags`;
int32 `format`;
uint32 `_reserved_`[2];
struct `vid_info` {
float `frame_rate`;
uint16 `width`;
uint16 `height`;
`color_space` `space`;
float `sampling_rate`;
uint32 `sample_format`;
uint16 `byte_order`;
uint16 `channel_count`;
};
struct `avi_info` {
uint32 `us_per_frame`;
uint16 `width`;
uint16 `height`;
uint16 `_reserved_`;
uint16 `type_count`;
`media_type` `types`[5];
};
union {
vid_info `vid`;
avi_info `avi`;
} `u`;
static `media_multistream_format` `wildcard`;
};

Describes the format of multistream media data, such as a QuickTime, AVI, or MPEG movie.

- avg_bit_rate and max_bit_rate indicate the average and maximum bit rates of the media data.

- avg_chunk_size and max_chunk_size indicate the average and maximum buffer sizes; if all buffers are the same size, these two values should be equal.

- flags provides informational flags for the buffers. `B_HEADER_HAS_FLAGS` indicates that the buffers' headers have valid flags; `B_CLEAN_BUFFERS` indicates that each buffer represents an integral number of frames, and `B_HOMOGENOUS_BUFFERS` indicates that each buffer has only one format in it.

- format indicates the multistream data format (`B_AVI`, `B_QUICKTIME`, etc).

- The union u contains either a `vid_info` or an `avi_info` structure that describes the video stream:

#### vid_info

- frame_rate specifies the video frame rate (in frames per second).

#### avi_info

- us_per_frame specifies the number of microseconds each frame should be displayed.

### media_multi_audio_format

Declared in: be/media/MediaDefs.h

struct `media_multi_audio_format` { media_raw_audio_format raw; media_multi_audio_info `multi`; };

Describes a multi-channel audio format. This is constructed by using a media_raw_audio_format to describe the physical format of the sound, followed by a media_multi_audio_info structure that adds the multi-channel information. This allows compatibility with existing BeOS software while adding support for multi-channel audio in new software.

### media_multi_audio_info

Declared in: be/media/MediaDefs.h

struct `media_multi_audio_info` {
uint32 `channel_mask`;
int16 `valid_bits`;
uint16 `matrix_mask`;
uint32 `_reserved_b`[3];
};

Provides information about multi-channel audio support.

- channel_mask indicates which channels are supported; for each channel (`B_CHANNEL_LEFT`, etc) the corresponding bit is set in this mask.

- valid_bits indicates how many bits in a 32-bit integer sample actually contain sample data.

- matrix_mask indicates which multi-channel audio matrices are used.

### media_multistream_header

Declared in: be/media/MediaDefs.h

struct `media_multistream_header` {
uint32 `_reserved_`[14];
uchar `unused_mask`;
uchar `_reserved_2`[3];
enum {
`B_MASTER_HEADER` = 0x1,
`B_SUBSTREAM_HEADER` = 0x2,
`B_COMPLETE_BUFFER` = 0x4
};
uint32 `flags`;
};

Defines the header of a multistream media buffer.

- unused_mask indicates which bits of the last byte in the buffer are unused.

- flags provides informational flags about the buffer. If `B_MASTER_HEADER` is specified, master stream header data is in the buffer; `B_SUBSTREAM_HEADER` indicates that the buffer contains substream header information. `B_COMPLETE_BUFFER` indicates that the buffer's data represents an integral number of frames.

You may add fields to the end of this structure if your multistream media format requires them.

### media_node

Declared in: <be/media/MediaDefs.h>

class `media_node` {
public:
`media_node()`;
`~media_node()`;
`media_node_id` `node`;
port_id `port`;
uint32 `kind`;
static `media_node` `null`;
private:
uint32 `_reserved_`[3];
};

The `media_node` structure is the class that defines a node to client applications; interactions with the BMediaRoster regarding nodes is done using `media_node` objects.

- node indicates the node's ID number.

- port specifies the port ID number of the node's control port.

- kind specifies the node's media kind. See "node_kind" on page181 for a list of node kinds.

- null represents a null node

Applications will usually treat this as a black box.

### media_node_attribute

Declared in: be/media/MediaNode.h

struct `media_node_attribute` {
enum {
`B_R40_COMPILED` = 1,
`B_USER_ATTRIBUTE_NAME` = 0x1000000,
`B_FIRST_USER_ATTRIBUTE
` };
uint32 `what`;
uint32 `flags`;
uint64 `data`;
};

The media_node_attribute structure provides additional information about nodes. Nodes can have as many of these as they want, and will return them from their `BMediaNode::GetNodeAttributes()` function. Applications query the node using the `BMediaRoster::GetNodeAttributesFor()` function.

The what field indicates the attribute type. `B_R40_COMPILED` indicates that the node was compiled using BeOS Release 4.0; BMediaNode returns this attribute automatically for nodes that were compiled using the Release 4.0 headers. Nodes may create their own attribute types, beginning at `B_FIRST_USER_ATTRIBUTE`.

The `B_USER_ATTRIBUTE_NAME` attribute specifies the name of a protocol for the user attributes implemented by the node. For example, if you devise a third-party standard for attribute values whose attribute IDs are greater than `B_FIRST_USER_ATTRIBUTE`, the value of `B_USER_ATTRIBUTE_NAME` would be the name of the standard.

The flags and data fields are used for different things depending on the what value; the `B_R40_COMPILED` attribute doesn't use them.

### media_node_id

Declared in: be/media/MediaDefs.h

typdef int32 `media_node_id`;

A node ID number.

### media_output

Declared in: be/media/MediaDefs.h

struct `media_output` {
`media_output()`;
`~media_output()`;
media_node `node`;
media_source `source`;
media_destination `destination`;
media_format `format`;
char `name`[`B_MEDIA_NAME_LENGTH`];
private:
`_reserved_media_output_`[4];
};

The media_output structure describes a complete connection between a media_source and media_destination, from the point-of-view of the consumer (the destination).

- node is the media_node that owns the output.

- source is the source socket from which the data is being sent.

- destination is the destination socket to which the data is being sent.

- format is the format of the data.

- name is the output's name.

### media_raw_audio_format

Declared in: be/media/MediaDefs.h

struct media_raw_audio_format {
enum {
B_AUDIO_FLOAT = 0x24,
B_AUDIO_INT = 0x4
B_AUDIO_SHORT = 0x2,
B_AUDIO_UCHAR = 0x11,
B_AUDIO_CHAR = 0x1,
B_AUDIO_SIZE_MASK = 0xf
}
float `frame_rate`;
uint32 `channel_count`;
uint32 `format`;
uint32 `byte_order`;
size_t `buffer_size`;
static media_multi_audio_format `wildcard`;
};

Describes the format of raw audio data.

The frame_rate indicates the frame rate, in Hertz. One frame is one sample per channel (stereo buffers contain two samples per channel). For audio, each buffer contains multiple audio samples, whereas video contains one frame, or one field (half-frame) per buffer.

The channel_count indicates the number of channels of audio (typically this is either 1 for mono or 2 for stereo).

The format specifies the sample format (for compressed formats, see media_encoded_audio_format):

- `B_AUDIO_FLOAT`. Each sample is four bytes; 0 is the middle, -1.0 is the bottom, 1.0 is the top.

- `B_AUDIO_INT`. Each sample is four bytes; 0 is the middle, 0x80000001 is the bottom, 0x7FFFFFFF is the top.

- `B_AUDIO_SHORT`. Each sample is two bytes; 0 is the middle, -32767 is the bottom, 32767 is the top.

- `B_AUDIO_UCHAR`. Each sample is one byte; 128 is the midpoint, 1 is the bottom, 255 is the top.

- `B_AUDIO_CHAR`. Each sample is one byte; 0 is the midpoint, -127 is the bottom, 127 is the top.

It's guaranteed that (format & `B_AUDIO_SIZE_MASK`) will always be equal to the size of the sample.

The byte_order indicates the endianness of the data (either `B_MEDIA_BIG_ENDIAN` or `B_MEDIA_LITTLE_ENDIAN`).

buffer_size indicates the size of each buffer.

### media_raw_video_format

Declared in: be/media/MediaDefs.h

struct `media_raw_video_format` {
float `field_rate`;
uint32 `interlace`;
uint32 `first_active`;
uint32 `last_active`;
uint32 `orientation`;
uint16 `pixel_width_aspect`;
uint16 `pixel_height_aspect`;
media_video_display_info `display
`
static media_raw_video_format `wildcard`;
};

Describes the format of raw video data.

- field_rate indicates the field rate. This is 59.94 for NTSC and 50.0 for PAL. If you use BT848 in non-interlaced mode (thereby picking out only every other field), you'd specify 29.97.

- interlace specifies how many fields there are per frame. A value of 1 indicates that the video is progressive (non-interlaced). NTSC video is interlaced such that there are two fields per frame, so for standard NTSC video, this value is 2.

- first_active and last_active indicate where the VBL lines at the top of the frame end, and where they resume at the bottom of the frame; video data is confined between these two scan lines. Usually you'll use 0 for first_active and line_count-1 for last_active; these indicate wildcard or "don't care" values.

- orientation indicates the orientation of the video; this is typically `B_VIDEO_TOP_LEFT_RIGHT`.

- pixel_width_aspect and pixel_height_aspect specify the numerator and denominator of the video's aspect ratio. If the aspect ratio is 4:3, these values will be 4 and 3, respectively.

### media_request_info

Declared in: be/media/MediaNode.h

struct `media_request_info` {
enum `what_code` {
`B_SET_VIDEO_CLIPPING_FOR` = 1,
`B_REQUEST_FORMAT_CHANGE`,
`B_SET_OUTPUT_ENABLED`,
`B_SET_OUTPUT_BUFFERS_FOR`,
`B_FORMAT_CHANGED` = 4097
};
what_code `what`;
int32 `change_tag`;
status_t `status`;
int32 `cookie`;
void * `user_data`;
media_source `source`;
media_destination `destination`;
media_format `format`;
uint32 `_reserved_`[32];
};

This structure contains information that describes a request that has been completed (or has failed). It gets passed into the `BMediaNode::RequestCompleted()` function.

The `what` field describes what type of request has been completed:

- `B_SET_VIDEO_CLIPPING_FOR` indicates that a `BBufferConsumer::SetVideoClippingFor()` request has been completed. The `source` and `destination` fields contain these values from the request, and `format.u.raw_video.display` describes the new video display settings.

- `B_REQUEST_FORMAT_CHANGE` indicates that a `BBufferConsumer::RequestFormatChange()` request has been completed. The `source` and `destination` fields contain these values from the request, and `format` contains the negotiated format (it may have been altered by the producer if there were wildcard fields).

- `B_SET_OUTPUT_ENABLED` indicates that a `BBufferConsumer::SetOutputEnabled()` request has been completed. The `source` and `destination` fields contain these values from the request, and `status` is always `B_OK`.

- `B_SET_OUTPUT_BUFFERS_FOR` indicates that a `BBufferConsumer::SetOutputBuffersFor()` request has been completed. The `source` and `destination` fields contain these values from the request, and `cookie` is a pointer to the BBufferGroup that was set. Note that the change was only applied if `status` is `B_OK`.

- `B_FORMAT_CHANGED` indicates that a `BBufferConsumer::FormatChanged()` request has been completed. The `source` and `destination` fields contain these values from the request, and `format` indicates the new format. The values seen here are from the initator's point of view.

The `user_data` field contains the userData pointer passed to the function that initiated the request; this can be anything the node making the request wants.

`status` indicates the status of the function called, and is `B_OK` if no error occurred.

### media_seek_tag

Declared in: be/media/MediaDefs.h

struct `media_seek_tag` { char `data`[16]; };

The `media_seek_tag` type is used to contain the seek tag data placed in buffer headers by producers. This can contain whatever information the producer deems necessary.

### media_source

Declared in: be/media/MediaDefs.h

struct `media_source` {
`media_source(`port_id, int32`)`;
`media_source(`const `media_source` &clone`)`;
`media_source` & operator`=` (const `media_source` &clone);
`media_source()`;
`~media_source()`;
port_id `port`;
int32 `id`;
static `media_source` `null`;
private:
uint32 `_reserved_media_source_`[2];
};

Describes the source end of a media connection between two nodes. The `port` field indicates the port ID on which the source communicates. This must be the same as the media_node.port value.

### media_video_display_info

Declared in: be/media/MediaDefs.h

struct `media_video_display_info` {
color_space `format`;
uint32 `line_width`;
uint32 `line_count`;
uint32 `bytes_per_row`;
uint32 `pixel_offset`;
uint32 `line_offset`;
uint32 `flags`;
uint32 `_reserved_`[3];
static `media_video_display_info` `wildcard`;
};

Describes a video buffer in terms of how its contents should be interpreted in order to display it on the screen.

- format specifies the buffer's color space.

- line_width and line_count indicate the total width of the buffer in pixels, and the total height of the buffer in lines.

- bytes_per_row specifies the number of bytes wide the buffer's image is, including any slop space.

- pixel_offset indicates the number of pixels between the start of the buffer and the start of the video field. The buffer is the framebuffer.

- line_offset specifies the offset between the start of the buffer and the start of the field, in lines. The buffer is the framebuffer.

- flags are media_display_flags, indicating the dominance and order of the video fields.

### media_video_header

Declared in: be/media/MediaDefs.h

struct `media_video_header` {
uint32 `_reserved_`[12];
float `field_gamma`;
uint32 `field_sequence`;
uint16 `field_number`;
uint16 `pulldown_number`;
uint16 `first_active_line`;
uint16 `line_count`;
};

Defines the header of a video buffer.

- field_gamma specifies the gamma at which the video was captured.

- field_sequence is an identifying number assigned to the field when it was captured. They progress in sequence; you can tell if a field was dropped by looking for skips in the sequence. Note that this value doesn't necessarily start at 0, and it can wrap back around to 0.

- field_number indicates which field of a video frame the buffer represents. It's 0 for field 1, 1 for field 2, and so forth.

- pulldown_number indicates that the field represented by the buffer is a duplicate of a field pulldown_number fields back. If this value is 0, it's not a duplicate field. This is used in cases when the video has been converted from one field rate to another, resulting in duplication of fields; these duplicated fields can be marked using pulldown numbers so video hardware and software can optimize their performance by knowing that duplicate fields exist.

- first_active_line indicates the topmost line that actually contains video data (instead of VBL data); this is an NTSC or PAL line number, which is 1-based. line_count indicates the number of active video lines in the field.

You may add fields to the end of this buffer if your video format requires them.

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..