C# Class AForge.Imaging.UnmanagedImage

Image in unmanaged memory.

The class represents wrapper of an image in unmanaged memory. Using this class it is possible as to allocate new image in unmanaged memory, as to just wrap provided pointer to unmanaged memory, where an image is stored.

Usage of unmanaged images is mostly beneficial when it is required to apply multiple image processing routines to a single image. In such scenario usage of .NET managed images usually leads to worse performance, because each routine needs to lock managed image before image processing is done and then unlock it after image processing is done. Without these lock/unlock there is no way to get direct access to managed image's data, which means there is no way to do fast image processing. So, usage of managed images lead to overhead, which is caused by locks/unlock. Unmanaged images are represented internally using unmanaged memory buffer. This means that it is not required to do any locks/unlocks in order to get access to image data (no overhead).

Sample usage:

 // sample 1 - wrapping .NET image into unmanaged without // making extra copy of image in memory BitmapData imageData = image.LockBits( new Rectangle( 0, 0, image.Width, image.Height ), ImageLockMode.ReadWrite, image.PixelFormat ); try { UnmanagedImage unmanagedImage = new UnmanagedImage( imageData ) ); // apply several routines to the unmanaged image } finally { image.UnlockBits( imageData ); } // sample 2 - converting .NET image into unmanaged UnmanagedImage unmanagedImage = UnmanagedImage.FromManagedImage( image ); // apply several routines to the unmanaged image ... // conver to managed image if it is required to display it at some point of time Bitmap managedImage = unmanagedImage.ToManagedImage( );

Inheritance: IDisposable

Datei anzeigen Open project: holisticware-admin/MonoVersal.AForgeNET Class Usage Examples

Public Methods

