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
显示文件 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.

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).

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