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_FEATURES
A structure used to define the supported camera features.
CAMERA_
INFO
CAMERA_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 Ref
A pointer to CAMERA_INFO.
PFRAME_
DESC
FRAME_DESC By Ref
A 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.