Method	Description
Clone ( ) : UnmanagedImage	Clone the unmanaged images. The method does complete cloning of the object.
Collect16bppPixelValues ( List points ) : ushort[]	Collect pixel values from the specified list of coordinates. The method goes through the specified list of points and for each point retrievs corresponding pixel's value from the unmanaged image. For grayscale image the output array has the same length as number of points in the specified list of points. For color image the output array has triple length, containing pixels' values in RGB order. The method does not make any checks for valid coordinates and leaves this up to user. If specified coordinates are out of image's bounds, the result is not predictable (crash in most cases). This method is supposed for images with 16 bpp channels only (16 bpp grayscale image and 48/64 bpp color images).
Collect8bppPixelValues ( List points ) : byte[]	Collect pixel values from the specified list of coordinates. The method goes through the specified list of points and for each point retrievs corresponding pixel's value from the unmanaged image. For grayscale image the output array has the same length as number of points in the specified list of points. For color image the output array has triple length, containing pixels' values in RGB order. The method does not make any checks for valid coordinates and leaves this up to user. If specified coordinates are out of image's bounds, the result is not predictable (crash in most cases). This method is supposed for images with 8 bpp channels only (8 bpp grayscale image and 24/32 bpp color images).
CollectActivePixels ( ) : List	Collect coordinates of none black pixels in the image.
CollectActivePixels ( Rectangle rect ) : List	Collect coordinates of none black pixels within specified rectangle of the image.
Copy ( UnmanagedImage destImage ) : void	Copy unmanaged image. The method copies current unmanaged image to the specified image. Size and pixel format of the destination image must be exactly the same.
Create ( int width, int height, PixelFormat pixelFormat ) : UnmanagedImage	Allocate new image in unmanaged memory. Allocate new image with specified attributes in unmanaged memory. The method supports only Format8bppIndexed, Format16bppGrayScale, Format24bppRgb, Format32bppRgb, Format32bppArgb, Format32bppPArgb, Format48bppRgb, Format64bppArgb and Format64bppPArgb pixel formats. In the case if Format8bppIndexed format is specified, pallete is not not created for the image (supposed that it is 8 bpp grayscale image).
Dispose ( ) : void	Dispose the object. Frees unmanaged resources used by the object. The object becomes unusable after that. The method needs to be called only in the case if unmanaged image was allocated using Create method. In the case if the class instance was created using constructor, this method does not free unmanaged memory.
FromManagedImage ( Bitmap image ) : UnmanagedImage	Create unmanaged image from the specified managed image. The method creates an exact copy of specified managed image, but allocated in unmanaged memory.
FromManagedImage ( BitmapData imageData ) : UnmanagedImage	Create unmanaged image from the specified managed image. The method creates an exact copy of specified managed image, but allocated in unmanaged memory. This means that managed image may be unlocked right after call to this method.
GetPixel ( IntPoint point ) : Color	Get color of the pixel with the specified coordinates. See GetPixel(int, int) for more information.
GetPixel ( int x, int y ) : Color	Get color of the pixel with the specified coordinates. In the case if the image has 8 bpp grayscale format, the method will return a color with all R/G/B components set to same value, which is grayscale intensity. The method supports only 8 bpp grayscale images and 24/32 bpp color images so far.
SetPixel ( IntPoint point, Color color ) : void	Set pixel with the specified coordinates to the specified color. See SetPixel(int, int, Color) for more information.
SetPixel ( int x, int y, Color color ) : void	Set pixel with the specified coordinates to the specified color. For images having 16 bpp per color plane, the method extends the specified color value to 16 bit by multiplying it by 256. For grayscale images this method will calculate intensity value based on the below formula: `0.2125 * Red + 0.7154 * Green + 0.0721 * Blue`
SetPixel ( int x, int y, byte value ) : void	Set pixel with the specified coordinates to the specified value. The method sets all color components of the pixel to the specified value. If it is a grayscale image, then pixel's intensity is set to the specified value. If it is a color image, then pixel's R/G/B components are set to the same specified value (if an image has alpha channel, then it is set to maximum value - 255 or 65535). For images having 16 bpp per color plane, the method extends the specified color value to 16 bit by multiplying it by 256.
SetPixels ( List coordinates, Color color ) : void	Set pixels with the specified coordinates to the specified color. For images having 16 bpp per color plane, the method extends the specified color value to 16 bit by multiplying it by 256.
ToManagedImage ( ) : Bitmap	Create managed image from the unmanaged. The method creates a managed copy of the unmanaged image with the same size and pixel format (it calls ToManagedImage(bool) specifying for the makeCopy parameter).
ToManagedImage ( bool makeCopy ) : Bitmap	Create managed image from the unmanaged. If the makeCopy is set to , then the method creates a managed copy of the unmanaged image, so the managed image stays valid even when the unmanaged image gets disposed. However, setting this parameter to creates a managed image which is just a wrapper around the unmanaged image. So if unmanaged image is disposed, the managed image becomes no longer valid and accessing it will generate an exception.
UnmanagedImage ( BitmapData bitmapData ) : System	Initializes a new instance of the UnmanagedImage class. Unlike FromManagedImage(BitmapData) method, this constructor does not make copy of managed image. This means that managed image must stay locked for the time of using the instance of unamanged image.
UnmanagedImage ( IntPtr imageData, int width, int height, int stride, PixelFormat pixelFormat ) : System	Initializes a new instance of the UnmanagedImage class. Using this constructor, make sure all specified image attributes are correct and correspond to unmanaged memory buffer. If some attributes are specified incorrectly, this may lead to exceptions working with the unmanaged memory.

Protected Methods

Method	Description
Dispose ( bool disposing ) : void	Dispose the object.

Private Methods

Method	Description
SetPixel ( int x, int y, byte r, byte g, byte b, byte a ) : void

Method Details

Clone() public method

Clone the unmanaged images.

The method does complete cloning of the object.

public Clone ( ) : UnmanagedImage
return	UnmanagedImage

Collect16bppPixelValues() public method

Collect pixel values from the specified list of coordinates.

The method goes through the specified list of points and for each point retrievs corresponding pixel's value from the unmanaged image.

For grayscale image the output array has the same length as number of points in the specified list of points. For color image the output array has triple length, containing pixels' values in RGB order.

The method does not make any checks for valid coordinates and leaves this up to user. If specified coordinates are out of image's bounds, the result is not predictable (crash in most cases).

