pod::Prima::Drawable(3)

User Contributed Perl Documentation

pod::Prima::Drawable(3)

NAME¶

Prima::Drawable - generic 2-D graphic interface

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;
   }

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.

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.

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 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-> create;
   $d-> lineWidth( 5);
   $d-> begin_paint_info;
   # lineWidth is 5 here
   $d-> lineWidth( 1);
   # lineWidth is 1
   $d-> end_paint_info;
   # lineWidth is 5 again

( Note: "::region" and "::clipRect" properties are exceptions. They cannot be used in the disabled state. The values of these properties, as well as the property "::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-> create( 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 - "Prima::Image" canvas retains its content after end_paint(), "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-> create( width => 10000, height => 10000);
   $d-> begin_paint;
   $x = $d-> get_text_width('A');
   $d-> end_paint;

is much more expensive than

   $d = Prima::Image-> create( 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.

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 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) { # this assertion is always false without
     ...                      # begin_paint/end_paint brackets
  }
  $d-> end_paint;

There are two color properties on each drawable - "::color" and "::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 "::palette" property. It works by inserting the 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.

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:

All primitives except images, "pixel", and "bar_alpha" can be plotted with antialiased edges (text is always antialiased when possible)
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 "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 "R = floor(x + 0.5)", where "R(0.7) = 1" and "R(-0.7) = -1".

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:

                 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)

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.

For the cases where the system does not support antialiasing, Prima provides the Prima::Drawable::Antialias emulation class, available through the "new_aa_surface" call.

To see if alpha and antialiasing are supported on the system, check the "sv::Antialias" value. To see if a particular drawable supports alpha layering, check the "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 "alpha" property when drawing primitives, or in the "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.

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 "color" property, and 1s using the "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 $target.

When using monochrome bitmaps for logical operations, note that the target colors should not be explicit 0 and 0xffffff, nor "cl::Black" and "cl::White", but "cl::Clear" and "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). "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.

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

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

height

An integer value from 1 to MAX_INT. Specifies the desired extent of a font glyph between descent and ascent lines in pixels.

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

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.

style

A combination of "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.

pitch

One of three constants:

   fp::Default
   fp::Fixed
   fp::Variable

"fp::Default" specifies no interest in the font pitch selection. "fp::Fixed" is set when a monospaced (all glyphs are of the same width) font is desired. "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.

vector

One of three constants:

   fv::Default
   fv::Bitmap
   fv::Outline

"fv::Default" specifies no interest in the font type selection, "fv::Bitmap" sets the priority for the bitmap fonts, and "fv::Outline" for the vector fonts.

Additionally, font entries returned from the "fonts" method may set the "vector" field to "fv::ScalableBitmap", to distinguish a bitmap font face that comes with predefined bitmap sets from a scalable font.

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.

encoding

A string value, one of the strings returned by "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

A hash that "::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 "::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 "::font" in a set-call.

To query the full list of fonts available to a graphic device, the "::fonts" method is used. This method is not present in the Prima::Drawable namespace; it can be found in two built-in class instances, "Prima::Application" and "Prima::Printer".

"Prima::Application::fonts" returns metrics for the fonts available to the screen device, while "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 "Prima::Drawable::font" method.

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

ascent

Number of pixels between a glyph baseline and descent line.

descent

Number of pixels between a glyph baseline and descent line.

internalLeading

Number of pixels between ascent and internal leading lines. Negative if the ascent line is below the internal leading line.

externalLeading

Number of pixels between ascent and external leading lines. Negative if the ascent line is above the external leading line.

          ------------- external leading line
     $    ------------- ascent line
    $ $
          ------------- internal leading line
     $
    $$$
   $   $
  $     $       $
  $$$$$$$    $$$
  $     $   $   $
  $     $   $   $
  $     $    $$$   ---- baseline
                $
                 $
                 $
             $$$$  ---- descent line

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.

maximalWidth

The maximal extent of a glyph in pixels. Equals to width in monospaced fonts.

xDeviceRes

Designed horizontal font resolution in dpi.

