NAME

Prima::Image - 2-D graphic interface for images

SYNOPSIS

use Prima qw(Application);

# create a new image from scratch
my $i = Prima::Image-> new(
   width => 32,
   height => 32,
   type   => im::BW, # same as im::bpp1 | im::GrayScale
);

# draw something
$i-> begin_paint;
$i-> color( cl::White);
$i-> ellipse( 5, 5, 10, 10);
$i-> end_paint;

# resize
$i-> size( 64, 64);

# file operations
$i-> load('a.gif') or die "Error loading:$@\n";
$i-> save('a.gif') or die "Error saving:$@\n";

# draw on screen
$::application-> begin_paint;

# the color image is drawn as specified by its palette
$::application-> put_image( 100, 100, $i);

# a bitmap is drawn as specified by the colors of the destination device
$::application-> set( color => cl::Red, backColor => cl::Green);
$::application-> put_image( 200, 100, $i-> bitmap);

DESCRIPTION

Prima::Image, Prima::Icon, and Prima::DeviceBitmap are the classes for bitmap handling, file, and graphic input and output. Prima::Image and Prima::DeviceBitmap are descendants of Prima::Drawable and represent bitmaps, stored in memory. Prima::Icon is a descendant of Prima::Image and also contains a 1-bit transparency mask or an 8-bit alpha channel.

USAGE

Pixel storage is usually a contiguous memory area, where scanlines of pixels are stored row-wise. The Prima toolkit is no exception, however, it does not assume that the underlying GUI system uses the same memory format. The implicit conversion routines are called when Prima::Image is about to be drawn onto the screen, for example. The conversions are not always efficient, therefore the Prima::DeviceBitmap class is introduced to represent a bitmap, stored in the system memory in the system pixel format. These two basic classes serve different needs but can be easily converted to each other, with the image and bitmap methods. Prima::Image is a more general bitmap representation, capable of file and graphic input and output, plus it is supplied with a set of conversion and scaling functions. The Prima::DeviceBitmap class has almost none of the additional functionality and is used for efficient graphic input and output.

Note: If you're looking for information on how to display an image, you may want to read first Prima::ImageViewer manual page, or use put_image / stretch_image ( Prima::Drawable ) inside your widget's onPaint callback.

Graphic input and output

As descendants of Prima::Drawable, all Prima::Image, Prima::Icon, and Prima::DeviceBitmap objects are also subject to three-state painting mode - normal ( disabled ), painting ( enabled ), and informational. Prima::DeviceBitmap, however, exists only in the enabled state, and cannot be switched to the other two.

When an image enters the enabled state, it can be used as a drawing canvas, so that all Prima::Drawable operations can be performed on it. When the image is back in the disabled state, the canvas pixels are copied back to the object- associated memory, in the pixel format supported by the toolkit. When the object enters the enabled state again, the pixels are copied to the system bitmap memory, in the pixel format supported by the system. In case the system pixel representation is less precise than Prima's, f ex when drawing on a 24-RGB image when the system has only 8-bit paletted display, then some pixel information will be lost in the process.

Image objects can be drawn on other images and device bitmaps, as well as on the screen and Prima::Widget objects. These operations are performed via one of the Prima::Drawable::put_image group methods ( see Prima::Drawable) and can be called with the image object in any paint state. The following code illustrates the dualism of the image object, where it can serve both as the drawing target and the drawing source:

my $a = Prima::Image-> new( width => 100, height => 100, type => im::RGB);
$a-> begin_paint;
$a-> clear;
$a-> color( cl::Green);
$a-> fill_ellipse( 50, 50, 30, 30);
$a-> end_paint;
$a-> rop( rop::XorPut);
$a-> put_image( 10, 10, $a);
$::application-> begin_paint;
$::application-> put_image( 0, 0, $a);
$::application-> end_paint;

