BitmapDataFactoryCreateBitmapData Method (Size, PixelFormat, Color32, Byte)

KGy SOFT Drawing Libraries Help
Creates a managed IReadWriteBitmapData with the specified size and pixelFormat.
See the Remarks section for details.

Namespace:  KGySoft.Drawing.Imaging
Assembly:  KGySoft.Drawing (in KGySoft.Drawing.dll) Version: 6.2.0
Syntax

public static IReadWriteBitmapData CreateBitmapData(
	Size size,
	PixelFormat pixelFormat = PixelFormat.Format32bppArgb,
	Color32 backColor = default,
	byte alphaThreshold = 128
)

Parameters

size
Type: System.DrawingSize
The size of the bitmap data to create.
pixelFormat (Optional)
Type: System.Drawing.ImagingPixelFormat
The desired pixel format of the bitmap data to create.
backColor (Optional)
Type: KGySoft.Drawing.ImagingColor32
For pixel formats without alpha gradient support specifies the BackColor value of the returned IReadWriteBitmapData instance. It does not affect the actual returned bitmap content. See the Remarks section for details. The alpha value (Color32.A field) of the specified background color is ignored. This parameter is optional.
Default value: The default value of the Color32 type, which has the same RGB values as Black.
alphaThreshold (Optional)
Type: SystemByte
For pixel formats without alpha gradient support specifies the AlphaThreshold value of the returned IReadWriteBitmapData instance. See the Remarks section for details. This parameter is optional.
Default value: 128.

Return Value

Type: IReadWriteBitmapData
A managed IReadWriteBitmapData with the specified size and pixelFormat.
Exceptions

ExceptionCondition
ArgumentOutOfRangeExceptionsize or pixelFormat has an invalid value.
Remarks

All possible PixelFormats are supported, regardless of the native Bitmap support of the current operating system.

Note Note
When pixelFormat specifies a wide-color format (48/64 bit or 16 bit grayscale), then the returned instance will use the full 16-bit range of the color channels. This means a different raw content to Windows' wide-color Bitmap instances, which use 13-bit channels. But this difference is transparent in most cases unless we access actual raw content by the ReadRaw and WriteRaw methods.

The backColor parameter has no effect if pixelFormat has alpha gradient support and it does not affect the actual content of the returned instance. To set all pixels to a color use the Clear extension method.

If alphaThreshold is zero, then setting a fully transparent pixel in a bitmap data with indexed or single-bit-alpha pixel format will blend the pixel to set with backColor even if the bitmap data can handle transparent pixels.

If alphaThreshold is 1, then the result color of setting a pixel of a bitmap data with indexed or single-bit-alpha pixel format will be transparent only if the color to set is completely transparent (has zero alpha).

If alphaThreshold is 255, then the result color of setting a pixel of a bitmap data with indexed or single-bit-alpha pixel format will be opaque only if the color to set is completely opaque (its alpha value is 255).

For PixelFormats without any alpha support the specified alphaThreshold is used only to determine the source pixels to skip when another bitmap data is drawn into the returned instance.

If a pixel of a bitmap data without alpha gradient support is set by the IWritableBitmapData.SetPixel/IWritableBitmapDataRow.SetColor methods or by the IReadWriteBitmapDataRow indexer, and the pixel has an alpha value that is greater than alphaThreshold, then the pixel to set will be blended with backColor.

Tip Tip
See Also

Reference