Prima::Image - Bitmap routines


   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;

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

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

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

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

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


Prima::Image, Prima::Icon and Prima::DeviceBitmap are classes for bitmap handling, including 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 contains a transparency mask along with the regular data.


Images usually are represented as a memory area, where pixel data are stored row-wise. The Prima toolkit is no exception, however, it does not assume that the 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 the different needs, but can be easily converted to each other, with 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 number of conversion and scaling functions. The Prima::DeviceBitmap class has almost none of additional functionality, and is targeted to efficient graphic input and output.

Note: If you're looking for information how to display an image, this is not the manual page. Look either at Prima::ImageViewer, or use put_image / stretch_image ( Prima::Drawable ) inside your widget's onPaint.

Graphic input and output

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

When an object enters the enabled state, it serves as a canvas, and all Prima::Drawable operations can be performed on it. When the object is back to the disabled state, the graphic information is stored into the object associated memory, in the pixel format, supported by the toolkit. This information can be visualized by using one of Prima::Drawable::put_image group methods. If the object enters the enabled state again, the graphic information is presented as an initial state of a bitmap.

It must be noted, that if an implicit conversion takes place after an object enters and before it leaves the enabled state, as it is with Prima::Image and Prima::Icon, the bitmap is converted to the system pixel format. During such conversion some information can be lost, due to down-sampling, and there is no way to preserve the information. This does not happen with Prima::DeviceBitmap.

