OpenScanDeviceLib
OpenScan Device Programming Interface
OpenScanDeviceLib.h
Go to the documentation of this file.
1 
7 #pragma once
8 
9 #include <stdbool.h>
10 #include <stdint.h>
11 #include <stdlib.h>
12 
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16 
52 
55 #define OScDevInternal_MAKE_VERSION(major, minor) \
56  (((uint32_t)(major) << 16) | (uint16_t)(minor))
57 
59 
93 #define OScDevInternal_ABI_VERSION OScDevInternal_MAKE_VERSION(13, 0)
94 
99 // Forward declarations for types defined later in this header
100 typedef struct OScDev_ModuleImpl OScDev_ModuleImpl;
101 typedef struct OScDev_DeviceImpl OScDev_DeviceImpl;
103 
105 #define OScDev_MAX_STR_SIZE 512
106 
108 #define OScDev_MAX_STR_LEN (OScDev_MAX_STR_SIZE - 1)
109 
110 // Declarations for opaque data types accessed through device interface
111 // functions.
112 typedef struct OScInternal_Device OScDev_Device;
113 typedef struct OScInternal_Setting OScDev_Setting;
114 typedef struct OScInternal_AcquisitionForDevice OScDev_Acquisition;
115 typedef struct RERR_Error OScDev_RichError;
116 #define OScDev_RichError_OK ((OScDev_RichError *)NULL)
117 
119 typedef int32_t OScDev_LogLevel;
120 
122 enum {
123  OScDev_LogLevel_Debug,
124  OScDev_LogLevel_Info,
125  OScDev_LogLevel_Warning,
126  OScDev_LogLevel_Error,
127 };
128 
129 typedef int32_t OScDev_ErrorCodeFormat;
130 enum {
137  32,
138 
141 };
142 
144 
149 typedef int32_t OScDev_Error;
150 enum {
151  OScDev_OK = 0,
152 
153  // WARNING: Do not edit these without correctly incrementing the device
154  // interface version.
155  OScDev_Error_Unknown = 10000,
156  OScDev_Error_Unsupported_Operation,
157  OScDev_Error_Illegal_Argument,
158  OScDev_Error_Device_Module_Already_Exists,
159  OScDev_Error_No_Such_Device_Module,
160  OScDev_Error_Driver_Not_Available,
161  OScDev_Error_Device_Already_Open,
162  OScDev_Error_Device_Not_Opened_For_LSM,
163  OScDev_Error_Device_Does_Not_Support_Clock,
164  OScDev_Error_Device_Does_Not_Support_Scanner,
165  OScDev_Error_Device_Does_Not_Support_Detector,
166  OScDev_Error_Wrong_Value_Type,
167  OScDev_Error_Setting_Not_Writable,
168  OScDev_Error_Wrong_Constraint_Type,
169  OScDev_Error_Unknown_Enum_Value_Name,
170  OScDev_Error_Acquisition_Running,
171  OScDev_Error_Not_Armed,
172  OScDev_Error_Waveform_Out_Of_Range,
173  OScDev_Error_Waveform_Memory_Size_Mismatch,
174  OScDev_Error_Data_Left_In_Fifo_After_Reading_Image,
175 };
176 
178 
188 #define OScDev_CHECK(err, call) ((err = (call)) != OScDev_OK)
189 
190 // Note: There is no OScDev_RETURN_IF_ERROR macro because it tends to
191 // encourage poor coding practices. Often, locally allocated resources need to
192 // be freed before returning with an error.
193 
194 typedef int32_t OScDev_TriggerSource;
195 enum {
196  OScDev_TriggerSource_Software,
197  OScDev_TriggerSource_External,
198 };
199 
200 typedef int32_t OScDev_ClockSource;
201 enum {
202  OScDev_ClockSource_Internal,
203  OScDev_ClockSource_External,
204 };
205 
206 typedef int32_t OScDev_ValueType;
207 enum {
208  OScDev_ValueType_String,
209  OScDev_ValueType_Bool,
210  OScDev_ValueType_Int32,
211  OScDev_ValueType_Float64,
212  OScDev_ValueType_Enum,
213 };
214 
215 typedef int32_t OScDev_ValueConstraint;
216 enum {
217  OScDev_ValueConstraint_None,
218  OScDev_ValueConstraint_DiscreteValues,
219  OScDev_ValueConstraint_Range,
220 };
221 
223 
237 typedef struct OScInternal_PtrArray OScDev_PtrArray;
238 
240 
252 typedef struct OScInternal_NumArray OScDev_NumArray;
253 
255 
262 typedef struct OScInternal_NumRange OScDev_NumRange;
263  // addtogroup dpi
265 
266 #ifndef OScDevInternal_BUILDING_OPENSCANLIB
267 
269 
272 
274 
278 
279 #endif
280 
282 
301 #define OScDev_MODULE_IMPL OScDev_ModuleImpl OScDevInternal_TheModuleImpl
302 
304 
309  // All functions take a pointer to the module implementation, even if not
310  // needed in the implementation, because it may help with debugging.
311 
312  void (*Log)(OScDev_ModuleImpl *modImpl, OScDev_Device *device,
313  OScDev_LogLevel level, const char *message);
314 
315  OScDev_RichError *(*Error_RegisterCodeDomain)(
316  OScDev_ModuleImpl *modImpl, const char *domainName,
317  OScDev_ErrorCodeFormat codeFormat);
318  OScDev_Error (*Error_ReturnAsCode)(OScDev_ModuleImpl *modImpl,
319  OScDev_RichError *error);
320  OScDev_RichError *(*Error_Create)(OScDev_ModuleImpl *modImpl,
321  const char *message);
322  OScDev_RichError *(*Error_CreateWithCode)(OScDev_ModuleImpl *modImpl,
323  const char *domainName,
324  OScDev_Error code,
325  const char *message);
326  OScDev_RichError *(*Error_Wrap)(OScDev_ModuleImpl *modImpl,
327  OScDev_RichError *cause,
328  const char *message);
329  OScDev_RichError *(*Error_WrapWithCode)(OScDev_ModuleImpl *modImpl,
330  OScDev_RichError *cause,
331  const char *domainName,
332  int32_t code, const char *message);
333 
334  const char *(*Error_GetMessage)(OScDev_ModuleImpl *modImpl,
335  OScDev_RichError *error);
336  const char *(*Error_GetDomain)(OScDev_ModuleImpl *modImpl,
337  OScDev_RichError *error);
338  int32_t (*Error_GetCode)(OScDev_ModuleImpl *modImpl,
339  OScDev_RichError *error);
340  OScDev_RichError *(*Error_GetCause)(OScDev_ModuleImpl *modImpl,
341  OScDev_RichError *error);
342  void (*Error_Format)(OScDev_ModuleImpl *modImpl, OScDev_RichError *error,
343  char *buffer, size_t bufsize);
344  void (*Error_FormatRecursive)(OScDev_ModuleImpl *modImpl,
345  OScDev_RichError *error, char *buffer,
346  size_t bufsize);
347  OScDev_RichError *(*Error_AsRichError)(OScDev_ModuleImpl *modImpl,
348  OScDev_Error code);
349  void (*Error_Destroy)(OScDev_ModuleImpl *modImpl, OScDev_RichError *error);
350 
351  OScDev_PtrArray *(*PtrArray_Create)(OScDev_ModuleImpl *modImpl);
352  OScDev_PtrArray *(*PtrArray_CreateFromNullTerminated)(
353  OScDev_ModuleImpl *modImpl, void *const *nullTerminatedArray);
354  void (*PtrArray_Destroy)(OScDev_ModuleImpl *modImpl,
355  const OScDev_PtrArray *arr);
356  void (*PtrArray_Append)(OScDev_ModuleImpl *modImpl, OScDev_PtrArray *arr,
357  void *obj);
358  size_t (*PtrArray_Size)(OScDev_ModuleImpl *modImpl,
359  const OScDev_PtrArray *arr);
360  bool (*PtrArray_Empty)(OScDev_ModuleImpl *modImpl,
361  const OScDev_PtrArray *arr);
362  void *(*PtrArray_At)(OScDev_ModuleImpl *modImpl,
363  const OScDev_PtrArray *arr, size_t index);
364 
365  OScDev_NumArray *(*NumArray_Create)(OScDev_ModuleImpl *modImpl);
366  OScDev_NumArray *(*NumArray_CreateFromNaNTerminated)(
367  OScDev_ModuleImpl *modImpl, const double *nanTerminatedArray);
368  void (*NumArray_Destroy)(OScDev_ModuleImpl *modImpl,
369  const OScDev_NumArray *arr);
370  void (*NumArray_Append)(OScDev_ModuleImpl *modImpl, OScDev_NumArray *arr,
371  double val);
372  size_t (*NumArray_Size)(OScDev_ModuleImpl *modImpl,
373  const OScDev_NumArray *arr);
374  bool (*NumArray_Empty)(OScDev_ModuleImpl *modImpl,
375  const OScDev_NumArray *arr);
376  double (*NumArray_At)(OScDev_ModuleImpl *modImpl,
377  const OScDev_NumArray *arr, size_t index);
378 
379  OScDev_NumRange *(*NumRange_CreateContinuous)(OScDev_ModuleImpl *modImpl,
380  double rMin, double rMax);
381  OScDev_NumRange *(*NumRange_CreateDiscrete)(OScDev_ModuleImpl *modImpl);
382  OScDev_NumRange *(*NumRange_CreateDiscreteFromNaNTerminated)(
383  OScDev_ModuleImpl *modImpl, const double *nanTerminatedArray);
384  void (*NumRange_Destroy)(OScDev_ModuleImpl *modImpl,
385  const OScDev_NumRange *range);
386  void (*NumRange_AppendDiscrete)(OScDev_ModuleImpl *modImpl,
387  OScDev_NumRange *range, double val);
388 
389  OScDev_Error (*Device_Create)(OScDev_ModuleImpl *modImpl,
390  OScDev_Device **device,
391  OScDev_DeviceImpl *impl, void *data);
392  void *(*Device_GetImplData)(OScDev_ModuleImpl *modImpl,
393  OScDev_Device *device);
394 
395  OScDev_Error (*Setting_Create)(OScDev_ModuleImpl *modImpl,
396  OScDev_Setting **setting, const char *name,
397  OScDev_ValueType valueType,
398  OScDev_SettingImpl *impl, void *data);
399  void (*Setting_Destroy)(OScDev_ModuleImpl *modImpl,
400  OScDev_Setting *setting);
401  void *(*Setting_GetImplData)(OScDev_ModuleImpl *modImpl,
402  OScDev_Setting *setting);
403 
404  // TODO These can return void
405  OScDev_Error (*Acquisition_IsClockRequested)(OScDev_ModuleImpl *modImpl,
406  OScDev_Acquisition *acq,
407  bool *isRequested);
408  OScDev_Error (*Acquisition_IsScannerRequested)(OScDev_ModuleImpl *modImpl,
409  OScDev_Acquisition *acq,
410  bool *isRequested);
411  OScDev_Error (*Acquisition_IsDetectorRequested)(OScDev_ModuleImpl *modImpl,
412  OScDev_Acquisition *acq,
413  bool *isRequested);
414  OScDev_Error (*Acquisition_GetClockStartTriggerSource)(
415  OScDev_ModuleImpl *modImpl, OScDev_Acquisition *acq,
416  OScDev_TriggerSource *startTrigger);
417  OScDev_Error (*Acquisition_GetClockSource)(OScDev_ModuleImpl *modImpl,
418  OScDev_Acquisition *acq,
419  OScDev_ClockSource *clock);
420 
421  uint32_t (*Acquisition_GetNumberOfFrames)(OScDev_ModuleImpl *modImpl,
422  OScDev_Acquisition *acq);
423  double (*Acquisition_GetPixelRate)(OScDev_ModuleImpl *modImpl,
424  OScDev_Acquisition *acq);
425  uint32_t (*Acquisition_GetResolution)(OScDev_ModuleImpl *modImpl,
426  OScDev_Acquisition *acq);
427  double (*Acquisition_GetZoomFactor)(OScDev_ModuleImpl *modImpl,
428  OScDev_Acquisition *acq);
429  void (*Acquisition_GetROI)(OScDev_ModuleImpl *modImpl,
430  OScDev_Acquisition *acq, uint32_t *xOffset,
431  uint32_t *yOffset, uint32_t *width,
432  uint32_t *height);
433 
434  bool (*Acquisition_CallFrameCallback)(OScDev_ModuleImpl *modImpl,
435  OScDev_Acquisition *acq,
436  uint32_t channel, void *pixels);
437 };
438 
440 
451 
460  const char *displayName;
461 
463  /*
464  * This flag determines how the device module reports errors.
465  * If false, the device module uses conventional integer error codes.
466  * If true, all errors generated by the device module should be rich
467  * errors, and they should be returned by converting to temporary integer
468  * codes via OScDev_Error_ReturnAsCode(). All new device modules should set
469  * this to true.
470  */
471  const bool supportsRichErrors;
472 
474 
480  OScDev_Error (*Open)(void);
481 
483 
489  OScDev_Error (*Close)(void);
490 
492 
505 };
506 
508  OScDev_Error (*GetModelName)(const char **name);
509 
511 
535 
537 
547  OScDev_Error (*ReleaseInstance)(OScDev_Device *device);
548 
549  OScDev_Error (*GetName)(OScDev_Device *device, char *name);
550 
552 
557  OScDev_Error (*Open)(OScDev_Device *device);
558 
559  OScDev_Error (*Close)(OScDev_Device *device);
560 
563 
572  OScDev_Error (*HasClock)(OScDev_Device *device, bool *hasClock);
573 
575  OScDev_Error (*HasScanner)(OScDev_Device *device, bool *hasScanner);
576 
578  OScDev_Error (*HasDetector)(OScDev_Device *device, bool *hasDetector);
579 
581  OScDev_Error (*MakeSettings)(OScDev_Device *device,
582  OScDev_PtrArray **settings);
583 
585 
593  OScDev_Error (*GetPixelRates)(OScDev_Device *device,
594  OScDev_NumRange **pixelRatesHz);
595 
597 
618  OScDev_Error (*GetActualPixelRate)(OScDev_Device *device,
619  double nominalRateHz,
620  double *actualRateHz);
621 
623 
632  OScDev_Error (*GetResolutions)(OScDev_Device *device,
633  OScDev_NumRange **resolutions);
634 
636 
645  OScDev_Error (*GetZoomFactors)(OScDev_Device *device,
646  OScDev_NumRange **zooms);
647 
649 
665  OScDev_Error (*IsROIScanSupported)(OScDev_Device *device, bool *supported);
666 
668 
678  OScDev_Error (*GetRasterWidths)(OScDev_Device *device,
679  OScDev_NumRange **widths);
680 
682 
692  OScDev_Error (*GetRasterHeights)(OScDev_Device *device,
693  OScDev_NumRange **heights);
694 
696 
702  OScDev_Error (*GetNumberOfChannels)(OScDev_Device *device,
703  uint32_t *nChannels);
704 
706 
711  OScDev_Error (*GetBytesPerSample)(OScDev_Device *device,
712  uint32_t *bytesPerSample);
713 
715 
754  OScDev_Error (*Arm)(OScDev_Device *device, OScDev_Acquisition *acq);
755 
757 
770  OScDev_Error (*Start)(OScDev_Device *device);
771 
773 
799  OScDev_Error (*Stop)(OScDev_Device *device);
800 
802 
814  OScDev_Error (*IsRunning)(OScDev_Device *device, bool *isRunning);
815 
817 
828  OScDev_Error (*Wait)(OScDev_Device *device);
829 };
830 
832  // TODO The value type should be moved inside the SettingImpl as a static
833  // data field. The type-dependent fields could be placed in a union:
834  // .valueType = OScDev_ValueType_Int32,
835  // .typeImpl.int32 = {
836  // .constraintType = OScDev_ValueConstraint_Range,
837  // .Get = myGetFunc,
838  // .Set = mySetFunc,
839  // .GetRange = myRangeFunc,
840  // }
841  // We can also provide static data fields for range and discrete values.
842 
843  OScDev_Error (*IsEnabled)(OScDev_Setting *setting, bool *enabled);
844  OScDev_Error (*IsWritable)(OScDev_Setting *setting, bool *writable);
845 
853  OScDev_Setting *setting, OScDev_ValueConstraint *constraintType);
854  OScDev_Error (*GetString)(OScDev_Setting *setting, char *value);
855  OScDev_Error (*SetString)(OScDev_Setting *setting, const char *value);
856  OScDev_Error (*GetBool)(OScDev_Setting *setting, bool *value);
857  OScDev_Error (*SetBool)(OScDev_Setting *setting, bool value);
858  OScDev_Error (*GetInt32)(OScDev_Setting *setting, int32_t *value);
859  OScDev_Error (*SetInt32)(OScDev_Setting *setting, int32_t value);
860 
869  OScDev_Error (*GetInt32Range)(OScDev_Setting *setting, int32_t *min,
870  int32_t *max);
871 
890  OScDev_Error (*GetInt32DiscreteValues)(OScDev_Setting *setting,
891  OScDev_NumArray **values);
892 
893  OScDev_Error (*GetFloat64)(OScDev_Setting *setting, double *value);
894  OScDev_Error (*SetFloat64)(OScDev_Setting *setting, double value);
895 
904  OScDev_Error (*GetFloat64Range)(OScDev_Setting *setting, double *min,
905  double *max);
906 
924  OScDev_Error (*GetFloat64DiscreteValues)(OScDev_Setting *setting,
925  OScDev_NumArray **values);
926  OScDev_Error (*GetEnum)(OScDev_Setting *setting, uint32_t *value);
927  OScDev_Error (*SetEnum)(OScDev_Setting *setting, uint32_t value);
928  OScDev_Error (*GetEnumNumValues)(OScDev_Setting *setting, uint32_t *count);
929  OScDev_Error (*GetEnumNameForValue)(OScDev_Setting *setting,
930  uint32_t value, char *name);
931  OScDev_Error (*GetEnumValueForName)(OScDev_Setting *setting,
932  uint32_t *value, const char *name);
933 
935  void (*Release)(OScDev_Setting *setting);
936 };
937 
938 #ifdef __cplusplus
939 } // extern "C"
940 #endif
941 
942 #ifndef OScDevInternal_BUILDING_OPENSCANLIB
943 
944 // Inline functions wrapping all entries in the OpenScanLib function table
945 //
946 // Use of this macro tricks Doxygen into documenting the functions even though
947 // they are static.
948 #define OScDev_API static inline
949 
955 OScDev_API void OScDev_Log(OScDev_Device *device, OScDev_LogLevel level,
956  const char *message) {
958  level, message);
959 }
960 
962 OScDev_API void OScDev_Log_Debug(OScDev_Device *device, const char *message) {
963  OScDev_Log(device, OScDev_LogLevel_Debug, message);
964 }
965 
967 OScDev_API void OScDev_Log_Info(OScDev_Device *device, const char *message) {
968  OScDev_Log(device, OScDev_LogLevel_Info, message);
969 }
970 
972 OScDev_API void OScDev_Log_Warning(OScDev_Device *device,
973  const char *message) {
974  OScDev_Log(device, OScDev_LogLevel_Warning, message);
975 }
976 
978 OScDev_API void OScDev_Log_Error(OScDev_Device *device, const char *message) {
979  OScDev_Log(device, OScDev_LogLevel_Error, message);
980 }
981 
982 OScDev_API OScDev_RichError *
983 OScDev_Error_RegisterCodeDomain(const char *domainName,
984  OScDev_ErrorCodeFormat codeFormat) {
985  return OScDevInternal_FunctionTable->Error_RegisterCodeDomain(
986  &OScDevInternal_TheModuleImpl, domainName, codeFormat);
987 }
988 
989 OScDev_API OScDev_Error OScDev_Error_ReturnAsCode(OScDev_RichError *error) {
990  return OScDevInternal_FunctionTable->Error_ReturnAsCode(
992 }
993 
994 OScDev_API OScDev_RichError *OScDev_Error_Create(const char *message) {
995  return OScDevInternal_FunctionTable->Error_Create(
996  &OScDevInternal_TheModuleImpl, message);
997 }
998 
999 OScDev_API OScDev_RichError *
1000 OScDev_Error_CreateWithCode(const char *domainName, int32_t code,
1001  const char *message) {
1002  return OScDevInternal_FunctionTable->Error_CreateWithCode(
1003  &OScDevInternal_TheModuleImpl, domainName, code, message);
1004 }
1005 
1006 OScDev_API OScDev_RichError *OScDev_Error_Wrap(OScDev_RichError *cause,
1007  const char *message) {
1008  return OScDevInternal_FunctionTable->Error_Wrap(
1009  &OScDevInternal_TheModuleImpl, cause, message);
1010 }
1011 
1012 OScDev_API OScDev_RichError *OScDev_Error_WrapWithCode(OScDev_RichError *cause,
1013  const char *domainName,
1014  int32_t code,
1015  const char *message) {
1016  return OScDevInternal_FunctionTable->Error_WrapWithCode(
1017  &OScDevInternal_TheModuleImpl, cause, domainName, code, message);
1018 }
1019 
1020 OScDev_API const char *OScDev_Error_GetMessage(OScDev_RichError *error) {
1021  return OScDevInternal_FunctionTable->Error_GetMessage(
1023 }
1024 
1025 OScDev_API const char *OScDev_Error_GetDomain(OScDev_RichError *error) {
1026  return OScDevInternal_FunctionTable->Error_GetDomain(
1028 }
1029 
1030 OScDev_API int32_t OScDev_Error_GetCode(OScDev_RichError *error) {
1031  return OScDevInternal_FunctionTable->Error_GetCode(
1033 }
1034 
1035 OScDev_API OScDev_RichError *OScDev_Error_GetCause(OScDev_RichError *error) {
1036  return OScDevInternal_FunctionTable->Error_GetCause(
1038 }
1039 
1040 OScDev_API void OScDev_Error_Format(OScDev_RichError *error, char *buffer,
1041  size_t bufsize) {
1043  error, buffer, bufsize);
1044 }
1045 
1046 OScDev_API void OScDev_Error_FormatRecursive(OScDev_RichError *error,
1047  char *buffer, size_t bufsize) {
1048  OScDevInternal_FunctionTable->Error_FormatRecursive(
1049  &OScDevInternal_TheModuleImpl, error, buffer, bufsize);
1050 }
1051 
1052 OScDev_API OScDev_RichError *OScDev_Error_AsRichError(OScDev_Error code) {
1053  return OScDevInternal_FunctionTable->Error_AsRichError(
1055 }
1056 
1057 OScDev_API void OScDev_Error_Destroy(OScDev_RichError *error) {
1059  error);
1060 }
1061 
1064  return OScDevInternal_FunctionTable->PtrArray_Create(
1066 }
1067 
1068 OScDev_API OScDev_PtrArray *
1069 OScDev_PtrArray_CreateFromNullTerminated(void *const *nullTerminatedArray) {
1070  return OScDevInternal_FunctionTable->PtrArray_CreateFromNullTerminated(
1071  &OScDevInternal_TheModuleImpl, nullTerminatedArray);
1072 }
1073 
1075 OScDev_API void OScDev_PtrArray_Destroy(const OScDev_PtrArray *arr) {
1076  OScDevInternal_FunctionTable->PtrArray_Destroy(
1078 }
1079 
1081 OScDev_API void OScDev_PtrArray_Append(OScDev_PtrArray *arr, void *obj) {
1082  OScDevInternal_FunctionTable->PtrArray_Append(
1083  &OScDevInternal_TheModuleImpl, arr, obj);
1084 }
1085 
1086 OScDev_API size_t OScDev_PtrArray_Size(const OScDev_PtrArray *arr) {
1087  return OScDevInternal_FunctionTable->PtrArray_Size(
1089 }
1090 
1091 OScDev_API bool OScDev_PtrArray_Empty(const OScDev_PtrArray *arr) {
1092  return OScDevInternal_FunctionTable->PtrArray_Empty(
1094 }
1095 
1096 OScDev_API void *OScDev_PtrArray_At(const OScDev_PtrArray *arr, size_t index) {
1097  return OScDevInternal_FunctionTable->PtrArray_At(
1098  &OScDevInternal_TheModuleImpl, arr, index);
1099 }
1100 
1103  return OScDevInternal_FunctionTable->NumArray_Create(
1105 }
1106 
1107 OScDev_API OScDev_NumArray *
1108 OScDev_NumArray_CreateFromNaNTerminated(const double *nanTerminatedArray) {
1109  return OScDevInternal_FunctionTable->NumArray_CreateFromNaNTerminated(
1110  &OScDevInternal_TheModuleImpl, nanTerminatedArray);
1111 }
1112 
1114 OScDev_API void OScDev_NumArray_Destroy(const OScDev_NumArray *arr) {
1115  OScDevInternal_FunctionTable->NumArray_Destroy(
1117 }
1118 
1120 OScDev_API void OScDev_NumArray_Append(OScDev_NumArray *arr, double val) {
1121  OScDevInternal_FunctionTable->NumArray_Append(
1122  &OScDevInternal_TheModuleImpl, arr, val);
1123 }
1124 
1125 OScDev_API size_t OScDev_NumArray_Size(const OScDev_NumArray *arr) {
1126  return OScDevInternal_FunctionTable->NumArray_Size(
1128 }
1129 
1130 OScDev_API bool OScDev_NumArray_Empty(const OScDev_NumArray *arr) {
1131  return OScDevInternal_FunctionTable->NumArray_Empty(
1133 }
1134 
1135 OScDev_API double OScDev_NumArray_At(const OScDev_NumArray *arr,
1136  size_t index) {
1137  return OScDevInternal_FunctionTable->NumArray_At(
1138  &OScDevInternal_TheModuleImpl, arr, index);
1139 }
1140 
1141 OScDev_API OScDev_NumRange *OScDev_NumRange_CreateContinuous(double rMin,
1142  double rMax) {
1143  return OScDevInternal_FunctionTable->NumRange_CreateContinuous(
1144  &OScDevInternal_TheModuleImpl, rMin, rMax);
1145 }
1146 
1147 OScDev_API OScDev_NumRange *OScDev_NumRange_CreateDiscrete(void) {
1148  return OScDevInternal_FunctionTable->NumRange_CreateDiscrete(
1150 }
1151 
1152 OScDev_API OScDev_NumRange *OScDev_NumRange_CreateDiscreteFromNaNTerminated(
1153  const double *nanTerminatedArray) {
1155  ->NumRange_CreateDiscreteFromNaNTerminated(
1156  &OScDevInternal_TheModuleImpl, nanTerminatedArray);
1157 }
1158 
1159 OScDev_API void OScDev_NumRange_Destroy(const OScDev_NumRange *range) {
1160  OScDevInternal_FunctionTable->NumRange_Destroy(
1162 }
1163 
1164 OScDev_API void OScDev_NumRange_AppendDiscrete(OScDev_NumRange *range,
1165  double value) {
1166  OScDevInternal_FunctionTable->NumRange_AppendDiscrete(
1167  &OScDevInternal_TheModuleImpl, range, value);
1168 }
1169 
1170 OScDev_API OScDev_Error OScDev_Device_Create(OScDev_Device **device,
1171  OScDev_DeviceImpl *impl,
1172  void *data) {
1173  return OScDevInternal_FunctionTable->Device_Create(
1174  &OScDevInternal_TheModuleImpl, device, impl, data);
1175 }
1176 
1177 OScDev_API void *OScDev_Device_GetImplData(OScDev_Device *device) {
1178  return OScDevInternal_FunctionTable->Device_GetImplData(
1179  &OScDevInternal_TheModuleImpl, device);
1180 }
1181 
1182 OScDev_API OScDev_Error OScDev_Setting_Create(OScDev_Setting **setting,
1183  const char *name,
1184  OScDev_ValueType valueType,
1185  OScDev_SettingImpl *impl,
1186  void *data) {
1187  return OScDevInternal_FunctionTable->Setting_Create(
1188  &OScDevInternal_TheModuleImpl, setting, name, valueType, impl, data);
1189 }
1190 
1191 OScDev_API void OScDev_Setting_Destroy(OScDev_Setting *setting) {
1192  OScDevInternal_FunctionTable->Setting_Destroy(
1193  &OScDevInternal_TheModuleImpl, setting);
1194 }
1195 
1196 OScDev_API void *OScDev_Setting_GetImplData(OScDev_Setting *setting) {
1197  return OScDevInternal_FunctionTable->Setting_GetImplData(
1198  &OScDevInternal_TheModuleImpl, setting);
1199 }
1200 
1204  OScDev_Acquisition *acq, bool *isRequested) {
1205  return OScDevInternal_FunctionTable->Acquisition_IsClockRequested(
1206  &OScDevInternal_TheModuleImpl, acq, isRequested);
1207 }
1208 
1212  OScDev_Acquisition *acq, bool *isRequested) {
1213  return OScDevInternal_FunctionTable->Acquisition_IsScannerRequested(
1214  &OScDevInternal_TheModuleImpl, acq, isRequested);
1215 }
1216 
1220  OScDev_Acquisition *acq, bool *isRequested) {
1221  return OScDevInternal_FunctionTable->Acquisition_IsDetectorRequested(
1222  &OScDevInternal_TheModuleImpl, acq, isRequested);
1223 }
1224 
1226 
1235  OScDev_Acquisition *acq, OScDev_TriggerSource *startTrigger) {
1237  ->Acquisition_GetClockStartTriggerSource(&OScDevInternal_TheModuleImpl,
1238  acq, startTrigger);
1239 }
1240 
1242 
1250  OScDev_Acquisition *acq, OScDev_ClockSource *clock) {
1251  return OScDevInternal_FunctionTable->Acquisition_GetClockSource(
1252  &OScDevInternal_TheModuleImpl, acq, clock);
1253 }
1254 
1256 OScDev_API uint32_t
1257 OScDev_Acquisition_GetNumberOfFrames(OScDev_Acquisition *acq) {
1258  return OScDevInternal_FunctionTable->Acquisition_GetNumberOfFrames(
1260 }
1261 
1262 OScDev_API double OScDev_Acquisition_GetPixelRate(OScDev_Acquisition *acq) {
1263  return OScDevInternal_FunctionTable->Acquisition_GetPixelRate(
1265 }
1266 
1267 OScDev_API uint32_t OScDev_Acquisition_GetResolution(OScDev_Acquisition *acq) {
1268  return OScDevInternal_FunctionTable->Acquisition_GetResolution(
1270 }
1271 
1272 OScDev_API double OScDev_Acquisition_GetZoomFactor(OScDev_Acquisition *acq) {
1273  return OScDevInternal_FunctionTable->Acquisition_GetZoomFactor(
1275 }
1276 
1277 OScDev_API void OScDev_Acquisition_GetROI(OScDev_Acquisition *acq,
1278  uint32_t *xOffset, uint32_t *yOffset,
1279  uint32_t *width, uint32_t *height) {
1280  OScDevInternal_FunctionTable->Acquisition_GetROI(
1281  &OScDevInternal_TheModuleImpl, acq, xOffset, yOffset, width, height);
1282 }
1283 
1285 
1296 OScDev_API bool OScDev_Acquisition_CallFrameCallback(OScDev_Acquisition *acq,
1297  uint32_t channel,
1298  void *pixels) {
1299  return OScDevInternal_FunctionTable->Acquisition_CallFrameCallback(
1300  &OScDevInternal_TheModuleImpl, acq, channel, pixels);
1301 }
1302 
1303 #undef OScDev_API
1304 
1305 #endif // OScDevInternal_BUILDING_OPENSCANLIB
1306  // addtogroup dpi
bool OScDev_Acquisition_CallFrameCallback(OScDev_Acquisition *acq, uint32_t channel, void *pixels)
Send acquired data for one channel of a frame.
OScDev_Error OScDev_Acquisition_IsDetectorRequested(OScDev_Acquisition *acq, bool *isRequested)
OScDev_PtrArray * OScDev_PtrArray_Create(void)
Create an array of objects.
OScDev_Error OScDev_Acquisition_GetClockSource(OScDev_Acquisition *acq, OScDev_ClockSource *clock)
Determine the scanner and detector clock source for the given acquisition.
void OScDev_PtrArray_Destroy(const OScDev_PtrArray *arr)
Destroy (free) an array of objects.
void OScDev_Log_Error(OScDev_Device *device, const char *message)
Log an error-level message.
OScDev_Error OScDev_Acquisition_GetClockStartTriggerSource(OScDev_Acquisition *acq, OScDev_TriggerSource *startTrigger)
Determine the start trigger source for the clock for the given acquisition.
void OScDev_Log_Info(OScDev_Device *device, const char *message)
Log an info-level message.
void OScDev_Log_Debug(OScDev_Device *device, const char *message)
Log a debug-level message.
void OScDev_Log_Warning(OScDev_Device *device, const char *message)
Log a warning-level message.
OScDev_NumArray * OScDev_NumArray_Create(void)
Create an array of numbers.
struct OScInternal_PtrArray OScDev_PtrArray
Dynamic or static array of pointers.
struct OScInternal_NumRange OScDev_NumRange
Continuous or discrete numerical range.
int32_t OScDev_Error
Error return value.
OScDev_Error OScDev_Acquisition_IsScannerRequested(OScDev_Acquisition *acq, bool *isRequested)
void OScDev_Log(OScDev_Device *device, OScDev_LogLevel level, const char *message)
Log a message.
int32_t OScDev_LogLevel
Log level.
uint32_t OScDev_Acquisition_GetNumberOfFrames(OScDev_Acquisition *acq)
Determine the requested number of frames for the given acquisition.
struct OScInternal_NumArray OScDev_NumArray
Dynamic or static array of numbers.
OScDev_Error OScDev_Acquisition_IsClockRequested(OScDev_Acquisition *acq, bool *isRequested)
void OScDev_NumArray_Destroy(const OScDev_NumArray *arr)
Destroy (free) an array of numbers.
void OScDev_NumArray_Append(OScDev_NumArray *arr, double val)
Append a value to an array.
void OScDev_PtrArray_Append(OScDev_PtrArray *arr, void *obj)
Append an object to an array.
@ OScDev_ErrorCodeFormat_U16
16-bit unsigned integer, decimal
@ OScDev_ErrorCodeFormat_I16
16-bit signed integer, decimal
@ OScDev_ErrorCodeFormat_HexNoPad
Modifier to remove leading zeros from hex formats.
@ OScDev_ErrorCodeFormat_Hex32
32-bit unsigned integer, hexadecimal
@ OScDev_ErrorCodeFormat_U32
32-bit unsigned integer, decimal
@ OScDev_ErrorCodeFormat_I32
32-bit signed integer, decimal
@ OScDev_ErrorCodeFormat_Hex16
16-bit unsigned integer, hexadecimal
struct OScDevInternal_Interface * OScDevInternal_FunctionTable
Pointer to the interface function table provided by OpenScanLib.
OScDev_ModuleImpl OScDevInternal_TheModuleImpl
Pointer to the module implementation provided by the device module.
Interface function table for module to call OpenScanLib.
OScDev_Error(* Start)(OScDev_Device *device)
Start the clock from software.
OScDev_Error(* HasDetector)(OScDev_Device *device, bool *hasDetector)
Return true if this device can perform detection.
OScDev_Error(* HasClock)(OScDev_Device *device, bool *hasClock)
OScDev_Error(* ReleaseInstance)(OScDev_Device *device)
Free the private data for a device.
OScDev_Error(* MakeSettings)(OScDev_Device *device, OScDev_PtrArray **settings)
Create the settings for a device.
OScDev_Error(* Arm)(OScDev_Device *device, OScDev_Acquisition *acq)
Prepare the clock, scanner, and/or detector for an acquisition.
OScDev_Error(* GetActualPixelRate)(OScDev_Device *device, double nominalRateHz, double *actualRateHz)
Return the actual pixel rate with best known accuracy.
OScDev_Error(* IsROIScanSupported)(OScDev_Device *device, bool *supported)
Return whether the scanner can perform subregion scans.
OScDev_Error(* GetRasterWidths)(OScDev_Device *device, OScDev_NumRange **widths)
Return the allowed widths of the raster ROI.
OScDev_Error(* GetNumberOfChannels)(OScDev_Device *device, uint32_t *nChannels)
Return the number of channels given current settings.
OScDev_Error(* GetResolutions)(OScDev_Device *device, OScDev_NumRange **resolutions)
Return the allowed scanner resolutions.
OScDev_Error(* GetRasterHeights)(OScDev_Device *device, OScDev_NumRange **heights)
Return the allowed heights of the raster ROI.
OScDev_Error(* HasScanner)(OScDev_Device *device, bool *hasScanner)
Return true if this device can perform scanning.
OScDev_Error(* IsRunning)(OScDev_Device *device, bool *isRunning)
Return true if this device is armed or running an acquisition.
OScDev_Error(* EnumerateInstances)(OScDev_PtrArray **devices)
Create instances for each physically available device.
OScDev_Error(* Open)(OScDev_Device *device)
Establish a connection to the device.
OScDev_Error(* GetPixelRates)(OScDev_Device *device, OScDev_NumRange **pixelRatesHz)
Return the allowed pixel rates.
OScDev_Error(* GetZoomFactors)(OScDev_Device *device, OScDev_NumRange **zooms)
Return the allowed zoom factors.
OScDev_Error(* GetBytesPerSample)(OScDev_Device *device, uint32_t *bytesPerSample)
Return the bytes per sample given current settings.
OScDev_Error(* Wait)(OScDev_Device *device)
Wait for any current acquisition to finish.
OScDev_Error(* Stop)(OScDev_Device *device)
Stop the current acquisition and disarm.
The module implementation function table.
OScDev_Error(* Open)(void)
Called before OpenScanLib accesses any other functions in this module.
OScDev_Error(* Close)(void)
Called after OpenScanLib has finished accessing this module.
const bool supportsRichErrors
Whether the device module supports RichErrors.
OScDev_Error(* GetDeviceImpls)(OScDev_PtrArray **deviceImpls)
Return the device implementations available in this module.
const char * displayName
Human-readable name of this module.
OScDev_Error(* GetFloat64Range)(OScDev_Setting *setting, double *min, double *max)
Get the range of an float64 setting with range constraint.
void(* Release)(OScDev_Setting *setting)
Free the private data associated with a setting, if any.
OScDev_Error(* GetFloat64DiscreteValues)(OScDev_Setting *setting, OScDev_NumArray **values)
Get the allowed values of an float64 setting with discrete values constraint.
OScDev_Error(* GetInt32Range)(OScDev_Setting *setting, int32_t *min, int32_t *max)
Get the range of an int32 setting with range constraint.
OScDev_Error(* GetNumericConstraintType)(OScDev_Setting *setting, OScDev_ValueConstraint *constraintType)
Get the type of value constraint of an int32 or float64 setting.
OScDev_Error(* GetInt32DiscreteValues)(OScDev_Setting *setting, OScDev_NumArray **values)
Get the allowed values of an int32 setting with discrete values constraint.