dmBuffer(3dm) dmBuffer(3dm)
NAME
dmBufferSetPoolDefaults, dmBufferCreatePool, dmBufferDestroyPool - create
DMbufferpool
SYNOPSIS
#include <dmedia/dmbuffer.h>
DMstatus dmBufferSetPoolDefaults
( DMparams* poolParams,
int bufferCount,
int bufferSize,
DMboolean cacheable,
DMboolean mapped );
DMstatus dmBufferCreatePool
( const DMparams* poolParams,
DMbufferpool* returnPool );
DMstatus dmBufferDestroyPool( DMbufferpool pool );
DESCRIPTION
These functions are used to create and destroy pools of digital media
buffers. The pools and buffers are used for passing data among
application programs and for passing data to and from the digital media
libraries.
When creating a buffer pool, you must make sure that it is compatible
with all of the libraries with which it will be used. Different
libraries will have different memory allocation constraints, such as
alignment constraints, based on the I/O devices that they control. The
sequence of calls to create a buffer pool is: (1) call
dmBufferSetPoolDefaults to initialize a parameter list that holds the
settings for the pool, (2) call the different libraries that will be used
with the pool to update the parameter list based on their constraints,
and (3) call dmBufferCreatePool to create the pool based on the settings
in the parameter list.
The functions to get pool requirements from the various libraries are
dmICGetDstPoolParams(3dm), dmICGetSrcPoolParams(3dm),
dmBufferGetGLPoolParams(3dm), and vlDMPoolGetParams(3dm).
When the pool is no longer needed, dmBufferDestroyPool is used to free
it. However, the resources used by the pool will not actually be freed
until all of the clients of the pool have released it, and all of the
buffers allocated from that pool have been freed.
POOL PARAMETERS
The arguments to dmBufferSetPoolDefaults(3dm) are described as follows.
bufferSize
This is the default size, in bytes, of each buffer in the pool. All
of the buffers are the same size unless the pool was created with
Page 1
dmBuffer(3dm) dmBuffer(3dm)
the DMPOOLVARIABLE parameter set (see below).
This default buffer size may be increased when getting pool
parameters from a library, but will never be decreased.
bufferCount
This is the number of buffers in the pool. The buffer count may be
increased when getting pool parameters from a library, but will
never be decreased.
This value is stored as the value of the DMBUFFERCOUNT parameter.
An example of how to manipulate this parameter directly appears
below.
mapped
This is a boolean flag. When set to DMTRUE, it indicates that the
entire pool should be mapped into the address space of the
application program when it is created. When set to DMFALSE, block
are mapped individually when dmBufferMapData is called; they are
unmapped when dmBufferFree is called.
Mapping the entire pool means that dmBufferMapData simply returns a
pointer into an already mapped pool. This can be substantially
faster than adding a new memory mapping. The size of the pool
should be considered when setting this parameter as very large
buffer pools might not fit or severely limit the remaining space in
the processes address space.
cacheable
This is a boolean values that indicates whether or not caching
should be turned on when a buffer is mapped into the address space
of an application program. Setting it to DM_TRUE will turn on
caching, which means that CPU-based algorithms that read or write
the buffer will be faster. Setting it to DM_FALSE turns off
caching, which means that passing data between the CPU and other
parts of the computer may be faster because there is no overhead to
maintain cache coherency.
A pool from which different sized DMbuffers may be allocated is created
by setting the parameter DMPOOLVARIABLE with the call
dmParamsSetEnum(poolParams, DMPOOLVARIABLE, DMTRUE)
Pools created with this parameter set can be used both with
dmBufferAllocate to allocate buffers of default size as specified in
dmBufferSetPoolDefaults, or by dmBufferAllocateSize where the size is
specified as a parameter to that routine (see dmbufferAllocateSize(3dm)).
The size of a DMbufferpool created with the DMPOOLVARIABLE parameter
enabled can be set explicitly rather than by the default method (i.e.
bufferCount * bufferSize) by setting the DMPOOLSIZE parameter with the
call
Page 2
dmBuffer(3dm) dmBuffer(3dm)
dmParamsSetLongLong(poolParams, DMPOOLSIZE, nbytes)
where nbytes is the entire pool size in bytes. Use of this parameter
allows an application to independently specify buffer count, pool size
and default buffer allocation size.
BUFFER COUNT
Determining the number of buffers to allocate in a pool means adding up
the requirements of all of the clients that are using the pool. For
example, a program that passes buffers from a video input path to a video
output path and inserts closed captioning data would need enough buffers
for: (1) the input path, (2) the output path, and (3) the application
itself. Because this example uses both video paths at the same time, it
must make sure that enough buffers are allocated so that both can run
concurrently.
The functions that get pool parameters from the digital media libraries
update the DMBUFFERCOUNT parameter. They set it to the maximum of: the
previous setting, and the number required by the library. If you want to
use multiple clients with one pool at the same time, you must add up
their buffer requirements yourself.
Below is an example that adds the number of buffers required for two
video paths, plus two more buffers for the application to use:
DMbufferpool allocatePool(
VLServer server,
VLPath path1,
VLNode node1,
VLPath path2,
VLNode node2
)
{
DMstatus s;
int vs;
int bufferCount;
DMbufferpool pool;
/* Create a parameter list to hold the pool specs. */
s = dmParamsCreate( &poolParams );
if ( s != DM_SUCCESS ) handleError();
/* Set up the initial parameters, based on the way */
/* this program will access the buffers. */
bufferCount = 2; /* number of buffers the app needs */
s = dmBufferSetPoolDefaults(
poolParams,
0, /* buffer size. vl will set */
0, /* number of buffers */
Page 3
dmBuffer(3dm) dmBuffer(3dm)
DM_TRUE, /* cached? */
DM_TRUE /* mapped? */
);
if ( s != DM_SUCCESS ) handleError();
/* Get the constraints for the two video paths. */
/* Add the buffer counts because they'll be used */
/* at the same time */
s = dmParamsSetInt( poolParams, DM_BUFFER_COUNT, 0 );
if ( s != DM_SUCCESS ) handleError();
vs = vlDMPoolGetParams( server, path1, node1, poolParams );
bufferCount += dmParamsGetInt( poolParams, DM_BUFFER_COUNT );
s = dmParamsSetInt( poolParams, DM_BUFFER_COUNT, 0 );
if ( s != DM_SUCCESS ) handleError();
vs = vlDMPoolGetParams( server, path2, node2, poolParams );
bufferCount += dmParamsGetInt( poolParams, DM_BUFFER_COUNT );
/* Create the pool */
s = dmParamsSetInt( poolParams, DM_BUFFER_COUNT, bufferCount );
if ( s != DM_SUCCESS ) handleError();
s = dmBufferCreatePool( poolParams, &pool );
if ( s != DM_SUCCESS ) handleError();
/* Clean up and return the pool. */
dmParamsDestroy( poolParams );
return pool;
}
DIAGNOSTICS
All three functions return DMSUCCESS when successful, and DMFAILURE
otherwise. Error codes can be obtained from dmGetError(3dm).
SEE ALSO
dmParamsCreate(3dm), dmParamsDestroy(3dm), dmICGetDstPoolParams(3dm),
dmICGetSrcPoolParams(3dm), dmBufferGetGLPoolParams(3dm),
vlDMPoolGetParams(3dm), dmGetError(3dm), glXCreateGLXPbufferSGIX(3G).
Page 4