Edit

Share via

IMF2DBuffer2::Lock2DSize method (mfobjects.h)

  • Article

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:

  1. IMF2DBuffer2::Lock2DSize
  2. IMF2DBuffer::Lock2D
  3. 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)

See also

IMF2DBuffer2