A special case is a 1-bit ( monochrome ) DeviceBitmap. When it is drawn on a drawable with a bit depth greater than 1, the drawable's color and backColor properties are used to reflect the source's 1 and 0 bits, respectively.

File input and output

Depending on the toolkit configuration, images can be read and written in different file formats. This functionality is accessible via the load() and save() methods. Prima::image-load describes the loading and saving parameters that can be passed to these methods, so they can handle different aspects of file format-specific options, such as multi-frame operations, auto conversion when a format does not support a particular pixel type, etc. In this document, the load() and save() methods are illustrated only in their basic, single-frame functionality. When called with no extra parameters, these methods fail only if a disk I/O error occurs or an unsupported image format is used.

Pixel formats

Prima::Image supports several pixel formats, managed by the ::type property. The property is an integer value, a combination of the im::XXX constants. The toolkit defines standard pixel formats for the color formats (16-color, 256-color, 16M-color), and the gray-scale formats, mapped to C data types - unsigned char, unsigned short, unsigned long, float, and double. The gray-scale formats can be based on real-number types and complex-number types; the latter are represented by two real values per pixel, as the real and imaginary values.

A Prima::Image object can also be initialized from other pixel formats, that it does not support internally, but can convert data from. Currently, these are represented by a set of permutations of the 32-bit RGBA format, and 24-bit BGR format. These formats can only be used in conjunction with the ::data property.

The conversions can be performed between any of the supported formats ( to do so, the ::type property is to be set-called ). An image of any of these formats can be drawn on the screen, but if the system can not accept the pixel format ( as it is with the non-integer or complex formats ), the bitmap data are implicitly converted. The conversion does not change the data if the image is about to be drawn; the conversion is performed only when the image is about to be served as a drawing surface. If, for any reason, it is desired that the pixel format is not to be changed, the ::preserveType property must be set to 1. It does not prevent the conversion, but it detects if the image was implicitly converted inside the end_paint() call, and reverts it to the previous pixel format.

There are situations when the pixel format must be changed together with down-sampling the image. One of four down-sampling methods can be selected - without halftoning, 8x8 ordered halftoning, error diffusion, and error diffusion combined with the optimized palette. These can be set to the ::conversion property using one of the ict::XXX constants. When the conversion doesn't incur information loss, the ::conversion property is not used.

Another special case of image downsampling is the conversion with a palette. The following code,

$image-> type( im::bpp4);
$image-> palette( $palette);

and

$image-> palette( $palette);
$image-> type( im::bpp4);

produce different results, but none of these takes into account eventual palette remapping because the ::palette property does not change bitmap pixel data, but overwrites the palette information only. The correct syntax here is

$image-> set(
   palette => $palette,
   type    => im::bpp4,
);

This syntax is most powerful when conversion is set to those algorithms that can take into account the existing image pixels to produce an optimized palette. These are ict::Optimized ( default ) and ict::Posterization. This syntax not only allows remapping or downsampling pixels to a predefined color set but also can be used to limit the palette size to a particular number, without knowing the actual values of the final color palette. For example, for a 24-bit image,

$image-> set( type => im::bpp8, palette => 32);

call would calculate colors in the image, compress them to an optimized palette of 32 cells, and finally convert the image to the 8-bit format using that palette.

Instead of the palette property, the colormap property can also be used.

Data access

The individual pixel values can be accessed in the same way as in the Prima::Drawable class, via the ::pixel property. However, Prima::Image introduces several helper functions on its own.

The ::data property is used to set or retrieve the scalar representation of pixel data. The data are expected to be lined up to a 'line size' margin ( 4-byte boundary ), which is calculated as

$lineSize = int(( $image->width * ( $image-> type & im::BPP) + 31) / 32) * 4;

or returned from the read-only property ::lineSize.

That value is the actual size of a single row of pixels as stored internally in the object memory, however, the input to the ::data property should not necessarily be aligned to this value, it can be accompanied by a write-only flag 'lineSize' if the pixels are aligned differently:

$image-> set( width => 1, height=> 2);
$image-> type( im::RGB);
$image-> set(
   data => 'RGB----RGB----',
   lineSize => 7,
);
print $image-> data, "\n";

output: RGB-RGB-

Internally, Prima contains images in memory so that the first scanline is farthest away from the memory start; this is consistent with general Y-axis orientation in the Prima drawable paradigm but might be inconvenient when importing data that are organized otherwise. Another write-only boolean flag reverse can be set to 1 so data then are treated as if the first scanline of the image is closest to the start of data:

$image-> set( width => 1, height=> 2, type => im::RGB);
$image-> set(
   data => 'RGB-123-',
   reverse => 1,
);
print $image-> data, "\n";

output: RGB-123-

Although it is possible to perform all kinds of calculations and modifications with the pixels returned by the ::data property, it is not advisable unless the speed does not matter. Standalone PDL package with the help of PDL::PrimaImage package, and Prima-derived IPA package provide routines for data and image analysis provide tools for efficient pixel manipulations. Also, Prima::Image::Magick connects ImageMagick with Prima. Prima::Image itself provides only the simplest statistical information, namely: the lowest and highest pixel values, the arithmetic sum of pixel values, the sum of pixel squares, the mean value, variance, and standard deviation.

Standalone usage

All of the drawing functionality can be used standalone, with all other parts of the toolkit being uninitialized. Example:

my $i = Prima::Image->new( size => [5,5]);
$i->color(cl::Red);
$i->bar(0,0,$i->size);
$i->save('1.bmp');

This feature is useful in non-interactive programs, running in environments with no GUI access, for example, a CGI script with no access to an X11 display. Normally, Prima fails to start in such situations but can be told not to initialize the GUI part by explicitly specifying system-dependent options. See Prima::noX11 for more.

Generally, the standalone methods support all the OS-specific functions (i.e. color, region, etc). Also, the graphic primitives and put_image methods support drawing using the Porter-Duff and Photoshop operators that can be specified in the ::rop property by using values from the extended set of the rop::XXX constants, i e rop::SrcOver and above.

All text API is also supported (on unix if Prima is compiled with freetype and fontconfig) and can be used transparently for the caller. The list of available fonts, and their renderings, may differ from the fonts available in the system. For example, where the system may choose to render glyphs with pixel layout optimized for LCD screens, the font query subsystem may not.

See individual methods and properties in API that support standalone usage, and how they differ from system-dependent implementation.

Prima::Icon

The Prima::Icon class inherits all properties of Prima::Image and features the 1-bit transparency mask or the 8-bit alpha channel. The mask can also be loaded and saved into image files if the format supports transparency.

Similar to the Prima::Image::data property, the Prima::Icon::mask property provides access to the binary mask data. The mask can be updated automatically after an icon object is subjected to painting, resizing, or other destructive changes. The auxiliary properties ::autoMasking and ::maskColor/::maskIndex regulate the mask update procedure. For example, if an icon was loaded with the color ( vs. mask ) transparency information, the binary mask will be generated anyway, but it will be also recorded that a particular color is transparent, so eventual conversions can rely on the color value instead.

Drawing using an icon ignores the ::rop value except when its mask is an 8-bit alpha channel, in which case only the Photoshop and Porter-Duff operations are supported. When drawing happens on the system canvas (i e a widget, bitmap, or an image in the enabled state), the only operations supported are rop::Blend and rop::SrcCopy.

Layering

The term layered window is borrowed from the Windows world, and means a window with transparency. In Prima, the property layered is used to request this functionality. The result of the call $::application->get_system_value(sv::LayeredWidgets) can show if this functionality is available; if not, the ::layered property is ignored. By default, widget layering is turned off.

