This class encapsulates a platform-independent image. In wNim, wImage is a wrap of gdiplus image object.

Seealso:	wImageList wBitmap wIcon wCursor wIconImage

Consts:

The quality used in scale, rescale, transform, and retransform.

Consts	Description
wImageQualityNearest	Specifies nearest-neighbor interpolation.
wImageQualityBilinear	Specifies high-quality, bilinear interpolation.
wImageQualityBicubic	Specifies high-quality, bicubic interpolation.
wImageQualityNormal	Specifies the default interpolation mode.
wImageQualityHigh	Specifies a high-quality mode.
wImageQualityLow	Specifies a low-quality mode.

Used in rotateFlip as flag.

Consts	Description
wImageRotateNoneFlipNone	Specifies no rotation and no flipping.
wImageRotateNoneFlipX	Specifies no rotation and a horizontal flip.
wImageRotateNoneFlipY	Specifies no rotation and a vertical flip.
wImageRotateNoneFlipXY	Specifies no rotation, a horizontal flip, and then a vertical flip.
wImageRotate90FlipNone	Specifies a 90-degree rotation without flipping.
wImageRotate90FlipX	Specifies a 90-degree rotation followed by a horizontal flip.
wImageRotate90FlipY	Specifies a 90-degree rotation followed by a vertical flip.
wImageRotate90FlipXY	Specifies a 90-degree rotation followed by a horizontal flip and then a vertical flip.
wImageRotate180FlipNone	Specifies a 180-degree rotation without flipping.
wImageRotate180FlipX	Specifies a 180-degree rotation followed by a horizontal flip.
wImageRotate180FlipY	Specifies a 180-degree rotation followed by a vertical flip.
wImageRotate180FlipXY	Specifies a 180-degree rotation followed by a horizontal flip and then a vertical flip.
wImageRotate270FlipNone	Specifies a 270-degree rotation without flipping.
wImageRotate270FlipX	Specifies a 270-degree rotation followed by a horizontal flip.
wImageRotate270FlipY	Specifies a 270-degree rotation followed by a vertical flip.
wImageRotate270FlipXY	Specifies a 270-degree rotation followed by a horizontal flip and then a vertical flip.

Types

wImageError = object of wError: An error raised when wImage creation or operation failure.
wPixelFormat = enum wPixelFormat1bppIndexed, ## Specifies that the format is 1 bit per pixel, indexed. wPixelFormat4bppIndexed, ## Specifies that the format is 4 bits per pixel, indexed. wPixelFormat8bppIndexed, ## Specifies that the format is 8 bits per pixel, indexed. wPixelFormat16bppARGB1555, ## Specifies that the format is 16 bits per pixel; 1 bit is used for the alpha component, and 5 bits each are used for the red, green, and blue components. wPixelFormat16bppGrayScale, ## Specifies that the format is 16 bits per pixel, grayscale. wPixelFormat16bppRGB555, ## Specifies that the format is 16 bits per pixel; 5 bits each are used for the red, green, and blue components. The remaining bit is not used. wPixelFormat16bppRGB565, ## Specifies that the format is 16 bits per pixel; 5 bits are used for the red component, 6 bits are used for the green component, and 5 bits are used for the blue component. wPixelFormat24bppRGB, ## Specifies that the format is 24 bits per pixel; 8 bits each are used for the red, green, and blue components. wPixelFormat32bppARGB, ## Specifies that the format is 32 bits per pixel; 8 bits each are used for the alpha, red, green, and blue components. wPixelFormat32bppPARGB, ## Specifies that the format is 32 bits per pixel; 8 bits each are used for the alpha, red, green, and blue components. The red, green, and blue components are premultiplied according to the alpha component. wPixelFormat32bppRGB, ## Specifies that the format is 32 bits per pixel; 8 bits each are used for the red, green, and blue components. The remaining 8 bits are not used. wPixelFormat48bppRGB, ## Specifies that the format is 48 bits per pixel; 16 bits each are used for the red, green, and blue components. wPixelFormat64bppARGB, ## Specifies that the format is 64 bits per pixel; 16 bits each are used for the alpha, red, green, and blue components. wPixelFormat64bppPARGB ## Specifies that the format is 64 bits per pixel; 16 bits each are used for the alpha, red, green, and blue components. The red, green, and blue components are premultiplied according to the alpha component.

Consts

