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 - normal, 8x8 ordered halftoning, error diffusion, and error
177 diffusion combined with optimized palette. These can be set to the
178 "::conversion" property with one of "ict::XXX" constants. When there
179 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 "ict::Optimized" ( by default ). It
204 not only allows remapping or downsampling to a predefined colors set,
205 but also can be used to limit palette size to a particular number,
206 without knowing the actual values of the final color palette. For
207 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, for different aims. The "::data" property is used to set or
220 retrieve a scalar representation of bitmap data. The data are expected
221 to be lined up to a 'line size' margin ( 4-byte boundary ), which is
222 calculated as
223 $lineSize = int(( $image->width * ( $image-> type & im::BPP) + 31) / 32) * 4;
225 or returned from the read-only property "::lineSize".
227 This is the line size for the data as lined up internally in memory,
229 however "::data" should not necessarily should be aligned like this,
230 and can be accompanied with a write-only flag 'lineSize' if pixels are
231 aligned differently:
232 $image-> set( width => 1, height=> 2);
234 $image-> type( im::RGB);
235 $image-> set(
236 data => 'RGB----RGB----',
237 lineSize => 7,
238 );
239 print $image-> data, "\n";
240 output: RGB-RGB-
242 Internally, Prima contains images in memory so that the first scanline
244 is the farthest away from the memory start; this is consistent with
245 general Y-axis orientation in Prima drawable terminology, but might be
246 inconvenient when importing data organized otherwise. Another write-
247 only boolean flag "reverse" can be set to 1 so data then are treated as
248 if the first scanline of the image is the closest to the start of data:
249 $image-> set( width => 1, height=> 2, type => im::RGB);
251 $image-> set(
252 data => 'RGB-123-',
253 reverse => 1,
254 );
255 print $image-> data, "\n";
256 output: RGB-123-
258 Although it is possible to perform all kinds of calculations and
260 modification with the pixels, returned by "::data", it is not advisable
261 unless the speed does not matter. Standalone PDL package with help of
262 PDL::PrimaImage package, and Prima-derived IPA package provide routines
263 for data and image analysis. Also, Prima::Image::Magick connects
264 ImageMagick with Prima. Prima::Image itself provides only the simplest
265 statistic information, namely: lowest and highest pixel values, pixel
266 sum, sum of square pixels, mean, variance, and standard deviation.
267 Standalone usage
269 Some of image functionality can be used standalone, with all other
270 parts of the toolkit being uninitialized. The functionality is limited
271 to loading and saving files, and reading and writing pixels (outside
272 begin_paint only). All other calls are ignored.
273 This feature is useful in non-interactive programs, running in
275 evnironments with no GUI access, a cgi-script with no access to X11
276 display, for example. Normally, Prima fails to start in such
277 situations, but can be told not to initialize its GUI part by
278 explicitly operating system-dependent options. To do so, invoke
279 use Prima::noX11;
281 in the beginning of your program. See Prima::noX11 for more.
283 Prima::Icon
285 Prima::Icon inherits all properties of Prima::Image, and it also
286 provides a 1-bit depth transparency mask. This mask can also be loaded
287 and saved into image files, if the format supports a transparency
288 information.
289 Similar to Prima::Image::data property, Prima::Icon::mask property
291 provides access to the binary mask data. The mask can be updated
292 automatically, after an icon object was subject to painting, resizing,
293 or other destructive change. The auxiliary properties "::autoMasking"
294 and "::maskColor"/"::maskIndex" regulate mask update procedure. For
295 example, if an icon was loaded with the color ( vs. bitmap )
296 transparency information, the binary mask will be generated anyway, but
297 it will be also recorded that a particular color serves as a
298 transparent indicator, so eventual conversions can rely on the color
299 value, instead of the mask bitmap.
300 If an icon is drawn upon a graphic canvas, the image output is
302 constrained to the mask. On raster displays it is typically simulated
303 by a combination of and- and xor- operation modes, therefore attempts
304 to put an icon with "::rop", different from "rop::CopyPut", usually
305 fail.
306 Layering
308 The term layered window is borrowed from Windows world, and means a
309 window with transparency. In Prima, the property layered is used to
310 select this functionality. The call to
311 "$::application->get_system_value(sv::LayeredWidgets)" can check
312 whether this functionality is available; if not, the property is
313 ignored. By default, widgets can not use layering.
314 A layered drawable uses an extra alpha channel to designate the
316 transparency of the widget. Drawing on widgets will also look different
317 - for example, drawing with black color will make the black pixels
318 fully transparent, while other colors will blend with the underlying
319 background, but never in full. Prima provides no functions to draw with
320 alpha effects, and scarce image functions to address the alpha
321 surfaces. Drawing lines, text, etc with blending is delegated to
322 Prima::Cairo which is a separate module. Prima only provides alpha
323 surfaces and bitmaps with an additional alpha channel to draw upon.
324 However, "put_image" / "stretch_image" functions can operate on
325 surfaces with alpha as source and destination drawables. To address the
326 alpha channel on a drawable with Prima, one has to send either an
327 "Prima::Icon" with "maskType(im::bpp8)", or a layered "DeviceBitmap" to
328 these functions.
329 The corresponding "Prima::DeviceBitmap" type is "dbt::Layered", and is
331 fully compatible with layered widgets in the same fashion as
332 "DeviceBitmap" with type "dbt::Pixmap" is fully compatible with normal
333 widgets. One of ways to put a constant alpha value over a rectangle is
334 this, for example:
335 my $a = Prima::Icon->new(
337 width => 1,
338 height => 1,
339 type => im::RGB,
340 maskType => im::bpp8,
341 data => "\0\0\0",
342 mask => chr( $constant_alpha ),
343 );
344 $drawable-> stretch_image( 0, 0, 100, 100, $a, rop::SrcOver );
345 If displaying a picture with pre-existing alpha channel, you'll need to
347 call premultiply_alpha, because picture renderer assumes that pixel
348 values are premultiplied.
349 Even though addressing alpha values of pixels when drawing on layered
351 surfaces is not straighforward, the conversion between images and
352 device bitmaps fully supports alpha pixels. This means that:
353 * When drawing on an icon with 8-bit alpha channel (argb icon), any
355 changes to alpha values of pixels will be transferred back to the mask
356 property after "end_paint"
357 * Calls to "icon" function on DeviceBitmap with type "dbt::Layered"
359 produce identical argb icons. Calls to "bitmap" on argb icos produce
360 identical layered device bitmaps.
361 * Putting argb icons and layered device bitmap on other drawables
363 yields identical results.
364 Putting of argb source surfaces can be only used with two rops,
366 "rop::SrcOver" (default) and "rop::SrcCopy". The former produces
367 blending effect, while the latter copies alpha bits over to the
368 destination surface. Prima internal implementation of "put_image" and
369 "stretch_image" functions extends the allowed set of rops when
370 operating on images outside the begin_paint/end_paint brackets. These
371 rops support 12 Porter-Duff operators and flags to specify constant
372 alpha values to override the existing alpha channel, if any. See more
373 in "Raster operations" in Prima::Drawable.
374 Caveats: In Windows, mouse events will not be delivered to the layered
376 widget if the pixel under the mouse pointer is fully transparent.
377 See also: examples/layered.pl.
379
381 Prima::Image properties
382 colormap @PALETTE
383 A color palette, used for representing 1, 4, and 8-bit bitmaps,
384 when an image object is to be visualized. @PALETTE contains
385 individual colors component triplets, in RGB format. For example,
386 black-and-white monochrome image may contain colormap as
387 "0,0xffffff".
388 See also "palette".
390 conversion TYPE
392 Selects the type of dithering algorithm to be used for pixel down-
393 sampling. TYPE is one of "ict::XXX" constants:
394 ict::None - no dithering
396 ict::Ordered - 8x8 ordered halftone dithering
397 ict::ErrorDiffusion - error diffusion dithering with static palette
398 ict::Optimized - error diffusion dithering with optimized palette
399 As an example, if a 4x4 color image with every pixel set to
401 RGB(32,32,32), converted to a 1-bit image, the following results
402 occur:
403 ict::None:
405 [ 0 0 0 0 ]
406 [ 0 0 0 0 ]
407 [ 0 0 0 0 ]
408 [ 0 0 0 0 ]
409 ict::Ordered:
411 [ 0 0 0 0 ]
412 [ 0 0 1 0 ]
413 [ 0 0 0 0 ]
414 [ 1 0 0 0 ]
415 ict::ErrorDiffusion, ict::Ordered:
417 [ 0 0 1 0 ]
418 [ 0 0 0 1 ]
419 [ 0 0 0 0 ]
420 [ 0 0 0 0 ]
421 data SCALAR
423 Provides access to the bitmap data. On get-call, returns all bitmap
424 pixels, aligned to 4-byte boundary. On set-call, stores the
425 provided data with same alignment. The alignment can be altered by
426 submitting 'lineSize' write-only flag to set call; the ordering of
427 scan lines can be altered by setting 'reverse' write-only flag (
428 see "Data access" ).
429 height INTEGER
431 Manages the vertical dimension of the image data. On set-call, the
432 image data are changed accordingly to the new height, and depending
433 on "::vScaling" property, the pixel values are either scaled or
434 truncated.
435 lineSize INTEGER
437 A read-only property, returning the length of an image row in
438 bytes, as represented internally in memory. Data returned by
439 "::data" property are aligned with "::lineSize" bytes per row, and
440 setting "::data" expects data aligned with this value, unless
441 "lineSize" is set together with "data" to indicate another
442 alignment. See "Data access" for more.
443 mean
445 Returns mean value of pixels. Mean value is "::sum" of pixel
446 values, divided by number of pixels.
447 palette [ @PALETTE ]
449 A color palette, used for representing 1, 4, and 8-bit bitmaps,
450 when an image object is to be visualized. @PALETTE contains
451 individual color component triplets, in BGR format. For example,
452 black-and-white monochrome image may contain palette as
453 "[0,0,0,255,255,255]".
454 See also "colormap".
456 pixel ( X_OFFSET, Y_OFFSET ) PIXEL
458 Provides per-pixel access to the image data when image object is in
459 disabled paint state. Otherwise, same as "Prima::Drawable::pixel".
460 preserveType BOOLEAN
462 If 1, reverts the image type to its old value if an implicit
463 conversion was called during "end_paint()".
464 rangeHi
466 Returns maximum pixel value in the image data.
467 rangeLo
469 Returns minimum pixel value in the image data.
470 scaling INT
472 Declares the scaling strategy when image is resized. Strategies
473 "ist::None" through "ist::Box" are very fast scalers, others not
474 so.
475 Can be one of "ist:::XXX" constants:
477 ist::None - image will be either stripped (when downsizing)
479 or padded (when upsizing) with zeros
480 ist::Box - image will be scaled using simple box transform
481 ist::BoxX - columns will behave same as in ist::None,
482 rows will behave same as in ist::Box
483 ist::BoxY - rows will behave same as in ist::None,
484 columns will behave same as in ist::Box
485 ist::Triangle - bilinear interpolation
486 ist::Quadratic - 2rd order (quadratic) B-Spline approximation of Gaussian
487 ist::Sinc - sine function
488 ist::Hermite - B-Spline interpolation
489 ist::Cubic - 3rd order (cubic) B-Spline approximation of Gaussian
490 ist::Gaussian - Gaussian transform with gamma=0.5
491 Note: Resampling scaling algorithms (those greater than
493 "ist::Box"), when applied to Icons with 1-bit icon mask, will
494 silently convert the mask in 8-bit and apply the same scaling
495 algorithm to it. This will have great smoothing effect on mask
496 edges if the system supports ARGB layering (see Layering ).
497 size WIDTH, HEIGHT
499 Manages dimensions of the image. On set-call, the image data are
500 changed accordingly to the new dimensions, and depending on
501 "::scaling" property, the pixel values are either scaled or
502 truncated.
503 stats ( INDEX ) VALUE
505 Returns one of calculated values, that correspond to INDEX, which
506 is one of the following "is::XXX" constants:
507 is::RangeLo - minimum pixel value
509 is::RangeHi - maximum pixel value
510 is::Mean - mean value
511 is::Variance - variance
512 is::StdDev - standard deviation
513 is::Sum - sum of pixel values
514 is::Sum2 - sum of squares of pixel values
515 The values are re-calculated on request and cached. On set-call
517 VALUE is stored in the cache, and is returned on next get-call.
518 The cached values are discarded every time the image data changes.
519 These values are also accessible via set of alias properties:
521 "::rangeLo", "::rangeHi", "::mean", "::variance", "::stdDev",
522 "::sum", "::sum2".
523 stdDev
525 Returns standard deviation of the image data. Standard deviation
526 is the square root of "::variance".
527 sum Returns sum of pixel values of the image data
529 sum2
531 Returns sum of squares of pixel values of the image data
532 type TYPE
534 Governs the image pixel format type. TYPE is a combination of
535 "im::XXX" constants. The constants are collected in groups:
536 Bit-depth constants provide size of pixel is bits. Their actual
538 value is same as number of bits, so "im::bpp1" value is 1,
539 "im::bpp4" - 4, etc. The valid constants represent bit depths from
540 1 to 128:
541 im::bpp1
543 im::bpp4
544 im::bpp8
545 im::bpp16
546 im::bpp24
547 im::bpp32
548 im::bpp64
549 im::bpp128
550 The following values designate the pixel format category:
552 im::Color
554 im::GrayScale
555 im::RealNumber
556 im::ComplexNumber
557 im::TrigComplexNumber
558 im::SignedInt
559 Value of "im::Color" is 0, whereas other category constants
561 represented by unique bit value, so combination of "im::RealNumber"
562 and "im::ComplexNumber" is possible.
563 There also several mnemonic constants defined:
565 im::Mono - im::bpp1
567 im::BW - im::bpp1 | im::GrayScale
568 im::16 - im::bpp4
569 im::Nibble - im::bpp4
570 im::256 - im::bpp8
571 im::RGB - im::bpp24
572 im::Triple - im::bpp24
573 im::Byte - gray 8-bit unsigned integer
574 im::Short - gray 16-bit unsigned integer
575 im::Long - gray 32-bit unsigned integer
576 im::Float - float
577 im::Double - double
578 im::Complex - dual float
579 im::DComplex - dual double
580 im::TrigComplex - dual float
581 im::TrigDComplex - dual double
582 Bit depths of float- and double- derived pixel formats depend on a
584 platform.
585 The groups can be masked out with the mask values:
587 im::BPP - bit depth constants
589 im::Category - category constants
590 im::FMT - extra format constants
591 The extra formats are the pixel formats, not supported by "::type",
593 but recognized within the combined set-call, like
594 $image-> set(
596 type => im::fmtBGRI,
597 data => 'BGR-BGR-',
598 );
599 The data, supplied with the extra image format specification will
601 be converted to the closest supported format. Currently, the
602 following extra pixel formats are recognized:
603 im::fmtBGR
605 im::fmtRGBI
606 im::fmtIRGB
607 im::fmtBGRI
608 im::fmtIBGR
609 variance
611 Returns variance of pixel values of the image data. Variance is
612 "::sum2", divided by number of pixels minus square of "::sum" of
613 pixel values.
614 width INTEGER
616 Manages the horizontal dimension of the image data. On set-call,
617 the image data are changed accordingly to the new width, and
618 depending on "::scaling" property, the pixel values are either
619 scaled or truncated.
620 Prima::Icon properties
622 autoMasking TYPE
623 Selects whether the mask information should be updated
624 automatically with "::data" change or not. Every "::data" change is
625 mirrored in "::mask", using TYPE, one of "am::XXX" constants:
626 am::None - no mask update performed
628 am::MaskColor - mask update based on ::maskColor property
629 am::MaskIndex - mask update based on ::maskIndex property
630 am::Auto - mask update based on corner pixel values
631 The "::maskColor" color value is used as a transparent color if
633 TYPE is "am::MaskColor". The transparency mask generation
634 algorithm, turned on by "am::Auto" checks corner pixel values,
635 assuming that majority of the corner pixels represents a
636 transparent color. Once such color is found, the mask is generated
637 as in "am::MaskColor" case.
638 "::maskIndex" is the same as "::maskColor", except that it points
640 to a specific color index in the palette.
641 When image "::data" is stretched, "::mask" is stretched
643 accordingly, disregarding the "::autoMasking" value.
644 mask SCALAR
646 Provides access to the transparency bitmap. On get-call, returns
647 all bitmap pixels, aligned to 4-byte boundary in 1-bit format. On
648 set-call, stores the provided transparency data with same
649 alignment.
650 maskColor COLOR
652 When "::autoMasking" set to "am::MaskColor", COLOR is used as a
653 transparency value.
654 maskIndex INDEX
656 When "::autoMasking" set to "am::MaskIndex", INDEXth color in teh
657 current palette is used as a transparency value.
658 maskType INTEGER
660 Is either "im::bpp1" (1) or "im::bpp8" (8). The latter can be used
661 as a layered (argb) source surface to draw with blending effect.
662 Prima::DeviceBitmap properties
664 type INTEGER
665 A read-only property, that can only be set during creation,
666 reflects whether the system bitmap is black-and-white 1-bit
667 ("dbt::Bitmap"), is colored and compatible with widgets
668 ("dbt::Pixmap"), or is colored with alpha channel and compatible
669 with layered widgets ("dbt::Layered").
670 The color depth of a bitmap can be read via "get_bpp()" method;
672 monochrome bitmaps always have bit depth of 1, layered bitmaps have
673 bit depth of 32.
674 Prima::Image methods
676 bitmap
677 Returns newly created Prima::DeviceBitmap instance, with the image
678 dimensions and with the bitmap pixel values copied to.
679 clone %properties
681 Creates a copy of the image and applies %properties. An easy way to
682 create a down-sampled copy, for example.
683 codecs
685 Returns array of hashes, each describing the supported image
686 format. If the array is empty, the toolkit was set up so it can not
687 load and save images.
688 See Prima::image-load for details.
690 This method can be called without object instance.
692 dup Returns a duplicate of the object, a newly created Prima::Image,
694 with all information copied to it.
695 extract X_OFFSET, Y_OFFSET, WIDTH, HEIGHT
697 Returns a newly created image object with WIDTH and HEIGHT
698 dimensions, initialized with pixel data from X_OFFSET and Y_OFFSET
699 in the bitmap.
700 get_bpp
702 Returns the bit depth of the pixel format. Same as "::type &
703 im::BPP".
704 get_handle
706 Returns a system handle for an image object.
707 load (FILENAME or FILEGLOB) [ %PARAMETERS ]
709 Loads image from file FILENAME or stream FILEGLOB into an object,
710 and returns the success flag. The semantics of "load()" is
711 extensive, and can be influenced by PARAMETERS hash. "load()" can
712 be called either in a context of an existing object, then a boolean
713 success flag is returned, or in a class context, then a newly
714 created object ( or "undef" ) is returned. If an error occurs, $@
715 variable contains the error description string. These two
716 invocation semantics are equivalent:
717 my $x = Prima::Image-> create();
719 die "$@" unless $x-> load( ... );
720 and
722 my $x = Prima::Image-> load( ... );
724 die "$@" unless $x;
725 See Prima::image-load for details.
727 NB! When loading from streams on win32, mind "binmode".
729 map COLOR
731 Performs iterative mapping of bitmap pixels, setting every pixel to
732 "::color" property with respect to "::rop" type if a pixel equals
733 to COLOR, and to "::backColor" property with respect to "::rop2"
734 type otherwise.
735 "rop::NoOper" type can be used for color masking.
737 Examples:
739 width => 4, height => 1, data => [ 1, 2, 3, 4]
741 color => 10, backColor => 20, rop => rop::CopyPut
742 rop2 => rop::CopyPut
744 input: map(2) output: [ 20, 10, 20, 20 ]
745 rop2 => rop::NoOper
747 input: map(2) output: [ 1, 10, 3, 4 ]
748 mirror VERTICAL
750 Mirrors the image depending on boolean flag VERTICAL
751 premultiply_alpha CONSTANT_OR_IMAGE
753 Applies premultiplication formula to each pixel
754 pixel = pixel * alpha / 256
756 where alpha either is a constant, or a pixel value in an image
758 resample SRC_LOW, SRC_HIGH, DEST_LOW, DEST_HIGH
760 Performs linear scaling of gray pixel values from range (SRC_LOW -
761 SRC_HIGH) to range (DEST_LOW - DEST_HIGH). Can be used to visualize
762 gray non-8 bit pixel values, by the code:
763 $image-> resample( $image-> rangeLo, $image-> rangeHi, 0, 255);
765 rotate DEGREES
767 Rotates the image by 90, 180, or 270 degrees.
768 save (FILENAME or FILEGLOB), [ %PARAMETERS ]
770 Stores image data into image file FILENAME or stream FILEGLOB, and
771 returns the success flag. The semantics of "save()" is extensive,
772 and can be influenced by PARAMETERS hash. If error occurs, $@
773 variable contains error description string.
774 Note that when saving to a stream, "codecID" must be explicitly
776 given in %PARAMETERS.
777 See Prima::image-load for details.
779 NB! When saving to streams on win32, mind "binmode".
781 to_region
783 Creates a new Prima::Region object with the image as the data
784 source.
785 ui_scale %OPTIONS
787 Resizes the image with smooth scaling. Understands "zoom" and
788 "scaling" options. The "zoom" default value is the one in
789 "$::application->uiScaling", the "scaling" default value is
790 "ist::Quadratic" .
791 See also: "uiScaling" in Application
793 Prima::Image events
795 "Prima::Image"-specific events occur only from inside load call, to
796 report image loading progress. Not all codecs (currently JPEG,PNG,TIFF
797 only) are able to report the progress to the caller. See "Loading with
798 progress indicator" in Prima::image-load for details,
799 "watch_load_progress" in Prima::ImageViewer and "load" in
800 Prima::ImageDialog for suggested use.
801 HeaderReady EXTRAS
803 Called whenever image header is read, and image dimensions and
804 pixel type is changed accordingly to accomodate image data.
805 "EXTRAS" is the hash to be stored later in "{extras}" key on the
807 object.
808 DataReady X, Y, WIDTH, HEIGHT
810 Called whenever image data that cover area designated by
811 X,Y,WIDTH,HEIGHT is acquired. Use "load" option "eventDelay" to
812 limit the rate of "DataReady" event.
813 Prima::Icon methods
815 combine DATA, MASK
816 Copies information from DATA and MASK images into "::data" and
817 "::mask" property. DATA and MASK are expected to be images of same
818 dimension.
819 create_combined DATA, MASK
821 Same as "combine", but to be called as constructor.
822 premultiply_alpha CONSTANT_OR_IMAGE = undef
824 Applies premultiplication formula to each pixel
825 pixel = pixel * alpha / 256
827 where alpha is the corresponding alpha value for each coordinate.
829 Only applicable when "maskType" is <im::bpp8>.
830 split
832 Returns two new Prima::Image objects of same dimension. Pixels in
833 the first is are duplicated from "::data" storage, in the second -
834 from "::mask" storage.
835 ui_scale %OPTIONS
837 Same as "ui_scale" from "Prima::Image", but with few exceptions: It
838 tries to use "ist::Quadratic" only when the system supports ARGB
839 layering. Otherwise, falls back on "ist::Box" scaling algorithm,
840 and also limits the zoom factor to integers (2x, 3x etc) only,
841 because when displayed, the smooth-scaled color plane will not
842 match mask plane downgraded to 0/1 mask, and because box-scaling
843 with non-integer zooms looks ugly.
844 Prima::DeviceBitmap methods
846 icon
847 Returns a newly created Prima::Icon object instance, with the pixel
848 information copied from the object. If the bitmap is layered,
849 returns icons with maskType set to "im::bpp8".
850 image
852 Returns a newly created Prima::Image object instance, with the
853 pixel information copied from the object.
854 get_handle
856 Returns a system handle for a system bitmap object.
857
859 Dmitry Karasik, <dmitry@karasik.eu.org>.
860
862 Prima, Prima::Drawable, Prima::image-load, Prima::codecs.
863 PDL, PDL::PrimaImage, IPA
865 ImageMagick, Prima::Image::Magick
867perl v5.28.0 2017-03-13 pod::Prima::Image(3)