1pod::Prima::Image(3)  User Contributed Perl Documentation pod::Prima::Image(3)
2
3
4

NAME

6       Prima::Image - Bitmap routines
7

SYNOPSIS

9          use Prima qw(Application);
10
11          # create a new image from scratch
12          my $i = Prima::Image-> new(
13             width => 32,
14             height => 32,
15             type   => im::BW, # same as im::bpp1 | im::GrayScale
16          );
17
18          # draw something
19          $i-> begin_paint;
20          $i-> color( cl::White);
21          $i-> ellipse( 5, 5, 10, 10);
22          $i-> end_paint;
23
24          # mangle
25          $i-> size( 64, 64);
26
27          # file operations
28          $i-> save('a.gif') or die "Error saving:$@\n";
29          $i-> load('a.gif') or die "Error loading:$@\n";
30
31          # draw on screen
32          $::application-> begin_paint;
33
34          # an image is drawn as specified by its palette
35          $::application-> put_image( 100, 100, $i);
36
37          # a bitmap is drawn as specified by destination device colors
38          $::application-> set( color => cl::Red, backColor => cl::Green);
39          $::application-> put_image( 200, 100, $i-> bitmap);
40

DESCRIPTION

42       Prima::Image, Prima::Icon and Prima::DeviceBitmap are classes for
43       bitmap handling, including file and graphic input and output.
44       Prima::Image and Prima::DeviceBitmap are descendants of Prima::Drawable
45       and represent bitmaps, stored in memory.  Prima::Icon is a descendant
46       of Prima::Image and contains a transparency mask along with the regular
47       data.
48

USAGE

