![]() |
PVCAM
3.9.x
Programmable Virtual Camera Access Method library
|
Functions | |
rs_bool PV_DECL | pl_pvcam_get_ver (uns16 *pvcam_version) |
Returns the PVCAM version number. More... | |
rs_bool PV_DECL | pl_pvcam_init (void) |
Opens and initializes the library. More... | |
rs_bool PV_DECL | pl_pvcam_uninit (void) |
Closes the library, closes all devices, frees memory. More... | |
rs_bool PV_DECL | pl_cam_close (int16 hcam) |
Frees the current camera, prepares it for power-down. More... | |
rs_bool PV_DECL | pl_cam_get_name (int16 cam_num, char *camera_name) |
Returns the name of a camera. More... | |
rs_bool PV_DECL | pl_cam_get_total (int16 *totl_cams) |
Returns the number of cameras attached to the system. More... | |
rs_bool PV_DECL | pl_cam_open (char *camera_name, int16 *hcam, int16 o_mode) |
Reserves and initializes the camera hardware. More... | |
rs_bool PV_DECL | pl_cam_register_callback_ex3 (int16 hcam, int32 callback_event, void *callback, void *context) |
Installs a function that will be called when an event occurs in a camera providing information about frame via FRAME_INFO type and with user context information. More... | |
rs_bool PV_DECL | pl_cam_deregister_callback (int16 hcam, int32 callback_event) |
Uninstalls a function for camera system event. More... | |
int16 PV_DECL | pl_error_code (void) |
Returns the most recent error condition. More... | |
rs_bool PV_DECL | pl_error_message (int16 err_code, char *msg) |
Returns a string explaining input error code. More... | |
rs_bool PV_DECL | pl_get_param (int16 hcam, uns32 param_id, int16 param_attribute, void *param_value) |
Returns the requested attribute for a PVCAM parameter. More... | |
rs_bool PV_DECL | pl_set_param (int16 hcam, uns32 param_id, void *param_value) |
Sets the current value for a PVCAM parameter. More... | |
rs_bool PV_DECL | pl_get_enum_param (int16 hcam, uns32 param_id, uns32 index, int32 *value, char *desc, uns32 length) |
Returns the enumerated value of the parameter param_id at index. More... | |
rs_bool PV_DECL | pl_enum_str_length (int16 hcam, uns32 param_id, uns32 index, uns32 *length) |
Returns the length of the descriptive string for the parameter param_id at index. More... | |
rs_bool PV_DECL | pl_pp_reset (int16 hcam) |
This function will reset all post-processing modules to their default values. More... | |
rs_bool PV_DECL | pl_create_smart_stream_struct (smart_stream_type **array, uns16 entries) |
Creates and allocates variable of smart_stream_type type with the number of entries passed in via the entries parameter and returns pointer to it. More... | |
rs_bool PV_DECL | pl_release_smart_stream_struct (smart_stream_type **array) |
Frees the space previously allocated by the pl_create_smart_stream_struct function. More... | |
rs_bool PV_DECL | pl_create_frame_info_struct (FRAME_INFO **new_frame) |
Creates and allocates variable of FRAME_INFO type and returns pointer to it. More... | |
rs_bool PV_DECL | pl_release_frame_info_struct (FRAME_INFO *frame_to_delete) |
Deletes variable of FRAME_INFO type. More... | |
rs_bool PV_DECL | pl_exp_setup_seq (int16 hcam, uns16 exp_total, uns16 rgn_total, const rgn_type *rgn_array, int16 exp_mode, uns32 exposure_time, uns32 *exp_bytes) |
Prepares the camera to perform a readout. More... | |
rs_bool PV_DECL | pl_exp_start_seq (int16 hcam, void *pixel_stream) |
Begins exposing, returns immediately. More... | |
rs_bool PV_DECL | pl_exp_setup_cont (int16 hcam, uns16 rgn_total, const rgn_type *rgn_array, int16 exp_mode, uns32 exposure_time, uns32 *exp_bytes, int16 buffer_mode) |
Sets circular buffer mode. More... | |
rs_bool PV_DECL | pl_exp_start_cont (int16 hcam, void *pixel_stream, uns32 size) |
Begins continuous readout into circular buffer. More... | |
rs_bool PV_DECL | pl_exp_trigger (int16 hcam, uns32 *flags, uns32 value) |
Sends a software trigger to the device. More... | |
rs_bool PV_DECL | pl_exp_check_status (int16 hcam, int16 *status, uns32 *bytes_arrived) |
Checks the status of sequence acquisition. More... | |
rs_bool PV_DECL | pl_exp_check_cont_status (int16 hcam, int16 *status, uns32 *bytes_arrived, uns32 *buffer_cnt) |
Checks the continuous readout status from the camera into a circular buffer. More... | |
rs_bool PV_DECL | pl_exp_check_cont_status_ex (int16 hcam, int16 *status, uns32 *byte_cnt, uns32 *buffer_cnt, FRAME_INFO *frame_info) |
Checks the continuous readout status from the camera into a circular buffer. More... | |
rs_bool PV_DECL | pl_exp_get_latest_frame (int16 hcam, void **frame) |
This function returns a pointer to the most recently acquired frame in the circular buffer. More... | |
rs_bool PV_DECL | pl_exp_get_latest_frame_ex (int16 hcam, void **frame, FRAME_INFO *frame_info) |
Returns pointer to the most recent frame in circular buffer. More... | |
rs_bool PV_DECL | pl_exp_get_oldest_frame (int16 hcam, void **frame) |
This function returns pointer to the oldest unretrieved frame in the circular buffer. More... | |
rs_bool PV_DECL | pl_exp_get_oldest_frame_ex (int16 hcam, void **frame, FRAME_INFO *frame_info) |
This function returns pointer to the oldest unretrieved frame in the circular buffer. More... | |
rs_bool PV_DECL | pl_exp_unlock_oldest_frame (int16 hcam) |
Makes oldest frame in circular buffer overwritable. More... | |
rs_bool PV_DECL | pl_exp_stop_cont (int16 hcam, int16 cam_state) |
Stops continuous readout acquisition. Identical to pl_exp_abort. More... | |
rs_bool PV_DECL | pl_exp_abort (int16 hcam, int16 cam_state) |
Stops collecting data, cleans up device driver, halts camera. More... | |
rs_bool PV_DECL | pl_exp_finish_seq (int16 hcam, void *pixel_stream, int16 hbuf) |
Finishes and cleans up after pl_exp_start_seq. More... | |
rs_bool PV_DECL | pl_io_script_control (int16 hcam, uns16 addr, flt64 state, uns32 location) |
Defines control of an I/O line from within a camera script. More... | |
rs_bool PV_DECL | pl_io_clear_script_control (int16 hcam) |
Clears the current setup for control of the available I/O lines within a camera script. More... | |
rs_bool PV_DECL | pl_md_frame_decode (md_frame *pDstFrame, void *pSrcBuf, uns32 srcBufSize) |
Decodes a metadata-enabled frame data into provided frame descriptor structure. More... | |
rs_bool PV_DECL | pl_md_frame_recompose (void *pDstBuf, uns16 offX, uns16 offY, uns16 dstWidth, uns16 dstHeight, md_frame *pSrcFrame) |
Optional function that recomposes a multi-ROI frame into a displayable image buffer. More... | |
rs_bool PV_DECL | pl_md_create_frame_struct_cont (md_frame **pFrame, uns16 roiCount) |
This method creates an empty md_frame structure for known number of ROIs. More... | |
rs_bool PV_DECL | pl_md_create_frame_struct (md_frame **pFrame, void *pSrcBuf, uns32 srcBufSize) |
This method creates an empty md_frame structure from an existing buffer. More... | |
rs_bool PV_DECL | pl_md_release_frame_struct (md_frame *pFrame) |
Releases the md_frame struct. More... | |
rs_bool PV_DECL | pl_md_read_extended (md_ext_item_collection *pOutput, void *pExtMdPtr, uns32 extMdSize) |
Reads all the extended metadata from the given ext. metadata buffer. More... | |
Frees the current camera, prepares it for power-down.
This function has two effects. First, it removes the listed camera from the reserved list, allowing other users to open and use the hardware. Second, it performs all cleanup, close-down, and shutdown preparations needed by the hardware. A camera can only be closed if it was previously opened.
[in] | hcam | Camera handle returned from pl_cam_open. |
Uninstalls a function for camera system event.
Use this API call to uninstall a function for the specified camera system event.
[in] | hcam | Camera handle returned from pl_cam_open. |
[in] | callback_event | Callback event to register for (see PL_CALLBACK_EVENT). |
Returns the name of a camera.
This function allows a user to learn the string identifier associated with every camera on the current system. This is a companion to the pl_cam_get_total function. cam_num input can run from 0 to (totl_cams-1
), inclusive. The user must pass in a string that is at least CAM_NAME_LEN characters long, pl_cam_get_name then fills that string with an appropriate null-terminated string. camera_name
can be passed directly into the pl_cam_open function. It has no other use, aside from providing a brief description of the camera.
[in] | cam_num | Camera number Range: 0 through (totl_cams-1 ). |
[out] | camera_name | Text name assigned to a camera (with RSConfig). |
Returns the number of cameras attached to the system.
This function reports the number of cameras on the system. All the listed cameras may not be available on multi-tasking systems, some cameras may already be in use by other users. A companion function pl_cam_get_name can be used to get the string identifier associated with each camera.
[out] | totl_cams | Total number of cameras in the system. |
uninit
/ init
regenerates the list of available cameras, updating the system for any additions or deletions. Reserves and initializes the camera hardware.
The string camera_name should be identical to one of the valid camera names returned by pl_cam_get_name. If the name is valid, pl_cam_open completes a short set of checks and diagnostics as it attempts to establish communication with the camera electronics unit. If successful, the camera is opened and a valid camera handle is passed back in hcam. Otherwise, pl_cam_open returns with a failure. An explanation is shown in pl_error_code.
The o_mode setting controls the mode under which the camera is opened. Currently, the only possible choice is OPEN_EXCLUSIVE. On multi-user systems, opening a camera under the exclusive mode reserves it for the current user, locking out all other users on the system. If pl_cam_open is successful, the user has exclusive access to that camera until the camera is closed or pl_pvcam_uninit is called.
[in] | camera_name | Text name assigned to a camera (with RSConfig). |
[out] | hcam | Camera handle returned from pl_cam_open. |
[in] | o_mode | Mode to open the camera in (must be OPEN_EXCLUSIVE). |
rs_bool PV_DECL pl_cam_register_callback_ex3 | ( | int16 | hcam, |
int32 | callback_event, | ||
void * | callback, | ||
void * | context | ||
) |
Installs a function that will be called when an event occurs in a camera providing information about frame via FRAME_INFO type and with user context information.
This function combines functionality provided by pl_cam_register_callback_ex and pl_cam_register_callback_ex2.
Use this API call to install a function that will be called when the specified event occurs providing additional frame information. Input parameter of the callback function must be of FRAME_INFO* type in order to receive information about the frame (timestamp with precision of 0.1ms, frame counter number, ID (handle) of the camera that produced the frame). Also pointer to a context that will be echoed back when the callback is invoked can be passed to PVCAM in this function.
[in] | hcam | Camera handle returned from pl_cam_open. |
[in] | callback_event | Callback event to register for (see PL_CALLBACK_EVENT). |
[out] | callback | Callback function pointer. |
[out] | context | Pointer to custom user context. |
rs_bool PV_DECL pl_create_frame_info_struct | ( | FRAME_INFO ** | new_frame | ) |
Creates and allocates variable of FRAME_INFO type and returns pointer to it.
This function will create a variable of FRAME_INFO type and return a pointer to access it. The GUID field of the FRAME_INFO structure is assigned by this function. Other fields are updated by PVCAM at the time of frame reception.
[out] | new_frame | Frame info struct to be returned. |
rs_bool PV_DECL pl_create_smart_stream_struct | ( | smart_stream_type ** | array, |
uns16 | entries | ||
) |
Creates and allocates variable of smart_stream_type type with the number of entries passed in via the entries parameter and returns pointer to it.
This function will create a variable of smart_stream_type type and return a pointer to access it. The entries parameter passed by the user determines how many entries the structure will contain.
[out] | array | Created struct to be returned. |
[in] | entries | Number of entries to be in smart stream struct. |
Returns the length of the descriptive string for the parameter param_id at index.
This function will return the length (length) of the descriptive string for the parameter param_id at index. The length includes the terminating null ('\0') character.
[in] | hcam | Camera handle returned from pl_cam_open. |
[in] | param_id | ID of the parameter to get or set (PARAM_...). |
[in] | index | Index of enumeration Range: 0 through N-1, where N is retrieved with get_param(..., ATTR_COUNT, ...). |
[out] | length | Length of text description of enumeration. |
int16 PV_DECL pl_error_code | ( | void | ) |
Returns the most recent error condition.
As every PVCAM function begins, it resets the error code to 0. If an error occurs later in the function, the error code is set to a corresponding value.
For details about correct handling see Error Handling section.
Returns a string explaining input error code.
This function fills in the character string msg with a message that corresponds to the value in err_code. The msg string is allocated by the user, and should be at least ERROR_MSG_LEN elements long.
For details about correct handling see Error Handling section.
[in] | err_code | Unique ID of the error: returned from pl_error_code. |
[out] | msg | Text description of err_code. |
Stops collecting data, cleans up device driver, halts camera.
pl_exp_abort performs two functions: it stops the host device driver, and it may halt the camera (hcam specifies which camera and which device driver are being used.) Halting the camera halts readout, clearing
, and all other camera activity. On the host side, data collection is controlled by a device driver. If data collection is currently enabled (the image data active state), this function stops collection, returns the low-level communication hardware and software to an image data idle state, and disables collection. In the idle state, any data that arrives is ignored and discarded. The idle state is the normal system default. On the camera side, the Camera Control Subsystem (CCS) may be in the process of collecting data, or it may be in one of several idle states. This function always stops the data collection software. In addition, it has the option of forcing the CCS into a new state by setting the cam_state variable to one of the following constants, which are camera dependent: PL_CCS_ABORT_MODES.
[in] | hcam | Camera handle returned from pl_cam_open. |
[out] | cam_state | State to set the camera in (CCS_NO_CHANGE,...). |
clear_cycles
is zero or the clear mode is CLEAR_NEVER, the image may be read off by performing a bias readout. In frame transfer mode, you may not want to close the shutter when halting the CCS. Some frame transfer systems do not include a shutter, in which case an attempt to open or close the shutter is ignored, but does not cause an error. rs_bool PV_DECL pl_exp_check_cont_status | ( | int16 | hcam, |
int16 * | status, | ||
uns32 * | bytes_arrived, | ||
uns32 * | buffer_cnt | ||
) |
Checks the continuous readout status from the camera into a circular buffer.
This function will return the status of a continuous readout from the camera into a circular buffer. status is a pointer to one of the values listed here: PL_IMAGE_STATUSES.
[in] | hcam | Camera handle returned from pl_cam_open. |
[out] | status | Status of the current capture (EXPOSURE_IN_PROGRESS,...). |
[out] | bytes_arrived | Number of bytes that have arrived. For continuous mode this is the number of bytes that have arrived this time through the buffer. |
[out] | buffer_cnt | Number of times through the buffer (continuous mode). |
rs_bool PV_DECL pl_exp_check_cont_status_ex | ( | int16 | hcam, |
int16 * | status, | ||
uns32 * | byte_cnt, | ||
uns32 * | buffer_cnt, | ||
FRAME_INFO * | frame_info | ||
) |
Checks the continuous readout status from the camera into a circular buffer.
This function will return the status of a continuous readout from the camera into a circular buffer. status is a pointer to one of the values listed here: PL_IMAGE_STATUSES.
Values in the variable pointed to by frame_info will be updated with frame counters, timestamps (with precision of 0.1ms) and readout time information assigned by device driver at the moment of frame reception.
[in] | hcam | Camera handle returned from pl_cam_open. |
[out] | status | Status of the current capture (EXPOSURE_IN_PROGRESS,...). |
[out] | byte_cnt | Size of buffer to hold images (in bytes). |
[out] | buffer_cnt | Number of times through the buffer (continuous mode). |
[out] | frame_info | Frame info struct pointer. |
Checks the status of sequence acquisition.
This is only useful when data collection has been set up and started, as with a call to the functions pl_exp_setup_seq and pl_exp_start_seq. In general, these functions start an exposure and then immediately return, allowing the progress to be monitored. The status gives a quick evaluation of progress. The argument status returns one of the values listed here: PL_IMAGE_STATUSES.
More detailed information is returned in bytes_arrived. This reports on exactly how many bytes of data have arrived so far. This level of feedback is unimportant to many users.
[in] | hcam | Camera handle returned from pl_cam_open. |
[out] | status | Status of the current capture (EXPOSURE_IN_PROGRESS, ...). |
[out] | bytes_arrived | Number of bytes that have arrived. For continuous mode this is the number of bytes that have arrived this time through the buffer. |
Finishes and cleans up after pl_exp_start_seq.
This cleans up after an exposure started through pl_exp_start_seq has finished readout. If the exposure has not finished readout, this function returns with an error. Argument hbuf is not used at the moment.
[in] | hcam | Camera handle returned from pl_cam_open. |
[in] | pixel_stream | Buffer to hold image(s). |
[in] | hbuf | Standard image buffer. Not used this time. |
This function returns a pointer to the most recently acquired frame in the circular buffer.
[in] | hcam | Camera handle returned from pl_cam_open. |
[out] | frame | Pointer to the most recent frame. |
rs_bool PV_DECL pl_exp_get_latest_frame_ex | ( | int16 | hcam, |
void ** | frame, | ||
FRAME_INFO * | frame_info | ||
) |
Returns pointer to the most recent frame in circular buffer.
Additionally, this function updates values of timestamps (with precision of 0.1ms), frame counter numbers and readout time in variable of FRAME_INFO type.
[in] | hcam | Camera handle returned from pl_cam_open. |
[out] | frame | Pointer to the most recent frame. |
[out] | frame_info | Frame info struct pointer. |
This function returns pointer to the oldest unretrieved frame in the circular buffer.
After calling this function, pl_exp_unlock_oldest_frame has to be called to notify PVCAM that the oldest frame can be overwritten with new data.
This function should be used in acquisitions running in CIRC_NO_OVERWRITE mode.
[in] | hcam | Camera handle returned from pl_cam_open. |
[out] | frame | Pointer to the oldest unretrieved frame. |
rs_bool PV_DECL pl_exp_get_oldest_frame_ex | ( | int16 | hcam, |
void ** | frame, | ||
FRAME_INFO * | frame_info | ||
) |
This function returns pointer to the oldest unretrieved frame in the circular buffer.
After calling this function, pl_exp_unlock_oldest_frame has to be called to notify PVCAM that the oldest frame can be overwritten with new data.
This function should be used in acquisitions running in CIRC_NO_OVERWRITE mode.
Additionally, this function updates the values in the variable pointed to by frame_info with the data collected at the time of frame reception by the device driver (e.g. frame counter value).
[in] | hcam | Camera handle returned from pl_cam_open. |
[out] | frame | Pointer to the oldest unretrieved frame. |
[out] | frame_info | Frame info struct pointer. |
rs_bool PV_DECL pl_exp_setup_cont | ( | int16 | hcam, |
uns16 | rgn_total, | ||
const rgn_type * | rgn_array, | ||
int16 | exp_mode, | ||
uns32 | exposure_time, | ||
uns32 * | exp_bytes, | ||
int16 | buffer_mode | ||
) |
Sets circular buffer mode.
This function sets the mode of operation for the circular buffer. This function uses the array of regions, exposure mode, exposure time passed in, and circular buffer mode and transmits them to the camera. The pointer rgn_array points to rgn_total region definitions. exp_mode specifies the bitwise OR combination of the exposure mode and expose out mode. exposure_time specifies the exposure time in the currently selected exposure time resolution (see PARAM_EXP_RES and PARAM_EXP_RES_INDEX). The pointer exp_bytes points to a variable that will be filled with number of bytes in the pixel stream. buffer_mode can be set to either CIRC_OVERWRITE or CIRC_NO_OVERWRITE. This function must be called before calling pl_exp_start_cont.
The settings are then downloaded to the camera. If there is any problem (overlapping regions or a frame-transfer setting for a camera that lacks that capability), this function aborts and returns with a failure. pl_error_code indicates the definition problem. The exp_bytes pointer is filled with the number of bytes of memory needed to buffer the full sequence. (It is the developer's responsibility to allocate a memory buffer for the pixel stream.) When this function returns, the camera is ready to begin the exposure. pl_exp_start_cont initiates exposure and readout.
[in] | hcam | Camera handle returned from pl_cam_open. |
[in] | rgn_total | Total number of regions defined for each image. |
[in] | rgn_array | Array of regions (must be rgn_total in size). See rgn_type for details. |
[in] | exp_mode | Mode for capture (TIMED_MODE, STROBED_MODE, ...). |
[in] | exposure_time | Time to expose in selected exposure resolution. Default is milliseconds (see PARAM_EXP_RES). |
[out] | exp_bytes | Value returned from PVCAM specifying the required number of bytes to allocate for the capture. |
[in] | buffer_mode | Circular buffer mode (CIRC_OVERWRITE, CIRC_NO_OVERWRITE). |
rs_bool PV_DECL pl_exp_setup_seq | ( | int16 | hcam, |
uns16 | exp_total, | ||
uns16 | rgn_total, | ||
const rgn_type * | rgn_array, | ||
int16 | exp_mode, | ||
uns32 | exposure_time, | ||
uns32 * | exp_bytes | ||
) |
Prepares the camera to perform a readout.
This function uses the array of regions, exposure mode, and exposure time passed in and transmits them to the camera. exp_total specifies the number of images to take. The pointer rgn_array points to rgn_total region definitions, exp_mode specifies the bitwise OR combination of exposure mode and expose out mode (see chapter Extended Exposure Modes), exposure_time specifies the exposure time in the currently selected exposure time resolution (see PARAM_EXP_RES and PARAM_EXP_RES_INDEX). The pointer exp_bytes points to a variable that will be filled with number of bytes in the pixel stream. The settings are then uploaded to the camera. If there is any problem (overlapping regions or a frame-transfer setting for a camera that lacks that capability), this function aborts and returns with a failure. pl_error_code indicates the definition problem. The exp_bytes pointer is filled with the number of bytes of memory needed to buffer the full sequence. (It is the developer's responsibility to allocate a memory buffer for the pixel stream.) When this function returns, the camera is ready to begin the exposure. pl_exp_start_seq initiates exposure and readout.
[in] | hcam | Camera handle returned from pl_cam_open. |
[in] | exp_total | Total number of exposures to take. |
[in] | rgn_total | Total number of regions defined for each image. |
[in] | rgn_array | Array of regions (must be rgn_total in size). See rgn_type for details. |
[in] | exp_mode | Mode for capture (TIMED_MODE, STROBED_MODE, ...). |
[in] | exposure_time | Time to expose in selected exposure resolution. Default is milliseconds (see PARAM_EXP_RES). |
[out] | exp_bytes | Value returned from PVCAM specifying the required number of bytes to allocate for the capture. |
Begins continuous readout into circular buffer.
This function will initiate a continuous readout from the camera into a circular buffer.
[in] | hcam | Camera handle returned from pl_cam_open. |
[in] | pixel_stream | Buffer to hold image(s). |
[in] | size | Size of continuous capture pixel_stream (must be a multiple of byte_cnt ). |
Begins exposing, returns immediately.
This is a companion function to pl_exp_setup_seq. pl_exp_setup_seq must be called first to define the exposure and program this information into the camera. After that, pl_exp_start_seq may be called one or more times. Each time it is called, it starts one sequence and returns immediately (a sequence may be one or more exposures). Progress can be monitored through pl_exp_check_status. The next sequence may be started as soon as the readout has finished or an abort has been performed (pl_exp_abort).
The hcam parameter defines which camera is used. The user must allocate an appropriately sized memory buffer for data collection, pointed to by pixel_stream. This buffer must be at least exp_bytes
bytes, where exp_bytes
is the value returned from pl_exp_setup_seq.
[in] | hcam | Camera handle returned from pl_cam_open. |
[out] | pixel_stream | Buffer to hold image(s). |
Stops continuous readout acquisition. Identical to pl_exp_abort.
This function halts a continuous readout acquisition into a circular buffer. cam_state defines the new state of the Camera Control Subsystem, as described in the documentation for the pl_exp_abort function. To simplify the code, pl_exp_abort may be used instead of pl_exp_stop_cont to stop both continuous and sequential acquisitions.
[in] | hcam | Camera handle returned from pl_cam_open. |
[out] | cam_state | State to set the camera in (CCS_NO_CHANGE,...). |
Sends a software trigger to the device.
In order to use the software trigger, following preconditions must be met:
[in] | hcam | Camera handle returned from pl_cam_open. |
[in,out] | flags | Input/output flags, see remarks. |
[in] | value | Reserved for future use. This value should be set to 0. |
Makes oldest frame in circular buffer overwritable.
This function allows PVCAM to overwrite the oldest frame in the circular buffer.
[in] | hcam | Camera handle returned from pl_cam_open. |
rs_bool PV_DECL pl_get_enum_param | ( | int16 | hcam, |
uns32 | param_id, | ||
uns32 | index, | ||
int32 * | value, | ||
char * | desc, | ||
uns32 | length | ||
) |
Returns the enumerated value of the parameter param_id at index.
This function will return the enumerated value of the parameter param_id at index. It also returns a string associated with the enumerated type (desc). length indicates the maximum length allowed for the returned description.
[in] | hcam | Camera handle returned from pl_cam_open. |
[in] | param_id | ID of the parameter to get or set (PARAM_...). |
[in] | index | Index of enumeration Range: 0 through N-1 ... where N is retrieved with get_param(...,ATTR_COUNT,...). |
[out] | value | Numerical value of enumeration. |
[out] | desc | Text description of enumeration. |
[in] | length | Length of text description of enumeration. |
rs_bool PV_DECL pl_get_param | ( | int16 | hcam, |
uns32 | param_id, | ||
int16 | param_attribute, | ||
void * | param_value | ||
) |
Returns the requested attribute for a PVCAM parameter.
This function returns the requested attribute for a PVCAM parameter.
param_id is an enumerated type that indicates the parameter in question. param_value points to the value of the requested attribute for the parameter. It is a void*
because it can be different data types. The user is responsible for passing in the correct data type (see attribute descriptions that follow). param_attribute is used to retrieve characteristics of the parameter. See PL_PARAM_ATTRIBUTES for possible values for param_attribute.
Reading of values for attributes ATTR_AVAIL, ATTR_ACCESS and ATTR_TYPE should always succeed and return correct value. Values for other attributes can be read only if ATTR_ACCESS reports either ACC_READ_ONLY or ACC_READ_WRITE.
[in] | hcam | Camera handle returned from pl_cam_open. |
[in] | param_id | ID of the parameter to get or set (PARAM_...). |
[in] | param_attribute | Attribute of the parameter to get (ATTR_...). |
[out] | param_value | Value to get or set. |
Clears the current setup for control of the available I/O lines within a camera script.
This function allows the application program to clear the current setup for control of the available I/O lines within the script. This allows the user to enter a new setup for these lines.
[in] | hcam | Camera handle returned from pl_cam_open. |
Defines control of an I/O line from within a camera script.
This function allows the application program to define control of the available I/O lines from within a script. This allows for more precise control of external devices. For example, the application could request that a linear stage be indexed immediately after integration, instead of waiting until after the data is read out, the shutter is closed, etc.
state has different meanings depending on the I/O type which are described here: PL_IO_TYPE. location can be set to the values described here: PL_SRC_MODES.
[in] | hcam | Camera handle returned from pl_cam_open. |
[in] | addr | Specifies which I/O address to control. |
[in] | state | Specifies the value to write to the register. |
[in] | location | Specifies when to control the I/O (SCR_PRE_FLASH,...). Values are listed here: PL_IO_TYPE. |
This method creates an empty md_frame structure from an existing buffer.
Use this method when loading buffers from disk or when performance is not critical. Do not forget to release the structure when not needed. For continuous acquisition where the number or ROIs is known it is recommended to use the other provided method to avoid frequent memory allocation.
[out] | pFrame | A pointer address where the newly created structure will be stored. |
[in] | pSrcBuf | A raw frame data pointer as returned from the camera |
[in] | srcBufSize | Size of the raw frame data buffer |
This method creates an empty md_frame structure for known number of ROIs.
Use this method to prepare and pre-allocate one structure before starting continuous acquisition. Once callback arrives fill the structure with pl_md_frame_decode and display the metadata. Release the structure when not needed.
[out] | pFrame | A pointer to frame helper structure address where the structure will be allocated. |
[in] | roiCount | Number of ROIs the structure should be prepared for. |
Decodes a metadata-enabled frame data into provided frame descriptor structure.
This function processes the input frame and calculates pointers to frame metadata header, ROI header(s) and ROI image data and stores those into the provided pDstFrame structure. This function does not copy any pixel data. Since the pDstFrame stores only pointers to the pSrcBuf memory, the pSrcBuf must be valid for as long as the pDstFrame is accessed.
[out] | pDstFrame | A pre-allocated helper structure that will be filled with information based on the input frame buffer. |
[in] | pSrcBuf | A pointer to a frame data as retrieved from PVCAM. See functions pl_exp_get_latest_frame and pl_exp_get_latest_frame_ex. |
[in] | srcBufSize | The size of the raw frame data. Size of a frame is obtained from pl_exp_setup_seq and pl_exp_setup_cont functions. |
rs_bool PV_DECL pl_md_frame_recompose | ( | void * | pDstBuf, |
uns16 | offX, | ||
uns16 | offY, | ||
uns16 | dstWidth, | ||
uns16 | dstHeight, | ||
md_frame * | pSrcFrame | ||
) |
Optional function that recomposes a multi-ROI frame into a displayable image buffer.
Every ROI will be copied into its appropriate location in the provided buffer. Please note that the function will subtract the Implied ROI position from each ROI position which essentially moves the entire Implied ROI to a [0, 0] position. Use the Offset arguments to shift all ROIs back to desired positions if needed. If you use the Implied ROI position for offset arguments the frame will be recomposed as it appears on the full frame.
The caller is responsible for black-filling the input buffer. Usually, this function is called during live/preview mode where the destination buffer is re-used. If the ROIs do move during acquisition it is essential to black-fill the destination buffer before calling this function. This is not needed if the ROIs do not move. If the ROIs move during live mode it is also recommended to use the offset arguments and recompose the ROI to a full frame - with moving ROIs the implied ROI may change with each frame and this may cause undesired ROI "twitching" in the displayable image.
[out] | pDstBuf | An output buffer, the buffer must be at least the size of the implied ROI that is calculated during the frame decoding process. The buffer must be of type uns16. If offset is set the buffer must be large enough to allow the entire implied ROI to be shifted. |
[in] | offX | Offset in the destination buffer, in pixels. If 0 the Implied ROI will be shifted to position 0 in the target buffer. Use (ImpliedRoi.s1 / ImplierRoi.sbin) as offset value to disable the shift and keep the ROIs in their absolute positions. |
[in] | offY | Offset in the destination buffer, in pixels. If 0 the Implied ROI will be shifted to position 0 in the target buffer. Use (ImpliedRoi.p1 / ImplierRoi.pbin) as offset value to disable the shift and keep the ROIs in their absolute positions. |
[in] | dstWidth | Width, in pixels of the destination image buffer. The buffer must be large enough to hold the entire Implied ROI, including the offsets (if used). |
[in] | dstHeight | Height, in pixels of the destination image buffer. |
[in] | pSrcFrame | A helper structure, previously decoded using the frame decoding function. |
rs_bool PV_DECL pl_md_read_extended | ( | md_ext_item_collection * | pOutput, |
void * | pExtMdPtr, | ||
uns32 | extMdSize | ||
) |
Reads all the extended metadata from the given ext. metadata buffer.
[out] | pOutput | A pre-allocated structure that will be filled with metadata |
[in] | pExtMdPtr | A pointer to the ext. MD buffer, this can be obtained from the md_frame and md_frame_roi structures. |
[in] | extMdSize | Size of the ext. MD buffer, also retrievable from the helper structures. |
Releases the md_frame struct.
[in] | pFrame | A pointer to the previously allocated structure. |
This function will reset all post-processing modules to their default values.
[in] | hcam | Camera handle returned from pl_cam_open. |
Returns the PVCAM version number.
The version is a highly formatted hexadecimal number of the style:
High byte | Low | byte |
---|---|---|
High nibble | Low nibble | |
Major version | Minor version | Trivial version |
For example, the number 0x11F1 indicates major release 17, minor release 15, and trivial change 1. A major release is defined as anything that alters the interface, calling sequence, parameter list, or interpretation of any function in the library. This includes new functions and alterations to existing functions, but it does not include alterations to the optional libraries, which sit on top of PVCAM (each optional library includes its own, independent version number). A new major release often requires a change in the PVCAM library, but wherever possible, major releases are backwards compatible with earlier releases. A minor release should be completely transparent to higher-level software (PVCAM) but may include internal enhancements. The trivial version is reserved for use by the software staff to keep track of extremely minor variations. The last digit is used for build numbers and should be ignored. Minor and trivial releases should require no change in the calling software.
[out] | pvcam_version | Version number of PVCAM installer. |
rs_bool PV_DECL pl_pvcam_init | ( | void | ) |
Opens and initializes the library.
The PVCAM library requires significant system resources: memory, hardware access, etc. pl_pvcam_init prepares these resources for use, as well as allocating whatever static memory the library needs. Until pl_pvcam_init is called, every PVCAM function (except for the error reporting functions) will fail and return an error message that corresponds to "library has not been initialized".
rs_bool PV_DECL pl_pvcam_uninit | ( | void | ) |
Closes the library, closes all devices, frees memory.
This function releases all system resources that pl_pvcam_init acquired. It also searches for all cameras that the user has opened. If it finds any, it will close them before exiting. It will also unlock and free memory, and clean up after itself as much as possible.
rs_bool PV_DECL pl_release_frame_info_struct | ( | FRAME_INFO * | frame_to_delete | ) |
Deletes variable of FRAME_INFO type.
This function will deallocate FRAME_INFO variable created by pl_create_frame_info_struct.
[in] | frame_to_delete | Frame info struct to be released. |
rs_bool PV_DECL pl_release_smart_stream_struct | ( | smart_stream_type ** | array | ) |
Frees the space previously allocated by the pl_create_smart_stream_struct function.
This function will deallocate a smart_stream_type variable created by pl_create_smart_stream_struct.
[in] | array | Struct to be released. |
Sets the current value for a PVCAM parameter.
This function sets the current value for a PVCAM parameter.
param_id is an enumerated type that indicates the parameter in question. param_value points to the new value of the parameter. For the enumerated type this value is the value assigned to current enum item not the item index.
[in] | hcam | Camera handle returned from pl_cam_open. |
[in] | param_id | ID of the parameter to get or set (PARAM_...). |
[in] | param_value | Value to get or set. |