Image is a convenience class for working with bitmap images in Lime.

Although ImageBuffer holds the actual bitmap data, Image includes convenience methods for loading from files, loading from bytes, and performing many pixel operations over an ImageBuffer instance.

Static methods

staticfromBase64(base64:String, type:String):Image

Converts a Base64-encoded String into an Image, or returns null if this is not possible

Parameters:

base64

A Base64-encoded String

type

A mime-type to describe the image data (such as "image/png")

Returns:

A new Image, or null if conversion was not possible

staticfromBitmapData(bitmapData:BitmapData):Image

Available on Flash

Creates a new Image from a Flash BitmapData instance

Parameters:

bitmapData

A source bitmapData to use

Returns:

A new Image instance

staticfromBytes(bytes:Bytes):Image

Converts a Bytes object to an Image instance

Some platforms (such as Flash and HTML5) cannot convert Bytes to an Image synchronously, and may not work properly.

Image.loadFromBytes works asynchronously, and should work consistently on all platforms.

Parameters:

bytes

A Bytes holding encoded image data

Returns:

A new Image instance

staticfromCanvas(canvas:CanvasElement):Image

Available on HTML5

Converts an js.html.CanvasElement instance to an Image

Parameters:

canvas

A CanvasElement

Returns:

A new Image instance

staticfromFile(path:String):Image

Loads an Image from a path synchronously.

Some platforms, such as Flash and HTML5, cannot load images synchronously.

Image.loadFromFile works asynchronously, and should behave consistently on all platforms.

Parameters:

path

The source file path or URL of an encoded image file

Returns:

A new Image instance

staticfromImageElement(image:ImageElement):Image

Available on HTML5

Converts a js.html.Image instance to an Image

Parameters:

image

An ImageElement instance

Returns:

A new Image instance

staticloadFromBase64(base64:String, type:String):Future<Image>

Creates a new Image instance from a Base64-encoded String, asynchronously

Parameters:

base64

A Base64-encoded string representing encoded image data

type

The mime type of the encoded data (such as "image/png")

Returns:

A Future to return a new Image instance

staticloadFromBytes(bytes:Bytes):Future<Image>

Creates a new Image instance from image-encoded Bytes, loaded asynchronously

Parameters:

bytes

A Bytes instance

Returns:

A Future to return a new Image instance

staticloadFromFile(path:String):Future<Image>

Creates a new Image instance from a file path or URL, loaded asynchronously

Parameters:

path

A file path or URL containing an encoded image

Returns:

A Future to return a new Image instance

Constructor

@:value({ type : null, color : null, height : -1, width : -1, offsetY : 0, offsetX : 0, buffer : null })new(?buffer:ImageBuffer, offsetX:Int = 0, offsetY:Int = 0, width:Int = -1, height:Int = -1, ?color:Int, ?type:ImageType)

Creates a new Image instance.

If buffer is null, but width and height are set, a new ImageBuffer is allocated matching the color requested.

Parameters:

buffer

(Optional) The ImageBuffer this Image represents

offsetX

(Optional) A logical offset value within the ImageBuffer dimensions

offsetY

(Optional) A logical offset value within the ImageBuffer dimensions

width

(Optional) A logical width value within the ImageBuffer dimensions

height

(Optional) A logical height value within the ImageBuffer dimensions

color

(Optional) A fill color to use if the buffer property is null

type

(Optional) An ImageType to use for this Image

Variables

buffer:ImageBuffer

The ImageBuffer store that backs the Image

data:UInt8Array

Retrieves UInt8Array data from the ImageBuffer. If the ImageBuffer is not in a data format, it will be converted.

dirty:Bool

Whether the Image is dirty. This is set to true when pixel operations have been performed on the underlying buffer, and can be set to false again by your own renderer.

format:PixelFormat

Get or set the PixelFormat for the underlying ImageBuffer. This can be used to convert the ImageBuffer to a new format.

height:Int

The logical height of the Image. This can be smaller than the height of the underlying buffer.

offsetX:Int

The offset X position of the Image, from the source buffer, when the Image is smaller than the full size of the source buffer

offsetY:Int

The offset Y position of the Image, from the source buffer, when the Image is smaller than the full size of the source buffer

powerOfTwo:Bool

Get or set whether the ImageBuffer dimensions are both a power-of-two (such as 2, 4, 8, 16, so on). Setting this value may resize the underlying buffer

premultiplied:Bool

Get or set whether this Image has premultiplied alpha. Setting this value may multiply or unmultiply data if the underlying ImageBuffer uses a different format.

read onlyrect:Rectangle

The offset, width and height of this image as a Rectangle

src:Dynamic

A higher-level representation of the source ImageBuffer. This might be an HTML5 Image, CanvasElement or a Flash BitmapData instance.

