1pod::Prima::Image(3) User Contributed Perl Documentation pod::Prima::Image(3)
2
6 Prima::Image - Bitmap routines
7
9 use Prima qw(Application);
10 # 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 # draw something
19 $i-> begin_paint;
20 $i-> color( cl::White);
21 $i-> ellipse( 5, 5, 10, 10);
22 $i-> end_paint;
23 # mangle
25 $i-> size( 64, 64);
26 # file operations
28 $i-> save('a.gif') or die "Error saving:$@\n";
29 $i-> load('a.gif') or die "Error loading:$@\n";
30 # draw on screen
32 $::application-> begin_paint;
33 # an image is drawn as specified by its palette
35 $::application-> set( color => cl::Red, backColor => cl::Green);
36 $::application-> put_image( 100, 100, $i);
37 # a bitmap is drawn as specified by destination device colors
39 $::application-> put_image( 200, 100, $i-> bitmap);
40
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
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 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 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 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 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 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 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 It must be noted, that "put_image", "stretch_image" and
113 "put_image_indirect" are only painting methods that allow drawing on an
114 image that is in its paint-disabled state. Moreover, in such context
115 they only allow "Prima::Image" descendants to be passed as a source
116 image object. This functionality does not imply that the image is
117 internally switched to the paint-enabled state and back; the painting
118 is performed without switching and without interference with the
119 system's graphical layer.
120 Another special case is a 1-bit ( monochrome ) DeviceBitmap. When it is
122 drawn upon a drawable with bit depth greater than 1, the drawable's
123 color and backColor properties are used to reflect 1 and 0 bits,
124 respectively. On a 1-bit drawable this does not happen, and the color
125 properties are not used.
126 File input and output
128 Depending on the toolkit configuration, images can be read and written
129 in different formats. This functionality in accessible via "load()" and
130 "save()" methods. Prima::image-load is dedicated to the description of
131 loading and saving parameters, that can be passed to the methods, so
132 they can handle different aspects of file format-specific options, such
133 as multi-frame operations, auto conversion when a format does not
134 support a particular pixel format etc. In this document, "load()" and
135 "save()" methods are illustrated only in their basic, single-frame
136 functionality. When called with no extra parameters, these methods fail
137 only if a disk I/O error occurred or an unknown image format was used.
138 When an image is loaded, the old bitmap memory content is discarded,
140 and the image attributes are changed accordingly to the loaded image.
141 Along with these, an image palette is loaded, if available, and a pixel
142 format is assigned, closest or identical to the pixel format in the
143 image file.
144 Pixel formats
146 Prima::Image supports a number of pixel formats, governed by the
147 "::type" property. It is reflected by an integer value, a combination
148 of "im::XXX" constants. The whole set of pixel formats is represented
149 by colored formats, like, 16-color, 256-color and 16M-color, and by
150 gray-scale formats, mapped to C data types - unsigned char, unsigned
151 short, unsigned long, float and double. The gray-scale formats are
152 further subdivided to real-number formats and complex-number format;
153 the last ones are represented by two real values per pixel, containing
154 the real and the imaginary values.
155 Prima::Image can also be initialized from other formats, that it does
157 not support, but can convert data from. Currently these are represented
158 by a set of permutations of 32-bit RGBA format, and 24-bit BGR format.
159 These formats can only be used in conjunction with "::data" property.
160 The conversions can be performed between any of the supported formats (
162 to do so, "::type" property is to be set-called ). An image of any of
163 these formats can be drawn on the screen, but if the system can not
164 accept the pixel format ( as it is with non-integer or complex formats
165 ), the bitmap data are implicitly converted. The conversion does not
166 change the data if the image is about to be drawn; the conversion is
167 performed only when the image is about to be served as a drawing
168 surface. If, by any reason, it is desired that the pixel format is not
169 to be changed, the "::preserveType" property must be set to 1. It does
170 not prevent the conversion, but it detects if the image was implicitly
171 converted inside "end_paint()" call, and reverts it to its previous
172 pixel format.
173 There are situations, when pixel format must be changed together while
175 down-sampling the image. One of four down-sampling methods can be
176 selected - no halftoning, 8x8 ordered halftoning, error diffusion, and
177 error diffusion combined with optimized palette. These can be set to
178 the "::conversion" property with one of "ict::XXX" constants. When
179 there is no information loss, "::conversion" property is not used.
180 Another special case of conversion is a conversion with a palette. The
182 following calls,
183 $image-> type( im::bpp4);
185 $image-> palette( $palette);
186 and
188 $image-> palette( $palette);
190 $image-> type( im::bpp4);
191 produce different results, but none of these takes into account
193 eventual palette remapping, because "::palette" property does not
194 change bitmap pixel data, but overwrites palette information. A proper
195 call syntax here would be
196 $image-> set(
198 palette => $palette,
199 type => im::bpp4,
200 );
201 This call produces also palette pixel mapping. This syntax is most
203 powerful when conversion is set to those algorithms that can take in
204 the account the existing image pixels, to produce an optimized palette.
205 These are "ict::Optimized" ( by default ) and "ict::Posterization".
206 This syntax not only allows remapping or downsampling to a predefined
207 colors set, but also can be used to limit palette size to a particular
208 number, without knowing the actual values of the final color palette.
209 For example, for an 24-bit image,
210 $image-> set( type => im::bpp8, palette => 32);
212 call would calculate colors in the image, compress them to an optimized
214 palette of 32 cells and finally converts to a 8-bit format.
215 Instead of "palette" property, "colormap" can also be used.
217 Data access
219 The pixel values can be accessed in Prima::Drawable style, via
220 "::pixel" property. However, Prima::Image introduces several helper
221 functions, for different aims. The "::data" property is used to set or
222 retrieve a scalar representation of bitmap data. The data are expected
223 to be lined up to a 'line size' margin ( 4-byte boundary ), which is
224 calculated as
225 $lineSize = int(( $image->width * ( $image-> type & im::BPP) + 31) / 32) * 4;
227 or returned from the read-only property "::lineSize".
229 This is the line size for the data as lined up internally in memory,
231 however "::data" should not necessarily should be aligned like this,
232 and can be accompanied with a write-only flag 'lineSize' if pixels are
233 aligned differently:
234 $image-> set( width => 1, height=> 2);
236 $image-> type( im::RGB);
237 $image-> set(
238 data => 'RGB----RGB----',
239 lineSize => 7,
240 );
241 print $image-> data, "\n";
242 output: RGB-RGB-
244 Internally, Prima contains images in memory so that the first scanline
246 is the farthest away from the memory start; this is consistent with
247 general Y-axis orientation in Prima drawable terminology, but might be
248 inconvenient when importing data organized otherwise. Another write-
249 only boolean flag "reverse" can be set to 1 so data then are treated as
250 if the first scanline of the image is the closest to the start of data:
251 $image-> set( width => 1, height=> 2, type => im::RGB);
253 $image-> set(
254 data => 'RGB-123-',
255 reverse => 1,
256 );
257 print $image-> data, "\n";
258 output: RGB-123-
260 Although it is possible to perform all kinds of calculations and
262 modification with the pixels, returned by "::data", it is not advisable
263 unless the speed does not matter. Standalone PDL package with help of
264 PDL::PrimaImage package, and Prima-derived IPA package provide routines
265 for data and image analysis. Also, Prima::Image::Magick connects
266 ImageMagick with Prima. Prima::Image itself provides only the simplest
267 statistic information, namely: lowest and highest pixel values, pixel
268 sum, sum of square pixels, mean, variance, and standard deviation.
269 Standalone usage
271 Some of image functionality can be used standalone, with all other
272 parts of the toolkit being uninitialized. The functionality is limited
273 to loading and saving files, and reading and writing pixels (outside
274 begin_paint only). All other calls are ignored. Example:
275 my $i = Prima::Image->new( size => [5,5]);
277 $i->color(cl::Red);
278 $i->bar(0,0,$i->size);
279 $i->save('1.bmp');
280 This feature is useful in non-interactive programs, running in
282 environments with no GUI access, a cgi-script with no access to X11
283 display, for example. Normally, Prima fails to start in such
284 situations, but can be told not to initialize its GUI part by
285 explicitly operating system-dependent options. To do so, invoke
286 use Prima::noX11;
288 in the beginning of your program. See Prima::noX11 for more.
290 Generally the standalone methods support all the OS-specific functions
292 (i.e. color, region, etc), plus they support alpha blending using "rop"
293 property and "rop::alpha($rop, $src_alpha[, $dst_alpha]))" value.
294 See individual methods and properties in API that support standalone
296 usage, and how they differ from system-dependent implementation.
297 Prima::Icon
299 Prima::Icon inherits all properties of Prima::Image, and it also
300 provides a 1-bit depth transparency mask. This mask can also be loaded
301 and saved into image files, if the format supports a transparency
302 information.
303 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 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 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 A layered drawable uses an extra alpha channel to designate the
330 transparency of the widget. Drawing on widgets will also look different
331 - for example, drawing with black color will make the black pixels
332 fully transparent, while other colors will blend with the underlying
333 background, but never in full. Prima provides no functions to draw with
334 alpha effects, and scarce image functions to address the alpha
335 surfaces. Drawing lines, text, etc with blending is delegated to
336 Prima::Cairo which is a separate module. Prima only provides alpha
337 surfaces and bitmaps with an additional alpha channel to draw upon.
338 However, "put_image" / "stretch_image" functions can operate on
339 surfaces with alpha as source and destination drawables. To address the
340 alpha channel on a drawable with Prima, one has to send either an
341 "Prima::Icon" with "maskType(im::bpp8)", or a layered "DeviceBitmap" to
342 these functions.
343 The corresponding "Prima::DeviceBitmap" type is "dbt::Layered", and is
345 fully compatible with layered widgets in the same fashion as
346 "DeviceBitmap" with type "dbt::Pixmap" is fully compatible with normal
347 widgets. One of ways to put a constant alpha value over a rectangle is
348 this, for example:
349 my $a = Prima::Icon->new(
351 width => 1,
352 height => 1,
353 type => im::RGB,
354 maskType => im::bpp8,
355 data => "\0\0\0",
356 mask => chr( $constant_alpha ),
357 );
358 $drawable-> stretch_image( 0, 0, 100, 100, $a, rop::SrcOver );
359 If displaying a picture with pre-existing alpha channel, you'll need to
361 call premultiply_alpha, because picture renderer assumes that pixel
362 values are premultiplied.
363 Even though addressing alpha values of pixels when drawing on layered
365 surfaces is not straighforward, the conversion between images and
366 device bitmaps fully supports alpha pixels. This means that:
367 * When drawing on an icon with 8-bit alpha channel (argb icon), any
369 changes to alpha values of pixels will be transferred back to the mask
370 property after "end_paint"
371 * Calls to "icon" function on DeviceBitmap with type "dbt::Layered"
373 produce identical argb icons. Calls to "bitmap" on argb icos produce
374 identical layered device bitmaps.
375 * Putting argb icons and layered device bitmap on other drawables
377 yields identical results.
378 Putting of argb source surfaces can be only used with two rops,
380 "rop::SrcOver" (default) and "rop::SrcCopy". The former produces
381 blending effect, while the latter copies alpha bits over to the
382 destination surface. Prima internal implementation of "put_image" and
383 "stretch_image" functions extends the allowed set of rops when
384 operating on images outside the begin_paint/end_paint brackets. These
385 rops support 12 Porter-Duff operators and flags to specify constant
386 alpha values to override the existing alpha channel, if any. See more
387 in "Raster operations" in Prima::Drawable.
388 Caveats: In Windows, mouse events will not be delivered to the layered
390 widget if the pixel under the mouse pointer is fully transparent.
391 See also: examples/layered.pl.
393
395 Prima::Image properties
396 colormap @PALETTE
397 A color palette, used for representing 1, 4, and 8-bit bitmaps,
398 when an image object is to be visualized. @PALETTE contains
399 individual colors component triplets, in RGB format. For example,
400 black-and-white monochrome image may contain colormap as
401 "0,0xffffff".
402 See also "palette".
404 conversion TYPE
406 Selects the type of dithering algorithm to be used for pixel down-
407 sampling. TYPE is one of "ict::XXX" constants:
408 ict::None - no dithering, with static palette or palette optimized by source palette
410 ict::Posterization - no dithering, with optimized palette by source pixels
411 ict::Ordered - fast 8x8 ordered halftone dithering with static palette
412 ict::ErrorDiffusion - error diffusion dithering with static palette
413 ict::Optimized - error diffusion dithering with optimized palette
414 As an example, if a 4x4 color image with every pixel set to
416 RGB(32,32,32), converted to a 1-bit image, the following results
417 occur:
418 ict::None, ict::Posterization:
420 [ 0 0 0 0 ]
421 [ 0 0 0 0 ]
422 [ 0 0 0 0 ]
423 [ 0 0 0 0 ]
424 ict::Ordered:
426 [ 0 0 0 0 ]
427 [ 0 0 1 0 ]
428 [ 0 0 0 0 ]
429 [ 1 0 0 0 ]
430 ict::ErrorDiffusion, ict::Ordered:
432 [ 0 0 1 0 ]
433 [ 0 0 0 1 ]
434 [ 0 0 0 0 ]
435 [ 0 0 0 0 ]
436 Values of these constants are made from "ictp::" in Prima::Const
438 and "ictd::" in Prima::Const constansts.
439 data SCALAR
441 Provides access to the bitmap data. On get-call, returns all bitmap
442 pixels, aligned to 4-byte boundary. On set-call, stores the
443 provided data with same alignment. The alignment can be altered by
444 submitting 'lineSize' write-only flag to set call; the ordering of
445 scan lines can be altered by setting 'reverse' write-only flag (
446 see "Data access" ).
447 height INTEGER
449 Manages the vertical dimension of the image data. On set-call, the
450 image data are changed accordingly to the new height, and depending
451 on "::vScaling" property, the pixel values are either scaled or
452 truncated.
453 lineSize INTEGER
455 A read-only property, returning the length of an image row in
456 bytes, as represented internally in memory. Data returned by
457 "::data" property are aligned with "::lineSize" bytes per row, and
458 setting "::data" expects data aligned with this value, unless
459 "lineSize" is set together with "data" to indicate another
460 alignment. See "Data access" for more.
461 mean
463 Returns mean value of pixels. Mean value is "::sum" of pixel
464 values, divided by number of pixels.
465 palette [ @PALETTE ]
467 A color palette, used for representing 1, 4, and 8-bit bitmaps,
468 when an image object is to be visualized. @PALETTE contains
469 individual color component triplets, in BGR format. For example,
470 black-and-white monochrome image may contain palette as
471 "[0,0,0,255,255,255]".
472 See also "colormap".
474 pixel ( X_OFFSET, Y_OFFSET ) PIXEL
476 Provides per-pixel access to the image data when image object is in
477 disabled paint state.
478 Pixel values for grayscale 1- and 4- bit images are treated
480 specifically, such that like 8-bit function, values cover range
481 between 0 and 255. F.ex. pixel values for grayscale 1 bit images
482 are 0 and 255, not 0 and 1.
483 In paint state same as "Prima::Drawable::pixel".
485 preserveType BOOLEAN
487 If 1, reverts the image type to its old value if an implicit
488 conversion was called during "end_paint()".
489 rangeHi
491 Returns maximum pixel value in the image data.
492 rangeLo
494 Returns minimum pixel value in the image data.
495 scaling INT
497 Declares the scaling strategy when image is resized. Strategies
498 "ist::None" through "ist::Box" are very fast scalers, others not
499 so.
500 Can be one of "ist:::XXX" constants:
502 ist::None - image will be either stripped (when downsizing)
504 or padded (when upsizing) with zeros
505 ist::Box - image will be scaled using simple box transform
506 ist::BoxX - columns will behave same as in ist::None,
507 rows will behave same as in ist::Box
508 ist::BoxY - rows will behave same as in ist::None,
509 columns will behave same as in ist::Box
510 ist::Triangle - bilinear interpolation
511 ist::Quadratic - 2rd order (quadratic) B-Spline approximation of Gaussian
512 ist::Sinc - sine function
513 ist::Hermite - B-Spline interpolation
514 ist::Cubic - 3rd order (cubic) B-Spline approximation of Gaussian
515 ist::Gaussian - Gaussian transform with gamma=0.5
516 Note: Resampling scaling algorithms (those greater than
518 "ist::Box"), when applied to Icons with 1-bit icon mask, will
519 silently convert the mask in 8-bit and apply the same scaling
520 algorithm to it. This will have great smoothing effect on mask
521 edges if the system supports ARGB layering (see "Layering" ).
522 size WIDTH, HEIGHT
524 Manages dimensions of the image. On set-call, the image data are
525 changed accordingly to the new dimensions, and depending on
526 "::scaling" property, the pixel values are either scaled or
527 truncated.
528 stats ( INDEX ) VALUE
530 Returns one of calculated values, that correspond to INDEX, which
531 is one of the following "is::XXX" constants:
532 is::RangeLo - minimum pixel value
534 is::RangeHi - maximum pixel value
535 is::Mean - mean value
536 is::Variance - variance
537 is::StdDev - standard deviation
538 is::Sum - sum of pixel values
539 is::Sum2 - sum of squares of pixel values
540 The values are re-calculated on request and cached. On set-call
542 VALUE is stored in the cache, and is returned on next get-call.
543 The cached values are discarded every time the image data changes.
544 These values are also accessible via set of alias properties:
546 "::rangeLo", "::rangeHi", "::mean", "::variance", "::stdDev",
547 "::sum", "::sum2".
548 stdDev
550 Returns standard deviation of the image data. Standard deviation
551 is the square root of "::variance".
552 sum Returns sum of pixel values of the image data
554 sum2
556 Returns sum of squares of pixel values of the image data
557 type TYPE
559 Governs the image pixel format type. TYPE is a combination of
560 "im::XXX" constants. The constants are collected in groups:
561 Bit-depth constants provide size of pixel is bits. Their actual
563 value is same as number of bits, so "im::bpp1" value is 1,
564 "im::bpp4" - 4, etc. The valid constants represent bit depths from
565 1 to 128:
566 im::bpp1
568 im::bpp4
569 im::bpp8
570 im::bpp16
571 im::bpp24
572 im::bpp32
573 im::bpp64
574 im::bpp128
575 The following values designate the pixel format category:
577 im::Color
579 im::GrayScale
580 im::RealNumber
581 im::ComplexNumber
582 im::TrigComplexNumber
583 im::SignedInt
584 Value of "im::Color" is 0, whereas other category constants
586 represented by unique bit value, so combination of "im::RealNumber"
587 and "im::ComplexNumber" is possible.
588 There also several mnemonic constants defined:
590 im::Mono - im::bpp1
592 im::BW - im::bpp1 | im::GrayScale
593 im::16 - im::bpp4
594 im::Nibble - im::bpp4
595 im::256 - im::bpp8
596 im::RGB - im::bpp24
597 im::Triple - im::bpp24
598 im::Byte - gray 8-bit unsigned integer
599 im::Short - gray 16-bit unsigned integer
600 im::Long - gray 32-bit unsigned integer
601 im::Float - float
602 im::Double - double
603 im::Complex - dual float
604 im::DComplex - dual double
605 im::TrigComplex - dual float
606 im::TrigDComplex - dual double
607 Bit depths of float- and double- derived pixel formats depend on a
609 platform.
610 The groups can be masked out with the mask values:
612 im::BPP - bit depth constants
614 im::Category - category constants
615 im::FMT - extra format constants
616 The extra formats are the pixel formats, not supported by "::type",
618 but recognized within the combined set-call, like
619 $image-> set(
621 type => im::fmtBGRI,
622 data => 'BGR-BGR-',
623 );
624 The data, supplied with the extra image format specification will
626 be converted to the closest supported format. Currently, the
627 following extra pixel formats are recognized:
628 im::fmtBGR
630 im::fmtRGBI
631 im::fmtIRGB
632 im::fmtBGRI
633 im::fmtIBGR
634 variance
636 Returns variance of pixel values of the image data. Variance is
637 "::sum2", divided by number of pixels minus square of "::sum" of
638 pixel values.
639 width INTEGER
641 Manages the horizontal dimension of the image data. On set-call,
642 the image data are changed accordingly to the new width, and
643 depending on "::scaling" property, the pixel values are either
644 scaled or truncated.
645 Prima::Icon properties
647 autoMasking TYPE
648 Selects whether the mask information should be updated
649 automatically with "::data" change or not. Every "::data" change is
650 mirrored in "::mask", using TYPE, one of "am::XXX" constants:
651 am::None - no mask update performed
653 am::MaskColor - mask update based on ::maskColor property
654 am::MaskIndex - mask update based on ::maskIndex property
655 am::Auto - mask update based on corner pixel values
656 The "::maskColor" color value is used as a transparent color if
658 TYPE is "am::MaskColor". The transparency mask generation
659 algorithm, turned on by "am::Auto" checks corner pixel values,
660 assuming that majority of the corner pixels represents a
661 transparent color. Once such color is found, the mask is generated
662 as in "am::MaskColor" case.
663 "::maskIndex" is the same as "::maskColor", except that it points
665 to a specific color index in the palette.
666 When image "::data" is stretched, "::mask" is stretched
668 accordingly, disregarding the "::autoMasking" value.
669 mask SCALAR
671 Provides access to the transparency bitmap. On get-call, returns
672 all bitmap pixels, aligned to 4-byte boundary in 1-bit format. On
673 set-call, stores the provided transparency data with same
674 alignment.
675 maskColor COLOR
677 When "::autoMasking" set to "am::MaskColor", COLOR is used as a
678 transparency value.
679 maskIndex INDEX
681 When "::autoMasking" set to "am::MaskIndex", INDEXth color in teh
682 current palette is used as a transparency value.
683 maskType INTEGER
685 Is either "im::bpp1" (1) or "im::bpp8" (8). The latter can be used
686 as a layered (argb) source surface to draw with blending effect.
687 Prima::DeviceBitmap properties
689 type INTEGER
690 A read-only property, that can only be set during creation,
691 reflects whether the system bitmap is black-and-white 1-bit
692 ("dbt::Bitmap"), is colored and compatible with widgets
693 ("dbt::Pixmap"), or is colored with alpha channel and compatible
694 with layered widgets ("dbt::Layered").
695 The color depth of a bitmap can be read via "get_bpp()" method;
697 monochrome bitmaps always have bit depth of 1, layered bitmaps have
698 bit depth of 32.
699 Prima::Image methods
701 bar X1, Y1, X2, Y2
702 Outside the paint state uses owen implementation for drawing a
703 rectangular shape. The following properties are respected:
704 "color", "backColor", "rop", "rop2", "fillPattern",
705 "fillPatternOffset", "region". "rop2" accepts either "rop::CopyPut"
706 or "rop::NoOper" values, to produce either opaque or transparent
707 fill pattern application.
708 Inside the paint state is identical to "Drawable::bar".
710 bitmap
712 Returns newly created Prima::DeviceBitmap instance, with the image
713 dimensions and with the bitmap pixel values copied to.
714 clear [X1, Y1, X2, Y2]
716 Same as "Drawable::clear" but can be used also outside of the paint
717 state.
718 clone %properties
720 Creates a copy of the image and applies %properties. An easy way to
721 create a down-sampled copy, for example.
722 codecs
724 Returns array of hashes, each describing the supported image
725 format. If the array is empty, the toolkit was set up so it can not
726 load and save images.
727 See Prima::image-load for details.
729 This method can be called without object instance.
731 dup Returns a duplicate of the object, a newly created Prima::Image,
733 with all information copied to it. Does not preserve graphical
734 properties (color etc).
735 extract X_OFFSET, Y_OFFSET, WIDTH, HEIGHT
737 Returns a newly created image object with WIDTH and HEIGHT
738 dimensions, initialized with pixel data from X_OFFSET and Y_OFFSET
739 in the bitmap.
740 fill_chord, fill_ellipse, fill_sector, flood_fill
742 Same as "Drawable::" functions but can be used also outside of the
743 paint state.
744 get_bpp
746 Returns the bit depth of the pixel format. Same as "::type &
747 im::BPP".
748 get_handle
750 Returns a system handle for an image object.
751 load (FILENAME or FILEGLOB) [ %PARAMETERS ]
753 Loads image from file FILENAME or stream FILEGLOB into an object,
754 and returns the success flag. The semantics of "load()" is
755 extensive, and can be influenced by PARAMETERS hash. "load()" can
756 be called either in a context of an existing object, then a boolean
757 success flag is returned, or in a class context, then a newly
758 created object ( or "undef" ) is returned. If an error occurs, $@
759 variable contains the error description string. These two
760 invocation semantics are equivalent:
761 my $x = Prima::Image-> create();
763 die "$@" unless $x-> load( ... );
764 and
766 my $x = Prima::Image-> load( ... );
768 die "$@" unless $x;
769 See Prima::image-load for details.
771 NB! When loading from streams on win32, mind "binmode".
773 map COLOR
775 Performs iterative mapping of bitmap pixels, setting every pixel to
776 "::color" property with respect to "::rop" type if a pixel equals
777 to COLOR, and to "::backColor" property with respect to "::rop2"
778 type otherwise.
779 "rop::NoOper" type can be used for color masking.
781 Examples:
783 width => 4, height => 1, data => [ 1, 2, 3, 4]
785 color => 10, backColor => 20, rop => rop::CopyPut
786 rop2 => rop::CopyPut
788 input: map(2) output: [ 20, 10, 20, 20 ]
789 rop2 => rop::NoOper
791 input: map(2) output: [ 1, 10, 3, 4 ]
792 mirror VERTICAL
794 Mirrors the image depending on boolean flag VERTICAL
795 premultiply_alpha CONSTANT_OR_IMAGE
797 Applies premultiplication formula to each pixel
798 pixel = pixel * alpha / 256
800 where alpha either is a constant, or a pixel value in an image
802 put_image, put_image_indirect, stretch_image
804 Same as "Drawable::" functions but can be used also outside of the
805 paint state.
806 Extends raster functionality to access alpha channel either using
808 constant alpha values or "Prima::Icon" as sources. See explanation
809 of "rop::" constants in "Raster operations" in Prima::Drawable.
810 resample SRC_LOW, SRC_HIGH, DEST_LOW, DEST_HIGH
812 Performs linear scaling of gray pixel values from range (SRC_LOW -
813 SRC_HIGH) to range (DEST_LOW - DEST_HIGH). Can be used to visualize
814 gray non-8 bit pixel values, by the code:
815 $image-> resample( $image-> rangeLo, $image-> rangeHi, 0, 255);
817 rotate DEGREES
819 Rotates the image. Where the angle is 90, 180, or 270 degrees, fast
820 pixel flipping is used, otherwise fast Paeth rotation is used.
821 Eventual resampling can be controlled by "scaling" property (
822 probably not worth it for functions with support of more than 1
823 pixel).
824 Resulting images can be 1 pixel too wide due to horizontal shearing
826 applied twice, where in worst cases 1 pixel from the original image
827 can take 3 horizontal pixels on the result.
828 save (FILENAME or FILEGLOB), [ %PARAMETERS ]
830 Stores image data into image file FILENAME or stream FILEGLOB, and
831 returns the success flag. The semantics of "save()" is extensive,
832 and can be influenced by PARAMETERS hash. If error occurs, $@
833 variable contains error description string.
834 Note that when saving to a stream, "codecID" must be explicitly
836 given in %PARAMETERS.
837 See Prima::image-load for details.
839 NB! When saving to streams on win32, mind "binmode".
841 shear X, Y
843 Applies shearing to the image. If the shearing is needed only for
844 one axis, set shear factor for the other one to zero.
845 to_region
847 Creates a new Prima::Region object with the image as the data
848 source.
849 transform @MATRIX
851 Applies generic 2D transform matrix to the image, where matrix is 4
852 numbers.
853 Tries first to split matrix into series of shear and scale
855 transforms using LDU decomposition; if an interim image needs to be
856 too large, fails and returns "false".
857 Rotation matrices can be applied too, however, when angles are
859 close to 90 and 270, either interim images become too big, or
860 defects introduced by shearing become too visible. Therefore the
861 method specifically detects for rotation cases, and uses Paeth
862 rotation algorithm instead, which yields better results. Also, if
863 the angle is detected to be 90, 180, or 270 degrees, fast pixel
864 flipping is used.
865 Eventual resampling can be controlled by "scaling" property.
867 ui_scale %OPTIONS
869 Resizes the image with smooth scaling. Understands "zoom" and
870 "scaling" options. The "zoom" default value is the one in
871 "$::application->uiScaling", the "scaling" default value is
872 "ist::Quadratic" .
873 See also: "uiScaling" in Application
875 Prima::Image events
877 "Prima::Image"-specific events occur only from inside load call, to
878 report image loading progress. Not all codecs (currently JPEG,PNG,TIFF
879 only) are able to report the progress to the caller. See "Loading with
880 progress indicator" in Prima::image-load for details,
881 "watch_load_progress" in Prima::ImageViewer and "load" in
882 Prima::Dialog::ImageDialog for suggested use.
883 HeaderReady EXTRAS
885 Called whenever image header is read, and image dimensions and
886 pixel type is changed accordingly to accomodate image data.
887 "EXTRAS" is the hash to be stored later in "{extras}" key on the
889 object.
890 DataReady X, Y, WIDTH, HEIGHT
892 Called whenever image data that cover area designated by
893 X,Y,WIDTH,HEIGHT is acquired. Use "load" option "eventDelay" to
894 limit the rate of "DataReady" event.
895 Prima::Icon methods
897 alpha ALPHA <X1, Y1, X2, Y2>
898 Same as "Drawable::alpha" but can be used also outside of the paint
899 state.
900 combine DATA, MASK
902 Copies information from DATA and MASK images into "::data" and
903 "::mask" property. DATA and MASK are expected to be images of same
904 dimension.
905 create_combined DATA, MASK
907 Same as "combine", but to be called as constructor.
908 image %opt
910 Renders icon graphics on a newly created Prima::Image object
911 instance upon black background. If $opt{background} is given, it
912 is used instead.
913 premultiply_alpha CONSTANT_OR_IMAGE = undef
915 Applies premultiplication formula to each pixel
916 pixel = pixel * alpha / 256
918 where alpha is the corresponding alpha value for each coordinate.
920 Only applicable when "maskType" is <im::bpp8>.
921 split
923 Returns two new Prima::Image objects of same dimension. Pixels in
924 the first is are duplicated from "::data" storage, in the second -
925 from "::mask" storage.
926 ui_scale %OPTIONS
928 Same as "ui_scale" from "Prima::Image", but with few exceptions: It
929 tries to use "ist::Quadratic" only when the system supports ARGB
930 layering. Otherwise, falls back on "ist::Box" scaling algorithm,
931 and also limits the zoom factor to integers (2x, 3x etc) only,
932 because when displayed, the smooth-scaled color plane will not
933 match mask plane downgraded to 0/1 mask, and because box-scaling
934 with non-integer zooms looks ugly.
935 Prima::DeviceBitmap methods
937 dup Returns a duplicate of the object, a newly created
938 Prima::DeviceBitmap, with all information copied to it. Does not
939 preserve graphical properties (color etc).
940 icon
942 Returns a newly created Prima::Icon object instance, with the pixel
943 information copied from the object. If the bitmap is layered,
944 returns icons with maskType set to "im::bpp8".
945 image
947 Returns a newly created Prima::Image object instance, with the
948 pixel information copied from the object.
949 get_handle
951 Returns a system handle for a system bitmap object.
952
954 Dmitry Karasik, <dmitry@karasik.eu.org>.
955
957 Prima, Prima::Drawable, Prima::image-load, Prima::codecs.
958 PDL, PDL::PrimaImage, IPA
960 ImageMagick, Prima::Image::Magick
962perl v5.32.0 2020-07-28 pod::Prima::Image(3)