Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
pod::Prima::Image(3)  User Contributed Perl Documentation pod::Prima::Image(3)

       Prima::Image - Bitmap routines

	  use Prima qw(Application);

	  # create a new image from scratch
	  my $i	= Prima::Image-> new(
	     width => 32,
	     height => 32,
	     type   => im::BW, # same as im::bpp1 | im::GrayScale

	  # draw something
	  $i-> begin_paint;
	  $i-> color( cl::White);
	  $i-> ellipse(	5, 5, 10, 10);
	  $i-> end_paint;

	  # mangle
	  $i-> size( 64, 64);

	  # file operations
	  $i-> save('a.gif') or	die "Error saving:$@\n";
	  $i-> load('a.gif') or	die "Error loading:$@\n";

	  # draw on screen
	  $::application-> begin_paint;

	  # an image is	drawn as specified by its palette
	  $::application-> put_image( 100, 100,	$i);

	  # a bitmap is	drawn as specified by destination device colors
	  $::application-> set(	color => cl::Red, backColor => cl::Green);
	  $::application-> put_image( 200, 100,	$i-> bitmap);

       Prima::Image, Prima::Icon and Prima::DeviceBitmap are classes for
       bitmap handling,	including file and graphic input and output.
       Prima::Image and	Prima::DeviceBitmap are	descendants of Prima::Drawable
       and represent bitmaps, stored in	memory.	 Prima::Icon is	a descendant
       of Prima::Image and contains a transparency mask	along with the regular

       Images usually are represented as a memory area,	where pixel data are
       stored row-wise.	The Prima toolkit is no	exception, however, it does
       not assume that the GUI system uses the same memory format.  The
       implicit	conversion routines are	called when Prima::Image is about to
       be drawn	onto the screen, for example. The conversions are not always
       efficient, therefore the	Prima::DeviceBitmap class is introduced	to
       represent a bitmap, stored in the system	memory in the system pixel
       format. These two basic classes serve the different needs, but can be
       easily converted	to each	other, with "image" and	"bitmap" methods.
       Prima::Image is a more general bitmap representation, capable of	file
       and graphic input and output, plus it is	supplied with number of
       conversion and scaling functions. The Prima::DeviceBitmap class has
       almost none of additional functionality,	and is targeted	to efficient
       graphic input and output.

       Note: If	you're looking for information how to display an image,	this
       is not the manual page. Look either at Prima::ImageViewer, or use
       "put_image" / "stretch_image" ( Prima::Drawable ) inside	your widget's

   Graphic input and output
       As descendants of Prima::Drawable, all Prima::Image, Prima::Icon	and
       Prima::DeviceBitmap objects are subject to three-state painting mode -
       normal (	disabled ), painting ( enabled ) and informational.
       Prima::DeviceBitmap is, however,	exists only in the enabled state, and
       can not be switched to the other	two.

       When an object enters the enabled state,	it serves as a canvas, and all
       Prima::Drawable operations can be performed on it. When the object is
       back to the disabled state, the graphic information is stored into the
       object associated memory, in the	pixel format, supported	by the
       toolkit.	 This information can be visualized by using one of
       "Prima::Drawable::put_image" group methods. If the object enters	the
       enabled state again, the	graphic	information is presented as an initial
       state of	a bitmap.

       It must be noted, that if an implicit conversion	takes place after an
       object enters and before	it leaves the enabled state, as	it is with
       Prima::Image and	Prima::Icon, the bitmap	is converted to	the system
       pixel format. During such conversion some information can be lost, due
       to down-sampling, and there is no way to	preserve the information. This
       does not	happen with Prima::DeviceBitmap.

       Image objects can be drawn upon images, as well as on the screen	and
       Prima::Widget objects. This operation is	performed via one of
       Prima::Drawable::put_image group	methods	( see Prima::Drawable),	and
       can be called with the image object disregarding	the paint state. The
       following code illustrates the dualism of an image object, where	it can
       serve both as a drawing surface and as a	drawing	tool:

	   my $a = Prima::Image-> create( width	=> 100,	height => 100, type => im::RGB);
	   $a->	begin_paint;
	   $a->	clear;
	   $a->	color( cl::Green);
	   $a->	fill_ellipse( 50, 50, 30, 30);
	   $a->	end_paint;
	   $a->	rop( rop::XorPut);
	   $a->	put_image( 10, 10, $a);
	   $::application-> begin_paint;
	   $::application-> put_image( 0, 0, $a);
	   $::application-> end_paint;

       It must be noted, that "put_image", "stretch_image" and
       "put_image_indirect" only allow "Prima::Image" descendants to be	passed
       as a source image object.  This functionality does not imply that the
       image is	internally switched to the paint-enabled state and back; on
       the contrary, the painting is performed without switching and using
       only Prima's own	code, without using the	system's graphical layer.

       Another special case is a 1-bit ( monochrome ) DeviceBitmap. When it is
       drawn upon a drawable with bit depth greater than 1, the	drawable's
       color and backColor properties are used to reflect 1 and	0 bits,
       respectively. On	a 1-bit	drawable this does not happen, and the color
       properties are not used.

   File	input and output
       Depending on the	toolkit	configuration, images can be read and written
       in different formats. This functionality	in accessible via "load()" and
       "save()"	methods. Prima::image-load is dedicated	to the description of
       loading and saving parameters, that can be passed to the	methods, so
       they can	handle different aspects of file format-specific options, such
       as multi-frame operations, auto conversion when a format	does not
       support a particular pixel format etc. In this document,	"load()" and
       "save()"	methods	are illustrated	only in	their basic, single-frame
       functionality. When called with no extra	parameters, these methods fail
       only if a disk I/O error	occurred or an unknown image format was	used.

       When an image is	loaded,	the old	bitmap memory content is discarded,
       and the image attributes	are changed accordingly	to the loaded image.
       Along with these, an image palette is loaded, if	available, and a pixel
       format is assigned, closest or identical	to the pixel format in the
       image file.

   Pixel formats
       Prima::Image supports a number of pixel formats,	governed by the
       "::type"	property. It is	reflected by an	integer	value, a combination
       of "im::XXX" constants. The whole set of	pixel formats is represented
       by colored formats, like, 16-color, 256-color and 16M-color, and	by
       gray-scale formats, mapped to C data types - unsigned char, unsigned
       short, unsigned long, float and double.	The gray-scale formats are
       further subdivided to real-number formats and complex-number format;
       the last	ones are represented by	two real values	per pixel, containing
       the real	and the	imaginary values.

       Prima::Image can	also be	initialized from other formats,	that it	does
       not support, but	can convert data from. Currently these are represented
       by a set	of permutations	of 32-bit RGBA format, and 24-bit BGR format.
       These formats can only be used in conjunction with "::data" property.

       The conversions can be performed	between	any of the supported formats (
       to do so, "::type" property is to be set-called ). An image of any of
       these formats can be drawn on the screen, but if	the system can not
       accept the pixel	format ( as it is with non-integer or complex formats
       ), the bitmap data are implicitly converted. The	conversion does	not
       change the data if the image is about to	be drawn; the conversion is
       performed only when the image is	about to be served as a	drawing
       surface.	If, by any reason, it is desired that the pixel	format is not
       to be changed, the "::preserveType" property must be set	to 1. It does
       not prevent the conversion, but it detects if the image was implicitly
       converted inside	"end_paint()" call, and	reverts	it to its previous
       pixel format.

       There are situations, when pixel	format must be changed together	while
       down-sampling the image.	One of four down-sampling methods can be
       selected	- no halftoning, 8x8 ordered halftoning, error diffusion, and
       error diffusion combined	with optimized palette.	These can be set to
       the "::conversion" property with	one of "ict::XXX" constants.  When
       there is	no information loss, "::conversion" property is	not used.

       Another special case of conversion is a conversion with a palette. The
       following calls,

	 $image-> type(	im::bpp4);
	 $image-> palette( $palette);


	 $image-> palette( $palette);
	 $image-> type(	im::bpp4);

       produce different results, but none of these takes into account
       eventual	palette	remapping, because "::palette" property	does not
       change bitmap pixel data, but overwrites	palette	information. A proper
       call syntax here	would be

	 $image-> set(
	    palette => $palette,
	    type    => im::bpp4,

       This call produces also palette pixel mapping.  This syntax is most
       powerful	when conversion	is set to those	algorithms that	can take in
       the account the existing	image pixels, to produce an optimized palette.
       These are "ict::Optimized" ( by default ) and "ict::Posterization".
       This syntax not only allows remapping or	downsampling to	a predefined
       colors set, but also can	be used	to limit palette size to a particular
       number, without knowing the actual values of the	final color palette.
       For example, for	an 24-bit image,

	 $image-> set( type => im::bpp8, palette => 32);

       call would calculate colors in the image, compress them to an optimized
       palette of 32 cells and finally converts	to a 8-bit format.

       Instead of "palette" property, "colormap" can also be used.

   Data	access
       The pixel values	can be accessed	in Prima::Drawable style, via
       "::pixel" property. However, Prima::Image introduces several helper
       functions on its	own.

       The "::data" property is	used to	set or retrieve	a scalar
       representation of bitmap	data. The data are expected to be lined	up to
       a 'line size' margin ( 4-byte boundary ), which is calculated as

	 $lineSize = int(( $image->width * ( $image-> type & im::BPP) +	31) / 32) * 4;

       or returned from	the read-only property "::lineSize".

       This is the line	size for the data as lined up internally in memory,
       however "::data"	should not necessarily should be aligned like this,
       and can be accompanied with a write-only	flag 'lineSize'	if pixels are
       aligned differently:

	 $image-> set( width =>	1, height=> 2);
	 $image-> type(	im::RGB);
	 $image-> set(
	    data => 'RGB----RGB----',
	    lineSize =>	7,
	 print $image->	data, "\n";

	 output: RGB-RGB-

       Internally, Prima contains images in memory so that the first scanline
       is the farthest away from the memory start; this	is consistent with
       general Y-axis orientation in Prima drawable terminology, but might be
       inconvenient when importing data	organized otherwise. Another write-
       only boolean flag "reverse" can be set to 1 so data then	are treated as
       if the first scanline of	the image is the closest to the	start of data:

	 $image-> set( width =>	1, height=> 2, type => im::RGB);
	 $image-> set(
	    data => 'RGB-123-',
	    reverse => 1,
	 print $image->	data, "\n";

	 output: RGB-123-

       Although	it is possible to perform all kinds of calculations and
       modification with the pixels, returned by "::data", it is not advisable
       unless the speed	does not matter. Standalone PDL	package	with help of
       PDL::PrimaImage package,	and Prima-derived IPA package provide routines
       for data	and image analysis.  Also, Prima::Image::Magick	connects
       ImageMagick with	Prima.	Prima::Image itself provides only the simplest
       statistic information, namely: lowest and highest pixel values, pixel
       sum, sum	of square pixels, mean,	variance, and standard deviation.

   Standalone usage
       Some of image functionality can be used standalone, with	all other
       parts of	the toolkit being uninitialized. The functionality is limited
       to loading and saving files, and	reading	and writing pixels (outside
       begin_paint only).  All other calls are ignored.	Example:

	  my $i	= Prima::Image->new( size => [5,5]);

       This feature is useful in non-interactive programs, running in
       environments with no GUI	access,	a cgi-script with no access to X11
       display,	for example.  Normally,	Prima fails to start in	such
       situations, but can be told not to initialize its GUI part by
       explicitly operating system-dependent options. To do so,	invoke

	 use Prima::noX11;

       in the beginning	of your	program. See Prima::noX11 for more.

       Generally the standalone	methods	support	all the	OS-specific functions
       (i.e.  color, region, etc), plus	the primitives and "put_image" methods
       support drawing using Porter-Duff operators from	"rop" property (i e
       rop::SrcOver and	above).

       See individual methods and properties in	API that support standalone
       usage, and how they differ from system-dependent	implementation.

       Prima::Icon inherits all	properties of Prima::Image, and	it also
       provides	a transparency mask of either 1	or 8 bits.  This mask can also
       be loaded and saved into	image files, if	the format supports
       transparency information.

       Similar to Prima::Image::data property, Prima::Icon::mask property
       provides	access to the binary mask data.	 The mask can be updated
       automatically, after an icon object was subject to painting, resizing,
       or other	destructive change.  The auxiliary properties "::autoMasking"
       and "::maskColor"/"::maskIndex" regulate	 mask update procedure.	For
       example,	if an icon was loaded with the color ( vs. bitmap )
       transparency information, the binary mask will be generated anyway, but
       it will be also recorded	that a particular color	serves as a
       transparent indicator, so eventual conversions can rely on the color
       value, instead of the mask bitmap.

       If an icon is drawn upon	a graphic canvas, the image output is
       constrained to the mask.	On raster displays it is typically simulated
       by a combination	of and-	and xor- operation modes, therefore attempts
       to put an icon with "::rop", different from "rop::CopyPut", usually

       The term	layered	window is borrowed from	Windows	world, and means a
       window with transparency. In Prima, the property	layered	is used	to
       select this functionality. The call to
       "$::application->get_system_value(sv::LayeredWidgets)" can check
       whether this functionality is available;	if not,	the property is
       ignored.	 By default, widgets can not use layering.

       A layered drawable uses an extra	alpha channel to designate the
       transparency.  Drawing on widgets will also look	different - for
       example,	drawing	with black color will make the black pixels fully
       transparent, while other	colors will blend with the underlying
       background, but never in	full. Prima provides graphics primitives to
       draw using alpha	effects, and some image	functions to address the alpha

       "put_image" / "stretch_image" functions can operate on surfaces with
       alpha as	source and destination drawables. To address the alpha channel
       on a drawable with Prima, one has to send either	an "Prima::Icon" with
       "maskType(im::bpp8)", or	a layered "DeviceBitmap" to these functions.

       The corresponding "Prima::DeviceBitmap" type is "dbt::Layered", and is
       fully compatible	with layered widgets in	the same fashion as
       "DeviceBitmap" with type	"dbt::Pixmap" is fully compatible with normal
       widgets.	One of ways to put a constant alpha value over a rectangle is
       this, for example:

	  my $a	= Prima::Icon->new(
	      width    => 1,
	      height   => 1,
	      type     => im::RGB,
	      maskType => im::bpp8,
	      data     => "\0\0\0",
	      mask     => chr( $constant_alpha ),
	  $drawable-> stretch_image( 0,	0, 100,	100, $a, rop::SrcOver );

       If displaying a picture with pre-existing alpha channel,	you'll need to
       call premultiply_alpha, because picture renderer	assumes	that pixel
       values are premultiplied.

       Even though addressing alpha values of pixels when drawing on layered
       surfaces	is not straighforward, the conversion between images and
       device bitmaps fully supports alpha pixels. This	means that:

       * When drawing on an icon with 8-bit alpha channel (argb	icon), any
       changes to alpha	values of pixels will be transferred back to the mask
       property	after "end_paint"

       * Calls to "icon" function on DeviceBitmap with type "dbt::Layered"
       produce identical argb icons. Calls to "bitmap" on argb icos produce
       identical layered device	bitmaps.

       * Putting argb icons and	layered	device bitmap on other drawables
       yields identical	results.

       Putting of argb source surfaces can be only used	with two rops,
       "rop::SrcOver" (default)	and "rop::SrcCopy". The	former produces
       blending	effect,	while the latter copies	alpha bits over	to the
       destination surface. Prima internal implementation of "put_image" and
       "stretch_image" functions extends the allowed set of rops when
       operating on images outside the begin_paint/end_paint brackets. These
       rops support 12 Porter-Duff operators, some more	"photoshop" operators,
       and special flags to specify constant alpha values to override the
       existing	alpha channel, if any.	See more in "Raster operations"	in

       Caveats:	In Windows, mouse events will not be delivered to the layered
       widget if the pixel under the mouse pointer is fully transparent.

       See also: examples/

   Prima::Image	properties
       colormap	@PALETTE
	   A color palette, used for representing 1, 4,	and 8-bit bitmaps,
	   when	an image object	is to be visualized. @PALETTE contains
	   individual colors component triplets, in RGB	format.	For example,
	   black-and-white monochrome image may	contain	colormap as

	   See also "palette".

       conversion TYPE
	   Selects the type of dithering algorithm to be used for pixel	down-
	   sampling.  TYPE is one of "ict::XXX"	constants:

	      ict::None		   - no	dithering, with	static palette or palette optimized by source palette
	      ict::Posterization   - no	dithering, with	optimized palette by source pixels
	      ict::Ordered	   - fast 8x8 ordered halftone dithering with static palette
	      ict::ErrorDiffusion  - error diffusion dithering with static palette
	      ict::Optimized	   - error diffusion dithering with optimized palette

	   As an example, if a 4x4 color image with every pixel	set to
	   RGB(32,32,32), converted to a 1-bit image, the following results

	      ict::None, ict::Posterization:
		[ 0 0 0	0 ]
		[ 0 0 0	0 ]
		[ 0 0 0	0 ]
		[ 0 0 0	0 ]

		[ 0 0 0	0 ]
		[ 0 0 1	0 ]
		[ 0 0 0	0 ]
		[ 1 0 0	0 ]

	      ict::ErrorDiffusion, ict::Ordered:
		[ 0 0 1	0 ]
		[ 0 0 0	1 ]
		[ 0 0 0	0 ]
		[ 0 0 0	0 ]

	   Values of these constants are made from "ictp::" in Prima::Const
	   and "ictd::"	in Prima::Const	constansts.

       data SCALAR
	   Provides access to the bitmap data. On get-call, returns all	bitmap
	   pixels, aligned to 4-byte boundary. On set-call, stores the
	   provided data with same alignment. The alignment can	be altered by
	   submitting 'lineSize' write-only flag to set	call; the ordering of
	   scan	lines can be altered by	setting	'reverse' write-only flag (
	   see "Data access" ).

       height INTEGER
	   Manages the vertical	dimension of the image data.  On set-call, the
	   image data are changed accordingly to the new height, and depending
	   on "::vScaling" property, the pixel values are either scaled	or

       lineSize	INTEGER
	   A read-only property, returning the length of an image row in
	   bytes, as represented internally in memory. Data returned by
	   "::data" property are aligned with "::lineSize" bytes per row, and
	   setting "::data" expects data aligned with this value, unless
	   "lineSize" is set together with "data" to indicate another
	   alignment. See "Data	access"	for more.

	   Returns mean	value of pixels.  Mean value is	"::sum"	of pixel
	   values, divided by number of	pixels.

       palette [ @PALETTE ]
	   A color palette, used for representing 1, 4,	and 8-bit bitmaps,
	   when	an image object	is to be visualized. @PALETTE contains
	   individual color component triplets,	in BGR format. For example,
	   black-and-white monochrome image may	contain	palette	as

	   See also "colormap".

       pixel ( X_OFFSET, Y_OFFSET ) PIXEL
	   Provides per-pixel access to	the image data when image object is in
	   disabled paint state.

	   Pixel values	for grayscale 1- and 4-	bit images are treated
	   specifically, such that like	8-bit function,	values cover range
	   between 0 and 255. F.ex. pixel values for grayscale 1 bit images
	   are 0 and 255, not 0	and 1.

	   In paint state same as "Prima::Drawable::pixel".

       preserveType BOOLEAN
	   If 1, reverts the image type	to its old value if an implicit
	   conversion was called during	"end_paint()".

	   Returns maximum pixel value in the image data.

	   Returns minimum pixel value in the image data.

       scaling INT
	   Declares the	scaling	strategy when image is resized.	 Strategies
	   "ist::None" through "ist::Box" are very fast	scalers, others	not

	   Can be one of "ist:::XXX" constants:

	     ist::None	    - image will be either stripped (when downsizing)
			      or padded	(when upsizing)	with zeros
	     ist::Box	    - image will be scaled using simple	box transform
	     ist::BoxX	    - columns will behave same as in ist::None,
			      rows will	behave same as in ist::Box
	     ist::BoxY	    - rows will	behave same as in ist::None,
			      columns will behave same as in ist::Box
	     ist::AND	    - when row or columns is to	be shrunk, leftover pixels
			      will be AND-end together (for black on white)
			      (	does not work for floating poing pixels	)
	     ist::OR	    - when row or columns is to	be shrunk, leftover pixels
			      will be OR-end together (for white on black)
			      (	does not work for floating poing pixels	)
	     ist::Triangle  - bilinear interpolation
	     ist::Quadratic - 2rd order	(quadratic) B-Spline approximation of Gaussian
	     ist::Sinc	    - sine function
	     ist::Hermite   - B-Spline interpolation
	     ist::Cubic	    - 3rd order	(cubic)	B-Spline approximation of Gaussian
	     ist::Gaussian  - Gaussian transform with gamma=0.5

	   Note: Resampling scaling algorithms (those greater than
	   "ist::Box"),	when applied to	Icons with 1-bit icon mask, will
	   silently convert the	mask in	8-bit and apply	the same scaling
	   algorithm to	it. This will have great smoothing effect on mask
	   edges if the	system supports	ARGB layering (see "Layering" ).

       size WIDTH, HEIGHT
	   Manages dimensions of the image. On set-call, the image data	are
	   changed accordingly to the new dimensions, and depending on
	   "::scaling" property, the pixel values are either scaled or

       stats ( INDEX ) VALUE
	   Returns one of calculated values, that correspond to	INDEX, which
	   is one of the following "is::XXX" constants:

	      is::RangeLo  - minimum pixel value
	      is::RangeHi  - maximum pixel value
	      is::Mean	   - mean value
	      is::Variance - variance
	      is::StdDev   - standard deviation
	      is::Sum	   - sum of pixel values
	      is::Sum2	   - sum of squares of pixel values

	   The values are re-calculated	on request and cached.	On set-call
	   VALUE is stored in the cache, and is	returned on next get-call.
	   The cached values are discarded every time the image	data changes.

	   These values	are also accessible via	set of alias properties:
	   "::rangeLo",	"::rangeHi", "::mean", "::variance", "::stdDev",
	   "::sum", "::sum2".

	   Returns standard deviation of the image data.  Standard deviation
	   is the square root of "::variance".

       sum Returns sum of pixel	values of the image data

	   Returns sum of squares of pixel values of the image data

       type TYPE
	   Governs the image pixel format type.	TYPE is	a combination of
	   "im::XXX" constants.	The constants are collected in groups:

	   Bit-depth constants provide size of pixel is	bits. Their actual
	   value is same as number of bits, so "im::bpp1" value	is 1,
	   "im::bpp4" -	4, etc.	The valid constants represent bit depths from
	   1 to	128:


	   The following values	designate the pixel format category:


	   Value of "im::Color"	is 0, whereas other category constants
	   represented by unique bit value, so combination of "im::RealNumber"
	   and "im::ComplexNumber" is possible.

	   There also several mnemonic constants defined:

	      im::Mono		- im::bpp1
	      im::BW		- im::bpp1 | im::GrayScale
	      im::16		- im::bpp4
	      im::Nibble	- im::bpp4
	      im::256		- im::bpp8
	      im::RGB		- im::bpp24
	      im::Triple	- im::bpp24
	      im::Byte		- gray 8-bit unsigned integer
	      im::Short		- gray 16-bit unsigned integer
	      im::Long		- gray 32-bit unsigned integer
	      im::Float		- float
	      im::Double	- double
	      im::Complex	- dual float
	      im::DComplex	- dual double
	      im::TrigComplex	- dual float
	      im::TrigDComplex	- dual double

	   Bit depths of float-	and double- derived pixel formats depend on a

	   The groups can be masked out	with the mask values:

	      im::BPP	   - bit depth constants
	      im::Category - category constants
	      im::FMT	   - extra format constants

	   The extra formats are the pixel formats, not	supported by "::type",
	   but recognized within the combined set-call,	like

	      $image-> set(
		 type => im::fmtBGRI,
		 data => 'BGR-BGR-',

	   The data, supplied with the extra image format specification	will
	   be converted	to the closest supported format. Currently, the
	   following extra pixel formats are recognized:


	   Returns variance of pixel values of the image data.	Variance is
	   "::sum2", divided by	number of pixels minus square of "::sum" of
	   pixel values.

       width INTEGER
	   Manages the horizontal dimension of the image data.	On set-call,
	   the image data are changed accordingly to the new width, and
	   depending on	"::scaling" property, the pixel	values are either
	   scaled or truncated.

   Prima::Icon properties
       autoMasking TYPE
	   Selects whether the mask information	should be updated
	   automatically with "::data" change or not. Every "::data" change is
	   mirrored in "::mask", using TYPE, one of "am::XXX" constants:

	      am::None		 - no mask update performed
	      am::MaskColor	 - mask	update based on	::maskColor property
	      am::MaskIndex	 - mask	update based on	::maskIndex property
	      am::Auto		 - mask	update based on	corner pixel values

	   The "::maskColor" color value is used as a transparent color	if
	   TYPE	is "am::MaskColor". The	transparency mask generation
	   algorithm, turned on	by "am::Auto" checks corner pixel values,
	   assuming that majority of the corner	pixels represents a
	   transparent color. Once such	color is found,	the mask is generated
	   as in "am::MaskColor" case.

	   "::maskIndex" is the	same as	"::maskColor", except that it points
	   to a	specific color index in	the palette.

	   When	image "::data" is stretched, "::mask" is stretched
	   accordingly,	disregarding the "::autoMasking" value.

       mask SCALAR
	   Provides access to the transparency bitmap. On get-call, returns
	   all bitmap pixels, aligned to 4-byte	boundary in 1-bit format. On
	   set-call, stores the	provided transparency data with	same

       maskColor COLOR
	   When	"::autoMasking"	set to "am::MaskColor",	COLOR is used as a
	   transparency	value.

       maskIndex INDEX
	   When	"::autoMasking"	set to "am::MaskIndex",	INDEXth	color in teh
	   current palette is used as a	transparency value.

       maskType	INTEGER
	   Is either "im::bpp1"	(1) or "im::bpp8" (8). The latter can be used
	   as a	layered	(argb) source surface to draw with blending effect.

   Prima::DeviceBitmap properties
       type INTEGER
	   A read-only property, that can only be set during creation,
	   reflects whether the	system bitmap is black-and-white 1-bit
	   ("dbt::Bitmap"), is colored and compatible with widgets
	   ("dbt::Pixmap"), or is colored with alpha channel and compatible
	   with	layered	widgets	("dbt::Layered").

	   The color depth of a	bitmap can be read via "get_bpp()" method;
	   monochrome bitmaps always have bit depth of 1, layered bitmaps have
	   bit depth of	32.

   Prima::Image	methods
       bar X1, Y1, X2, Y2
	   Outside the paint state uses	owen implementation for	drawing	a
	   rectangular shape.  The following properties	are respected:
	   "color", "backColor", "rop",	"rop2",	"fillPattern",
	   "fillPatternOffset",	"region". "rop2" accepts either	"rop::CopyPut"
	   or "rop::NoOper" values, to produce either opaque or	transparent
	   fill	pattern	application.

	   Inside the paint state is identical to "Drawable::bar".

	   Returns newly created Prima::DeviceBitmap instance, with the	image
	   dimensions and with the bitmap pixel	values copied to.

       clear [X1, Y1, X2, Y2]
	   Same	as "Drawable::clear" but can be	used also outside of the paint

       clone %properties
	   Creates a copy of the image and applies %properties.	An easy	way to
	   create a down-sampled copy, for example.

	   Returns array of hashes, each describing the	supported image
	   format. If the array	is empty, the toolkit was set up so it can not
	   load	and save images.

	   See Prima::image-load for details.

	   This	method can be called without object instance.

       dup Returns a duplicate of the object, a	newly created Prima::Image,
	   with	all information	copied to it. Does not preserve	graphical
	   properties (color etc).

	   Returns a newly created image object	with WIDTH and HEIGHT
	   dimensions, initialized with	pixel data from	X_OFFSET and Y_OFFSET
	   in the bitmap.

       fill_chord, fill_ellipse, fill_sector, flood_fill
	   Same	as "Drawable::"	functions but can be used also outside of the
	   paint state.

	   Returns the bit depth of the	pixel format. Same as "::type &

	   Returns a system handle for an image	object.

	   Loads image from file FILENAME or stream FILEGLOB into an object,
	   and returns the success flag.  The semantics	of "load()" is
	   extensive, and can be influenced by PARAMETERS hash.	"load()" can
	   be called either in a context of an existing	object,	then a boolean
	   success flag	is returned, or	in a class context, then a newly
	   created object ( or "undef" ) is returned. If an error occurs, $@
	   variable contains the error description string. These two
	   invocation semantics	are equivalent:

	      my $x = Prima::Image-> create();
	      die "$@" unless $x-> load( ... );


	      my $x = Prima::Image-> load( ... );
	      die "$@" unless $x;

	   See Prima::image-load for details.

	   NB! When loading from streams on win32, mind	"binmode".

       map COLOR
	   Performs iterative mapping of bitmap	pixels,	setting	every pixel to
	   "::color" property with respect to "::rop" type if a	pixel equals
	   to COLOR, and to "::backColor" property with	respect	to "::rop2"
	   type	otherwise.

	   "rop::NoOper" type can be used for color masking.


	      width => 4, height => 1, data => [ 1, 2, 3, 4]
	      color => 10, backColor =>	20, rop	=> rop::CopyPut

	      rop2 => rop::CopyPut
	      input: map(2) output: [ 20, 10, 20, 20 ]

	      rop2 => rop::NoOper
	      input: map(2) output: [ 1, 10, 3,	4 ]

       mirror VERTICAL
	   Mirrors the image depending on boolean flag VERTICAL

       premultiply_alpha CONSTANT_OR_IMAGE
	   Applies premultiplication formula to	each pixel

	      pixel = pixel * alpha / 256

	   where alpha either is a constant, or	a pixel	value in an image

       put_image, put_image_indirect, stretch_image
	   Same	as "Drawable::"	functions but can be used also outside of the
	   paint state.

	   Extends raster functionality	to access alpha	channel	either using
	   constant alpha values or "Prima::Icon" as sources. See explanation
	   of "rop::" constants	in "Raster operations" in Prima::Drawable.

	   Performs linear scaling of gray pixel values	from range (SRC_LOW -
	   SRC_HIGH) to	range (DEST_LOW	- DEST_HIGH). Can be used to visualize
	   gray	non-8 bit pixel	values,	by the code:

	      $image-> resample( $image-> rangeLo, $image-> rangeHi, 0,	255);

       rotate DEGREES
	   Rotates the image. Where the	angle is 90, 180, or 270 degrees, fast
	   pixel flipping is used, otherwise fast Paeth	rotation is used.
	   Eventual resampling can be controlled by "scaling" property (
	   probably not	worth it for functions with support of more than 1

	   Resulting images can	be 1 pixel too wide due	to horizontal shearing
	   applied twice, where	in worst cases 1 pixel from the	original image
	   can take 3 horizontal pixels	on the result.

	   Stores image	data into image	file FILENAME or stream	FILEGLOB, and
	   returns the success flag.  The semantics of "save()"	is extensive,
	   and can be influenced by PARAMETERS hash. If	error occurs, $@
	   variable contains error description string.

	   Note	that when saving to a stream, "codecID"	must be	explicitly
	   given in %PARAMETERS.

	   See Prima::image-load for details.

	   NB! When saving to streams on win32,	mind "binmode".

       shear X,	Y
	   Applies shearing to the image. If the shearing is needed only for
	   one axis, set shear factor for the other one	to zero.

	   Creates a new Prima::Region object with the image as	the data

       transform @MATRIX
	   Applies generic 2D transform	matrix to the image, where matrix is 4

	   Tries first to split	matrix into series of shear and	scale
	   transforms using LDU	decomposition; if an interim image needs to be
	   too large, fails and	returns	"false".

	   Rotation matrices can be applied too, however, when angles are
	   close to 90 and 270,	either interim images become too big, or
	   defects introduced by shearing become too visible. Therefore	the
	   method specifically detects for rotation cases, and uses Paeth
	   rotation algorithm instead, which yields better results.  Also, if
	   the angle is	detected to be 90, 180,	or 270 degrees,	fast pixel
	   flipping is used.

	   Eventual resampling can be controlled by "scaling" property.

       ui_scale	%OPTIONS
	   Resizes the image with smooth scaling. Understands "zoom" and
	   "scaling" options. The "zoom" default value is the one in
	   "$::application->uiScaling",	the "scaling" default value is
	   "ist::Quadratic" .

	   See also: "uiScaling" in Application

   Prima::Image	events
       "Prima::Image"-specific events occur only from inside load call,	to
       report image loading progress. Not all codecs (currently	JPEG,PNG,TIFF
       only) are able to report	the progress to	the caller. See	"Loading with
       progress	indicator" in Prima::image-load	for details,
       "watch_load_progress" in	Prima::ImageViewer and "load" in
       Prima::Dialog::ImageDialog for suggested	use.

       HeaderReady EXTRAS
	   Called whenever image header	is read, and image dimensions and
	   pixel type is changed accordingly to	accomodate image data.

	   "EXTRAS" is the hash	to be stored later in "{extras}" key on	the

       DataReady X, Y, WIDTH, HEIGHT
	   Called whenever image data that cover area designated by
	   X,Y,WIDTH,HEIGHT is acquired. Use "load" option "eventDelay"	to
	   limit the rate of "DataReady" event.

   Prima::Icon methods
       alpha ALPHA <X1,	Y1, X2,	Y2>
	   Same	as "Drawable::alpha" but can be	used also outside of the paint

       combine DATA, MASK
	   Copies information from DATA	and MASK images	into "::data" and
	   "::mask" property. DATA and MASK are	expected to be images of same

       create_combined DATA, MASK
	   Same	as "combine", but to be	called as constructor.

       image %opt
	   Renders icon	graphics on a newly created Prima::Image object
	   instance upon black background.  If $opt{background}	is given, it
	   is used instead.

       premultiply_alpha CONSTANT_OR_IMAGE = undef
	   Applies premultiplication formula to	each pixel

	      pixel = pixel * alpha / 256

	   where alpha is the corresponding alpha value	for each coordinate.
	   Only	applicable when	"maskType" is <im::bpp8>.

	   Returns two new Prima::Image	objects	of same	dimension.  Pixels in
	   the first is	are duplicated from "::data" storage, in the second -
	   from	"::mask" storage.

       ui_scale	%OPTIONS
	   Same	as "ui_scale" from "Prima::Image", but with few	exceptions: It
	   tries to use	"ist::Quadratic" only when the system supports ARGB
	   layering. Otherwise,	falls back on "ist::Box" scaling algorithm,
	   and also limits the zoom factor to integers (2x, 3x etc) only,
	   because when	displayed, the smooth-scaled color plane will not
	   match mask plane downgraded to 0/1 mask, and	because	box-scaling
	   with	non-integer zooms looks	ugly.

   Prima::DeviceBitmap methods
       dup Returns a duplicate of the object, a	newly created
	   Prima::DeviceBitmap,	with all information copied to it. Does	not
	   preserve graphical properties (color	etc).

	   Returns a newly created Prima::Icon object instance,	with the pixel
	   information copied from the object. If the bitmap is	layered,
	   returns icons with maskType set to "im::bpp8".

	   Returns a newly created Prima::Image	object instance, with the
	   pixel information copied from the object.

	   Returns a system handle for a system	bitmap object.

       Dmitry Karasik, <>.

       Prima, Prima::Drawable, Prima::image-load, Prima::codecs.

       PDL, PDL::PrimaImage, IPA

       ImageMagick, Prima::Image::Magick

perl v5.32.1			  2022-04-02		  pod::Prima::Image(3)


Want to link to this manual page? Use this URL:

home | help