transparent:Bool

Get or set whether the underlying ImageBuffer is transparent.

type:ImageType

The current ImageType, representing what is being used to store the Image's graphics

version:Int

The version of the Image increases each time it is modified, helpful to determining whether a cache is out-of-date.

width:Int

The logical width of the Image. This can be smaller than the width of the underlying buffer.

x:Float

A convenience property, unused internally, which may be helpful for different renderer implementations

y:Float

A convenience property, unused internally, which may be helpful for different renderer implementations

Methods

clone():Image

Creates a duplicate copy of this Image and ImageBuffer

Returns:

A new Image instance

colorTransform(rect:Rectangle, colorMatrix:ColorMatrix):Void

Applies a color transform to the underlying ImageBuffer data

Parameters:

rect

The target rectangle to transform

colorMatrix

A ColorMatrix for color offset and/or multiplication

copyChannel(sourceImage:Image, sourceRect:Rectangle, destPoint:Vector2, sourceChannel:ImageChannel, destChannel:ImageChannel):Void

Copy a color channel from one Image to another. This can also be within the same Image instance.

Parameters:

sourceImage

The Image to copy from

sourceRect

The source rectangle to copy from in the sourceImage

destPoint

The destination point to apply the channel in the current Image

sourceChannel

The source color channel to copy the data from

destChannel

The destination color channel to apply the data into

@:value({ mergeAlpha : false, alphaPoint : null, alphaImage : null })copyPixels(sourceImage:Image, sourceRect:Rectangle, destPoint:Vector2, ?alphaImage:Image, ?alphaPoint:Vector2, mergeAlpha:Bool = false):Void

Copies pixels from one Image to another. The source Image can also be this Image

Parameters:

sourceImage

The source Image to copy from

sourceRect

The source rectangle to use when copying

destPoint

The destination point to use when copying

alphaImage

(Optional) A different Image to use as the alpha channel while copying

alphaPoint

(Optional) A point in the alpha image to use when copying

mergeAlpha

(Optional) Whether to blend the source and destination alpha (true), or to replace the destination alpha (false)

@:value({ quality : 90, format : null })encode(?format:ImageFileFormat, quality:Int = 90):Bytes

Encodes this Image into an image file format, such as PNG or JPEG.

Parameters:

format

(Optional) An ImageFileFormat to encode into (default is PNG)

quality

(Optional) A quality value to use when encoding as JPEG (from 0 to 100)

Returns:

Bytes for the encoded Image, or null if encoding was not successful

@:value({ format : null })fillRect(rect:Rectangle, color:Int, ?format:PixelFormat):Void

Fill a rectangle in the Image with a solid color

Parameters:

rect

A destination rectangle in this Image to fill

color

The color to use when filling this Image

format

(Optional) The PixelFormat that color is encoded in (default is RGBA)

@:value({ format : null })floodFill(x:Int, y:Int, color:Int, ?format:PixelFormat):Void

Applies a flood fill to this Image, starting with the point specified.

A flood fill behaves similarly to the "paint can" tool in many image editors, the fill will apply the chosen color to neighboring pixels of the same color.

Parameters:

x

The target x coordinate within the Image to use with the fill

y

The target y coordinate within the Image to use with the fill

color

The color to use when performing the fill

format

(Optional) The PixelFormat that color is encoded in (default is RGBA)

@:value({ format : null, findColor : true })getColorBoundsRect(mask:Int, color:Int, findColor:Bool = true, ?format:PixelFormat):Rectangle

Finds a region in the Image that includes pixels all of a certain color (when findColor is true) or excludes a certain color (findColor is false)

Parameters:

mask

A hexadecimal mask to use when comparing colors. You can use this to compare all of a color, or only certain color channels

color

The color value to use in comparisons

findColor

(Optional) Whether to find a region that does match the color (true) or excludes it (false)

format

(Optional) The PixelFormat that the color and mask are encoded in (default is RGBA)

Returns:

The matching bounds Rectangle, or null if no matching region is found

@:value({ format : null })getPixel(x:Int, y:Int, ?format:PixelFormat):Int

Gets a 24-bit pixel from the Image (red, green and blue, but no alpha)

Parameters:

x

The x location to fetch

y

The y location to fetch

format

(Optional) The PixelFormat to encode the return value in (default is RGBA)

Returns:

The specified pixel, or 0 if it is out-of-bounds

@:value({ format : null })getPixel32(x:Int, y:Int, ?format:PixelFormat):Int

Gets a 32-bit pixel from the Image, including alpha

Parameters:

x

The x location to fetch

y

The y location to fetch

format

(Optional) The PixelFormat to encode the return value in (default is RGBA)

Returns:

The specified pixel, or 0 if it is out-of-bounds

@:value({ format : null })getPixels(rect:Rectangle, ?format:PixelFormat):Bytes

Gets a region of pixels from the Image, as Bytes

Parameters:

rect

The source Rectangle to read from

format

(Optional) The PixelFormat to use when writing to the Bytes object (default is RGBA)

Returns:

A Bytes object representing the region, or null if it is not possible to read

merge(sourceImage:Image, sourceRect:Rectangle, destPoint:Vector2, redMultiplier:Int, greenMultiplier:Int, blueMultiplier:Int, alphaMultiplier:Int):Void

Blits a second Image onto this one, using optional color multipliers

Parameters:

sourceImage

An Image instance to copy from

sourceRect

The source rectangle to use when copying

destPoint

The destination point in this Image to copy into

redMultiplier

A red multiplier to use when blitting

greenMultiplier

A green multiplier to use when blitting

blueMultiplier

A blue multiplier to use when blitting

alphaMultiplier

An alpha multiplier to use when blitting

resize(newWidth:Int, newHeight:Int):Void

Resizes the current Image, reallocating the ImageBuffer to a new size. The resize algorithm for most platforms is bilinear.

Parameters:

newWidth

A new width for the Image

newHeight

A new height for the Image

scroll(x:Int, y:Int):Void

Scrolls the content of this Image.

Pixels on the edges of the scroll will remain repeated, while others within the scroll area will be shifted

Parameters:

x

The amount of horizontal scroll to apply

y

The amount of vertical scroll to apply

@:value({ format : null })setPixel(x:Int, y:Int, color:Int, ?format:PixelFormat):Void

Sets a pixel in the current Image in 24-bit color format (red, green, blue, no alpha)

Parameters:

x

The x coordinate of the pixel

y

The y coordinate of the pixel

color

The color to use

format

(Optional) The PixelFormat that color is encoded in (default is RGBA)

@:value({ format : null })setPixel32(x:Int, y:Int, color:Int, ?format:PixelFormat):Void

Sets a pixel in the current Image in 32-bit color format (includes alpha)

Parameters:

x

The x coordinate of the pixel

y

The y coordinate of the pixel

color

The color to use

format

(Optional) The PixelFormat that color is encoded in (default is RGBA)

@:value({ endian : null, format : null })setPixels(rect:Rectangle, bytePointer:BytePointer, ?format:PixelFormat, ?endian:Endian):Void

Sets a region of pixels at once using a BytePointer

Parameters:

rect

The region of pixels in this Image to replace with the incoming bytes

bytePointer

A BytePointer object referencing the Bytes and position to read from

format

(Optional) The PixelFormat that the pixels are encoded in (default is RGBA)

endian

(Optional) The endianness of the incoming bytes (default is the system endianness)

@:value({ format : null, copySource : false, mask : 0xFFFFFFFF, color : 0x00000000 })threshold(sourceImage:Image, sourceRect:Rectangle, destPoint:Vector2, operation:String, threshold:Int, color:Int = 0x00000000, mask:Int = 0xFFFFFFFF, copySource:Bool = false, ?format:PixelFormat):Int

Tests pixel values in an image against a specified threshold and sets pixels that pass the test to new color values. Using the threshold() method, you can isolate and replace color ranges in an image and perform other logical operations on image pixels.

The threshold() method's test logic is as follows:

  1. If ((pixelValue & mask) operation(threshold & mask)), then set the pixel to color;
  2. Otherwise, if copySource == true, then set the pixel to corresponding pixel value from sourceBitmap.

The operation parameter specifies the comparison operator to use for the threshold test. For example, by using "==" as the operation parameter, you can isolate a specific color value in an image. Or by using {operation: "<", mask: 0xFF000000, threshold: 0x7F000000, color: 0x00000000}, you can set all destination pixels to be fully transparent when the source image pixel's alpha is less than 0x7F. You can use this technique for animated transitions and other effects.

Parameters:

sourceImage

The input bitmap image to use. The source image can be a different Image object or it can refer to the current Image instance.

sourceRect

A rectangle that defines the area of the source image to use as input.

destPoint

The point within the destination image (the current Image instance) that corresponds to the upper-left corner of the source rectangle.

operation

One of the following comparison operators, passed as a String: "<", "<=", ">", ">=", "==", "!="

threshold

The value that each pixel is tested against to see if it meets or exceeds the threshhold.

color

The color value that a pixel is set to if the threshold test succeeds. The default value is 0x00000000.

mask

The mask to use to isolate a color component.

copySource

If the value is true, pixel values from the source image are copied to the destination when the threshold test fails. If the value is false, the source image is not copied when the threshold test fails.

Returns:

The number of pixels that were changed.