Image objects can be drawn upon images, as well as on the screen and Prima::Widget objects. This operation is performed via one of Prima::Drawable::put_image group methods ( see Prima::Drawable), and can be called with the image object disregarding the paint state. The following code illustrates the dualism of an image object, where it can serve both as a drawing surface and as a drawing tool:

    my $a = Prima::Image-> create( 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;

It must be noted, that put_image, stretch_image and put_image_indirect only allow Prima::Image descendants to be passed as a source image object. This functionality does not imply that the image is internally switched to the paint-enabled state and back; on the contrary, the painting is performed without switching and using only Prima's own code, without using the system's graphical layer.

Another special case is a 1-bit ( monochrome ) DeviceBitmap. When it is drawn upon a drawable with bit depth greater than 1, the drawable's color and backColor properties are used to reflect 1 and 0 bits, respectively. On a 1-bit drawable this does not happen, and the color properties are not used.

File input and output

Depending on the toolkit configuration, images can be read and written in different formats. This functionality in accessible via load() and save() methods. Prima::image-load is dedicated to the description of loading and saving parameters, that can be passed to the 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 format etc. In this document, 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 occurred or an unknown image format was used.

When an image is loaded, the old bitmap memory content is discarded, and the image attributes are changed accordingly to the loaded image. Along with these, an image palette is loaded, if available, and a pixel format is assigned, closest or identical to the pixel format in the image file.

Pixel formats

Prima::Image supports a number of pixel formats, governed by the ::type property. It is reflected by an integer value, a combination of im::XXX constants. The whole set of pixel formats is represented by colored formats, like, 16-color, 256-color and 16M-color, and by gray-scale formats, mapped to C data types - unsigned char, unsigned short, unsigned long, float and double. The gray-scale formats are further subdivided to real-number formats and complex-number format; the last ones are represented by two real values per pixel, containing the real and the imaginary values.

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

The conversions can be performed between any of the supported formats ( to do so, ::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 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, by 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 end_paint() call, and reverts it to its previous pixel format.

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

Another special case of conversion is a conversion with a palette. The following calls,

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


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

produce different results, but none of these takes into account eventual palette remapping, because ::palette property does not change bitmap pixel data, but overwrites palette information. A proper call syntax here would be

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

This call produces also palette pixel mapping. This syntax is most powerful when conversion is set to those algorithms that can take in the account the existing image pixels, to produce an optimized palette. These are ict::Optimized ( by default ) and ict::Posterization. This syntax not only allows remapping or downsampling to a predefined colors set, but also can be used to limit palette size to a particular number, without knowing the actual values of the final color palette. For example, for an 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 converts to a 8-bit format.

Instead of palette property, colormap can also be used.

Data access

The pixel values can be accessed in Prima::Drawable style, via ::pixel property. However, Prima::Image introduces several helper functions on its own.

The ::data property is used to set or retrieve a scalar representation of bitmap 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.

This is the line size for the data as lined up internally in memory, however ::data should not necessarily should be aligned like this, and can be accompanied with a write-only flag 'lineSize' if 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 the farthest away from the memory start; this is consistent with general Y-axis orientation in Prima drawable terminology, but might be inconvenient when importing data 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 the 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 modification with the pixels, returned by ::data, it is not advisable unless the speed does not matter. Standalone PDL package with help of PDL::PrimaImage package, and Prima-derived IPA package provide routines for data and image analysis. Also, Prima::Image::Magick connects ImageMagick with Prima. Prima::Image itself provides only the simplest statistic information, namely: lowest and highest pixel values, pixel sum, sum of square pixels, mean, variance, and standard deviation.

Standalone usage

Some of image functionality can be used standalone, with all other parts of the toolkit being uninitialized. The functionality is limited to loading and saving files, and reading and writing pixels (outside begin_paint only). All other calls are ignored. Example:

   my $i = Prima::Image->new( size => [5,5]);

This feature is useful in non-interactive programs, running in environments with no GUI access, a cgi-script with no access to X11 display, for example. Normally, Prima fails to start in such situations, but can be told not to initialize its GUI part by explicitly operating system-dependent options. To do so, invoke

  use Prima::noX11;

in the beginning of your program. See Prima::noX11 for more.

Generally the standalone methods support all the OS-specific functions (i.e. color, region, etc), plus the primitives and put_image methods support drawing using Porter-Duff operators from rop property (i e rop::SrcOver and above).

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


Prima::Icon inherits all properties of Prima::Image, and it also provides a transparency mask of either 1 or 8 bits. This mask can also be loaded and saved into image files, if the format supports transparency information.

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

If an icon is drawn upon a graphic canvas, the image output is constrained to the mask. On raster displays it is typically simulated by a combination of and- and xor- operation modes, therefore attempts to put an icon with ::rop, different from rop::CopyPut, usually fail.


The term layered window is borrowed from Windows world, and means a window with transparency. In Prima, the property layered is used to select this functionality. The call to $::application->get_system_value(sv::LayeredWidgets) can check whether this functionality is available; if not, the property is ignored. By default, widgets can not use layering.

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

put_image / stretch_image functions can operate on surfaces with alpha as source and destination drawables. To address the alpha channel on a drawable with Prima, one has to send either an Prima::Icon with maskType(im::bpp8), or a layered DeviceBitmap to these functions.

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 ways to put a constant alpha value over a rectangle is this, for example:

   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 pre-existing alpha channel, you'll need to call premultiply_alpha, because picture renderer assumes that pixel values are premultiplied.

Even though addressing alpha values of pixels when drawing on 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 8-bit alpha channel (argb icon), any changes to alpha values of pixels will be transferred back to the mask property after end_paint

* Calls to icon function on DeviceBitmap with type dbt::Layered produce identical argb icons. Calls to bitmap 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 rops, rop::Blend (default) and rop::SrcCopy. The former produces 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 internal implementation of put_image and stretch_image functions extends the allowed set of rops when operating on images outside the begin_paint/end_paint brackets. These rops support 12 Porter-Duff operators, some more "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.

See also: examples/


Prima::Image properties

colormap @PALETTE

A color palette, used for representing 1, 4, and 8-bit bitmaps, when an image object is to be visualized. @PALETTE contains individual colors component triplets, in RGB format. For example, black-and-white monochrome image may contain colormap as 0,0xffffff.

See also palette.

conversion TYPE

Selects the type of dithering algorithm to be used for pixel down-sampling. TYPE is one of ict::XXX constants:

   ict::None            - no dithering, with static palette or palette optimized by source palette
   ict::Posterization   - no dithering, with optimized palette by source pixels
   ict::Ordered         - fast 8x8 ordered halftone dithering with static palette
   ict::ErrorDiffusion  - error diffusion dithering with static palette
   ict::Optimized       - error diffusion dithering with optimized palette

As an example, if a 4x4 color image with every pixel set to RGB(32,32,32), converted to a 1-bit image, the following results occur:

   ict::None, ict::Posterization:
     [ 0 0 0 0 ]
     [ 0 0 0 0 ]
     [ 0 0 0 0 ]
     [ 0 0 0 0 ]

     [ 0 0 0 0 ]
     [ 0 0 1 0 ]
     [ 0 0 0 0 ]
     [ 1 0 0 0 ]

   ict::ErrorDiffusion, ict::Ordered:
     [ 0 0 1 0 ]
     [ 0 0 0 1 ]
     [ 0 0 0 0 ]
     [ 0 0 0 0 ]

Values of these constants are made from "ictp::" in Prima::Const and "ictd::" in Prima::Const constants.


Provides access to the bitmap data. On get-call, returns all bitmap pixels, aligned to 4-byte boundary. On set-call, stores the provided data with same alignment. The alignment can be altered by submitting 'lineSize' write-only flag to set call; the ordering of scan lines can be altered by setting 'reverse' write-only flag ( see "Data access" ).

height INTEGER

Manages the vertical dimension of the image data. On set-call, the image data are changed accordingly to the new height, and depending on ::vScaling property, the pixel values are either scaled or truncated.

lineSize INTEGER

A read-only property, returning the length of an image row in bytes, as represented internally in memory. Data returned by ::data property are aligned with ::lineSize bytes per row, and setting ::data expects data aligned with this value, unless lineSize is set together with data to indicate another alignment. See "Data access" for more.


Returns mean value of pixels. Mean value is ::sum of pixel values, divided by number of pixels.

palette [ @PALETTE ]

A color palette, used for representing 1, 4, and 8-bit bitmaps, when an image object is to be visualized. @PALETTE contains individual color component triplets, in BGR format. For example, black-and-white monochrome image may contain palette as [0,0,0,255,255,255].

See also colormap.


Provides per-pixel access to the image data when image object is in disabled paint state.

Pixel values for grayscale 1- and 4- bit images are treated specifically, such that like 8-bit function, values cover range between 0 and 255. F.ex. pixel values for grayscale 1 bit images are 0 and 255, not 0 and 1.

In paint state same as Prima::Drawable::pixel.

preserveType BOOLEAN

If 1, reverts the image type to its old value if an implicit conversion was called during end_paint().


Returns maximum pixel value in the image data.


Returns minimum pixel value in the image data.

scaling INT

Declares the scaling strategy when image is resized. Strategies ist::None through ist::Box are very fast scalers, others not so.

Can be one of ist:::XXX constants:

  ist::None      - image will be either stripped (when downsizing)
                   or padded (when upsizing) with zeros
  ist::Box       - image will be scaled using simple box transform
  ist::BoxX      - columns will behave same as in ist::None,
                   rows will behave same as in ist::Box
  ist::BoxY      - rows will behave same as in ist::None,
                   columns will behave same as in ist::Box
  ist::AND       - when row or columns is to be shrunk, leftover pixels
                   will be AND-end together (for black on white)
                   ( does not work for floating point pixels )
  ist::OR        - when row or columns is to be shrunk, leftover pixels
                   will be OR-end together (for white on black)
                   ( does not work for floating point pixels )
  ist::Triangle  - bilinear interpolation
  ist::Quadratic - 2rd order (quadratic) B-Spline approximation of Gaussian
  ist::Sinc      - sine function
  ist::Hermite   - B-Spline interpolation
  ist::Cubic     - 3rd order (cubic) B-Spline approximation of Gaussian
  ist::Gaussian  - Gaussian transform with gamma=0.5

Note: Resampling scaling algorithms (those greater than ist::Box), when applied to Icons with 1-bit icon mask, will silently convert the mask in 8-bit and apply the same scaling algorithm to it. This will have great smoothing effect on mask edges if the system supports ARGB layering (see "Layering" ).


Manages dimensions of the image. On set-call, the image data are changed accordingly to the new dimensions, and depending on ::scaling property, the pixel values are either scaled or truncated.

stats ( INDEX ) VALUE

Returns one of calculated values, that correspond to INDEX, which is one of the following is::XXX constants:

   is::RangeLo  - minimum pixel value
   is::RangeHi  - maximum pixel value
   is::Mean     - mean value
   is::Variance - variance
   is::StdDev   - standard deviation
   is::Sum      - sum of pixel values
   is::Sum2     - sum of squares of pixel values

The values are re-calculated on request and cached. On set-call VALUE is stored in the cache, and is returned on next get-call. The cached values are discarded every time the image data changes.

These values are also accessible via set of alias properties: ::rangeLo, ::rangeHi, ::mean, ::variance, ::stdDev, ::sum, ::sum2.


Returns standard deviation of the image data. Standard deviation is the square root of ::variance.


Returns sum of pixel values of the image data


Returns sum of squares of pixel values of the image data

type TYPE

Governs the image pixel format type. TYPE is a combination of im::XXX constants. The constants are collected in groups:

Bit-depth constants provide size of pixel is bits. Their actual value is same as number of bits, so im::bpp1 value is 1, im::bpp4 - 4, etc. The valid constants represent bit depths from 1 to 128:


The following values designate the pixel format category:


Value of im::Color is 0, whereas other category constants represented by unique bit value, so combination of im::RealNumber and im::ComplexNumber is possible.

There also several mnemonic constants defined:

   im::Mono          - im::bpp1
   im::BW            - im::bpp1 | im::GrayScale
   im::16            - im::bpp4
   im::Nibble        - im::bpp4
   im::256           - im::bpp8
   im::RGB           - im::bpp24
   im::Triple        - im::bpp24
   im::Byte          - gray 8-bit unsigned integer
   im::Short         - gray 16-bit unsigned integer
   im::Long          - gray 32-bit unsigned integer
   im::Float         - float
   im::Double        - double
   im::Complex       - dual float
   im::DComplex      - dual double
   im::TrigComplex   - dual float
   im::TrigDComplex  - dual double

Bit depths of float- and double- derived pixel formats depend on a platform.

The groups can be masked out with the mask values:

   im::BPP      - bit depth constants
   im::Category - category constants
   im::FMT      - extra format constants

The extra formats are the pixel formats, not supported by ::type, but recognized within the combined set-call, like

   $image-> set(
      type => im::fmtBGRI,
      data => 'BGR-BGR-',

The data, supplied with the extra image format specification will be converted to the closest supported format. Currently, the following extra pixel formats are recognized:


Returns variance of pixel values of the image data. Variance is ::sum2, divided by number of pixels minus square of ::sum of pixel values.


Manages the horizontal dimension of the image data. On set-call, the image data are changed accordingly to the new width, and depending on ::scaling property, the pixel values are either scaled or truncated.

Prima::Icon properties

autoMasking TYPE

Selects whether the mask information should be updated automatically with ::data change or not. Every ::data change is mirrored in ::mask, using TYPE, one of 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 majority of the corner pixels represents a transparent color. Once such color is found, the mask is generated as in 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.


Provides access to the transparency bitmap. On a get-call, returns all bitmap pixels, aligned to 4-byte boundary in 1-bit format. On a set-call, stores the provided transparency data with same alignment. If the SCALAR is an image object, copies its pixels as a new mask.

maskColor COLOR

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

maskIndex INDEX

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

maskLineSize INTEGER

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

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 effect.

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


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

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

Prima::Image methods

bar X1, Y1, X2, Y2

Outside the paint state uses own implementation for drawing a rectangular shape. The following properties are respected: color, backColor, rop, rop2, fillPattern, fillPatternOffset, region. rop2 accepts either rop::CopyPut or rop::NoOper values, to produce either opaque or transparent fill pattern application.

Inside the paint state is identical to Drawable::bar.


Returns newly created Prima::DeviceBitmap instance, with the image dimensions and with the bitmap pixel values copied to.

clear [X1, Y1, X2, Y2]

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

clone %properties

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


Returns array of hashes, each describing the supported image format. If the array is empty, the toolkit was set up so it can not load and save images.

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)'

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


Returns a newly created image object with WIDTH and HEIGHT dimensions, initialized with pixel data from X_OFFSET and Y_OFFSET in the bitmap.

fill_chord, fill_ellipse, fill_sector, flood_fill

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


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


Returns a system handle for an image object.


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

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


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

See Prima::image-load for details.

NB! When loading from streams on win32, mind 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.


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

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


   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 ]

Mirrors the image depending on boolean flag VERTICAL

premultiply_alpha CONSTANT_OR_IMAGE

Applies premultiplication formula to each pixel

   pixel = pixel * alpha / 256

where alpha either is a constant, or a pixel value in an image

put_image, put_image_indirect, stretch_image

Same as 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 explanation of rop:: constants in "Raster operations" in Prima::Drawable.


Performs linear scaling of gray pixel values from range (SRC_LOW - SRC_HIGH) to 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);

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 scaling property ( probably not worth it for functions with support of more than 1 pixel).

