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 See individual methods and properties in API that support standalone
292 usage, and how they differ from system-dependent implementation.
293 Prima::Icon
295 Prima::Icon inherits all properties of Prima::Image, and it also
296 provides a 1-bit depth transparency mask. This mask can also be loaded
297 and saved into image files, if the format supports a transparency
298 information.
299 Similar to Prima::Image::data property, Prima::Icon::mask property
301 provides access to the binary mask data. The mask can be updated
302 automatically, after an icon object was subject to painting, resizing,
303 or other destructive change. The auxiliary properties "::autoMasking"
304 and "::maskColor"/"::maskIndex" regulate mask update procedure. For
305 example, if an icon was loaded with the color ( vs. bitmap )
306 transparency information, the binary mask will be generated anyway, but
307 it will be also recorded that a particular color serves as a
308 transparent indicator, so eventual conversions can rely on the color
309 value, instead of the mask bitmap.
310 If an icon is drawn upon a graphic canvas, the image output is
312 constrained to the mask. On raster displays it is typically simulated
313 by a combination of and- and xor- operation modes, therefore attempts
314 to put an icon with "::rop", different from "rop::CopyPut", usually
315 fail.
316 Layering
318 The term layered window is borrowed from Windows world, and means a
319 window with transparency. In Prima, the property layered is used to
320 select this functionality. The call to
321 "$::application->get_system_value(sv::LayeredWidgets)" can check
322 whether this functionality is available; if not, the property is
323 ignored. By default, widgets can not use layering.
324 A layered drawable uses an extra alpha channel to designate the
326 transparency of the widget. Drawing on widgets will also look different
327 - for example, drawing with black color will make the black pixels
328 fully transparent, while other colors will blend with the underlying
329 background, but never in full. Prima provides no functions to draw with
330 alpha effects, and scarce image functions to address the alpha
331 surfaces. Drawing lines, text, etc with blending is delegated to
332 Prima::Cairo which is a separate module. Prima only provides alpha
333 surfaces and bitmaps with an additional alpha channel to draw upon.
334 However, "put_image" / "stretch_image" functions can operate on
335 surfaces with alpha as source and destination drawables. To address the
336 alpha channel on a drawable with Prima, one has to send either an
337 "Prima::Icon" with "maskType(im::bpp8)", or a layered "DeviceBitmap" to
338 these functions.
339 The corresponding "Prima::DeviceBitmap" type is "dbt::Layered", and is
341 fully compatible with layered widgets in the same fashion as
342 "DeviceBitmap" with type "dbt::Pixmap" is fully compatible with normal
343 widgets. One of ways to put a constant alpha value over a rectangle is
344 this, for example:
345 my $a = Prima::Icon->new(
347 width => 1,
348 height => 1,
349 type => im::RGB,
350 maskType => im::bpp8,
351 data => "\0\0\0",
352 mask => chr( $constant_alpha ),
353 );
354 $drawable-> stretch_image( 0, 0, 100, 100, $a, rop::SrcOver );
355 If displaying a picture with pre-existing alpha channel, you'll need to
357 call premultiply_alpha, because picture renderer assumes that pixel
358 values are premultiplied.
359 Even though addressing alpha values of pixels when drawing on layered
361 surfaces is not straighforward, the conversion between images and
362 device bitmaps fully supports alpha pixels. This means that:
363 * When drawing on an icon with 8-bit alpha channel (argb icon), any
365 changes to alpha values of pixels will be transferred back to the mask
366 property after "end_paint"
367 * Calls to "icon" function on DeviceBitmap with type "dbt::Layered"
369 produce identical argb icons. Calls to "bitmap" on argb icos produce
370 identical layered device bitmaps.
371 * Putting argb icons and layered device bitmap on other drawables
373 yields identical results.
374 Putting of argb source surfaces can be only used with two rops,
376 "rop::SrcOver" (default) and "rop::SrcCopy". The former produces
377 blending effect, while the latter copies alpha bits over to the
378 destination surface. Prima internal implementation of "put_image" and
379 "stretch_image" functions extends the allowed set of rops when
380 operating on images outside the begin_paint/end_paint brackets. These
381 rops support 12 Porter-Duff operators and flags to specify constant
382 alpha values to override the existing alpha channel, if any. See more
383 in "Raster operations" in Prima::Drawable.
384 Caveats: In Windows, mouse events will not be delivered to the layered
386 widget if the pixel under the mouse pointer is fully transparent.
387 See also: examples/layered.pl.
389
391 Prima::Image properties
392 colormap @PALETTE
393 A color palette, used for representing 1, 4, and 8-bit bitmaps,
394 when an image object is to be visualized. @PALETTE contains
395 individual colors component triplets, in RGB format. For example,
396 black-and-white monochrome image may contain colormap as
397 "0,0xffffff".
398 See also "palette".
400 conversion TYPE
402 Selects the type of dithering algorithm to be used for pixel down-
403 sampling. TYPE is one of "ict::XXX" constants:
404 ict::None - no dithering, with static palette or palette optimized by source palette
406 ict::Posterization - no dithering, with optimized palette by source pixels
407 ict::Ordered - fast 8x8 ordered halftone dithering with static palette
408 ict::ErrorDiffusion - error diffusion dithering with static palette
409 ict::Optimized - error diffusion dithering with optimized palette
410 As an example, if a 4x4 color image with every pixel set to
412 RGB(32,32,32), converted to a 1-bit image, the following results
413 occur:
414 ict::None, ict::Posterization:
416 [ 0 0 0 0 ]
417 [ 0 0 0 0 ]
418 [ 0 0 0 0 ]
419 [ 0 0 0 0 ]
420 ict::Ordered:
422 [ 0 0 0 0 ]
423 [ 0 0 1 0 ]
424 [ 0 0 0 0 ]
425 [ 1 0 0 0 ]
426 ict::ErrorDiffusion, ict::Ordered:
428 [ 0 0 1 0 ]
429 [ 0 0 0 1 ]
430 [ 0 0 0 0 ]
431 [ 0 0 0 0 ]
432 Values of these constants are made from "ictp::" in Prima::Const
434 and "ictd::" in Prima::Const constansts.
435 data SCALAR
437 Provides access to the bitmap data. On get-call, returns all bitmap
438 pixels, aligned to 4-byte boundary. On set-call, stores the
439 provided data with same alignment. The alignment can be altered by
440 submitting 'lineSize' write-only flag to set call; the ordering of
441 scan lines can be altered by setting 'reverse' write-only flag (
442 see "Data access" ).
443 height INTEGER
445 Manages the vertical dimension of the image data. On set-call, the
446 image data are changed accordingly to the new height, and depending
447 on "::vScaling" property, the pixel values are either scaled or
448 truncated.
449 lineSize INTEGER
451 A read-only property, returning the length of an image row in
452 bytes, as represented internally in memory. Data returned by
453 "::data" property are aligned with "::lineSize" bytes per row, and
454 setting "::data" expects data aligned with this value, unless
455 "lineSize" is set together with "data" to indicate another
456 alignment. See "Data access" for more.
457 mean
459 Returns mean value of pixels. Mean value is "::sum" of pixel
460 values, divided by number of pixels.
461 palette [ @PALETTE ]
463 A color palette, used for representing 1, 4, and 8-bit bitmaps,
464 when an image object is to be visualized. @PALETTE contains
465 individual color component triplets, in BGR format. For example,
466 black-and-white monochrome image may contain palette as
467 "[0,0,0,255,255,255]".
468 See also "colormap".
470 pixel ( X_OFFSET, Y_OFFSET ) PIXEL
472 Provides per-pixel access to the image data when image object is in
473 disabled paint state.
474 Pixel values for grayscale 1- and 4- bit images are treated
476 specifically, such that like 8-bit function, values cover range
477 between 0 and 255. F.ex. pixel values for grayscale 1 bit images
478 are 0 and 255, not 0 and 1.
479 In paint state same as "Prima::Drawable::pixel".
481 preserveType BOOLEAN
483 If 1, reverts the image type to its old value if an implicit
484 conversion was called during "end_paint()".
485 rangeHi
487 Returns maximum pixel value in the image data.
488 rangeLo
490 Returns minimum pixel value in the image data.
491 scaling INT
493 Declares the scaling strategy when image is resized. Strategies
494 "ist::None" through "ist::Box" are very fast scalers, others not
495 so.
496 Can be one of "ist:::XXX" constants:
498 ist::None - image will be either stripped (when downsizing)
500 or padded (when upsizing) with zeros
501 ist::Box - image will be scaled using simple box transform
502 ist::BoxX - columns will behave same as in ist::None,
503 rows will behave same as in ist::Box
504 ist::BoxY - rows will behave same as in ist::None,
505 columns will behave same as in ist::Box
506 ist::Triangle - bilinear interpolation
507 ist::Quadratic - 2rd order (quadratic) B-Spline approximation of Gaussian
508 ist::Sinc - sine function
509 ist::Hermite - B-Spline interpolation
510 ist::Cubic - 3rd order (cubic) B-Spline approximation of Gaussian
511 ist::Gaussian - Gaussian transform with gamma=0.5
512 Note: Resampling scaling algorithms (those greater than
514 "ist::Box"), when applied to Icons with 1-bit icon mask, will
515 silently convert the mask in 8-bit and apply the same scaling
516 algorithm to it. This will have great smoothing effect on mask
517 edges if the system supports ARGB layering (see "Layering" ).
518 size WIDTH, HEIGHT
520 Manages dimensions of the image. On set-call, the image data are
521 changed accordingly to the new dimensions, and depending on
522 "::scaling" property, the pixel values are either scaled or
523 truncated.
524 stats ( INDEX ) VALUE
526 Returns one of calculated values, that correspond to INDEX, which
527 is one of the following "is::XXX" constants:
528 is::RangeLo - minimum pixel value
530 is::RangeHi - maximum pixel value
531 is::Mean - mean value
532 is::Variance - variance
533 is::StdDev - standard deviation
534 is::Sum - sum of pixel values
535 is::Sum2 - sum of squares of pixel values
536 The values are re-calculated on request and cached. On set-call
538 VALUE is stored in the cache, and is returned on next get-call.
539 The cached values are discarded every time the image data changes.
540 These values are also accessible via set of alias properties:
542 "::rangeLo", "::rangeHi", "::mean", "::variance", "::stdDev",
543 "::sum", "::sum2".
544 stdDev
546 Returns standard deviation of the image data. Standard deviation
547 is the square root of "::variance".
548 sum Returns sum of pixel values of the image data
550 sum2
552 Returns sum of squares of pixel values of the image data
553 type TYPE
555 Governs the image pixel format type. TYPE is a combination of
556 "im::XXX" constants. The constants are collected in groups:
557 Bit-depth constants provide size of pixel is bits. Their actual
559 value is same as number of bits, so "im::bpp1" value is 1,
560 "im::bpp4" - 4, etc. The valid constants represent bit depths from
561 1 to 128:
562 im::bpp1
564 im::bpp4
565 im::bpp8
566 im::bpp16
567 im::bpp24
568 im::bpp32
569 im::bpp64
570 im::bpp128
571 The following values designate the pixel format category:
573 im::Color
575 im::GrayScale
576 im::RealNumber
577 im::ComplexNumber
578 im::TrigComplexNumber
579 im::SignedInt
580 Value of "im::Color" is 0, whereas other category constants
582 represented by unique bit value, so combination of "im::RealNumber"
583 and "im::ComplexNumber" is possible.
584 There also several mnemonic constants defined:
586 im::Mono - im::bpp1
588 im::BW - im::bpp1 | im::GrayScale
589 im::16 - im::bpp4
590 im::Nibble - im::bpp4
591 im::256 - im::bpp8
592 im::RGB - im::bpp24
593 im::Triple - im::bpp24
594 im::Byte - gray 8-bit unsigned integer
595 im::Short - gray 16-bit unsigned integer
596 im::Long - gray 32-bit unsigned integer
597 im::Float - float
598 im::Double - double
599 im::Complex - dual float
600 im::DComplex - dual double
601 im::TrigComplex - dual float
602 im::TrigDComplex - dual double
603 Bit depths of float- and double- derived pixel formats depend on a
605 platform.
606 The groups can be masked out with the mask values:
608 im::BPP - bit depth constants
610 im::Category - category constants
611 im::FMT - extra format constants
612 The extra formats are the pixel formats, not supported by "::type",
614 but recognized within the combined set-call, like
615 $image-> set(
617 type => im::fmtBGRI,
618 data => 'BGR-BGR-',
619 );
620 The data, supplied with the extra image format specification will
622 be converted to the closest supported format. Currently, the
623 following extra pixel formats are recognized:
624 im::fmtBGR
626 im::fmtRGBI
627 im::fmtIRGB
628 im::fmtBGRI
629 im::fmtIBGR
630 variance
632 Returns variance of pixel values of the image data. Variance is
633 "::sum2", divided by number of pixels minus square of "::sum" of
634 pixel values.
635 width INTEGER
637 Manages the horizontal dimension of the image data. On set-call,
638 the image data are changed accordingly to the new width, and
639 depending on "::scaling" property, the pixel values are either
640 scaled or truncated.
641 Prima::Icon properties
643 autoMasking TYPE
644 Selects whether the mask information should be updated
645 automatically with "::data" change or not. Every "::data" change is
646 mirrored in "::mask", using TYPE, one of "am::XXX" constants:
647 am::None - no mask update performed
649 am::MaskColor - mask update based on ::maskColor property
650 am::MaskIndex - mask update based on ::maskIndex property
651 am::Auto - mask update based on corner pixel values
652 The "::maskColor" color value is used as a transparent color if
654 TYPE is "am::MaskColor". The transparency mask generation
655 algorithm, turned on by "am::Auto" checks corner pixel values,
656 assuming that majority of the corner pixels represents a
657 transparent color. Once such color is found, the mask is generated
658 as in "am::MaskColor" case.
659 "::maskIndex" is the same as "::maskColor", except that it points
661 to a specific color index in the palette.
662 When image "::data" is stretched, "::mask" is stretched
664 accordingly, disregarding the "::autoMasking" value.
665 mask SCALAR
667 Provides access to the transparency bitmap. On get-call, returns
668 all bitmap pixels, aligned to 4-byte boundary in 1-bit format. On
669 set-call, stores the provided transparency data with same
670 alignment.
671 maskColor COLOR
673 When "::autoMasking" set to "am::MaskColor", COLOR is used as a
674 transparency value.
675 maskIndex INDEX
677 When "::autoMasking" set to "am::MaskIndex", INDEXth color in teh
678 current palette is used as a transparency value.
679 maskType INTEGER
681 Is either "im::bpp1" (1) or "im::bpp8" (8). The latter can be used
682 as a layered (argb) source surface to draw with blending effect.
683 Prima::DeviceBitmap properties
685 type INTEGER
686 A read-only property, that can only be set during creation,
687 reflects whether the system bitmap is black-and-white 1-bit
688 ("dbt::Bitmap"), is colored and compatible with widgets
689 ("dbt::Pixmap"), or is colored with alpha channel and compatible
690 with layered widgets ("dbt::Layered").
691 The color depth of a bitmap can be read via "get_bpp()" method;
693 monochrome bitmaps always have bit depth of 1, layered bitmaps have
694 bit depth of 32.
695 Prima::Image methods
697 bar X1, Y1, X2, Y2
698 Outside the paint state uses owen implementation for drawing a
699 rectangular shape. The following properties are respected:
700 "color", "backColor", "rop", "rop2", "fillPattern",
701 "fillPatternOffset", "region". "rop2" accepts either "rop::CopyPut"
702 or "rop::NoOper" values, to produce either opaque or transparent
703 fill pattern application.
704 Inside the paint state is identical to "Drawable::bar".
706 bitmap
708 Returns newly created Prima::DeviceBitmap instance, with the image
709 dimensions and with the bitmap pixel values copied to.
710 clear [X1, Y1, X2, Y2]
712 Same as "Drawable::clear" but can be used also outside of the paint
713 state.
714 clone %properties
716 Creates a copy of the image and applies %properties. An easy way to
717 create a down-sampled copy, for example.
718 codecs
720 Returns array of hashes, each describing the supported image
721 format. If the array is empty, the toolkit was set up so it can not
722 load and save images.
723 See Prima::image-load for details.
725 This method can be called without object instance.
727 dup Returns a duplicate of the object, a newly created Prima::Image,
729 with all information copied to it.
730 extract X_OFFSET, Y_OFFSET, WIDTH, HEIGHT
732 Returns a newly created image object with WIDTH and HEIGHT
733 dimensions, initialized with pixel data from X_OFFSET and Y_OFFSET
734 in the bitmap.
735 fill_chord, fill_ellipse, fill_sector
737 Same as "Drawable::" functions but can be used also outside of the
738 paint state.
739 get_bpp
741 Returns the bit depth of the pixel format. Same as "::type &
742 im::BPP".
743 get_handle
745 Returns a system handle for an image object.
746 load (FILENAME or FILEGLOB) [ %PARAMETERS ]
748 Loads image from file FILENAME or stream FILEGLOB into an object,
749 and returns the success flag. The semantics of "load()" is
750 extensive, and can be influenced by PARAMETERS hash. "load()" can
751 be called either in a context of an existing object, then a boolean
752 success flag is returned, or in a class context, then a newly
753 created object ( or "undef" ) is returned. If an error occurs, $@
754 variable contains the error description string. These two
755 invocation semantics are equivalent:
756 my $x = Prima::Image-> create();
758 die "$@" unless $x-> load( ... );
759 and
761 my $x = Prima::Image-> load( ... );
763 die "$@" unless $x;
764 See Prima::image-load for details.
766 NB! When loading from streams on win32, mind "binmode".
768 map COLOR
770 Performs iterative mapping of bitmap pixels, setting every pixel to
771 "::color" property with respect to "::rop" type if a pixel equals
772 to COLOR, and to "::backColor" property with respect to "::rop2"
773 type otherwise.
774 "rop::NoOper" type can be used for color masking.
776 Examples:
778 width => 4, height => 1, data => [ 1, 2, 3, 4]
780 color => 10, backColor => 20, rop => rop::CopyPut
781 rop2 => rop::CopyPut
783 input: map(2) output: [ 20, 10, 20, 20 ]
784 rop2 => rop::NoOper
786 input: map(2) output: [ 1, 10, 3, 4 ]
787 mirror VERTICAL
789 Mirrors the image depending on boolean flag VERTICAL
790 premultiply_alpha CONSTANT_OR_IMAGE
792 Applies premultiplication formula to each pixel
793 pixel = pixel * alpha / 256
795 where alpha either is a constant, or a pixel value in an image
797 put_image, put_image_indirect, stretch_image
799 Same as "Drawable::" functions but can be used also outside of the
800 paint state.
801 Extends raster functionality to access alpha channel either using
803 constant alpha values or "Prima::Icon" as sources. See explanation
804 of "rop::" constants in "Raster operations" in Prima::Drawable.
805 resample SRC_LOW, SRC_HIGH, DEST_LOW, DEST_HIGH
807 Performs linear scaling of gray pixel values from range (SRC_LOW -
808 SRC_HIGH) to range (DEST_LOW - DEST_HIGH). Can be used to visualize
809 gray non-8 bit pixel values, by the code:
810 $image-> resample( $image-> rangeLo, $image-> rangeHi, 0, 255);
812 rotate DEGREES
814 Rotates the image by 90, 180, or 270 degrees.
815 save (FILENAME or FILEGLOB), [ %PARAMETERS ]
817 Stores image data into image file FILENAME or stream FILEGLOB, and
818 returns the success flag. The semantics of "save()" is extensive,
819 and can be influenced by PARAMETERS hash. If error occurs, $@
820 variable contains error description string.
821 Note that when saving to a stream, "codecID" must be explicitly
823 given in %PARAMETERS.
824 See Prima::image-load for details.
826 NB! When saving to streams on win32, mind "binmode".
828 to_region
830 Creates a new Prima::Region object with the image as the data
831 source.
832 ui_scale %OPTIONS
834 Resizes the image with smooth scaling. Understands "zoom" and
835 "scaling" options. The "zoom" default value is the one in
836 "$::application->uiScaling", the "scaling" default value is
837 "ist::Quadratic" .
838 See also: "uiScaling" in Application
840 Prima::Image events
842 "Prima::Image"-specific events occur only from inside load call, to
843 report image loading progress. Not all codecs (currently JPEG,PNG,TIFF
844 only) are able to report the progress to the caller. See "Loading with
845 progress indicator" in Prima::image-load for details,
846 "watch_load_progress" in Prima::ImageViewer and "load" in
847 Prima::ImageDialog for suggested use.
848 HeaderReady EXTRAS
850 Called whenever image header is read, and image dimensions and
851 pixel type is changed accordingly to accomodate image data.
852 "EXTRAS" is the hash to be stored later in "{extras}" key on the
854 object.
855 DataReady X, Y, WIDTH, HEIGHT
857 Called whenever image data that cover area designated by
858 X,Y,WIDTH,HEIGHT is acquired. Use "load" option "eventDelay" to
859 limit the rate of "DataReady" event.
860 Prima::Icon methods
862 alpha ALPHA <X1, Y1, X2, Y2>
863 Same as "Drawable::alpha" but can be used also outside of the paint
864 state.
865 combine DATA, MASK
867 Copies information from DATA and MASK images into "::data" and
868 "::mask" property. DATA and MASK are expected to be images of same
869 dimension.
870 create_combined DATA, MASK
872 Same as "combine", but to be called as constructor.
873 premultiply_alpha CONSTANT_OR_IMAGE = undef
875 Applies premultiplication formula to each pixel
876 pixel = pixel * alpha / 256
878 where alpha is the corresponding alpha value for each coordinate.
880 Only applicable when "maskType" is <im::bpp8>.
881 split
883 Returns two new Prima::Image objects of same dimension. Pixels in
884 the first is are duplicated from "::data" storage, in the second -
885 from "::mask" storage.
886 ui_scale %OPTIONS
888 Same as "ui_scale" from "Prima::Image", but with few exceptions: It
889 tries to use "ist::Quadratic" only when the system supports ARGB
890 layering. Otherwise, falls back on "ist::Box" scaling algorithm,
891 and also limits the zoom factor to integers (2x, 3x etc) only,
892 because when displayed, the smooth-scaled color plane will not
893 match mask plane downgraded to 0/1 mask, and because box-scaling
894 with non-integer zooms looks ugly.
895 Prima::DeviceBitmap methods
897 icon
898 Returns a newly created Prima::Icon object instance, with the pixel
899 information copied from the object. If the bitmap is layered,
900 returns icons with maskType set to "im::bpp8".
901 image
903 Returns a newly created Prima::Image object instance, with the
904 pixel information copied from the object.
905 get_handle
907 Returns a system handle for a system bitmap object.
908
910 Dmitry Karasik, <dmitry@karasik.eu.org>.
911
913 Prima, Prima::Drawable, Prima::image-load, Prima::codecs.
914 PDL, PDL::PrimaImage, IPA
916 ImageMagick, Prima::Image::Magick
918perl v5.30.0 2019-08-21 pod::Prima::Image(3)