Scorpion Camera Driver - DLL interface

This section provides a guide to the SCD API in the forms of c-dll. The Scorpion Camera Driver dll is used as a generic interface to any 2D or 3D camera.

Camera Persistence

The Scorpion Camera Driver is responsible for camera property persistance and must store camera configuration at supplied systemPath.

This enable Scorpion to manage multiple or individual setup for each Scorpion profile.

Scorpion will always set the systempath to the profile directory in the initialize method.

The driver may use any file format/subdirectories to store the camera settings. The configuration file is when opening a camera to enable the user to manage the complete camera setting for every profile and instance of Scorpion Vision Software.

Interface Definitions

typedef struct _WH {
int w;
int h;
} WH;

typedef void CallbackFunc(unsigned int grabberNo, unsigned int portNo);
typedef void CmdCallbackFunc(unsigned int grabberNo, const char* cmd, const char* params);
typedef void DebugMsgFunc(const char* msg);

#define GRABDLL_API extern "C" __declspec(dllexport)

#define RET_OK 1
#define RET_ERR 0

Interface Description

This section provides a description of the primary functions to implement.

GRABDLL_API int initialize(char* aSystemPath, DebugMsgFunc* aDebugMsgFunc)

  Camera driver initialization - called by Scorpion after DLL loads.

  Reference counting is needed to handle multiple Scorpion instances
  where each Scorpion instance will call initialize/finalize
  at load/unload of the camera driver.

  DebugMsgFunc is used to output messages to the Scorpion console window.

  SystemPath is the profile directory.

GRABDLL_API int finalize()

  Camera driver finalization - called by Scorpion before DLL unload.

  Used to release resources

GRABDLL_API int getCVLNoOfSupportedCameras(void)

Get number of available cameras.

This method is used when iterating for available cameras in conjunction with
the "getCVLCameraConfigNames" method.

Return number of cameras - matches names returned by **getCVLCameraConfigNames**

GRABDLL_API char **getCVLCameraConfigNames()

Get names of available cameras

Should return pointers to 'static' strings.
Scorpion will scan the returned **char until a NULL pointer when browsing available cameras.

The last valid item must be followed by a NULL pointer (lpszCameraNames[nCameras]=NULL).

GRABDLL_API int openCVLPort(
  unsigned int grabberNo,
  unsigned int portNo,
  char* cameraName,
  WH &imageSize)

  Open a camera

  The driver must return the image size on success, otherwise (0,0).

Note

The image size is “static” as long as the camera is open and cannot be changed at runtime. Changes of image size will not be ‘detected’ until next time Scorpion opens the camera.

Scorpion uses the grabberNo/portNo as crossindex/handle for accessing the camera.

GRABDLL_API void closeCVLPort(unsigned int grabberNo, unsigned int portNo)

  Close the open camera

Note

A close - open sequence or camera reset will reload the configuration.

If the Image Size is changed this will change the otherwise static image size

GRABDLL_API int doCVLGrab(unsigned int grabberNo, unsigned int portNo)

  Grab an image from camera mapped to grabberNo/portNo.

GRABDLL_API int getCVLGrabRow (
  unsigned int grabberNo,
  unsigned int portNo,
  unsigned char* rowPtr,
  unsigned int row,
  unsigned int firstPix,
  unsigned int lastPix)

  Get the image from camera mapped to grabberNo/portNo

  rowPtr - [IN] destination buffer where to copy image data - allocated/owned by Scorpion
  row - [IN] range 0..height-1 image layout TOP-DOWN
  firstPix - [IN] index of first pixel in row (normally 0)
  lastPix - [IN] index of last pixel in row (normally width-1)

Note

The image size is “static” at runtime,

  • Scorpion requires image size returned in the open method.
  • The pixelSize can be changed using “set/getProperty” methods.
  • Scorpion always checks “PixelSize” property if available before acquiring an image.
GRABDLL_API int setCompleteCallback(unsigned int grabberNo, unsigned int portNo, CallbackFunc* func)

  Set a callback for image complete notifications

  The callback is normally called from the camera thread and only
  gives a notification to Scorpion when a new image is completed.

GRABDLL_API int setHWTrigger(
  unsigned int grabberNo,
  unsigned int portNo,
  unsigned int HWTrigger)

  Enable / disable HWTrigger

  unsigned int HWTrigger - boolean value of either 0 or 1

