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 ??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.

void astGrfSet( AstPlot $\ast$this, const char $\ast$name, AstGrfFun fun )

this

name

fun

All the functions listed below (except for " Cap" ) 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.

The first parameter (" grfcon" ) for each function is an AST KeyMap pointer that can be used by the called function to establish the context in which it is being called. The contents of the KeyMap are determined by the calling application, which should obtain a pointer to the KeyMap using the astGetGrfContext function, and then store any necessary information in the KeyMap using the methods of the KeyMap class. Note, the functions listed below should never annul or delete the supplied KeyMap pointer.

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( AstObject $\ast$grfcon, int attr, double value, double $\ast$old_value, int prim )

• grfcon - A KeyMap containing information passed from the calling application.

• 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.

The " BBuf" function should start a new graphics buffering context. A matching call to the function " EBuf" should be used to end the context. The nature of the buffering is determined by the underlying graphics system.

int BBuf( AstObject $\ast$grfcon )

• grfcon - A KeyMap containing information passed from the calling application.

The " Cap" function is called to determine if the grf module has a given capability, as indicated by the " cap" argument:

int Cap( AstObject $\ast$grfcon, int cap, int value )

• grfcon - A KeyMap containing information passed from the calling application.

• cap - The capability being inquired about. This will be one of the following constants defined in grf.h:

GRF__SCALES: This function should return a non-zero value if the " Scales" function is implemented, and zero otherwise. The supplied " value" argument should be ignored.

GRF__MJUST: This function should return a non-zero value if the " Text" and " TxExt" 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 " Text" or " TxExt" 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 " Text" and " TxExt" functions can recognise and interpret graphics escape sequences within the supplied string (see attribute Escape). 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 " Text" and " TxExt" . Otherwise, " value" indicates whether " Text" and " TxExt" should interpret escape sequences in subsequent calls. If " value" is non-zero then escape sequences should be interpreted by " Text" and " TxExt" . Otherwise, they should be drawn as literal text.

• value - The use of this parameter depends on the value of " cap" as described above.

• Returned Function Value: The value returned by the function depends on the value of " cap" as described above. Zero should be returned if the supplied capability is not recognised.

The " EBuf" function should end the current graphics buffering context. See the description of " BBuf" above for further details. It requires the following interface:

int EBuf( AstObject $\ast$grfcon )

• grfcon - A KeyMap containing information passed from the calling application.

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( AstObject $\ast$grfcon )

• grfcon - A KeyMap containing information passed from the calling application.

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

int Line( AstObject $\ast$grfcon, int n, const float $\ast$x, const float $\ast$y )

• grfcon - A KeyMap containing information passed from the calling application.

• 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.

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

int Mark( AstObject $\ast$grfcon, int n, const float $\ast$x, const float $\ast$y, int type )

• grfcon - A KeyMap containing information passed from the calling application.

• 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.

The " Qch" function returns the heights of characters drawn vertically and horizontally in graphics coordinates. It requires the following interface:

int Qch( AstObject $\ast$grfcon, float $\ast$chv, float $\ast$chh )

• grfcon - A KeyMap containing information passed from the calling application.

• chv - A pointer to the float which is to receive the height of characters drawn with a vertical baseline. This will be an increment in the X axis.

• chh - A pointer to the float which is to receive the height of characters drawn with a horizontal baseline. This will be an increment in the Y axis.

The " Scales" function returns two values (one for each axis) which scale increments on the corresponding axis into a " normal" coordinate system in which: 1) the axes have equal scale in terms of (for instance) millimetres per unit distance, 2) X values increase from left to right, and 3) Y values increase from bottom to top. It requires the following interface:

int Scales( AstObject $\ast$grfcon, float $\ast$alpha, float $\ast$beta )

• grfcon - A KeyMap containing information passed from the calling application.

• alpha - A pointer to the float which is to receive the scale for the X axis (i.e. Xnorm = alpha$\ast$Xworld).

• beta - A pointer to the float which is to receive the scale for the Y axis (i.e. Ynorm = beta$\ast$Yworld).

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( AstObject $\ast$grfcon, const char $\ast$text, float x, float y, const char $\ast$just, float upx, float upy )

• grfcon - A KeyMap containing information passed from the calling application.

• 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.

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( AstObject $\ast$grfcon, const char $\ast$text, float x, float y, const char $\ast$just, float upx, float upy, float $\ast$xb, float $\ast$yb )

• grfcon - A KeyMap containing information passed from the calling application.

• 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.