Register a graphics routine for use by a Plot
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.
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.
"
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 AST_PLOT call which created
the Plot.
The first argument (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 AST_GETGRFCONTEXT routine, 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"
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( GRFCON, ATT, VAL, OLDVAL, PRIM )
GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application.
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.
"
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.
INTEGER FUNCTION BBUF( GRFCON )
GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application.
"
Cap"
function is called to determine if the grf module has a given
capability, as indicated by the "
cap"
argument:
INTEGER FUNCTION CAP( GRFCON, CAP, VALUE )
GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application.
CAP = INTEGER (Given) The capability being inquired about. This will be one of the following constants defined in GRF_PAR:
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 = INTEGER (Given) 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.
"
EBuf"
function should end the current graphics buffering context. See the description of "
BBuf"
above for further details. It requires the following interface:
INTEGER FUNCTION EBUF( GRFCON )
GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application.
"
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( GRFCON )
GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application.
"
Line"
function displays lines joining the given positions and requires the
following interface:
INTEGER FUNCTION LINE( GRFCON, N, X, Y )
GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application.
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"
function displays
markers at the given positions. It requires the following interface:
INTEGER FUNCTION MARK( GRFCON, N, X, Y, TYPE )
GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application.
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.
"
Qch"
function returns the heights of characters drawn vertically and
horizontally in graphics coordinates. It requires the following interface:
INTEGER FUNCTION QCH( GRFCON, CHV, CHH )
GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application.
CHV = REAL (Returned) The height of characters drawn with a vertical baseline. This will be an increment in the X axis.
CHH = REAL (Returned) The height of characters drawn with a horizontal baseline. This will be an increment in the Y axis.
"
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:
INTEGER FUNCTION SCALES( GRFCON, ALPHA, BETA )
GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application.
ALPHA = REAL (Returned) The scale for the X axis (i.e. Xnorm = alpha∗Xworld).
BETA = REAL (Returned) The scale for the Y axis (i.e. Ynorm = beta∗Yworld).
"
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( GRFCON, TEXT, X, Y, JUST, UPX, UPY )
GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application.
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"
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( GRFCON, TEXT, X, Y, JUST, UPX, UPY, XB, YB )
GRFCON = INTEGER (Given) - A KeyMap containing information passed from the calling application.
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.