IMF2DBuffer2::Lock2DSize method

Gives the caller access to the memory in the buffer.

Syntax


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

Parameters

lockFlags [in]

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

ppbScanline0 [out]

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.

plPitch [out]

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

ppbBufferStart [out]

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

pcbBufferLength [out]

Receives the length of the buffer, in bytes.

Return value

This method can return one of these values.

Return codeDescription
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 acess, it can be locked for read or write acess.

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

Minimum supported client

Windows 8 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2012 [desktop apps | Windows Store apps]

Header

Mfobjects.idl (include Mfidl.h)

See also

IMF2DBuffer2

 

 

Show: