TIEBitmap.EncapsulateFragmentedMemory

Declaration

procedure EncapsulateFragmentedMemory(fragments: PPointerArray; fragmentsCount: Integer; rowsPerFragment: Integer; bmpWidth, bmpHeight: Integer; bmpPixelFormat: TIEPixelFormat; DoFreeImage: Boolean; Origin: TIEBitmapOrigin = ieboBottomLeft);

Description

Encapsulates an existing bitmap whose rows are stored in several memory blocks (fragments).
fragments is an array of fragmentsCount pointers. Each fragment holds rowsPerFragment rows of RowLen bytes. Together they must hold at least bmpHeight rows.
The rows are ordered as if the fragments were one contiguous buffer, exactly as for EncapsulateMemory: with Origin = ieboBottomLeft (Windows default) the first row of the first fragment is the bottom row of the image; with ieboTopLeft it is the top row.
The memory is not owned by TIEBitmap (it is not freed on destroy).
If DoFreeImage is True, any previous image content held by this TIEBitmap is freed before encapsulating the fragments.

Example

// Two fragments of 50 rows each, top row first
frags[0] := buf1;
frags[1] := buf2;
bmp.EncapsulateFragmentedMemory( @frags, 2, 50, width, 100, ie24RGB, False, ieboTopLeft );

See Also

◼EncapsulateMemory

Compatibility Information

In v15.2.4 the fragments parameter was moved to the start, so existing code fails to compile and can be reviewed. Previously the parameter order was (fragmentsCount, rowsPerFragment, fragments, ...).
The row order also changed to match EncapsulateMemory. The fragments are now read as if they were copied, in order, into one contiguous block, and the result is identical to calling EncapsulateMemory with that block and the same Origin:
◼ieboBottomLeft (default): the first row of fragment 0 is the bottom row of the image
◼ieboTopLeft: the first row of fragment 0 is the top row of the image
Prior to v15.2.4 the row order was the reverse: with ieboBottomLeft the first row of fragment 0 was the top row. To keep the old row order, swap the origin (old ieboBottomLeft = new ieboTopLeft).
// Old code (prior to v15.2.4): fragments filled top row first, default origin
bmp.EncapsulateFragmentedMemory( 2, 50, @frags, width, 100, ie24RGB, False );

// New code giving the same image
bmp.EncapsulateFragmentedMemory( @frags, 2, 50, width, 100, ie24RGB, False, ieboTopLeft );

// The fragments give the same result as one contiguous block, e.g.
GetMem( buf, 100 * bmp.RowLen );
Move( frags[0]^, buf^, 50 * bmp.RowLen );
Move( frags[1]^, ( PByte( buf ) + 50 * bmp.RowLen )^, 50 * bmp.RowLen );
bmp2.EncapsulateMemory( buf, width, 100, ie24RGB, False, ieboTopLeft );  // bmp2 has the same pixels as bmp

---