Data Structures
struct	OScDev_ModuleImpl
	The module implementation function table. More...

Macros
#define	OScDev_CHECK(err, call) ((err = (call)) != OScDev_OK)
	Convenience macro for checking error return values. More...

#define	OScDev_MAX_STR_LEN (OScDev_MAX_STR_SIZE - 1)
	Maximum length for strings copied to provided buffer.

#define	OScDev_MAX_STR_SIZE 512
	Buffer size for fixed-length strings.

#define	OScDev_MODULE_IMPL OScDev_ModuleImpl OScDevInternal_TheModuleImpl
	Define the device module implementation. More...

#define	OScDev_RichError_OK ((OScDev_RichError *)NULL)

Typedefs
typedef struct OScInternal_AcquisitionForDevice	OScDev_Acquisition

typedef int32_t	OScDev_ClockSource

typedef struct OScInternal_Device	OScDev_Device

typedef struct OScDev_DeviceImpl	OScDev_DeviceImpl

typedef int32_t	OScDev_Error
	Error return value. More...

typedef int32_t	OScDev_ErrorCodeFormat

typedef int32_t	OScDev_LogLevel
	Log level.

typedef struct OScDev_ModuleImpl	OScDev_ModuleImpl

typedef struct OScInternal_NumArray	OScDev_NumArray
	Dynamic or static array of numbers. More...

typedef struct OScInternal_NumRange	OScDev_NumRange
	Continuous or discrete numerical range. More...

typedef struct OScInternal_PtrArray	OScDev_PtrArray
	Dynamic or static array of pointers. More...

typedef struct RERR_Error	OScDev_RichError

typedef struct OScInternal_Setting	OScDev_Setting

typedef struct OScDev_SettingImpl	OScDev_SettingImpl

typedef int32_t	OScDev_TriggerSource

typedef int32_t	OScDev_ValueConstraint

typedef int32_t	OScDev_ValueType

Enumerations
enum	{ OScDev_LogLevel_Debug , OScDev_LogLevel_Info , OScDev_LogLevel_Warning , OScDev_LogLevel_Error }
	Constants for OScDev_LogLevel.

enum	{ OScDev_ErrorCodeFormat_I32 = 1 , OScDev_ErrorCodeFormat_U32 = 2 , OScDev_ErrorCodeFormat_Hex32 = 4 , OScDev_ErrorCodeFormat_I16 = 8 , OScDev_ErrorCodeFormat_U16 = 16 , OScDev_ErrorCodeFormat_Hex16 , OScDev_ErrorCodeFormat_HexNoPad = 1 << 31 }

enum	{ OScDev_OK = 0 , OScDev_Error_Unknown = 10000 , OScDev_Error_Unsupported_Operation , OScDev_Error_Illegal_Argument , OScDev_Error_Device_Module_Already_Exists , OScDev_Error_No_Such_Device_Module , OScDev_Error_Driver_Not_Available , OScDev_Error_Device_Already_Open , OScDev_Error_Device_Not_Opened_For_LSM , OScDev_Error_Device_Does_Not_Support_Clock , OScDev_Error_Device_Does_Not_Support_Scanner , OScDev_Error_Device_Does_Not_Support_Detector , OScDev_Error_Wrong_Value_Type , OScDev_Error_Setting_Not_Writable , OScDev_Error_Wrong_Constraint_Type , OScDev_Error_Unknown_Enum_Value_Name , OScDev_Error_Acquisition_Running , OScDev_Error_Not_Armed , OScDev_Error_Waveform_Out_Of_Range , OScDev_Error_Waveform_Memory_Size_Mismatch , OScDev_Error_Data_Left_In_Fifo_After_Reading_Image }

enum	{ OScDev_TriggerSource_Software , OScDev_TriggerSource_External }

enum	{ OScDev_ClockSource_Internal , OScDev_ClockSource_External }

enum	{ OScDev_ValueType_String , OScDev_ValueType_Bool , OScDev_ValueType_Int32 , OScDev_ValueType_Float64 , OScDev_ValueType_Enum }

enum	{ OScDev_ValueConstraint_None , OScDev_ValueConstraint_DiscreteValues , OScDev_ValueConstraint_Range }

