dmBuffer(3dm)dmBuffer(3dm)NAME
dmBufferSetPoolDefaults, dmBufferCreatePool, dmBufferDestroyPool - create
DMbufferpool
SYNOPSIS
#include <dmedia/dm_buffer.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 DM_POOL_VARIABLE 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 DM_BUFFER_COUNT parameter.
An example of how to manipulate this parameter directly appears
below.
mapped
This is a boolean flag. When set to DM_TRUE, it indicates that the
entire pool should be mapped into the address space of the
application program when it is created. When set to DM_FALSE, 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 DM_POOL_VARIABLE with the call
dmParamsSetEnum(poolParams, DM_POOL_VARIABLE, DM_TRUE)
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 DM_POOL_VARIABLE parameter
enabled can be set explicitly rather than by the default method (i.e.
bufferCount * bufferSize) by setting the DM_POOL_SIZE parameter with the
call
Page 2
dmBuffer(3dm)dmBuffer(3dm)
dmParamsSetLongLong(poolParams, DM_POOL_SIZE, 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 DM_BUFFER_COUNT 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;
}
SUPPORT FOR MULTI-NODE SYSTEMS
On large machines, with multiple node cards, the additional pool
parameters DM_POOL_NODE_MASK and DM_POOL_NODE_DIST are supported. These
allow developers to fine-tune buffer allocation for a particular
application and hardware configuration.
The parameter NODE_MASK allows buffer pages to be allocated on specific
node cards. If not set, or set to zero, memory is allocated as normal.
If non-zero, then pages in the buffer pool are distributed evenly across
multiple nodes. Each bit in the 64-bit node mask enables buffer
allocation on that particular node. For example, in a three node system,
if you wished to distribute buffers across memory in the second and third
nodes, then set the node mask to 0x6.
If the NODE_MASK has more than 1 bit set, then the NODE_DIST parameter
controls the number of pages sequentially allocated on each node. Buffer
allocation is achieved by allocating NODE_DIST pages on the lowest node
in the NODE_MASK, then allocating NODE_DIST pages on the next node, and
so on; repeatedly cycling through all nodes until all required pages have
been allocated. The default NODE_DIST is 1, giving the finest
distribution granularity. NODE_DIST is 64 bits (a long long parameter).
In the current implementation, the upper 33 bits are reserved and must be
Page 4
dmBuffer(3dm)dmBuffer(3dm)
0.
If available hardware will not support your specified allocation
strategy, the system will silently attempt simpler allocation strategies.
You can use the command "osview -a" to examine memory allocation per node
at runtime.
In the current implementation, only memory on the first 64 nodes may be
used for buffer allocation.
DIAGNOSTICS
All three functions return DM_SUCCESS when successful, and DM_FAILURE
otherwise. Error codes can be obtained from dmGetError(3dm).
SEE ALSOdmParamsCreate(3dm), dmParamsDestroy(3dm), dmICGetDstPoolParams(3dm),
dmICGetSrcPoolParams(3dm), dmBufferGetGLPoolParams(3dm),
vlDMPoolGetParams(3dm), dmGetError(3dm), glXCreateGLXPbufferSGIX(3G).
Page 5