This method is supposed for images with 16 bpp channels only (16 bpp grayscale image and 48/64 bpp color images).

Unsupported pixel format of the source image. Use Collect8bppPixelValues() method for /// images with 8 bpp channels.

public Collect16bppPixelValues ( List points ) : ushort[]
points	List	List of coordinates to collect pixels' value from.
return	ushort[]

Collect8bppPixelValues() public method

Collect pixel values from the specified list of coordinates.

The method goes through the specified list of points and for each point retrievs corresponding pixel's value from the unmanaged image.

The method does not make any checks for valid coordinates and leaves this up to user. If specified coordinates are out of image's bounds, the result is not predictable (crash in most cases).

This method is supposed for images with 8 bpp channels only (8 bpp grayscale image and 24/32 bpp color images).

Unsupported pixel format of the source image. Use Collect16bppPixelValues() method for /// images with 16 bpp channels.

public Collect8bppPixelValues ( List points ) : byte[]
points	List	List of coordinates to collect pixels' value from.
return	byte[]

CollectActivePixels() public method

Collect coordinates of none black pixels in the image.

public CollectActivePixels ( ) : List
return	List

CollectActivePixels() public method

Collect coordinates of none black pixels within specified rectangle of the image.

public CollectActivePixels ( Rectangle rect ) : List
rect	System.Drawing.Rectangle	Image's rectangle to process.
return	List

Copy() public method

Copy unmanaged image.

The method copies current unmanaged image to the specified image. Size and pixel format of the destination image must be exactly the same.

Destination image has different size or pixel format.

public Copy ( UnmanagedImage destImage ) : void
destImage	UnmanagedImage	Destination image to copy this image to.
return	void

Create() public static method

Allocate new image in unmanaged memory.

Allocate new image with specified attributes in unmanaged memory.

The method supports only Format8bppIndexed, Format16bppGrayScale, Format24bppRgb, Format32bppRgb, Format32bppArgb, Format32bppPArgb, Format48bppRgb, Format64bppArgb and Format64bppPArgb pixel formats. In the case if Format8bppIndexed format is specified, pallete is not not created for the image (supposed that it is 8 bpp grayscale image).

Unsupported pixel format was specified. Invalid image size was specified.

public static Create ( int width, int height, PixelFormat pixelFormat ) : UnmanagedImage
width	int	Image width.
height	int	Image height.
pixelFormat	PixelFormat	Image pixel format.
return	UnmanagedImage

Dispose() public method

Dispose the object.

Frees unmanaged resources used by the object. The object becomes unusable after that.

The method needs to be called only in the case if unmanaged image was allocated using Create method. In the case if the class instance was created using constructor, this method does not free unmanaged memory.

public Dispose ( ) : void
return	void

Dispose() protected method

Dispose the object.

protected Dispose ( bool disposing ) : void
disposing	bool	Indicates if disposing was initiated manually.
return	void

FromManagedImage() public static method

Create unmanaged image from the specified managed image.

The method creates an exact copy of specified managed image, but allocated in unmanaged memory.

Unsupported pixel format of source image.

public static FromManagedImage ( Bitmap image ) : UnmanagedImage
image	System.Drawing.Bitmap	Source managed image.
return	UnmanagedImage

FromManagedImage() public static method

Create unmanaged image from the specified managed image.

The method creates an exact copy of specified managed image, but allocated in unmanaged memory. This means that managed image may be unlocked right after call to this method.

Unsupported pixel format of source image.

public static FromManagedImage ( BitmapData imageData ) : UnmanagedImage
imageData	System.Drawing.Imaging.BitmapData	Source locked image data.
return	UnmanagedImage

GetPixel() public method

Get color of the pixel with the specified coordinates.

See GetPixel(int, int) for more information.

public GetPixel ( IntPoint point ) : Color
point	IntPoint	Point's coordiates to get color of.
return	Color

GetPixel() public method

Get color of the pixel with the specified coordinates.

In the case if the image has 8 bpp grayscale format, the method will return a color with all R/G/B components set to same value, which is grayscale intensity.

