LuaStudio API documentation

Lib.Media.Display.BitmapData.new(inWidth, inHeight, inTransparent, fillColor, inPixelFormat)

Creates a BitmapData object with a specified width inWidth and height inHeight. If you specify a value for the fillColor parameter, every pixel in the bitmap is set to that color. By default, the bitmap is created as transparent, unless you pass the value false for the transparent parameter. After you create an opaque bitmap, you cannot change it to a transparent bitmap. Every pixel in an opaque bitmap uses only 24 bits of color channel information. If you define the bitmap as transparent, every pixel uses 32 bits of color channel information, including an alpha transparency channel.

inWidth - The width of the bitmap image in pixels.

inHeight - The height of the bitmap image in pixels.

inTransparent - Specifies whether the bitmap image supports per-pixel transparency. The recommended default value is true(transparent). To create a fully transparent bitmap, set the value of the transparent parameter to true and the value of the fillColor parameter to 0x00000000(or to 0). Setting the transparent property to false can result in minor improvements in rendering performance.

fillColor - A 32-bit ARGB color value that you use to fill the bitmap image area. The recommended default value is 0xFFFFFFFF(solid white).

inPixelFormat - Int, PixelFormat, Default =-1 (None)

Lib.Media.Display.BitmapData.loadFromBytes(bytes, rawAlpha)

Creates BitmapData object from ByteArray objects including rawAlpha (can be nil) 

bytes - ByteArray object 

rawAlpha - ByteArray object, can be nil

height

The height of the bitmap image in pixels.

read-only

width

The width of the bitmap image in pixels.

read-only

rect

The rectangle that defines the size and location of the bitmap image.

read-only

transparent

Defines whether the bitmap image supports per-pixel transparency.

read-only true/false

applyFilter(sourceBitmapData, sourceRect, destPoint, filter)

Takes a source image sourceBitmapData and a filter object and generates the filtered image. This method relies on the behavior of built-in filter objects, which determine the destination rectangle that is affected by an input source rectangle sourceRect. After a filter is applied, the resulting image can be larger than the input image. For example, if you use a BlurFilter class to blur a source rectangle of(50,50,100,100) and a destination point of(10,10), the area that changes in the destination image is larger than(10,10,60,60) because of the blurring. This happens internally during the applyFilter() call. If the sourceRect parameter of the sourceBitmapData parameter is an interior region, such as(50,50,100,100) in a 200 x 200 image, the filter uses the source pixels outside the sourceRect parameter to generate the destination rectangle. If the BitmapData object and the object specified as the sourceBitmapData parameter are the same object, the application uses a temporary copy of the object to perform the filter. For best performance, avoid this situation.

sourceBitmapData - The input bitmap image to use. The source image can be a different BitmapData object or it can refer to the current BitmapData 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 BitmapData instance) that corresponds to the upper-left corner of the source rectangle.

filter - The filter object that you use to perform the filtering operation.

clone()

Returns a new BitmapData object that is a clone of the original instance with an exact copy of the contained bitmap.

colorTransform(rect, colorTransform) 

Adjusts the color values in a specified area of a bitmap image by using a ColorTransform object. If the rectangle matches the boundaries of the bitmap image, this method transforms the color values of the entire image.

rect - A Rectangle object that defines the area of the image in which the ColorTransform object is applied.

colorTransform - A ColorTransform object that describes the color transformation values to apply.

copyChannel(sourceBitmapData, sourceRect, destPoint, inSourceChannel, inDestChannel)

Transfers data from one channel of another BitmapData object or the current BitmapData object into a channel of the current BitmapData object. All of the data in the other channels in the destination BitmapData object are preserved.

The source channel value and destination channel value can be one of following values:

BitmapDataChannel.RED

BitmapDataChannel.GREEN

BitmapDataChannel.BLUE

BitmapDataChannel.ALPHA