Camera Configuration

The camera driver is recommended to implement a property dialog using the configureCamera method.

The dialog is completely defined by the camera driver.

GRABDLL_API int configureCamera(
  HWND hParentWnd,
  char *cameraName)

  Used from version 6.1.0.370
  Displays the camera property dialog

Note

Scorpion versions prior to 6.1.0.370 requires the “configure” method to be implemented to enable user configuration by property dialog.

Camera Properties

This part of the interface is optional, it is recommended to implement.

Access to camera properties is very important for a fullfledge driver.

GRABDLL_API int getPropertyRange(
  unsigned int grabberNo,
  unsigned int portNo,
  char *prop,
  long *min, long *max)

  Get range for a camera property

  prop - [IN] name of property
  min - [OUT] min value of property
  max - [OUT] max value of property

GRABDLL_API int getProperty(unsigned int grabberNo, unsigned int portNo, char *prop, long *value)

Return the value for a camera property

prop - [IN] name of property
value - [OUT] value of property

Note

“PixelSize” property must be always provided, since the open method does not report PixelSize. PixelSize must be either 8 or 24 bit

GRABDLL_API int setProperty(unsigned int grabberNo, unsigned int portNo, char *prop, long value)

Set the value for a camera property

  prop - [IN] name of property
  value - [IN] value of property

Note

From Scorpion Vision XI it is recommended to implement the property access using execCmd.

Already implemented interfaces are kept unchanged for 100% backward compatibility.

The reason for moving to execCmd is the ability to support all datatypes:

  • int
  • float
  • enums

Camera Commands and CallBacks

The commands and callbacks are based on text commands. This provides an fleaxible interface to implement property management, standard commands and custom commands/events to and from the camera.

This part of the interface was added to Scorpion from version 8.0.0.441.

It is optional.

  • cmdCallBack is used by the driver to execute Scorpion Commands
    • it can be used to send messages or execute commands in Scorpion
    • a driver can make user configurable events - this can be a part of the camera property dialog
    • it makes it possible to perform Scorpion ExecuteCmd(cmd,params)
  • execCmd or executeCmd is used to send commands to the driver
    • the is a recommended command set to be implemented
    • the driver can add driver specific commands
GRABDLL_API int setCmdCallback(
  unsigned int grabberNo,
  unsigned int portNo,
  CmdCallbackFunc *func)

  Set callback functions for commands
    supported by Scorpion 8.0.0.441 and later

  The callback is threadsafe and the command execution will be
  handled by Scorpion in the normal Windows message queue.

    cmd - [OUT] command - driver specific
    params - [OUT] parameters - driver specific

GRABDLL_API int execCmd(
  unsigned int grabberNo,
  unsigned int portNo,
  const char * cmd,
  const char  *params,
  char *resp, int size)

  Execute driver specific command
    supported by Scorpion 8.0.0.441 and later

  The function should return the response as string

  cmd - [IN] command - driver specific
  params - [IN] parameters - driver specific
  resp - [OUT] the result buffer (make sure memory allocated for resp is at least size)
  size - [IN] size of result buffer

Obsolete - Legacy

The following functions are supported - but made obsolete. They are kept for backward compatibility.

GRABDLL_API int getCVLMaxNoOfGrabbers(void)

Get number of addressable grabber cards

Default is 1

GRABDLL_API int getCVLMaxNoOfPorts(unsigned int grabberNo)

Get max number of possible concurrent cameras available -

Default is 1

GRABDLL_API void setDebugMsgProc(DebugMsgFunc* aDebugMsgFunc)

  Message routing from camera driver to Scorpion console window.

  The feature is replaced by the Initialize method.

GRABDLL_API int setSystemPath(char *aSystemPath)

  Set system path for configuraton files.
  The camera driver dll is responsible for camera property persistance and must store camera
  configuration at supplied systempath to handle multiple configurations in different
  directories. Scorpion will always set the systempath to the profile directory.
  The driver may use any file format/subdirectories to store the individual camera
  configurations. The configuration files are to be used when opening a camera.

  The drivers default SystemPath should be working directory at loading

  The feature is replaced by the Initialize method.

GRABDLL_API int configure(
  HWND hParentWnd,
  unsigned int grabberNo,
  unsigned portNo)

  Displays the camera property dialog
  Scorpion versions prior to 6.1.0.370 requires the "configure" method to be implemented