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. Various graphics functions are used 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 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

  • BBuf - Start a new graphics buffering context

  • Cap - Inquire a capability

  • EBuf - End the current graphics buffering context

  • 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

  • Qch - Return the character height in world coordinates

  • Scales - Get the axis scales

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

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

BBuf

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

Cap

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

int Cap( AstObject grfcon, int cap, int value )

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.

EBuf

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

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

Line

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

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

Mark

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

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

Qch

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

int Qch( AstObject grfcon, float chv, float chh )

Scales

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 grfcon, float alpha, float beta )

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

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