50       Images usually are represented as a memory area, where pixel data are
51       stored row-wise. The Prima toolkit is no exception, however, it does
52       not assume that the GUI system uses the same memory format.  The
53       implicit conversion routines are called when Prima::Image is about to
54       be drawn onto the screen, for example. The conversions are not always
55       efficient, therefore the Prima::DeviceBitmap class is introduced to
56       represent a bitmap, stored in the system memory in the system pixel
57       format. These two basic classes serve the different needs, but can be
58       easily converted to each other, with "image" and "bitmap" methods.
59       Prima::Image is a more general bitmap representation, capable of file
60       and graphic input and output, plus it is supplied with number of
61       conversion and scaling functions. The Prima::DeviceBitmap class has
62       almost none of additional functionality, and is targeted to efficient
63       graphic input and output.
64
65       Note: If you're looking for information how to display an image, this
66       is not the manual page. Look either at Prima::ImageViewer, or use
67       "put_image" / "stretch_image" ( Prima::Drawable ) inside your widget's
68       onPaint.
69
70   Graphic input and output
71       As descendants of Prima::Drawable, all Prima::Image, Prima::Icon and
72       Prima::DeviceBitmap objects are subject to three-state painting mode -
73       normal ( disabled ), painting ( enabled ) and informational.
74       Prima::DeviceBitmap is, however, exists only in the enabled state, and
75       can not be switched to the other two.
76
77       When an object enters the enabled state, it serves as a canvas, and all
78       Prima::Drawable operations can be performed on it. When the object is
79       back to the disabled state, the graphic information is stored into the
80       object associated memory, in the pixel format, supported by the
81       toolkit.  This information can be visualized by using one of
82       "Prima::Drawable::put_image" group methods. If the object enters the
83       enabled state again, the graphic information is presented as an initial
84       state of a bitmap.
85
86       It must be noted, that if an implicit conversion takes place after an
87       object enters and before it leaves the enabled state, as it is with
88       Prima::Image and Prima::Icon, the bitmap is converted to the system
89       pixel format. During such conversion some information can be lost, due
90       to down-sampling, and there is no way to preserve the information. This
91       does not happen with Prima::DeviceBitmap.
92
93       Image objects can be drawn upon images, as well as on the screen and
94       Prima::Widget objects. This operation is performed via one of
95       Prima::Drawable::put_image group methods ( see Prima::Drawable), and
96       can be called with the image object disregarding the paint state. The
97       following code illustrates the dualism of an image object, where it can
98       serve both as a drawing surface and as a drawing tool:
99
100           my $a = Prima::Image-> create( width => 100, height => 100, type => im::RGB);
101           $a-> begin_paint;
102           $a-> clear;
103           $a-> color( cl::Green);
104           $a-> fill_ellipse( 50, 50, 30, 30);
105           $a-> end_paint;
106           $a-> rop( rop::XorPut);
107           $a-> put_image( 10, 10, $a);
108           $::application-> begin_paint;
109           $::application-> put_image( 0, 0, $a);
110           $::application-> end_paint;
111
112       It must be noted, that "put_image", "stretch_image" and
113       "put_image_indirect" only allow "Prima::Image" descendants to be passed
114       as a source image object.  This functionality does not imply that the
115       image is internally switched to the paint-enabled state and back; on
116       the contrary, the painting is performed without switching and using
117       only Prima's own code, without using the system's graphical layer.
118
119       Another special case is a 1-bit ( monochrome ) DeviceBitmap. When it is
120       drawn upon a drawable with bit depth greater than 1, the drawable's
121       color and backColor properties are used to reflect 1 and 0 bits,
122       respectively. On a 1-bit drawable this does not happen, and the color
123       properties are not used.
124
125   File input and output
126       Depending on the toolkit configuration, images can be read and written
127       in different formats. This functionality in accessible via load() and
128       save() methods. Prima::image-load is dedicated to the description of
129       loading and saving parameters, that can be passed to the methods, so
130       they can handle different aspects of file format-specific options, such
131       as multi-frame operations, auto conversion when a format does not
132       support a particular pixel format etc. In this document, load() and
133       save() methods are illustrated only in their basic, single-frame
134       functionality. When called with no extra parameters, these methods fail
135       only if a disk I/O error occurred or an unknown image format was used.
136
137       When an image is loaded, the old bitmap memory content is discarded,
138       and the image attributes are changed accordingly to the loaded image.
139       Along with these, an image palette is loaded, if available, and a pixel
140       format is assigned, closest or identical to the pixel format in the
141       image file.
142
143   Pixel formats
144       Prima::Image supports a number of pixel formats, governed by the
145       "::type" property. It is reflected by an integer value, a combination
146       of "im::XXX" constants. The whole set of pixel formats is represented
147       by colored formats, like, 16-color, 256-color and 16M-color, and by
148       gray-scale formats, mapped to C data types - unsigned char, unsigned
149       short, unsigned long, float and double.  The gray-scale formats are
150       further subdivided to real-number formats and complex-number format;
151       the last ones are represented by two real values per pixel, containing
152       the real and the imaginary values.
153
154       Prima::Image can also be initialized from other formats, that it does
155       not support, but can convert data from. Currently these are represented
156       by a set of permutations of 32-bit RGBA format, and 24-bit BGR format.
157       These formats can only be used in conjunction with "::data" property.
158
159       The conversions can be performed between any of the supported formats (
160       to do so, "::type" property is to be set-called ). An image of any of
161       these formats can be drawn on the screen, but if the system can not
162       accept the pixel format ( as it is with non-integer or complex formats
163       ), the bitmap data are implicitly converted. The conversion does not
164       change the data if the image is about to be drawn; the conversion is
165       performed only when the image is about to be served as a drawing
166       surface. If, by any reason, it is desired that the pixel format is not
167       to be changed, the "::preserveType" property must be set to 1. It does
168       not prevent the conversion, but it detects if the image was implicitly
169       converted inside end_paint() call, and reverts it to its previous pixel
170       format.
171
172       There are situations, when pixel format must be changed together while
173       down-sampling the image. One of four down-sampling methods can be
174       selected - no halftoning, 8x8 ordered halftoning, error diffusion, and
175       error diffusion combined with optimized palette. These can be set to
176       the "::conversion" property with one of "ict::XXX" constants.  When
177       there is no information loss, "::conversion" property is not used.
178
179       Another special case of conversion is a conversion with a palette. The
180       following calls,
181
182         $image-> type( im::bpp4);
183         $image-> palette( $palette);
184
185       and
186
187         $image-> palette( $palette);
188         $image-> type( im::bpp4);
189
190       produce different results, but none of these takes into account
191       eventual palette remapping, because "::palette" property does not
192       change bitmap pixel data, but overwrites palette information. A proper
193       call syntax here would be
194
195         $image-> set(
196            palette => $palette,
197            type    => im::bpp4,
198         );
199
200       This call produces also palette pixel mapping.  This syntax is most
201       powerful when conversion is set to those algorithms that can take in
202       the account the existing image pixels, to produce an optimized palette.
203       These are "ict::Optimized" ( by default ) and "ict::Posterization".
204       This syntax not only allows remapping or downsampling to a predefined
205       colors set, but also can be used to limit palette size to a particular
206       number, without knowing the actual values of the final color palette.
207       For example, for an 24-bit image,
208
209         $image-> set( type => im::bpp8, palette => 32);
210
211       call would calculate colors in the image, compress them to an optimized
212       palette of 32 cells and finally converts to a 8-bit format.
213
214       Instead of "palette" property, "colormap" can also be used.
215
216   Data access
217       The pixel values can be accessed in Prima::Drawable style, via
218       "::pixel" property. However, Prima::Image introduces several helper
219       functions on its own.
220
221       The "::data" property is used to set or retrieve a scalar
222       representation of bitmap data. The data are expected to be lined up to
223       a 'line size' margin ( 4-byte boundary ), which is calculated as
224
225         $lineSize = int(( $image->width * ( $image-> type & im::BPP) + 31) / 32) * 4;
226
227       or returned from the read-only property "::lineSize".
228
229       This is the line size for the data as lined up internally in memory,
230       however "::data" should not necessarily should be aligned like this,
231       and can be accompanied with a write-only flag 'lineSize' if pixels are
232       aligned differently:
233
234         $image-> set( width => 1, height=> 2);
235         $image-> type( im::RGB);
236         $image-> set(
237            data => 'RGB----RGB----',
238            lineSize => 7,
239         );
240         print $image-> data, "\n";
241
242         output: RGB-RGB-
243
244       Internally, Prima contains images in memory so that the first scanline
245       is the farthest away from the memory start; this is consistent with
246       general Y-axis orientation in Prima drawable terminology, but might be
247       inconvenient when importing data organized otherwise. Another write-
248       only boolean flag "reverse" can be set to 1 so data then are treated as
249       if the first scanline of the image is the closest to the start of data:
250
251         $image-> set( width => 1, height=> 2, type => im::RGB);
252         $image-> set(
253            data => 'RGB-123-',
254            reverse => 1,
255         );
256         print $image-> data, "\n";
257
258         output: RGB-123-
259
260       Although it is possible to perform all kinds of calculations and
261       modification with the pixels, returned by "::data", it is not advisable
262       unless the speed does not matter. Standalone PDL package with help of
263       PDL::PrimaImage package, and Prima-derived IPA package provide routines
264       for data and image analysis.  Also, Prima::Image::Magick connects
265       ImageMagick with Prima.  Prima::Image itself provides only the simplest
266       statistic information, namely: lowest and highest pixel values, pixel
267       sum, sum of square pixels, mean, variance, and standard deviation.
268
269   Standalone usage
270       Some of image functionality can be used standalone, with all other
271       parts of the toolkit being uninitialized. The functionality is limited
272       to loading and saving files, and reading and writing pixels (outside
273       begin_paint only).  All other calls are ignored. Example:
274
275          my $i = Prima::Image->new( size => [5,5]);
276          $i->color(cl::Red);
277          $i->bar(0,0,$i->size);
278          $i->save('1.bmp');
279
280       This feature is useful in non-interactive programs, running in
281       environments with no GUI access, a cgi-script with no access to X11
282       display, for example.  Normally, Prima fails to start in such
283       situations, but can be told not to initialize its GUI part by
284       explicitly operating system-dependent options. To do so, invoke
285
286         use Prima::noX11;
287
288       in the beginning of your program. See Prima::noX11 for more.
289
290       Generally the standalone methods support all the OS-specific functions
291       (i.e.  color, region, etc), plus the primitives and "put_image" methods
292       support drawing using Porter-Duff operators from "rop" property (i e
293       rop::SrcOver and above).
294
295       See individual methods and properties in API that support standalone
296       usage, and how they differ from system-dependent implementation.
297
298   Prima::Icon
299       Prima::Icon inherits all properties of Prima::Image, and it also
300       provides a transparency mask of either 1 or 8 bits.  This mask can also
301       be loaded and saved into image files, if the format supports
302       transparency information.
303
304       Similar to Prima::Image::data property, Prima::Icon::mask property
305       provides access to the binary mask data.  The mask can be updated
306       automatically, after an icon object was subject to painting, resizing,
307       or other destructive change.  The auxiliary properties "::autoMasking"
308       and "::maskColor"/"::maskIndex" regulate  mask update procedure. For
309       example, if an icon was loaded with the color ( vs. bitmap )
310       transparency information, the binary mask will be generated anyway, but
311       it will be also recorded that a particular color serves as a
312       transparent indicator, so eventual conversions can rely on the color
313       value, instead of the mask bitmap.
314
315       If an icon is drawn upon a graphic canvas, the image output is
316       constrained to the mask. On raster displays it is typically simulated
317       by a combination of and- and xor- operation modes, therefore attempts
318       to put an icon with "::rop", different from "rop::CopyPut", usually
319       fail.
320
321   Layering
322       The term layered window is borrowed from Windows world, and means a
323       window with transparency. In Prima, the property layered is used to
324       select this functionality. The call to
325       "$::application->get_system_value(sv::LayeredWidgets)" can check
326       whether this functionality is available; if not, the property is
327       ignored.  By default, widgets can not use layering.
328
329       A layered drawable uses an extra alpha channel to designate the
330       transparency.  Drawing on widgets will also look different - for
331       example, drawing with black color will make the black pixels fully
332       transparent, while other colors will blend with the underlying
333       background, but never in full. Prima provides graphics primitives to
334       draw using alpha effects, and some image functions to address the alpha
335       surfaces.
336
337       "put_image" / "stretch_image" functions can operate on surfaces with
338       alpha as source and destination drawables. To address the alpha channel
339       on a drawable with Prima, one has to send either an "Prima::Icon" with
340       maskType(im::bpp8), or a layered "DeviceBitmap" to these functions.
341
342       The corresponding "Prima::DeviceBitmap" type is "dbt::Layered", and is
343       fully compatible with layered widgets in the same fashion as
344       "DeviceBitmap" with type "dbt::Pixmap" is fully compatible with normal
345       widgets. One of ways to put a constant alpha value over a rectangle is
346       this, for example:
347
348          my $a = Prima::Icon->new(
349              width    => 1,
350              height   => 1,
351              type     => im::RGB,
352              maskType => im::bpp8,
353              data     => "\0\0\0",
354              mask     => chr( $constant_alpha ),
355          );
356          $drawable-> stretch_image( 0, 0, 100, 100, $a, rop::SrcOver );
357
358       If displaying a picture with pre-existing alpha channel, you'll need to
359       call premultiply_alpha, because picture renderer assumes that pixel
360       values are premultiplied.
361
362       Even though addressing alpha values of pixels when drawing on layered
363       surfaces is not straightforward, the conversion between images and
364       device bitmaps fully supports alpha pixels. This means that:
365
366       * When drawing on an icon with 8-bit alpha channel (argb icon), any
367       changes to alpha values of pixels will be transferred back to the mask
368       property after "end_paint"
369
370       * Calls to "icon" function on DeviceBitmap with type "dbt::Layered"
371       produce identical argb icons. Calls to "bitmap" on argb icons produce
372       identical layered device bitmaps.
373
374       * Putting argb icons and layered device bitmap on other drawables
375       yields identical results.
376
377       Putting of argb source surfaces can be only used with two rops,
378       "rop::SrcOver" (default) and "rop::SrcCopy". The former produces
379       blending effect, while the latter copies alpha bits over to the
380       destination surface. Prima internal implementation of "put_image" and
381       "stretch_image" functions extends the allowed set of rops when
382       operating on images outside the begin_paint/end_paint brackets. These
383       rops support 12 Porter-Duff operators, some more "photoshop" operators,
384       and special flags to specify constant alpha values to override the
385       existing alpha channel, if any.  See more in "Raster operations" in
386       Prima::Drawable.
387
388       Caveats: In Windows, mouse events will not be delivered to the layered
389       widget if the pixel under the mouse pointer is fully transparent.
390
391       See also: examples/layered.pl.
392