Functions
bool	OScDev_Acquisition_CallFrameCallback (OScDev_Acquisition acq, uint32_t channel, void pixels)
	Send acquired data for one channel of a frame. More...

OScDev_Error	OScDev_Acquisition_GetClockSource (OScDev_Acquisition acq, OScDev_ClockSource clock)
	Determine the scanner and detector clock source for the given acquisition. More...

OScDev_Error	OScDev_Acquisition_GetClockStartTriggerSource (OScDev_Acquisition acq, OScDev_TriggerSource startTrigger)
	Determine the start trigger source for the clock for the given acquisition. More...

uint32_t	OScDev_Acquisition_GetNumberOfFrames (OScDev_Acquisition *acq)
	Determine the requested number of frames for the given acquisition.

double	OScDev_Acquisition_GetPixelRate (OScDev_Acquisition *acq)

uint32_t	OScDev_Acquisition_GetResolution (OScDev_Acquisition *acq)

void	OScDev_Acquisition_GetROI (OScDev_Acquisition acq, uint32_t xOffset, uint32_t yOffset, uint32_t width, uint32_t *height)

double	OScDev_Acquisition_GetZoomFactor (OScDev_Acquisition *acq)

OScDev_Error	OScDev_Acquisition_IsClockRequested (OScDev_Acquisition acq, bool isRequested)

OScDev_Error	OScDev_Acquisition_IsDetectorRequested (OScDev_Acquisition acq, bool isRequested)

OScDev_Error	OScDev_Acquisition_IsScannerRequested (OScDev_Acquisition acq, bool isRequested)

OScDev_Error	OScDev_Device_Create (OScDev_Device *device, OScDev_DeviceImpl impl, void *data)

void *	OScDev_Device_GetImplData (OScDev_Device *device)

OScDev_RichError *	OScDev_Error_AsRichError (OScDev_Error code)

OScDev_RichError *	OScDev_Error_Create (const char *message)

OScDev_RichError *	OScDev_Error_CreateWithCode (const char domainName, int32_t code, const char message)

void	OScDev_Error_Destroy (OScDev_RichError *error)

void	OScDev_Error_Format (OScDev_RichError error, char buffer, size_t bufsize)

void	OScDev_Error_FormatRecursive (OScDev_RichError error, char buffer, size_t bufsize)

OScDev_RichError *	OScDev_Error_GetCause (OScDev_RichError *error)

int32_t	OScDev_Error_GetCode (OScDev_RichError *error)

const char *	OScDev_Error_GetDomain (OScDev_RichError *error)

const char *	OScDev_Error_GetMessage (OScDev_RichError *error)

OScDev_RichError *	OScDev_Error_RegisterCodeDomain (const char *domainName, OScDev_ErrorCodeFormat codeFormat)

OScDev_Error	OScDev_Error_ReturnAsCode (OScDev_RichError *error)

OScDev_RichError *	OScDev_Error_Wrap (OScDev_RichError cause, const char message)

OScDev_RichError *	OScDev_Error_WrapWithCode (OScDev_RichError cause, const char domainName, int32_t code, const char *message)

void	OScDev_Log (OScDev_Device device, OScDev_LogLevel level, const char message)
	Log a message.

void	OScDev_Log_Debug (OScDev_Device device, const char message)
	Log a debug-level message.

void	OScDev_Log_Error (OScDev_Device device, const char message)
	Log an error-level message.

void	OScDev_Log_Info (OScDev_Device device, const char message)
	Log an info-level message.

void	OScDev_Log_Warning (OScDev_Device device, const char message)
	Log a warning-level message.

void	OScDev_NumArray_Append (OScDev_NumArray *arr, double val)
	Append a value to an array.

double	OScDev_NumArray_At (const OScDev_NumArray *arr, size_t index)

OScDev_NumArray *	OScDev_NumArray_Create (void)
	Create an array of numbers.

OScDev_NumArray *	OScDev_NumArray_CreateFromNaNTerminated (const double *nanTerminatedArray)

void	OScDev_NumArray_Destroy (const OScDev_NumArray *arr)
	Destroy (free) an array of numbers.

bool	OScDev_NumArray_Empty (const OScDev_NumArray *arr)

size_t	OScDev_NumArray_Size (const OScDev_NumArray *arr)

void	OScDev_NumRange_AppendDiscrete (OScDev_NumRange *range, double value)

