IMediaDet::GetBitmapBits method

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The GetBitmapBits method retrieves a video frame at the specified media time. The returned frame is always in 24-bit RGB format.

Syntax

HRESULT GetBitmapBits(
   double StreamTime,
   long   *pBufferSize,
   char   *pBuffer,
   long   Width,
   long   Height
);

Parameters

StreamTime

Time at which to retrieve the video frame, in seconds.

pBufferSize

Receives the required buffer size. If pBuffer is NULL, the variable receives the size of the buffer needed to retrieve the frame. If pBuffer is not NULL, this parameter is ignored.

pBuffer

Pointer to a buffer that receives a BITMAPINFOHEADER structure followed by the DIB bits.

Width

Width of the video image, in pixels.

Height

Height of the video image, in pixels.

Return value

Returns an HRESULT value. Possible values include the following:

Remarks

Before calling this method, set the file name and stream by calling IMediaDet::put_Filename and IMediaDet::put_CurrentStream.

To determine the size of the buffer that is required, call this method with pBuffer equal to NULL. The size is returned in the variable pointed to by pBufferSize. Then create the buffer and call the method again, with pBuffer equal to the address of the buffer. When the method returns, the buffer contains a BITMAPINFOHEADER structure followed by the bitmap. The bitmap is scaled to the dimensions specified in the Width and Height parameters.

This method puts the media detector into bitmap grab mode. Once this method has been called, the various stream information methods in IMediaDet do not work, unless you create a new instance of the media detector.

Examples

The following code uses the GetBitmapBits method to create a device-independent bitmap.

long size;
hr = pDet->GetBitmapBits(0, &size, 0, width, height);
if (SUCCEEDED(hr)) 
{
    char *pBuffer = new char[size];
    if (!pBuffer)
        return E_OUTOFMEMORY;
    try {
        hr = pDet->GetBitmapBits(0, 0, pBuffer, width, height);
    }
    catch (...) {
        delete [] pBuffer;
        throw;
    }
    if (SUCCEEDED(hr))
    {
        BITMAPINFOHEADER *bmih = (BITMAPINFOHEADER*)pBuffer;
        HDC hdcDest = GetDC(0);
        
        // Find the address of the start of the image data.
        void *pData = pBuffer + sizeof(BITMAPINFOHEADER);
        
        // Note: In general a BITMAPINFOHEADER can include extra color
        // information at the end, so calculating the offset to the image
        // data is not generally correct. However, the IMediaDet interface
        // always returns an RGB-24 image with no extra color information.
        
        BITMAPINFO bmi;
        ZeroMemory(&bmi, sizeof(BITMAPINFO));
        CopyMemory(&(bmi.bmiHeader), bmih, sizeof(BITMAPINFOHEADER));
        HBITMAP hBitmap = CreateDIBitmap(hdcDest, bmih, CBM_INIT, 
            pData, &bmi, DIB_RGB_COLORS);
    }
    delete[] pBuffer;
}

Requirements

See also

IMediaDet Interface

Error and Success Codes