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-> put_image( 100, 100, $i);
36 # 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
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" 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 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 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 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 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 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 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 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 Another special case of conversion is a conversion with a palette. The
180 following calls,
181 $image-> type( im::bpp4);
183 $image-> palette( $palette);
184 and
186 $image-> palette( $palette);
188 $image-> type( im::bpp4);
189 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 $image-> set(
196 palette => $palette,
197 type => im::bpp4,
198 );
199 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 $image-> set( type => im::bpp8, palette => 32);
210 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 Instead of "palette" property, "colormap" can also be used.
215 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 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 $lineSize = int(( $image->width * ( $image-> type & im::BPP) + 31) / 32) * 4;
226 or returned from the read-only property "::lineSize".
228 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 $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 output: RGB-RGB-
243 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 $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 output: RGB-123-
259 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 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 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 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 use Prima::noX11;
287 in the beginning of your program. See Prima::noX11 for more.
289 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 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 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 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. 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 "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 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 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 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 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 * 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 * 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 * Putting argb icons and layered device bitmap on other drawables
375 yields identical results.
376 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 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 See also: examples/layered.pl.
392
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 See also "palette".
403 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 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 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 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 ict::Ordered:
425 [ 0 0 0 0 ]
426 [ 0 0 1 0 ]
427 [ 0 0 0 0 ]
428 [ 1 0 0 0 ]
429 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 Values of these constants are made from "ictp::" in Prima::Const
437 and "ictd::" in Prima::Const constants.
438 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 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 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 mean
462 Returns mean value of pixels. Mean value is "::sum" of pixel
463 values, divided by number of pixels.
464 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 See also "colormap".
473 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 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 In paint state same as "Prima::Drawable::pixel".
484 preserveType BOOLEAN
486 If 1, reverts the image type to its old value if an implicit
487 conversion was called during end_paint().
488 rangeHi
490 Returns maximum pixel value in the image data.
491 rangeLo
493 Returns minimum pixel value in the image data.
494 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 Can be one of "ist:::XXX" constants:
501 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 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 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 stats ( INDEX ) VALUE
535 Returns one of calculated values, that correspond to INDEX, which
536 is one of the following "is::XXX" constants:
537 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 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 These values are also accessible via set of alias properties:
551 "::rangeLo", "::rangeHi", "::mean", "::variance", "::stdDev",
552 "::sum", "::sum2".
553 stdDev
555 Returns standard deviation of the image data. Standard deviation
556 is the square root of "::variance".
557 sum Returns sum of pixel values of the image data
559 sum2
561 Returns sum of squares of pixel values of the image data
562 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 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 im::bpp1
573 im::bpp4
574 im::bpp8
575 im::bpp16
576 im::bpp24
577 im::bpp32
578 im::bpp64
579 im::bpp128
580 The following values designate the pixel format category:
582 im::Color
584 im::GrayScale
585 im::RealNumber
586 im::ComplexNumber
587 im::TrigComplexNumber
588 im::SignedInt
589 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 There also several mnemonic constants defined:
595 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 Bit depths of float- and double- derived pixel formats depend on a
614 platform.
615 The groups can be masked out with the mask values:
617 im::BPP - bit depth constants
619 im::Category - category constants
620 im::FMT - extra format constants
621 The extra formats are the pixel formats, not supported by "::type",
623 but recognized within the combined set-call, like
624 $image-> set(
626 type => im::fmtBGRI,
627 data => 'BGR-BGR-',
628 );
629 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 im::fmtBGR
635 im::fmtRGBI
636 im::fmtIRGB
637 im::fmtBGRI
638 im::fmtIBGR
639 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 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 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 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 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 "::maskIndex" is the same as "::maskColor", except that it points
670 to a specific color index in the palette.
671 When image "::data" is stretched, "::mask" is stretched
673 accordingly, disregarding the "::autoMasking" value.
674 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 maskColor COLOR
682 When "::autoMasking" set to "am::MaskColor", COLOR is used as a
683 transparency value.
684 maskIndex INDEX
686 When "::autoMasking" set to "am::MaskIndex", INDEXth color in the
687 current palette is used as a transparency value.
688 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 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 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 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 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 Inside the paint state is identical to "Drawable::bar".
720 bitmap
722 Returns newly created Prima::DeviceBitmap instance, with the image
723 dimensions and with the bitmap pixel values copied to.
724 clear [X1, Y1, X2, Y2]
726 Same as "Drawable::clear" but can be used also outside of the paint
727 state.
728 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 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 See Prima::image-load for details.
739 This method can be called without object instance:
741 perl -MData::Dumper=Dumper -MPrima::noX11 -MPrima -le 'print Dumper(Prima::Image->codecs)'
743 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 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 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 get_bpp
758 Returns the bit depth of the pixel format. Same as "::type &
759 im::BPP".
760 get_handle
762 Returns a system handle for an image object.
763 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 my $x = Prima::Image-> create();
775 die "$@" unless $x-> load( ... );
776 and
778 my $x = Prima::Image-> load( ... );
780 die "$@" unless $x;
781 See Prima::image-load for details.
783 NB! When loading from streams on win32, mind "binmode".
785 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 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 "rop::NoOper" type can be used for color masking.
798 Examples:
800 width => 4, height => 1, data => [ 1, 2, 3, 4]
802 color => 10, backColor => 20, rop => rop::CopyPut
803 rop2 => rop::CopyPut
805 input: map(2) output: [ 20, 10, 20, 20 ]
806 rop2 => rop::NoOper
808 input: map(2) output: [ 1, 10, 3, 4 ]
809 mirror VERTICAL
811 Mirrors the image depending on boolean flag VERTICAL
812 premultiply_alpha CONSTANT_OR_IMAGE
814 Applies premultiplication formula to each pixel
815 pixel = pixel * alpha / 256
817 where alpha either is a constant, or a pixel value in an image
819 put_image, put_image_indirect, stretch_image
821 Same as "Drawable::" functions but can be used also outside of the
822 paint state.
823 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 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 $image-> resample( $image-> rangeLo, $image-> rangeHi, 0, 255);
834 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 Fills empty pixels with optional fill color.
843 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 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 Note that when saving to a stream, "codecID" must be explicitly
855 given in %PARAMETERS.
856 See Prima::image-load for details.
858 NB! When saving to streams on win32, mind "binmode".
860 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 Returns encoded content on success, or "undef" on failure; $@ is
867 set in the latter case.
868 scanline Y
870 Returns a scanline from Y in the same raw format as "data"
871 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 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 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 to_region
885 Creates a new Prima::Region object with the image as the data
886 source.
887 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 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 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 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 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 Eventual resampling can be controlled by "scaling" property.
914 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 See also: "uiScaling" in Application
922 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 HeaderReady EXTRAS
932 Called whenever image header is read, and image dimensions and
933 pixel type is changed accordingly to accommodate image data.
934 "EXTRAS" is the hash to be stored later in "{extras}" key on the
936 object.
937 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 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 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 create_combined DATA, MASK, %SET
954 Same as "combine", but to be called as constructor, and sets
955 properties in %SET
956 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 maskline Y
963 Returns a mask scanline from Y in the same raw format as "mask"
964 premultiply_alpha CONSTANT_OR_IMAGE = undef
966 Applies premultiplication formula to each pixel
967 pixel = pixel * alpha / 255
969 where alpha is the corresponding alpha value for each coordinate.
971 Only applicable when "maskType" is <im::bpp8>.
972 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 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 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 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 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 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 image
1007 Returns a newly created Prima::Image object instance, with the
1008 pixel information copied from the object.
1009 get_handle
1011 Returns a system handle for a system bitmap object.
1012
1014 Dmitry Karasik, <dmitry@karasik.eu.org>.
1015
1017 Prima, Prima::Drawable, Prima::image-load, Prima::codecs.
1018 PDL, PDL::PrimaImage, IPA
1020 ImageMagick, Prima::Image::Magick
1022perl v5.36.0 2023-03-20 pod::Prima::Image(3)