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

   
astGrfSet - Register a graphics function for use by a Plot

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

Synopsis:
void astGrfSet( AstPlot *this, const char *name, AstGrfFun fun )

Parameters:
this
Pointer to the Plot.
name
A name indicating the graphics function to be replaced. Six graphics functions are used in total by the Plot class, and any combination of them may be supplied by calling this function once for each function to be replaced. If any of the six graphics functions are not replaced in this way, the corresponding functions 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
A Pointer to the function to be used to provide the functionality indicated by parameter name. The interface for each function is described below, but the function pointer should be cast to a type of AstGrfFun when calling astGrfSet.

Once a function has been provided, a null pointer can be supplied in a subsequent call to astGrfSet to reset the function to the corresponding function in the graphics interface selected at link-time.

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 astPlot 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:

int Attr( int attr, double value, double *old_value, int prim )

  • attr - An integer value identifying the required attribute. The following symbolic values are defined in 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 - A new value to store for the attribute. If this is AST__BAD no value is stored.
  • old_value - A pointer to a double in which to return the attribute value. If this is NULL, no value is returned.
  • prim - The sort of graphics primitive to be drawn with the new attribute. Identified by the following values defined in grf.h: 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:

int Flush()

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

int Line( int n, const float *x, const float *y )

  • n - The number of positions to be joined together.
  • x - A pointer to an array holding the "n" x values.
  • y - A pointer to an array holding the "n" y values.

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

int Mark( int n, const float *x, const float *y, int type )

  • n - The number of positions to be marked.
  • x - A pointer to an array holding the "n" x values.
  • y - A pointer to an array holding the "n" y values.
  • type - 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:

int Text( const char *text, float x, float y, const char *just, float upx, float upy )

  • text - Pointer to a null-terminated character string to be displayed.
  • x - The reference x coordinate.
  • y - The reference y coordinate.
  • just - 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.
  • upx - 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.
  • upy - 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:

int TxExt( const char *text, float x, float y, const char *just, float upx, float upy, float *xb, float *yb )

  • text - Pointer to a null-terminated character string to be displayed.
  • x - The reference x coordinate.
  • y - The reference y coordinate.
  • just - 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. See "Text" above.
  • upx - The x component of the up-vector for the text. See "Text" above.
  • upy - The y component of the up-vector for the text. See "Text" above.
  • xb - An array of 4 elements in which to return the x coordinate of each corner of the bounding box.
  • yb - An array of 4 elements in which to return the y coordinate of each corner of the bounding box.



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

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
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