IMF2DBuffer::Lock2D method (mfobjects.h)

Gives the caller access to the memory in the buffer.

Syntax

HRESULT Lock2D(
  [out] BYTE **ppbScanline0,
  [out] LONG *plPitch
);

Parameters

[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.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Remarks

If p is a pointer to the first byte in a row of pixels, p + (*plPitch) points to the first byte in the next row of pixels. A buffer might contain padding after each row of pixels, so the stride might be wider than the width of the image in bytes. Do not access the memory that is reserved for padding bytes, because it might not be read-accessible or write-accessible. For more information, see Image Stride.

The pointer returned in pbScanline0 remains valid as long as the caller holds the lock. When you are done accessing the memory, call IMF2DBuffer::Unlock2D to unlock the buffer. You must call Unlock2D once for each call to Lock2D. After you unlock the buffer, the pointer returned in pbScanline0 is no longer valid and should not be used. Generally, it is best to call Lock2D only when you need to access the buffer memory, and not earlier.

The values returned by the IMFMediaBuffer::GetCurrentLength and IMFMediaBuffer::GetMaxLength methods do not apply to the buffer that is returned by the Lock2D method. For the same reason, you do not need to call IMFMediaBuffer::SetCurrentLength after manipulating the data in the buffer returned by the Lock2D method.

The IMFMediaBuffer::Lock method fails while the Lock2D lock is held, and vice-versa. Applications should use only one of these methods at a time.

When the underlying buffer is a Direct3D surface, the method fails if the surface is not lockable.

Requirements

See also

IMF2DBuffer

Media Buffers

Uncompressed Video Buffers