yDeviceRes

Designed vertical font resolution in dpi.

firstChar

Index of the first glyph present in a font.

lastChar

Index of the last glyph present in a font.

breakChar

Index of the default character used to divide words. In a typical Western language font it is 32, the ASCII space character.

defaultChar

Index of a glyph that is drawn instead of a nonexistent glyph if its index is passed to the text drawing routines.

underlinePosition

Position below baseline where to draw underscore line, in pixels. Is negative.

underlineThickness

Pixel width of the underscore line

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:

    .  .     .  .      .  .        .  .
    .  .     $$$.      .  .        .  .
    .  .   $$.  $      .  .        .  .
    .  .   $$.  .      .  .     $$ .  .
    . $$$$$$$$$$.      .  .$$$$$   .  .
    .  .  $$ .  .      .  $    $$  .  .
    .  . $$  .  .      .  .$$$$$   .  .
    .  . $$  .  .      .  .    $$  .  .
    .  .$$   .  .      .  . $$$ $$$.  .
    $$ .$$   .  .      .  $       $$  .
    .$$$     .  .      .  .$$$$$$$$.  .
    .  .     .  .      .  .        .  .
    <A>.     .<C>      <A>.        .<C>
    .<-.--B--.->.      .  .<--B--->.  .
      A = -3                A = 3
      B = 13                B = 10
      C = -3                C = 3

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 "DEF" metrics, are returned by the get_font_def() method.

Raster operations¶

The Prima::Drawable class has two raster operation properties: "::rop" and "::rop2". These define how the graphic primitives are plotted. "::rop" deals with the foreground color drawing, and "::rop2" with the background.

Universal ROPs

The toolkit defines the following operations:

   rop::Blackness      #   = 0
   rop::NotOr          #   = !(src | dest)
   rop::NotSrcAnd      #  &= !src
   rop::NotPut         #   = !src
   rop::NotDestAnd     #   = !dest & src
   rop::Invert         #   = !dest
   rop::XorPut         #  ^= src
   rop::NotAnd         #   = !(src & dest)
   rop::AndPut         #  &= src
   rop::NotXor         #   = !(src ^ dest)
   rop::NotSrcXor      #     alias for rop::NotXor
   rop::NotDestXor     #     alias for rop::NotXor
   rop::NoOper         #   = dest
   rop::NotSrcOr       #  |= !src
   rop::CopyPut        #   = src
   rop::NotDestOr      #   = !dest | src
   rop::OrPut          #  |= src
   rop::Whiteness      #   = 1

Usually, however, graphic devices support only a small part of the above set, limiting "::rop" to the most important operations: Copy, And, Or, Xor, NoOp. "::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 "put_image" and "stretch_image" can only use "rop::SrcCopy" and "rop::Blend" raster operations on OS-provided surfaces. See more on "rop::Blend" below.

Also, the "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.

rop::Blend

"rop::Blend" is the same as "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 "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.

Default raster operations

The "put_image", "stretch_image", and "put_image_indirect" methods are allowed to be called without explicitly specifying the ROP to be used. In this case, the default ROP, that depends on the source drawable, will be used. In the majority of cases the default ROP is "rop::CopyPut", however, when drawing using layered device bitmaps and icons with 8-bit alpha masks, "rop::Blend" is used instead. This is a sort of a DWIM behavior.

This effect is achieved by translating the "rop::Default" constant via the "get_effective_rop" method, that can be used to detect what is the preferred raster operation for a source drawable. "rop::Default" can only be used in the aforementioned there methods, not in the "rop" property, not anywhere else.

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:

   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

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 "rop::alpha($rop, [ $src_alpha, [ $dst_alpha ]])" that does the same.

Also, the function 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

"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 "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 "$image->alpha" is 255; add the rop flags "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 "rop::CopyPut" and "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.

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);

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 "::matrix" property that translates the (0,0) point to the given offset. Calls to "::matrix", "::clipRect" and "::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.

Matrix

