The Media Kit: BBuffer

The Media Kit Table of Contents | The Media Kit Index

# BBuffer

Derived from: none

Declared in: be/media/Buffer.h

Library: libmedia.so

Allocation: Constructor only

###### Summary

A BBuffer references a chunk of shared memory where media data can be passed between applications and nodes. The control header for these buffers is passed through the use of a safer IPC mechanism, but the actual data these headers represent typically require a high data rate, and for the sake of maximizing performance, shared memory is the method by which the buffers are managed.

BBuffers originate at some BBufferProducer, which has a BBufferGroup that acts as a source of BBuffers (see `BBufferConsumer::SetOutputBuffersFor()`). BBuffers are sent through all participating nodes, possibly being sent down a long chain—much like a bucket brigade—until finally the node arrives at a node that chooses not to pass along the BBuffer any further, at which the buffer's `Recycle()` function is called to return the buffer to the BBufferGroup's store, where it gets reused by another batch of data.

An application or custom node can set up BBuffers that reference a specific area of memory, such as a low-level driver buffer, a BBitmap, or a BDirectWindow's area of a frame buffer. This ability can provide for great optimization by avoiding unnecessary copy operations.

The BSmallBuffer class, derived from BBuffer, is used for very small buffers; they don't go in BBufferGroups, and get handled specially to optimize performance.

BBuffer should never be subclassed, since they're mostly owned and managed by the Media Server. Even if you create your own BBuffer, once you've called `BBufferConsumer::SetOutputBuffersFor()`, the "same" buffer received back by your BBufferConsumer may actually be another instance of the BBuffer class.

## Constructor and Destructor

The BBuffer constructor and destructor are private; use the appropriate functions in the BBufferGroup class to create and destroy BBuffers.

## Member Functions

### AudioHeader()

media_audio_header *`AudioHeader(`

void`)

`

Returns a pointer to an audio buffer's header; this is just an alias for:

       &BBuffer::Header()->u.raw_audio;

### CloneInfo()

buffer_clone_info `CloneInfo(`void`)` const

Returns a buffer_clone_info structure describing a buffer. This information is primarily for debugging purposes; don't use this buffer_clone_info structure to add a buffer to a buffer group, because it'll just alias an existing buffer.

### Data()

void *`Data(`void`) `

The `Data()` function returns a pointer to the first byte of the buffer, or `NULL` if the buffer somehow couldn't be properly initialized (in which case the buffer can't be used).

### Flags()

int32 `Flags(`void`) `

Returns the buffer's flags. The flags let you specify options for the buffer. For example, you might create a BBufferGroup in which some buffers are intended for odd video fields (`B_F1_BUFFER`), and other buffers are intended for even video fields (`B_F2_BUFFER`), thereby letting you handle interlaced video much more easily by having each buffer know where the video should be displayed.

### Header()

media_header *`Header(`void`) `

Returns a pointer to the buffer's header. This header describes the media data contained therein. The result is only valid for a buffer received from either `BBufferGroup::RequestBuffer()` or `BBufferConsumer::BufferReceived()`.

If you put data into a buffer, you should call `Header()` to obtain a pointer to the buffer's header, then fill out the media_header structure with information describing the buffer's contents.

### ID()

media_buffer_id `ID(`void`) `

If the buffer has been successfully registered with the Media Server, and is available for use by other clients, `ID()` returns a positive buffer ID. Otherwise, a negative number is returned.

### Recycle()

void `Recycle(`void`) `

Sends the buffer back to the BBufferGroup that owns it so the buffer can be reused. You can only call `Recycle()` on a buffer that you received from either the `BBufferGroup::RequestBuffer()` call or the `BBufferConsumer::BufferReceived()` call.

| Don't call both `BroadcastBuffer()` and `Recycle()` on the same buffer.

### SizeAvailable()

size_t `SizeAvailable(`void`) `

Returns the size, in bytes, of the buffer. The actual number of bytes used might be less than this value, and is stored in the buffer's header, which can be obtained by calling the `Header()` function.

### SizeUsed() , SetSizeUsed()

size_t `SizeUsed(`void`) `
void `SetSizeUsed(`ssize_t sizeUsed`) `

`SizeUsed()` returns the number of bytes in the buffer that are currently in use.

`SetSizeUsed()` sets this value. This should be called after writing data into the buffer in order to indicate the size of the written data.

### Type()

media_type `Type(`void`) `

Returns the media type of the data contained within the buffer, as specified by the BBufferProducer from which the buffer originated. This value is only valid if you received the buffer from either the `BBufferGroup::RequestBuffer()` call or the `BBufferConsumer::BufferReceived()` call.

### VideoHeader()

media_video_header *`VideoHeader(`void`) `

Returns a pointer to a video buffer's header; this is just an alias for:

       &BBuffer::Header()->u.raw_video;

## Constants

### Flags

Declared in: be/media/Buffer.h

Constant | Description
--- | ---
`B_F1_BUFFER` | Buffer is for odd fields.
`B_F2_BUFFER` | Buffer is for even fields.
`B_SMALL_BUFFER` | The buffer is a small buffer.

These flags can be assigned to a buffer; the current possible values let you specify whether the buffer should be used for even video fields or odd video fields; if `B_SMALL_BUFFER` is set, the buffer is a BSmallBuffer.

## Structures

### buffer_clone_info

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

       struct buffer_clone_info {
          buffer_clone_info();
          ~buffer_clone_info();
          media_buffer_id buffer;
          area_id area;
          size_t offset;
          size_t size;
          int32 flags;
       private:
          _reserved_[4];
       };

Describes where in memory a BBuffer resides (in terms of the memory area and offset into the area at which the buffer is located, and the size of the buffer), as well as the buffer's flags.

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