GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  STARLINK::AST::PLPLOT (3)

.ds Aq ’

NAME

Starlink::AST::PLplot - AST wrapper to the PLplot library

CONTENTS

SYNOPSIS



   use Starlink::AST::PLplot



The main methods which need to be registered with the AST package are shown below,



   $status = _GFlush();
   $status = _GLine( \@x, \@y );
   $status = _GMark( \@x, \@y, $type );
   $status = _GText( $text, $x, $y, $just, $upx, $upy );
   ( $status, $xb, $yb ) = _GTxExt( $text, $x, $y, $just, $upx, $upy );
   ( $status, $chv, $chh ) = _GQch();
   ( $status, $old_value ) = _GAttr( $attr, $value, $prim );
   ( $status, $alpha, $beta) = _GScales();



DESCRIPTION

This file implements the low level graphics functions required by the rest of AST, by calling suitable PLplot functions.

NOTES

All the functions in this module are private, and are intended to be called from the AST module. None of these functions should be considered to be part of the packages public interface.

REVISION

$Id$

METHODS

<B>_GFlushB> This function ensures that the display device is up-to-date, by flushing any pending graphics to the output device.



   my $status = _GFlush();



<B>_GLineB> This function displays lines joining the given positions.



   my $status = _GLine( \@x, \@y );



<B>_GMarkB> This function displays markers at the given positions.



   my $status = _GMark( \@x, \@y, $type );



where $type is an integer used to indicate the type of marker required.

<B>_GTextB> This function displays a character string $text at a given position using a specified justification and up-vector.



   my $status = _GText( $text, $x, $y, $just, $upx, $upy );



where $x is the reference x coordinate, $y is the reference y coordinate, and where $just is a character string which specifies the location within the text string which is to be placed at the reference position given by x and y. The first character may be ’T’ for top, ’C’ for centre, or ’B’ for bottom, and specifies the vertical location of the reference position. Note, bottom corresponds to the base-line of normal text. Some characters (eg y, g, p, etc) descend below the base-line. The second character may be ’L’ for left, ’C’ for centre, or ’R’ for right, and specifies the horizontal location of the reference position. If the string has less than 2 characters then ’C’ is used for the missing characters.

And $upx is the x component of the up-vector for the text, in graphics world coordinates. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from left to right on the screen.

While $upy is the y component of the up-vector for the text, in graphics world coordinates. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from bottom to top on the screen.

<B>_GScalesB> This function returns two values (one for each axis) which scale increments on the corresponding axis into a normal coordinate system in which: The axes have equal scale in terms of (for instance) millimetres per unit distance, X values increase from left to right and the Y values increase from bottom to top.



   my ( $status, $alpha, $beta ) = _GScales()



<B>_GTxExtB> This function returns the corners of a box which would enclose the supplied character string if it were displayed using astGText. The returned box INCLUDES any leading or trailing spaces.



   my ( $status, $xb, $yb ) = _GTxtExt( $text, $x, $y, $just, $upx, $upy);



where $x is the reference x coordinate, $y is the reference y coordinate, and where $justification is a character string which specifies the location within the text string which is to be placed at the reference position given by x and y. The first character may be ’T’ for top, ’C’ for centre, or ’B’ for bottom, and specifies the vertical location of the reference position. Note, bottom corresponds to the base-line of normal text. Some characters (eg y, g, p, etc) descend below the base-line. The second character may be ’L’ for left, ’C’ for centre, or ’R’ for right, and specifies the horizontal location of the reference position. If the string has less than 2 characters then ’C’ is used for the missing characters.

And $upx is the x component of the up-vector for the text, in graphics world coordinates. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from left to right on the screen.

While $upy is the y component of the up-vector for the text, in graphics world coordinates. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from bottom to top on the screen.

Finally $xb is a refernce to an array of 4 elements in which to return the x coordinate of each corner of the bounding box, and $yb is a reference to an array of 4 elements in which to return the y coordinate of each corner of the bounding box.

Notes:
- The order of the corners is anti-clockwise (in world coordinates)
starting at the bottom left.
- A NULL value for just causes a value of CC to be used.
- Both upx and upy being zero causes an error.
- Any unrecognised character in just causes an error.
- Zero is returned for all bounds of the box if an error occurs.

<B>_GQchB> This function returns the heights of characters drawn vertically and horizontally in world coordinates.



   my ( $status, $chv, $chh ) = _GQch( );



Where $chv is the height of characters drawn with a vertical baseline. This will be an increment in the X axis. Where $chh is the height of characters drawn with a horizontal baseline. This will be an increment in the Y axis.

<B>_GAttrB> This function returns the current value of a specified graphics attribute, and optionally establishes a new value. The supplied value is converted to an integer value if necessary before use.



   my ( $status, $old_value ) = _GAttr( $attr, $value, $prim );



Where $attr is an integer value identifying the required attribute. The following symbolic values are defined in the AST grf.h:



           GRF__STYLE  - Line style.
           GRF__WIDTH  - Line width.
           GRF__SIZE   - Character and marker size scale factor.
           GRF__FONT   - Character font.
           GRF__COLOUR - Colour index.



$value is a new value to store for the attribute. If this is AST__BAD no value is stored, and $old_value is a scalar containing the old attribute value, if this is NULL no value is returned.

Finally $prim is the sort of graphics primitive to be drawn with the new attribute. Identified by the following values defined in AST’s grf.h:



           GRF__LINE
           GRF__MARK
           GRF__TEXT



<B>_GCapB> This function is called by the AST Plot class to determine if the grf module has a given capability, as indicated by the cap argument.



  $has_cap = _GCap( $cap, $value );



The capability string should be one of the following constants provided in the Starlink::AST::Grf namespace:

GRF__SCALES: This function should return a non-zero value if it implements the astGScales function, and zero otherwise. The supplied value argument should be ignored.

GRF__MJUST: This function should return a non-zero value if the astGText and astGTxExt functions recognise M as a character in the justification string. If the first character of a justification string is M, then the text should be justified with the given reference point at the bottom of the bounding box. This is different to B justification, which requests that the reference point be put on the baseline of the text, since some characters hang down below the baseline. If the astGText or astGTxExt function cannot differentiate between M and B, then this function should return zero, in which case M justification will never be requested by Plot. The supplied value argument should be ignored.

GRF__ESC: This function should return a non-zero value if the astGText and astGTxExt functions can recognise and interpret graphics escape sequences within the supplied string. These escape sequences are described below. Zero should be returned if escape sequences cannot be interpreted (in which case the Plot class will interpret them itself if needed). The supplied value argument should be ignored only if escape sequences cannot be interpreted by astGText and astGTxExt. Otherwise, value indicates whether astGText and astGTxExt should interpret escape sequences in subsequent calls. If value is non-zero then escape sequences should be interpreted by astGText and astGTxExt. Otherwise, they should be drawn as literal text.

Zero should be returned if the supplied capability is not recognised.

COPYRIGHT

Copyright (C) 2004-2005 Particle Physics and Astronomy Research Council. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA

AUTHORS

Tim Jenness <tjenness@cpan.org>, Alasdair Allan <aa@astro.ex.ac.uk>, Brad Cavanagh <b.cavanagh@jach.hawaii.edu>, Andy Gibb <agibb@phas.ubc.ca>.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 STARLINK::AST::PLPLOT (3) 2016-03-17

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.