sourceBitmapData - The input bitmap image to use. The source image can be a different BitmapData object or it can refer to the current BitmapData object.

sourceRect - The source Rectangle object. To copy only channel data from a smaller area within the bitmap, specify a source rectangle that is smaller than the overall size of the BitmapData object.

destPoint - The destination Point object that represents the upper-left corner of the rectangular area where the new channel data is placed. To copy only channel data from one area to a different area in the destination image, specify a point other than (0,0).

sourceChannel - The source channel. Use a value from the BitmapDataChannel object (BitmapDataChannel.RED, BitmapDataChannel.BLUE, BitmapDataChannel.GREEN, BitmapDataChannel.ALPHA).

destChannel - The destination channel. Use a value from the BitmapDataChannel object (BitmapDataChannel.RED, BitmapDataChannel.BLUE, BitmapDataChannel.GREEN, BitmapDataChannel.ALPHA).

copyPixels(sourceBitmapData, sourceRect, destPoint, alphaBitmapData, alphaPoint, mergeAlpha)

Provides a fast routine to perform pixel manipulation between images with no stretching, rotation, or color effects. This method copies a rectangular area of a source image to a rectangular area of the same size at the destination point of the destination BitmapData object.

If you include the alphaBitmapData and alphaPoint parameters, you can use a secondary image as an alpha source for the source image. If the source image has alpha data, both sets of alpha data are used to composite pixels from the source image to the destination image. The alphaPoint parameter is the point in the alpha image that corresponds to the upper-left corner of the source rectangle. Any pixels outside the intersection of the source image and alpha image are not copied to the destination image.

The mergeAlpha property controls whether or not the alpha channel is used when a transparent image is copied onto another transparent image. To copy pixels with the alpha channel data, set the mergeAlpha property to true. By recommended default, the mergeAlpha property is false.

sourceBitmapData - The input bitmap image from which to copy pixels. The source image can be a different BitmapData instance, or it can refer to the current BitmapData instance.

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

destPoint - The destination point that represents the upper-left corner of the rectangular area where the new pixels are placed.

alphaBitmapData - A secondary, alpha BitmapData object source.

alphaPoint - The point in the alpha BitmapData object source that corresponds to the upper-left corner of the sourceRect parameter.

mergeAlpha - To use the alpha channel, set the value to true. To copy pixels with no alpha channel, set the value to false.

dispose()

Frees memory that is used to store the BitmapData object.

When the dispose() method is called on an image, the width and height of the image are set to 0. All subsequent calls to methods or properties of this BitmapData instance fail, and an exception is thrown.

BitmapData.dispose() releases the memory occupied by the actual bitmap data, immediately(a bitmap can consume up to 64 MB of memory). After using BitmapData.dispose(), the BitmapData object is no longer usable and an exception may be thrown if you call functions on the BitmapData object. However, BitmapData.dispose() does not garbage collect the BitmapData object(approximately 128 bytes); the memory occupied by the actual BitmapData object is released at the time the BitmapData object is collected by the garbage collector.

draw(source, matrix, colorTransform, blendMode, clipRect, smoothing)

Draws the source display object onto the bitmap image, using the Lib software renderer. You can specify matrix, colorTransform, blendMode, and a destination clipRect parameter to control how the rendering performs, you can specify whether the bitmap should be smoothed when scaled.

The source display object does not use any of its applied transformations for this call. It is treated as it exists in the library or file, with no matrix transform, no color transform, and no blend mode. To draw a display object(such as a movie clip) by using its own transform properties, you can copy its transform property object to the transform property of the Bitmap object that uses the BitmapData object.

source - The display object or BitmapData object to draw to the BitmapData object.

matrix - A Matrix object used to scale, rotate, or translate the coordinates of the bitmap. If you do not want to apply a matrix transformation to the image, set this parameter to an identity matrix, created with the default Matrix.new() constructor, or pass a nil value.