OScDev_NumRange *	OScDev_NumRange_CreateContinuous (double rMin, double rMax)

OScDev_NumRange *	OScDev_NumRange_CreateDiscrete (void)

OScDev_NumRange *	OScDev_NumRange_CreateDiscreteFromNaNTerminated (const double *nanTerminatedArray)

void	OScDev_NumRange_Destroy (const OScDev_NumRange *range)

void	OScDev_PtrArray_Append (OScDev_PtrArray arr, void obj)
	Append an object to an array.

void *	OScDev_PtrArray_At (const OScDev_PtrArray *arr, size_t index)

OScDev_PtrArray *	OScDev_PtrArray_Create (void)
	Create an array of objects.

OScDev_PtrArray *	OScDev_PtrArray_CreateFromNullTerminated (void const nullTerminatedArray)

void	OScDev_PtrArray_Destroy (const OScDev_PtrArray *arr)
	Destroy (free) an array of objects.

bool	OScDev_PtrArray_Empty (const OScDev_PtrArray *arr)

size_t	OScDev_PtrArray_Size (const OScDev_PtrArray *arr)

OScDev_Error	OScDev_Setting_Create (OScDev_Setting *setting, const char name, OScDev_ValueType valueType, OScDev_SettingImpl impl, void data)

void	OScDev_Setting_Destroy (OScDev_Setting *setting)

void *	OScDev_Setting_GetImplData (OScDev_Setting *setting)

Detailed Description

OpenScanDeviceLib is a static library to which every OpenScan device module must link, and contains the mechanism that allows devices to call functions in OpenScanLib, as well as the mechanism by which OpenScanLib accesses the device module.

To create a new device module, use the macro OScDev_MODULE_IMPL to provide all required data and implementation functions.

Macro Definition Documentation

◆ OScDev_CHECK

#define OScDev_CHECK	(	err,
		call
	)	((err = (call)) != OScDev_OK)

Convenience macro for checking error return values.

For example,

OScDev_Error err;
if (OScDev_CHECK(err, OScDev_Device_Create(...)))
{
    // clean up
    return err;
}

Definition at line 188 of file OpenScanDeviceLib.h.

◆ OScDev_MODULE_IMPL

#define OScDev_MODULE_IMPL OScDev_ModuleImpl OScDevInternal_TheModuleImpl

Define the device module implementation.

Each device module must use this macro exactly once, in an implementation file (i.e. not in a header), to define the module implementation.

For example,

OScDev_MODULE_IMPL =
{
    .displayName = "MyDevice",
    .Open = MyDeviceOpen,
    .Close = MyDeviceClose,
    // ...
};

Within the braces, all required fields (and any desired optional fields) of OScDev_ModuleImpl must be initialized.

See also: OScDev_ModuleImpl

Definition at line 301 of file OpenScanDeviceLib.h.

Typedef Documentation

◆ OScDev_Error

typedef int32_t OScDev_Error

Error return value.

Zero (OScDev_OK) indicates success.

This will be replaced with an opaque type in the future.

Definition at line 149 of file OpenScanDeviceLib.h.

◆ OScDev_PtrArray

typedef struct OScInternal_PtrArray OScDev_PtrArray

Dynamic or static array of pointers.

This data type is used to pass lists of objects from device modules to OpenScanLib.

Whether the pointers contained in the array are "owned" (in the resource-management sense) by the array depends on the usage context; make sure to check the documentation of the function accepting or returning the array.

An array can be created dynamically by calling OScDev_PtrArray_Create().

(Because this type is intended solely for passing short lists, the only available operation is appending elements.)

Definition at line 215 of file OpenScanDeviceLib.h.

◆ OScDev_NumArray

typedef struct OScInternal_NumArray OScDev_NumArray

Dynamic or static array of numbers.

This data type is used to pass lists of numbers from device modules to OpenScanLib.

Although it holds double values, we use it for integer lists, too, for simplicity.

An array can be created dynamically by calling OScDev_NumArray_Create().

(Because this type is intended solely for passing short lists, the only available operation is appending elements.)

Definition at line 215 of file OpenScanDeviceLib.h.

◆ OScDev_NumRange

typedef struct OScInternal_NumRange OScDev_NumRange

Continuous or discrete numerical range.

This data type is used to mass numerical ranges from device modules to OpenScanLib.

