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


DESCRIPTION
     vlGetFilled(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.
     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 ALSO
     vlGetFrontierMSC(3dm), vlGetUSTPerMSC(3dm)