colorTransform - A ColorTransform object that you use to adjust the color values of the bitmap. If no object is supplied (nil), the bitmap image's colors are not transformed. If you must pass this parameter but you do not want to transform the image, set this parameter to a ColorTransform object created with the default ColorTransform.new() constructor.

blendMode - A string value, from the BlendMode object, specifying the blend mode to be applied to the resulting bitmap.

clipRect - A Rectangle object that defines the area of the source object to draw. If you do not supply this value (nil), no clipping occurs and the entire source object is drawn.

smoothing - A Boolean value that determines whether a BitmapData object is smoothed when scaled or rotated, due to a scaling or rotation in the matrix parameter. With smoothing set to false, the rotated or scaled BitmapData image can appear pixelated or jagged. For example, the following two images use the same BitmapData object for the source parameter, but the smoothing parameter is set to true on the left and false on the right:

Drawing a bitmap with smoothing set to true takes longer than doing so with smoothing set to false.

encode(format, quality)

Encodes the current image as a JPG or PNG format ByteArray.

Returns a ByteArray in the specified encoding format

format - The encoding format, either "png" or "jpg" string:

Lib.Media.Display.BitmapData.PNG

Lib.Media.Display.BitmapData.JPG

quality - The encoding quality, when encoding with the JPG format. (recommended default value 0.9)

fillRect(rect, colour)

Fills a rectangular area rect of pixels with a specified ARGB color.

rect - The rectangular area to fill.

color - The ARGB color value that fills the area. ARGB colors are often specified in hexadecimal format; for example, 0xFF336699.

fillRectEx(rect, colour, alpha)

Fills a rectangular area rect of pixels with a specified ARGB color, using alpha.

rect - The rectangular area to fill.

color - The ARGB color value that fills the area. ARGB colors are often specified in hexadecimal format; for example, 0xFF336699.

alpha - alpha value, recommended default 255

floodFill(x, y, color)

Performs a flood fill operation on an image starting at an (x, y) coordinate and filling with a certain color.

x - start coordinate x

y - start coordinate y

color - color value

getBytes(inPixelFormat)

Returns ByteArray

inPixelFormat - Int, PixelFormat, Default =-1 (None)

getColorBoundsRect(mask, color, findColor)

Determines a rectangular region that either fully encloses all pixels of a specified color within the bitmap image(if the findColor parameter is set to true) or fully encloses all pixels that do not include the specified color(if the findColor parameter is set to false).

For example, if you have a source image and you want to determine the rectangle of the image that contains a nonzero alpha channel, pass {mask: 0xFF000000, color: 0x00000000} as parameters. If the findColor parameter is set to true, the entire image is searched for the bounds of pixels for which (value AND mask) == color(where value is the color value of the pixel). If the findColor parameter is set to false, the entire image is searched for the bounds of pixels for which (value AND mask) ~= color(where value is the color value of the pixel). To determine white space around an image, pass {mask: 0xFFFFFFFF, color: 0xFFFFFFFF} to find the bounds of nonwhite pixels.

Returns the region of the image that is the specified color.

mask  - A hexadecimal value, specifying the bits of the ARGB color to consider. The color value is combined with this hexadecimal value, by using the (bitwise AND) operator.

color - A hexadecimal value, specifying the ARGB color to match (if findColor is set to true) or not to match(if findColor is set to false).

findColor - If the value is set to true, returns the bounds of a color value in an image. If the value is set to false, returns the bounds of where this color doesn't exist in an image. (default recommended value is true)

getData(dataHandle, inPixelFormat, dataOffset, dataStride, subSample)

Get the pixels and fill  a (region) of a byte buffer of given pixel format.

The buffer should be allocated with enough room to hold the data

Pixel conversion between non-float types will take place (eg, pfLuma -> pfRGB)

dataHandle - ByteArray  

inPixelFormat - PixelFormat, Default = -1 (None),

dataOffset - Data offset, Default = 0, 

dataStride - Data stride, Default = 0, 

