This chapter documents PHPlot internal functions. These functions are intended to be used only by PHPlot itself.
Starting with PHPlot-5.1.0, most of the internal functions are declared as
protected
, which limits their visibility to other member
functions and inherited or parent classes. Some internal functions are
still public
, usually because they are needed for
testing PHPlot. However, all functions documented in this chapter should be
treated as private, for use only by PHPlot. If you feel you have a need to
use one of these functions from outside PHPlot (or an inherited class),
please report this via the available PHPlot support mechanisms.
This non-member function was removed at PHPlot-5.0.4.
This non-member function was removed at PHPlot-5.0.4 and replaced with the class member function pad_array.
Calculates the X and Y axis positions in world coordinates. These can be supplied by the user, in which case they are only changed if they are outside the data range. If not supplied by the user, the Y axis is set to the minimum X value, so it appears on the left. If not supplied the the user, the X axis is set to Y=0 (Y=1 for log scale plots) if the Y data range includes 0, else to the minimum Y value. Note: This code was moved out of CalcTranslation at PHPlot-5.0.5. Called by DrawGraph.
Calculates the widths of the bars for 'bars' and 'stackedbars' plot types. It calculates the width of the bars and the margins around and between them. Called by DrawGraph before calling DrawBars or DrawStackedBars.
Calculates the size of the four margins around the plot area: x_left_margin, x_right_margin, y_top_margin, and y_bot_margin. It does this by trying to determine how much space is needed for titles, labels, and tick marks. Starting with PHPlot-5.0.5, this is only called by DrawGraph, and it also calculates position offsets for titles and labels. It is called even in case of a user-supplied plot area (SetPlotAreaPixels or SetMarginsPixels was used). If the $maximize argument is true, then the plot area does not leave room for X or Y axis, labels, or titles; this is used for pie charts.
Through PHPlot-5.0.6, all 4 margins are either user-defined or all 4 are automatically calculated. Starting with PHPlot-5.0.7, the 4 margins can be independently set or defaulted to automatic. CalcMargins calculates values for all 4 margins, but only saves those that have not been set using either SetMarginsPixels or SetPlotAreaPixels. Note that other than the overall plot title, elements are drawn relative to the plot area, which is calculated based on the actual margins. If the top margin is increased, for example, the plot title stays at the top of the image, but top tick marks and labels move down against the graph.
Calculates the size of the biggest X data label. It returns the height along the Y axis of the tallest data label. This is used to allocate space for margins. This was added to PHPlot-5.0.5. Called by CalcMargins.
Calculates the size of the biggest tick label. The $which argument is 'x' or 'y' to indicate which labels to work with. For 'x', it returns the height along the Y axis; for 'y' it returns the width along the X axis. This is used to allocate space for margins. This was added to PHPlot-5.0.5. Calls CalcTicks to determine the tick value parameters. Called by CalcMargins.
Calculates the pixel coordinates of the plot area. This was added to PHPlot-5.0.5 by moving the parts of the calculations out of SetPlotAreaPixels and SetMarginsPixels. Those two functions now simply record their arguments, and make no attempt to calculate any parameters. Called by DrawGraph, after CalcMargins is used to calculate margins.
Calculates the world coordinate limits of the plot area. This was added to PHPlot-5.0.5 by moving the calculations out of SetPlotAreaWorld. Called by DrawGraph, after FindDataLimits is used to examine the data array values.
Calculates the tick parameters. $which is 'x' or 'y'. Returns an array of 3 values: start, end, and interval. This was added to PHPlot-5.0.5, although it still uses the same method of just dividing the interval by 10 if there is no user-supplied interval or tick count. Called by CalcMaxTickLabelSize, DrawYTicks, and DrawXTicks.
Calculates the parameters for transforming world to pixel coordinates. This function calculates the scale (xscale, yscale) and origin (plot_origin_x, plot_origin_y) for X and Y translations, which are used by the xtr() and ytr() functions. Starting with PHPlot-5.0.5, this is only called by DrawGraph, as nothing else uses the parameters until the graph is ready to be drawn.
Used to validate the data_type for a plot_type. This works like a specialized version of CheckOption. $valid_types contains the valid data type(s) for the current plot_type, separated by a comma and space if more than one is supported. If the current data_type is in the list, returns TRUE, else produces an error. This was added in PHPlot-5.1.2 to unify the way the plot drawing functions check the data type.
Fixes up the data and tick label position, angle, and format settings. This applies defaults to X data label and tick label positions but avoids having them overlap unless the user deliberately positioned them that way. Also sets the default angle for X data labels, and the default formatting for X and Y data labels, to match the corresponding settings for tick labels if they were not already set. This is for compatibility with PHPlot-5.0.7 and earlier, when there was only one control for both types of labels. Called by DrawGraph before calculating margins with CalcMargins. This was added in PHPlot-5.1.0.
Checks the validity of an option passed to a PHPlot member function. $which_opt is the string to check, and $which_acc is a string of acceptable choices (with a comma and then a space between each choice). If the string to check is not found in the string of acceptable choices, a fatal error will be reported using DrawError. The error message will include $which_func which should be the name of the calling function (using the PHP __FUNCTION__ magic constant). Note that this is used to catch programming errors, not run-time or user errors. If the string to check is acceptable, it is returned down-cased and trimmed of leading and trailing spaces. Note: At PHPlot-5.0.5, this function was changed to require exactly ', ' (comma space) between acceptable choices, and reject empty strings for $which_opt and disallow partial matches.
Checks the validity of an option argument passed to a PHPlot member function that can accept its argument as either a string or an array of strings. $opt is the string or array to check, and $acc is a string of acceptable choices (with a comma and then a space between each choice). If the $opt argument is supplied as a string, it is first converted to an array with one element. Then the elements of the array are each checked for validity. If any element of the array of strings to check is not found in the string of acceptable choices, a fatal error will be reported using DrawError. The error message will include $func which should be the name of the calling function (using the PHP __FUNCTION__ magic constant). Note that this is used to catch programming errors, not run-time or user errors. If all of the array elements to check are acceptable, the array is returned with each element down-cased and trimmed of leading and trailing spaces. Note that an array is always returned, even if the opt argument is a string. This was added in PHPlot-5.1.2.
Adjusts the point_shapes and point_sizes arrays so they have the same size, and stores the size in a class variable. This handles processing deferred from SetPointShapes and SetPointSizes until graph drawing time. It must be called from internal functions that produce plots that use point shapes: currently DrawDots and DrawDotsError. This was added in PHPlot-5.1.0.
Call a callback (hook) function. $reason is the name given to the callback, for example 'draw_titles' (meaning: call after drawing titles). The reasons are array indexes in the $callbacks class variable. Following that are zero or more arguments to pass to the callback, after the image resource and passthrough arguments. DoCallback does nothing if there is no callback registered for the given reason, otherwise it calls the callback function. See Chapter 6, Callbacks for more information on callbacks.
Draws an area plot, or a stacked area plot (if the optional argument is True). Called by DrawGraph when the plot type is 'area' or 'stackedarea'. Stacked area plots were added in PHPlot-5.1.1; through PHPlot-5.1.0 this function did not have a parameter and was used only for area plots.
Draws the image background, either an image file or solid fill or nothing. Called by DrawGraph.
Draws a bar chart plot. Called by DrawGraph when the plot type is 'bars'.
Draws a data label for a point. This is separate from the X data labels, and is currently only available for bar charts. Called by DrawBars if enabled with SetYDataLabelPos.
Draws a single marker point ('dot') at the given X and Y world coordinates, using the given color. The $record parameter selects the marker shape and size using the arrays set up with SetPointSizes() and SetPointShapes(); they are not passed as arguments themselves. Called by those plotting routines that include dots: DrawDotsError and DrawDots.
Draws a dot plot. Called by DrawGraph when the plot type is either 'linepoints' or 'points', and the data type does not select error bars (is not 'data-data-error').
Draws a dot plot with error bars. Called by DrawGraph when the plot type is either 'linepoints' or 'points', and the data type is 'data-data-error'.
Starting with PHPlot-5.0.5, this function is an alias for PrintError and is retained for compatibility. The $where_x and $where_arguments are now ignored. (Previously they positioned the error message on the image, but were never used.)
(Through PHPlot-5.0.4, DrawError wrote the error message to an image, wrote the image, and exited.)
Draws a border around the image, if enabled by SetImageBorderType. Called by DrawGraph.
Draws the plot legend. This includes the box, text labels, and color boxes. Called by DrawGraph, but only if legend text has been set using SetLegend.
Draws a line plot. Called by DrawGraph when the plot type is 'lines' or 'linepoints', and the data type does not select error bars (is not 'data-data-error').
Draws a lines plot with error bars. Called by DrawGraph when the plot type is either 'linepoints' or 'lines', and the data type is 'data-data-error'.
Draws a pie chart plot. Called by DrawGraph with the plot type is 'pie'.
Draws the plot area background, either an image file set with SetPlotAreaBgImage, or else a solid fill color selected by SetPlotBgColor if enabled with SetDrawPlotAreaBackground or else nothing. Called by DrawGraph.
Draws the border around the plot area. This draws zero to four lines around the plot area (depending on SetPlotBorderType). It only draws the outline; other functions draw the tick marks and labels for the X axis and Y axis. Called by DrawGraph.
Draws a squared (stepped lines) plot. Called by DrawGraph when the plot type is 'squared'.
Draws a stacked bars chart plot. Called by DrawGraph when the plot type is 'stackedbars'.
Draws a string of text $which_text, at position ($which_xpos, $which_ypos). The font is selected with $which_font, which is one of the font arrays in the object. The text is drawn at angle $which_angle (built-in fonts can be used at 0 and 90 degrees only, TrueType at any angle). $which_color is a GD color index for the image. Text alignment relative to the (x,y) point is controlled with $which_halign ('center', 'left', or 'right') and $which_valign ('center', 'bottom', 'top'). Multi-line text strings are supported. This function accounts for the limitations and differences in GD text drawing routines for built-in and TrueType fonts. Called by numerous functions which place text on the plot.
Starting with PHPlot-5.0.5, this function just calls ProcessText in text drawing mode. DrawText should be used by all internal PHPlot code that needs to draw text, and ProcessText should only be used by DrawText and SizeText.
There are 7 font array variables in the PHPlot object. Through PHPlot-5.0.5, these were separate variables: generic_font, title_font, legend_font, x_label_font, y_label_font, x_title_font, and y_title_font. Starting with PHPlot-5.0.6, these were combined into a single class array variable 'fonts', indexed by the element name, for example $fonts['generic'].
Starting with PHPlot-5.1.0, $which_font can be NULL or an empty string to use the 'generic' font. This was intended to allow callbacks to avoid having to reference the internal class array variable which stores font information.
Draws a thin bar lines plot. This is sometimes called an impulse plot. Called by DrawGraph when the plot type is 'thinbarline'.
Draws the main plot title as set with SetTitle. This is centered at the very top of the image. Called by DrawGraph.
Draws the X (horizontal) axis, including the axis line, tick marks and labels, and also draws the vertical grid lines. All of these except the axis line are done in DrawXTicks. Called by DrawGraph.
Draws a data label for an X value. The labels are above or below the plot area or both, depending on the value set with SetXDataLabelPos. This also calls DrawXDataLine to draw a line from the label to the point, if enabled. Called by plot drawing routines for all plot types except 'pie': DrawArea, DrawBars, DrawDots, DrawDotsError, DrawThinBarLines, DrawLines, DrawLinesError, DrawSquared, and DrawStackedBars.
Draws X data lines, which are vertical lines from the bottom or top of the plot to the data points. This is enabled with SetDrawXDataLabelLines. The lines are drawn from the position (above, below, or both) of the X data labels, which are set with SetXDataLabelPos. Called by DrawXDataLabel.
Draws a single X value tick mark and its label. These can appear on the bottom of the graph, top of the graph, along the X axis (even if it is in the middle somewhere), on both sides, or nowhere, as set with SetXTickPos and SetXTickLabelPos. Called by DrawXTicks. This was added at PHPlot-5.0.5 by splitting the code out of DrawXTicks, for symmetry with DrawYTicks.
Draws the vertical grid lines, the tick marks, and tick labels. Calls CalcTicks to calculate the tick parameters. Calls DrawXTick to draw each tick mark and its label. Called by DrawXAxis.
Draws the X axis title. There can be zero, one, or two of them depending on the position parameter specified in SetXTitle. Calls DrawText to actually draw the title(s). Called by DrawGraph.
Draws the Y (vertical) axis, including the axis line, tick marks and labels, and also draws the horizontal grid lines. All of these except the axis line are done in DrawYTicks. Called by DrawGraph.
Draws an error bar for the point at world coordinates ($x_world, $y_world). $error_height is the height (in world coordinates) of the error bar: positive for the upper range error, negative for the lower range error. The $error_bar_type is set to 'tee' or 'line' by SetErrorBarShape. Called by DrawDotsError and DrawLinesError, twice for each point on the plot (upper range error and lower range error).
Draws a single Y value tick mark and its label. These can appear on the left of the graph, right of the graph, along the Y axis (even if it is in the middle somewhere), on both sides, or nowhere, as set with SetYTickPos and SetYTickLabelPos. Called by DrawYTicks.
Draws the horizontal grid lines, the tick marks, and tick labels. Calls DrawYTick to draw each tick mark and its label. Called by DrawYAxis.
Draws the Y axis title. There can be zero, one, or two of them depending on the position parameter specified in SetYTitle. Calls DrawText to actually draw the title(s). Called by DrawGraph.
Finds the limits of the data. Using the data_type and the data array, it goes through the points and determines the minimum and maximum X and Y values. It stores the min and max Y values for each row (plot line) in the class arrays data_min and data_max. (Before PHPlot-5.0.4, these were stored back into the data array with special index values MINY (-1) and MAXY (-2).) It also stores the overall min and max X and Y values as min_x, max_x, min_y, and max_y. It also stores the length of the longest data label in max_t. Starting with PHPlot-5.0.5, this is only called once by DrawGraph. (In PHPlot-5.0.4 and earlier, this was called from various places, with a flag data_limits_done to indicate it was called.)
Formats a value for use as a tick or data label. This implements the format type selected with SetXLabelType ,SetYLabelType, SetXDataLabelType ,and SetYDataLabelType. By default it returns the value as-is, or it can format it as a floating point number or date/time value. Called by several functions that need to format label values. Separation of data and tick label formatting was available starting with PHPlot-5.1.0.
Reads an image file from $image_filename, stores the width and height (in pixels) in the $width and $height reference arguments, and returns a PHP GD image resource of the image. This is used by SetInputFile and tile_img. Errors go to PrintError; there is no way for the script to recover. Possible errors include an image file type which is unsupported by PHP GD, or a corrupt image file. Note: This was added at PHPlot-5.0.4, by moving common code from the two calling functions.
This returns the image border width, as set with SetImageBorderWidth or as defaulted. It is used by CalcMargins to account for image border width, and by DrawImageBorder when drawing the image border. This was added in PHPlot-5.1.2.
Given a font array variable, returns the proper spacing in pixels between lines of text using that font. This works for both GD and TrueType fonts. See also SetLineSpacing. Used by ProcessTextGD, ProcessTextTTF, and DrawLegend. Note: This was added at PHPlot-5.0.6, with support for mixing TTF and GD fonts.
Formats a floating point number, like PHP's number_format(), inserting a decimal separator and thousands groups separators. Unlike the PHP function, this uses variables in the PHPlot class to select the separators. The separators can be set with SetNumberFormat, or by default PHPlot will attempt to get locale-specific values. For example, 1234+(56/100) will be returned as "1,234.56" if the locale is "en_US", and as "1.234,56" if the locale is "de_DE". As a fall-back, if locale information is not available, '.' is used for decimal point, and ',' for thousands separator. This fall-back is equivalent to the behavior in PHPlot 5.0rc3 and earlier. This is used by FormatLabel when the formatting type is 'data', and also for the pie chart labels in DrawPieChart.
Pads an array $arr with copies of itself until it reaches the given size. If $arr is a scalar, it will first be converted to an array with one element. Then, if $arr has fewer than $size elements, elements of $arr starting from the first will be appended until it reaches $size elements. This only works on zero-based sequential integer indexed arrays. Called by PadArrays, SetPointShapes, and SetPointSizes. This replaced array_pad_array at PHPlot-5.0.4, however that had an unused 3rd argument, and worked on general indexed arrays.
Pads the style arrays (line_widths, line_styles, data_colors, etc.) so they are all large enough to contain an entry for each data set or plot line. This uses pad_array. Called by DrawGraph before drawing anything.
Handles a fatal error within PHPlot. Starting with PHPlot-5.0.5 this and DrawError are identical. PrintError attempts to draw the error message $error_message into the image, and then output the image. This method is used because PHPlot is normally expected to output an image, and text output would not be displayed properly. (If no image resource was available, and the SetIsInline flag is not on, PHPlot will send a 500 Internal Server Error header.) After this, PrintError uses the PHP trigger_error() function to signal a user error. This is normally fatal to the script, unless caught. This will also result in the error message written to the error output stream, which typically ends up in a web server error log.
(Through PHPlot-5.0.4, PrintError wrote an error message to standard output and exited.)
This function acts as a bridge, or switch, between the two functions SizeText and DrawText, which handle both GD and TTF text, and the functions which specifically handle GD text or TTF text. The arguments to this function are the same as DrawText except for an additional first argument $draw_it. If $draw_it is true, text is drawn. This is used by DrawText. If $draw_it is false, only the bounding box size of the text is calculated and returned. This is used by SizeText. In text sizing mode, the x, y, color, halign, and valign arguments are ignored, as they are not needed when calculating the text bounding box size. This function is only called by SizeText and DrawText, and calls either ProcessTextTTF or ProcessTextGD.
Draws GD fixed-font text, or calculates the size of GD fixed-font text. This is only called by ProcessText after it determines that GD text is in use. If $draw_it is true, text is drawn; if $draw_it is false, only the bounding box size of the text is calculated and returned as a two-element array ($width, $height). Here $width is measured along the X axis, and $height along Y, regardless of the text angle. These are the size of an orthogonal bounding box that contains the text block. The $font argument is a PHPlot font array, which must reference a GD font. The $angle is 0 or 90 degrees, as GD text only supports those values. $x, $y are the reference point of the text $text, which is drawn in color $color. The text string can contain multiple lines, with a newline character between lines. The $h_factor and $v_factor arguments are translated from the alignment arguments supplied to DrawText or SizeText: 0, 0.5, or 1.0 If $draw_it is false, for text sizing mode, the x, y, color, h_factor and v_factor arguments are ignored.
Note: This was added at PHPlot-5.0.5. It was changed at PHPlot-5.0.6 to take a single font array argument, rather than 3 separate arguments for font number, width, and height.
Draws TTF text, or calculates the size of TTF text. This is only called by ProcessText after it determines that TTF text is in use. If $draw_it is true, text is drawn; if $draw_it is false, only the bounding box size of the text is calculated and returned as a two-element array ($width, $height). Here $width is measured along the X axis, and $height along Y, regardless of the text angle. These are the size of an orthogonal bounding box that contains the text block. The $font argument is a PHPlot font array, which must reference a TTF font. The text is drawn at $angle degrees; unlike GD text TTF text can be drawn at any angle. $x, $y are the reference point of the text $text, which is drawn in color $color. The text string can contain multiple lines, with a newline character between lines. The $h_factor and $v_factor arguments are translated from the alignment arguments supplied to DrawText or SizeText: 0, 0.5, or 1.0 If $draw_it is false, for text sizing mode, the x, y, color, h_factor and v_factor arguments are ignored.
Note that the interpretation of the alignment for text at arbitrary angles may not be what you expect. Rotation of text happens before alignment, and alignment and positioning use the orthogonal bounding box of the text.
Note: This was added at PHPlot-5.0.5. It was changed in PHPlot-5.0.6 to take a single font array argument, rather than 2 separate arguments for font filename and size.
Sets the GD line style to select a dashed line, in preparation for drawing a dashed line. To understand how this works, it helps to look at the documentation for the PHP GD function ImageSetStyle() and also refer to SetDefaultDashedStyle. GD expects a line style to be specified as an array of pixel values, which is awkward to deal with. PHPlot uses a shorthand notation with integer values indicating pairs of the number of color, then transparent pixels. SetDefaultDashedStyle creates a string of PHP code to generate an array of pixel values the way GD wants them, but defers filling in the exact color to use. SetDashedStyle evaluates this string with $which_ndx_color set to the color to use for the current line. The result is an array of pixel values for GD's ImageSetStyle. Called by DrawXTicks and DrawYTicks if a dashed grid is selected, as well as other line drawing functions such as DrawLines if dashed lines are used.
Selects all the default font values and sizes. See SetFont for details of the font element names and default values. Called by PHPlot, the class constructor, to initialize fonts in the plot object, and by SetUseTTF to restore the defaults when changing from or to TrueType font usage.
Initializes default colors and styles for PHPlot objects. Mostly this calls the public member functions such as SetDataColors but without specifying an array of colors, which causes the member functions to select default values. Called by PHPlot, the class constructor, to initialize the plot object.
Given a color specification (see SetRGBColor), and a default alpha value, returns a color index to be used in GD drawing functions. The color is the exact color requested if it already exists in the image, or if can be allocated. For palette images, if the color map is full, no new colors can be allocated, and this function will return an index to the closest existing color. For truecolor images, this function always returns an index for the exact requested color. The default alpha parameter was added in PHPlot-5.1.1.
Given a color specification (see SetRGBColor), and a default alpha value, returns an index for a slightly darker color to be used in GD drawing functions. The method used is to subtract 48 from each red, green, and blue component (without letting any go negative). The alpha component is not adjusted. This is used for shadow colors (for example, in bar charts and pie charts). The same method as in SetIndexColor is used to select a color index. The default alpha parameter was added in PHPlot-5.1.1.
Sets an image file $which_input_file to be used as the background image for the graph. Also resets the graph size to the size of the image file. This is used by the constructor, PHPlot. Note: In earlier releases, this was considered an externally available function. After a PHPlot object was created with the constructor, SetInputFile could be used to resize it and set the background image. Although this still works, it is deprecated. SetInputFile should be considered an internal-use-only function. Users should set the background image file using the 4th argument of PHPlot when creating an instance of the object.
Sets the formatting used for tick and data labels. This implements
SetXLabelType, SetYLabelType,
SetXDataLabelType ,and SetYDataLabelType.
$mode is either 'x', 'xd', 'y', or 'yd' and selects the axis to configure
and type of label being drawn (x, y for tick labels; xd, yd for data labels).
$args is an array of arguments, with $args[0] selecting the type of
formatting (for example, 'data'). Additional array elements depend on
the formatting type. For more details, see the above-referenced functions.
All arguments to those functions are combined into an array and passed to
SetLabelType
as $args.
Separation of data and tick label formatting was available starting with
PHPlot-5.1.0.
Converts a general color specification into a standard form as an array of 4 components: red, green, blue, and alpha, and returns the array. The 3 color components are integers in the range 0-255, and the alpha component is an integer in the range 0-127 (where 0 means opaque). The acceptable color specification forms are documented in Section 3.5.1, “Color Parameter Forms” and Section 3.6.4, “Color Parameter Form Extensions”, and include color names, component arrays, and strings of the form #RRGGBB and #RRGGBBAA. The alpha argument provides a default value if the color specification does not include alpha; the default 0 makes the color opaque. This is used directly by SetIndexColor and SetIndexDarkColor, and indirectly by all functions that accept a color specification. Use of alpha in the color specification, the default alpha argument, and the 4th component in the returned array were added in PHPlot-5.1.1.
Calculates the size of a block of text. It works on both GD (fixed-font) and TTF text. $which_font is a PHPlot font array, $which_angle is the text angle in degrees, and $which_text is the text string. The text string can contain multiple lines, with a newline character between lines. This function just calls ProcessText in text sizing mode to do the work. It returns a two-element array with the text width and height. These are the width and height of an orthogonal bounding box (box aligned with the X and Y axes) which contains the rotated text block. Called by functions which need to determine text size for laying out plot elements, such as CalcMargins. This function replaced TTFBBoxSize at PHPlot-5.0.5.
Tiles an image file over another the current plot image. $file is the filename of the image to use as the tile. ($xorig, $yorig) are the origin point for the tiling, and ($width, $height) are the area to be tiled. These are used to tile just under the plot area versus the entire image. The $mode can be 'centeredtile', 'tile', or 'scale'. Scale mode scales the source image to fit the target area. Tile and centeredtile modes repeat the source image as needed to fit into the target area; the difference is that centeredtile offsets the tile start position by half its size, which works better for some tiles. Called by DrawBackground and DrawPlotAreaBackground if an image file is selected for the plot area or overall background.
This function was removed at PHPlot-5.0.5. It was replaced by SizeText.
Translates an X world coordinate value into a pixel coordinate value. This uses the scale and translation set up by CalcTranslation. See GetDeviceXY for a public interface.
Translates a Y world coordinate value into a pixel coordinate value. This uses the scale and translation set up by CalcTranslation. See GetDeviceXY for a public interface.