A range can be created dynamically by calling OScDev_NumRange_CreateContinuous() or OScDev_NumRange_CreateDiscrete().

Definition at line 215 of file OpenScanDeviceLib.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
OScDev_ErrorCodeFormat_I32	32-bit signed integer, decimal
OScDev_ErrorCodeFormat_U32	32-bit unsigned integer, decimal
OScDev_ErrorCodeFormat_Hex32	32-bit unsigned integer, hexadecimal
OScDev_ErrorCodeFormat_I16	16-bit signed integer, decimal
OScDev_ErrorCodeFormat_U16	16-bit unsigned integer, decimal
OScDev_ErrorCodeFormat_Hex16	16-bit unsigned integer, hexadecimal
OScDev_ErrorCodeFormat_HexNoPad	Modifier to remove leading zeros from hex formats.

Definition at line 130 of file OpenScanDeviceLib.h.

Function Documentation

◆ OScDev_Acquisition_IsClockRequested()

OScDev_Error OScDev_Acquisition_IsClockRequested	(	OScDev_Acquisition *	acq,
		bool *	isRequested
	)

Determine whether this device should provide the clock for the given acquisition.

Definition at line 1203 of file OpenScanDeviceLib.h.

◆ OScDev_Acquisition_IsScannerRequested()

OScDev_Error OScDev_Acquisition_IsScannerRequested	(	OScDev_Acquisition *	acq,
		bool *	isRequested
	)

Determine whether this device should perform scanning for the given acquisition.

Definition at line 1211 of file OpenScanDeviceLib.h.

◆ OScDev_Acquisition_IsDetectorRequested()

OScDev_Error OScDev_Acquisition_IsDetectorRequested	(	OScDev_Acquisition *	acq,
		bool *	isRequested
	)

Determine whether this device should perform detection for the given acquisition.

Definition at line 1219 of file OpenScanDeviceLib.h.

◆ OScDev_Acquisition_GetClockStartTriggerSource()

OScDev_Error OScDev_Acquisition_GetClockStartTriggerSource	(	OScDev_Acquisition *	acq,
		OScDev_TriggerSource *	startTrigger
	)

Determine the start trigger source for the clock for the given acquisition.

This function is only useful when the clock is requested for the acquisition (see OScDev_Acquisition_IsClockRequested()).

Parameters

[in]	acq	the acquisition
[out]	startTrigger	the clock start trigger; either software or external

Definition at line 1234 of file OpenScanDeviceLib.h.

◆ OScDev_Acquisition_GetClockSource()

OScDev_Error OScDev_Acquisition_GetClockSource	(	OScDev_Acquisition *	acq,
		OScDev_ClockSource *	clock
	)

Determine the scanner and detector clock source for the given acquisition.

This function is only useful when the scanner and/or detector is requested for the acquisition (see OScDev_Acquisition_IsScannerRequested() and OScDev_Acquisition_IsDetectorRequested()).

Todo:: This is redundant with OScDev_Acquisition_IsClockRequested(). Remove.

Definition at line 1249 of file OpenScanDeviceLib.h.

◆ OScDev_Acquisition_CallFrameCallback()

bool OScDev_Acquisition_CallFrameCallback	(	OScDev_Acquisition *	acq,
		uint32_t	channel,
		void *	pixels
	)

Send acquired data for one channel of a frame.

This function must be called during an acquisition by the device that owns the detector for the acquisition.

The data pointed to by pixels must not change during the call to this function.

Parameters

[in]	acq	the acquisition that was given when arming this device
[in]	channel	the channel index
[in]	pixels	the raw pixel data for the channel

Definition at line 1296 of file OpenScanDeviceLib.h.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ OScDev_CHECK

◆ OScDev_MODULE_IMPL

Typedef Documentation

◆ OScDev_Error

◆ OScDev_PtrArray

◆ OScDev_NumArray

◆ OScDev_NumRange

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ OScDev_Acquisition_IsClockRequested()

◆ OScDev_Acquisition_IsScannerRequested()

◆ OScDev_Acquisition_IsDetectorRequested()

◆ OScDev_Acquisition_GetClockStartTriggerSource()

◆ OScDev_Acquisition_GetClockSource()

◆ OScDev_Acquisition_CallFrameCallback()