lime.graphics.Image - Lime API Reference

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:

If ((pixelValue & mask) operation(threshold & mask)), then set the pixel to color;
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.

class Image

package lime.graphics

Static methods

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

staticfromBitmapData(bitmapData:BitmapData):Image

staticfromBytes(bytes:Bytes):Image

staticfromCanvas(canvas:CanvasElement):Image

staticfromFile(path:String):Image

staticfromImageElement(image:ImageElement):Image

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

staticloadFromBytes(bytes:Bytes):Future<Image>

staticloadFromFile(path:String):Future<Image>

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)

Variables

buffer:ImageBuffer

data:UInt8Array

dirty:Bool

format:PixelFormat

height:Int

offsetX:Int

offsetY:Int

powerOfTwo:Bool

premultiplied:Bool

read onlyrect:Rectangle

src:Dynamic

transparent:Bool

type:ImageType

version:Int

width:Int

x:Float

y:Float

Methods

clone():Image

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@: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

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

`staticfromBitmapData(bitmapData:BitmapData):Image`

`staticfromBytes(bytes:Bytes):Image`

`staticfromCanvas(canvas:CanvasElement):Image`

`staticfromFile(path:String):Image`

`staticfromImageElement(image:ImageElement):Image`

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

`staticloadFromBytes(bytes:Bytes):Future<Image>`

`staticloadFromFile(path:String):Future<Image>`

`@: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)`

`buffer:ImageBuffer`

`data:UInt8Array`

`dirty:Bool`

`format:PixelFormat`

`height:Int`

`offsetX:Int`

`offsetY:Int`

`powerOfTwo:Bool`

`premultiplied:Bool`

`read onlyrect:Rectangle`

`src:Dynamic`

`transparent:Bool`

`type:ImageType`

`version:Int`

`width:Int`

`x:Float`

`y:Float`

`clone():Image`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`@: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`