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. |
| 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. |
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.