API

394   Prima::Image properties
395       colormap @PALETTE
396           A color palette, used for representing 1, 4, and 8-bit bitmaps,
397           when an image object is to be visualized. @PALETTE contains
398           individual colors component triplets, in RGB format. For example,
399           black-and-white monochrome image may contain colormap as
400           "0,0xffffff".
401
402           See also "palette".
403
404       conversion TYPE
405           Selects the type of dithering algorithm to be used for pixel down-
406           sampling.  TYPE is one of "ict::XXX" constants:
407
408              ict::None            - no dithering, with static palette or palette optimized by source palette
409              ict::Posterization   - no dithering, with optimized palette by source pixels
410              ict::Ordered         - fast 8x8 ordered halftone dithering with static palette
411              ict::ErrorDiffusion  - error diffusion dithering with static palette
412              ict::Optimized       - error diffusion dithering with optimized palette
413
414           As an example, if a 4x4 color image with every pixel set to
415           RGB(32,32,32), converted to a 1-bit image, the following results
416           occur:
417
418              ict::None, ict::Posterization:
419                [ 0 0 0 0 ]
420                [ 0 0 0 0 ]
421                [ 0 0 0 0 ]
422                [ 0 0 0 0 ]
423
424              ict::Ordered:
425                [ 0 0 0 0 ]
426                [ 0 0 1 0 ]
427                [ 0 0 0 0 ]
428                [ 1 0 0 0 ]
429
430              ict::ErrorDiffusion, ict::Ordered:
431                [ 0 0 1 0 ]
432                [ 0 0 0 1 ]
433                [ 0 0 0 0 ]
434                [ 0 0 0 0 ]
435
436           Values of these constants are made from "ictp::" in Prima::Const
437           and "ictd::" in Prima::Const constants.
438
439       data SCALAR
440           Provides access to the bitmap data. On get-call, returns all bitmap
441           pixels, aligned to 4-byte boundary. On set-call, stores the
442           provided data with same alignment. The alignment can be altered by
443           submitting 'lineSize' write-only flag to set call; the ordering of
444           scan lines can be altered by setting 'reverse' write-only flag (
445           see "Data access" ).
446
447       height INTEGER
448           Manages the vertical dimension of the image data.  On set-call, the
449           image data are changed accordingly to the new height, and depending
450           on "::vScaling" property, the pixel values are either scaled or
451           truncated.
452
453       lineSize INTEGER
454           A read-only property, returning the length of an image row in
455           bytes, as represented internally in memory. Data returned by
456           "::data" property are aligned with "::lineSize" bytes per row, and
457           setting "::data" expects data aligned with this value, unless
458           "lineSize" is set together with "data" to indicate another
459           alignment. See "Data access" for more.
460
461       mean
462           Returns mean value of pixels.  Mean value is "::sum" of pixel
463           values, divided by number of pixels.
464
465       palette [ @PALETTE ]
466           A color palette, used for representing 1, 4, and 8-bit bitmaps,
467           when an image object is to be visualized. @PALETTE contains
468           individual color component triplets, in BGR format. For example,
469           black-and-white monochrome image may contain palette as
470           "[0,0,0,255,255,255]".
471
472           See also "colormap".
473
474       pixel ( X_OFFSET, Y_OFFSET ) PIXEL
475           Provides per-pixel access to the image data when image object is in
476           disabled paint state.
477
478           Pixel values for grayscale 1- and 4- bit images are treated
479           specifically, such that like 8-bit function, values cover range
480           between 0 and 255. F.ex. pixel values for grayscale 1 bit images
481           are 0 and 255, not 0 and 1.
482
483           In paint state same as "Prima::Drawable::pixel".
484
485       preserveType BOOLEAN
486           If 1, reverts the image type to its old value if an implicit
487           conversion was called during end_paint().
488
489       rangeHi
490           Returns maximum pixel value in the image data.
491
492       rangeLo
493           Returns minimum pixel value in the image data.
494
495       scaling INT
496           Declares the scaling strategy when image is resized.  Strategies
497           "ist::None" through "ist::Box" are very fast scalers, others not
498           so.
499
500           Can be one of "ist:::XXX" constants:
501
502             ist::None      - image will be either stripped (when downsizing)
503                              or padded (when upsizing) with zeros
504             ist::Box       - image will be scaled using simple box transform
505             ist::BoxX      - columns will behave same as in ist::None,
506                              rows will behave same as in ist::Box
507             ist::BoxY      - rows will behave same as in ist::None,
508                              columns will behave same as in ist::Box
509             ist::AND       - when row or columns is to be shrunk, leftover pixels
510                              will be AND-end together (for black on white)
511                              ( does not work for floating point pixels )
512             ist::OR        - when row or columns is to be shrunk, leftover pixels
513                              will be OR-end together (for white on black)
514                              ( does not work for floating point pixels )
515             ist::Triangle  - bilinear interpolation
516             ist::Quadratic - 2rd order (quadratic) B-Spline approximation of Gaussian
517             ist::Sinc      - sine function
518             ist::Hermite   - B-Spline interpolation
519             ist::Cubic     - 3rd order (cubic) B-Spline approximation of Gaussian
520             ist::Gaussian  - Gaussian transform with gamma=0.5
521
522           Note: Resampling scaling algorithms (those greater than
523           "ist::Box"), when applied to Icons with 1-bit icon mask, will
524           silently convert the mask in 8-bit and apply the same scaling
525           algorithm to it. This will have great smoothing effect on mask
526           edges if the system supports ARGB layering (see "Layering" ).
527
528       size WIDTH, HEIGHT
529           Manages dimensions of the image. On set-call, the image data are
530           changed accordingly to the new dimensions, and depending on
531           "::scaling" property, the pixel values are either scaled or
532           truncated.
533
534       stats ( INDEX ) VALUE
535           Returns one of calculated values, that correspond to INDEX, which
536           is one of the following "is::XXX" constants:
537
538              is::RangeLo  - minimum pixel value
539              is::RangeHi  - maximum pixel value
540              is::Mean     - mean value
541              is::Variance - variance
542              is::StdDev   - standard deviation
543              is::Sum      - sum of pixel values
544              is::Sum2     - sum of squares of pixel values
545
546           The values are re-calculated on request and cached.  On set-call
547           VALUE is stored in the cache, and is returned on next get-call.
548           The cached values are discarded every time the image data changes.
549
550           These values are also accessible via set of alias properties:
551           "::rangeLo", "::rangeHi", "::mean", "::variance", "::stdDev",
552           "::sum", "::sum2".
553
554       stdDev
555           Returns standard deviation of the image data.  Standard deviation
556           is the square root of "::variance".
557
558       sum Returns sum of pixel values of the image data
559
560       sum2
561           Returns sum of squares of pixel values of the image data
562
563       type TYPE
564           Governs the image pixel format type. TYPE is a combination of
565           "im::XXX" constants. The constants are collected in groups:
566
567           Bit-depth constants provide size of pixel is bits. Their actual
568           value is same as number of bits, so "im::bpp1" value is 1,
569           "im::bpp4" - 4, etc. The valid constants represent bit depths from
570           1 to 128:
571
572              im::bpp1
573              im::bpp4
574              im::bpp8
575              im::bpp16
576              im::bpp24
577              im::bpp32
578              im::bpp64
579              im::bpp128
580
581           The following values designate the pixel format category:
582
583              im::Color
584              im::GrayScale
585              im::RealNumber
586              im::ComplexNumber
587              im::TrigComplexNumber
588              im::SignedInt
589
590           Value of "im::Color" is 0, whereas other category constants
591           represented by unique bit value, so combination of "im::RealNumber"
592           and "im::ComplexNumber" is possible.
593
594           There also several mnemonic constants defined:
595
596              im::Mono          - im::bpp1
597              im::BW            - im::bpp1 | im::GrayScale
598              im::16            - im::bpp4
599              im::Nibble        - im::bpp4
600              im::256           - im::bpp8
601              im::RGB           - im::bpp24
602              im::Triple        - im::bpp24
603              im::Byte          - gray 8-bit unsigned integer
604              im::Short         - gray 16-bit unsigned integer
605              im::Long          - gray 32-bit unsigned integer
606              im::Float         - float
607              im::Double        - double
608              im::Complex       - dual float
609              im::DComplex      - dual double
610              im::TrigComplex   - dual float
611              im::TrigDComplex  - dual double
612
613           Bit depths of float- and double- derived pixel formats depend on a
614           platform.
615
616           The groups can be masked out with the mask values:
617
618              im::BPP      - bit depth constants
619              im::Category - category constants
620              im::FMT      - extra format constants
621
622           The extra formats are the pixel formats, not supported by "::type",
623           but recognized within the combined set-call, like
624
625              $image-> set(
626                 type => im::fmtBGRI,
627                 data => 'BGR-BGR-',
628              );
629
630           The data, supplied with the extra image format specification will
631           be converted to the closest supported format. Currently, the
632           following extra pixel formats are recognized:
633
634              im::fmtBGR
635              im::fmtRGBI
636              im::fmtIRGB
637              im::fmtBGRI
638              im::fmtIBGR
639
640       variance
641           Returns variance of pixel values of the image data.  Variance is
642           "::sum2", divided by number of pixels minus square of "::sum" of
643           pixel values.
644
645       width INTEGER
646           Manages the horizontal dimension of the image data.  On set-call,
647           the image data are changed accordingly to the new width, and
648           depending on "::scaling" property, the pixel values are either
649           scaled or truncated.
650
651   Prima::Icon properties
652       autoMasking TYPE
653           Selects whether the mask information should be updated
654           automatically with "::data" change or not. Every "::data" change is
655           mirrored in "::mask", using TYPE, one of "am::XXX" constants:
656
657              am::None           - no mask update performed
658              am::MaskColor      - mask update based on ::maskColor property
659              am::MaskIndex      - mask update based on ::maskIndex property
660              am::Auto           - mask update based on corner pixel values
661
662           The "::maskColor" color value is used as a transparent color if
663           TYPE is "am::MaskColor". The transparency mask generation
664           algorithm, turned on by "am::Auto" checks corner pixel values,
665           assuming that majority of the corner pixels represents a
666           transparent color. Once such color is found, the mask is generated
667           as in "am::MaskColor" case.
668
669           "::maskIndex" is the same as "::maskColor", except that it points
670           to a specific color index in the palette.
671
672           When image "::data" is stretched, "::mask" is stretched
673           accordingly, disregarding the "::autoMasking" value.
674
675       mask SCALAR
676           Provides access to the transparency bitmap. On get-call, returns
677           all bitmap pixels, aligned to 4-byte boundary in 1-bit format. On
678           set-call, stores the provided transparency data with same
679           alignment.
680
681       maskColor COLOR
682           When "::autoMasking" set to "am::MaskColor", COLOR is used as a
683           transparency value.
684
685       maskIndex INDEX
686           When "::autoMasking" set to "am::MaskIndex", INDEXth color in the
687           current palette is used as a transparency value.
688
689       maskLineSize INTEGER
690           A read-only property, returning the length of mask row in bytes, as
691           represented internally in memory. Data returned by "::mask"
692           property are aligned with "::maskLineSize" bytes per row.
693
694       maskType INTEGER
695           Is either "im::bpp1" (1) or "im::bpp8" (8). The latter can be used
696           as a layered (argb) source surface to draw with blending effect.
697
698   Prima::DeviceBitmap properties
699       type INTEGER
700           A read-only property, that can only be set during creation,
701           reflects whether the system bitmap is black-and-white 1-bit
702           ("dbt::Bitmap"), is colored and compatible with widgets
703           ("dbt::Pixmap"), or is colored with alpha channel and compatible
704           with layered widgets ("dbt::Layered").
705
706           The color depth of a bitmap can be read via get_bpp() method;
707           monochrome bitmaps always have bit depth of 1, layered bitmaps have
708           bit depth of 32.
709
710   Prima::Image methods
711       bar X1, Y1, X2, Y2
712           Outside the paint state uses own implementation for drawing a
713           rectangular shape.  The following properties are respected:
714           "color", "backColor", "rop", "rop2", "fillPattern",
715           "fillPatternOffset", "region". "rop2" accepts either "rop::CopyPut"
716           or "rop::NoOper" values, to produce either opaque or transparent
717           fill pattern application.
718
719           Inside the paint state is identical to "Drawable::bar".
720
721       bitmap
722           Returns newly created Prima::DeviceBitmap instance, with the image
723           dimensions and with the bitmap pixel values copied to.
724
725       clear [X1, Y1, X2, Y2]
726           Same as "Drawable::clear" but can be used also outside of the paint
727           state.
728
729       clone %properties
730           Creates a copy of the image and applies %properties. An easy way to
731           create a down-sampled copy, for example.
732
733       codecs
734           Returns array of hashes, each describing the supported image
735           format. If the array is empty, the toolkit was set up so it can not
736           load and save images.
737
738           See Prima::image-load for details.
739
740           This method can be called without object instance:
741
742              perl -MData::Dumper=Dumper -MPrima::noX11 -MPrima -le 'print Dumper(Prima::Image->codecs)'
743
744       dup Returns a duplicate of the object, a newly created Prima::Image,
745           with all information copied to it. Does not preserve graphical
746           properties (color etc).
747
748       extract X_OFFSET, Y_OFFSET, WIDTH, HEIGHT
749           Returns a newly created image object with WIDTH and HEIGHT
750           dimensions, initialized with pixel data from X_OFFSET and Y_OFFSET
751           in the bitmap.
752
753       fill_chord, fill_ellipse, fill_sector, flood_fill
754           Same as "Drawable::" functions but can be used also outside of the
755           paint state.
756
757       get_bpp
758           Returns the bit depth of the pixel format. Same as "::type &
759           im::BPP".
760
761       get_handle
762           Returns a system handle for an image object.
763
764       load (FILENAME or FILEGLOB) [ %PARAMETERS ]
765           Loads image from file FILENAME or stream FILEGLOB into an object,
766           and returns the success flag.  The semantics of load() is
767           extensive, and can be influenced by PARAMETERS hash. load() can be
768           called either in a context of an existing object, then a boolean
769           success flag is returned, or in a class context, then a newly
770           created object ( or "undef" ) is returned. If an error occurs, $@
771           variable contains the error description string. These two
772           invocation semantics are equivalent:
773
774              my $x = Prima::Image-> create();
775              die "$@" unless $x-> load( ... );
776
777           and
778
779              my $x = Prima::Image-> load( ... );
780              die "$@" unless $x;
781
782           See Prima::image-load for details.
783
784           NB! When loading from streams on win32, mind "binmode".
785
786       load_stream BASE64_STRING, %OPTIONS
787           Decodes BASE64_STRING and tries to load an image from it.  Returns
788           image reference(s) on success, or "undef" on failure; also $@ is
789           set in this case.
790
791       map COLOR
792           Performs iterative mapping of bitmap pixels, setting every pixel to
793           "::color" property with respect to "::rop" type if a pixel equals
794           to COLOR, and to "::backColor" property with respect to "::rop2"
795           type otherwise.
796
797           "rop::NoOper" type can be used for color masking.
798
799           Examples:
800
801              width => 4, height => 1, data => [ 1, 2, 3, 4]
802              color => 10, backColor => 20, rop => rop::CopyPut
803
804              rop2 => rop::CopyPut
805              input: map(2) output: [ 20, 10, 20, 20 ]
806
807              rop2 => rop::NoOper
808              input: map(2) output: [ 1, 10, 3, 4 ]
809
810       mirror VERTICAL
811           Mirrors the image depending on boolean flag VERTICAL
812
813       premultiply_alpha CONSTANT_OR_IMAGE
814           Applies premultiplication formula to each pixel
815
816              pixel = pixel * alpha / 256
817
818           where alpha either is a constant, or a pixel value in an image
819
820       put_image, put_image_indirect, stretch_image
821           Same as "Drawable::" functions but can be used also outside of the
822           paint state.
823
824           Extends raster functionality to access alpha channel either using
825           constant alpha values or "Prima::Icon" as sources. See explanation
826           of "rop::" constants in "Raster operations" in Prima::Drawable.
827
828       resample SRC_LOW, SRC_HIGH, DEST_LOW, DEST_HIGH
829           Performs linear scaling of gray pixel values from range (SRC_LOW -
830           SRC_HIGH) to range (DEST_LOW - DEST_HIGH). Can be used to visualize
831           gray non-8 bit pixel values, by the code:
832
833              $image-> resample( $image-> rangeLo, $image-> rangeHi, 0, 255);
834
835       rotate DEGREES [,FILL_COLOR]
836           Rotates the image. Where the angle is 90, 180, or 270 degrees, fast
837           pixel flipping is used, otherwise fast Paeth rotation is used.
838           Eventual resampling can be controlled by "scaling" property (
839           probably not worth it for functions with support of more than 1
840           pixel).
841
842           Fills empty pixels with optional fill color.
843
844           Resulting images can be 1 pixel too wide due to horizontal shearing
845           applied twice, where in worst cases 1 pixel from the original image
846           can take 3 horizontal pixels on the result.
847
848       save (FILENAME or FILEGLOB), [ %PARAMETERS ]
849           Stores image data into image file FILENAME or stream FILEGLOB, and
850           returns the success flag.  The semantics of save() is extensive,
851           and can be influenced by PARAMETERS hash. If error occurs, $@
852           variable contains error description string.
853
854           Note that when saving to a stream, "codecID" must be explicitly
855           given in %PARAMETERS.
856
857           See Prima::image-load for details.
858
859           NB! When saving to streams on win32, mind "binmode".
860
861       save_stream BASE64_STRING, %OPTIONS
862           Saves image into a datastream and return it encoded in base64.
863           Unless $OPTIONS{codecID} or "$image-"{extras}->{codecID}> is set,
864           tries to find the best codec for the job.
865
866           Returns encoded content on success, or "undef" on failure; $@ is
867           set in the latter case.
868
869       scanline Y
870           Returns a scanline from Y in the same raw format as "data"
871
872       shear X, Y
873           Applies shearing to the image. If the shearing is needed only for
874           one axis, set shear factor for the other one to zero.
875
876       convert_to_icon $MASK_DEPTH, $MASK_TEMPLATE
877           Creates an icon from image, with $MASK_DEPTH integer (can be either
878           1 or 8), and $$MASK_TEMPLATE scalar used for newly populate mask.
879
880       to_rgba TYPE=undef
881           Creates a new icon with type set to 24 or 8 gray bits and mask type
882           to 8 bit.  If TYPE is set, uses this type instead.
883
884       to_region
885           Creates a new Prima::Region object with the image as the data
886           source.
887
888       transform matrix => [a,b,c,d,x,y], [ fill => color ]
889           Applies generic 2D transform matrix to the image, fills empty
890           pixels with optional fill color.
891
892           Required option "matrix" should point to an array of 6 float
893           numbers, where these represent a standard 3x2 matrix for 2D
894           transformation, f ex a "Prima::matrix" object.
895
896           Tries first to split matrix into series of shear and scale
897           transforms using LDU decomposition; if an interim image is
898           calculated to be too large, fails and returns "false".
899
900           The last two members (X and Y translation) only use mantissa and
901           ignore the rest, so setting them f ex to 10.5 will not produce an
902           image 11 pixels larger, but only 1.  The translation is thus
903           effectively sub-pixel.
904
905           Rotation matrices can be applied too, however, when angles are
906           close to 90 and 270, either interim images become too big, or
907           defects introduced by shearing become too visible. Therefore the
908           method specifically detects for rotation cases, and uses Paeth
909           rotation algorithm instead, which yields better results.  Also, if
910           the angle is detected to be 90, 180, or 270 degrees, fast pixel
911           flipping is used.
912
913           Eventual resampling can be controlled by "scaling" property.
914
915       ui_scale %OPTIONS
916           Resizes the image with smooth scaling. Understands "zoom" and
917           "scaling" options. The "zoom" default value is the one in
918           "$::application->uiScaling", the "scaling" default value is
919           "ist::Quadratic" .
920
921           See also: "uiScaling" in Application
922
923   Prima::Image events
924       "Prima::Image"-specific events occur only from inside load call, to
925       report image loading progress. Not all codecs (currently JPEG,PNG,TIFF
926       only) are able to report the progress to the caller. See "Loading with
927       progress indicator" in Prima::image-load for details,
928       "watch_load_progress" in Prima::ImageViewer and "load" in
929       Prima::Dialog::ImageDialog for suggested use.
930
931       HeaderReady EXTRAS
932           Called whenever image header is read, and image dimensions and
933           pixel type is changed accordingly to accommodate image data.
934
935           "EXTRAS" is the hash to be stored later in "{extras}" key on the
936           object.
937
938       DataReady X, Y, WIDTH, HEIGHT
939           Called whenever image data that cover area designated by
940           X,Y,WIDTH,HEIGHT is acquired. Use "load" option "eventDelay" to
941           limit the rate of "DataReady" event.
942
943   Prima::Icon methods
944       alpha ALPHA <X1, Y1, X2, Y2>
945           Same as "Drawable::alpha" but can be used also outside of the paint
946           state.
947
948       combine DATA, MASK
949           Copies information from DATA and MASK images into "::data" and
950           "::mask" property. DATA and MASK are expected to be images of same
951           dimension.
952
953       create_combined DATA, MASK, %SET
954           Same as "combine", but to be called as constructor, and sets
955           properties in %SET
956
957       image %opt
958           Renders icon graphics on a newly created Prima::Image object
959           instance upon black background.  If $opt{background} is given, it
960           is used instead.
961
962       maskline Y
963           Returns a mask scanline from Y in the same raw format as "mask"
964
965       premultiply_alpha CONSTANT_OR_IMAGE = undef
966           Applies premultiplication formula to each pixel
967
968              pixel = pixel * alpha / 255
969
970           where alpha is the corresponding alpha value for each coordinate.
971           Only applicable when "maskType" is <im::bpp8>.
972
973       rotate, transform
974           Applies same transformation as in "Prima::Image" to both color and
975           mask pixels.  Ignores fill color, fills with zeros both planes.
976
977       split
978           Returns two new Prima::Image objects of same dimension.  Pixels in
979           the first is are duplicated from "::data" storage, in the second -
980           from "::mask" storage.
981
982       translate matrix => [a,b,c,d,x,y]
983           Same as the "translate" method from "Prima::Image" except that it
984           also rotates the mask, and ignores "fill" option - all new pixels
985           are filled with zeros.
986
987       ui_scale %OPTIONS
988           Same as "ui_scale" from "Prima::Image", but with few exceptions: It
989           tries to use "ist::Quadratic" only when the system supports ARGB
990           layering. Otherwise, falls back on "ist::Box" scaling algorithm,
991           and also limits the zoom factor to integers (2x, 3x etc) only,
992           because when displayed, the smooth-scaled color plane will not
993           match mask plane downgraded to 0/1 mask, and because box-scaling
994           with non-integer zooms looks ugly.
995
996   Prima::DeviceBitmap methods
997       dup Returns a duplicate of the object, a newly created
998           Prima::DeviceBitmap, with all information copied to it. Does not
999           preserve graphical properties (color etc).
1000
1001       icon
1002           Returns a newly created Prima::Icon object instance, with the pixel
1003           information copied from the object. If the bitmap is layered,
1004           returns icons with maskType set to "im::bpp8".
1005
1006       image
1007           Returns a newly created Prima::Image object instance, with the
1008           pixel information copied from the object.
1009
1010       get_handle
1011           Returns a system handle for a system bitmap object.
1012

AUTHOR

1014       Dmitry Karasik, <dmitry@karasik.eu.org>.
1015

SEE ALSO

1017       Prima, Prima::Drawable, Prima::image-load, Prima::codecs.
1018
1019       PDL, PDL::PrimaImage, IPA
1020
1021       ImageMagick, Prima::Image::Magick
1022
1023
1024
1025perl v5.36.0                      2023-03-20              pod::Prima::Image(3)
Impressum