next up previous
Next: AST_GRID - Draw a set of labelled coordinate axes
Up: AST Routine Descriptions
Previous: AST_GRFPUSH - Save the current graphics functions used by a Plot

   
AST_GRFSET - Register a graphics routine for use by a Plot

Description:
This routine can be used to select the underlying graphics routines to be used when the supplied Plot produces graphical output. If this routine is not called prior to producing graphical output, then the underlying graphics routines selected at link-time (using the ast_link command) will be used. To use alternative graphics routines, call this routine before the graphical output is created, specifying the graphics routines to be used. This will register the routine for future use, but the routine will not actually be used until the Grf attribute is given a non-zero value.

Invocation:
CALL AST_GRFSET( THIS, NAME, FUN, STATUS )

Arguments:
THIS = INTEGER (Given)
Pointer to the Plot.
NAME = CHARACTER * ( * ) (Given)
A name indicating the graphics routine to be replaced. Six graphics routines are used in total by the Plot class, and any combination of them may be supplied by calling this routine once for each routine to be replaced. If any of the six graphics routines are not replaced in this way, the corresponding routines in the graphics interface selected at link-time (using the ast_link command) are used. The allowed names are:

  • Attr - Enquire or set a graphics attribute value
  • Flush - Flush all pending graphics to the output device
  • Line - Draw a polyline (i.e. a set of connected lines)
  • Mark - Draw a set of markers
  • Text - Draw a character string
  • TxExt - Get the extent of a character string

The string is case insensitive. For details of the interface required for each, see the sections below.

FUN = INTEGER FUNCTION (Given)
The name of the routine to be used to provide the functionality indicated by parameter NAME (the name should also appear in a Fortran EXTERNAL statement in the routine which invokes AST_GRFSET).

Once a routine has been provided, the "null" routine AST_NULL can be supplied in a subsequent call to astGrfSet to reset the routine to the corresponding routine in the graphics interface selected at link-time. AST_NULL is defined in the AST_PAR include file.

STATUS = INTEGER (Given and Returned)
The global status.

Function Interfaces
All the functions listed below should return an integer value of 0 if an error occurs, and 1 otherwise. All x and y values refer to "graphics cordinates" as defined by the GRAPHBOX parameter of the AST_PLOT call which created the Plot.

Attr
The "Attr" 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. It requires the following interface:

INTEGER FUNCTION ATTR( ATT, VAL, OLDVAL, PRIM )

  • ATT = INTEGER (Given) - An integer identifying the required attribute. The following symbolic values are defined in GRF_PAR: GRF__STYLE (Line style), GRF__WIDTH (Line width), GRF__SIZE (Character and marker size scale factor), GRF__FONT (Character font), GRF__COLOUR (Colour index).
  • VAL = DOUBLE PRECISION (Given) - no value is stored.
  • OLDVAL = DOUBLE PRECISION (Returned) - Returned holding the attribute value.
  • PRIM = INTEGER (Given) - The sort of graphics primitive to be drawn with the new attribute. Identified by the following values defined in GRF_PAR: GRF__LINE, GRF__MARK, GRF__TEXT.

Flush
The "Flush" function ensures that the display device is up-to-date, by flushing any pending graphics to the output device. It requires the following interface:

INTEGER FUNCTION FLUSH()

Line
The "Line" function displays lines joining the given positions and requires the following interface:

INTEGER FUNCTION LINE( N, X, Y )

  • N = INTEGER (Given) - The number of positions to be joined together.
  • X( N ) = REAL (Given) - An array holding the "n" x values.
  • Y( N ) = REAL (Given) - An array holding the "n" y values.

Mark
The "Mark" function displays markers at the given positions. It requires the following interface:

INTEGER FUNCTION MARK( N, X, Y, TYPE )

  • N = INTEGER (Given) - The number of positions to be marked.
  • X( N ) = REAL (Given) - An array holding the "n" x values.
  • Y( N ) = REAL (Given) - An array holding the "n" y values.
  • TYPE = INTEGER (Given) - An integer which can be used to indicate the type of marker symbol required.

Text
The "Text" function displays a character string at a given position using a specified justification and up-vector. It requires the following interface:

INTEGER FUNCTION TEXT( TEXT, X, Y, JUST, UPX, UPY )

  • TEXT = CHARACTER * ( * ) (Given) - The string to be displayed.
  • X = REAL (Given) - The reference x coordinate.
  • Y = REAL (Given) - The reference y coordinate.
  • JUST = CHARACTER * ( * ) (Given ) - A 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.
  • UPX = REAL (Given) - The x component of the up-vector for the text. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from left to right on the screen.
  • UPX = REAL (Given) - The y component of the up-vector for the text. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from bottom to top on the screen.

TxExt
The "TxExt" function returns the corners of a box which would enclose the supplied character string if it were displayed using the Text function described above. The returned box includes any leading or trailing spaces. It requires the following interface:

INTEGER FUNCTION TXEXT( TEXT, X, Y, JUST, UPX, UPY, XB, YB )

  • TEXT = CHARACTER * ( * ) (Given) - The string to be displayed.
  • X = REAL (Given) - The reference x coordinate.
  • Y = REAL (Given) - The reference y coordinate.
  • JUST = CHARACTER * ( * ) (Given ) - A string which specifies the location within the text string which is to be placed at the reference position given by x and y. See "Text" above.
  • UPX = REAL (Given) - The x component of the up-vector for the text. See "Text" above.
  • UPX = REAL (Given) - The y component of the up-vector for the text. See "Text" above.
  • XB( 4 ) = REAL (Returned) - Returned holding the x coordinate of each corner of the bounding box.
  • YB( 4 ) = REAL (Returned) - Returned holding the y coordinate of each corner of the bounding box.



next up previous
Next: AST_GRID - Draw a set of labelled coordinate axes
Up: AST Routine Descriptions
Previous: AST_GRFPUSH - Save the current graphics functions used by a Plot

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
30th April 2003
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2003 Central Laboratory of the Research Councils