videoFrame(3mms) — Subroutines
Name
videoFrame --- Transfer a single frame from or to a video device channel
Syntax
#include <mme/mme_api.h>
MMRESULT videoFrame(HVIDEO hVideo,
LPVIDEOHDR lpVHdr);
Arguments
HVIDEO hVideo
Specifies a handle to a video device channel. The channel must be of type VIDEO_IN or VIDEO_OUT.
LPVIDEOHDR lpVHdr
Specifies a pointer to a VIDEOHDR data structure.
The VIDEOHDR data structure must be allocated with the mmeAllocMem function before being passed to the videoFrame function. The data buffer pointed to by its lpData field or the data buffers pointed to by its lpData2 field must must be allocated using the mmeAllocBuffer or mmeAllocBufferAndGetShminfo function.
Description
The videoFrame function transfers a single frame from or to a video device channel. Use the videoFrame function with a VIDEO_IN channel to transfer a single image from the capture hardware frame buffer. Use the videoFrame function with a VIDEO_OUT channel to transfer a single image to the capture hardware frame buffer.
To determine the size of the buffer needed for capturing data, use the videoConfigure function. If the buffer size is not large enough, the videoFrame function can fail.
See the videoConfigure(3mms) reference page for detailed information determining the size of the buffer required.
If the image data to be played back is in JPEG format (JPEG_DIB or MJPG_DIB) or if the captured buffer is JPEG format, a dual buffers scheme can be used to simultaneously play back the input image and return an uncompressed image (8-bit dithered or 24-bit X image, YUV, or BI_BITFIELDS format) to the application. The application can display the dithered image to allow viewing of the image that is being played back.
In Microsoft Video for Windows (VFW), the VIDEOHDR data structure fields dwFlags and dwBytesUsed are frequently updated to reflect the state of the buffer as it is processed by the driver. On UNIX systems, these fields are updated only once when the buffer is returned to the client.
Extensions
The VIDEOHDR data structure has been extended by three fields: lpData2, dwBufferLength2, and dwBytesUsed2, to support multiple buffers for use with the FullVideo Supreme JPEG and Sound and Motion J300 option modules.
For video playback, the dwBytesUsed field of the VIDEOHDR data structure is filled with the size of the buffer that was passed to the videoFrame function.
The videoFrame function has been extended to recognize the flags VHDR_FIELD_EVEN and VHDR_FIELD_ODD in the dwFlags field of the data structure VIDEOHDR. When the VIDEO_MODE_FIELD_BOTH field mode is used, the application tells the device which field to use by setting the dwFlags field to either VHDR_FIELD_EVEN or VHDR_FIELD_ODD. On capture, the device fills the buffer with the field from the next captured frame. On playback, the device places the data in the buffer of the next frame’s field.
Return Values
Returns DV_ERR_OK if the function is successful; otherwise, it returns the following error code:
DV_ERR_CREATEPALETTE@T{ A PALETTE must have been set previous to this operation when the biCompression is BICOMP_DECXIMAGEDIB and the biBitCount is 8, otherwise this error is returned. T} DV_ERR_INVALHANDLE@T{ The specified device handle is invalid. T}