Before a DMbufferpool is created, you must obtain the pool requirements of any library that will interact with the pool. Pool requirements are maintained in a DMparams list, created using dmParamsCreate() and initialized by calling dmBufferSetPoolDefaults(). See Chapter 3 in the Digital Media Programming Guide for an overview of DMparams. The function prototype for this call is

DMstatus dmBufferSetPoolDefaults(DMparams *poolParams, int bufferCount, int bufferSize, DMboolean cacheable, DMboolean mapped)

where

The Video Library pool requirements are obtained by calling vlDMBufferGetParams() on a memory node:

int vlDMBufferGetParams(VLServer svr, VLPath path, VLNode node, DMparams *params)

where

As with similar calls in other libraries, vlDMBufferGetParams takes as input a DMparams list initialized by dmBufferSetPoolDefaults, and possibly other libraries' pool requirements functions. On output, the Video Library's requirements are merged with the input requirements.

After all libraries that will use the pool have been queried for their requirements, the application can create a DMbufferpool by calling dmBufferCreatePool. Its function prototype is

DMstatus dmBufferCreatePool(const DMparams *poolParams, DMbufferpool *returnPool)

where

If the application captures video data, it specifies the DMbufferpool the memory node should use by calling vlDMBufferPoolRegister:

int vlDMBufferPoolRegister(VLServer svr, VLPath path, VLNode node, DMbufferpool pool)

where

When the video device is ready to capture a new frame or field, it will allocate a DMbuffer from the specified pool, place the field or frame in it, then send the buffer to the application.

To begin data transfer (for either type of buffer), use vlBeginTransfer(). Its function prototype is

int vlBeginTransfer(VLServer vlSvr, VLPath path, int count,
      VLTransferDescriptor* xferDesc) 

where

Tailor the data transfer by means of transfer descriptors. Multiple transfer descriptors are supplied; they are executed in order. The transfer descriptors are

This example fragment transfers the entire contents of the buffer immediately.

xferDesc.mode = VL_TRANSFER_MODE_DISCRETE;

xferDesc.count = imageCount;
xferDesc.delay = 0;
xferDesc.trigger = VLTriggerImmediate;

This fragment shows the default descriptor, which is the same as passing in a null for the descriptor pointer. Transfer begins immediately; count is ignored.

xferDesc.mode = VL_TRANSFER_MODE_CONTINUOUS;

xferDesc.count = 0;
xferDesc.delay = 0;
xferDesc.trigger = VLTriggerImmediate;

After the transfer has been started, captured video may be retrieved using vlDMBufferGetValid:

int vlDMBufferGetValid(VLServer svr, VLPath path, VLNode node, DMbuffer* dmbuffer)

where

The DMbuffer handle returned by vlDMBufferGetValid is an opaque reference to the captured video. dmBufferMapData can be used to obtain a pointer to the actual image data so that it can be processed or written to disk. dmBufferMapData does not have to be called if the buffer will be directly sent to another device or library.

Applications can use vlDMBufferPutValid to send buffers to a video device:

int vlDMBufferPutValid(VLServer svr, VLPath path, VLNode node, DMbuffer dmbuffer)

where

The DMbuffer may have been obtained from another library, such as dmIC, or generated by the application itself. See Chapter 5 in the Digital Media Programming Guide for an explanation of how to allocate a DMbuffer from a DMbufferpool.

Once the application is done with a buffer, it should call dmBufferFree to indicate that it no longer intends to use the buffer. After all users of a buffer have called dmBufferFree on it, the buffer is considered free to be reallocated. The Video Library never implicitly releases the application's access to a buffer. Consequently, an application can send the same buffer to a memory node multiple times, or hold a captured image for an indefinite period.

Once you have specified frame parameters in a transfer involving memory (or have determined to use the defaults), create a VL buffer for the video data. In this case, video data is frames or fields, depending on the capture type:

VL buffers provide a way to read and write varying sizes of video data. A frame of data consists of the actual frame data and an information structure describing the underlying data, including device-specific information.

When a VL buffer is created, constraints are specified that control the total size of the data segment and the number of frame or field buffers (sectors) to allocate. A head and a tail flag are automatically set in a VL buffer so that the latest frame can be accessed. A sector is locked down if it is not called; that is, it remains locked until it is read. When the VL buffer is written to and all sectors are occupied, data transfer stops. The sector last written to remains locked down until it is released.

All sectors in a VL buffer must be of the same size, which is the value returned by vlGetTransferSize(). Its function prototype is

long vlGetTransferSize(VLServer vlSvr, VLPath path)

