Register a graphics function for use by a Plot astGrfSet
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 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.
"
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"
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 )
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.
"
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 )
grfcon - 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:
int Cap( AstObject 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.
"
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 )
grfcon - 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:
int Flush( AstObject grfcon )
grfcon - A KeyMap containing information passed from the calling application.
"
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 )
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.
"
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 )
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.
"
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 )
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.
"
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 )
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 = alphaXworld).
beta - A pointer to the float which is to receive the scale for the Y axis (i.e. Ynorm = betaYworld).
"
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 )
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.
"
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 )
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.