The method supports only 8 bpp grayscale images and 24/32 bpp color images so far.

The specified pixel coordinate is out of image's bounds. Pixel format of this image is not supported by the method.

public GetPixel ( int x, int y ) : Color
x	int	X coordinate of the pixel to get.
y	int	Y coordinate of the pixel to get.
return	Color

SetPixel() public method

Set pixel with the specified coordinates to the specified color.

See SetPixel(int, int, Color) for more information.

public SetPixel ( IntPoint point, Color color ) : void
point	IntPoint	Point's coordiates to set color for.
color	Color	Color to set for the pixel.
return	void

SetPixel() public method

Set pixel with the specified coordinates to the specified color.

For images having 16 bpp per color plane, the method extends the specified color value to 16 bit by multiplying it by 256.

For grayscale images this method will calculate intensity value based on the below formula: 0.2125 * Red + 0.7154 * Green + 0.0721 * Blue

public SetPixel ( int x, int y, Color color ) : void
x	int	X coordinate of the pixel to set.
y	int	Y coordinate of the pixel to set.
color	Color	Color to set for the pixel.
return	void

SetPixel() public method

Set pixel with the specified coordinates to the specified value.

The method sets all color components of the pixel to the specified value. If it is a grayscale image, then pixel's intensity is set to the specified value. If it is a color image, then pixel's R/G/B components are set to the same specified value (if an image has alpha channel, then it is set to maximum value - 255 or 65535).

For images having 16 bpp per color plane, the method extends the specified color value to 16 bit by multiplying it by 256.

public SetPixel ( int x, int y, byte value ) : void
x	int	X coordinate of the pixel to set.
y	int	Y coordinate of the pixel to set.
value	byte	Pixel value to set.
return	void

SetPixels() public method

Set pixels with the specified coordinates to the specified color.

For images having 16 bpp per color plane, the method extends the specified color value to 16 bit by multiplying it by 256.

public SetPixels ( List coordinates, Color color ) : void
coordinates	List	List of points to set color for.
color	Color	Color to set for the specified points.
return	void

ToManagedImage() public method

Create managed image from the unmanaged.

The method creates a managed copy of the unmanaged image with the same size and pixel format (it calls ToManagedImage(bool) specifying for the makeCopy parameter).

public ToManagedImage ( ) : Bitmap
return	System.Drawing.Bitmap

ToManagedImage() public method

Create managed image from the unmanaged.

If the makeCopy is set to , then the method creates a managed copy of the unmanaged image, so the managed image stays valid even when the unmanaged image gets disposed. However, setting this parameter to creates a managed image which is just a wrapper around the unmanaged image. So if unmanaged image is disposed, the managed image becomes no longer valid and accessing it will generate an exception.

The unmanaged image has some invalid properties, which results /// in failure of converting it to managed image. This may happen if user used the /// constructor specifying some /// invalid parameters.

public ToManagedImage ( bool makeCopy ) : Bitmap
makeCopy	bool	Make a copy of the unmanaged image or not.
return	System.Drawing.Bitmap

UnmanagedImage() public method

Initializes a new instance of the UnmanagedImage class.

Unlike FromManagedImage(BitmapData) method, this constructor does not make copy of managed image. This means that managed image must stay locked for the time of using the instance of unamanged image.

public UnmanagedImage ( BitmapData bitmapData ) : System
bitmapData	System.Drawing.Imaging.BitmapData	Locked bitmap data.
return	System

UnmanagedImage() public method

Initializes a new instance of the UnmanagedImage class.

Using this constructor, make sure all specified image attributes are correct and correspond to unmanaged memory buffer. If some attributes are specified incorrectly, this may lead to exceptions working with the unmanaged memory.

public UnmanagedImage ( IntPtr imageData, int width, int height, int stride, PixelFormat pixelFormat ) : System
imageData	System.IntPtr	Pointer to image data in unmanaged memory.
width	int	Image width in pixels.
height	int	Image height in pixels.
stride	int	Image stride (line size in bytes).
pixelFormat	PixelFormat	Image pixel format.
return	System