BOOL
VC_StreamAddBuffer(
VCUSER_HANDLE vh,
LPVIDEOHDR lpvh
);
The VC_StreamAddBuffer function adds a buffer to a video capture driver’s queue of buffers used to receive video capture input frames.
Parameters
vh
Handle to the kernel-mode driver, obtained from VC_OpenDevice.
lpvh
Pointer to a VIDEOHDR structure defining the buffer to be queued.
Return Value
Returns TRUE if the operation succeeds. Otherwise returns FALSE.
Comments
A user-mode video capture driver using VCUser.lib should call VC_StreamAddBuffer when its DriverProc function receives a DVM_STREAM_ADDBUFFER message.
If the driver has not called VC_StreamStart to start reading frames, the specified buffer is added to the user-mode driver’s buffer queue. If VC_StreamStart has been called, the VC_StreamAddBuffer function tries to send the buffer to the kernel-mode driver. To limit the amount of memory the kernel-mode driver must lock, a maximum of two buffers are queued to the kernel-mode driver at one time. Any additional buffers are queued in the user-mode driver until the kernel-mode driver’s queue contains less than two buffers. The VC_StreamAddBuffer function always returns after the buffer is queued, without waiting for captured data to be placed in the buffer.
To send a buffer to the kernel-mode driver, the VC_StreamAddBuffer function calls DeviceIoControl (described in the Win32 SDK), specifying an IOCTL_VIDC_ADD_BUFFER control code. If the kernel-mode driver is using VCKernel.lib, and if the specified buffer length is smaller than the image size value specified with VC_SetImageSize, the buffer is not queued. If the buffer size is acceptable, VCKernel.lib places the buffer’s I/O request packet (IRP) in a queue, where it stays until needed to receive a captured frame. (For more information about IRPs, see the Kernel-Mode Drivers Design Guide.)
If the kernel-mode driver fails to lock the buffer in the client’s address space (because the buffer is too large for the system’s memory resources), then VCUser.lib sends IOCTL_VIDC_CAP_TO_SYSBUF, IOCTL_VIDC_PARTIAL_CAPTURE, and IOCTL_VIDC_FREE_SYSBUF, control codes to request the kernel-mode driver to copy frame buffer data into a system-allocated buffer. The data is then copied to the client’s buffers as smaller, partial frame sections.