VLGETFILLED(3dm)VLGETFILLED(3dm)NAME
vlGetFilled, vlGetFilledByNode, vlDMBufferGetFilledByNode - get the
number of valid entries in a VLBuffer or given path.
SYNOPSIS
#include <dmedia/vl.h>
int vlGetFilled(VLServer server, VLPath path, VLBuffer buffer);
int vlGetFilledByNode(VLServer server, VLPath path, VLNode node);
int vlDMBufferGetFilledByNode(VLServer server, VLPath path, VLNode node);
PARAMETERS
server expects the VL server to use
path expects the VLPath for which you want a filled count
node expects the VL_MEM VLNode on the path
buffer expects the VLBuffer on the VLPath for which
you want a filled count
DESCRIPTIONvlGetFilled(3dm) only returns useful information for a path under the
following circumstances: the path must have a VL_MEM node and a VLBuffer.
The path must already be set up (see vlSetupPaths(3dm)). The path's
transfer must already have begun (see vlBeginTransfer(3dm)).
For a VLbuffer in a video to memory path, vlGetFilled(3dm) returns the
number of entries in the VLBuffer which have been placed there by the
device (using vlPutValid(3dm)) but have not yet been claimed by the
application (using vlGetNextValid(3dm)).
For a VLBuffer in a memory to video path, vlGetFilled(3dm) returns the
number of entries in the VLBuffer which have been placed there by the
application (using vlPutValid(3dm)) but have not yet been claimed by the
device (using vlGetNextValid(3dm)).
vlDMBufferGetFilledByNode(3dm) and vlGetFilledByNode(3dm) are equivalent
to vlGetFilled(3dm) for paths that use DMbufferpools instead of
VLBuffers.
For a DMbufferpool in a video to memory path, vlDMBufferGetFilled(3dm)
returns the number of entries in the DMbufferpool which have been placed
there by the device (using vlDMBufferPutValid(3dm)) but have not yet been
claimed by the application (using vlDMBufferGetValid(3dm)).
For a DMbufferpool in a memory to video path, vlDMBufferGetFilled(3dm)
returns the number of entries in the DMbufferpool which have been placed
there by the application (using vlDMBufferPutValid(3dm)) but have not yet
been claimed by the device (using vlDMBufferGetValid(3dm)).
For a video to memory path, vlGetFilledByNode(3dm) returns the number of
data events which the device has placed into the application's event
queue but which have not yet been claimed by the application.
Page 1
VLGETFILLED(3dm)VLGETFILLED(3dm)
For a memory to video path, vlGetFilledByNode(3dm) returns the number of
data events an application has queued for output to the device using
vlDMBufferSend(3dm) (multiple sends of the same buffer count as different
data events), but which the device has not yet claimed.
vlGetFilledByNode(3dm) is obsolete and works on O2 platforms only (see
vlintro(3dm)).
RETURN VALUE
If successful, vlGetFilled and vlGetFilledByNode return a positive count.
A value of -1 indicates an error, and vlGetErrno(3dm) can be called to
return the error code.
NOTES
For paths using VLBuffers, the vlGetLatestValid(3dm) function may call
vlGetNextValid(3dm) several times, so it may cause the value returned by
vlGetFilled(3dm) to decrease by more than one.
For video to memory paths, you can use vlGetFilled(3dm) and
vlGetFilledByNode(3dm) to determine how much new data is currently
available to be received by the application. This provides a lower bound
on the number of times an application may receive data by calling
routines such as vlGetNextValid(3dm).
For memory to video paths, you can not use these functions to determine
how much space is currently available in an output VLBuffer or
DMbufferpool (which would give you a lower bound on the number of times
you will successfully be able to call vlGetNextFree(3dm) or
dmBufferAllocate(3dm) to reserve space). If you are using traditional
VLBuffers, there is currently no way to determine this except simply
calling vlGetNextFree(3dm) and seeing if it works. If you are using
DMbufferpools, you can use the dmBufferGetPoolState(3dm) call to
determine the current amount of free space in the buffer pool.
Also note for memory to video paths: the device may choose to claim
pending output buffers or data events at any time between when the
application sends them and when they need to be output. Therefore, on
some devices, these functions may not be a good indication of the amount
of data buffered up for output. The UST/MSC functions (see
vlGetFrontierMSC(3dm)) provide a much better indication of the current
amount of buffering for both video to memory and memory to video paths.
SEE ALSOvlGetFrontierMSC(3dm), vlGetUSTPerMSC(3dm)
Page 2
