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
Afficher le fichier Open project: holisticware-admin/MonoVersal.AForgeNET Class Usage Examples

Méthodes publiques

Méthode 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.

Méthodes protégées

Méthode Description
Dispose ( bool disposing ) : void

Dispose the object.

Private Methods

Méthode Description
SetPixel ( int x, int y, byte r, byte g, byte b, byte a ) : void

Method Details

Clone() public méthode

Clone the unmanaged images.

The method does complete cloning of the object.

public Clone ( ) : UnmanagedImage
Résultat UnmanagedImage

Collect16bppPixelValues() public méthode

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.
Résultat ushort[]

Collect8bppPixelValues() public méthode

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.
Résultat byte[]

CollectActivePixels() public méthode

Collect coordinates of none black pixels in the image.
public CollectActivePixels ( ) : List
Résultat List

CollectActivePixels() public méthode

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.
Résultat List

Copy() public méthode

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.
Résultat void

Create() public static méthode

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.
Résultat UnmanagedImage

Dispose() public méthode

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
Résultat void

Dispose() protected méthode

Dispose the object.
protected Dispose ( bool disposing ) : void
disposing bool Indicates if disposing was initiated manually.
Résultat void

FromManagedImage() public static méthode

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.
Résultat UnmanagedImage

FromManagedImage() public static méthode

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.
Résultat UnmanagedImage

GetPixel() public méthode

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.
Résultat Color

GetPixel() public méthode

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.
Résultat Color

SetPixel() public méthode

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.
Résultat void

SetPixel() public méthode

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.
Résultat void

SetPixel() public méthode

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.
Résultat void

SetPixels() public méthode

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.
Résultat void

ToManagedImage() public méthode

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
Résultat System.Drawing.Bitmap

ToManagedImage() public méthode

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.
Résultat System.Drawing.Bitmap

UnmanagedImage() public méthode

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.
Résultat System

UnmanagedImage() public méthode

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.
Résultat System