Notational Conventions


In this section,


  • italics are used to represent variables, function names, and program names,


  • courier is used to represent source code given as examples.


Using the API Functions with C/C++ or Visual Basic


To use the API functions within a C/C++ program, the program must include the header PixeLINKApi.h and link to PxLApi40.lib.  To use within a Visual Basic program, add the file PixeLINKApi.bas to the Visual Basic project.


Obtaining the Imager Object Handle


Most API functions in this set require a camera to be selected with PxLInitialize first.  PxLInitialize provides the camera Object Handle (or “Camera Handle”) required by these functions.  The camera is specified by the required serial number which is made available through PxLGetNumberCameras.


Return Values


All return values are listed here.


Data Types


The PixeLINK API uses a variety of simple and structured data types.  


C/C++
Visual Basic
Description
BOOLEAN
LONG
A 32 bit variable set to 0 for FALSE and non-zero fro TRUE. 
Visual Basic has a different definition of Boolean and the application 
should use LONG instead.
CAMERA_
FEATURES
CAMERA_FEATURESA structure used to define the supported camera features.
CAMERA_INFOCAMERA_INFO
A structure used to define camera-specific version information.
float
DOUBLE
A 32-bit floating point number.
FRAME_DESC
FRAME_DESC
A structure containing the settings for a frame.
HANDLE
LONG
A pointer to a structure that allows access to the camera driver. It is usually an unsigned 32 bit value. For application languages other than C/C++, that HANDLE type may be considered a 32-bit signed or unsigned integer.
LPVOID
See Descriptions
A pointer to any type (for example, typedef void *LPVOID;)
Visual Basic - does not deal in pointers. In this case, the best way to create a dynamic array of type BYTE and access its first member By Ref.
LPSTR
See Descriptions
This indicates a pointer to type CHAR (typedef CHAR *LPSTR;).  CHAR is an 8 bit variable.


For an OUT variable, a typical "pointer" can be created by an array (e.g char pName[33];)Visual Basic - This is STRING By Ref.


For an OUT variable, then the application must ensure that a NULL terminated string of appropriate length is available by using String(NECESSARY_SIZE, vbNulChar).
PCAMERA_FEATURES
CAMERA_FEATURES By Ref
A pointer to CAMERA_FEATURES.
PCAMERA_INFO
CAMERA_INFO By RefA pointer to CAMERA_INFO.
PFRAME_DESC
FRAME_DESC By RefA pointer to FRAME_DESC
PU32
LONG By Ref 
(See Descriptions)
A pointer to 32 bit unsigned integer (U32) Visual Basic. Usually use LONG By Ref. In some cases ( such as PxLGetFeature), a dynamic array is required instead. The size of the array is based on the number of LONGs required.
U32 
LONG 
A 32 bit unsigned integer.
Visual Basic does not have unsigned values. Use LONG.


Data Direction


The PixeLINK function descriptions also indicate the data direction:


IN
An input parameter that will not be modified by the function. A constant may be used.
OUT
A parameter or pointer location to be returned by the function.
IN OUT
An input parameter or pointer location to be modified by the function.

Reserved Messages


The API reserves Windows messages from WM_USER to WM_USER+100.  If user-defined messages are required for user applications, WM_USER+101 should be specified.



Format of API Function Descriptions


The following sample (MyFunction) illustrates the general format of each entry and describes the information contained within each subsection.



MyFunction
Syntax 


 PXL_RETURN_CODE MyFunction (modifier parameter[,...]);
  
This statement demonstrates the declaration syntax of the function. Each parameter is italicized.
   

Description

  

This summary of the function’s purpose is followed by descriptions of its parameters and other relevant information pertaining to the function.

  

Default [Selected functions only]

 

The default value(s) of camera properties listed here are valid after initialization or reset. 


Usage [Selected functions only]

 

A sample is provided to demonstrate usage, where necessary 


Comments, Restrictions and Limitations

 

This area contains additional comments about the function.