This section contains an alphabetical listing of the functions an application uses to manage video capture and playback. These functions are prefixed with video.

#include <mme/mme_api.h> MMRESULT videoClose(HVIDEO hVideo)

Arguments HVIDEO hVideo
Specifies a handle to a video device channel. If the function is successful, the handle will be invalid after this call.

Description

The videoClose function closes the specified video device channel. If buffers have been sent with the videoStreamAddBuffer function and they have not been returned to the application, the close operation fails. Use the videoStreamReset function to mark all pending buffers as done.

Return Values

Returns DV_ERR_OK if the function is successful; otherwise, it returns one of the following error codes:

#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 video option modules.

For more details about the BITMAPINFOHEADER data structures and palette information, see Chapter 7.

The RGBQUAD and BITMAPINFOHEADER data structures must be allocated with the mmeAllocMem function before being passed to the videoConfigure function.

For the FullVideo Supreme and FullVideo Supreme JPEG option modules, 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. This is a Compaq 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, the data buffer containing the compressed data is sent by the application to the VIDEO_OUT channel, and the data buffer specified for the uncompressed 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.
  If using dual buffers with this option, the lpData2 argument must point to the second BITMAPINFOHEADER data structure, and the biSizeImage field of this BITMAPINFOHEADER data structure must also be set. If not using dual buffers, the lpData2 argument should be set to NULL.

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 the BITMAPINFOHEADER data structure (LPBITMAPINFOHEADER) only if using dual buffers. Otherwise, this argument is NULL.
• The dwSize2 argument is the size in bytes of the BITMAPINFOHEADER data structure only if using dual buffers. Otherwise, this argument is zero.

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. See Section 4.5 for more information about using dual buffers.

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).

Return Values

Returns DV_ERR_OK if the function is successful; otherwise, it returns one of the following error codes:

#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 hardware frame buffer. Use the videoFrame function with a VIDEO_OUT channel to transfer a single image to the 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 description of the videoConfigure function for detailed information about 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.

The order in which the BITMAPINFOHEADER data structures are passed to the videoConfigure function (when msg is DVM_FORMAT and dwFlags is VIDEO_CONFIGURE_SET) is the expected order of the buffers pointed to by the lpData2 field of the VIDEOHDR data structure passed to this function.

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 OpenVMS systems, these fields are updated only once when the buffer is returned to the client.

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.

See Section 4.4.2 and Section 4.5 for more information about the VIDEOHDR data structure and using multiple buffers.

Return Values

Returns DV_ERR_OK if the function is successful; otherwise, it returns the following error code:

#include <mme/mme_api.h> DWORD videoGetBrightness(HVIDEO hVideo)

Arguments HVIDEO hVideo
Specifies a handle to a video device channel.

Description

The videoGetBrightness function obtains the current brightness value. This brightness value is applied to the 8-bit X image data returned to the application. This request is not supported for video playback using a single buffer.

Return Values

Returns the current brightness value if the function is successful; otherwise, it returns one of the following error codes:

#include <mme/mme_api.h> MMRESULT videoGetChannelCaps(HVIDEO hvideo, LPCHANNEL_CAPS lpChannelCaps, DWORD dwSize);

Arguments HVIDEO hVideo
Specifies a handle to a video device channel.

LPCHANNEL_CAPS lpChannelCaps
Specifies a pointer to a CHANNEL_CAPS data structure. This data structure is filled with information about the capabilities of the video device channel.

The CHANNEL_CAPS data structure must be allocated with the mmeAllocMem function before being passed to the videoGetChannelCaps function. See Chapter 2 for more information about the memory allocation functions.

DWORD dwSize
Specifies the size of the CHANNEL_CAPS data structure.

Description

The videoGetChannelCaps function retrieves a description of the capabilities of a channel. For example, capability information might include whether or not the channel can crop and scale images.

Note Use the videoOpen function before calling the videoGetChannelCaps function. You must open a channel before calling the videoGetChannelCaps function.

Return Values

Returns DV_ERR_OK if the function is successful; otherwise, it returns one of the following error codes:

#include <mme/mme_api.h> DWORD videoGetContrast(HVIDEO hVideo)

Arguments HVIDEO hVideo
Specifies a handle to a video device channel.

Description

The videoGetContrast function obtains the current contrast value. This contrast value is applied to the 8-bit X image data returned to the application. This request is not supported for video playback using a single buffer.

Return Values

Returns the current contrast value if the function is successful; otherwise, it returns one of the following error codes: