macro to retrieve the alpha component. 0 is transparent, 255
is opaque.
=head3 cdDecodeAlpha()
$alpha = $canvas->cdDecodeAlpha($color);
#or
$alpha = IUP->Canvas->cdDecodeAlpha($color);
Returns the alpha component of a color in the CD library. Can be used
without an active canvas. 0 is transparent, 255 is opaque.
=head3 cdAlpha()
$alpha = $canvas->cdAlpha($color); #XXX-TODO check this
#or
$alpha = IUP::Canvas->cdAlpha($color);
Macro that returns the alpha component of a color in the CD library.
Can be used without an active canvas.
=head3 cdRed()
$red = $canvas->cdRed($color);
#or
$red = IUP::Canvas->cdRed($color);
Macro that returns the red component of a color in the CD library. Can
be used without an active canvas.
=head3 cdGreen()
$green = $canvas->cdGreen($color);
#or
$green = IUP::Canvas->cdGreen($color);
Macro that returns the green component of a color in the CD library.
Can be used without an active canvas.
=head3 cdBlue()
$blue = $canvas->cdBlue($color);
#or
$blue = IUP::Canvas->cdBlue($color);
Macro that returns the blue component of a color in the CD library. Can
be used without an active canvas.
=head3 cdGetColorPlanes()
$bpp = $canvas->cdGetColorPlanes();
Returns a given number, for instance I, which defines the number of
colors supported by the current device as I<2p>, representing the
number of bits by pixel.
=head3 cdPalette()
$canvas->cdPalette($palette, $mode); #XXX-TODO
In systems limited to 256 palette colors, this function aims at adding
B> colors to the system's palette. In such systems, the colors
demanded forward or backward which are not in the palette are
approximated to the closest available color. The type can be
B or B. B ignores the system
colors and interface elements, since the menus and dialogues may be in
illegible colors, but there will be more colors available.
C> is the recommended type. It must always be used before
drawing. It cannot be queried.
=head3 cdCreatePalette()
$palete = $canvas=>cdCreatePalette($size);
#or
$palete = IUP::Canvas=>cdCreatePalette($size);
Creates a palette.
=head3 cdKillPalette()
$canvas->cdKillPalette($palette);
#or
IUP::Canvas->cdKillPalette($palette);
Destroys the created palette and liberates allocated memory. If this
function is not called in Lua, the garbage collector will call it.
=head3 Palette Data Access
Data access in Lua is done directly using the array access operators.
The colors can have their values checked or changed directly as if they
were Lua tables:
$palette->[$index] = IUP::Canvas->cdEncodeColor($r, $g, $b);
#...
$color = $palette->[$index];
($r, $g, $b) = IUP::Canvas->cdDecodeColor($color);
Notice that the type of value returned or received by palette[index] is
a lightuserdata, the same type used with functions L,
L, L, L and L.
=head2 Methods - Coordinate System
=head3 cdGetSize()
($width, $height, $mm_width, $mm_height) = $canvas->cdGetSize();
Returns the canvas size in pixels and in millimeters. You can provide
only the desired values and C for the others.
=head3 cdYAxisMode()
$old_invert = $canvas->cdYAxisMode($invert);
Controls the orientation of the Y axis. Internally in some drivers the
native axis orientation is top-bottom, so the CD primitives must invert
the Y axis since the CD orientation is bottom-top. Using CD_QUERY will
return the current Y axis mode, if needs to be invert or not. Using 1
or 0 you can control if the Y axis should be inverted or not
independent from the native orientation, with that you can in fact
invert the orientation of the CD primitives.
=head3 cdUpdateYAxis()
$yr = $canvas->cdUpdateYAxis($yc);
$yr = $canvas->cdInvertYAxis($yc);
#XXX-TODO cdfCanvasInvertYAxis
#XXX-TODO cdfCanvasUpdateYAxis
Converts the coordinate system of the CD library into the internal
system of the active canvas' driver, and the other way round, if they
are invert, or else do nothing. This is just "y = height-1 - y". It
returns the changed value. The "Invert" will always invert the given
value, the "Update" function will invert only if the canvas has the Y
axis inverted.
=head3 cdMM2Pixel()
($dx, $dy) = $canvas->cdMM2Pixel($mm_dx, $mm_dy);
($dx, $dy) = $canvas->cdfMM2Pixel($mm_dx, $mm_dy);
Converts sizes in millimeters into pixels (canvas coordinates). You can
provide only the desired values and C for the others.
=head3 cdPixel2MM()
($mm_dx, $mm_dy) = $canvas->cdPixel2MM($dx, $dy);
($mm_dx, $mm_dy) = $canvas->cdfPixel2MM($dx, $dy);
Converts sizes in pixels (canvas coordinates) into millimeters. You can
provide only the desired values and C for the others. Use this
function to obtain the horizontal and vertical resolution of the canvas
by passing 1 as parameter in dx and dy. The resolution value is
obtained using the formula B.
=head3 cdOrigin()
$canvas->cdOrigin($x, $y);
$canvas->cdfOrigin($x, $y);
Allows translating the origin - for instance, to the center of the
canvas. The function profits from the architecture of the library to
simulate a translation of the origin, which in fact is never actually
passed to the canvas in the respective driver. It is not related with
WD nor Transformation Matrix. Default values: (0, 0)
=head3 cdGetOrigin()
($x, $y) = $canvas->cdGetOrigin();
($x, $y) = $canvas->cdfGetOrigin();
Returns the origin.
=head3 cdTransform()
$canvas->cdTransform($matrix);
Defines a transformation matrix with 6 elements. If the matrix is C,
the transformation is reset to the identity. Default value: C.
The matrix contains scale, rotation and translation elements as
follows:
|x'| |sx*cos(angle) -sin(angle) dx| |x| | $matrix->[0] $matrix->[2] $matrix->[4] |
|y'| = | sin(angle) sy*cos(angle) dy| * |y| with indices | $matrix->[1] $matrix->[3] $matrix->[5] |
|1|
But notice that the indices are different of the L.
Functions that retrieve images from the canvas are not affected by the
transformation matrix, such as L and L.
Transformation matrix is independent of the B and
B functions. And those are affected if a transformation is set,
just like other regular primitives.
=head3 cdGetTransform()
$matrix = $canvas->cdGetTransform();
Returns the transformation matrix. If the identity is set, returns C.
=head3 cdTransformMultiply()
$canvas->cdTransformMultiply($matrix);
Left multiply the current transformation by the given transformation.
=head3 cdTransformTranslate()
$canvas->cdTransformTranslate($dx, $dy);
Applies a translation to the current transformation.
=head3 cdTransformScale()
$canvas->cdTransformScale($sx, $sy);
Applies a scale to the current transformation.
=head3 cdTransformRotate()
$canvas->cdTransformRotate($angle);
Applies a rotation to the current transformation. Angle is in degrees,
oriented counter-clockwise from the horizontal axis.
=head3 cdTransformPoint()
($tx, $ty) = $canvas->cdTransformPoint($x, $y); #returns integers
($tx, $ty) = $canvas->cdfTransformPoint($x, $y); #returns real numbers
Applies a transformation to a given point.
=head2 Methods - World Coordinates
Allows the use of a World Coordinate System. In this system you can
attribute coordinates to any unit you want. After you define a window
(rectangular region) in your world, each given coordinate is then
mapped to canvas coordinates to draw the primitives. You can define a
viewport in your canvas to change the coordinate mapping from world to
canvas. The image below shows the relation between Window and Viewport.
Window x Viewport
=for html 
If you want to map coordinates from one system to another, use the
B e B functions.
The quality of the picture depends on the conversion from World to
Canvas, so if the canvas has a small size the picture quality will be
poor. To increase picture quality create a canvas with a larger size,
if possible.
All World Coordinate drawing in all drivers are simulated using other
CD primitives and do NOT depend or use the L
transformation matrix.
XXX-TODO: add note on method naming convenction:
$canvas->cdMethodName vs. $canvas->wdMethodName
=head3 wdWindow()
$canvas->wdWindow($xmin, $xmax, $ymin, $ymax);
Configures a window in the world coordinate system to be used to
convert world coordinates (with values in real numbers) into canvas
coordinates (with values in integers). The default window is the size
in millimeters of the whole canvas.
=head3 wdGetWindow
($xmin, $xmax, $ymin, $ymax) = $canvas->wdGetWindow();
Queries the current window in the world coordinate system being used to
convert world coordinates into canvas coordinates (and the other way
round). It is not necessary to provide all return pointers, you can
provide only the desired values.
=head3 wdViewport
$canvas->wdViewport($xmin, $xmax, $ymin, $ymax);
Configures a viewport in the canvas coordinate system to be used to
convert world coordinates (with values in real numbers) into canvas
coordinates (with values in integers). The default viewport is the
whole canvas (0,w-1,0,h-1). If the canvas size is changed, the viewport
will not be automatically updated.
=head3 wdGetViewport()
($xmin, $xmax, $ymin, $ymax) = $canvas->wdGetViewport();
Queries the current viewport in the world coordinate system being used
to convert world coordinates into canvas coordinates (and the other way
round). It is not necessary to provide all return pointers, you can
provide only the desired values and C for the others.
=head3 wdWorld2Canvas()
($xv, $yv) = $canvas->wdWorld2Canvas($xw, $yw);
Converts world coordinates into canvas coordinates. It is not necessary
to provide all return pointers, you can provide only the desired values
and C for the others.
=head3 wdCanvas2World()
($xw, $yw) = $canvas->wdCanvas2World($xv, $yv);
Converts canvas coordinates into world coordinates. It is not necessary
to provide all return pointers, you can provide only the desired values
and C for the others.
=head3 wdSetTransform()
$canvas->wdSetTransform($sx, $sy, $tx, $ty);
Configures the world coordinate system transformation to be used to
convert world coordinates (with values in real numbers) into canvas
coordinates (with values in integers). The transformation is
automatically set by B and B. This
has NO relation with L.
=head3 wdGetTransform()
($sx, $sy, $tx, $ty) = $canvas->wdGetTransform();
Queries the current transformation being used to convert world
coordinates into canvas coordinates (and the other way round). It is
not necessary to provide all return pointers, you can provide only the
desired values.
=head3 wdTranslate()
$canvas->wdTranslate($dtx, $dty);
Translates the transformation by a delta, by adding the given values to
the current tx and ty values.
=head3 wdScale()
$canvas->wdScale($dsx, $dsy);
Scales the transformation by a delta, by multiplying the given values
by the current sx and sy values.
=head3 wdCanvasHardcopy()
$canvas->wdCanvasHardcopy($ctx, $data, $draw_func); #XXX-TODO
Creates a new canvas, prepares Window and Viewport according to the
provided canvas, maintaining the aspect ratio and making the drawing
occupy the largest possible area of the new canvas, calls the drawing
function (which must use routines in WC) and, finally, removes the new
canvas.
It is usually used for "hard copies" of drawings (print equivalent
copy). The most common used contexts are Printer, PS and PDF.
=head2 Methods - Primitives / Marks
A mark is a punctual representation. It can have different sizes and
types. All types are affected only by mark attributes and by the
foreground color.
All marks in all drivers are simulated using other CD primitives,
except L.
=head3 cdPixel()
$canvas->cdPixel($x, $y, $color);
$canvas->wdPixel($x, $y, $color);
Configures the pixel B<(x,y)> with the color defined by B. It is
the smallest element of the canvas. It depends only on global
attributes of the canvas. It can be very slow on some drivers.
Sometimes it is implemented as a rectangle with size 1x1.
=head3 cdMark()
$canvas->cdMark($x, $y);
$canvas->wdMark($x, $y);
Draws a mark in B<(x,y)> using the current foreground color. It is
not possible to use this function between a call to functions
L and L if the type of mark is set to
B. If the active driver does not include this primitive, it
will be simulated using other primitives from the library, such as
L.
If you will call this function several times in a sequence, then it is
recommended that the application changes the filling and line
attributes to those used by this function:
$canvas->cdInteriorStyle(CD_SOLID);
$canvas->cdLineStyle(CD_CONTINUOUS);
$canvas->cdLineWidth(1);
This will greatly increase this function's performance. Also in this
case, if the mark is very small, we suggest using the L
function so that the application itself draws the mark. In many cases,
this also increases this function's performance.
=head3 cdMarkType()
$canvas->cdMarkType($type);
Configures the current mark type for: B, B,
B, B, B, B, B,
B or B. Returns the previous value.
Default value: B. Value Bsimply returns the
current value.
Mark Types:
=for html 
=head3 cdMarkSize()
$old_size = $canvas->cdMarkSize($number);
$old_size = $canvas->wMarkSize($number);
Configures the mark size in pixels. Returns the previous value. Default
value: 10. Value B simply returns the current value. Valid
width interval: E= 1.
In WC, it configures the current line width in millimeters.
=head2 Methods - Primitives / Lines
Line are segments that connects 2 or more points. The L function
includes the 2 given points and draws the line using the foreground
color. Line thickness is controlled by the L function. By
using function L you can draw dashed lines with some
variations. Lines with a style other than continuous are affected by
the back opacity attribute and by the background color.
=head3 cdLine()
$canvas->cdLine($x1, $y1, $x2, $y2);
$canvas->cdfLine($x1, $y1, $x2, $y2);
$canvas->dwLine($x1, $y1, $x2, $y2);
Draws a line from B<(x1,y1)> to C> using the current
foreground color and line width and style. Both points are included in
the line.
Open polygons can be created using:
$canvas->cdBegin(CD_OPEN_LINES);
$canvas->cdVertex($x,$y);
#...
$canvas->cdEnd();
Closed polygons use the same number of vertices but the last point is
automatically connected to the first point. Closed polygons can be
created using:
$canvas->cdBegin(CD_CLOSED_LINES);
$canvas->cdVertex($x,$y);
#...
$canvas->cdEnd();
Bezier lines can be created using:
$canvas->cdBegin(CD_BEZIER);
$canvas->cdVertex($x,$y);
#...
$canvas->cdEnd()
At least 4 vertices must be defined. The two vertices of the middle are the
control vertices. A sequence of bezier lines can be defined using more
3 vertices, two control points and an end point, the last point of the
previous bezier will be used as the start point.
See the documentation of XXX-polygon section-XXX
L
L
L
=head3 cdRect()
$canvas->cdRect($xmin, $xmax, $ymin, $ymax);
$canvas->cdfRect($xmin, $xmax, $ymin, $ymax); #XXX-TODO autodetect int vs. double
$canvas->wdRect($xmin, $xmax, $ymin, $ymax);
Draws a rectangle with no filling. All points in the limits of interval
B E= B E= B, B E= B E= B will be painted. It
is affected by line attributes and the foreground color. If the active
driver does not include this primitive, it will be simulated using the
L primitive.
=head3 cdArc()
$canvas->cdArc($xc, $yc, $w, $h, $angle1, $angle2);
$canvas->cdfArc($xc, $yc, $w, $h, $angle1, $angle2);
$canvas->wdArc($xc, $yc, $w, $h, $angle1, $angle2);
Draws the arc of an ellipse aligned with the axis, using the current
foreground color and line width and style.
The coordinate B<(xc,yc)> defines the center of the ellipse. Dimensions
B and B define the elliptic axes X and Y, respectively.
Angles B and B are in degrees and oriented
counter-clockwise. They define the arc start and end, but they are not
the angle relative to the center, except when w==h and the ellipse is
reduced to a circle. The arc starts at the point
C<(xc+(w/2)*cos(angle1), yc+(h/2)*sin(angle1))> and ends at
C<(xc+(w/2)*cos(angle2), yc+(h/2)*sin(angle2))>. A complete ellipse can
be drawn using 0 and 360 as the angles. If B is less than
B it will be increased by 360 until it is greater than
B.
The angles are specified so if the size of the ellipse (w x h) is
changed, its shape is preserved. So the angles relative to the center
are dependent from the ellipse size. The actual angle can be obtained
using CB<)*sin(angle), (w/2)*cos(angle))>.
To specify the angle in radians, you can use the definition
B to multiply the value in radians before passing the angle
to CD.
Arc Parameters:
=for html 
=head3 cdLineStyle()
$old_style = $canvas->cdLineStyle($style);
Configures the current line style for: B, B,
B, B B or C>.
Returns the previous value. Default value: B. Value
B simply returns the current value. When B is used
the L function must be called before to initialize
the custom dashes. The spaces are drawn with the background color,
except when back opacity is transparent then the background is left
unchanged. See L.
Line Styles:
=for html 
=head3 cdLineStyleDashes()
$canvas->cdLineStyleDashes(\@dashes);
Defines the custom line style dashes. The first value is the length of
the first dash, the second value is the length of the first space, and
so on. For example: C<@dashes = (10 2 5 2)> means dash size 10, space size 2, dash
size 5, space size 2, and repeats the pattern. Sizes are in pixels.
=head3 cdLineWidth()
$old_width = $canvas->cdLineWidth($width);
$old_width = $canvas->wdLineWidth($width_mm);
Configures the width of the current line (in pixels). Returns the
previous value. Default value: 1. Value B simply returns
the current value. Valid width interval: E= 1.
In WC, it configures the current line width in millimeters.
=head3 cdLineJoin()
$old_style = $canvas->cdLineJoin($style);
Configures the current line style for: B, B or
B. Returns the previous value. Default value: B.
Value B simply returns the current value.
Line Joins:
=for html 
=head3 cdLineCap()
$old_style = $canvas->cdLineCap($style);
Configures the current line style for: B, B
or B. Returns the previous value. Default value:
B. Value B simply returns the current value.
Line Caps:
=for html 
=head2 Methods - Primitives / Polygons
The functions L, L and L are use for many
situations. L is called once, L can be called many
times, and L is called once to actually do something. If you
call L again before L the process is restarted, except
for BBB<)> that can contains one or more polygons
inside.
=head3 cdBegin()
$canvas->cdBegin($mode);
Starts defining a polygon to be drawn (or filled) according to the
mode: B, B, BB>B or B>. Do not create embedded
polygons, that is, do not call function L twice without a call
to L in between.
=over
=item * B connects all the points at cdEnd. Depends
on line width and line style attributes.
=item * connects all the points at cdEnd and
connects the last point to the first. Depends on line width and line
style attributes.
=item * B connects the last point to the first and fills the
resulting polygon according to the current interior style. When the
interior style B is defined the it behaves as if the mode
were B.
=item * Bnstead of creating a polygon to be drawn, creates
a polygon to define a polygonal clipping region.
=item * B> defines the points of a bezier curve. There
must be at least 4 points: I, I, I< control> and
I. To specify a sequence of curves use 3 more points for each
curve: I, I, I, I, I< control>, I,
... The end point is used as start point for the next curve.
=item * B>: starts the creation of a complex region for
clipping. All calls to L, L, L,
B