The "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, "get_matrix" and "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 "get_matrix" returns is also a blessed object of type "Prima::matrix" ( see "Prima::matrix" in Prima::types ) that is a separate copy of the object matrix. "Prima::matrix" objects feature a set of operations such as "rotate" and "translate" that transform the matrix further. To apply this matrix, one calls "$drawable->set_matrix($matrix)" or "$matrix->apply($drawable)".

There is also a property "matrix" that is not orthogonal to the "get_matrix"/ "set_matrix" method pair, as "matrix" returns a "Prima::Matrix" object, that, contrary to a "Prima::matrix" object returned by "get_matrix", is a direct accessor to the drawable's matrix:

        my $m = $self->get_matrix;
        $m->translate(1,2);
        $self->set_matrix($m); # or $self->matrix($m);

is the same as

        $self->matrix->translate(1,2);

and does not need an explicit call to "set_matrix" or "apply".

This class has all the methods the "Prima::matrix" has. See more in "Prima::Matrix" in Prima::types. See also: reset_matrix.

Custom line end styles¶

Prima uses its own plotting mechanism in Prima::Drawable::Path to produce all primitive shapes, including lines. The way lines are plotted is managed by the properties "lineEnd", "lineJoin", "linePattern", and "miterLimit". All of these properties are described below, however, "lineEnd" provides rich capabilities to generate custom line ends, and this is what is described in this section.

le:: namespace

There are 3 predefined "le::" integer constants

  le::Flat
  le::Square
  le::Round

that are hardcoded in Prima, that are accepted by the "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 "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):

   # all three lines produce the same effect
   $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) ) );

lineEnd accessors

The "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 "lineHead", "lineTail", "arrowHead", and "arrowTail", or an index-based accessor "lineEndIndex":

                   [ lineHeads and lineTails ]
            \____    ____    ___     __   ____   ___\
            /                                       /
         arrowTail                                  arrowHead

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 "line", 2 for "conic", and 3 for "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 "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]
     ]

API¶

Graphic context properties¶

alpha INTEGER

Sets the alpha component of the brush, where 0 is fully transparent and 255 is fully opaque.

Note that premultiplication of "color" and "backColor" is not necessary as it is done internally.

Default: 255

antialias BOOLEAN

Turns on and off antialiased drawing on all primitives, excluding image, "pixel", and "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 "Antialiasing and alpha".

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 "undef", the heads are painted with the same style as "lineHead"

Default value: "le::Round". Cannot be "undef".

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 "undef", the heads are painted with the same style as "lineTail"; if it is also "undef", then the style of "lineHead" is used.

Default value: "undef"

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.

color COLOR

Sets foreground color to the graphic context. All drawing routines use this property value.

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 "::region" value.

Note: "::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 "Graphic context and canvas") -- except on images.

fillMode INTEGER

Affects the filling style of complex polygonal shapes filled by "fillpoly". If "fm::Winding", the filled shape contains no holes; if "fm::Alternate", holes are present where the shape edges cross.

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

Default value: "fm::Winding|fm::Overlay"

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 "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 "backColor", and 1s as "color". When "rop2" is set to "rop::NoOper", treats 0s as fully transparent pixels. Additionally, when in the render mode respects the "alpha" property.

Note: Drawing over a monochrome bitmap or image will not respect its "rop" on Win32.

Depending on the parameters, treats the input as follows:

fp:: constant

There are some predefined patterns, that can be referred to via "fp::" constants:

  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

( the actual patterns are hardcoded in api/api.c ) The default pattern is fp::Solid.

On a get-call, does not return the "fp::" value but the corresponding array (see below). If a constant value is needed to be recovered, use the "fp::builtin" function that would return the constant from the array. There are also two shortcut functions, "fp::is_solid" and "fp::is_empty" that check if the fill pattern is all-ones or all-zeros, correspondingly.

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:

   # 76543210
     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 ]);

Monochrome image

Like the array above, wants an image consisting of 0s and 1s where these would represent the target canvas' "backColor" and "color" property values, correspondingly, when rendered. In the same fashion, when "rop2" is set to "rop::NoOper", zeros will be treated as transparent pixels.