subSample - Sub sample, Default = 1

getPixel(x, y)

Returns an ARGB color value that contains alpha channel data and RGB data. This method is similar to the getPixel() method, which returns an RGB color without alpha channel data. If the(x, y) coordinates are outside the bounds of the image, 0 is returned.

All pixels in a BitmapData object are stored as premultiplied color values. A premultiplied image pixel has the red, green, and blue color channel values already multiplied by the alpha data. For example, if the alpha value is 0, the values for the RGB channels are also 0, independent of their unmultiplied values. This loss of data can cause some problems when you perform operations. All BitmapData methods take and return unmultiplied values. The internal pixel representation is converted from premultiplied to unmultiplied before it is returned as a value. During a set operation, the pixel value is premultiplied before the raw image pixel is set.

x - The x position of the pixel.

y - The y position of the pixel.

getPixel32(x, y)

Returns an ARGB color value that contains alpha channel data and RGB data. This method is similar to the getPixel() method, which returns an RGB color without alpha channel data. If the(x, y) coordinates are outside the bounds of the image, 0 is returned.

All pixels in a BitmapData object are stored as premultiplied color values. A premultiplied image pixel has the red, green, and blue color channel values already multiplied by the alpha data. For example, if the alpha value is 0, the values for the RGB channels are also 0, independent of their unmultiplied values. This loss of data can cause some problems when you perform operations. All BitmapData methods take and return unmultiplied values. The internal pixel representation is converted from premultiplied to unmultiplied before it is returned as a value. During a set operation, the pixel value is premultiplied before the raw image pixel is set.

x - The x position of the pixel.

y - The y position of the pixel.

getPixels(rect)

Generates a byte array from a rectangular region of pixel data. Writes an unsigned integer(a 32-bit unmultiplied pixel value) for each pixel into the byte array.

Returns a ByteArray representing the pixels in the given Rectangle.

rect - A rectangular area in the current BitmapData object.

getVector(rect)

Generates a vector array from a rectangular region of pixel data. Returns a vector array of unsigned integers(a 32-bit unmultiplied pixel value) for the specified rectangle.

Returns a vector array representing the given Rectangle.

rect - A rectangular area in the current BitmapData object.

noise(randomSeed, low, high, channelOptions, grayScale)

Fills an image with pixels representing random noise.

randomSeed - The random seed number to use. If you keep all other parameters the same, you can generate different pseudo-random results by varying the random seed value. The noise function is a mapping function, not a true random-number generation function, so it creates the same results each time from the same random seed.

low - The lowest value to generate for each channel(0 to 255) Default recommended value is 0. 

high - The highest value to generate for each channel(0 to 255). Default recommended value is 255. 

channelOptions - A number that can be a combination of any of the four color channel values (BitmapDataChannel.RED, BitmapDataChannel.BLUE, BitmapDataChannel.GREEN, and BitmapDataChannel.ALPHA). You can use the logical OR operator to combine channel values. Default recommended value is 7. 

grayScale - A Boolean value. If the value is true, a grayscale image is created by setting all of the color channels to the same value. The alpha channel selection is not affected by setting this parameter to true. Default recommended value is false. 

save(inFilename, inQuality)

Save BitmapData to image file (jpg or png) with different quality

inFilename - String, image file name with extensions: jpg, jpeg, png. Any other extension will be accepted as png

inQuality - Float, Quality, Default = 0.9

scroll(x, y) 

Scrolls an image by a certain(x, y) pixel amount. Edge regions outside the scrolling area are left unchanged.

x - The amount by which to scroll horizontally.

y - The amount by which to scroll vertically.

setData(dataHandle, inPixelFormat, dataOffset, dataStride, expand)

Set the pixels from a (region) of a byte buffer of given pixel format.

Pixel conversion between non-float types will take place (eg, pfLuma -> pfRGB)

dataHandle - ByteArray  

