videoSetFieldMode(3mms) — Subroutines
Name
videoSetFieldMode --- Set the current video field mode
Syntax
#include <mme/mme_api.h>
MMRESULT videoSetFieldMode(
HVIDEO hVideo,
DWORD dwMode);
Arguments
HVIDEO hVideo
Specifies a handle to a video device channel.
DWORD dwMode
Specifies the field mode. The mode must be one of the following:
VIDEO_MODE_FRAME
VIDEO_MODE_FRAME_EVEN_DOM
VIDEO_MODE_FRAME_ODD_DOM
VIDEO_MODE_FIELD_BOTH
VIDEO_MODE_FIELD_ODD_ONLY
VIDEO_MODE_FIELD_EVEN_ONLY
Description
The videoSetFieldMode function sets the current video field mode. Call this function after any calls to the videoSetStandard function and before any calls to the videoConfigure function with the DVM_FORMAT and VIDEO_CONFIGURE_SET flags. If you want to change the field mode after calling videoConfigure, you must call videoConfigure again after calling videoSetFieldMode.
Not all field modes are supported on all devices and not all field modes are supported for all formats.
Interlaced video data contains both even and odd fields. Each field is half the height of a full frame. The lines in each of the fields represent the even or odd lines in the full frame. Sometimes, just odd or even fields are acceptable to capture and playback to reduce the overhead required in processing data. At other times, full frames are required to prevent any loss of content. Some devices cannot return full frames of data, however. They may, though, be able to return alternating even and odd fields.
VIDEO_MODE_FRAME tells the hardware device to use full frames and indicates the default dominance of the device. (For more information about field mode dominance, see the Extensions section of this function.) VIDEO_MODE_FIELD_EVEN_ONLY and VIDEO_MODE_FIELD_ODD_ONLY tell the device to use just the even or odd fields, respectively, dropping half the video information. VIDEO_MODE_FIELD_BOTH tells the device to use both odd and even fields. In all but the last mode, only one type of frame or field can be exchanged with the device. However, when the mode is VIDEO_MODE_FIELD_BOTH, the application must tell the device which field is involved. The functions videoFrame and videoStreamAddBuffer have been extended to recognize a new flag in the VIDEOHDR dwFlags field. VHDR_FIELD_ODD and VHDR_FIELD_EVEN tell the device which field to use the buffer for. On capture, the device will wait until the next specified field and fill in the buffer with that field. On playback, the device will play back the buffer during that field period. If buffers are not queued before the next field time, then that field and the next field will be missed since the device will have to wait for the next odd or even field, depending on the field specification.
When composing a full frame from two fields or decomposing a frame into two fields, the first line of the frame contains the first line of the even field, the second line of the frame contains the odd field, and so on. The following C code fragment shows code to decompose a frame into two fields:
char ∗ fieldEven, ∗ fieldOdd, ∗ frame;
int width, height;
int i;
for ( i=0; i < height/2; i++) {
bcopy(&frame[(i∗2)∗width], &fieldEven[i∗width], width);
bcopy(&frame[(i∗2+1)∗width], &fieldOdd[i∗width], width);
}
Dithering on some devices depends on adjacent lines. If the device is returning alternating odd and even fields in a dithered format, then the quality of a resulting frame will not be as good as the quality from a captured frame. It might be possible to capture data in a nondithered format (such as YUV), compose the frame in that format, and then dither the resulting frame, using the ICDecompress function. For example, you can capture the images in YUV format and then dither them by calling the ICDecompress function to convert the YUV format to 8-bit X image format.
Standard image sizes are as follows:
frame@640x480@T{ 768x576 T} field@640x240@T{ 768x288 T}
Field Mode Dominance
The videoSetFieldMode function has been extended to include field mode dominance support. Capturing full-frame video requires combining two consecutive video fields in one frame. The first field in the pair is referred to as the dominant field. Source and destination video devices should agree on field dominance. If they do not, then reversed dominance, such as framing artifacts in full-frame mode, can occur. This can be seen by magnifying an area of motion in a captured frame to see temporal artifacts or jagged edges in the images. <P> The VIDEO_MODE_FRAME flag has been extended to indicate the default dominance of a hardware device. Two flags, VIDEO_MODE_FRAME_EVEN_DOM and VIDEO_MODE_FRAME_ODD_DOM, have been added to specify even and odd dominance, respectively. If the field mode is set to VIDEO_MODE_FRAME and a query of the field mode using the videoGetFieldMode function is made, the device will return the field mode dominance it is using (video capture only at this time). <P> Not all devices can be adjusted. Setting the field mode to VIDEO_MODE_FRAME_EVEN_DOM or VIDEO_MODE_FRAME_ODD_DOM may result in an error if that particular dominance is not currently supported. Use VIDEO_MODE_FRAME if the dominance is not important to an application. Be aware of this error if your application deinterlaces images on its own. Be careful about placing even and odd fields in the frames your application composes (video capture) or decomposes (video playback).
Extensions
None.
Return Values
Returns DV_ERR_OK if the function is successful; otherwise, it returns one of the following error codes:
DV_ERR_UNSUPPORTED@T{ The function is not supported for the device. T} DV_ERR_PARAM1@T{ The mode is not valid or not currently supported by the device. T} DV_ERR_INVALHANDLE@T{ The specified device handle is invalid. T}
Device-Specific Notes
The J300 supports the following modes:
FRAME@Y@T{ N T} EVEN_ONLY@Y@T{ Y T} ODD_ONLY@N@T{ N T} BOTH@Y@T{ Y T}
As previously discussed, dithered images (8-bit X Image format) captured from the J300 in even and odd field mode will look grainy. It is possible to capture the images in YUV format and then dither them by calling the ICDecompress function to convert the YUV format to 8-bit X Image format.
Field Mode Dominance
The following notes regarding field mode dominance are specific to the Sound and Motion J300 and FullVideo Supreme option modules.
The Sound and Motion J300 option module does not permit adjustment of field dominance. It is always set to even.
The FullVideo Supreme JPEG option module and Revision B of the FullVideo Supreme (AV301) option module allow adjustment of video capture field dominance. By default, these option modules use odd dominance for video capture. Both boards use odd dominance for video playback, but the dominance cannot be adjusted.
The FullVideo Supreme option modules that support this can be determined by examining the part number on the module itself:
Revision A 54-23296-04.A01
Revision B 54-23296-04.B01