=head1 NAME
Prima::Drawable - generic 2-D graphic interface
=head1 SYNOPSIS
if ( $object-> isa('Prima::Drawable')) {
$object-> begin_paint;
$object-> color( cl::Black);
$object-> line( 100, 100, 200, 200);
$object-> ellipse( 100, 100, 200, 200);
$object-> end_paint;
}
=head1 DESCRIPTION
Prima::Drawable is a descendant of the Prima::Component class. It provides
access to the system graphic context and canvas through its methods and
properties. The Prima::Drawable descendants Prima::Widget, Prima::Image,
Prima::DeviceBitmap, and Prima::Printer are backed by system-dependent routines
that allow drawing and painting on the system objects.
=head1 USAGE
Prima::Drawable, as well as its ancestors Prima::Component and Prima::Object,
is never used directly because the Prima::Drawable class by itself provides
only the interface. It provides a three-state object access - when drawing and
painting are enabled, when these are disabled, and the information acquisition
state. By default, the object is created in a paint-disabled state. To switch
to the enabled state, the begin_paint() method is used. Once in the enabled state,
the object drawing and painting methods apply to the system canvas. To return
to the disabled state, the end_paint() method is called. The information state
can be managed by using begin_paint_info() and end_paint_info() methods pair.
An object cannot be triggered from the information state to the enabled state (
and vice versa ) directly.
=head2 Graphic context and canvas
The graphic context is the set of variables, that control how exactly
graphic primitives are rendered. The variable examples are color, font,
line width, etc.
Another term used here is I<canvas> - the graphic area of a certain extent,
connected to the Prima object, where the drawing and painting methods are used.
In all three states, a graphic context is allowed to be modified, but in
different ways. In the disabled state, a graphic context value is saved as a
template; when an object enters the information or the enabled state, all
values are preserved, but when the object is back to the disabled state, the
graphic context is restored to the values last assigned before entering the
enabled state. The code example below illustrates the idea:
$d = Prima::Drawable-> new;
$d-> lineWidth( 5);
$d-> begin_paint_info;
$d-> lineWidth( 1);
$d-> end_paint_info;
( Note: C<::region> and C<::clipRect> properties are exceptions. They cannot
be used in the disabled state. The values of these properties, as well as the
property C<::matrix> are neither recorded nor used as a template).
That is, in the disabled state any Drawable maintains only the graphic context values.
To draw on a canvas, the object must enter the enabled state by calling begin_paint().
This function can be unsuccessful because the object binds with system resources
during this stage, and allocation of those may fail. Only after the enabled state is entered,
the canvas is accessible:
$d = Prima::Image-> new( width => 100, height => 100);
if ( $d-> begin_paint) {
$d-> color( cl::Black);
$d-> bar( 0, 0, $d-> size);
$d-> color( cl::White);
$d-> fill_ellipse( $d-> width / 2, $d-> height / 2, 30, 30);
$d-> end_paint;
} else {
die "can't draw on image:$@";
}
Different objects are mapped to different types of canvases -
C<Prima::Image> canvas retains its content after end_paint(),
C<Prima::Widget> maps it to some screen area, which content
more transitory, etc.
The information state is as same as the enabled state, but the changes to
the canvas are not visible. Its sole purpose is to read, not to write information.
Because begin_paint() requires some amount of system resources, there is
a chance that a resource request can fail, for any reason. The begin_paint_info()
requires some resources as well, but usually much less, and therefore
if only information is desired, it is usually faster and cheaper to
obtain it inside the information state. A notable example is the
get_text_width() method, which returns the length of a text string in pixels.
It works in both enabled and information states, but code
$d = Prima::Image-> new( width => 10000, height => 10000);
$d-> begin_paint;
$x = $d-> get_text_width('A');
$d-> end_paint;
is much more expensive than
$d = Prima::Image-> new( width => 10000, height => 10000);
$d-> begin_paint_info;
$x = $d-> get_text_width('A');
$d-> end_paint_info;
for the obvious reasons.
It must be noted that some information methods like get_text_width()
work even under the disabled state; the object is switched to
the information state implicitly if it is necessary.
See also: L</graphic_context>.
=head2 Color space
Graphic context and canvas operations rely completely
on a system implementation. The internal canvas color representation
is therefore system-specific, and usually could not be described
in Prima definitions. Often the only information available
about color space is its color depth.
Therefore all color manipulations, including dithering and antialiasing are
subject to system implementation, and can not be controlled from perl code.
When a property is set on the object in the disabled state, it is recorded
verbatim; color properties are no exception. After the object switches to the
enabled state, a color value is translated to the system color representation,
which might be different from Prima's. For example, if the display color depth
is 15 bits, 5 bits for every component, then the white color value 0xffffff is
mapped to
11111000 11111000 11111000
--R----- --G----- --B-----
that equals to 0xf8f8f8, not 0xffffff ( See L<Prima::gp-problems> for
inevident graphic issues discussion ).
The Prima::Drawable color format is RRGGBB, with each component
resolution of 8 bits, thus allowing 2^24 color combinations. If the device color space
depth is different, the color is truncated or expanded automatically. In
case the device color depth is insufficient, dithering algorithms may apply.
Note: not only color properties but all graphic context properties
allow all possible values in the disabled state, which are translated into
system-allowed values when entering the enabled and the information states.
This feature can be used to test if a graphic device is capable of
performing certain operations ( for example,
if it supports raster operations - the printers usually do not ). Example:
$d-> begin_paint;
$d-> rop( rop::Or);
if ( $d-> rop != rop::Or) {
...
}
$d-> end_paint;
There are two color properties on each drawable -
C<::color> and C<::backColor>. The values they operate are unsigned integers
in the discussed above RRGGBB 24-bit format, however, the toolkit defines
some mnemonic color constants as well:
cl::Black
cl::Blue
cl::Green
cl::Cyan
cl::Red
cl::Magenta
cl::Brown
cl::LightGray
cl::DarkGray
cl::LightBlue
cl::LightGreen
cl::LightCyan
cl::LightRed
cl::LightMagenta
cl::Yellow
cl::White
cl::Gray
It is not unlikely that if a device's color depth
is insufficient, the primitives
could be drawn with dithered or incorrect colors. This usually happens
on paletted displays, with 256 or fewer colors.
There exist two methods that facilitate the correct color representation.
The first way is to get as much information as possible about the device.
The methods get_nearest_color() and get_physical_palette()
provide a possibility to avoid mixed colors drawing by obtaining
indirect information about solid colors, supported by a device.
Another method is to use the C<::palette> property. It works by insertingthe colors into the system palette, so if an application
knows the colors it needs beforehand, it can employ this method - however,
this might result in a system palette flash when a window focus toggles.
Both of these methods are applicable both with drawing routines and image output.
An application that desires to display an image with the least distortion is advised to
export its palette to an output device because images usually are not
subject to automatic dithering algorithms. The Prima::ImageViewer module
employs this scheme.
=head2 Antialiasing and alpha
If the system has the capability for antialiased drawing and alpha rendering, Prima
can use it. The render mode can be turned on by calling $drawable->antialias(1)
which turns on the following effects:
=over
=item *
All primitives except images, C<pixel>, and C<bar_alpha> can be plotted with
antialiased edges (text is always antialiased when possible)
=item *
Graphic coordinates are then used as floating point numbers, not integers. That
means that f ex a call
$drawable->rectangle(5.3, 5.3, 10, 10)
that had its coordinates automatically rounded to (5,5,10,10), now will render
the primitive with subpixel precision, where its two edges will be divided
between pixels 5 and 6, by using half-tones.
Another note on the rounding of coordinates: historically almost all Prima
pixel coordinates were integers, and implicit rounding of the passed numbers
was done using the C<int> function, i e int(0.7)=0 and int(-0.7)=0. This was
later changed, breaking some backward compatibility, and now the rounding
function is a more robust C<R = floor(x + 0.5)>, where C<R(0.7) = 1> and
C<R(-0.7) = -1>.
=item *
The coordinate offset (0,0) moves to the ephemeral point between screen pixels
(0,0),(-1,0),(-1,-1),(0,-1), which in turn leads to different results when
plotting closed shapes. F.ex. an ellipse with a diameter of 3 pixels looks
like this:
=for podview <img src="aa2.gif" cut=1 title="3px ellipse and origin of the coordinate grid">
=for html <p>
<figure>
<figcaption>3px ellipse and origin of the coordinate grid</figcaption>
</figure>
<!--
Origin of the coordinate grid (0,0)
^ ^
| |
. |____ . . - . .
|XXX| |
|XXX| |
--|---|---|---> --|---X---|--->
| |
| |
. - . . . - . .
| |
antialias(0) antialias(1)
Ellipse with a diameter of 3 pixels
^ ^
|XXX X|X
. |XXX. . . XX-XX . .
XXX|XXX XXX XXX|XXX
XXX|XXX XXX X XXX|XXX X
--|---|---|---> --|---|---|.-->
|XXX X XXX|XXX X
|XXX XXX|XXX
. - . . . XX-XX . .
| X|X
| |
antialias(0) antialias(1)
=for html -->
=for podview </cut>
That is why if you need to draw a robust graphic routine that would have
more or less identical results in both antialiasing modes, the closed
shapes may need to decrease the diameter by 1 pixel when the antialiasing mode
is set.
=back
For the cases where the system does not support antialiasing, Prima provides
the L<Prima::Drawable::Antialias> emulation class, available through the
C<new_aa_surface> call.
To see if alpha and antialiasing are supported on the system, check the
C<sv::Antialias> value. To see if a particular drawable supports alpha
layering, check the C<can_draw_alpha> method.
Note that in the render mode, all painting operations treat the alpha channel
differently, which can have a dramatic difference on layered surfaces. In the
normal mode, the alpha channel is completely ignored, and using normal mode
paints on a layered widget always produces a translucent window because the
alpha value will always be 0, and the color bits are assumed to be already
premultiplied. In the render mode, the alpha channel is addressed by the C<alpha>
property when drawing primitives, or in the C<mask> property when drawing icons
(again, drawing images and non-layered bitmaps assumes alpha = 0). The same is
valid for fill pattern images and fill pattern icons.
=head2 Monochrome bitmaps
Prima has special rules when drawing a monochrome Prima::DeviceBitmap.
Such objects don't possess an inherent color palette,
and by definition are bitmaps with only two pixel values present, 0s and
1s. When a monochrome bitmap is drawn, 0s are painted using the color value of the target canvas
C<color> property, and 1s using the C<backColor> value.
That means that the following code
$bitmap-> color(0);
$bitmap-> line(0,0,100,100);
$target-> color(cl::Green);
$target-> put_image(0,0,$bitmap);
produces a green line on C<$target>.
When using monochrome bitmaps for logical operations, note that the target colors
should not be explicit 0 and 0xffffff, nor C<cl::Black> and C<cl::White>, but
C<cl::Clear> and C<cl::Set> instead. The reason is that on paletted displays,
the system palette may not necessarily contain the white color under palette index
(2^ScreenDepth-1). C<cl::Set> thus signals that the value should be "all ones",
no matter what color it represents because it will be used for logical
operations.
=head2 Fonts
Prima maintains its own font naming convention which usually does not conform
to the system's. Since Prima's goal is interoperability, it might be so that
some system fonts would not be accessible from within the toolkit.
Prima::Drawable provides property C<::font> that accepts/returns a hash,
that represents the state of a font in the system graphic context.
The font hash keys that are acceptable on the set-call are:
=over 4
=item name
The font name string. If there is no such font, a default font name is used. To
select the default font, a 'Default' string can be passed with the same result
( unless the system has a font named 'Default', of course).
=item height
An integer value from 1 to MAX_INT. Specifies the desired extent of a font
glyph between descent and ascent lines in pixels.
=item size
An integer value from 1 to MAX_INT. Specifies the desired
extent of a font glyph between descent and internal leading lines in
points. The relation between C<size> and C<height> is
height - internal_leading
size = --------------------------- * 72.27
resolution
That differs from some other system representations:
Win32, for example, rounds 72.27 constant to 72.
=item width
An integer value from 0 to MAX_INT. If greater than 0, specifies the desired
extent of a font glyph width in pixels. If 0, sets the default ( designed )
width corresponding to the font size or height.
=item style
A combination of C<fs::> ( font style ) constants. The constants
fs::Normal
fs::Bold
fs::Thin
fs::Italic
fs::Underlined
fs::StruckOut
fs::Outline
can be OR-ed together to express the font style.
fs::Normal equals 0 and is usually never used.
If some styles are not supported by a system-dependent font subsystem,
they are ignored.
=item pitch
One of three constants:
fp::Default
fp::Fixed
fp::Variable
C<fp::Default> specifies no interest in the font pitch selection. C<fp::Fixed>
is set when a monospaced (all glyphs are of the same width) font is desired.
C<fp::Variable> pitch specifies a font with different glyph widths. This key is
of the highest priority; all other keys may be altered for the consistency of
the pitch key.
=item vector
One of three constants:
fv::Default
fv::Bitmap
fv::Outline
C<fv::Default> specifies no interest in the font type selection,
C<fv::Bitmap> sets the priority for the bitmap fonts, and C<fv::Outline> for
the vector fonts.
Additionally, font entries returned from the C<fonts> method may set the
C<vector> field to C<fv::ScalableBitmap>, to distinguish a bitmap font face
that comes with predefined bitmap sets from a scalable font.
=item direction
A counter-clockwise rotation angle - 0 is default, 90 is pi/2, 180 is pi, etc.
If a font cannot be rotated, it is usually substituted with the one that can.
=item encoding
A string value, one of the strings returned by
C<Prima::Application::font_encodings>. Selects the desired font
encoding; if empty, picks the first matched encoding, preferably
the locale set up by the user.
The encodings provided by different systems are different;
in addition, the only encodings are recognizable by the system,
that are represented by at least one font in the system.
Unix systems and the toolkit PostScript interface usually
provide the following encodings:
iso8859-1
iso8859-2
... other iso8859 ...
fontspecific
Win32 returns the literal strings like
Western
Baltic
Cyrillic
Hebrew
Symbol
=back
A hash that C<::font> returns, is a tied hash, whose
keys are also available as separate properties.
For example,
$x = $d-> font-> {style};
is equivalent to
$x = $d-> font-> style;
While the latter gives nothing but the arguable coding convenience, its
usage in set-call is much more usable:
$d-> font-> style( fs::Bold);
instead of
my %temp = %{$d-> font};
$temp{ style} = fs::Bold;
$d-> font( \%temp);
The properties of a font-tied hash are also accessible through the set() call,
like in Prima::Object:
$d-> font-> style( fs::Bold);
$d-> font-> width( 10);
is an equivalent to
$d-> font-> set(
style => fs::Bold,
width => 10,
);
When get-called, the C<::font> property returns a hash where
more entries than those described above can be found. These keys
are read-only, their values are ignored if passed to C<::font>
in a set-call.
To query the full list of fonts available to
a graphic device, the C<::fonts> method is used. This method is
not present in the Prima::Drawable namespace; it can be found in two
built-in class instances, C<Prima::Application> and C<Prima::Printer>.
C<Prima::Application::fonts> returns metrics for the fonts available to
the screen device, while C<Prima::Printer::fonts> ( or its substitute Prima::PS::Printer )
returns fonts for the printing device. The result of this method is an
array of font metrics, fully analogous to these
returned by the C<Prima::Drawable::font> method.
=over 4
=item family
A string with font family name. The family is a
secondary string key, used for distinguishing between
fonts with the same name but of different vendors ( for example,
Adobe Courier and Microsoft Courier).
=item ascent
Number of pixels between a glyph baseline and descent line.
=item descent
Number of pixels between a glyph baseline and descent line.
=item internalLeading
Number of pixels between ascent and internal leading lines.
Negative if the ascent line is below the internal leading line.
=item externalLeading
Number of pixels between ascent and external leading lines.
Negative if the ascent line is above the external leading line.
=for podview <img src="leadings.gif" cut=1 title="Horizontal font measurements">
=for html <p>
<figure>
<figcaption>Horizontal font measurements</figcaption>
</figure>
<!--
------------- external leading line
$ ------------- ascent line
$ $
------------- internal leading line
$
$$$
$ $
$ $ $
$$$$$$$ $$$
$ $ $ $
$ $ $ $
$ $ $$$ ---- baseline
$
$
$
$$$$ ---- descent line
=for html -->
=for podview </cut>
=item weight
Font designed weight. Can be one of
fw::UltraLight
fw::ExtraLight
fw::Light
fw::SemiLight
fw::Medium
fw::SemiBold
fw::Bold
fw::ExtraBold
fw::UltraBold
constants.
=item maximalWidth
The maximal extent of a glyph in pixels. Equals to B<width> in
monospaced fonts.
=item xDeviceRes
Designed horizontal font resolution in dpi.
=item yDeviceRes
Designed vertical font resolution in dpi.
=item firstChar
Index of the first glyph present in a font.
=item lastChar
Index of the last glyph present in a font.
=item breakChar
Index of the default character used to divide words.
In a typical Western language font it is 32, the ASCII space character.
=item defaultChar
Index of a glyph that is drawn instead of a nonexistent
glyph if its index is passed to the text drawing routines.
=item underlinePosition
Position below baseline where to draw underscore line, in pixels.
Is negative.
=item underlineThickness
Pixel width of the underscore line
=item colored
True if the font has COLR/CPAL information and Prima is compiled with its support,
so that f ex emoji fonts are displayed with full color.
Same as C<Prima::Drawable::is_font_colored>
=back
=head2 Font ABC metrics
Besides these characteristics, every font glyph has an ABC metric,
the three integer values that describe the horizontal extents of a
glyph's black part relative to the glyph extent:
=for podview <img src="fontabc.gif" cut=1 title="Vertical glyph measurements">
. . . . . . . .
. . $$$. . . . .
. . $$. $ . . . .
. . $$. . . . $$ . .
. $$$$$$$$$$. . .$$$$$ . .
. . $$ . . . $ $$ . .
. . $$ . . . .$$$$$ . .
. . $$ . . . . $$ . .
. .$$ . . . . $$$ $$$. .
$$ .$$ . . . $ $$ .
.$$$ . . . .$$$$$$$$. .
. . . . . . . .
<A>. .<C> <A>. .<C>
.<-.--B--.->. . .<--B--->. .
A = -3 A = 3
B = 13 B = 10
C = -3 C = 3
=for html -->
=for podview </cut>
A and C are negative, if a glyph 'hangs' over its neighbors,
as shown in the picture on the left. A and C values are positive if a glyph contains
empty space in front or behind the neighbor glyphs, like in the picture on the right.
As can be seen, B is the width of a glyph's black part.
ABC metrics are returned by the get_font_abc() method.
The corresponding vertical metrics, called C<DEF> metrics, are returned
by the get_font_def() method.
=head2 Raster operations
The Prima::Drawable class has two raster operation properties: C<::rop> and
C<::rop2>. These define how the graphic primitives are plotted. C<::rop> deals
with the foreground color drawing, and C<::rop2> with the background.
=head3 Universal ROPs
The toolkit defines the following operations:
=for podview <img src="rop1.gif" cut=1 title="Classic raster operations">
rop::Blackness
rop::NotOr
rop::NotSrcAnd
rop::NotPut
rop::NotDestAnd
rop::Invert
rop::XorPut
rop::NotAnd
rop::AndPut
rop::NotXor
rop::NotSrcXor
rop::NotDestXor
rop::NoOper
rop::NotSrcOr
rop::CopyPut
rop::NotDestOr
rop::OrPut
rop::Whiteness
=for html -->
=for podview </cut>
Usually, however, graphic devices support only a small part of the above set,
limiting C<::rop> to the most important operations: Copy, And, Or, Xor, NoOp.
C<::rop2> is usually even more restricted, and supports only Copy and NoOp.
The raster operations apply to all graphic primitives except SetPixel.
Note for layering: using layered images and device bitmaps with
C<put_image> and C<stretch_image> can only use C<rop::SrcCopy> and C<rop::Blend>raster operations on OS-provided surfaces. See more on C<rop::Blend> below.
Also, the C<rop::AlphaCopy> operation is available for accessing alpha bits only.
When used, the source image is treated as an alpha mask, and therefore it has to
be grayscale. It can be used to apply the alpha bits independently, without
the need to construct an Icon object.
=head3 rop::Blend
C<rop::Blend> is the same as C<rop::SrcOver> except the source pixels are assumed
to be already premultiplied with the source alpha. This is the default raster operation
when drawing with 8-bit icon masks or on layered surfaces, and it reflects the
expectation of the OS that images come premultiplied.
This is the only blending operator supported on the widgets and bitmaps, and it
is advised to premultiply image pixels before drawing images using it with a
call to the C<Image.premultiply_alpha> method. The core image drawing supports
this operator in case these premultiplied images are to be used not only on
native surfaces but also on Prima images.
=head3 Default raster operations
The C<put_image>, C<stretch_image>, and C<put_image_indirect> methods are
allowed to be called without explicitly specifying the ROP to be used. In this
case, the I<default ROP>, that depends on the source drawable, will be used. In
the majority of cases the default ROP is C<rop::CopyPut>, however, when drawing
using layered device bitmaps and icons with 8-bit alpha masks, C<rop::Blend> is
used instead. This is a sort of a DWIM behavior.
This effect is achieved by translating the C<rop::Default> constant via the
C<get_effective_rop> method, that can be used to detect what is the preferred
raster operation for a source drawable. C<rop::Default> can only be used in the
aforementioned there methods, not in the C<rop> property, not anywhere else.
=head3 Additional ROPs
Prima core imaging supports extra features for compositing images outside
the begin_paint/end_paint brackets. It supports the following 12+1 Porter-Duff
operators and some selected Photoshop blend operators:
=for podview
<img src="rop2.gif" cut=1 title="Porter-Duff operators">
<img src="rop3.png" cut=1 title="Photoshop operators">
=for html <p>
<!--
rop::Blend
rop::Clear rop::Add
rop::Xor rop::Multiply
rop::SrcOver rop::Screen
rop::DstOver rop::Overlay
rop::SrcCopy rop::Darken
rop::DstCopy rop::Lighten
rop::SrcIn rop::ColorDodge
rop::DstIn rop::ColorBurn
rop::SrcOut rop::HardLight
rop::DstOut rop::SoftLight
rop::SrcAtop rop::Difference
rop::DstAtop rop::Exclusion
=for html -->
=for podview </cut>
=over
=item Transparency control
There is defined a set of constants to apply a constant source and destination alpha to when
there is no alpha channel available:
rop::SrcAlpha
rop::SrcAlphaShift
rop::DstAlpha
rop::DstAlphaShift
Combine the rop constant using this formula:
$rop = rop::XXX |
rop::SrcAlpha | ( $src_alpha << rop::SrcAlphaShift ) |
rop::DstAlpha | ( $dst_alpha << rop::DstAlphaShift )
or by calling C<rop::alpha($rop, [ $src_alpha, [ $dst_alpha ]])> that does the same.
Also, the function C<rop::blend($alpha)> creates a rop constant for the simple blending of two images
by the following formula:
$dst = ( $src * $alpha + $dst * ( 255 - $alpha ) ) / 255
C<rop::alpha> also can be used for drawing on
images outside begin_paint/end_paint with all Porter-Duff and Photoshop raster operators:
$image->rop( rop::alpha( rop::SrcOver, 128 ));
$image->ellipse( 5, 5, 5, 5 );
Note that when the raster operation is set to C<rop::SrcOver>, the
fully identical effect can be achieved by
$image->alpha(128);
$image->ellipse( 5, 5, 5, 5 );
as well, in a DWIM fashion. The only corner case here is when
C<< $image->alpha >> is 255; add the rop flags
C<< rop::DstAlpha | ( 255 < rop::DstAlphaShift ) >> to make sure that blending is selected.
The corner case happens because the values of the Porter-Duff and bitwise rops clash, as the
design was to make the values of C<rop::CopyPut> and C<rop::Blend> to be the same to serve
as a sensible default. This may be resolved in future.
When used with icons, their source and/or destination alpha channels are
additionally multiplied by these values.
=item rop::ConstantColor
This bit is used when the alpha is defined but the main bits aren't. In this
case, the main bits are filled from the destination's image color, and the
source image is treated as the source alpha channel. The following code applies
a solid green shade with a mask loaded from a file.
$src->load('8-bit gray mask.png');
$dst->color(cl::LightGreen);
$dst->put_image( 0,0,$src,rop::SrcOver | rop::ConstantColor);
=back
=head2 Coordinates
The Prima toolkit employs the XY grid where X ascends rightwards and Y ascends
upwards. There, the (0,0) location is the bottom-left pixel of a canvas.
All graphic primitives use inclusive-inclusive boundaries.For example,
$d-> bar( 0, 0, 1, 1);
plots a bar that covers 4 pixels: (0,0), (0,1), (1,0) and (1,1).
The coordinate origin can be shifted using the C<::matrix> property
that translates the (0,0) point to the given offset. Calls to
C<::matrix>, C<::clipRect> and C<::region> always use the 'physical'(0,0) point, whereas the plotting methods use the transformation result,the 'logical' (0,0) point.
As noted before, these three properties cannot be used when an object
is in the disabled state.
=head3 Matrix
The C<Prima::Drawable> class accepts matrix scalars in the form of
6-item arrays that constitute the following 2-D transformation matrix
A B DX
C D DY
0 0 1
where the coordinate transformation follows this formula:
x' = A x + B x + DX
y' = C y + D y + DY
There are two accessors, C<get_matrix> and C<set_matrix> that return a copy
of the current matrix or copy a new matrix, correspondingly, from and to the
drawable object.
The 6-item array that C<get_matrix> returns is also a blessed object of type
C<Prima::matrix> ( see L<Prima::types/Prima::matrix> ) that is a separate copy
of the object matrix. C<Prima::matrix> objects feature a set of operations such
as C<rotate> and C<translate> that transform the matrix further. To apply this
matrix, one calls C<< $drawable->set_matrix($matrix) >> or C<< $matrix->apply($drawable) >>.
There is also a property C<matrix> that is not orthogonal to the C<get_matrix>/
C<set_matrix> method pair, as C<matrix> returns a C<Prima::Matrix> object, that, contrary
to a C<Prima::matrix> object returned by C<get_matrix>, is a direct accessor to the drawable's
matrix:
my $m = $self->get_matrix;
$m->translate(1,2);
$self->set_matrix($m);
is the same as
$self->matrix->translate(1,2);
and does not need an explicit call to C<set_matrix> or C<apply>.
This class has all the methods the C<Prima::matrix> has. See more in
L<Prima::types/Prima::Matrix>. See also: L<reset_matrix>.
=head2 Custom line end styles
Prima uses its own plotting mechanism in L<Prima::Drawable::Path> to produce
all primitive shapes, including lines. The way lines are plotted is managed by
the properties C<lineEnd>, C<lineJoin>, C<linePattern>, and C<miterLimit>. All of
these properties are described below, however, C<lineEnd> provides rich
capabilities to generate custom line ends, and this is what is described in
this section.
=over
=item le:: namespace
There are 3 predefined C<le::> integer constants
=for podview <img src="lineends.gif" cut=1>
le::Flat
le::Square
le::Round
=for html -->
=for podview </cut>
that are hardcoded in Prima, that are accepted by the C<lineEnd> property.
These constants are somewhat limited in the way one can operate them, for the sake
of efficiency.
It is also possible to supply an array descriptor that defines a set of
primitives that plot a line cap, automatically transformed with respect to
the current line tangent and width. Details of the descriptor syntax itself
are given in the next section, while here the set of non-hardcoded line end
functions is listed, which is also suitable for use in the C<lineEnd>property.
le::Arrow
le::Cusp
le::InvCusp
le::Knob
le::Rect
le::RoundRect
le::Spearhead
le::Tail
These descriptors could be arbitrarily transformed (f ex scaled):
$x->lineEnd( le::scale( Arrow => 1.5 ) );
$x->lineEnd( le::transform( le::Arrow, [1.5,0,0,1.5,0,0] ) );
$x->lineEnd( le::transform( le::Arrow, Prima::matrix->new->scale(1.5) ) );
=for podview <img src="lineends2.gif" title="Line ends with x 1.5 scaling">
=for html <p>
<figure>
<figcaption>Line ends with x 1.5 scaling</figcaption>
</figure>
=item lineEnd accessors
The C<lineEnd> property can accept up to 4 line end definitions, depending on
syntax. When Prima plots lines, depending on the location of a line end, one
of these 4 definitions is selected. Each definition also has its own property
- see L</lineHead>, L</lineTail>, L</arrowHead>, and L</arrowTail>, or an
index-based accessor C<lineEndIndex>:
=for podview <img src="lineends3.gif" cut=1>
[ lineHeads and lineTails ]
\____ ____ ___ __ ____ ___\
/ /
arrowTail arrowHead
=for html -->
=for podview </cut>
=item Line end syntax
The syntax for the custom line end style is:
syntax ::= array of pairs
pair ::= command, array of points
command ::= line or conic or cubic
points ::= set of x,y coordinate pairs (vertices)
where individual commands accept an arbitrary number of vertices, but no less
than 1 for C<line>, 2 for C<conic>, and 3 for C<cubic>.
The commands are executed sequentially on a coordinate grid where the line
width is assumed to be 1, the plotting starts from the point at (1,0) and
ends at (-1,0).
For example, this is the definition of C<le::Arrow>:
[
conic => [1,0,2.5,0,2.5,-0.5],
line => [0,2.5],
conic => [-2.5,-0.5,-2.5,0,-1,0]
]
=for podview <img src="lineends4.gif">
=back
=head1 API
=head2 Graphic context properties
=over 4
=item alpha INTEGER
Sets the alpha component of the brush, where 0 is fully transparent
and 255 is fully opaque.
Note that premultiplication of C<color> and C<backColor> is not necessary as it
is done internally.
Default: 255
=item antialias BOOLEAN
Turns on and off antialiased drawing on all primitives, excluding
image, C<pixel>, and C<bar_alpha> calls.
It will not be possible to turn the property on if the system does not
support it. Also, monochrome images won't support it as well.
See L</"Antialiasing and alpha">.
=item arrowHead
Defines the style to paint line heads on starting or ending points used to
define a line or polygon. Is never used on closed shapes. If C<undef>, the
heads are painted with the same style as C<lineHead>
Default value: C<le::Round>. Cannot be C<undef>.
=item arrowTail
Defines the style to paint line tails on starting or ending points used to
define a line or a polygon. Is never used on closed shapes. If C<undef>, the
heads are painted with the same style as C<lineTail>; if it is also C<undef>,
then the style of C<lineHead> is used.
Default value: C<undef>
=item backColor COLOR
Sets background color to the graphic context. All drawing routines
that use non-solid or transparent fill or line patterns use this property value.=item color COLOR
Sets foreground color to the graphic context. All drawing routines
=item clipRect X1, Y1, X2, Y2
Selects the clipping rectangle corresponding to the physical canvas origin.
On get-call, returns the extent of the clipping area, if it is not rectangular,
or the clipping rectangle otherwise. The code
$d-> clipRect( 1, 1, 2, 2);
$d-> bar( 0, 0, 1, 1);
thus affects only one pixel at (1,1).
Set-call discards the previous C<::region> value.
Note: C<::clipRect> can not be used while the object is in the paint-disabled state,
its context is neither recorded nor used as a template
( see L</"Graphic context and canvas">) -- except on images.
=item fillMode INTEGER
Affects the filling style of complex polygonal shapes filled by C<fillpoly>.
If C<fm::Winding>, the filled shape contains no holes; if C<fm::Alternate>, holes are present
where the shape edges cross.
The C<fm::Overlay> flag can be combined with these to counter an intrinsic defect
of filled shapes both in Win32 and X11 that don't exactly follow polygon
vertices. When supplied, it overlays a polygon over the filled shape, so that
the latter falls exactly in the boundaries defined by vertices. This is
desirable when one wants the shape to be defined exactly by polygon vertices
but is not desirable when a shape has holes in it and is connected in a way
that the polygon overlay may leave visible connection edges over them.
=for podview <img src="windings.gif">
Default value: C<fm::Winding|fm::Overlay>
=item fillPattern ( [ @PATTERN ] ) or ( fp::XXX ) or IMAGE
Selects 8x8 fill pattern that affects primitives that plot filled shapes:
bar(), fill_chord(), fill_ellipse(), fillpoly(), fill_sector(), floodfill().
Accepts either a C<fp::> constant or a reference to an array of 8 integers, or
an image reference. In all cases, except where the image is colored, treats 0s
in the pattern as the currently selected C<backColor>, and 1s as C<color>. When
C<rop2> is set to C<rop::NoOper>, treats 0s as fully transparent pixels.
Additionally, when in the render mode respects the C<alpha> property.
Note: Drawing over a monochrome bitmap or image will not respect its C<rop> on
Win32.
Depending on the parameters, treats the input as follows:
=over
=item fp:: constant
There are some predefined patterns, that can be referred to via C<fp::>
constants:
=for podview <img src="fills.gif" cut=1>
fp::Empty
fp::Solid
fp::Line
fp::LtSlash
fp::Slash
fp::BkSlash
fp::LtBkSlash
fp::Hatch
fp::XHatch
fp::Interleave
fp::WideDot
fp::CloseDot
fp::SimpleDots
fp::Borland
fp::Parquet
=for html -->
=for podview </cut>
( the actual patterns are hardcoded in api/api.c )
The default pattern is fp::Solid.
On a get-call, does not return the C<fp::> value but the corresponding array
(see below). If a constant value is needed to be recovered, use the C<fp::builtin>function that would return the constant from the array. There are also two
shortcut functions, C<fp::is_solid> and C<fp::is_empty> that check if the fill
pattern is all-ones or all-zeros, correspondingly.
=item Array
Wants an 8-item array where each item is a byte value, representing 8 bits of
each line in a pattern. The first integer is the topmost pattern line, and the
bit 0x80 is the leftmost pixel in the line.
An example below shows the encoding of the fp::Parquet pattern:
84218421 Hex
0 $ $ $ 51
1 $ $ 22
2 $ $ $ 15
3 $ $ 88
4 $ $ $ 45
5 $ $ 22
6 $ $ $ 54
7 $ $ 88
$d-> fillPattern([ 0x51, 0x22, 0x15, 0x88, 0x45, 0x22, 0x54, 0x88 ]);
=item Monochrome image
Like the I<array> above, wants an image consisting of 0s and 1s where these
would represent the target canvas' C<backColor> and C<color> property values,
correspondingly, when rendered. In the same fashion, when C<rop2> is set to
C<rop::NoOper>, zeros will be treated as transparent pixels.
=item Color image
Ignores color, and backColor, and rop2.
Just uses the tiles and the current C<alpha> value.
=item Icon
Ignores color, backColor, and rop2. Uses the alpha pixel values from the
icon's mask and the current C<alpha> value.
=back
=item fillPatternOffset X, Y
Origin coordinates for the C<fillPattern>. Image patterns origin (0,0) is
system-dependent.
=item font \%FONT
Manages font context. FONT hash acceptable values are
C<name>, C<height>, C<size>, C<width>, C<style> and C<pitch>.
Synopsis:
$d-> font-> size( 10);
$d-> font-> name( 'Courier');
$d-> font-> set(
style => $x-> font-> style | fs::Bold,
width => 22
);
See L</Fonts> for the detailed descriptions.
Applies to text_out(), get_text_width(), get_text_box(), get_font_abc(), get_font_def(),
render_glyph().
=item font_mapper
Returns a font mapper object that provides the interface to a set of fonts used
for substitution in polyfont shaping (see L</text_shape>). The fonts can be
accessed there either by their font hash (name and style only, currently), or
the font's corresponding index.
There are two font lists used in the substitution mechanism, I<passive> and
I<active>. The passive font list is initiated during the toolkit start and is
never changed. Each font there is addressed by an index. When the actual search
for a glyph is initiated, these fonts are queried in the loop and are checked
if they contain the required glyphs. These queries are also cached so that next
time lookups run much quicker. That way, an C<active> font list is built, and
the next substitutions use it before trying to look into the passive list. Sincethe ordering of fonts is system-based and is rather random, some fonts may not be a good
or aesthetic substitution. Therefore the mapper can assist in adding
or removing particular fonts to the active list, potentially allowing an
application to store and load a user-driven selection of substitution fonts.
The following methods are available on the font mapper object:
=over
=item activate %FONT
Adds the FONT into the active substitution list if the font is not disabled
=item get INDEX
Returns the font hash registered under INDEX
=item count
Returns the number of all fonts in the collection
=item index
Returns what index is assigned to the currently used font, if any
=item passivate %FONT
Remove the font from the active substitution list
=item is_active %FONT
Returns whether the font is in the active substitution list or not
=item enable %FONT
Enables the font entry, the font will be considered for the polyfont lookup
=item disable %FONT
Disables the font entry, the font will not be considered for the polyfont lookup
=item is_enabled %FONT
Returns whether the font is enabled or not
=back
=item lineHead
Defines the style to paint line heads in patterned lines only, on line segments
that do not lie on line starting or ending points used to define a line or
polygon.
Default value: C<undef>
=item lineEnd VALUE
Selects a line ending cap for plotting primitives. VALUE
can be one of
=for podview <img src="lineends1.gif" cut=1>
le::Arrow
le::Cusp
le::InvCusp
le::Flat
le::Knob
le::Rect
le::RoundRect
le::Spearhead
le::Square
le::Round
le::Tail
=for html -->
=for podview </cut>
constants, C<undef>, a custom line end description, or an array of four where
each entry is one of the values above.
The C<undef> value is only accepted in the array syntax, and not for the index
0 (L</lineHead>). The other indexes behave differently if are set to C<undef> -
see more in L</lineTail>, L</arrowHead>, L</arrowTail>, and L</lineEndIndex>.
C<le::Round> is the default value.
See also: L<Custom line end styles>.
=item lineEndIndex INDEX, VALUE
Same as C<lineEnd> except only addresses a single line ending style.
Allows VALUE to be C<undef> for indexes greater than 0; depending on the index, the line
style will be different ( see more in L</lineTail>, L</arrowHead>, L</arrowTail> ).
Allows special INDEX values or'ed with C<le::Only>, that behave differently, if
the line end style is C<undef>: while normal INDEX queries may return C<undef>,
or possibly affect neighbor indexing (if these are, in turn, C<undef>s), the
calls with the C<le::Only> bit set never return C<undef> on get-calls, and never
affect neighbor styles on set-calls.
The following lookup rules are used if a line end style is undef:
lei::LineTail - can never be undef
lei::LineHead - if undef, same as lei::LineTail
lei::ArrowTail - if undef, same as lei::LineTail
lei::ArrowHead - if undef, same as lei::LineHead, and if it also is undef, then same as lei::LineTail
=item lineJoin VALUE
Selects a line joining style for polygons. VALUE
can be one of
=for podview <img src="linejoins.gif" cut=1>
lj::Round
lj::Bevel
lj::Miter
=for html -->
=for podview </cut>
constants. lj::Round is the default value.
=item linePattern PATTERN
Selects a line pattern for plotting primitives. PATTERN is either a predefined
C<lp::> constant, or a string where each even byte is the length of a dash, and
each odd byte is the length of a gap.
The predefined constants are:
=for podview <img src="linepats.gif" cut=1>
lp::Null
lp::Solid
lp::Dash
lp::LongDash
lp::ShortDash
lp::Dot
lp::DotDot
lp::DashDot
lp::DashDotDot
=for podview </cut>
=for html -->
Not all systems are capable of accepting user-defined line patterns
and in such a situation the C<lp::> constants are mapped to the system-defined
patterns. In Win9x, for example, lp::DashDotDot is much different from
its string definition. This however is only actual for lines with width=0,
as wider lines are rendered by the Prima internal code.
The default value is lp::Solid.
=item lineTail
Defines the style to paint line tails in patterned lines only, on line segments
that do not lie on line starting or ending points used to define a line or
polygon. If C<undef>, line tails are painted with the same style as
C<lineHead>.
Default value: C<undef>
=item lineWidth WIDTH
Selects a line width for plotting primitives when C<antialias> is 0. If a
VALUE is 0, then a I<cosmetic> pen is used - the thinnest possible line that a
device can plot. If a VALUE is greater than 0, then a I<geometric> pen is used
- the line width is set in device units. There is a subtle difference between
VALUE 0 and 1 in the way the lines are joined.
When C<antialias> is 1, the geometric plotting algorithm is always used.
Default value: 0
=item matrix [A,B,C,D,X,Y] | Prima::Matrix
Sets current matrix transformation that is used in all plotting operations
except C<clipRect> and C<region>. Returns a L<Prima/Matrix> object.
The default value is (1,0,0,1,0,0) or C<Prima::matrix::identity>.
Note: C<::matrix> can not be used while the object is in the paint-disabled
state, its context is neither recorded nor used as a template
( see L</"Graphic context and canvas">).
See also: L<Prima::types/Prima::matrix> and C<Prima::types/Prima::Matrix>.
=item miterLimit VALUE
When path segments connect at a sharp angle, a miter join results in a spike
that extends well beyond the connection point. The purpose of the miter limit
is to cut off such spikes when they become objectionably long. At any given
corner, the miter length is the distance from the point at which the inner
edges of the stroke intersect to the point at which the outside edges of the
strokes intersect -- in other words, the diagonal length of the miter. This
distance increases as the angle between the segments decreases. If the ratio of
the miter length to the line width exceeds the miter limit parameter, stroke
treats the corner with a bevel join instead of a miter join. The ratio of miter
length to line width is directly related to the angle j between the segments
by the formula:
r = 1/sin(j/2)
Default value: 10.0
Assuming the line join is C<lj::Miter> and the line angle is 30 degrees:
=for podview <img src="miterlimit.gif" cut=1>
miter limit = 1.0: \__/
miter limit = 9.0: \ /
\/
=for podview </cut>
=for html -->
=item palette [ @PALETTE ]
Requests to install solid colors into the system palette, as many as possible.
PALETTE is an array of integer triplets, where each is the R, G, and B
components. The call
$d-> palette([128, 240, 240]);
selects a gray-cyan color, for example.
The return value from the get-call is the content of the previous set-call,
not the actual colors that were copied to the system palette.
=item region OBJECT
Selects a clipping region applied to all drawing and painting routines. In the
set-call, the OBJECT is either undef, then the clip region is erased ( no clip),
or a Prima::Image object with a bit depth of 1, or a C<Prima::Region> object.
The bit mask of the OBJECT is applied to the system clipping region. If the
OBJECT is smaller than the drawable, its exterior is assigned to the clipped
area as well. Discards the previous C<::clipRect> value; successive get-calls
to C<::clipRect> return the boundaries of the region.
In the get-mode returns either undef or a Prima::Region object.
Note: C<::region> can not be used while the object is in the paint-disabled
state, its context is neither recorded nor used as a template ( see L</"Graphic
context and canvas">).
=item resolution X, Y
A read-only property. Returns horizontal and vertical
device resolution in dpi.
=item rop OPERATION
Selects raster operation that applies to foreground color plotting routines.
See also: C<::rop2>, L</"Raster operations">.
=item rop2 OPERATION
Selects raster operation that applies to background color plotting routines.
See also: C<::rop>, L</"Raster operations">.
=item textOpaque FLAG
If FLAG is 1, then text_out() fills the text background area with the
C<::backColor> property value before drawing the text. The default value is 0
when text_out() plots text only.
In the system-based text drawing, if the background area is filled, then the alpha value is ignored.
In the standalone text drawing, if the background area is filled, then the alpha value is not ignored.
See get_text_box().
=item textOutBaseline FLAG
If FLAG is 1, then text_out() plots text on a given Y coordinate correspondent
to font baseline. If FLAG is 0, a Y coordinate is mapped to the font descent
line. The default value is 0.
=item translate X_OFFSET, Y_OFFSET
Translates the origin point by X_OFFSET and Y_OFFSET. Does not affect
C<::clipRect> and C<::region>. Not cumulative, so the call sequence
$d-> translate( 5, 5);
$d-> translate( 15, 15);
is equivalent to
$d-> translate( 15, 15);
Note: C<::translate> can not be used while the object is in the paint-disabled
state, its context is neither recorded nor used as a template
( see L</"Graphic context and canvas">).
=back
=head2 Other properties
=over 4
=item height HEIGHT
Selects the height of a canvas.
=item size WIDTH, HEIGHT
Selects the extent of a canvas.
=item width WIDTH
Selects the width of a canvas.
=back
=head2 Graphic primitives methods
=over 4
=item arc X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
Plots an arc with the center in X, Y, and DIAMETER_X and DIAMETER_Y axes
from START_ANGLE to END_ANGLE.
Context used: color, backColor, lineEnd, linePattern, lineWidth, miterLimit, rop, rop2
=item bar X1, Y1, X2, Y2
Draws a filled rectangle
Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2
=item bar_alpha ALPHA <X1, Y1, X2, Y2>
Fills a rectangle in the alpha channel bits only, using the ALPHA value between (0-255).
Can be called without parameters, in this case, fills the whole canvas.
Has only effect on the layered surfaces.
=item bars @RECTS
Draws a set of filled rectangles.
RECTS is an array of integer quartets in the format (X1,Y1,X2,Y2).
Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2
=item chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
Plots an arc with the center in X, Y, and DIAMETER_X and DIAMETER_Y axes
from START_ANGLE to END_ANGLE and connects its ends with the straight line.
Context used: color, backColor, lineEnd, linePattern, lineWidth, miterLimit, rop, rop2
=item clear <X1, Y1, X2, Y2>
Draws a rectangle filled with background color. Can be called without
parameters, in this case, fills the whole canvas.
Context used: backColor, rop2
=item draw_text CANVAS, TEXT, X1, Y1, X2, Y2, [ FLAGS = dt::Default, TAB_INDENT = 1 ]
Draws several lines of text one under another with respect to align and break rules,
specified in FLAGS and TAB_INDENT tab character expansion.
C<draw_text> is a convenience wrapper around C<text_wrap> for drawing the wrapped
text, and also provides the tilde ( ~ )- character underlining support.
The FLAGS is a combination of the following constants:
dt::Left - text is aligned to the left boundary
dt::Right - text is aligned to the right boundary
dt::Center - text is aligned horizontally in the center
dt::Top - text is aligned to the upper boundary
dt::Bottom - text is aligned to the lower boundary
dt::VCenter - text is aligned vertically in the center
dt::DrawMnemonic - tilde-escapement and underlining is used
dt::DrawSingleChar - sets tw::BreakSingle option to
Prima::Drawable::text_wrap call
dt::NewLineBreak - sets tw::NewLineBreak option to
Prima::Drawable::text_wrap call
dt::SpaceBreak - sets tw::SpaceBreak option to
Prima::Drawable::text_wrap call
dt::WordBreak - sets tw::WordBreak option to
Prima::Drawable::text_wrap call
dt::ExpandTabs - performs tab character ( \t ) expansion
dt::DrawPartial - draws the last line, if it is visible partially
dt::UseExternalLeading - text lines positioned vertically with respect to
the font external leading
dt::UseClip - assign ::clipRect property to the boundary rectangle
dt::QueryLinesDrawn - calculates and returns the number of lines drawn
( contrary to dt::QueryHeight )
dt::QueryHeight - if set, calculates and returns vertical extension
of the lines drawn
dt::NoWordWrap - performs no word wrapping by the width of the boundaries
dt::WordWrap - performs word wrapping by the width of the boundaries
dt::Default - dt::NewLineBreak|dt::WordBreak|dt::ExpandTabs|
dt::UseExternalLeading
Context used: color, backColor, font, rop, textOpaque, textOutBaseline
=item ellipse X, Y, DIAMETER_X, DIAMETER_Y
Plots an ellipse with the center in X, Y, and DIAMETER_X and DIAMETER_Y axes.
Context used: color, backColor, linePattern, lineWidth, rop, rop2
=item fill_chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
Fills a chord outline with the center in X, Y, and DIAMETER_X and DIAMETER_Y axes
from START_ANGLE to END_ANGLE (see chord()).
Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2
=item fill_ellipse X, Y, DIAMETER_X, DIAMETER_Y
Fills an elliptical outline with the center in X, Y, and DIAMETER_X and DIAMETER_Y axes.
Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2
=item fillpoly \@POLYGON
Fills a polygonal area defined by POLYGON set of points. POLYGON must present
an array of (X,Y) integer pairs. Example:
$d-> fillpoly([ 0, 0, 15, 20, 30, 0]);
Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2, fillMode
Returns success flag; if failed, C<$@> contains the error.
See also: polyline().
=item fill_sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
Fills a sector outline with the center in X, Y, and DIAMETER_X and DIAMETER_Y axes
from START_ANGLE to END_ANGLE (see sector()).
Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2
=item fill_spline \@VERTICES, %OPTIONS
Fills a polygonal area defined by the curve projected by applying a B-spline
curve based on a set of VERTICES. VERTICES must present an array of (X,Y)
integer pairs. Example:
$d-> fill_spline([ 0, 0, 15, 20, 30, 0]);
Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2
Returns success flag; if failed, C<$@> contains the error.
See also: spline, render_spline
=item flood_fill X, Y, COLOR, SINGLEBORDER = 1
Fills an area of the canvas using the current fill context. The area is
assumed to be bounded as specified by the SINGLEBORDER parameter. SINGLEBORDER
can be 0 or 1.
SINGLEBORDER = 0: The fill area is bounded by the color specified by
the COLOR parameter.
SINGLEBORDER = 1: The fill area is defined by the color that
is specified by COLOR.
Filling continues outward in all directions as long as the color
is encountered. This style is useful for filling areas with
multicolored boundaries.
Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2
=item line X1, Y1, X2, Y2
Plots the straight line from (X1,Y1) to (X2,Y2).
Context used: color, backColor, linePattern, lineWidth, rop, rop2
=item lines \@LINES
LINES is an array of integer quartets in format (X1,Y1,X2,Y2).
lines() plots the straight line per quartet.
Context used: color, backColor, linePattern, lineWidth, rop, rop2
Returns success flag; if failed, C<$@> contains the error.
=item new_aa_surface
Returns a new antialiasing surface object for AA emulation. See
L<Prima::Drawable::Antialias> for usage and details.
=item new_gradient
Returns a new gradient object. See L<Prima::Drawable::Gradient> for usage and details.
=item new_path
Returns a new path object. See L<Prima::Drawable::Path> for usage and details.
=item pixel X, Y, <COLOR>
::pixel is a property - on set-call it changes the pixel value at (X,Y) to
COLOR, on get-call ( without COLOR ) it does return a pixel value at (X,Y).
No context is used except matrix transformation of the coordinates. May return
C<cl::Invalid> to signal an error or the out-of-boundaries condition.
=item polyline \@POLYGON
Draws a polygonal area defined by the POLYGON set of points.
POLYGON must contain an array of integer pairs in (X,Y) format.
Context used: color, backColor, linePattern, lineWidth, lineJoin, lineEnd, miterLimit, rop, rop2
Returns success flag; if failed, C<$@> contains the error.
See also: fillpoly().
=item put_image X, Y, OBJECT, [ ROP=rop::Default]
Draws an OBJECT at coordinates (X,Y). OBJECT must be Prima::Image,
Prima::Icon, or Prima::DeviceBitmap. If ROP raster operation is specified,
it is used. Otherwise, the current value of the C<::rop> property is used.
Returns success flag; if failed, C<$@> contains the error.
Context used: rop; color and backColor for a monochrome DeviceBitmap
=item put_image_indirect OBJECT, X, Y, X_FROM, Y_FROM, DEST_WIDTH, DEST_HEIGHT, SRC_WIDTH, SRC_HEIGHT, [ROP=rop::Default]
Draws the OBJECT's source rectangle into the destination rectangle,
stretching or compressing the source bits to fit the dimensions of the
destination rectangle, if necessary. The source rectangle starts at
(X_FROM,Y_FROM), and is SRC_WIDTH pixels wide and SRC_HEIGHT pixels tall.
The destination rectangle starts at (X,Y), and is abs(DEST_WIDTH) pixels wide
and abs(DEST_HEIGHT) pixels tall. If DEST_WIDTH or DEST_HEIGHT are negative,
a mirroring by the respective axis is performed.
OBJECT must be Prima::Image, Prima::Icon, or Prima::DeviceBitmap.
No context is used, except color and backColor for a monochrome DeviceBitmap
Returns success flag; if failed, C<$@> contains the error.
=item rect3d X1, Y1, X2, Y2, WIDTH, LIGHT_COLOR, DARK_COLOR, [ BACK_COLOR ]
Draws a 3d-shaded rectangle (X1,Y1 - X2,Y2) with WIDTH line width, and
LIGHT_COLOR and DARK_COLOR colors. If BACK_COLOR is specified, paints an
inferior rectangle with it, otherwise the inferior rectangle is not touched.
Context used: rop; color and backColor for a monochrome DeviceBitmap
=item rect_fill X1, Y1, X2, Y2, BORDER_WIDTH, FOREGROUND, BACKGROUND
Draws a rectangle with outline color FOREGROUND and BORDER_WIDTH pixels,
and fills it with color BACKGROUND. If FOREGROUND and/or BACKGROUND are
undefined, current colors are used. BORDER_WIDTH is 1 pixel if omitted.
Contrary to a call to C<rectangle()> with the line width greater than 1, never
paints pixels outside the given rectangle; the border is painted inwards.
Context used: rop, fillPattern
=item rect_focus X1, Y1, X2, Y2, [ WIDTH = 1 ]
Draws a marquee rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH line width.
No context is used.
=item rect_solid X1, Y1, X2, Y2, BORDER_WIDTH, FOREGROUND
Draws a rectangle with outline color FOREGROUND and BORDER_WIDTH pixels. If
FOREGROUND is undefined, a current color is used. BORDER_WIDTH is 1 pixel if
omitted.
Contrary to a call to C<rectangle()> with line width greater than 1, never
paints pixels outside the given rectangle; the border is painted inwards.
Context used: rop
=item rectangle X1, Y1, X2, Y2
Plots a rectangle with (X1,Y1) - (X2,Y2) extents.
Context used: color, backColor, linePattern, lineWidth, rop, rop2
=item sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
Plots an arc with the center in X, Y, and DIAMETER_X and DIAMETER_Y axis from
START_ANGLE to END_ANGLE and connects its ends and (X,Y) with two straight
lines.
Context used: color, backColor, lineEnd, linePattern, lineWidth, miterLimit, rop, rop2
=item spline \@VERTICES, %OPTIONS
Draws a B-spline curve defined by a set of VERTICES control points. VERTICES
must present an array of (X,Y) integer pairs.
The extra options C<knots> and C<weights> described below allow to upgrade
the B-spline into a NURBS curve.
The following options are supported:
=over
=item closed BOOL = undef
When not set, checks if the first and the last vertices point to the same
point, and assumes a closed shape if they do. Note - a closed shape rendering
is implemented by adding a degree minus two points to the set; this is
important if C<weight> or C<knots> are specified.
=item degree INTEGER = 2
The B-spline degree. Default is 2 (quadratic). The number of points supplied
must be at least a degree plus one.
=item knots \@INTEGERS
An array of N integers ( N = number of points plus degree plus one ). By
default, if the shape is opened (i.e. first and last points are different),
represents a clamped array, so that the first and last points of the final
curve match the first and the last control points. If the shape is closed,
represents an unclamped array so that no control points lie directly on the
curve.
Quote wikipedia: "The knot vector is a sequence of parameter values that
determines where and how the control points affect the NURBS curve... The
knot vector divides the parametric space in the intervals ... usually
referred to as knot spans. Each time the parameter value enters a new knot
span, a new control point becomes active, while an old control point is
discarded. It follows that the values in the knot vector should be in
nondecreasing order, so (0, 0, 1, 2, 3, 3) is valid while (0, 0, 2, 1, 3, 3)
is not."
=item precision INTEGER = 24
Defines the number of steps to split the curve into. The value is multiplied by the number
of points and the result is used as the number of steps.
=item weight \@INTEGERS = [ 1, 1, 1, ... ]
An array of integers, one for each point supplied. Assigning these can be used to
convert B-spline into a NURBS. By default set of ones.
=back
Context used: color, backColor, linePattern, lineWidth, lineEnd, miterLimit, rop, rop2
See also: fill_spline, render_spline.
=item stretch_image X, Y, DEST_WIDTH, DEST_HEIGHT, OBJECT, [ ROP=rop::Default ]
Draws the OBJECT on the destination rectangle, stretching or compressing the
source bits to fit the dimensions of the destination rectangle, if necessary.
If DEST_WIDTH or DEST_HEIGHT are negative, a mirroring is performed. The
destination rectangle starts at (X,Y) and is DEST_WIDTH pixels wide and
DEST_HEIGHT pixels tall.
If ROP raster operation is specified, it is used. Otherwise, the value of
the C<::rop> property is used.
OBJECT must be Prima::Image, Prima::Icon, or Prima::DeviceBitmap.
Returns success flag; if failed, C<$@> contains the error.
Context used: rop
=item text_out TEXT, X, Y
Draws TEXT string at (X,Y). TEXT is either a character string or a
C<Prima::Drawable::Glyphs> object returned from C<text_shape>, or
C<< Prima::Drawable::Glyphs->glyphs >> strings of glyphs.
Returns success flag; if failed, C<$@> contains the error.
Context used: color, backColor, font, rop, textOpaque, textOutBaseline
=item text_shape TEXT, %OPTIONS
Converts TEXT into a set of glyphs, returns either a C<Prima::Drawable::Glyphs>
object, or a C<0> integer when shaping is not necessary, or C<undef> as an
error.
When Prima is compiled with C<libfribidi>, the method runs the unicode
bidirectional algorithm on TEXT that properly positions embedded directional
text (f.ex. a Latin quote inside an Arabic text),
see L<Unicode Standard Annex
for the details. Without the library only does minimal RTL alignment.
Glyphs returned are positioned according to RTL directions given in TEXT using
characters from unicode block "General Punctuation U+2000 .. U+206F".
Additionally, character ligation may be performed so that one or more
characters are represented by one or more glyphs. Such syntactic units,
I<clusters>, are adopted in Prima where appropriate, instead of character
units, for selection, navigation, etc in f.ex. C<Prima::InputLine> and
C<Prima::Edit>. Helper routines that translate clusters, glyphs, and characters
into each other are found in L<Prima::Drawable::Glyphs>.
Options recognized:
=over
=item advances BOOLEAN = false
The shaping process may or may not fill an integer array of advances and positions for
each glyph, depending on the implementation. The advances are needed to
represent f.ex. combining graphemes, when TEXT consisting of two characters,
C<"A"> and combining grave accent U+300 should be drawn as a single E<Agrave>
cluster but are represented by two glyphs C<"A"> and C<"`">. The grave glyph
has its own advance for standalone usage, but in this case, it should be
ignored, and that is achieved by filling the advance table where the C<"A"> advance
is the normal glyph advance, whereas the advance of the C<"`"> is zero. Also,
the position table additionally shifts glyph position by X and Y coordinates,
when that is needed (f.ex. it might be positioned differently by the vertical axis on
C<"a"> and C<"A">).
Setting these options to C<true> will force to fill advance and positioning tables.
These tables can be manipulated later, and are respected by C<text_out> and
C<get_text_width>.
=item language STRING = undef
When set, the shaping process can take into account the language of the text.
F.ex. text C<"ae"> might be shaped as a single glyph I<E<aelig>> for the Latin
language, but never for English.
=item level INTEGER = ts::Full
Selects the shaping (i.e. text to glyph conversion) level, how the system
should treat the input text, and how deep the shaping should go.
One of the following C<ts::XXX> options:
=over
=item ts::Bytes
Treats input text as non-unicode locale-specific codepoints, characters higher
than 255 are treated as chr(255). Reordering never happens, font substitution
never happens, kerning and ligation never happen; returns glyph indexes in a
1:1 mapping for each codepoint.
=item ts::None
Performs quick null shaping without mapping to the font glyphs, but only
running the bidirectional algorithm on the text. On the return, C<glyphs>, as well
as eventual C<advances> and C<positions>, are filled with zeros, but C<indexes>
are filled with the proper character offsets, effectively making it a visual-to-logical
map since the number of glyphs will always be equal to the number of characters
in TEXT because ligation never happens here (except when TEXT contains unicode
directional characters such as isolates etc - those are removed from the output).
By default, advances and positions are not filled, but if the C<advances> option is set,
fills them with zeros.
=item ts::Glyphs
Applies the unicode bidi algorithm and maps the result onto font glyphs. Ligation
and kerning don't happen here, it's the same as C<ts::None> but with
the glyph mapping part.
By default, advances and positions are not filled, but if the C<advances>
option is set, fills the advances array with character glyph advances and the
positions array with zeros.
May fill the C<fonts> array if the C<polyfont> option is set.
=item ts::Full
Applies the unicode bidi algorithm and runs the full shaping on the result.
Ligation and kerning may occur. Always fills the advances and positions array;
the C<advances> option is ignored.
If the system or the selected font does not support shaping, tries to ligate
known Arabic shapes using the I<fribidi> library, if available. Also in
this case does not return the advances and positions by default, but if
the C<advances> option is set, fills the advances array with character glyph
advances and the positions array with zeros.
May fill the C<fonts> array if the C<polyfont> option is set.
=back
=item pitch INTEGER
When the C<polyfont> is set (default) and thus font substitution is desired, filters only fonts
that match C<pitch>, either C<fp::Variable> or C<fp::Fixed>. By default will be
set to C<fp::Fixed> if the current for is monospaced, but to C<fp::Default>
matching all fonts, otherwise.
=item polyfont BOOLEAN = true
If set, checks if the currently selected font supports all ithe required
unicode points, and if not, selects substitutions from a pre-populated list,
taking into account the font pitch (see C<pitch> above). In cases where the
current font does not have enough glyphs to shape all the requested unicode
points, font substitution is performed, and the result contains an extra array
C<fonts> (see L<Prima::Drawable::Glyphs/fonts>). When the current font has all
the needed glyphs, the fonts array is not created.
The font list access is available through L</font_mapper>.
Valid only with shaping levels C<ts::Glyphs> and C<ts::Full>.
=item reorder BOOLEAN = true
When set, the unicode bidi algorithm is used to reorder codepoints, and
additionally, RTL codepoints may be reversed (depending on the direction context).
When unset, no such reordering occurs, to emulate as much as possible a
behavior that each text grapheme is being mapped to a glyph cluster exactly as
it occurs in the input text, from left to right. Note that bidi reordering
still may occur internally, since system shapers may reverse the placement of RTL
characters, so the Prima reordering is needed to cancel this. In theory the caller
shouldn't see the difference as these should cancel each other, but if Prima
miscalculates the expected way the system shaper does the bidi processing, it
might.
A similar effect can be reached by prepending the text with U+202D
(LEFT-TO-RIGHT OVERRIDE).
=item replace_tabs INTEGER = -1
If set to 0 or more, replaces each tab character with the space character and sets
their widths to the width of the latter multiplied by the given number. Since
it needs the advances table to operate, automatically sets the C<advances>
option. If the string passed indeed contains tab characters, also turns off
the C<skip_if_simple> option.
Note: if using the result later in C<text_wrap>, set the C<tabIndent> parameters there to 1
to avoid double multiplication of the tab character width.
=item rtl BOOLEAN
If set to 1, the default text direction is assumed as RTL, and as LTR if set to 0.
If unset, the text direction is taken from L<Prima::Application/textDirection>.
=item skip_if_simple BOOLEAN = false
When set, checks whether the shaping result is identical to the input, in the sense
that a call to C<text_out(TEXT)> and a call to C<text_shape_out(TEXT)> produce
identical results. The majority of English text will fall into that category, and
when that indeed happens, returns an integer value of C<0> instead of a glyph object.
=back
See also C<text_shape_out>, C<get_text_shape_width>, C<text_wrap_shape>.
=item text_shape_out TEXT, X, Y[, RTL]
Runs shaping on TEXT character string with the RTL flag (or C<< $::application->textDirection >>.
Draws the resulting glyph string at (X,Y).
Returns success flag; if failed, C<$@> contains the error.
Context used: color, backColor, font, rop, textOpaque, textOutBaseline
=back
=head2 Methods
=over 4
=item begin_paint
Enters the enabled ( active paint ) state and returns the success flag; if failed,
C<$@> contains the error. Once the object is in the enabled state, painting
and drawing methods can write on the canvas.
See also: C<end_paint>, C<begin_paint_info>, L</"Graphic context and canvas">
=item begin_paint_info
Enters the information state and returns the success flag; if failed, C<$@> contains
the error. The object information state is the same as the enabled state ( see
C<begin_paint>), except painting and drawing methods do not change the object
canvas.
See also: C<end_paint_info>, C<begin_paint>, L</"Graphic context and canvas">
=item can_draw_alpha
Returns whether using alpha bits operation on the drawable will have any effect
or not. Note that the drawable may not necessarily have an alpha channel,
for example, a normal RGB image is capable of being painted on with alpha while not
having any alpha on its own. On Unix, all non-1-bit drawables return true if
Prima was compiled with XRender support and if that extension is present on the
X server. On windows, all non-1-bit drawables return true unconditionally.
See also: C<has_alpha_layer>
=item end_paint
Exits the enabled state and returns the object to a disabled state.
See also: C<begin_paint>, L</"Graphic context and canvas">
=item end_paint_info
Exits the information state and returns the object to a disabled state.
See also: C<begin_paint_info>, L</"Graphic context and canvas">
=item font_match \%SOURCE, \%DEST, PICK = 1
Performs merging of two font hashes, SOURCE and DEST.
Returns the merge result. If PICK is true, matches the result
with a system font repository.
Called implicitly by C<::font> on set-call, allowing the following
example to work:
$d-> font-> set( size => 10);
$d-> font-> set( style => fs::Bold);
In the example, the hash 'style => fs::Bold' does not overwrite
the previous font context ( 'size => 10' ) but gets added to it ( by font_match()),
providing the resulting font with both font properties set.
=item fonts <FAMILY = "", ENCODING = "">
Member of C<Prima::Application> and C<Prima::Printer>, does not
present in C<Prima::Drawable>.
Returns an array of font metric hashes for a given font FAMILY
and ENCODING. Every hash has a full set of elements described in L</"Fonts">.
If called without parameters, returns an array of the same hashes
where each hash represents a member of the font family from every
system font set. In this special case, each font hash contains
an additional C<encodings> entry, which points to an array of encodings
available for the font.
If called with FAMILY parameter set but no ENCODING is set, enumerates
all combinations of fonts with all available encodings.
If called with FAMILY set to an empty string, but ENCODING specified,
returns only fonts that can be displayed with the encoding.
Example:
print sort map {"$_->{name}\n"} @{$::application-> fonts};
=item get_bpp
Returns device color depth. 1 is for black-and-white monochrome,
24 for true color, etc.
=item get_effective_rop ROP
Converts a given ROP depending on the drawable type. The majority of cases only
convert C<rop::Default> to C<rop::CopyPut>, however, layered device bitmaps and
icons with 8-bit alpha masks return C<rop::Blend> instead.
=item get_font_abc FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
Returns ABC font metrics for the given range, starting at
FIRST_CHAR and ending with LAST_CHAR. If these two parameters are both -1,
the default range ( 0 and 255 ) is assumed. The UNICODE boolean flag
is responsible for the representation of characters in the 127-255 range.
If 0, the default, encoding-dependent characters are assumed.
If 1, the U007F-U00FF glyphs from the Latin-1 set are used.
The result is an integer array reference, where every character
glyph is referred to by three integers, each triplet containing
A, B and C values.
For a detailed explanation of ABC meaning, see L</"Font ABC metrics">;
Context used: font
=item get_font_def FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
Same as C<get_font_abc> but for the vertical metrics. Is expensive
on bitmap fonts because in order to find out the correct values Prima
has to render glyphs on bitmaps and scan for black and white pixels.
Vector fonts are not subject to this, and the call is as effective
as C<get_font_abc>.
=item get_font_languages
Returns an array of ISO 639 strings that can be displayed using glyphs
available in the currently selected font.
=item get_font_ranges
Returns an array of integer pairs denoting unicode indices of glyphs covered by
the currently selected font. Each pair is the first and the last index of a
contiguous range.
Context used: font
=item get_nearest_color COLOR
Returns the nearest possible solid color in the representation of the graphic
device. Always returns the same color if the device bit depth is equal to or
greater than 24.
=item get_paint_state
Returns the paint state value as one of the C<ps::> constants - C<ps::Disabled>
if the object is in the disabled state, C<ps::Enabled> for the enabled state,
C<ps::Information> for the information state.
The C<ps::Disabled> constant is equal to 0 so this allows for simple boolean
testing whether one can get/set graphical properties on the object.
See L</"Graphic context and canvas"> for more.
=item get_physical_palette
Returns an array of (R,G,B) integer triplets where each color entry is in the 0
- 255 range.
The physical palette array is non-empty only on paletted graphic devices,
the true color devices always return an empty array.
The physical palette reflects the solid colors currently available
to all programs in the system. The information is volatile if
the system palette can change colors, since any other application
may request to change the system colors at any moment.
=item get_text_shape_width TEXT, [ FLAGS ]
Runs shaping on TEXT character string with the text direction either taken from
the C<FLAGS & to::RTL> value or from the C<< $::application->textDirection >> property.
Returns the width of the shaping result as if it would be drawn using the currently
selected font.
If C<FLAGS & to::AddOverhangs> is set, the first character's absolute A value
and the last character's absolute C value are added to the string if they are
negative.
=item get_text_width TEXT, ADD_OVERHANG = 0
Returns the TEXT string width if it would be drawn using the currently selected font.
TEXT is either a character string, or a C<Prima::Drawable::Glyphs> object
returned from C<text_shape>, or a C<< Prima::Drawable::Glyphs-> glyphs >> glyph
string.
If ADD_OVERHANG is 1, the first character's absolute A value and the last
character's absolute C value are added to the string if they are negative.
See more on ABC values at L</"Font ABC metrics">.
Context used: font
=item get_text_box TEXT
Returns the TEXT string extensions if it would be drawn using the currently selected
font. TEXT is either a character string or a C<Prima::Drawable::Glyphs>
object returned from the C<text_shape> method, or C<< Prima::Drawable::Glyphs-> glyphs >>
glyph string.
The result is an anonymous array of 5 points ( 5 integer pairs
in (X,Y) format). These 5 points are pixel offsets for the following string
extents, given the string is plotted at (0,0):
1: start of string at the ascent line ( top left )
2: start of string at the descent line ( bottom left )
3: end of string at the ascent line ( top right )
4: end of string at the descent line ( bottom right )
5: concatenation point
The concatenation point coordinates (XC,YC) are the values passed to the
consequent text_out() call so that the conjoint string would plot as if it was
a part of the TEXT. Depending on the value of the C<textOutBaseline> property,
the concatenation point is located either on the baseline or on the descent
line.
Context used: font, textOutBaseline
=for podview <img src="gettextbox.gif" cut=1>
1 3 3 4
** ****
* * *
*** ***
* * *
**** **
2 4 1 2
=for podview </cut>
=for html -->
=item graphic_context %GC, $CALLBACK
A shortcut method that saves the graphic context, applies changes in %GC, calls $CALLBACK,
and finally restores the context. F ex:
$self->graphic_context( fillPattern => fp::Solid, sub { $self-> bar(..) } );
=item graphic_context_pop
Restores the graphic context properties from the stack.
=item graphic_context_push
Saves the graphic context properties on the stack.
=item has_alpha_layer
Returns true if the drawable has an alpha channel. If the drawable is treated as a source,
it means its alpha content will be respected when drawing on another surface. If the drawable is
treated as a destination, it means that its alpha content will be updated if drawing on it uses
alpha bits.
See also: C<can_draw_alpha>.
=item is_font_colored
True if the current font has COLR/CPAL information and Prima is compiled with its support,
so that f ex emoji fonts are displayed with full color.
Same as C<Prima::Font::colored>
=item render_glyph INDEX, %OPTIONS
Returns a representation of a glyph as an outline. The outline is an integer
array formed as a set of plotting commands. Each command is a C<ggo::> constant
followed by an integer value with the number of the points returned, followed
by the 2D point coordinates in 1/64 pixels.
The following options are recognized:
=over
=item glyph BOOL
If set, INDEX is treated as the glyph index rather than the character index.
The default value is false.
=item hints BOOL
If set, hinting is enabled.
The default value is true.
=item unicode BOOL
If set, INDEX is treated as a utf8 character index, otherwise a locale-specific index.
The default value is false.
=back
The C<ggo::> commands are:
ggo::Move - move point
ggo::Line - plot line
ggo::Conic - plot 2-degree spline
ggo::Cubic - plot 3-degree spline
=item render_pattern IMAGE|ICON|ARRAY|INDEX, %OPTIONS
Takes a fill pattern represented by one of the C<fp::XXX> constants, an array of 8
bytes, or an image (or icon); the same syntax as in C<fillPattern>.
Uses %OPTIONS to generate a new rectangular pattern that can be used in the
C<fillPattern> property. Since Prima does not provide an individual property
that would manage specifically the matrix of a fill pattern, this method can be
used to implement this functionality.
Also respects the C<preserveType> property of the image, and if it is set,
changes the resulting pattern image type back to the original type. In case
where fillPattern is given by an ARRAY or an INDEX, always generates an
C<im::BW> image, so it can be used both in C<rop2> transparent and opaque
modes, like the original pattern.
Options:
=over
=item color COLOR, alpha 0-255
If C<margin> is used, pre-fills the target image with this color. C<alpha> is used
to pre-fill the target image's mask with this value, if the image is an icon.
=item margin XY | [ X, Y ]
Set margins in X and Y pixels before applying the transformation
=item matrix MATRIX
2D matrix to transform IMAGE
=back
=item render_polyline \@POLYLINE, %OPTIONS
Performs calculations on the POLYLINE, defined by OPTIONS. The following options are recognized:
=over
=item aafill BOOLEAN
If set, renders a 8-bit grayscale image with antialiased filled polygon.
The polygon is automatically adjusted so its lower and left boundaries
and on the resulting image's lower and left boundaries. Also the image
size corresponds to the polygon size.
The filling mode can be specificed with the C<mode> option, or the current
C<fillMode> will be used. Note the the option only accepts the C<fm::Winding>
and C<fm::Alternate> constants, and ignores C<fm::Overlay>.
Return three scalars: first two are the X and Y polygon offsets, and
the first is the image itself.
=item box BOOLEAN
If set, instead of polyline vertices, calculates the box extents of the polyline
(either original or after the matrix transform, depending on whether the C<matrix> option was supplied or not),
and returns 4 numerics for left, bottom, width, and height of the box enclosure.
=item integer BOOLEAN
By default, the result is returned as a set of floating point numerics, however,
if integer results are needed, the results are transformed to integers using
the I<< int = float + ((float < 0) ? -0.5 : 0.5) >> formula.
=item matrix A,B,C,D,U,V
If supplied, performs matrix transformation on each polyline vertex:
X' = AX + CY + U
Y' = BX + DY + V
and returns the new polyline
=item mode fm::Windings | fm::Alternate
See C<aafill> above.
=item path BOOLEAN
If set, treats polyline as a path that will get applied C<lineEnd>,
C<lineJoin>, C<linePattern>, and C<miterLimit> properties (either from the object
or from %OPTIONS) and returns a set of commands that would represent the final
shape. The commands are: I<arc> (6 arguments, same as the C<arc> primitive),
I<line> with 1 argument, a polyline array (respects the C<integer> option), and
I<open> with no arguments.
See L<Prima::Drawable::Path/widen> for usage. See also C<line_join_hints> below.
=item line_join_hints ARRAY OF INTEGERS
Only when the C<path> option is present:
A specially formatted array of indexes that hint where inside the polyline are
the boundaries between the points that need to override C<lineJoin> and force
it to be C<lj::Miter>.
See L<Prima::Drawable::Path/widen> for usage.
=back
=item render_spline \@VERTICES, %OPTIONS
Renders B-spline curve from a set of VERTICES to a polyline with given options.
The method is internally used by C<spline> and C<fill_spline>, and is provided
for cases when these are insufficient. See the description of options in L</spline>.
=item reset_matrix
Set the CTM to identity
=item text_wrap TEXT, WIDTH, OPTIONS, [TAB_INDENT = 8, FROM = 0, LENGTH = -1, GLYPHS]
Breaks the TEXT string in chunks that must fit into a WIDTH pixels wide box (
for WIDTH >= 0 ). TEXT is either a character string or a
C<Prima::Drawable::Glyphs> object returned from C<text_shape>, or a C<<
Prima::Drawable::Glyphs->glyphs >> string of glyphs. In the latter case some
wrapping options are not applicable. It is possible to send both text as TEXT
and its shaped representation as GLYPHS.
The breaking algorithm and its result are managed by the OPTIONS integer value
that is a combination of the following C<tw::> constants:
=over 4
=item tw::CalcMnemonic
Use 'hotkey' semantics, when a character preceded by the tilde character (~)
has a special meaning, f ex it gets underlined when used in menus. If this bit
is set, the first tilde character used as an escape is not calculated, and
never appears in the result apart from the escaped character.
Not applicable in glyph wrapping.
=item tw::CollapseTilde
In addition to tw::CalcMnemonic, removes the tilde character from
the resulting chunks.
Not applicable in glyph wrapping.
=item tw::CalcTabs
If set, treats tab ('\t') characters as TAB_INDENT times space characters.
Not applicable in glyph wrapping.
=item tw::ExpandTabs
If set, expands tab ('\t') characters as TAB_INDENT times space characters.
Not applicable in glyph wrapping.
=item tw::BreakSingle
Defines the method behavior when the text cannot fit in WIDTH.
Does not affect anything else otherwise.
If set, the method returns an empty array. If unset, returns a text broken
by the minimum number of characters per chunk. In the latter case the width of
the resulting text blocks B<will> exceed the WIDTH.
=item tw::NewLineBreak
Forces the creation of a new chunk after the newline character ('\n').
If the UTF8 text is passed, the unicode line break characters C<0x2028> and C<0x2029>
produce the same effect as the newline character.
Not applicable in glyph wrapping.
=item tw::SpaceBreak
Forces the creation of a new chunk after the space character (' ') or the tab
character.
Not applicable in glyph wrapping.
=item tw::ReturnChunks
Defines the result of the text_wrap() method.
If set, the array consists of integer pairs,
where each is a text offset within TEXT and its length.
If unset, the resulting array consists of text chunks.
=item tw::ReturnGlyphs
If GLYPHS is set (only together with TEXT), this option becomes available
to get the resulting chunks as sub-sets of GLYPHS.
=item tw::ReturnLines
Equals to 0, is a mnemonic to an unset tw::ReturnChunks.
When wrapping glyphs, has the same effect as the C<tw::ReturnGlyphs> flag.
=item tw::WordBreak
If unset, the TEXT breaks as soon as the chunk width exceeds WIDTH.
If set, tries to keep words in TEXT so they do not appear in two
chunks, e.g. breaks TEXT by words, not by characters.
If Prima is compiled with the I<libthai> library and Thai text is detected,
Prima uses the library to detect the word boundaries because the Thai
language does not use spaces between words. This behavior can be disabled byrunning Prima with C<--no-libthai>.
Not applicable in glyph wrapping.
=item tw::ReturnFirstLineLength
If set, C<text_wrap> proceeds until the first line is wrapped, either by
width or ( if specified ) by break characters. Returns the length of the
resulting line. Used for efficiency as the inverted C<get_text_width> function.
=back
If OPTIONS has tw::CalcMnemonic or tw::CollapseTilde bits set, then the last
scalar of the array is a special hash reference. The hash contains extra
information regarding the 'hotkey' position of the underline - it is assumed that the
tilde character '~' prefixes the underlined character. The hash
contains the following keys:
=over 4
=item tildeLine
Chunk index that contains the escaped character. Set to undef if no tilde escape
was found; the rest of the information in the hash is not relevant in this
case.
=item tildeStart
The horizontal offset of the beginning of the line that underlines
the escaped character.
=item tildeEnd
The horizontal offset of the end of the line that underlines
the escaped character.
=item tildeChar
The escaped character.
=back
Context used: font
=item text_wrap_shape TEXT, WIDTH = -1, %OPTIONS
Runs C<text_shape> over results from a C<text_wrap> call, with C<TEXT>, C<WIDTH>,
C<$OPTIONS{options}>, and C<$OPTIONS{tabs}>. Other C<%OPTIONS> are used in
the C<text_shape> call. Where C<text_wrap> returns text substrings or positions,
return glyphs objects or their positions instead.
When called with C<tw::CalcMnemonic> options, recalculates the tilde position
so it adapts to the glyph positions returned.
If C<$OPTIONS{kashida}> is set, performs kashida justification on the last
wrapped line, using optional C<$OPTIONS{min_kashida}> value ( see
L<Prima::Drawable::Glyphs/arabic_justify> ).
If C<$OPTIONS{letter}> or C<$OPTIONS{word}> is set, performs the interspace
justification on all but the last wrapped line.
=back
=head1 AUTHOR
Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>.
=head1 SEE ALSO
L<Prima>, L<Prima::Object>, L<Prima::Image>, L<Prima::Region>,
L<Prima::Drawable::Path>, L<Prima::Drawable::Glyphs>
