Edit

Bitmap::LockBits method (gdiplusheaders.h)

  • Article

The Bitmap::LockBits method locks a rectangular portion of this bitmap and provides a temporary buffer that you can use to read or write pixel data in a specified format. Any pixel data that you write to the buffer is copied to the Bitmap object when you call Bitmap::UnlockBits.

Syntax

Status LockBits(
  [in]      const Rect  *rect,
  [in]      UINT        flags,
  [in]      PixelFormat format,
  [in, out] BitmapData  *lockedBitmapData
);

Parameters

[in] rect

Type: const Rect*

Pointer to a rectangle that specifies the portion of the bitmap to be locked.

[in] flags

Type: UINT

Set of flags that specify whether the locked portion of the bitmap is available for reading or for writing and whether the caller has already allocated a buffer. Individual flags are defined in the ImageLockMode enumeration.

[in] format

Type: PixelFormat

Integer that specifies the format of the pixel data in the temporary buffer. The pixel format of the temporary buffer does not have to be the same as the pixel format of this Bitmap object. The PixelFormat data type and constants that represent various pixel formats are defined in Gdipluspixelformats.h. For more information about pixel format constants, see Image Pixel Format Constants. GDI+ version 1.0 does not support processing of 16-bits-per-channel images, so you should not set this parameter equal to PixelFormat48bppRGB, PixelFormat64bppARGB, or PixelFormat64bppPARGB.

[in, out] lockedBitmapData

Type: BitmapData*

Pointer to a BitmapData object. If the ImageLockModeUserInputBuf flag of the flags parameter is cleared, then lockedBitmapData serves only as an output parameter. In that case, the Scan0 data member of the BitmapData object receives a pointer to a temporary buffer, which is filled with the values of the requested pixels. The other data members of the BitmapData object receive attributes (width, height, format, and stride) of the pixel data in the temporary buffer. If the pixel data is stored bottom-up, the Stride data member is negative. If the pixel data is stored top-down, the Stride data member is positive. If the ImageLockModeUserInputBuf flag of the flags parameter is set, then lockedBitmapData serves as an input parameter (and possibly as an output parameter). In that case, the caller must allocate a buffer for the pixel data that will be read or written. The caller also must create a BitmapData object, set the Scan0 data member of that BitmapData object to the address of the buffer, and set the other data members of the BitmapData object to specify the attributes (width, height, format, and stride) of the buffer.

Return value

Type: Status

If the method succeeds, it returns Ok, which is an element of the Status enumeration.

If the method fails, it returns one of the other elements of the Status enumeration.

Requirements

Requirement Value
Minimum supported client Windows XP, Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header gdiplusheaders.h (include Gdiplus.h)
Library Gdiplus.lib
DLL Gdiplus.dll

See also

Bitmap

Bitmap::UnlockBits

BitmapData

Image

Image Pixel Format Constants

ImageLockMode

Images, Bitmaps, and Metafiles

Using Images, Bitmaps, and Metafiles