NAME

GD::Window - Allows the creation of windows within an GD image that have a different coordinate system.

SYNOPSIS

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

DESCRIPTION

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.

Methods

new

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:

useImage

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.

passThrough

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.

invertY

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.

image methods

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            

EXPORT

None by default.

SEE ALSO

GD, GD::Image

BUGS

Test suite is almost non-existant at the moment. Tests are being added...

AUTHOR

Edward Funnekotter, <efunneko+cpan@gmail.com<gt>

COPYRIGHT AND LICENSE

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.