inPixelFormat - PixelFormat, Default = -1 (None),

dataOffset - Data offset, Default = 0, 

dataStride - Data stride, Default = 0, 

expand - Expand, Default = 1

setPixel(x, y, color)

Sets a single pixel of a BitmapData object. The current alpha channel value of the image pixel is preserved during this operation. The value of the RGB color parameter is treated as an unmultiplied color value.

x - The x position of the pixel whose value changes.

y - The y position of the pixel whose value changes.

color - The resulting RGB color for the pixel.

setPixel32(x, y, color)

Sets the color and alpha transparency values of a single pixel of a BitmapData object. This method is similar to the setPixel() method; the main difference is that the setPixel32() method takes an ARGB color value that contains alpha channel information.

All pixels in a BitmapData object are stored as premultiplied color values. A premultiplied image pixel has the red, green, and blue color channel values already multiplied by the alpha data. For example, if the alpha value is 0, the values for the RGB channels are also 0, independent of their unmultiplied values. This loss of data can cause some problems when you perform operations. All BitmapData methods take and return unmultiplied values. The internal pixel representation is converted from premultiplied to unmultiplied before it is returned as a value. During a set operation, the pixel value is premultiplied before the raw image pixel is set.

x - The x position of the pixel whose value changes.

y - The y position of the pixel whose value changes.

color - The resulting ARGB color for the pixel. If the bitmap is opaque(not transparent), the alpha transparency portion of this color value is ignored.

setPixels(rect, inputByteArray)

Converts a byte array into a rectangular region of pixel data. For each pixel, the ByteArray.readUnsignedInt() method is called and the return value is written into the pixel. If the byte array ends before the full rectangle is written, the function returns. The data in the byte array is expected to be 32-bit ARGB pixel values. No seeking is performed on the byte array before or after the pixels are read.

rect - Specifies the rectangular region of the BitmapData object.

inputByteArray - A ByteArray object that consists of 32-bit unmultiplied pixel values to be used in the rectangular region.

setVector(rect, inputVector)

Converts a vector array inputVector into a rectangular region of pixel data. For each pixel, a vector element is read and written into the BitmapData pixel. The data in the vector is expected to be 32-bit ARGB pixel values.

rect - Specifies the rectangular region of the BitmapData object.

inputVector - vector array with 32-bit ARGB pixels

threshold(sourceBitmapData, sourceRect, destPoint, operation, threshold, color, mask, copySource)

Tests pixel values in an image against a specified threshold and sets pixels that pass the test to new color values. 

Returns number of pixels that were changed.

sourceBitmapData - The input bitmap image to use. The source image can be a different BitmapData object or it can refer to the current BitmapData 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 BitmapData 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 recommended value is 0x00000000. 

mask - The mask to use to isolate a color component. Default recommended value is 0xFFFFFFFF

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. Default recommended value is false

Lib.Media.Display.BitmapData.createPremultiplied(width, height, inArgb)

Creates BitmapData

width - Int, BitmapData width

height - Int, BitmapData height

inArgb - Int, Default value 0

Lib.Media.Display.BitmapData.createGrey(width, height, inLuma)

Creates BitmapData

width - Int, BitmapData width

height - Int, BitmapData height

inLuma - Int

Lib.Media.Display.BitmapData.createAlpha(width, height,inAlpha)

Creates BitmapData

width - Int, BitmapData width

height - Int, BitmapData height

inAlpha - Int, Default value 0

Lib.Media.Display.BitmapData.createUInt16(width, height)

Creates BitmapData

width - Int, BitmapData width

height - Int, BitmapData height

Lib.Media.Display.BitmapData.createUInt32(width, height)

Creates BitmapData

width - Int, BitmapData width

height - Int, BitmapData height

Lib.Media.Display.BitmapData.load(inFilename, format)

Loads BitmapData from file

inFilename - String, image file name, 

format - PixelFormat, Default = -1 (None)