Navigation:  DPLOTLIB Functions >

DPlot_AddData function

Print this Topic Previous pageReturn to chapter overviewNext page

int DPlot_AddData(int DocNum, int DataType, int NumPts, int Curve, float *array1, float *array2);

int DPlot_AddData8(int DocNum, int DataType, int NumPts, int Curve, double *array1, double *array2);

 

Parameters

DocNum

Document index for the document that you want to add data to. In general this value will have been returned by a previous call to DPlot_Plot or DPlot_Command with a FileNew command.

DataType

Must be DATA_XYXY (XY plot), DATA_3DR (contour plot of randomly-spaced 3D points), DATA_3DS (3D scatter plot), or DATA_1D (box-and-whisker plots and dot graphs). These constants are defined in the header files for the various demo programs.

NumPts

Number of data points to add.

Curve

1-based index of the curve (for DATA_XYXY), group (for DATA_1D), or data set (for DATA_3DS) that the new points are associated with. Ignored for DATA_3DR. To generate a new curve, group, or data set, set Curve to 0.

*array1

Address of the X array for DATA_XYXY. Not used for other graph types.

*array2

Address of the Y array for DATA_XYXY

 

X,Y,Z triplets (in the order x(0),y(0),z(0),x(1),y(1),z(1),... etc.) for DATA_3DR or DATA_3DS

 

X,Y,Z,amplitude values for DATA_4D or DATA_4DS

 

Y (amplitude) array for DATA_1D

Return Values

 1

Success

0

Generic error. For more specific error information use DPlot_SetErrorMode.

-1

Could not start DPlot or DPlot Jr.

-2

Could not initiate a DDE conversation with DPlot on the given document index.

-3

Unsupported DataType.

-4

Invalid DocNum

Remarks

This function, like DPlot_Command with [XY()], [XYXY()], or [XYZ()] commands, may be used in real-time applications.

For best results with real-time applications:

Use the ManualScale command to force the plot coordinates to the desired value. Otherwise, DPlot will continually adjust the plot coordinates to fit the incoming data. If the ManualScale command is issued DPlot keeps the extents of the X axis constant, shifting the plot window to the right when necessary.
Turn off antialiasing. Antialiased line segments take up to 10 times as long to draw as standard aliased line segments. You can turn off antialiasing in DPlot with DPlot_Command and [GeneralOptions(32,0)].
Do not use DPlot_SetErrorMethod(2) (display error messages in a MessageBox) in your release version, particularly with .NET programs. Doing so can easily lead to runaway MessageBox's when an error is encountered.

 

Notes for version 2.2.2.6 and later

New to version 2.2.2.6 and later versions of DPLOTLIB.DLL: As with most other DPLOTLIB functions, DPlot_AddData initializes the DDE management library (DDEML) and establishes a DDE conversation with DPlot. In previous versions DPlot_AddData terminated the conversation and "uninitialized" the DDEML on exit. In general this works fine on non-.NET apps on Windows XP and previous versions of Windows. But on Vista and with .NET apps on any version of Windows, the calls to DDEML functions take far too long and serve as bottlenecks, possibly resulting in "busy" messages. The problem was particularly severe on Vista. In version 2.2.2.6, the DDEML is initialized once and a DDE conversation is established, but not closed. This change removes the bottlenecks experienced with .NET apps and all DPLOTLIB programs on Windows Vista. However, it also forces the calling application to eventually close the DDE conversation. This is accomplished with a call to the new DPlot_Disconnect function. Failure to call DPlot_Disconnect when your program is done with DPlot_AddData will lead to consuming resources unnecessarily, and possibly to a failure to connect with DPlot in a later call.

If your real-time program produces data at a fairly fast rate (e.g. faster than 10 points per second and your program will be producing a plot with 10's of thousands of points or more, you should consider using the DeferMinMaxCheck command. By default, DPlot will recalculate minimum values, maximum values, means, and standard deviations after every call to DPlot_AddData. In a plot with many thousands of points this calculation is enough of a bottleneck that it might interfere with the next call to DPlot_AddData. The downside to using [DeferMinMaxCheck(1)] is that any text placeholders will not be updated until a [DeferMinMaxCheck(0)] command is sent.

 

 

 


Page url: http://www.dplot.com/lib/index.htm?dplot_adddata.htm