-
Notifications
You must be signed in to change notification settings - Fork 9
/
plugins_api.h
165 lines (129 loc) · 6.98 KB
/
plugins_api.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
#ifndef PLUGINS_API_H
#define PLUGINS_API_H
#include <stdint.h>
//============== Jag plugins api description ===================================
//
// Custom shared libraries should provide 2 functions:
//
// #ifdef __cplusplus
// extern "C" {
// #endif
//
// int jag_data_source_match(const wchar_t *file_name);
// struct jag_data_source_api* jag_load_data_source(const wchar_t *file_name);
//
// #ifdef __cplusplus
// }
// #endif
//
//
//
// jag_data_source_match - function determines if this shared library can process and
// load file "file_name" (on failure 0 is returned, on success - nonzero).
//
// jag_load_data_source - loads data from "file_name" data source and returns pointer
// to the jag_data_source_api object (see description below).
//
//==================================================================================
#define JAG_PARAM_DESCR_SIZE 128
#define JAG_PARAM_NAME_SIZE 64
#define JAG_PARAM_UNITS_SIZE 64
#define JAG_MATCH_FUNCTION_NAME "jag_data_source_match"
#define JAG_LOAD_FUNCTION_NAME "jag_load_data_source"
#ifdef __cplusplus
extern "C" {
#endif
struct jag_data_source_api;
struct jag_param_description
{
wchar_t description[JAG_PARAM_NAME_SIZE];
wchar_t name[JAG_PARAM_NAME_SIZE];
wchar_t units[JAG_PARAM_UNITS_SIZE];
uint32_t dimension; // if parameter is scalar than dimension = 1,
// if parameter is a vector than dimension is a size of this vector,
// if parameter is 2D, 3D ... vector you should linearize it and
// represent as 1D vector.
};
struct jag_data_source_api
{
// p_impl - pointer to the implementation specific data
void *p_impl;
// get_number_of_parameters - returns number of parameters written in the data source
uint32_t (*get_number_of_parameters)(const struct jag_data_source_api *data_source);
// get_parameter_description - returns description of the parameter with "primary_index" index
// primary_index is in range [0; result of "get_number_of_parameters" - 1].
void (*get_parameter_description)(const struct jag_data_source_api *data_source,
uint32_t primary_index,
struct jag_param_description *description);
// get_parameter_size - returns number of data points in "secondary_index"
// coordinate of the parameter with "primary_index" index (if this parameter
// has only one dimension than "secondary_index" should be ignored). For non scalar
// parameters secondary_index is in range [0, "dimension in jag_param_description structure" - 1].
uint64_t (*get_parameter_size)(const struct jag_data_source_api *data_source,
uint32_t primary_index,
uint32_t secondary_index);
// get_parameter - returns data for the "secondary_index"
// coordinate of the parameter with "primary_index" index (if this parameter
// has only one dimension than secondary_index should be ignored).
uint64_t (*get_parameter)(const struct jag_data_source_api *data_source,
uint32_t primary_index,
uint32_t secondary_index,
double *x_data,
double *y_data,
size_t data_sz);
// get_data_source_name - returns name of the data source from which this jag_data_source_api
// was loaded
const wchar_t* (*get_data_source_name)(const struct jag_data_source_api *data_source);
// loading_progress - returns loading progress. Before loading progress == 0.
// When loading of all data is finished progress == 100. Jag will not invoke
// get_parameter function if progress != 100.
int (*loading_progress)(const struct jag_data_source_api *data_source);
// is_valid - returns true if all data were loaded successfully, if errors during
// loading were detected false is returned
int (*is_valid)(const struct jag_data_source_api *data_source);
// delete_data_source - this function should release all resources allocated for loaded data
void (*delete_data_source)(struct jag_data_source_api *data_source);
};
#ifdef __cplusplus
}
#endif
// NOTE: get_number_of_parameters, get_parameter_description can be invoked before loading_progress == 100.
// Also get_number_of_parameters or get_parameter_description can be invoked simultaneously with loading_progress
// from different threads. So, if you need synchronization, you should ensure it. If at the moment of invocation
// of these functions number of parameters or their descriptions are not known, execution of these functions should be blocked
// and wait until this information will be read from the data source and only then correct result should be returned.
//
// get_parameter_size, get_data_source_name, is_valid, delete_data_source - will be invoked by jag only if loading_progress == 100.
// NOTE: Jag designed in assumption that all parameters in the data source,
// are represented as functions of some argument (this parameter can be time or something like that):
// Yni = fn(xi) (thats why pointer to the function "get_parameter" in jag_data_source_api
// structure returns 2 data vectors x_data and y_data). For 2 different parameters parameter1 and parameter1
// these arguments can be different, so "get_parameter" can return different "x_data" for parameters with
// different primary_index. Also, keep in mind that data in x_data should be in ascending order. Adjacent points in x_data can be equal.
//
// EXAMPLE: Suppose you wrote a plugin to load "*.csv" files and you have a file:
//
// some_data.csv:
//
// time, parameter1, parameter2
// 0, 10, 20
// 100, 20, 21
// 200, 30, 31
// 300, 40, 21
// 400, 50, 20
//
// Then for example your plugin can be implemented so that:
// get_number_of_parameters - returns 2 (for parameter1, parameter2, each parameter has dimension = 1) (parameter1 and parameter2 are considered
// as functions of argument time)
// get_parameter_size - returns 5 (because each parameter has 5 points to show on the plot)
// get_parameter - returns for parameter1(primary_index = 0) x_data = {0, 100, 200, 300, 400}, y_data = {10, 20, 30, 40, 50},
// for parameter1(primary_index = 1) x_data = {0, 100, 200, 300, 400}, y_data = {20, 21, 31, 21, 20},
//
// Also you can write another implementation. For example:
// get_number_of_parameters - returns 2 (for time, parameter1, parameter2, each parameter has dimension = 1) (parameter1, parameter2, time are considered
// as functions of argument number of line in the origin data source file)
// get_parameter_size - returns 5 (because each parameter has 5 points to show on the plot)
// get_parameter - returns for time (primary_index = 0) x_data = {1, 2, 3, 4, 5}, y_data = {0, 100, 200, 300, 400},
// for parameter1(primary_index = 1) x_data = {1, 2, 3, 4, 5}, y_data = {10, 20, 30, 40, 50},
// for parameter1(primary_index = 2) x_data = {1, 2, 3, 4, 5}, y_data = {20, 21, 31, 21, 20},
#endif // PLUGINS_API_H