CopyFromBuffer(self, data, format=BitmapBufferFormat_RGB, stride=-1)
Copy data from a buffer object to replace the bitmap pixel data.
Default format is plain RGB, but other formats are now supported as
well.

// Grabs the entire desktop. Make sure to set video_alpha to 0 before and to 100 after,
// to grab the desktop without the engine. Returns a BMAP* with the grabbed desktop.
//
BMAP* bmap_for_desktop ()
{
BMAP* bmap = NULL;

// get the device context of the entire desktop, including windows bar and everything
HDC hDesktopDC = GetWindowDC(HWND_DESKTOP);
if (hDesktopDC != 0)
{
// get desktop size in pixels
int desktopSizeX = GetSystemMetrics(SM_CXSCREEN);
int desktopSizeY = GetSystemMetrics(SM_CYSCREEN);

// creates a bitmap compatible with the desktop device context, in which we will later
// blit the desktop content into

HBITMAP hBitmap = CreateCompatibleBitmap(hDesktopDC, desktopSizeX, desktopSizeY);
if (hBitmap != NULL)
{
// create a memory device context compatible with the device context of the desktop. This
// context will be used to select the blit target
HDC hBitmapdc = CreateCompatibleDC(hDesktopDC);

// select the target bitmap into a the desktop-alike device context and copy the desktop
SelectObject(hBitmapdc, hBitmap);
BitBlt(hBitmapdc, 0, 0, desktopSizeX, desktopSizeY, hDesktopDC, 0, 0, SRCCOPY);

// create Gamestudio bitmap with size of the desktop
bmap = bmap_createblack(desktopSizeX, desktopSizeY, 888);
if (bmap != NULL)
{
// lock bitmap to blit from windows bitmap to Gamestudio bitmap
var format = bmap_lock(bmap, 0);
if (format > 0)
{
// we blit the bitmap pixelwise by fetching and converting the RGB components from the
// Windows bitmap and throwing it with pixel_to_bmap into the Gamestudio bitmap. This
// procedure might be faster by using GetDIBits and bmap->finalbits, but this seems to be
// safer for now

int iRow, iCol;
COLORREF colorRef;
COLOR color;
var pixel;

for (iRow = 0; iRow < bmap->height; iRow++)
{
for (iCol = 0; iCol < bmap->width; iCol++)
{
// retrieve the RGB color value as of the pixel at the specified coordinate as hexadecimal
// value 0x00bbggrr. We use the standard GDI macros to extract the component
colorRef = GetPixel(hBitmapdc, iCol, iRow);

if (colorRef != CLR_INVALID)
{
color.red = GetRValue(colorRef);
color.green = GetGValue(colorRef);
color.blue = GetBValue(colorRef);
}
// else: the pixel is outside of the current clipping region

// convert and set the retrieved color to a pixel in the format of the Gamestudio bitmap
pixel = pixel_for_vec(&color, 100, format);
pixel_to_bmap(bmap, iCol, iRow, pixel);
}
}

// blitting done, unlock Gamestudio bitmap
bmap_unlock(bmap);
}
}

// lets delete the desktop-alike device context
DeleteDC(hBitmapdc);
}

// an application must not -delete- a DC whose handle was obtained by calling the GetDC
// function. Instead, it must call the ReleaseDC function to free the DC. If such a DC is
// not freed, serious effects on painting requested by other applications can happen!
ReleaseDC(HWND_DESKTOP, hDesktopDC);
}

return(bmap);
}