wImageQualityNearest = 5
wImageQualityBilinear = 6
wImageQualityBicubic = 7
wImageQualityNormal = 0
wImageQualityHigh = 2
wImageQualityLow = 1
wImageRotateNoneFlipNone = 0
wImageRotateNoneFlipX = 4
wImageRotateNoneFlipY = 6
wImageRotateNoneFlipXY = 2
wImageRotate90FlipNone = 1
wImageRotate90FlipX = 5
wImageRotate90FlipY = 7
wImageRotate90FlipXY = 3
wImageRotate180FlipNone = 2
wImageRotate180FlipX = 6
wImageRotate180FlipY = 4
wImageRotate180FlipXY = 0
wImageRotate270FlipNone = 3
wImageRotate270FlipX = 7
wImageRotate270FlipY = 5
wImageRotate270FlipXY = 1
wImageTypeBmp = "BMP"
wImageTypeGif = "GIF"
wImageTypeJpeg = "JPG"
wImageTypePng = "PNG"
wImageTypeTiff = "TIF"
wImageTypeIco = "ICO"
wBitmapTypeBmp = "BMP"
wBitmapTypeGif = "GIF"
wBitmapTypeJpeg = "JPG"
wBitmapTypePng = "PNG"
wBitmapTypeTiff = "TIF"
wBitmapTypeIco = "ICO"

Procs

proc delete(self: wImage) {...}{.raises: [], tags: [].}

Nim's garbage collector will delete this object by default. However, sometimes you maybe want do that by yourself.

proc getHandle(self: wImage): ptr GpBitmap {...}{.inline, raises: [], tags: [].}

Gets the real resource handle of gdiplus bitmap.

proc getWidth(self: wImage): int {...}{.raises: [wImageError], tags: [].}

Gets the width of the image in pixels.

proc getHeight(self: wImage): int {...}{.raises: [wImageError], tags: [].}

Gets the height of the image in pixels.

proc getSize(self: wImage): wSize {...}{.inline, raises: [wImageError], tags: [].}

Returns the size of the image in pixels.

proc getPixel(self: wImage; x: int; y: int): ARGB {...}{.raises: [wImageError], tags: [].}

Return the ARGB value at given pixel location.

proc getPixel(self: wImage; pos: wPoint): ARGB {...}{.raises: [wImageError], tags: [].}

Return the ARGB value at given pixel location.

proc setPixel(self: wImage; x: int; y: int; color: ARGB) {...}{.raises: [wImageError], tags: [].}

Set the ARGB value at given pixel location.

proc setPixel(self: wImage; pos: wPoint; color: ARGB) {...}{.raises: [wImageError], tags: [].}

Set the ARGB value at given pixel location.

proc getRed(self: wImage; x: int; y: int): byte {...}{.raises: [wImageError], tags: [].}

Returns the red intensity at the given coordinate.

proc getRed(self: wImage; pos: wPoint): byte {...}{.raises: [wImageError], tags: [].}

Returns the red intensity at the given coordinate.

proc getGreen(self: wImage; x: int; y: int): byte {...}{.raises: [wImageError], tags: [].}

Returns the green intensity at the given coordinate.

proc getGreen(self: wImage; pos: wPoint): byte {...}{.raises: [wImageError], tags: [].}

Returns the green intensity at the given coordinate.

proc getBlue(self: wImage; x: int; y: int): byte {...}{.raises: [wImageError], tags: [].}

Returns the blue intensity at the given coordinate.

proc getBlue(self: wImage; pos: wPoint): byte {...}{.raises: [wImageError], tags: [].}

Returns the blue intensity at the given coordinate.

proc getAlpha(self: wImage; x: int; y: int): byte {...}{.raises: [wImageError], tags: [].}

Return alpha value at given pixel location.

proc getAlpha(self: wImage; pos: wPoint): byte {...}{.raises: [wImageError], tags: [].}

Return alpha value at given pixel location.

proc saveFile(self: wImage; filename: string; fileType = ""; quality: range[0 .. 100] = 90) {...}{.raises: [wImageError], tags: [].}

Saves an image into the file. If fileType is empty, use extension name as fileType. Use getEncoders iterator to list the supported format.

proc saveData(self: wImage; fileType: string; quality: range[0 .. 100] = 90): string {...}{. raises: [wImageError], tags: [RootEffect].}

Saves an image into binary data (stored as string). Use getEncoders iterator to list the supported format.

proc init(self: wImage; gdip: ptr GpBitmap; copy = true) {...}{. raises: [wNilAccess, wImageError], tags: [].}

Initializes an image from a gdiplus bitmap handle. If copy is false, this only wrap it to wImage object. It means the handle will be destroyed by wImage when it is destroyed.

