BitmapDataFactoryCreateBitmapData(Size, KnownPixelFormat, WorkingColorSpace, Color32, Byte) Method

Creates an IReadWriteBitmapData instance with the specified size and pixelFormat.

Definition

Namespace: KGySoft.Drawing.Imaging
Assembly: KGySoft.Drawing.Core (in KGySoft.Drawing.Core.dll) Version: 8.1.0
C#
public static IReadWriteBitmapData CreateBitmapData(
	Size size,
	KnownPixelFormat pixelFormat,
	WorkingColorSpace workingColorSpace,
	Color32 backColor = default,
	byte alphaThreshold = 128
)

Parameters

size  Size
The size of the bitmap data to create in pixels.
pixelFormat  KnownPixelFormat
The desired pixel format of the bitmap data to create.
workingColorSpace  WorkingColorSpace
Specifies the preferred color space that should be used when working with the result bitmap data.
See the Remarks section of the WorkingColorSpace enumeration for more details.
backColor  Color32  (Optional)
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  Byte  (Optional)
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

IReadWriteBitmapData
An IReadWriteBitmapData instance with the specified size and pixelFormat.

Remarks

This method supports predefined pixel formats. To create a bitmap data with some custom pixel format use the overloads that have PixelFormatInfo parameters.

The backColor parameter has no practical 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 KnownPixelFormats 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.

The workingColorSpace parameter indicates the preferred color space when working with the result bitmap data. Blending operations performed by this library (eg. by IWritableBitmapData.SetPixel when blending is necessary as described above, or by the DrawInto extension methods) respect the value of this parameter. Blending in the linear color space produces natural results but the operation is a bit slower if the actual pixel format is not in the linear color space, and the result is different from the results of most applications including popular image processors and web browsers. See the Remarks section of the WorkingColorSpace enumeration for more details.

  Tip

Exceptions

ArgumentOutOfRangeExceptionsize has a zero or negative width or height
-or-
pixelFormat is not one of the valid formats
-or-
workingColorSpace is not one of the defined values.

See Also