videoConfigure(3mms) — Subroutines
Name
videoConfigure --- Set or retrieve a configurable driver option
Syntax
#include <mme/mme_api.h>
MMRESULT videoConfigure(HVIDEO hVideo,
UINT msg,
DWORD dwFlags,
LPDWORD lpdwReturn,
LPVOID lpData1,
DWORD dwSize1,
LPVOID lpData2,
DWORD dwSize2);
Arguments
HVIDEO hVideo
Specifies a handle to a video device channel.
UINT msg
Specifies a message about the option to set or retrieve. The following messages are defined:
DVM_FORMAT
Indicates that format information is being sent to or retrieved from the video device driver.
DVM_PALETTE
Indicates that a palette is being sent to or retrieved from the video device driver.
See the Description section for information specific to multimedia hardware options.
DWORD dwFlags
Specifies flags for configuring or interrogating the video device driver. The following flags are defined:
VIDEO_CONFIGURE_SET
Indicates that values are being sent to the driver.
VIDEO_CONFIGURE_GET
Indicates that values are being obtained from the driver.
VIDEO_CONFIGURE_QUERY
Used to determine if the driver supports the option specified by the msg argument. This flag should be combined with either the VIDEO_CONFIGURE_SET or VIDEO_CONFIGURE_GET flag. If this flag is set, the lpData1, dwSize1, lpData2, and dwSize2 arguments are ignored.
VIDEO_CONFIGURE_QUERYSIZE
Returns the size, in bytes, of the configuration option in the lpdwReturn argument. This flag is valid only if the
VIDEO_CONFIGURE_GET flag is also set.
VIDEO_CONFIGURE_CURRENT
Requests the current value. This flag is valid only if the
VIDEO_CONFIGURE_GET flag is also set.
VIDEO_CONFIGURE_NOMINAL
Requests the nominal value. This flag is valid only if the
VIDEO_CONFIGURE_GET flag is also set.
VIDEO_CONFIGURE_MIN
Requests the minimum value. This flag is valid only if the
VIDEO_CONFIGURE_GET flag is also set.
VIDEO_CONFIGURE_MAX
Gets the maximum value. This flag is valid only if the
VIDEO_CONFIGURE_GET flag is also set.
LPDWORD lpdwReturn
Points to a DWORD used for returning information from the driver. If the VIDEO_CONFIGURE_QUERYSIZE flag is set, the lpdwReturn argument is filled with the size of the configuration option. The lpdwReturn argument must be allocated with the mmeAllocMem function before being used. See the Description section for information specific to hardware options.
LPVOID lpData1
Specifies a pointer to message-specific data. See the Description section for information specific to hardware options.
DWORD dwSize1
Specifies the size (in bytes) of the lpData1 buffer. See the Description section for information specific to hardware options.
LPVOID lpData2
Specifies a pointer to message-specific data. See the Description section for information specific to hardware options.
DWORD dwSize2
Specifies the size (in bytes) of the lpData2 buffer. See the Description section for information specific to hardware options.
Description
The videoConfigure function sets or retrieves a configurable driver option. Use this function to assign or obtain palette and format information from the Sound and Motion J300 option module. For more details about the BITMAPINFOHEADER data structures and palette information, see the Programmer’s Guide.
The RGBQUAD and BITMAPINFOHEADER data structures must be allocated with the mmeAllocMem function before being passed to the videoConfigure function.
For the Sound and Motion J300 option module, the following information applies.
DVM_PALETTE
For video capture operations, if the msg argument is set to DVM_PALETTE, then:
•The lpdwReturn argument is used to return the size in bytes of the RGB data array. This is equal to:
number of colormap entries ∗ sizeof(RGBQUAD)
if the dwFlags argument is set to:
(VIDEO_CONFIGURE_GET & VIDEO_CONFIGURE_QUERYSIZE)
•The lpData1 argument is the RGB data structure RGBQUAD.
•The dwSize1 argument is the size in bytes of the lpData1 argument.
•The lpData2 argument is not used.
•The dwSize2 argument specifies the number of colors to use when setting the palette. Check the RGBQUAD array returned from VIDEO_CONFIGURE_GET to determine the number of colors actually used by the device. Note: this is a Digital extension to the videoConfigure function. Normally, this field is not used.
For video playback operations, if the msg argument is set to DVM_PALETTE, then:
•If using single buffers with 8-bit X image format, the videoConfigure function requires a palette (which is defined by a 256-entry array of type RGBQUAD) with all 256 colormap entries set. In this case, the data buffer containing the X image data is sent by the application to the VIDEO_OUT channel. The RGBQUAD array is used as the colormap for the X image data when it is converted to the video signal.
When the dwFlags argument is set to VIDEO_CONFIGURE_SET, the videoConfigure function requires that the rgbReserved field of all 256 colormap entries in the RGBQUAD array be set to 1:
for (i=0; i<255; i++) rgb[i].rgbReserved = 1;
•If using dual buffers and the 8 bits/pixel X image format, the data buffer containing the compressed data is sent by the application to the VIDEO_OUT channel, and the data buffer specified for the X image data is filled and sent back to the application. If using 8-bit X image format with dual buffers, a palette is required to translate the compressed data to the uncompressed format. In this case, the palette setup is the same as for capturing data. A call to the videoConfigure function is required to set up the device palette. The application must retrieve the latest palette being used by setting the dwFlags argument to:
(VIDEO_CONFIGURE_GET | VIDEO_CONFIGURE_CURRENT)
The application must use this palette to set the screen colormap appropriately.
DVM_FORMAT
For video capture and playback operations, if the msg argument is set to DVM_FORMAT, then:
•The lpdwReturn argument is not used.
•The lpData1 argument is a pointer to a BITMAPINFOHEADER data structure (LPBITMAPINFOHEADER).
•The dwSize1 argument is the size in bytes of the BITMAPINFOHEADER data structure.
•The lpData2 argument is a pointer to a BITMAPINFOHEADER data structure (LPBITMAPINFOHEADER) only if using dual buffers. Otherwise, this argument is zero.
•The dwSize2 argument is the size of the BITMAPINFOHEADER data structure only if using dual buffers. Otherwise, this argument is NULL.
To get the required size of the buffer for the video data, set the dwFlags argument to:
(VIDEO_CONFIGURE_GET | VIDEO_CONFIGURE_MIN)
and set the width and height of the image in the BITMAPINFOHEADER data structure pointed to by the lpData1 argument. The buffer size is returned in the biSizeImage field of the BITMAPINFOHEADER data structure.
If you are using dual buffering, the lpData2 argument points to the second BITMAPINFOHEADER data structure, and the biSizeImage field of this data structure will be set. If you are not using dual buffering, lpData2 should be NULL.
The videoConfigure function returns the DV_ERR_BADFORMAT error code if the device channel is opened incorrectly. It returns the DV_ERR_NOTSUPPORTED error code if, when using dual buffers, an unsupported combination of formats was chosen (for example, if both buffers are one of 8- or 24-bit X image format or YUV format).
Extensions
When calling videoConfigure with DVM_PALETTE and VIDEO_CONFIGURE_SET, the dwSize2 field deviates from the standard. Refer to the field description under DVM_PALETTE.
Return Values
Returns DV_ERR_OK if the function is successful; otherwise, it returns one of the following error codes:
DV_ERR_BADFORMAT@T{ The size of the palette is incorrect. T} DV_ERR_CREATEPALETTE@T{ Could not create the palette. T} DV_ERR_INVALHANDLE@T{ The specified device handle is invalid. T} DV_ERR_NOTSUPPORTED@T{ The function is not supported. T}