Commit 75523af4 authored by Rossa, Lutz's avatar Rossa, Lutz
Browse files

XenethCamera version from Nov 19th 2020

parent e98cc468
///
/// @file XCamera.h
/// @brief This file contains the camera interface definitions.
///
/// @note This header file is documented using the Doxygen documentation framework.
/// On Windows systems refer to the xeneth-sdk.chm file found in the Help-folder
/// which is located in the SDK installation directory (Default: \%ProgramFiles\%\\Xeneth\\Sdk)
/// For Linux systems refer to /usr/share/doc/xeneth-major-minor-subminor/index.html.
///
#ifndef _XENICS_XCAMERA_GEN2_H_
# define _XENICS_XCAMERA_GEN2_H_
#ifdef _WIN32
# ifndef CALLCV
# define CALLCV __stdcall ///< Compatibility with VB6
# define CALLCVCB __cdecl
# else
# pragma message ("Warning: building using custom calling convention.")
# endif
# ifdef _USRDLL
# define IMPEXP __declspec(dllexport) ///< Attributes for C++ exports
# define IMPEXPC __declspec(dllexport) CALLCV ///< Attributes for C exports
# else
# define IMPEXP __declspec(dllimport) ///< Attributes for C++ exports
# define IMPEXPC __declspec(dllimport) CALLCV ///< Attributes for C exports
# endif
#else
# define CALLCV
# define CALLCVCB
# define IMPEXP
# define IMPEXPC
#endif
#ifdef __cplusplus
extern "C" {
#endif
///
/// @brief These are the error codes used throughout the API.
/// To get a string representation of the error code at runtime make sure to check the XC_ErrorToString() function.
///
typedef enum
{
I_OK = 0, ///< Success.
I_DIRTY = 1, ///< Internal.
E_BUG = 10000, ///< Generic.
E_NOINIT = 10001, ///< Camera was not successfully initialised.
E_LOGICLOADFAILED = 10002, ///< Invalid logic file.
E_INTERFACE_ERROR = 10003, ///< Command interface failure.
E_OUT_OF_RANGE = 10004, ///< Provided value is incapable of being produced by the hardware.
E_NOT_SUPPORTED = 10005, ///< Functionality not supported by this camera.
E_NOT_FOUND = 10006, ///< File/Data not found.
E_FILTER_DONE = 10007, ///< Filter has finished processing, and will be removed.
E_NO_FRAME = 10008, ///< A frame was requested by calling GetFrame, but none was available.
E_SAVE_ERROR = 10009, ///< Couldn't save to file.
E_MISMATCHED = 10010, ///< Buffer size mismatch.
E_BUSY = 10011, ///< The API can not read a temperature because the camera is busy.
E_INVALID_HANDLE = 10012, ///< An unknown handle was passed to the C API.
E_TIMEOUT = 10013, ///< Operation timed out.
E_FRAMEGRABBER = 10014, ///< Frame grabber error.
E_NO_CONVERSION = 10015, ///< GetFrame could not convert the image data to the requested format.
E_FILTER_SKIP_FRAME = 10016, ///< Filter indicates the frame should be skipped.
E_WRONG_VERSION = 10017, ///< Version mismatch.
E_PACKET_ERROR = 10018, ///< The requested frame cannot be provided because at least one packet has been lost.
E_WRONG_FORMAT = 10019, ///< The emissivity map you tried to set should be a 16 bit greyscale PNG.
E_WRONG_SIZE = 10020, ///< The emissivity map you tried to set has the wrong dimensions (width, height).
E_CAPSTOP = 10021, ///< Internal
E_OUT_OF_MEMORY = 10022, ///< An allocation failed because the system ran out of memory.
E_RFU
} ErrorCodes;
///
/// @brief The different colour mappings available for greyscale data sources.
/// These modes affects how colour coded images are displayed and saved to disk.
/// These flags are used by XCamera::SetColourMode and XCamera::GetColourMode.
///
typedef enum
{
ColourMode_8 = 0, ///< Intensity only
ColourMode_16 = 1, ///< Alias
ColourMode_Profile = 2, ///< Uses a colour profile bitmap. See #LoadColourProfile()
ColourMode_Invert = 256 ///< Set this flag if an inversion of the colour profile is desired. eg: #ColourMode_8 | #ColourMode_Invert
} ColourMode;
///
/// @brief The different destinations supported by the XCamera::Blit-method.
///
typedef enum
{
Window = 0, /**< Blit the contents of the last captured frame directly to a Windows client device context using a Window handle (HWND) */
DeviceContext = 1 /**< Blit the contents of the last captured frame to a specified device context.
This can be any device context (HDC) like a memory DC, paint DC or a handle to a DC associated with a Graphics-object (C#) */
} BlitType;
///
/// @brief The supported frame types
///
/// These are used to learn the native pixel size of the camera using XCamera::GetFrameType,
/// or during frame conversions when calling the XCamera::GetFrame(FrameType, unsigned long, void *, unsigned int)-method.
///
typedef enum
{
FT_UNKNOWN = -1, ///< Unknown invalid frame type
FT_NATIVE = 0, ///< The native frame type of this camera (can be FT_8..,FT_16..,FT32.. check GetFrameType())
FT_8_BPP_GRAY = 1, ///< 8-bit greyscale
FT_16_BPP_GRAY = 2, ///< 16-bit greyscale (default for most of the Xenics branded cameras)
FT_32_BPP_GRAY = 3, ///< 32-bit greyscale
FT_32_BPP_RGBA = 4, ///< 32-bit colour RGBA [B,G,R,A] Available for output conversion.
FT_32_BPP_RGB = 5, ///< 32-bit colour RGB [B,G,R] Available for output conversion.
FT_32_BPP_BGRA = 6, ///< 32-bit colour BGRA [R,G,B,A]
FT_32_BPP_BGR = 7 ///< 32-bit colour BGR [R,G,B]
} FrameType;
/* Basic types */
typedef int XCHANDLE; ///< Handle type used to identify an initialised session to a camera.
typedef unsigned long ErrCode; ///< Type to hold an error code (see #ErrorCodes)
typedef unsigned long FilterID; ///< Filter ID handle type used to identify a filter registered to the filter stack of a #XCamera-object.
#if defined(__LP64__) // Handle systems with 8-byte "long" types (such as Linux 64bit) without altering the .dll/.so signature on pre-existing systems.
typedef unsigned int dword; ///< 4 bytes (32-bits)
#else
typedef unsigned long dword; ///< 4 bytes (32-bits)
#endif
typedef unsigned short word; ///< 2 bytes (16-bits)
typedef unsigned char byte; ///< 1 byte (8-bits)
typedef unsigned char boole; ///< 1 byte (8-bits)
typedef void * voidp; ///< void pointer type
///
/// @brief Image filter messages
///
typedef enum
{
XMsgInit = 0, /**< [API->Filter Event] Called when the filter is being installed ( (!) calling thread context) */
XMsgClose = 1, /**< [API->Filter Event] Called when the filter is being removed ( (!) calling thread context) */
XMsgFrame = 2, /**< [API->Filter Event] Called after every frame grab ( (!) grabbing thread context) */
XMsgGetName = 3, /**< [App->Filter Event] Retrieve filter name: the filter should copy a friendly string to msgparm */
XMsgGetValue = 4, /**< [Obsolete] */
XMsgSave = 5, /**< [Obsolete] */
XMsgGetStatus = 6, /**< [API->Filter Event] Retrieves a general purpose status message from the image filter */
XMsgUpdateViewPort = 7, /**< [API->Filter Event] Instructs an image correction filter to update it's view port
This message is sent to a filter upon changing the window of interest, or when
flipping image horizontally or vertically */
XMsgCanProceed = 8, /**< Used by image filters in in interactive mode to indicate acceptable image conditions */
XMsgGetInfo = 9, /**< [Internal] Used to query filter 'registers' */
XMsgSelect = 10, /**< [Obsolete] */
XMsgProcessedFrame = 11, /**< [API->Filter Event] Sent after other filters have done their processing. Do not modify the frame data
in response to this event. */
XMsgTimeout = 13, /**< [API->Filter Event] A camera time-out event was generated */
XMsgIsBusy = 16, /**< [Thermography] Is the temperature filter recalculating - Used to check if the thermal filter is
still updating it's linearisation tables */
XMsgSetTROI = 17, /**< [Imaging/Thermo] Set the adu/temperature span in percent, (see #XMsgSetTROIParms) */
XMsgLoad = 18, /**< [Obsolete] */
XMsgUnload = 19, /**< [Obsolete] */
XMsgADUToTemp = 12, /**< [Thermography] Convert an ADU value to a temperature (see #XFltADUToTemperature) */
XMsgGetEN = 14, /**< [Obsolete] Get temperature correction parameters (see #XMsgGetRadiometricParms) */
XMsgSetEN = 15, /**< [Obsolete] Set temperature correction parameters (see #XMsgGetRadiometricParms) */
XMsgTempToADU = 20, /**< [Thermography] Convert a temperature to an ADU value (see #XFltTemperatureToADU) */
XMsgGetTValue = 21, /**< [Thermography] Retrieve an emissivity corrected value from a coordinate */
XMsgGetRadiometricParms = 22, /**< [Thermography] Get temperature correction parameters (see #XMsgTempParms) */
XMsgSetRadiometricParms = 23, /**< [Thermography] Set temperature correction parameters (see #XMsgTempParms) */
XMsgSerialise = 100, /**< [App->Filter event] Serialise internal parameter state (write xml structure) see #XFltSetParameter */
XMsgDeserialise = 101, /**< [App->Filter event] Deserialise parameter state (read xml structure) see #XFltSetParameter */
XMsgGetPriority = 102, /**< [Filter Management] Write the current filter priority to the long * provided in v_pMsgParm */
XMsgSetFilterState = 104, /**< [Filter Management] Enable or disable an image filter temporarily by sending 0/1 in v_pMsgParm */
XMsgIsSerialiseDirty = 105, /**< [Internal] */
XMsgStoreHandle = 106, /**< [Internal] Start tracking the module handle for plugin image filters */
XMsgUpdateTint = 107, /**< [API->Filter event] Integration time change notification */
XMsgLinADUToTemp = 109, /**< [Thermography] Convert a Linearized ADU value to a temperature (see #XFltADUToTemperatureLin) */
XMsgLinTempToADU = 110, /**< [Thermography] Convert a temperature to a Linearized ADU value (see #XFltTemperatureToADULin) */
XMsgUpdateSpan = 111, /**< [API->Filter event] Span change notification */
XMsgUpdatePalette = 112, /**< [API->Filter event] Colour profile change notification */
XMsgFilterQueued = 113, /**< [API->Filter event] A filter is queued */
XMsgFilterRemoved = 114, /**< [API->Filter event] A filter is removed */
XMsgDrawOverlay = 200, /**< [API->Filter event] Draw the RGBA frame overlay, v_pMsgParm is the pointer to the RGBA data
structure */
XMsgLineariseOutput = 201, /**< [Thermography] When specifying a v_pMsgParm that is non zero, starts linearising adu output */
XMsgSetEmiMap = 202, /**< [Thermography] Streams the main emissivity map to the thermal filter (16 bit png, 65535 = 1.0) */
XMsgSetEmiMapUser = 203, /**< [Thermography] Stream a user emissivity map to the thermal filter (16 bit png, 65535 = 1.0,
0 values are replaced by the emissivity in the main map) */
XMsgGetEmiMap = 204, /**< [Thermography] Stream out the combined emissivity map */
XMsgClrEmiMap = 205, /**< [Thermography] Clear emissivity map */
XMsgClrEmiMapUser = 206, /**< [Thermography] Clear emissivity map (user) */
XMsgPushRange = 207, /**< [Thermography] Push a new linearization range to the thermal filter */
XMsgThmFilterState = 208, /**< [Thermography] Filter event indicating thermal filter queue/removal */
XMsgThmAdjustSet = 209, /**< [Thermography] Set global offset & gain adu adjustment (pre-thermal conversion) */
XMsgThmAdjustGet = 210, /**< [Thermography] (see #XMsgTempAdjustmentParms) */
XMsgLog = 211, /**< [Plugin->API] Fire a log event to the end user application\n
Target filter id: 0xffffffff */
XMsgGetDeltaT = 212, /**< [Internal] */
XMsgGetTintRange = 213, /**< [Plugin->API] Request the exposure time range
Target filter id: 0xffffffff */
XMsgCorrectionDirty = 214, /**< [Internal] The onboard thermography parameters have changed */
XMsgHasRadianceInfo = 215, /**< [Thermography] Check if the radiance information is available. This is needed to for emissivity correction */
XMsgCorrectionDataChanged = 216, /**< [Internal] New correction data is loaded */
XMsgPostProcess = 217, /**< [Internal] A post processing step is introduced in the software correction filter */
XMsgZoomLensConnect = 300, /**< [Zoom lens] Connect to the zoom lens on the specified port. */
XMsgZoomLensGetState = 301, /**< [Zoom lens] Get the current zoom/focus state from the zoom lens filter. */
XMsgZoomLensSetState = 302, /**< [Zoom lens] Set the current zoom/focus state in the zoom lens filter. */
XMsgZoomLensGetInfo = 303, /**< [Zoom lens] Get some descriptive information about the connected lens. */
XMsgUser = 24200 /**< If you develop your own image filter plugins, please use this constant to offset your messages. */
} XFilterMessage;
///
/// @brief Image filter callback prototype.
///
/// @param[in] v_pCamera pointer to camera object
/// @param[in] v_pUserParm user argument as specified in XCamera::AddImageFilter
/// @param[in] tMsg as per #XFilterMessage
/// @param[in] v_pMsgParm as per XCamera::MsgImageFilter
///
/// @return The user has to return #I_OK on success.
/// On failure one of the other possible values should be returned.
///
/// @retval #I_OK Success.
///
typedef ErrCode (CALLCVCB *XImageFilter)(void * v_pCamera, void * v_pUserParm, XFilterMessage tMsg, void * v_pMsgParm);
///
/// @brief Status messages used in conjunction with the #XStatus-callback.
///
typedef enum {
XSLoadLogic = 1, /**< Passed when loading the camera's main logic file */
XSLoadVideoLogic = 2, /**< Passed when loading the camera's video output firmware */
XSDataStorage = 3, /**< Passed when accessing persistent data on the camera */
XSCorrection = 4, /**< Passed when uploading correction data to the camera */
XSSelfStart = 5, /**< Passed when a self starting camera is starting (instead of XSLoadLogic) */
XSMessage = 6, /**< String event
** This status message is used to relay critical errors, and events originating
** from within the API.
** Cam|PropLimit|property=number - A filter notifies you your user interface should limit the value of 'property' to 'number'
** Cam|TemperatureFilter|RangeUpdate - The thermography filter uses this to notify you of a span update.
** Cam|TemperatureFilter|Off - The thermography filter suggests the application to dequeue the filter.
** Cam|InterfaceUpdate - Internal, do not handle, returning E_BUG here causes the API to stop unpacking 'abcd.package'.packages to %appdata%/xenics/interface
**
**
**/
XSLoadGrabber = 7, /**< Passed when loading the framegrabber */
XSDeviceInformation = 8 /**< Device information passed when connecting a device, ulP is the lower part of the address. When using 64-bit the higher part of the address is stored in ulT */
} XStatusMessage;
///
/// @brief Status callback prototype.
///
/// This function is called by the SDK to report camera and interface events,
/// indicate progress while saving or loading blobs and general messages.
/// When a status function is declared the user is able to register this callback by
/// passing a pointer to the function as the pCallBack-argument when instantiating
/// a new XCamera-object (XC_OpenCamera() or XCamera::Create()).
///
/// @code
/// #include "XCamera.h"
/// #include <stdio.h>
///
/// ErrCode XStatusCallback(void *v_pUserParm, int iMsg, unsigned long ulP, unsigned long ulT) {
/// if (iMsg == XSMessage) {
///
/// #ifdef _WIN64
/// char * string_buffer = (char *)(ulP | (unsigned long long)ulT << 32);
/// #else
/// char * string_buffer = (char *)ulP;
/// #endif
///
/// printf("[MESSAGE] %s\r\n", string_buffer);
///
/// }
/// else if (iMsg == XSDeviceInformation) {
///
/// #ifdef _WIN64
/// XDeviceInformation * device_info = (XDeviceInformation *)(ulP | (unsigned long long)ulT << 32);
/// #else
/// XDeviceInformation * device_info = (XDeviceInformation *)ulP;
/// #endif
///
/// printf("[DEVINFO] %s (%i)\r\n", device_info->name, device_info->serial);
///
/// }
/// else {
/// printf("[UNHANDLED] iMsg = %i\r\n", iMsg);
/// }
///
/// return I_OK;
/// }
///
/// int main() {
/// // ...
/// XCHANDLE handle = XC_OpenCamera("soft://0", XStatusCallback, 0);
/// // ...
/// return 0;
/// }
/// @endcode
///
/// <b>SDK messages:</b>
/// When iMsg is set to #XSMessage the user can obtain a string buffer from the SDK.
/// This buffer will contain messages such as Informative event messages, warnings
/// or error messages that can be useful when debugging the user code.
/// To obtain this buffer convert ulP (32-bit), or both ulP and ulT combined (64-bit) to
/// a char-pointer where ulP is the low part of the address and for 64-bit ulT is used
/// to represent the high part of the address.
///
/// <b>Device information:</b>
/// The device information messages work in a same manner as the SDK messages. In case when iMsg is
/// set to #XSDeviceInformation the user can obtain the #XDeviceInformation-structure.
/// To obtain this structure convert ulP (32-bit), or both ulP and ulT combined (64-bit) to
/// a XDeviceInformation-pointer where ulP is the low part of the address and for 64-bit ulT is used
/// to represent the high part of the address.
///
/// @param[in] v_pUserParm User argument that will be passed for each call.
/// @param[in] iMsg #XStatusMessage
/// @param[in] ulP Progress or low address depending on the message type.
/// @param[in] ulT Total or high address (only in 64-bit) depending on the message.
///
/// @return The user has to return #I_OK on success.
/// On failure one of the other possible values should be returned.
///
/// @retval #I_OK Success.
///
typedef ErrCode (CALLCVCB *XStatus)(void *v_pUserParm, int iMsg, unsigned long ulP, unsigned long ulT);
///
/// @brief The XCamera::GetFrame(FrameType, unsigned long, void *, unsigned int)-flags
///
/// These flags are used to control the way the GetFrame-method works.
///
typedef enum
{
XGF_Blocking = 1, ///< In blocking-mode the method does not return immediately with the return codes #E_NO_FRAME / #I_OK.
/// Instead the method waits for a frame and only returns until a frame was captured, or a time-out period has elapsed.
XGF_NoConversion= 2, ///< Prevents internal conversion to 8 bit, specifying this flag reduces computation time, but prevents #SaveData() and the #Blit() method from working.
XGF_FetchPFF = 4, ///< Retrieve the per frame footer with frame timing information. Call XCamera::GetFrameFooterLength() to determine the increase in frame size.
XGF_RFU_1 = 8,
XGF_RFU_2 = 16,
XGF_RFU_3 = 32
} XGetFrameFlags;
///
/// @brief XCamera::SaveData()-flags
///
typedef enum
{
XSD_Force16 = 1, ///< Forces 16-bit output independent of the current #ColourMode-setting (only possible for PNG's)
XSD_Force8 = 2, ///< Forces 8-bit output independent of the current #ColourMode
XSD_AlignLeft = 4, ///< Left aligns 16-bit output (#XSD_Force16 | #XSD_AlignLeft)
XSD_SaveThermalInfo = 8, ///< Save thermal conversion structure (only available when saving 16-bit PNGs)
XSD_RFU_0 = 16, ///< Reserved
XSD_RFU_1 = 32,
XSD_RFU_2 = 64,
XSD_RFU_3 = 128
} XSaveDataFlags;
///
/// @brief XCamera::SaveSettings()-flags
///
typedef enum
{
XSS_SaveCameraProps = 1, ///< Define property sources to save settings from.
XSS_SaveGrabberProps = 2, ///<
XSS_SaveAllProps = 4, ///< Also save properties marked 'No persist'.
XSS_SS_RFU_3 = 8 ///<
} XSaveSettingsFlags;
///
/// @brief XCamera::LoadSettings()-flags
///
typedef enum
{
XSS_IgnoreNAIS = 1, ///< Ignore properties which do not affect the image.
XSS_LS_RFU_1 = 2, ///<
XSS_LS_RFU_2 = 4, ///<
XSS_LS_RFU_3 = 8 ///<
} XLoadSettingsFlags;
///
/// @brief XCamera::LoadCalibration()-flags
///
typedef enum
{
XLC_StartSoftwareCorrection = 1, ///< Starts the software correction filter after unpacking the calibration data
XLC_RFU_1 = 2,
XLC_RFU_2 = 4,
XLC_RFU_3 = 8
} XLoadCalibrationFlags;
///
/// @brief Xeneth property types
///
/// These types and their attributes are used by the property system.
/// To retrieve the property type call the XCamera::GetPropertyType-method using the short name to identify the property.
///
typedef enum
{
XType_None = 0x00000000,
XType_Base_Mask = 0x000000ff, ///< Type mask
XType_Attr_Mask = 0xffffff00, ///< Attribute mask
XType_Base_Number = 0x00000001, ///< A number (floating)
XType_Base_Enum = 0x00000002, ///< An enumerated type (a choice)
XType_Base_Bool = 0x00000004, ///< Boolean (true / false / 1 / 0)
XType_Base_Blob = 0x00000008, ///< Binary large object
XType_Base_String = 0x00000010, ///< String
XType_Base_Action = 0x00000020, ///< Action (button)
XType_Base_Rfu1 = 0x00000040, ///< RFU
XType_Base_Rfu2 = 0x00000080, ///< RFU
XType_Base_MinMax = 0x00002000, ///< The property accepts the strings 'min' and 'max' to set the best achievable extremities.
XType_Base_ReadOnce = 0x00001000, ///< Property needs to be read at start-up only
XType_Base_NoPersist = 0x00000800, ///< Property shouldn't be persisted (saved & restored)
XType_Base_NAI = 0x00000400, ///< Property does not affect image intensity level ('Not Affecting Image')
XType_Base_RW = 0x00000300, ///< Write and read back
XType_Base_Writeable = 0x00000200, ///< Writeable properties have this set in their high byte
XType_Base_Readable = 0x00000100, ///< Readable properties have this set in their high byte
XType_Number = 0x00000201, ///< Write only number
XType_Enum = 0x00000202, ///< Write only enumeration
XType_Bool = 0x00000204, ///< Write only boolean
XType_Blob = 0x00000208, ///< Write only binary large object
XType_String = 0x00000210, ///< Write only string
XType_Action = 0x00000220, ///< Action (button)
XType_RO_Number = 0x00000101, ///< Read only number
XType_RO_Enum = 0x00000102, ///< Read only enumeration
XType_RO_Bool = 0x00000104, ///< Read only boolean
XType_RO_Blob = 0x00000108, ///< Read only binary large object
XType_RO_String = 0x00000110, ///< Read only string
XType_RW_Number = 0x00000301, ///< R/W number
XType_RW_Enum = 0x00000302, ///< R/W enumeration
XType_RW_Bool = 0x00000304, ///< R/W boolean
XType_RW_Blob = 0x00000308, ///< R/W binary large object
XType_RW_String = 0x00000310 ///< R/W string
} XPropType;
///
/// @brief Xeneth directory identifiers used by XCamera::GetPath
///
typedef enum
{
XDir_FilterData = 0x0000, ///< Filter data (%APPDATA%/XenICs/Data/&lt;sessionnumber&gt;)
XDir_ScriptRoot = 0x0001, ///< Script root (%APPDATA%/XenICs/Interface/&lt;PID-number&gt;)
XDir_Calibrations = 0x0002, ///< Calibration folder (%ProgramFiles%/Xeneth/Calibrations)
XDir_InstallDir = 0x0003, ///< Installation folder (%CommonProgramFiles%/XenICs/Runtime)
XDir_Plugins = 0x0004, ///< Plugin folder (%CommonProgramFiles%/XenICs/Runtime/Plugins)
XDir_CachePath = 0x0005, ///< Cache folder (%APPDATA%/XenICs/Cache)
XDir_SdkResources = 0x0006, ///< SDK resource folder (%CommonProgramFiles%/XenICs/Runtime/Resources)
XDir_Xeneth = 0x0007, ///< Xeneth installation directory
XDir_GrabberScriptRoot = 0x0008, ///< Script root (%APPDATA%/XenICs/Interface/&lt;FrameGrabber&gt;)
} XDirectories;
///
/// @brief Xeneth Enumeration Flags (XEF)
///
/// Used by #XCD_EnumerateDevices and XCamera::GetDeviceList to specify the protocols to be discovered.
/// Choose #XEF_EnableAll to enumerate all supported protocols. Two flags are made available for internal cache control:
/// #XEF_UseCached is passed when the user only wants to retrieve the devices already discovered by a previous
/// call to one of the discovery methods. #XEF_ReleaseCache allows the user to clear the internal cache list.
/// By default the cache list is cleared when a new discovery sequence is initiated or when the library is released.
///
typedef enum
{
XEF_Network = 0x00000001, ///< Network
XEF_Serial = 0x00000002, ///< Serial
XEF_CameraLink = 0x00000004, ///< CameraLink
XEF_GigEVision = 0x00000008, ///< GigEVision
XEF_CoaXPress = 0x00000010, ///< CoaXPress
XEF_USB = 0x00000020, ///< USB
XEF_EnableAll = 0x0000FFFF, ///< Enable all protocols.
XEF_UseCached = 0x01000000, ///< Use cached devices on enumeration.
XEF_ReleaseCache = 0x02000000, ///< Release internally cached devices.
} XEnumerationFlag;
typedef unsigned int XEnumerationFlags; ///< @sa XEnumerationFlag
///
/// @brief Xeneth device state (XDS) used in the XDeviceInformation structure to indicate the current state of the device.
///
/// Devices which are marked as available are free to establish a connection to. Busy devices are currently
/// in use by another user. Unreachable are devices which were detected but no route exists. In this case the
/// user will be unable to establish a connection.
///
typedef enum {
XDS_Available = 0x0, ///< The device is available to establish a connection.
XDS_Busy = 0x1, ///< The device is currently in use.
XDS_Unreachable = 0x2 ///< The device was detected but is unreachable.
} XDeviceStates;
typedef unsigned int XDeviceState; ///< @sa XDeviceStates
/* Structures */
#pragma pack(push, 1)
///
/// @brief Per frame software footer.
///
/// Use XCamera::GetFrameFooterLength() to determine the exact size in bytes of both soft and hardware footers.
/// For more detailed information about footers refer to the XFooters.h-header. To learn how to retrieve
/// the per frame footer make sure to check XCamera::GetFrame(FrameType, unsigned long, void *, unsigned int) and the #XGF_FetchPFF-flag.
///
typedef struct
{
unsigned short len; ///< Structure length.
unsigned short ver; ///< Fixed to 0xAA00.
long long soc; ///< Time of Start Capture (us since start of epoch).
long long tft; ///< Time of reception (us since start of epoch).
dword tfc; ///< Frame counter.
dword fltref; ///< Reference for attaching messages/frame (described in #XFooters.h).
dword hfl; ///< Hardware footer length.
} XPFF;
///
/// @brief Device information structure
///
/// This structure holds all details needed to set up a connection to a discovered device.
/// Use this structure in combination with the XCD_EnumerateDevices()-function.
/// In case a direct connection using a protocol specific URL was established it is also
/// possible to catch the #XDeviceInformation-structure in the #XStatus-callback.
///
typedef struct {
int size; ///< Should be set to sizeof(XDeviceInformation)
char name[64]; ///< String containing the device's model name
char transport[64]; ///< Serial | CoaXPress | GigEVision | Network | CameraLink
char url[256]; ///< URL identifying the camera internally. e.g. cam://0..n
char address[64]; ///< The address where the device resides, the format is protocol specific. e.g. 192.168.2.2 | COM0..n | CL0..n::( NationalInstruments | Euresys | Imperx ... )
unsigned int serial; ///< Serial number reported by the camera. e.g. 0x12345678
unsigned int pid; ///< Product id reported by the camera. e.g. 0x0000F020
XDeviceState state; ///< Camera status to determine if the camera is in use at that time.
} XDeviceInformation;
#pragma pack(pop)
#ifdef __cplusplus
}
#endif
#ifdef __cplusplus
//////////////////////////////////////////////////////////////////////////////////////
///
/// @brief This class provides an interface to the Xenics cameras
///
class XCamera
{
protected:
XCamera();
public:
//////////////////////////////////////////////////////////////////////////////////////////
// Opening the camera
//////////////////////////////////////////////////////////////////////////////////////////
///
/// @brief Enumerates all available devices.
///
/// A device list containing 'connectionURL'|'description'. Device names are separated by a pipe '|' symbol.
///
/// @note It is advised to use the \ref c_device_discovery "Xeneth camera discovery functions (XCD_*)", such as XCD_EnumerateDevices to
/// perform device enumeration.
/// @warning This function can be marked as deprecated in a future major release but is kept for now to maintain backwards compatibility.
///
/// @param[out] pList Zero terminated string which will receive the device list.
/// @param[in] iMaxLen Allocated memory available for the device list.
///
static void IMPEXP GetDeviceList(char * pList, int iMaxLen);
///
/// @brief Enumerates all available devices, protocol selection is based on the value passed with the flags argument.
///
/// A device list containing 'connectionURL'|'description'. Device names are separated by a pipe '|' symbol.
///
/// @note It is advised to use the \ref c_device_discovery "Xeneth camera discovery functions (XCD_*)", such as XCD_EnumerateDevices to
/// perform device enumeration.
/// @warning This function can be marked as deprecated in a future major release but is kept for now to maintain backwards compatibility.
///
/// @param[out] pList Zero terminated string which will receive the device list.
/// @param[in] iMaxLen Allocated memory available for the device list.
/// @param[in] flags Flag to configure the protocols to use during the discovery sequence or to retrieve
/// the internal cached devices (See #XEnumerationFlag).
///
static void IMPEXP GetDeviceList(char * pList, int iMaxLen, XEnumerationFlags flags);
///
/// @brief Creates a camera object.
///
/// @param[in] pCameraName The camera connection URL as returned by GetDeviceList (!)\n
/// Special cameras:\n
/// \a "cam://select" Start Xeneth (if installed) to select a camera\n
/// \a "soft://0" Virtual camera (for application development without a camera)\n
/// Options:\n
/// \a "cam://x?fg=none" Start API in command & control mode (C&C). In this mode it is not possible to perform image acquisition.\n
/// \a "cam://x?fg=XFrameGrabberNative" Given the choice between using a CameraLink&trade; grabber and the native protocol (ether/usb..) use the native one.
///
/// @param[in] pCallBack Status callback function (See #XStatus)
/// @param[in] pUser User parameter for said callback function
///
/// @return A pointer to the created #XCamera-object, or a null pointer in case of an allocation error.
///
static XCamera IMPEXP *Create(const char *pCameraName = "cam://0", XStatus pCallBack = 0, void *pUser = 0);
///
/// @brief Call this destructor using the delete-operator to destroy the instance.
///
/// The session to the camera will be closed when the destructor is called.
///
virtual ~XCamera();
///
/// @brief Checks if the session to the camera was properly initialised.
///
/// @retval true The session to the camera is successfully initialised
/// @retval false The session to the camera failed to initialise
///