proc Image(gdip: ptr GpBitmap; copy = true): wImage {...}{.inline, discardable, raises: [wNilAccess, wImageError], tags: [].}

Constructor.

proc init(self: wImage; image: wImage) {...}{.inline, raises: [wNilAccess, wImageError], tags: [].}

Initializes an image from wImage object, aka. copy constructors.

proc Image(image: wImage): wImage {...}{.inline, discardable, raises: [wNilAccess, wImageError], tags: [].}

Constructor.

proc init(self: wImage; bmp: wBitmap) {...}{.raises: [wNilAccess, wImageError], tags: [].}

Initializes an image from wBitmap object.

proc Image(bmp: wBitmap): wImage {...}{.inline, discardable, raises: [wNilAccess, wImageError], tags: [].}

Constructor.

proc init(self: wImage; data: pointer; length: int) {...}{. raises: [wNilAccess, Exception, wImageError], tags: [RootEffect].}

Initializes an image from binary image data. Use getDecoders iterator to list the supported format.

proc Image(data: pointer; length: int): wImage {...}{.inline, raises: [wNilAccess, Exception, wImageError], tags: [RootEffect].}

Constructor.

proc init(self: wImage; str: string) {...}{.raises: [wImageError, wNilAccess, Exception], tags: [RootEffect].}

Initializes an image from a file. Use getDecoders iterator to list the supported format. If str is not a valid file path, it will be regarded as the binary data in memory. For example:

const data = staticRead("test.png")
var image = Image(data)

proc Image(str: string): wImage {...}{.inline, discardable, raises: [wImageError, wNilAccess, Exception], tags: [RootEffect].}

Constructor.

proc init(self: wImage; width: int; height: int) {...}{.raises: [wImageError], tags: [].}

Initializes an empty image with the given size.

proc Image(width: int; height: int): wImage {...}{.inline, discardable, raises: [wImageError], tags: [].}

Constructor.

proc init(self: wImage; size: wSize) {...}{.inline, raises: [wImageError], tags: [].}

Initializes an empty image with the given size.

proc Image(size: wSize): wImage {...}{.inline, discardable, raises: [wImageError], tags: [].}

Constructor.

proc init(self: wImage; iconImage: wIconImage) {...}{. raises: [wNilAccess, Exception, wImageError], tags: [RootEffect].}

Initializes an image from a wIconImage object.

proc Image(iconImage: wIconImage): wImage {...}{.inline, raises: [wNilAccess, Exception, wImageError], tags: [RootEffect].}

Constructor.

proc init(self: wImage; icon: wIcon) {...}{.raises: [wNilAccess, wNilAccess, Exception, wImageError], tags: [RootEffect].}

Initializes an image from wIcon object.

proc Image(icon: wIcon): wImage {...}{.inline, discardable, raises: [wNilAccess, Exception, wImageError], tags: [RootEffect].}

Constructor.

proc init(self: wImage; cursor: wCursor) {...}{.raises: [wNilAccess, wNilAccess, Exception, wImageError], tags: [RootEffect].}

Initializes an image from wCursor object.

proc Image(cursor: wCursor): wImage {...}{.inline, discardable, raises: [wNilAccess, Exception, wImageError], tags: [RootEffect].}

Constructor.

proc init(self: wImage; width: int; height: int; stride: int; format: wPixelFormat; scan0: pointer) {...}{.raises: [wImageError], tags: [].}

Initializes an image based on binary bytes along with size and format information.

proc Image(width: int; height: int; stride: int; format: wPixelFormat; scan0: pointer): wImage {...}{. inline, discardable, raises: [wImageError], tags: [].}

Constructor.

proc scale(self: wImage; width, height: int; quality = wImageQualityNormal): wImage {...}{. raises: [wImageError, wNilAccess], tags: [].}

Returns a scaled version of the image.

proc scale(self: wImage; size: wSize; quality = wImageQualityNormal): wImage {...}{.inline, raises: [wImageError, wNilAccess], tags: [].}

Returns a scaled version of the image.

proc rescale(self: wImage; width, height: int; quality = wImageQualityNormal) {...}{. discardable, raises: [wImageError], tags: [].}

Changes the size of the image in-place by scaling it.

proc rescale(self: wImage; size: wSize; quality = wImageQualityNormal) {...}{.inline, discardable, raises: [wImageError], tags: [].}

Changes the size of the image in-place by scaling it.