A layered drawable uses an extra alpha channel to for the transparency pixels. Drawing on widgets looks different as well - for example, drawing with black color will make the black pixels fully transparent, while other colors will blend with the underlying background. Prima provides graphics primitives to draw using alpha effects, and some image functions to address layered surfaces.

The put_image and stretch_image functions can operate on layered surfaces both as source and destination drawables. To address the alpha channel on a drawable use either a Prima::Icon with maskType(im::bpp8), or a layered DeviceBitmap.

The corresponding Prima::DeviceBitmap type is dbt::Layered, and is fully compatible with layered widgets in the same fashion as DeviceBitmap with type dbt::Pixmap is fully compatible with normal widgets. One of the ways to put a constant alpha value over a rectangle is, for example, like this:

my $a = Prima::Icon->new(
    width    => 1,
    height   => 1,
    type     => im::RGB,
    maskType => im::bpp8,
    data     => "\0\0\0",
    mask     => chr( $constant_alpha ),
);
$drawable-> stretch_image( 0, 0, 100, 100, $a, rop::SrcOver );

If displaying a picture with a pre-existing alpha channel, you'll need to call premultiply_alpha because the picture renderer assumes that pixel values are premultiplied.

Even though addressing the alpha values of pixels of the layered surfaces is not straightforward, the conversion between images and device bitmaps fully supports alpha pixels. This means that:

* When drawing on an icon with an 8-bit alpha channel (argb icon), any changes to the alpha values of pixels will be transferred back to the mask property after end_paint

* Calls to the icon method on a DeviceBitmap with type dbt::Layered produce identical argb icons. Calls to the bitmap method on argb icons produce identical layered device bitmaps.

* Putting argb icons and layered device bitmap on other drawables yields identical results.

Putting images on argb source surfaces can be only used with two raster operators, rop::Blend (default) and rop::SrcCopy. The former produces the blending effect, while the latter copies alpha bits over to the destination surface. Also, a special rop::AlphaCopy can be used to treat 8-bit grayscale source images as alpha maps, to replace the alpha pixels only.

Prima's internal implementation of the put_image and the stretch_image functions extends the allowed set of raster operators when operating on images outside the begin_paint/end_paint brackets. These operators include 12 Porter-Duff operators, a set of Photoshop operators, and special flags to specify constant alpha values to override the existing alpha channel, if any. See more in "Raster operations" in Prima::Drawable.

Caveats: In Windows, mouse events will not be delivered to the layered widget if the pixel under the mouse pointer is fully transparent.

API

Prima::Image properties

colormap @PALETTE

The color palette is used for representing 1, 4, and 8-bit bitmaps when the image object is to be visualized. @PALETTE contains combined RGB colors as 24-bit integers, 8 bits per component. For example, the colormap values for a typical black-and-white monochrome image can be 0,0xffffff.

Prima::Icon properties

autoMasking TYPE

Selects if the mask information should be updated automatically after ::data is changed. Every ::data change is mirrored in ::mask, using TYPE, one of the am::XXX constants:

am::None           - no mask update performed
am::MaskColor      - mask update based on ::maskColor property
am::MaskIndex      - mask update based on ::maskIndex property
am::Auto           - mask update based on corner pixel values

The ::maskColor color value is used as a transparent color if TYPE is am::MaskColor. The transparency mask generation algorithm turned on by am::Auto checks corner pixel values, assuming that the majority of the corner pixels represent a transparent color. Once such color is found, the mask is generated as in the am::MaskColor case.

::maskIndex is the same as ::maskColor, except that it points to a specific color index in the palette.

When image ::data is stretched, ::mask is stretched accordingly, disregarding the ::autoMasking value.

mask SCALAR

Provides access to the transparency pixels. On the get-call, returns all mask pixels, aligned to a 4-byte boundary. On the set-call, stores the provided transparency data with the same alignment. If the SCALAR is an image object, copies its pixels as a new mask. In that case, copies the pixels as is if the format matches (i e 1-bit icon mask receives 1-bit pixels from the image). or the image data is converted to 8 bits and the mask is converted to the 8-bit format as well.

