IMF2DBuffer2::Lock2DSize method (mfobjects.h)

Article
07/27/2022

Gives the caller access to the memory in the buffer.

Syntax

HRESULT Lock2DSize(
  [in]  MF2DBuffer_LockFlags lockFlags,
  [out] BYTE                 **ppbScanline0,
  [out] LONG                 *plPitch,
  [out] BYTE                 **ppbBufferStart,
  [out] DWORD                *pcbBufferLength
);

Parameters

[in] lockFlags

A member of the MF2DBuffer_LockFlags enumeration that specifies whether to lock the buffer for reading, writing, or both.

[out] ppbScanline0

Receives a pointer to the first byte of the top row of pixels in the image. The top row is defined as the top row when the image is presented to the viewer, and might not be the first row in memory.

[out] plPitch

Receives the surface stride, in bytes. The stride might be negative, indicating that the image is oriented from the bottom up in memory.

[out] ppbBufferStart

Receives a pointer to the start of the accessible buffer in memory.

[out] pcbBufferLength

Receives the length of the buffer, in bytes.

Return value

This method can return one of these values.

Return code	Description
S_OK	Success.
MF_E_INVALIDREQUEST	Invalid request. The buffer might already be locked with an incompatible locking flag. See Remarks.
E_OUTOFMEMORY	There is insufficient memory to complete the operation.

Remarks

When you are done accessing the memory, call IMF2DBuffer::Unlock2D to unlock the buffer. You must call Unlock2D once for each call to Lock2DSize.

This method is equivalent to the IMF2DBuffer::Lock2D method. However, Lock2DSize is preferred because it enables the caller to validate memory pointers, and because it supports read-only locks. A buffer is not guaranteed to support the IMF2DBuffer2 interface. To access a buffer, you should try the following methods in the order listed:

IMF2DBuffer2::Lock2DSize
IMF2DBuffer::Lock2D
IMFMediaBuffer::Lock

The ppbBufferStart and pcbBufferLength parameters receive the bounds of the buffer memory. Use these values to guard against buffer overruns. Use the values of ppbScanline0 and plPitch to access the image data. If the image is bottom-up in memory, ppbScanline0 will point to the last scan line in memory and plPitch will be negative. For more information, see Image Stride.

The lockFlags parameter specifies whether the buffer is locked for read-only access, write-only access, or read/write access.

If the buffer is already locked for read-only access, it cannot be locked for write access.
If the buffer is already locked for write-only access, it cannot be locked for read access.
If the buffer is already locked for read/write access, it can be locked for read or write access.

When possible, use a read-only or write-only lock, and avoid locking the buffer for read/write access. If the buffer represents a DirectX Graphics Infrastructure (DXGI) surface, a read/write lock can cause an extra copy between CPU memory and GPU memory.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 [desktop apps \| UWP apps]
Target Platform	Windows
Header	mfobjects.h (include Mfidl.h)