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.
275 This feature is useful in non-interactive programs, running in
277 evnironments with no GUI access, a cgi-script with no access to X11
278 display, for example. Normally, Prima fails to start in such
279 situations, but can be told not to initialize its GUI part by
280 explicitly operating system-dependent options. To do so, invoke
281 use Prima::noX11;
283 in the beginning of your program. See Prima::noX11 for more.
285 Prima::Icon
287 Prima::Icon inherits all properties of Prima::Image, and it also
288 provides a 1-bit depth transparency mask. This mask can also be loaded
289 and saved into image files, if the format supports a transparency
290 information.
291 Similar to Prima::Image::data property, Prima::Icon::mask property
293 provides access to the binary mask data. The mask can be updated
294 automatically, after an icon object was subject to painting, resizing,
295 or other destructive change. The auxiliary properties "::autoMasking"
296 and "::maskColor"/"::maskIndex" regulate mask update procedure. For
297 example, if an icon was loaded with the color ( vs. bitmap )
298 transparency information, the binary mask will be generated anyway, but
299 it will be also recorded that a particular color serves as a
300 transparent indicator, so eventual conversions can rely on the color
301 value, instead of the mask bitmap.
302 If an icon is drawn upon a graphic canvas, the image output is
304 constrained to the mask. On raster displays it is typically simulated
305 by a combination of and- and xor- operation modes, therefore attempts
306 to put an icon with "::rop", different from "rop::CopyPut", usually
307 fail.
308 Layering
310 The term layered window is borrowed from Windows world, and means a
311 window with transparency. In Prima, the property layered is used to
312 select this functionality. The call to
313 "$::application->get_system_value(sv::LayeredWidgets)" can check
314 whether this functionality is available; if not, the property is
315 ignored. By default, widgets can not use layering.
316 A layered drawable uses an extra alpha channel to designate the
318 transparency of the widget. Drawing on widgets will also look different
319 - for example, drawing with black color will make the black pixels
320 fully transparent, while other colors will blend with the underlying
321 background, but never in full. Prima provides no functions to draw with
322 alpha effects, and scarce image functions to address the alpha
323 surfaces. Drawing lines, text, etc with blending is delegated to
324 Prima::Cairo which is a separate module. Prima only provides alpha
325 surfaces and bitmaps with an additional alpha channel to draw upon.
326 However, "put_image" / "stretch_image" functions can operate on
327 surfaces with alpha as source and destination drawables. To address the
328 alpha channel on a drawable with Prima, one has to send either an
329 "Prima::Icon" with "maskType(im::bpp8)", or a layered "DeviceBitmap" to
330 these functions.
331 The corresponding "Prima::DeviceBitmap" type is "dbt::Layered", and is
333 fully compatible with layered widgets in the same fashion as
334 "DeviceBitmap" with type "dbt::Pixmap" is fully compatible with normal
335 widgets. One of ways to put a constant alpha value over a rectangle is
336 this, for example:
337 my $a = Prima::Icon->new(
339 width => 1,
340 height => 1,
341 type => im::RGB,
342 maskType => im::bpp8,
343 data => "\0\0\0",
344 mask => chr( $constant_alpha ),
345 );
346 $drawable-> stretch_image( 0, 0, 100, 100, $a, rop::SrcOver );
347 If displaying a picture with pre-existing alpha channel, you'll need to
349 call premultiply_alpha, because picture renderer assumes that pixel
350 values are premultiplied.
351 Even though addressing alpha values of pixels when drawing on layered
353 surfaces is not straighforward, the conversion between images and
354 device bitmaps fully supports alpha pixels. This means that:
355 * When drawing on an icon with 8-bit alpha channel (argb icon), any
357 changes to alpha values of pixels will be transferred back to the mask
358 property after "end_paint"
359 * Calls to "icon" function on DeviceBitmap with type "dbt::Layered"
361 produce identical argb icons. Calls to "bitmap" on argb icos produce
362 identical layered device bitmaps.
363 * Putting argb icons and layered device bitmap on other drawables
365 yields identical results.
366 Putting of argb source surfaces can be only used with two rops,
368 "rop::SrcOver" (default) and "rop::SrcCopy". The former produces
369 blending effect, while the latter copies alpha bits over to the
370 destination surface. Prima internal implementation of "put_image" and
371 "stretch_image" functions extends the allowed set of rops when
372 operating on images outside the begin_paint/end_paint brackets. These
373 rops support 12 Porter-Duff operators and flags to specify constant
374 alpha values to override the existing alpha channel, if any. See more
375 in "Raster operations" in Prima::Drawable.
376 Caveats: In Windows, mouse events will not be delivered to the layered
378 widget if the pixel under the mouse pointer is fully transparent.
379 See also: examples/layered.pl.
381
383 Prima::Image properties
384 colormap @PALETTE
385 A color palette, used for representing 1, 4, and 8-bit bitmaps,
386 when an image object is to be visualized. @PALETTE contains
387 individual colors component triplets, in RGB format. For example,
388 black-and-white monochrome image may contain colormap as
389 "0,0xffffff".
390 See also "palette".
392 conversion TYPE
394 Selects the type of dithering algorithm to be used for pixel down-
395 sampling. TYPE is one of "ict::XXX" constants:
396 ict::None - no dithering, with static palette or palette optimized by source palette
398 ict::Posterization - no dithering, with optimized palette by source pixels
399 ict::Ordered - fast 8x8 ordered halftone dithering with static palette
400 ict::ErrorDiffusion - error diffusion dithering with static palette
401 ict::Optimized - error diffusion dithering with optimized palette
402 As an example, if a 4x4 color image with every pixel set to
404 RGB(32,32,32), converted to a 1-bit image, the following results
405 occur:
406 ict::None, ict::Posterization:
408 [ 0 0 0 0 ]
409 [ 0 0 0 0 ]
410 [ 0 0 0 0 ]
411 [ 0 0 0 0 ]
412 ict::Ordered:
414 [ 0 0 0 0 ]
415 [ 0 0 1 0 ]
416 [ 0 0 0 0 ]
417 [ 1 0 0 0 ]
418 ict::ErrorDiffusion, ict::Ordered:
420 [ 0 0 1 0 ]
421 [ 0 0 0 1 ]
422 [ 0 0 0 0 ]
423 [ 0 0 0 0 ]
424 Values of these constants are made from "ictp::" in Prima::Const
426 and "ictd::" in Prima::Const constansts.
427 data SCALAR
429 Provides access to the bitmap data. On get-call, returns all bitmap
430 pixels, aligned to 4-byte boundary. On set-call, stores the
431 provided data with same alignment. The alignment can be altered by
432 submitting 'lineSize' write-only flag to set call; the ordering of
433 scan lines can be altered by setting 'reverse' write-only flag (
434 see "Data access" ).
435 height INTEGER
437 Manages the vertical dimension of the image data. On set-call, the
438 image data are changed accordingly to the new height, and depending
439 on "::vScaling" property, the pixel values are either scaled or
440 truncated.
441 lineSize INTEGER
443 A read-only property, returning the length of an image row in
444 bytes, as represented internally in memory. Data returned by
445 "::data" property are aligned with "::lineSize" bytes per row, and
446 setting "::data" expects data aligned with this value, unless
447 "lineSize" is set together with "data" to indicate another
448 alignment. See "Data access" for more.
449 mean
451 Returns mean value of pixels. Mean value is "::sum" of pixel
452 values, divided by number of pixels.
453 palette [ @PALETTE ]
455 A color palette, used for representing 1, 4, and 8-bit bitmaps,
456 when an image object is to be visualized. @PALETTE contains
457 individual color component triplets, in BGR format. For example,
458 black-and-white monochrome image may contain palette as
459 "[0,0,0,255,255,255]".
460 See also "colormap".
462 pixel ( X_OFFSET, Y_OFFSET ) PIXEL
464 Provides per-pixel access to the image data when image object is in
465 disabled paint state. Otherwise, same as "Prima::Drawable::pixel".
466 preserveType BOOLEAN
468 If 1, reverts the image type to its old value if an implicit
469 conversion was called during "end_paint()".
470 rangeHi
472 Returns maximum pixel value in the image data.
473 rangeLo
475 Returns minimum pixel value in the image data.
476 scaling INT
478 Declares the scaling strategy when image is resized. Strategies
479 "ist::None" through "ist::Box" are very fast scalers, others not
480 so.
481 Can be one of "ist:::XXX" constants:
483 ist::None - image will be either stripped (when downsizing)
485 or padded (when upsizing) with zeros
486 ist::Box - image will be scaled using simple box transform
487 ist::BoxX - columns will behave same as in ist::None,
488 rows will behave same as in ist::Box
489 ist::BoxY - rows will behave same as in ist::None,
490 columns will behave same as in ist::Box
491 ist::Triangle - bilinear interpolation
492 ist::Quadratic - 2rd order (quadratic) B-Spline approximation of Gaussian
493 ist::Sinc - sine function
494 ist::Hermite - B-Spline interpolation
495 ist::Cubic - 3rd order (cubic) B-Spline approximation of Gaussian
496 ist::Gaussian - Gaussian transform with gamma=0.5
497 Note: Resampling scaling algorithms (those greater than
499 "ist::Box"), when applied to Icons with 1-bit icon mask, will
500 silently convert the mask in 8-bit and apply the same scaling
501 algorithm to it. This will have great smoothing effect on mask
502 edges if the system supports ARGB layering (see "Layering" ).
503 size WIDTH, HEIGHT
505 Manages dimensions of the image. On set-call, the image data are
506 changed accordingly to the new dimensions, and depending on
507 "::scaling" property, the pixel values are either scaled or
508 truncated.
509 stats ( INDEX ) VALUE
511 Returns one of calculated values, that correspond to INDEX, which
512 is one of the following "is::XXX" constants:
513 is::RangeLo - minimum pixel value
515 is::RangeHi - maximum pixel value
516 is::Mean - mean value
517 is::Variance - variance
518 is::StdDev - standard deviation
519 is::Sum - sum of pixel values
520 is::Sum2 - sum of squares of pixel values
521 The values are re-calculated on request and cached. On set-call
523 VALUE is stored in the cache, and is returned on next get-call.
524 The cached values are discarded every time the image data changes.
525 These values are also accessible via set of alias properties:
527 "::rangeLo", "::rangeHi", "::mean", "::variance", "::stdDev",
528 "::sum", "::sum2".
529 stdDev
531 Returns standard deviation of the image data. Standard deviation
532 is the square root of "::variance".
533 sum Returns sum of pixel values of the image data
535 sum2
537 Returns sum of squares of pixel values of the image data
538 type TYPE
540 Governs the image pixel format type. TYPE is a combination of
541 "im::XXX" constants. The constants are collected in groups:
542 Bit-depth constants provide size of pixel is bits. Their actual
544 value is same as number of bits, so "im::bpp1" value is 1,
545 "im::bpp4" - 4, etc. The valid constants represent bit depths from
546 1 to 128:
547 im::bpp1
549 im::bpp4
550 im::bpp8
551 im::bpp16
552 im::bpp24
553 im::bpp32
554 im::bpp64
555 im::bpp128
556 The following values designate the pixel format category:
558 im::Color
560 im::GrayScale
561 im::RealNumber
562 im::ComplexNumber
563 im::TrigComplexNumber
564 im::SignedInt
565 Value of "im::Color" is 0, whereas other category constants
567 represented by unique bit value, so combination of "im::RealNumber"
568 and "im::ComplexNumber" is possible.
569 There also several mnemonic constants defined:
571 im::Mono - im::bpp1
573 im::BW - im::bpp1 | im::GrayScale
574 im::16 - im::bpp4
575 im::Nibble - im::bpp4
576 im::256 - im::bpp8
577 im::RGB - im::bpp24
578 im::Triple - im::bpp24
579 im::Byte - gray 8-bit unsigned integer
580 im::Short - gray 16-bit unsigned integer
581 im::Long - gray 32-bit unsigned integer
582 im::Float - float
583 im::Double - double
584 im::Complex - dual float
585 im::DComplex - dual double
586 im::TrigComplex - dual float
587 im::TrigDComplex - dual double
588 Bit depths of float- and double- derived pixel formats depend on a
590 platform.
591 The groups can be masked out with the mask values:
593 im::BPP - bit depth constants
595 im::Category - category constants
596 im::FMT - extra format constants
597 The extra formats are the pixel formats, not supported by "::type",
599 but recognized within the combined set-call, like
600 $image-> set(
602 type => im::fmtBGRI,
603 data => 'BGR-BGR-',
604 );
605 The data, supplied with the extra image format specification will
607 be converted to the closest supported format. Currently, the
608 following extra pixel formats are recognized:
609 im::fmtBGR
611 im::fmtRGBI
612 im::fmtIRGB
613 im::fmtBGRI
614 im::fmtIBGR
615 variance
617 Returns variance of pixel values of the image data. Variance is
618 "::sum2", divided by number of pixels minus square of "::sum" of
619 pixel values.
620 width INTEGER
622 Manages the horizontal dimension of the image data. On set-call,
623 the image data are changed accordingly to the new width, and
624 depending on "::scaling" property, the pixel values are either
625 scaled or truncated.
626 Prima::Icon properties
628 autoMasking TYPE
629 Selects whether the mask information should be updated
630 automatically with "::data" change or not. Every "::data" change is
631 mirrored in "::mask", using TYPE, one of "am::XXX" constants:
632 am::None - no mask update performed
634 am::MaskColor - mask update based on ::maskColor property
635 am::MaskIndex - mask update based on ::maskIndex property
636 am::Auto - mask update based on corner pixel values
637 The "::maskColor" color value is used as a transparent color if
639 TYPE is "am::MaskColor". The transparency mask generation
640 algorithm, turned on by "am::Auto" checks corner pixel values,
641 assuming that majority of the corner pixels represents a
642 transparent color. Once such color is found, the mask is generated
643 as in "am::MaskColor" case.
644 "::maskIndex" is the same as "::maskColor", except that it points
646 to a specific color index in the palette.
647 When image "::data" is stretched, "::mask" is stretched
649 accordingly, disregarding the "::autoMasking" value.
650 mask SCALAR
652 Provides access to the transparency bitmap. On get-call, returns
653 all bitmap pixels, aligned to 4-byte boundary in 1-bit format. On
654 set-call, stores the provided transparency data with same
655 alignment.
656 maskColor COLOR
658 When "::autoMasking" set to "am::MaskColor", COLOR is used as a
659 transparency value.
660 maskIndex INDEX
662 When "::autoMasking" set to "am::MaskIndex", INDEXth color in teh
663 current palette is used as a transparency value.
664 maskType INTEGER
666 Is either "im::bpp1" (1) or "im::bpp8" (8). The latter can be used
667 as a layered (argb) source surface to draw with blending effect.
668 Prima::DeviceBitmap properties
670 type INTEGER
671 A read-only property, that can only be set during creation,
672 reflects whether the system bitmap is black-and-white 1-bit
673 ("dbt::Bitmap"), is colored and compatible with widgets
674 ("dbt::Pixmap"), or is colored with alpha channel and compatible
675 with layered widgets ("dbt::Layered").
676 The color depth of a bitmap can be read via "get_bpp()" method;
678 monochrome bitmaps always have bit depth of 1, layered bitmaps have
679 bit depth of 32.
680 Prima::Image methods
682 bitmap
683 Returns newly created Prima::DeviceBitmap instance, with the image
684 dimensions and with the bitmap pixel values copied to.
685 clone %properties
687 Creates a copy of the image and applies %properties. An easy way to
688 create a down-sampled copy, for example.
689 codecs
691 Returns array of hashes, each describing the supported image
692 format. If the array is empty, the toolkit was set up so it can not
693 load and save images.
694 See Prima::image-load for details.
696 This method can be called without object instance.
698 dup Returns a duplicate of the object, a newly created Prima::Image,
700 with all information copied to it.
701 extract X_OFFSET, Y_OFFSET, WIDTH, HEIGHT
703 Returns a newly created image object with WIDTH and HEIGHT
704 dimensions, initialized with pixel data from X_OFFSET and Y_OFFSET
705 in the bitmap.
706 get_bpp
708 Returns the bit depth of the pixel format. Same as "::type &
709 im::BPP".
710 get_handle
712 Returns a system handle for an image object.
713 load (FILENAME or FILEGLOB) [ %PARAMETERS ]
715 Loads image from file FILENAME or stream FILEGLOB into an object,
716 and returns the success flag. The semantics of "load()" is
717 extensive, and can be influenced by PARAMETERS hash. "load()" can
718 be called either in a context of an existing object, then a boolean
719 success flag is returned, or in a class context, then a newly
720 created object ( or "undef" ) is returned. If an error occurs, $@
721 variable contains the error description string. These two
722 invocation semantics are equivalent:
723 my $x = Prima::Image-> create();
725 die "$@" unless $x-> load( ... );
726 and
728 my $x = Prima::Image-> load( ... );
730 die "$@" unless $x;
731 See Prima::image-load for details.
733 NB! When loading from streams on win32, mind "binmode".
735 map COLOR
737 Performs iterative mapping of bitmap pixels, setting every pixel to
738 "::color" property with respect to "::rop" type if a pixel equals
739 to COLOR, and to "::backColor" property with respect to "::rop2"
740 type otherwise.
741 "rop::NoOper" type can be used for color masking.
743 Examples:
745 width => 4, height => 1, data => [ 1, 2, 3, 4]
747 color => 10, backColor => 20, rop => rop::CopyPut
748 rop2 => rop::CopyPut
750 input: map(2) output: [ 20, 10, 20, 20 ]
751 rop2 => rop::NoOper
753 input: map(2) output: [ 1, 10, 3, 4 ]
754 mirror VERTICAL
756 Mirrors the image depending on boolean flag VERTICAL
757 premultiply_alpha CONSTANT_OR_IMAGE
759 Applies premultiplication formula to each pixel
760 pixel = pixel * alpha / 256
762 where alpha either is a constant, or a pixel value in an image
764 resample SRC_LOW, SRC_HIGH, DEST_LOW, DEST_HIGH
766 Performs linear scaling of gray pixel values from range (SRC_LOW -
767 SRC_HIGH) to range (DEST_LOW - DEST_HIGH). Can be used to visualize
768 gray non-8 bit pixel values, by the code:
769 $image-> resample( $image-> rangeLo, $image-> rangeHi, 0, 255);
771 rotate DEGREES
773 Rotates the image by 90, 180, or 270 degrees.
774 save (FILENAME or FILEGLOB), [ %PARAMETERS ]
776 Stores image data into image file FILENAME or stream FILEGLOB, and
777 returns the success flag. The semantics of "save()" is extensive,
778 and can be influenced by PARAMETERS hash. If error occurs, $@
779 variable contains error description string.
780 Note that when saving to a stream, "codecID" must be explicitly
782 given in %PARAMETERS.
783 See Prima::image-load for details.
785 NB! When saving to streams on win32, mind "binmode".
787 to_region
789 Creates a new Prima::Region object with the image as the data
790 source.
791 ui_scale %OPTIONS
793 Resizes the image with smooth scaling. Understands "zoom" and
794 "scaling" options. The "zoom" default value is the one in
795 "$::application->uiScaling", the "scaling" default value is
796 "ist::Quadratic" .
797 See also: "uiScaling" in Application
799 Prima::Image events
801 "Prima::Image"-specific events occur only from inside load call, to
802 report image loading progress. Not all codecs (currently JPEG,PNG,TIFF
803 only) are able to report the progress to the caller. See "Loading with
804 progress indicator" in Prima::image-load for details,
805 "watch_load_progress" in Prima::ImageViewer and "load" in
806 Prima::ImageDialog for suggested use.
807 HeaderReady EXTRAS
809 Called whenever image header is read, and image dimensions and
810 pixel type is changed accordingly to accomodate image data.
811 "EXTRAS" is the hash to be stored later in "{extras}" key on the
813 object.
814 DataReady X, Y, WIDTH, HEIGHT
816 Called whenever image data that cover area designated by
817 X,Y,WIDTH,HEIGHT is acquired. Use "load" option "eventDelay" to
818 limit the rate of "DataReady" event.
819 Prima::Icon methods
821 combine DATA, MASK
822 Copies information from DATA and MASK images into "::data" and
823 "::mask" property. DATA and MASK are expected to be images of same
824 dimension.
825 create_combined DATA, MASK
827 Same as "combine", but to be called as constructor.
828 premultiply_alpha CONSTANT_OR_IMAGE = undef
830 Applies premultiplication formula to each pixel
831 pixel = pixel * alpha / 256
833 where alpha is the corresponding alpha value for each coordinate.
835 Only applicable when "maskType" is <im::bpp8>.
836 split
838 Returns two new Prima::Image objects of same dimension. Pixels in
839 the first is are duplicated from "::data" storage, in the second -
840 from "::mask" storage.
841 ui_scale %OPTIONS
843 Same as "ui_scale" from "Prima::Image", but with few exceptions: It
844 tries to use "ist::Quadratic" only when the system supports ARGB
845 layering. Otherwise, falls back on "ist::Box" scaling algorithm,
846 and also limits the zoom factor to integers (2x, 3x etc) only,
847 because when displayed, the smooth-scaled color plane will not
848 match mask plane downgraded to 0/1 mask, and because box-scaling
849 with non-integer zooms looks ugly.
850 Prima::DeviceBitmap methods
852 icon
853 Returns a newly created Prima::Icon object instance, with the pixel
854 information copied from the object. If the bitmap is layered,
855 returns icons with maskType set to "im::bpp8".
856 image
858 Returns a newly created Prima::Image object instance, with the
859 pixel information copied from the object.
860 get_handle
862 Returns a system handle for a system bitmap object.
863
865 Dmitry Karasik, <dmitry@karasik.eu.org>.
866
868 Prima, Prima::Drawable, Prima::image-load, Prima::codecs.
869 PDL, PDL::PrimaImage, IPA
871 ImageMagick, Prima::Image::Magick
873perl v5.28.1 2019-02-02 pod::Prima::Image(3)