maskColor COLOR

When the ::autoMasking property is set to am::MaskColor, COLOR is used as the transparency value.

maskIndex INDEX

When the ::autoMasking property is set to am::MaskIndex, the INDEXth color in the current palette is used as the transparency value.

maskLineSize INTEGER

A read-only property, returning the length of the mask row in bytes, as represented internally in memory. Data returned by the ::mask property is aligned with ::maskLineSize bytes per row.

maskPixel ( X_OFFSET, Y_OFFSET ) PIXEL

Provides per-pixel access to the icon mask.

In the disabled mode, gets and sets the value directly from the mask memory. In the paint mode, and if (and only if) the mask depth is 8 bits, queries the alpha pixel value from the system paint surface. Pixel values for all mask depths are treated uniformly, their values range from 0 to 255. For example, values for 1-bit mask pixels are 0 and 255, not 0 and 1.

maskType INTEGER

Is either im::bpp1 (1) or im::bpp8 (8). The latter can be used as a layered (argb) source surface to draw with blending effects.

Note: if a mask with depth 8 is downgraded to depth 1, the image pixels that correspond to alpha values lesser than 255 will be reset to 0.

Prima::DeviceBitmap properties

maskPixel ( X_OFFSET, Y_OFFSET ) PIXEL

Provides per-pixel access to the alpha component of the layered device bitmap. If the bitmap is not layered, the property does not do anything.

type INTEGER

A read-only property that can only be set during creation, reflects whether the system bitmap is a black-and-white 1-bit (dbt::Bitmap), a colored drawable that is compatible with widgets (dbt::Pixmap), or is a colored drawable with an alpha channel that is compatible with layered widgets (dbt::Layered).

The bit depth of the bitmap pixel type can be read via the get_bpp() method; monochrome bitmaps always have a bit depth of 1, and layered bitmaps have a bit depth of 32.

Prima::Image methods

The following properties are same as in the Prima::Drawable clear class, but can be called also outside of the paint state: bar, bar_alpha, bars, chord, clear, ellipse, fill_chord, fill_ellipse, fill_sector, fill_spline, flood_fill, line, lines, pixel, polyline, put_image, put_image_indirect, rectangle, sector, spline, stretch_image.

These drawing primitives are executed using the core Prima functionality, without involving the system backend.

bitmap

Returns a newly created Prima::DeviceBitmap object with the same image dimensions and pixel content.

clone %properties

Creates a copy of the image and applies %properties. An easy way to create a down-sampled copy, for example.

codecs

Returns an array of hashes, each describing the supported image format.

See Prima::image-load for details.

This method can be called without object instance:

perl -MData::Dumper=Dumper -MPrima::noX11 -MPrima -le 'print Dumper(Prima::Image->codecs)'

dup

Returns a copy of the object, a newly created Prima::Image, with all properties copied. Does not preserve the graphical properties though (color etc).

extract X_OFFSET, Y_OFFSET, WIDTH, HEIGHT

Returns a newly created image object with dimensions equal to or less than WIDTH and HEIGHT, initialized with pixel data from X_OFFSET and Y_OFFSET in the bitmap. The dimensions could be less than requested if they extend past the original image dimensions.

Same as the Drawable:: functions but can be used also outside of the paint state.

get_bpp

Returns the bit depth of the pixel format. Same as ::type & im::BPP.

get_handle

Returns the system handle of the image object.

load (FILENAME or FILEGLOB) [ %PARAMETERS ]

Loads an image from file FILENAME or stream FILEGLOB into an object, and returns the success flag. The method features different semantics, depending on the PARAMETERS hash. The load() method can be called either in the context of the existing object, then a boolean success flag is returned. Or in the class context, then a newly created object ( or undef ) is returned. If an error occurs, the $@ variable contains the error string. These two invocation semantics are equivalent:

my $x = Prima::Image-> new();
die "$@" unless $x-> load( ... );

and

my $x = Prima::Image-> load( ... );
die "$@" unless $x;

See Prima::image-load for details and Prima::Image::Loader for more functionality.

Note: when loading from streams on win32, mind the binmode.

load_stream BASE64_STRING, %OPTIONS

Decodes BASE64_STRING and tries to load an image from it. Returns image reference(s) on success, or undef on failure; also $@ is set in this case.

map COLOR

Performs iterative mapping of bitmap pixels, setting every pixel to the ::color property with respect to the ::rop type if a pixel equals to COLOR, and to the ::backColor property with respect to the ::rop2 type otherwise.

The rop::NoOper type can be used for color masking.

Examples:

width => 4, height => 1, data => [ 1, 2, 3, 4]
color => 10, backColor => 20, rop => rop::CopyPut

rop2 => rop::CopyPut
input: map(2) output: [ 20, 10, 20, 20 ]

rop2 => rop::NoOper
input: map(2) output: [ 1, 10, 3, 4 ]

mirror VERTICAL

Mirrors the image either vertically or horizontally depending on the boolean flag VERTICAL

premultiply_alpha CONSTANT_OR_IMAGE

Applies premultiplication formula to each pixel

pixel = int( pixel * alpha / 255 + 0.5 )

where the alpha either is a constant or the corresponding pixel value in the image

put_image, put_image_indirect, stretch_image

Same as the Drawable:: functions but can be used also outside of the paint state.

Extends raster functionality to access alpha channel either using constant alpha values or Prima::Icon as sources. See the explanation of the rop:: constants in "Raster operations" in Prima::Drawable.

resample SRC_LOW, SRC_HIGH, DEST_LOW, DEST_HIGH

Performs linear scaling of gray pixel values from range (SRC_LOW - SRC_HIGH) to the new range (DEST_LOW - DEST_HIGH). Can be used to visualize gray non-8-bit pixel values, by the code:

$image-> resample( $image-> rangeLo, $image-> rangeHi, 0, 255);
$image-> type(im::Byte);

rotate DEGREES [,FILL_COLOR]

Rotates the image. Where the angle is 90, 180, or 270 degrees, fast pixel flipping is used, otherwise fast Paeth rotation is used. Eventual resampling can be controlled by the scaling property ( probably not worth it for functions with a support range of more than 1 pixel).

Fills empty pixels with an optional FILL_COLOR.

The resulting images can be 1 pixel too wide due to horizontal shearing applied twice, where in worst cases 1 pixel from the original image can take 3 horizontal pixels in the resulting image.

save (FILENAME or FILEGLOB), [ %PARAMETERS ]

Stores image data into image file FILENAME or stream FILEGLOB, returns the success flag. The method features different semantics, depending on the PARAMETERS hash. If an error occurs, the $@ variable contains the error string.

Note that when saving to a stream, codecID must be explicitly given in %PARAMETERS.

See Prima::image-load for details and "Prima::Image::Saver" in Prima::Image::Loader for more functionality.

Note: when saving to streams on win32, mind the binmode.

save_stream BASE64_STRING, %OPTIONS

Saves the image into an internal stream. Unless $OPTIONS{codecID} or $image-{extras}->{codecID}> is set, tries to find the best codec for the job. Returns the base64-encoded content on success, or undef on failure; $@ is set in the latter case.

scanline Y

Returns a scanline from the Y offset in the same raw format as data

shear X, Y

Applies the shearing transformation to the image. If the shearing is needed only for one axis, set the shearing factor for the other one to zero.

convert_to_icon $MASK_DEPTH, $MASK_TEMPLATE

Creates an icon from the image, with $MASK_DEPTH integer (can be either 1 or 8), and $$MASK_TEMPLATE scalar used for the newly created mask.