Fills empty pixels with optional fill color.

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 on the result.


Stores image data into image file FILENAME or stream FILEGLOB, and returns the success flag. The semantics of save() is extensive, and can be influenced by PARAMETERS hash. If error occurs, $@ variable contains error description string.

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

See Prima::image-load for details.

NB! When saving to streams on win32, mind binmode.

save_stream BASE64_STRING, %OPTIONS

Saves image into a datastream and return it encoded in base64. Unless $OPTIONS{codecID} or $image-{extras}->{codecID}> is set, tries to find the best codec for the job.

Returns encoded content on success, or undef on failure; $@ is set in the latter case.

scanline Y

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

shear X, Y

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

convert_to_icon $MASK_DEPTH, $MASK_TEMPLATE

Creates an icon from image, with $MASK_DEPTH integer (can be either 1 or 8), and $$MASK_TEMPLATE scalar used for newly populate 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 bit. If TYPE is set, uses this type instead.


Creates a new Prima::Region object with the image as the data source.

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

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

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 matrix into series of shear and scale transforms using LDU decomposition; if an interim image is calculated to be too large, fails and returns false.

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

Rotation matrices can be applied too, however, when angles are close to 90 and 270, either interim images become too big, or defects introduced by shearing become too visible. Therefore the method specifically detects for rotation cases, and uses 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 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, the scaling default value is ist::Quadratic .