proc size(self: wImage; size: wSize; pos: wPoint = (0, 0); align = 0): wImage {...}{. raises: [wImageError, wNilAccess], tags: [].}

Returns a resized version of this image without scaling it. The image is pasted into a new image at the position pos or by given align. align can be combine of wRight, wCenter, wLeft, wUp, wMiddle, wDown.

proc size(self: wImage; width, height: int; x, y: int = 0; align = 0): wImage {...}{.inline, raises: [wImageError, wNilAccess], tags: [].}

Returns a resized version of this image without scaling it.

proc resize(self: wImage; size: wSize; pos: wPoint = (0, 0); align = 0) {...}{.discardable, raises: [wImageError], tags: [].}

Changes the size of the image in-place without scaling it.

proc resize(self: wImage; width, height: int; x, y: int = 0; align = 0) {...}{.discardable, raises: [wImageError], tags: [].}

Changes the size of the image in-place without scaling it.

proc transform(self: wImage; scaleX, scaleY: float = 1; angle, deltaX, deltaY: float = 0; quality = wImageQualityNormal): wImage {...}{. raises: [wImageError, wNilAccess], tags: [].}

Returned a transformed version of this image by given parameters.

proc retransform(self: wImage; scaleX, scaleY: float = 1; angle, deltaX, deltaY: float = 0; quality = wImageQualityNormal) {...}{. discardable, raises: [wImageError], tags: [].}

Transforms the image in-place.

proc paste(self: wImage; image: wImage; x, y: int = 0; align = 0) {...}{.discardable, raises: [wNilAccess, wImageError], tags: [].}

Copy the data of the given image to the specified position in this image.

proc paste(self: wImage; image: wImage; pos: wPoint; align = 0) {...}{.discardable, raises: [wNilAccess, wImageError], tags: [].}

Copy the data of the given image to the specified position in this image.

proc rotateFlip(self: wImage; flag: int) {...}{.discardable, raises: [wImageError], tags: [].}

Rotates or flip the image.

proc rotateFlip(self: wImage; angle: int; flipX: bool; flipY: bool) {...}{.discardable, raises: [wImageError], tags: [].}

Rotates or flip the image. Angle should be one of 0, 90, 180, 270.

proc getSubImage(self: wImage; rect: wRect): wImage {...}{.raises: [wImageError], tags: [].}

Returns a sub image of the current one as long as the rect belongs entirely to the image.

proc crop(self: wImage; x, y, width, height: int): wImage {...}{.raises: [wImageError], tags: [].}

Returns a cropped image of the current one as long as the rect belongs entirely to the image.

proc blur(self: wImage; radius: range[0 .. 255] = 0; expandEdge = true) {...}{. raises: [wImageError], tags: [].}

Blur effect (Windows Vista or later).

proc brightnessContrast(self: wImage; brightness: range[-255 .. 255] = 0; contrast: range[-100 .. 100] = 0) {...}{.raises: [wImageError], tags: [].}

Brightness or contrast adjustment (Windows Vista or later).

proc sharpen(self: wImage; radius: range[0 .. 255] = 0; amount: range[0 .. 100] = 0) {...}{. raises: [wImageError], tags: [].}

Sharpen effect (Windows Vista or later).

proc tint(self: wImage; hue: range[-180 .. 180] = 0; amount: range[0 .. 100] = 0) {...}{. raises: [wImageError], tags: [].}

Tint effect (Windows Vista or later).

proc hueSaturationLightness(self: wImage; hue: range[-180 .. 180] = 0; saturation: range[-100 .. 100] = 0; lightness: range[-100 .. 100] = 0) {...}{.raises: [wImageError], tags: [].}

Hue, saturation, or lightness adjustment (Windows Vista or later).

proc colorBalance(self: wImage; cyanRed: range[-100 .. 100] = 0; magentaGreen: range[-100 .. 100] = 0; yellowBlue: range[-100 .. 100] = 0) {...}{.raises: [wImageError], tags: [].}

Color balance adjustment (Windows Vista or later).

proc levels(self: wImage; highlight: range[0 .. 100] = 0; midtone: range[-100 .. 100] = 0; shadow: range[0 .. 100] = 0) {...}{. raises: [wImageError], tags: [].}

Light, midtone, or dark adjustment (Windows Vista or later).

Iterators

iterator getEncoders(self: wImage): string {...}{.raises: [wImageError], tags: [].}: Iterates over each available image encoder on system.
iterator getDecoders(self: wImage): string {...}{.raises: [wImageError], tags: [].}: Iterates over each available image decoder on system.