IWICBitmap::Lock method (wincodec.h)

Provides access to a rectangular area of the bitmap.

Syntax

HRESULT Lock(
  [in]  const WICRect  *prcLock,
  [in]  DWORD          flags,
  [out] IWICBitmapLock **ppILock
);

Parameters

[in] prcLock

Type: const WICRect*

The rectangle to be accessed.

[in] flags

Type: DWORD

The access mode you wish to obtain for the lock. This is a bitwise combination of WICBitmapLockFlags for read, write, or read and write access.

[out] ppILock

Type: IWICBitmapLock**

A pointer that receives the locked memory location.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

Locks are exclusive for writing but can be shared for reading. You cannot call CopyPixels while the IWICBitmap is locked for writing. Doing so will return an error, since locks are exclusive.

Examples

In the following example, an IWICBitmap is created and the image data is cleared using an IWICBitmapLock.

    IWICImagingFactory *pFactory = NULL;
    IWICBitmap *pBitmap = NULL;

    UINT uiWidth = 640;
    UINT uiHeight = 480;
    WICPixelFormatGUID formatGUID = GUID_WICPixelFormat32bppBGRA;

    WICRect rcLock = { 0, 0, uiWidth, uiHeight };
    IWICBitmapLock *pLock = NULL;

    HRESULT hr = CoCreateInstance(
        CLSID_WICImagingFactory,
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_IWICImagingFactory,
        (LPVOID*)&pFactory
        );

    if (SUCCEEDED(hr))
    {
        hr = pFactory->CreateBitmap(uiWidth, uiHeight, formatGUID, WICBitmapCacheOnDemand, &pBitmap);
    }

    if (SUCCEEDED(hr))
    {
        hr = pBitmap->Lock(&rcLock, WICBitmapLockWrite, &pLock);

        if (SUCCEEDED(hr))
        {
            UINT cbBufferSize = 0;
            UINT cbStride = 0;
            BYTE *pv = NULL;

            hr = pLock->GetStride(&cbStride);

            if (SUCCEEDED(hr))
            {
                hr = pLock->GetDataPointer(&cbBufferSize, &pv);
            }

            // Clear the image data
            ZeroMemory(pv, cbBufferSize);

            // Release the bitmap lock.
            pLock->Release();
        }
    }

    if (pBitmap)
    {
        pBitmap->Release();
    }

    if (pFactory)
    {
        pFactory->Release();
    }

    return hr;

Requirements