Export (0) Print
Expand All

IMF2DBuffer interface

Represents a buffer that contains a two-dimensional surface, such as a video frame.

Members

The IMF2DBuffer interface inherits from the IUnknown interface. IMF2DBuffer also has these types of members:

Methods

The IMF2DBuffer interface has these methods.

MethodDescription
ContiguousCopyFrom

Copies data to this buffer from a buffer that has a contiguous format.

ContiguousCopyTo

Copies this buffer into the caller's buffer, converting the data to contiguous format.

GetContiguousLength

Retrieves the number of bytes needed to store the contents of the buffer in contiguous format.

GetScanline0AndPitch

Retrieves a pointer to the buffer memory and the surface stride.

IsContiguousFormat

Queries whether the buffer is contiguous in its native format.

Lock2D

Gives the caller access to the memory in the buffer.

Unlock2D

Unlocks a buffer that was previously locked.

 

Remarks

To get a pointer to this interface, call QueryInterface on the media buffer.

To use a 2-D buffer, it is important to know the stride, which is the number of bytes needed to go from one row of pixels to the next. The stride may be larger than the image width, because the surface may contain padding bytes after each row of pixels. Stride can also be negative, if the pixels are oriented bottom-up in memory. For more information, see Image Stride.

Every video format defines a contiguous or packed representation. This representation is compatible with the standard layout of a DirectX surface in system memory, with no additional padding. For RGB video, the contiguous representation has a pitch equal to the image width in bytes, rounded up to the nearest DWORD boundary. For YUV video, the layout of the contiguous representation depends on the YUV format. For planar YUV formats, the Y plane might have a different pitch than the U and V planes.

If a media buffer supports the IMF2DBuffer interface, the underlying buffer is not guaranteed to have a contiguous representation, because there might be additional padding bytes after each row of pixels. When a buffer is non-contiguous, the Lock and Lock2D methods have different behaviors:

  • The Lock2D method returns a pointer to the underlying buffer. The buffer might not be contiguous.
  • The Lock method returns a buffer that is guaranteed to be contiguous. If the underlying buffer is not contiguous, the method copies the data into a new buffer, and the Unlock method copies it back into the original buffer.

Call the Lock2D method to access the 2-D buffer in its native format. The native format might not be contiguous. The buffer's IMFMediaBuffer::Lock method returns a contiguous representation of the buffer. However, this might require an internal copy from the native format. For 2-D buffers, therefore, you should use the Lock2D method and avoid the Lock method. Because the Lock method might cause up to two buffer copies, the Lock2D method is generally more efficient and should be used when possible. To find out if the underlying buffer is contiguous, call IMF2DBuffer::IsContiguousFormat.

For uncompressed images, the amount of valid data in the buffer is determined by the width, height, and pixel layout of the image. For this reason, if you call Lock2D to access the buffer, do not rely on the values returned by IMFMediaBuffer::GetCurrentLength or IMFMediaBuffer::GetMaxLength. Similarly, if you modify the data in the buffer, you do not have to call IMFMediaBuffer::SetCurrentLength to update the size. Generally, you should avoid mixing calls to IMF2DBuffer and IMFMediaBuffer methods on the same media buffer.

Requirements

Minimum supported client

Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 [desktop apps | Windows Store apps]

Header

Mfobjects.h (include Mfidl.h)

Library

Mfuuid.lib

See also

Media Foundation Interfaces
Media Buffers
Uncompressed Video Buffers

 

 

Community Additions

ADD
Show:
© 2014 Microsoft