MCI_GETIMAGEBUFFER
This message is used by digital video or video overlay devices to retrieve the contents of the capture video buffer or the current movie frame into an application-provided buffer.
Syntax
param1 ULONG ulParam1; /* Flags for retrieval operation. */ param2 PMCI_IMAGE_PARMS pParam2; /* Pointer to the MCI_IMAGE_PARMS data structure. */
Parameters
- ulParam1 (ULONG) - input
- This parameter can contain any of the following flags:
- MCI_NOTIFY A notification message will be posted to the window specified in the hwndCallback parameter of the data structure.
- MCI_WAIT Control is not to be returned until the action is completed.
- MCI_CONVERT Specifies that the image format will be converted to the OS/2 memory bitmap format. The default is device-specific.
- Digital Video & Overlay Extensions
- MCI_USE_HW_BUFFER Capture will be from the hardware capture video buffer rather than the movie element.
- MCI_GET_HW_BUFFER_PTR Requests a direct pointer to the hardware buffer (Video Overlay only; not supported by M-Motion).
- pParam2 (PMCI_IMAGE_PARMS) - input
- A pointer to the MCI_IMAGE_PARMS structure. **Note:** If the pPelBuffer field is set to 0, the command acts as a **query**, and the driver fills in the structure with the required buffer length and characteristics.
Returns
- rc (ULONG) - returns
- Return codes indicating success or failure:
- MCIERR_SUCCESS Command completed successfully.
- MCIERR_INVALID_DEVICE_ID Invalid device ID.
- MCIERR_INVALID_BUFFER Buffer is invalid or too small.
- MCIERR_TARGET_DEVICE_FULL No disk space (often occurs during format conversion).
- MCIERR_INSTANCE_INACTIVE The device instance is currently inactive.
Remarks
The image data returned is uncompressed. If `MCI_CONVERT` is used, the buffer contains a `BITMAPFILEHEADER2` (or `BITMAPINFOHEADER2`), followed by the palette and the pel (pixel) data.
Conversion from internal formats (like YUVB) to OS/2 bitmap format may require temporary disk space; if the disk is full, the command will fail with `MCIERR_TARGET_DEVICE_FULL`.
Example Code
The following example shows how to capture a bitmap from video by first querying for the buffer size:
USHORT usUserParm = 0;
BITMAPINFOHEADER2 *pBMPhdr;
ULONG ulReturn;
ULONG ulFlags = MCI_CONVERT;
/**********************************************************/
/* 1. Determine the length and characteristics of buffer */
/**********************************************************/
memset ((PVOID)&mciImageParms, 0x00, sizeof (MCI_IMAGE_PARMS));
mciImageParms.hwndCallback = hwndNotify;
mciImageParms.ulBufLen = 0;
mciImageParms.pPelBuffer = 0;
ulReturn = mciSendCommand(usDeviceID, MCI_GETIMAGEBUFFER,
MCI_WAIT | ulFlags,
(PVOID)&mciImageParms,
usUserParm);
/*************************************/
/* 2. Allocate memory for the buffer */
/*************************************/
DosAllocMem (&mciImageParms.pPelBuffer,
mciImageParms.ulBufLen,
PAG_COMMIT | PAG_WRITE);
/*********************************/
/* 3. Get the data from the buffer */
/*********************************/
ulReturn = mciSendCommand(usDeviceID, MCI_GETIMAGEBUFFER,
MCI_WAIT | ulFlags,
(PVOID)&mciImageParms,
usUserParm);
pBMPhdr = (BITMAPINFOHEADER2 *)mciImageParms.pPelBuffer;
The following code illustrates how to capture an OS/2 bitmap from the hardware using a digital video device:
#define INCL_GPI
#define INCL_GPIBITMAPS
#include <os2.h>
#include <pmbitmap.h>
#define INCL_MMIO
#define INCL_MMIO_CODEC
#define INCL_MMIO_DOSIOPROC
#include <os2me.h>
#include <stdlib.h>
VOID BMPCaptureBitmap(PSWVRCB pCB, HWND hwnd)
{
MCI_IMAGE_PARMS mciImageParms;
PCHAR pBuf=0L;
HFILE hBMP;
ULONG ulAction;
ULONG cBytes;
LONG rc;
memset ((PVOID)&mciImageParms, 0x00, sizeof (MCI_IMAGE_PARMS));
mciImageParms.pPelBuffer = 0L;
mciImageParms.ulBufLen = 0L;
mciImageParms.rect.xLeft = pCB->recopts[usIndex].usCapPosX;
mciImageParms.rect.yBottom = pCB->recopts[usIndex].usCapPosY;
mciImageParms.rect.xRight = pCB->recopts[usIndex].usCapSizeX + pCB->recopts[usIndex].usCapPosX;
mciImageParms.rect.yTop = pCB->recopts[usIndex].usCapSizeY + pCB->recopts[usIndex].usCapPosY;
mciImageParms.ulPelBufferWidth = pCB->recopts[usIndex].usMovieSizeX;
mciImageParms.ulPelBufferHeight = pCB->recopts[usIndex].usMovieSizeY;
/* Query for buffer size */
rc = mciSendCommand( pCB->OutputMovie.usDeviceID,
MCI_GETIMAGEBUFFER,
MCI_WAIT | MCI_USE_HW_BUFFER | MCI_CONVERT,
(ULONG)&mciImageParms,
0);
/* Allocate the buffer */
rc = DosAllocMem ( (PPVOID) &pBuf,
(ULONG) mciImageParms.ulBufLen,
(ULONG) PAG_COMMIT | PAG_READ | PAG_WRITE);
mciImageParms.pPelBuffer=(PVOID)pBuf;
/* Retrieve image data */
rc = mciSendCommand( pCB->OutputMovie.usDeviceID,
MCI_GETIMAGEBUFFER,
MCI_WAIT | MCI_USE_HW_BUFFER | MCI_CONVERT,
(ULONG)&mciImageParms,
0);
if (!rc)
{
rc = DosOpen ( (PSZ)pCB->szBitmapFilename, &hBMP, &ulAction, 0, FILE_NORMAL,
FILE_CREATE,
OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYWRITE,
0L);
rc = DosWrite (hBMP, (PVOID)pBuf, mciImageParms.ulBufLen, &cBytes);
rc = DosClose (hBMP);
}
DosFreeMem( pBuf );
}