IMF2DBuffer interface (mfobjects.h)

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

Inheritance

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

Methods

The IMF2DBuffer interface has these methods.

IMF2DBuffer::ContiguousCopyFrom Copies data to this buffer from a buffer that has a contiguous format.
IMF2DBuffer::ContiguousCopyTo Copies this buffer into the caller's buffer, converting the data to contiguous format.
IMF2DBuffer::GetContiguousLength Retrieves the number of bytes needed to store the contents of the buffer in contiguous format.
IMF2DBuffer::GetScanline0AndPitch Retrieves a pointer to the buffer memory and the surface stride.
IMF2DBuffer::IsContiguousFormat Queries whether the buffer is contiguous in its native format.
IMF2DBuffer::Lock2D Gives the caller access to the memory in the buffer. (IMF2DBuffer.Lock2D)
IMF2DBuffer::Unlock2D Unlocks a buffer that was previously locked. Call this method once for each call to IMF2DBuffer::Lock2D.

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

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

See also

Media Buffers

Media Foundation Interfaces

Uncompressed Video Buffers