Color image

Ignores color, and backColor, and rop2. Just uses the tiles and the current "alpha" value.

Icon

Ignores color, backColor, and rop2. Uses the alpha pixel values from the icon's mask and the current "alpha" value.

fillPatternOffset X, Y

Origin coordinates for the "fillPattern". Image patterns origin (0,0) is system-dependent.

font \%FONT

Manages font context. FONT hash acceptable values are "name", "height", "size", "width", "style" and "pitch".

Synopsis:

   $d-> font-> size( 10);
   $d-> font-> name( 'Courier');
   $d-> font-> set(
     style => $x-> font-> style | fs::Bold,
     width => 22
   );

See "Fonts" for the detailed descriptions.

Applies to text_out(), get_text_width(), get_text_box(), get_font_abc(), get_font_def(), render_glyph().

font_mapper

Returns a font mapper object that provides the interface to a set of fonts used for substitution in polyfont shaping (see "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, passive and 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 "active" font list is built, and the next substitutions use it before trying to look into the passive list. Since the 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:

activate %FONT: Adds the FONT into the active substitution list if the font is not disabled
get INDEX: Returns the font hash registered under INDEX
count: Returns the number of all fonts in the collection
index: Returns what index is assigned to the currently used font, if any
passivate %FONT: Remove the font from the active substitution list
is_active %FONT: Returns whether the font is in the active substitution list or not
enable %FONT: Enables the font entry, the font will be considered for the polyfont lookup
disable %FONT: Disables the font entry, the font will not be considered for the polyfont lookup
is_enabled %FONT: Returns whether the font is enabled or not

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: "undef"

lineEnd VALUE

Selects a line ending cap for plotting primitives. VALUE can be one of

  le::Arrow
  le::Cusp
  le::InvCusp
  le::Flat
  le::Knob
  le::Rect
  le::RoundRect
  le::Spearhead
  le::Square
  le::Round
  le::Tail

constants, "undef", a custom line end description, or an array of four where each entry is one of the values above.

The "undef" value is only accepted in the array syntax, and not for the index 0 ("lineHead"). The other indexes behave differently if are set to "undef" - see more in "lineTail", "arrowHead", "arrowTail", and "lineEndIndex".

"le::Round" is the default value.

Other properties¶

height HEIGHT: Selects the height of a canvas.
size WIDTH, HEIGHT: Selects the extent of a canvas.
width WIDTH: Selects the width of a canvas.

Graphic primitives methods¶

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

bar X1, Y1, X2, Y2

Draws a filled rectangle

Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2

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.

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

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

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

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.

"draw_text" is a convenience wrapper around "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

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

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

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

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]); # triangle

Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2, fillMode

Returns success flag; if failed, $@ contains the error.

Methods¶

begin_paint

Enters the enabled ( active paint ) state and returns the success flag; if failed, $@ contains the error. Once the object is in the enabled state, painting and drawing methods can write on the canvas.

See also: "end_paint", "begin_paint_info", "Graphic context and canvas"

begin_paint_info

Enters the information state and returns the success flag; if failed, $@ contains the error. The object information state is the same as the enabled state ( see "begin_paint"), except painting and drawing methods do not change the object canvas.

See also: "end_paint_info", "begin_paint", "Graphic context and canvas"

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.

AUTHOR¶

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

Source file:	pod::Prima::Drawable.3pm.en.gz (from perl-Prima 1.74000-1.1)
Source last updated:	2024-08-20T05:30:45Z
Converted to HTML:	2024-12-25T01:26:44Z

NAME¶

SYNOPSIS¶

DESCRIPTION¶

USAGE¶

Graphic context and canvas¶

Color space¶

Antialiasing and alpha¶

Monochrome bitmaps¶

Fonts¶

Font ABC metrics¶

Raster operations¶

Coordinates¶

Custom line end styles¶

API¶

Graphic context properties¶

Other properties¶

Graphic primitives methods¶

Methods¶

AUTHOR¶

SEE ALSO¶