For example:

transfersize = vlGetTransferSize(vlSvr, path); 

where transfersize is the size of the data in bytes.

To create a VL buffer for the frame data, use vlCreateBuffer(). Its function prototype is

VLBuffer vlCreateBuffer(VLServer vlSvr, VLPath path, VLNode node, 
     int numFrames)

where

For example:

buf = vlCreateBuffer(vlSvr, path, src, 1); 

Table 5-2 shows the relationship between capture type and minimum VL buffer size.

---

Note: For memory nodes, real-time memory or video transfer can be performed only as long as buffer sectors are available to the OCTANE Personal Video device.

---

Use vlRegisterBuffer() to register the VL buffer with the data path. Its function prototype is

int vlRegisterBuffer(VLServer vlSvr, VLPath path,
     VLNode memnodeid, VLBuffer buffer)

where

For example:

vlRegisterBuffer(vlSvr, path, drn, Buffer);

Start data transfer the same way as for DMbuffers; see “Starting Data Transfer” in “Transferring Video Data Using DMbuffers.”

If your application uses a VL buffer, use various VL calls for reading frames, getting pointers to active buffers, freeing buffers, and other operations. Table 5-3 lists the buffer-related calls.

Figure 5-1 illustrates the difference between vlGetNextValid() and vlGetLatestValid().

Figure 5-1. vlGetNextValid() and vlGetLatestValid()

Table 5-4 lists the calls that extract information from a buffer.

---

Caution: None of these calls has count or block arguments; appropriate calls in the application must deal with a NULL return in cases of no data being returned.

---

In summary, for video-to-memory transfer, use

buffer = vlCreateBuffer(vlSvr, path, memnode1);
vlRegisterBuffer(vlSvr, path, memnode1, buffer); 
vlBeginTransfer(vlSvr, path, 0, NULL); 
info = vlGetNextValid(vlSvr, buffer);
/* OR vlGetLatestValid(vlSvr, buffer); */
dataptr = vlGetActiveRegion(vlSvr, buffer, info); 

/* use data for application */
…
vlPutFree(vlSvr, buffer); 

For memory-to-video transfer, use

buffer = vlCreateBuffer(vlSvr, path, memnode1);
vlRegisterBuffer(vlSvr, path, memnode1, buffer); 
vlBeginTransfer(vlSvr, path, 0, NULL); 
buffer = vlGetNextFree(vlSvr, buffer, bufsize); 
/* fill buffer with data */
…
vlPutValid(vlSvr, buffer); 

To read the frames to memory from the buffer, use vlGetNextValid() to read all the frames in the buffer or get a valid frame of data. Its function prototype is

VLInfoPtr vlGetNextValid(VLServer vlSvr, VLBuffer vlBuffer)

Use vlGetLatestValid() to read only the most current frame in the buffer, discarding the rest. Its function prototype is

VLInfoPtr vlGetLatestValid(VLServer vlSvr, VLBuffer vlBuffer) 

After removing interesting data, return the buffer for use with vlPutFree() (video to memory). Its function prototype is

int vlPutFree(VLServer vlSvr, VLBuffer vlBuffer)

To send frames from memory to video, use vlGetNextFree() to get a free buffer to which to write data. Its function prototype is

VLInfoPtr vlGetNextFree(VLServer vlSvr, VLBuffer vlBuffer,
      int size)

After filling the buffer with the data you want to send to video output, use vlPutValid() to put a frame into the valid list for output to video (memory to video). Its function prototype is

int vlPutValid(VLServer vlSvr, VLBuffer vlBuffer)

---

Caution: These calls do not have count or block arguments; appropriate calls in the application must deal with a NULL return in cases of no data being returned.

---

To get DMediaInfo and Image Data from the buffer, use vlGetActiveRegion() to get a pointer to the active buffer. Its function prototype is

void * vlGetActiveRegion(VLServer vlSvr, VLBuffer vlBuffer,
     VLInfoPtr ptr)

Use vlGetDMediaInfo() to get a pointer to the DMediaInfo structure associated with a frame. This structure contains timestamp and field count information. The function prototype for this call is

DMediaInfo * vlGetDMediaInfo(VLServer vlSvr, VLBuffer vlBuffer, 
     VLInfoPtr ptr)

Use vlGetImageInfo() to get a pointer to the DMImageInfo structure associated with a frame. This structure contains image size information. The function prototype for this call is

DMImageInfo * vlGetImageInfo(VLServer vlSvr, VLBuffer vlBuffer, 
     VLInfoPtr ptr)