GD::Window - Allows the creation of windows within an GD image that have a different coordinate system.
use GD::Window; # Globally treat the Y-axis as increasing in the upward direction # This can be set on a per-window basis too GD::Window->invertY(1); my $im = GD::Image->new(100, 100); # Create a window that will display from (10,25) to (90,75) in the # image, but the window itself will have the coordinate system # (-1000,-1000) to (1000, 1000). invertY is turned off, so Y=-1000 will be # the very top edge of the window (25 in the image) my $win = GD::Window->new($im, 10, 25, 90, 75, -1000, -1000, 1000, 1000, invertY => 0); my $col = $im->colorAllocateAlpha(75, 75, 75, 10); # Draw a line from 0,0 to 500, 500 in the window. This will # show up as a line from 50,50 to 62,62 in the image $win->line(0,0, 500, 500, $col);
GD::Window is a way to have some abstraction of drawing coordinates from the underlying image. An obvious example where this is useful is in cases where it is necessary to plot some values on a graph. The graph area within the image can be represented as a window with the exact dimensions as the graph itself allowing for easy plotting of the values. For example, if the x-axis has points that are seconds since epoch and the plot is constrained to a known time-period, then the windows X boundaries can be set to the start of the time-period and the end of the time period.
There are two very different ways to render the window onto the image. By default, the window simply transforms the X,Y coordinates (and some size values if necessary) and then calls the image's method with the transformed coordinates. In the other mode (useImage mode), a new image will be created to behind the scenes and it will be merged onto the main image. This will provide more accurate scaling and will provide clipping on the window edges, but it is slower and can use more memory.
To control which mode you use, an optional 'useImage => (0|1)' parameter can be passed to new to specify the mode. 'useImage => 1' will put the window into useImage mode.
It is also possible to layer windows on top of each other. Instead of passing an image reference to GD::Window::new, a window reference can be passed. This allows a heirchy of windows to be built.
new(<$image|$win>, imX1, imY1, imX2, imY2, winX1, winY1, winX2, winY2, %options)
Create a new window that will be placed at (imX1, imY1), (imX2, imY2) in the specified image or window. The window itself will have the coordinate system with (winX1, winY1) at one corner and (winX2, winY2) at the other corner.
The list of options are:
Instead of simply doing coordinate, height and width translations, draw to a separate image with the window's coordinate system and then put that image into the main image. This will achieve clipping for items that are outside the bounds of the window. Note that this will use a copyResampled function to put the window's image into the main image. Note also that if the window's coordinate system is very large, the window's image will consume a lot of memory.
If true ('passThrough => 1'), GD::Window will not complain about unsupported methods being called and will instead just pass them on to the image object. This can be useful if an existing program is being retrofitted with GD::Window and it is easier to just change the existing $image variable to point to a GD::Window object.
By default, GD's Y coordinates increase from the top edge of the image down towards the bottom edge of the image. If this option is set, then the Y axis will be flipped and Y coordinates will increase going up the image instead.
The following GD methods are supported within a GD::Window. They take exactly the same paramters as the normal image methods, but will do the appropriate scaling before rendering them.
setPixel line dashedLine rectangle filledRectangle ellipse filledEllipse arc filledArc fill fillToBorder copy copyMerge copyMergeGray copyResized copyResampled copyRotated string stringUp char charUp stringFT stringFTCircle clip
None by default.
Test suite is almost non-existant at the moment. Tests are being added...
Edward Funnekotter, <email@example.com<gt>
Copyright (C) 2009 by Edward Funnekotter
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.