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)

NAME
       Prima::Image - Bitmap routines

SYNOPSIS
	  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-> set(	color => cl::Red, backColor => cl::Green);
	  $::application-> put_image( 100, 100,	$i);

	  # a bitmap is	drawn as specified by destination device colors
	  $::application-> put_image( 200, 100,	$i-> bitmap);

DESCRIPTION
       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
       data.

USAGE
       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
       onPaint.

   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" are	only painting methods that allow drawing on an
       image that is in	its paint-disabled state. Moreover, in such context
       they 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;	the painting
       is performed without switching and without interference with 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	- normal, 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);

       and

	 $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 "ict::Optimized" ( by	default	). It
       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, for different	aims. 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.

       This feature is useful in non-interactive programs, running in
       evnironments 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.

   Prima::Icon
       Prima::Icon inherits all	properties of Prima::Image, and	it also
       provides	a 1-bit	depth transparency mask.  This mask can	also be	loaded
       and saved into image files, if the format supports a 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
       fail.

   Layering
       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 of the widget. 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 no	functions to draw with
       alpha effects, and scarce image functions to address the	alpha
       surfaces. Drawing lines,	text, etc with blending	is delegated to
       Prima::Cairo which is a separate	module.	Prima only provides alpha
       surfaces	and bitmaps with an additional alpha channel to	draw upon.
       However,	"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 and flags to specify constant
       alpha values to override	the existing alpha channel, if any.  See more
       in "Raster operations" in Prima::Drawable.

       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/layered.pl.

API
   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
	   "0,0xffffff".

	   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
	      ict::Ordered	   - 8x8 ordered halftone dithering
	      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
	   occur:

	      ict::None:
		[ 0 0 0	0 ]
		[ 0 0 0	0 ]
		[ 0 0 0	0 ]
		[ 0 0 0	0 ]

	      ict::Ordered:
		[ 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 ]

       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
	   truncated.

       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.

       mean
	   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
	   "[0,0,0,255,255,255]".

	   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. Otherwise, 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()".

       rangeHi
	   Returns maximum pixel value in the image data.

       rangeLo
	   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
	   so.

	   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::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
	   truncated.

       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".

       stdDev
	   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

       sum2
	   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:

	      im::bpp1
	      im::bpp4
	      im::bpp8
	      im::bpp16
	      im::bpp24
	      im::bpp32
	      im::bpp64
	      im::bpp128

	   The following values	designate the pixel format category:

	      im::Color
	      im::GrayScale
	      im::RealNumber
	      im::ComplexNumber
	      im::TrigComplexNumber
	      im::SignedInt

	   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
	   platform.

	   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:

	      im::fmtBGR
	      im::fmtRGBI
	      im::fmtIRGB
	      im::fmtBGRI
	      im::fmtIBGR

       variance
	   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
	   alignment.

       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
       bitmap
	   Returns newly created Prima::DeviceBitmap instance, with the	image
	   dimensions and with the bitmap pixel	values copied to.

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

       codecs
	   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.

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

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

       get_handle
	   Returns a system handle for an image	object.

       load (FILENAME or FILEGLOB) [ %PARAMETERS ]
	   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( ... );

	   and

	      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.

	   Examples:

	      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

       resample	SRC_LOW, SRC_HIGH, DEST_LOW, DEST_HIGH
	   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 by	90, 180, or 270	degrees.

       save (FILENAME or FILEGLOB), [ %PARAMETERS ]
	   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".

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

       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::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
	   object.

       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
       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
	   dimension.

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

       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>.

       split
	   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
       icon
	   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".

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

       get_handle
	   Returns a system handle for a system	bitmap object.

AUTHOR
       Dmitry Karasik, <dmitry@karasik.eu.org>.

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

       PDL, PDL::PrimaImage, IPA

       ImageMagick, Prima::Image::Magick

perl v5.24.1			  2017-03-13		  pod::Prima::Image(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | API | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pod::Prima::Image&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help