Derived from: none
Declared in: be/media/BufferGroup.h
Library: libmedia.so
Allocation: Constructor only
A BBufferGroup serves as a repository for BBuffers, and can be used to pass those buffers to another node for its use when sending data. It must also be used by your BBufferProducer to acquire BBuffers to put data that you produce into before you send the buffer on to its destination.
You can create a new BBufferGroup by simply calling:
new BBufferGroup;
If you pass in some arguments describing what sort of buffers you want, and how many of them, the group will even create the BBuffers for you. This is how you'll usually use BBufferGroup, from within your BBufferProducer subclass' constructor so you'll know there are buffers ready and waiting when it's time to start sending data. A possible exception is if your node is a filter that simply processes buffers it receives and passes them along.
A BBufferGroup instance runs a thread that reclaims BBuffers whose Recycle() function has been called. If the group is temporarily out of free buffers, a request for a buffer may block until one is available, or until the request times out, if a timeout is specified when the request is made.
BBufferGroup(size_t size, int32 numBuffers = 3,
uint32 placement = B_ANY_ADDRESS,
uint32 lock = B_FULL_LOCK)
BBufferGroup(void)
BBufferGroup(int32 numBuffers, const buffer_id *bufferList)
The first form of the constructor creates a BBufferGroup with some number of BBuffers already allocated by the group. These buffers will all live within a single Kernel Kit area, allocated by the group. The group tries to allocate an area with properties specified by the placement and lock arguments, large enough to hold numBuffers buffers of the specified size (there may be some padding added).
The second form of the constructor creates a BBufferGroup but doesn't create any buffers for it. You should add BBuffers to the group before trying to use it.
The third form of the constructor creates a BBufferGroup that contains the specified list of buffers. bufferList points to an array of buffer IDs for the buffers to be controlled by the group, and numBuffers is the number of buffers in the list. This version of the constructor isn't one you'll use very often.
Before using any buffers from a new BBufferGroup, call InitCheck() to determine if any errors occurred while creating the group.
~BBufferGroup()
Releases all memory used by the BBufferGroup, including the BBuffers it controls.
status_t AddBuffer(const buffer_clone_info &info)
Given the buffer_clone_info, this function adds the buffer to the BBufferGroup. Normally you'll fill out the buffer_clone_info structure yourself.
|
You shouldn't pass the result of a BBuffer::CloneInfo() call to this function, as doing so would create an "alias" buffer for the same memory area. This is probably not the effect you want. |
RETURN CODES
B_OK. No error adding the buffer to the group.
B_NO_MEMORY. Couldn't clone the buffer into the BBufferGroup's address space.
status_t CountBuffers(int32 *outBufferCount)
Returns, in outBufferCount, the number of buffers in the group.
RETURN CODES
B_OK. The number of buffers was returned successfully.
B_BAD_VALUE. Invalid outBufferCount pointer.
status_t GetBufferList(int32 listCount, BBuffer **outBuffers)
Returns a list of all the buffers in the group. When calling GetBufferList(), pass in outBuffers a pointer to an array of BBuffer pointers that you want to be filled with pointers to the group's buffers, and specify the number of elements in the array in listCount.
RETURN CODES
B_OK. No errors.
B_BAD_VALUE. listCount is less than 1, or outBuffers is NULL
status_t InitCheck(void)
Returns the error code resulting from the construction of the BBufferGroup.
RETURN CODES
B_OK. The new group was created successfully.
B_ERROR. Couldn't allocate the buffers for the group.
Area errors. See Areas in the Kernel Kit.
status_t ReclaimAllBuffers(void)
If you pass a buffer group to some other BBufferProducer but pass true for willReclaim in the BMediaRoster::SetOutputBuffers() call, you can later reclaim the buffers into the BBufferGroup by calling Reclaim().
ReclaimAllBuffers() will return B_OK when all buffers are accounted for, or return an error if buffers can't be reclaimed.
If you have buffers that reference some object that might go away (such as a BBitmap), you should call ReclaimAllBuffers() on the group and delete the BBufferGroup before that object goes away.
RETURN CODES
B_OK. All buffers reclaimed successfully.
B_CANNOT_RECLAIM_BUFFERS. Some buffers couldn't be reclaimed.
BBuffer *RequestBuffer(size_t size, bigtime_t timeout = B_INFINITE_TIMEOUT)
status_t RequestBuffer(BBuffer *outBuffer,
bigtime_t timeout = B_INFINITE_TIMEOUT)
Returns a pointer to a BBuffer of at least the specified size that your BBufferProducer subclass can put data into, then pass on to a media_destination. If there isn't a suitable buffer available, the call will block until either a buffer becomes available (in which case the buffer is returned) or the specified timeout is reached.
|
In BeOS Release 4, the timeout is ignored; B_INFINITE_TIMEOUT is always used, regardless of the value you specify. |
RequestBuffer() doesn't use the buffer flags; instead, you can look at the buffers within a BBufferGroup to find a specific buffer to request yourself, based on the value returned by BBuffer::Flags() or BBuffer::Size(), for example. Use the second form of RequestBuffer() to obtain a specific buffer.
The first version of RequestBuffer() returns NULL if no buffer can be obtained, and sets errno to the appropriate error code. The second version returns an appropriate error code.
 |
Don't call RequestBuffer() while an outstanding ReclaimAllBuffers() request is pending. To make sure that doesn't happen, a buffer producer should be designed to not know about the old group anymore once SetBufferGroup() is called to change its buffer group. |
RETURN CODES
B_OK. No errors.
B_MEDIA_BUFFERS_NOT_RECLAIMED. Buffers are in the process of being reclaimed.
B_ERROR. A miscellaneous error occurred.
status_t SetRecyclePriority(int32 priority)
Sets the priority for the BBufferGroup's buffer recycling thread. The specified priority must be between 5 and 120.
RETURN CODES
B_OK. No errors.
B_BAD_VALUE. The requested priority is outside the range 5...120.
The Be Book, in lovely HTML, for BeOS Release 4.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified November 3, 1998.