See also: "uiScaling" in Application

Prima::Image events

Prima::Image-specific events occur only from inside load call, to report image loading progress. Not all codecs (currently JPEG,PNG,TIFF only) are able to 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 image header is read, and image dimensions and pixel type is changed accordingly to accommodate image data.

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


Called whenever image data that cover area designated by X,Y,WIDTH,HEIGHT is acquired. Use load option eventDelay to limit the rate of DataReady event.

Prima::Icon methods

alpha ALPHA <X1, Y1, X2, Y2>

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

combine DATA, MASK

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

create_combined DATA, MASK, %SET

Same as combine, but to be called as constructor, and sets properties in %SET

image %opt

Renders icon graphics on a newly created Prima::Image object instance upon black background. If $opt{background} is given, it is used instead.

maskline Y

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

premultiply_alpha CONSTANT_OR_IMAGE = undef

Applies premultiplication formula to each pixel

   pixel = pixel * alpha / 255

where alpha is the corresponding alpha value for each coordinate. Only applicable when maskType is <im::bpp8>.

rotate, transform

Applies same transformation as in Prima::Image to both color and mask pixels. Ignores fill color, fills with zeros both planes.


Returns two new Prima::Image objects of same dimension. Pixels in the first is are duplicated from ::data storage, in the second - from ::mask storage.

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

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

ui_scale %OPTIONS

Same as ui_scale from Prima::Image, but with few exceptions: It tries to use ist::Quadratic only when the system supports ARGB layering. Otherwise, falls back on ist::Box scaling algorithm, and also limits the zoom factor to integers (2x, 3x etc) only, because when displayed, the smooth-scaled color plane will not match mask plane downgraded to 0/1 mask, and because box-scaling with non-integer zooms looks ugly.

Prima::DeviceBitmap methods


Returns a duplicate of the object, a newly created Prima::DeviceBitmap, with all information copied to it. Does not preserve graphical properties (color etc).


Returns a newly created Prima::Icon object instance, with the pixel information copied from the object. If the bitmap is layered, returns icons with maskType set to im::bpp8.


Returns a newly created Prima::Image object instance, with the pixel information copied from the object.


Returns a system handle for a system bitmap object.


Dmitry Karasik, <>.


Prima, Prima::Drawable, Prima::image-load, Prima::codecs.

PDL, PDL::PrimaImage, IPA

ImageMagick, Prima::Image::Magick