DVM_FORMAT

The DVM_FORMAT message requests a user-mode video capture driver to set a specified data format, or to return the current format, for the specified channel.

Parameters

dwDriverID

Video channel identifier. One of VIDEO_EXTERNALIN, VIDEO_IN, VIDEO_OUT, VIDEO_EXTERNALOUT. (For details, see Opening Video Channels.) Typically, drivers only allow VIDEO_IN for this message.

hDriver

Driver handle.

uMsg

DVM_FORMAT

lParam1

Contains flags. The following flags are defined.

Flag	Definition
VIDEO_CONFIGURE_CURRENT	The driver sets or returns the current format.
VIDEO_CONFIGURE_GET	The driver returns the requested information to the client.
VIDEO_CONFIGURE_MAX	The driver returns the maximum-sized format. (Used only with VIDEO_CONFIGURE_GET.)
VIDEO_CONFIGURE_MIN	The driver returns the minimum-sized format. (Used only with VIDEO_CONFIGURE_GET.)
VIDEO_CONFIGURE_NOMINAL	The driver returns the nominal format. (Used only with VIDEO_CONFIGURE_GET.)
VIDEO_CONFIGURE_QUERY	The driver indicates whether or not it supports the specified request.
VIDEO_CONFIGURE_QUERYSIZE	The driver returns the size, in bytes, of the format description.
VIDEO_CONFIGURE_SET	The driver sets a client-specified format description.

lParam2

Pointer to a VIDEOCONFIGPARMS structure. For the DVM_FORMAT message, the structure members are used as follows:

lpdwReturn

Pointer to a DWORD in which the driver returns the size, in bytes, of the BITMAPINFOHEADER structure, if the VIDEO_CONFIGURE_QUERYSIZE flag is set.

lpData1

Pointer to a client-supplied BITMAPINFOHEADER structure. (For more information about the BITMAPINFOHEADER structure, see the Win32 SDK.)

dwSize1

Size, in bytes, of the BITMAPINFOHEADER structure.

lpData2

Not used.

dwSize2

Not used.

Return Value

The driver should return DV_ERR_OK if the operation succeeds. Otherwise, it should return one of the DV_ERR error codes defined in msvideo.h. Custom error codes are also allowed (see DVM_GETERRORTEXT).

Comments

A client sends the DVM_FORMAT message by calling the driver’s DriverProc entry point, passing the specified parameter values. Applications can send this message by calling the videoConfigure function, which is described in the Video for Windows Development Kit.

The driver should test the VIDEO_CONFIGURE_SET and VIDEO_CONFIGURE_GET flags to determine whether to set or to return a format description. If neither of these flags is set, the driver should return an error code.

When a client sends this message, it must also include the address of a BITMAPINFOHEADER structure (unless either the VIDEO_CONFIGURE_QUERY or VIDEO_CONFIGURE_QUERYSIZE flag is set). Depending on whether the client has set VIDEO_CONFIGURE_SET or VIDEO_CONFIGURE_GET, the driver either reads or writes the contents of this structure.

If the VIDEO_CONFIGURE_QUERYSIZE flag is set, the driver just returns the size of the BITMAPINFOHEADER structure.

For more information on how drivers should allow applications and users to set the video data format, see Setting the Video Data Format.

User-mode video capture drivers using VCUser.lib can call VC_ConfigFormat when processing the DVM_FORMAT message.