to_colormask COLOR

Creates a new icon with bit depth 24 filled with COLOR, where the mask bits are copied from the caller image object and upgraded to bit depth 8 if needed.

to_rgba TYPE=undef

Creates a new icon with type set to 24 or 8 gray bits and mask type to 8 bits. If TYPE is set, uses that type instead.

to_region

Creates a new Prima::Region object with the image as the data source. The image is expected to be of 1-bit depth.

transform matrix => [a,b,c,d,x,y], [ fill => color ]

Applies a generic 2D transform matrix to the image and fills empty pixels with an optional fill color.

The required option matrix should point to an array of 6 float numbers, where these represent a standard 3x2 matrix for 2D transformation, f ex a Prima::matrix object.

Tries first to split the matrix into a series of shear and scale transforms using the LDU decomposition; if an interim image is calculated to be too large, fails and returns false.

The last two matrix members (X and Y translation) only use the mantissa and ignore the integer part, so setting these f ex to 10.5 will not produce an image 11 pixels larger, but only 1. The translation is thus effectively sub-pixel.

The rotation matrices can be applied too, however, when angles are close to 90 or 270 degrees, either interim images become too big, or defects introduced by the shearing become too visible. Therefore the method specifically detects rotation cases and uses the Paeth rotation algorithm instead, which yields better results. Also, if the angle is detected to be 90, 180, or 270 degrees, fast pixel flipping is used.

Eventual resampling can be controlled by the scaling property.

ui_scale %OPTIONS

Resizes the image with smooth scaling. Understands zoom and scaling options. The zoom default value is the one in $::application->uiScaling, and the scaling default value is ist::Quadratic .

Prima::Image events

Prima::Image-specific events occur only from inside the load call, to report the loading progress. Not all codecs (currently JPEG,PNG,TIFF only) can report the progress to the caller. See "Loading with progress indicator" in Prima::image-load for details, "watch_load_progress" in Prima::ImageViewer and "load" in Prima::Dialog::ImageDialog for suggested use.

HeaderReady EXTRAS

Called whenever the image header is read, and image dimensions and pixel type are changed accordingly to accommodate the image data.

EXTRAS is the hash to be stored later in the {extras} field on the object.

DataReady X, Y, WIDTH, HEIGHT

Called whenever image data that covers an area defined by the X,Y,WIDTH,HEIGHT rectangle is ready. Use the load option eventDelay to limit the rate of DataReady events.

Prima::Icon methods

bar_alpha ALPHA <X1, Y1, X2, Y2>

Same as Drawable::bar_alpha but can be used also outside of the paint state.

combine DATA, MASK

Copies information from the DATA and MASK images into the ::data and the ::mask properties. DATA and MASK are expected to be images of the same dimension.

create_combined DATA, MASK, %SET

Same as combine, except can be called without an object, and applies the %SET hash to the corresponding properties of the newly created icon.

image %opt

Renders the icon on a newly created Prima::Image object instance using the black background. If $opt{background} is given, this color is used instead.

maskline Y

Returns the mask scanline from the Y offset in the same raw format as mask

maskImage

Return an image created from the mask

premultiply_alpha CONSTANT_OR_IMAGE = undef

Applies the premultiplication formula to each pixel

pixel = pixel * alpha / 255

where alpha is the corresponding alpha value for each coordinate. If the value passed is undef, premultiplies the data pixels with the corresponding mask pixels.

Only applicable when maskType is <im::bpp8>.

rotate, transform

Applies the transformation to both color and mask pixels. Ignores fill color, fills with zeros in both planes.

split

Returns two new Prima::Image objects of the same dimension. Pixels in the first image are copied from the ::data storage, and in the second one - from the ::mask storage.

translate matrix => [a,b,c,d,x,y]

Same as the translate method in the Prima::Image class except that it also rotates the mask, and ignores the fill option - all new pixels are filled with zeros.