(Engine-Level Function)
| Description: | Displays a plot of a subsection of a buffer in a particular area of the window after converting the buffer to element values. Extends Plot. |
| Returns: | Nothing |
Usage:  |
Steady State only. |
| Function Groups: | Graphics, String and Buffer |
| Related to: | Plot | PlotXY |
| Format: |
PlotBuff(Buffer, Offset, N, Type, Low, High, X1, Y1, X2, Y2, Style, Color, Pattern, Background) ...OR... PlotBuff(Buffer, Offset, N, Type, Low, High, X1, Y1, X2, Y2, Pen, Brush [, XORMode, Direction, DrawStepped, BitNumber, Average]) |
| Parameters: |
| Buffer | ||||||||||
| Required. Any text expression that contains data to be plotted. | ||||||||||
| Offset | ||||||||||
| Required. Any numeric expression that gives the starting buffer position in data elements (not bytes or characters) of the first data element. | ||||||||||
| N | ||||||||||
| Required. Any numeric expression giving the number of elements to plot starting at the element given by the offset parameter. N must be greater than or equal to 2, and no greater than 32000. If this parameter is greater than the length of the buffer, the number of points plotted will be the number of points available in the buffer. If the end of the buffer is encountered before N points have been plotted, plotting continues with the first point in the buffer (offset 0). |
||||||||||
| Type | ||||||||||
Required. Any numeric expression giving the type of data held in the buffer. The types are described in the following table:
|
| Low |
| Required. Any numeric expression that defines the limit of data values to be plotted. This value need not be less than High but must not be equal to it. In the standard case, when this value is less than High, it will define the minimum value to display. For example, if Low was 10, a data value of 10 would fall on the edge of the bounding box, on either X1, if the plot is vertical, or on Y1, if the plot is horizontal. Any values below 10 in this case would not be shown - they would be outside the clipped box. |
| High |
| Required. Any numeric expression that defines the limit of data values to be plotted. This value need not be greater than Low but must not be equal to it. In the standard case, when this value is greater than Low, it will define the maximum value to display. For example, if High was 1000, a data value of 1000 would fall on the edge of the bounding box, on either X2, if the plot is vertical, or on Y2, if the plot is horizontal. Any values above 1000 in this case would not be shown - they would be outside the clipped box. |
| X1 |
| Required. Any numeric expression giving the X coordinate on the screen of one side of the plot area. This is typically, although not necessarily, the left side of the plot. For horizontal plots, this is the screen coordinate of the first point or bar plotted. For vertical plots, this is the value which corresponds to the Low parameter value. For vertical bar plots, X1 is the base coordinate for the bars. |
| Y1 |
| Required. Any numeric expression giving the Y coordinate on the screen of one side of the plot area. This is typically, although not necessarily, the bottom of the plot. For vertical plots, this is the screen coordinate of the first point or bar plotted. For horizontal plots, this is the value which corresponds to the Low parameter value. For horizontal bar plots, Y1 is the base coordinate for the bars. |
| X2 |
| Required. Any numeric expression giving the X coordinate on the screen of the side of the plot area opposite to X1. This is typically, although not necessarily, the right side of the plot. For horizontal plots, this is the screen coordinate of the last point or bar plotted. For vertical plots, this is the value which corresponds to the High parameter value. |
| Y2 |
| Required. Any numeric expression giving the Y coordinate on the screen of the side of the plot area opposite to Y1. This is typically, although not necessarily, the top of the plot. For vertical plots, this is the screen coordinate of the last point or bar plotted. For horizontal plots, this is the value which corresponds to the High parameter value. |
| Style |
| Required. Any numeric expression giving the style of the plot - the line style, direction, bit number for bits plots, and the number of points to average per point displayed. If PlotBuff senses that the Style parameter is a Pen, the Destructive, XORMode, DrawStepped, BitNumber, and Average parameters will become relevant. The Style is determined by adding together the following values. Line style + Direction + Path + Bit number + Average Line style is a number between 1 and 5 inclusive, giving the line style for line plots. A line style of 1 indicates a solid line. For bar plots, the line style portion of the Style parameter is ignored. Direction is either 0 or 10, where 0 is a horizontal plot and 10 is a vertical plot. Path is either 0 or 50. A 0 indicates that line plots are to be drawn directly from point to point. A 50 indicates that plots are to be drawn in a step fashion with two line segments between each point. The first segment runs parallel to the X-axis, the second, parallel to the Y-axis. This produces a square-looking plot. These step plots are useful for plotting status values which change in jumps rather than continuously. The Path value is ignored for bar plots. Bit number is the number of the bit to use in the data for plotting. If the normal entire value of the data is to be plotted, use 0 for this value. If only one of the bits from the data is to be plotted, use the bit number plus 1. The value to add is (Bit number + 1) * 100 or 0. The ability to plot only a single bit from short or long values allows status data to be stored very efficiently by not requiring a separate buffer for each status value. For bit plots, the value plotted is always a 0 or a 1 corresponding to the value of the selected bit. This plotting option is usually done in conjunction with a Path value of 50 for step plots. Average is the number of consecutive points to average to give a single point on the screen. It can be used to plot a very large number of values on the screen without having to draw all of the points on the screen. This will produce a smoothed plot and reduce the drawing time. The number to add is (Data points per displayed point - 1) * 10000. |
| Color |
| Required. Any numeric expression giving the VTScada Color Palette of the line and the foreground color for filled plots. If the number is less than 10000, the plot is non-destructive. If the number is greater than or equal to 10000, the plot is destructive and the actual color used is Color - 10000. |
| Pattern |
| Required. Any numeric expression giving the bar Fill Patterns for the plot. For a Pattern value of 0, the plot is a line plot. For Pattern values in the range of 1 to 25 inclusive, the plot is a bar plot with the hatch pattern corresponding to the Pattern parameter value. If the parameter is 1, the bars are a solid color and the Background parameter is ignored. |
| Background |
| Required. Any numeric expression giving the color number of the plot fill background color. This number is ignored if the Pattern parameter is equal to 1. For values of Pattern greater than 2, it gives the background color for the bar. |
| Pen |
| Required. The pen to be used (if any). |
| Brush |
| The brush to be used (if any). |
| XORMode |
| An optional parameter specifying whether the plot is destructive (if destructive, the plot line won't be affected by the background color). If set to 0 or Invalid (default), the destructive drawing mode will be used. If set to 1, the non-destructive or XOR drawing mode will be used. |
| Direction |
| An optional parameter specifying the horizontal or vertical direction for the plot. 0 or Invalid indicates horizontal, while 1 indicates vertical. |
| DrawStepped |
| An optional parameter specifying whether the plot is to be drawn from point-to-point, or stepped. 0 or Invalid indicates point-to-point, while 1 indicates stepped. |
| BitNumber |
| An optional parameter specifying the use of a whole value or a bit number. Invalid indicates a whole value should be used, while >=0 indicates that the specified bit number should be used. |
| Average |
| An optional parameter specifying whether consecutive points should be averaged to give a single point. Invalid or 0 indicates that averaging should not be used, while >0 indicates that the number of consecutive points should be averaged to give a single point. |
| Comments: | This function is a layered graphics statement. This statement will execute timer functions during the plotting process, allowing time critical functions such as driver I/O and data logging to continue running during the relatively long times it takes to update a plot on the screen. Through the ordering of Low, High, X1, X2, Y1, and Y2, there are 8 different orientations possible for line plots and 16 for bar plots. The normal left to right plot with minimum at the bottom will have Low < High, X1 < X2, and Y1 < Y2. By exchanging Low and High (i.e. Low > High), the plot will have minimum at the top with bars drawn from the bottom. Exchanging X1 and X2 (i.e. X1 > X2) will plot values from right to left. Exchanging Y1 and Y2 (i.e. Y1 > Y2) will plot values with minimum at the top and bars drawn from the top also. Combining these actions with the Style (horizontal or vertical) gives all possible plot orientations. If the number of points extends past the end of the buffer, the plot will continue at the first of the buffer until N points or all the points of the buffer have been plotted. The plot area defined by X1, Y1, X2, and Y2 limits the area which can be plotted on the screen. Any points which fall outside this area will not appear on the screen but will be "clipped" at the boundary. The PlotBuff statement works the same as the Plot statement. However, invalid values cannot exist in the buffer. The RAM memory savings of using buffers rather than arrays is in the range of 45% to 73%. |
Example:
{ Create the buffer and store the data in it }
If ! Valid(data);
[
data = MakeBuff(5, 0);
SetByte(data, 0, 1);
SetByte(data, 1, 9);
SetByte(data, 2, 0);
SetByte(data, 3, 6);
SetByte(data, 4, 10);
]
PlotBuff(data { Buffer name },
0, 10 { Start at first point and plot 10 points },
0 { Data in the range of 0-255; a single byte },
0, 10 { Low and high limits },
100, 500, 600, 100 { Bounding box for clipped area },
0 { Horizontal plot },
12 { Light red },
6 { Bar plot with vertical line pattern },
4 { Dark red background for pattern });
This plots a bar graph of 5 points in an area centered in the window. The bars will be vertical (points run along the horizontal), with light red vertical line pattern on dark red background.
