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

Detailed Description

Function Documentation

◆ pl_cam_close()

rs_bool PV_DECL pl_cam_close ( int16 hcam )

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.

Parameters

[in] hcam Camera handle returned from pl_cam_open.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_cam_open, pl_pvcam_init, pl_pvcam_uninit

Note: pl_pvcam_uninit automatically calls the pl_cam_close on all cameras opened by the current user.

◆ pl_cam_deregister_callback()

rs_bool PV_DECL pl_cam_deregister_callback	(	int16	hcam,
		int32	callback_event
	)

Uninstalls a function for camera system event.

Use this API call to uninstall a function for the specified camera system event.

Parameters

[in]	hcam	Camera handle returned from pl_cam_open.
[in]	callback_event	Callback event to register for (see PL_CALLBACK_EVENT).

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_cam_register_callback, pl_cam_register_callback_ex, pl_cam_register_callback_ex2, pl_cam_register_callback_ex3.

Note: Only PL_CALLBACK_BOF and PL_CALLBACK_EOF are fully supported by all camera types. Do not use other callback types in generic-purpose software. See callback descriptions section under pl_cam_register_callback_ex3 for details.

◆ pl_cam_get_name()

rs_bool PV_DECL pl_cam_get_name	(	int16	cam_num,
		char *	camera_name
	)

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.

Parameters

[in]	cam_num	Camera number Range: 0 through (`totl_cams-1`).
[out]	camera_name	Text name assigned to a camera (with RSConfig).

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_cam_get_total, pl_cam_open, pl_cam_close

Note: This call reports the names of all cameras on the system, even if all the cameras are not available. If the hardware is turned off, or if another user has a camera open, the camera name is reported, but the camera will not be available. pl_cam_get_name returns a name, and pl_cam_open gives information on availability of that camera. To build a complete list of every camera on the system, it is necessary to cycle through all the entries as shown below:
int total_cameras;
char name[CAM_NAME_LEN];
...
pl_cam_get_total(&total_cameras);
for (i = 0; i < total_cameras; i++) {
pl_cam_get_name(i, name);
printf("Camera %d is called '%s'\n", i, name);
}

◆ pl_cam_get_total()

rs_bool PV_DECL pl_cam_get_total ( int16 * totl_cams )

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.

Parameters

[out] totl_cams Total number of cameras in the system.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_cam_get_name, pl_cam_open, pl_cam_close

Note: This function actually searches for all device drivers on the system, without checking hardware. The list of cameras is obtained during pl_pvcam_init. Thus, if a new camera (new device driver) is added after the library was opened, the system won't know that the new camera is there. The system will also not notice if a camera is removed. (Obviously, this is only important on multi-tasking systems). A cycle of uninit / init regenerates the list of available cameras, updating the system for any additions or deletions.

◆ pl_cam_open()

rs_bool PV_DECL pl_cam_open	(	char *	camera_name,
		int16 *	hcam,
		int16	o_mode
	)

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_cam_get_name, pl_cam_get_total, pl_cam_close, pl_pvcam_init, pl_pvcam_uninit

Warning: Despite the above paragraph, a successful pl_cam_open does not mean that the camera is in working order. It does mean that you can communicate with the device driver associated with the camera. After a successful pl_cam_open, call pl_error_message, which reports any error conditions.

◆ pl_cam_register_callback_ex3()

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.

Example of Callback function:

void EOFCallbackHandler(FRAME_INFO* pFrameInfo, void* pContext)
{
    const int32 frameNr = pFrameInfo->FrameNr;
    const long64 frameTime = pFrameInfo->TimeStamp;
    const int16 camID = pFrameInfo->hCam;
    // Display or process frame info etc.
    if (*(int16*)pContext == hCamera1)
        EOFCountCamera1++;
    else if (*(int16*)pContext == hCamera2)
        EOFCountCamera2++;
}

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_cam_deregister_callback

Warning: pl_exp_finish_seq must be called if acquiring in sequential mode (using pl_exp_setup_seq and pl_exp_start_seq) with callbacks notification after all frames are read out and before new exposure is started by calling pl_exp_start_seq. Not all callbacks will be available for all camera systems/interfaces.

Note: Only PL_CALLBACK_BOF and PL_CALLBACK_EOF are fully supported by all camera types. Do not use other callback types in generic-purpose software.

◆ pl_create_frame_info_struct()

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.

Parameters

[out] new_frame Frame info struct to be returned.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_release_frame_info_struct, pl_exp_get_latest_frame_ex, pl_exp_get_oldest_frame_ex, pl_exp_check_cont_status_ex, pl_cam_register_callback_ex2, pl_cam_register_callback_ex3

◆ pl_create_smart_stream_struct()

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.

Parameters

[out]	array	Created struct to be returned.
[in]	entries	Number of entries to be in smart stream struct.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_release_smart_stream_struct

◆ pl_enum_str_length()

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.

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_get_enum_param

Note: This function can be used to determine the amount of memory to allocate for the descriptive string when calling the pl_get_enum_param function. Using the example in pl_get_enum_param, the length returned would be 5 (4 printable characters plus 1 null character).

◆ pl_error_code()

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: The current error code. Note that a call to pl_error_code does not reset the error code.

See also: pl_error_message

Note: pl_error_code works even before pl_pvcam_init is called. This allows a message to be returned if pl_pvcam_init fails.

Warning: The PVCAM library does not intercept signals. Errors that interrupt the normal process (divide by zero, etc.) may cause the software to crash, and pl_error_code may or may not contain useful information.

◆ pl_error_message()

rs_bool PV_DECL pl_error_message	(	int16	err_code,
		char *	msg
	)

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.

Parameters

[in]	err_code	Unique ID of the error: returned from pl_error_code.
[out]	msg	Text description of err_code.

Returns: Returns PV_OK if a message corresponding to the input code is found, PV_FAIL if the code does not have a corresponding message (msg will be filled with the string "Unknown error"). Even if a PV_FAIL is returned, the value of pl_error_code is not altered.

See also: pl_error_code

Note: pl_error_message works even before pl_pvcam_init is called. This allows a message to be printed if pl_pvcam_init fails. All error messages are standalone sentences without ending period having error code name appended in parenthesis.

◆ pl_exp_abort()

rs_bool PV_DECL pl_exp_abort	(	int16	hcam,
		int16	cam_state
	)

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.

Parameters

[in]	hcam	Camera handle returned from pl_cam_open.
[out]	cam_state	State to set the camera in (CCS_NO_CHANGE,...).

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

Note: This may also be called outside of an exposure. It can explicitly open the shutter, close the shutter, or stop the CCS. In the idle state, the system takes the least possible amount of action when image data arrives. On some systems, this involves placing the hardware in reset state, so it is inactive. On SCSI systems, the driver does not initiate any data transfers, although a buffer on the camera end may be filling up. If the CCS is halted and the shutter is closed (CCS_HALT_CLOSE_SHTR), the current image remains on the sensor (although dark charge continues to accumulate). If 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.

◆ pl_exp_check_cont_status()

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_exp_setup_cont, pl_exp_start_cont, pl_exp_get_oldest frame, pl_exp_get_latest_frame, pl_exp_unlock_oldest_frame, pl_exp_stop_cont

Note: This function only returns meaningful results if a continuous readout from the camera has been initiated by a call to pl_exp_start_cont. Use the parameter ID PARAM_CIRC_BUFFER with pl_get_param to check to see if the system can perform circular buffer operations.

◆ pl_exp_check_cont_status_ex()

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_exp_setup_cont, pl_exp_start_cont, pl_exp_get_oldest_frame, pl_exp_get_latest_frame, pl_exp_unlock_oldest_frame, pl_exp_stop_cont, pl_create_frame_info_struct, pl_exp_get_latest_frame_ex, pl_exp_get_oldest_frame_ex

Note: This function only returns meaningful results if a continuous readout from the camera has been initiated by a call to pl_exp_start_cont. Use the parameter ID PARAM_CIRC_BUFFER with pl_get_param to check to see if the system can perform circular buffer operations. Variable pointed to by frame_info must be created with pl_create_frame_info_struct.

◆ pl_exp_check_status()

rs_bool PV_DECL pl_exp_check_status	(	int16	hcam,
		int16 *	status,
		uns32 *	bytes_arrived
	)

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_exp_setup_seq, pl_exp_start_seq

◆ pl_exp_finish_seq()

rs_bool PV_DECL pl_exp_finish_seq	(	int16	hcam,
		void *	pixel_stream,
		int16	hbuf
	)

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_exp_abort, pl_exp_check_status, pl_exp_setup_seq, pl_exp_start_seq

Note: This function must also be called if acquiring in sequential mode (using pl_exp_setup_seq and pl_exp_start_seq) with callback notification after a frame is read out and before new exposure is started by calling pl_exp_start_seq.

◆ pl_exp_get_latest_frame()

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.

Parameters

[in]	hcam	Camera handle returned from pl_cam_open.
[out]	frame	Pointer to the most recent frame.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_exp_setup_cont, pl_exp_start_cont, pl_exp_check_cont_status, pl_exp_stop_cont

Note: If the camera in use is not able to return the latest frame for the current operating mode, this function will fail. For example, some cameras cannot return the latest frame in CIRC_NO_OVERWRITE mode. Use the parameter ID PARAM_CIRC_BUFFER with pl_get_param to check to see if the system can perform circular buffer operations.

◆ pl_exp_get_latest_frame_ex()

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.

Parameters

[in]	hcam	Camera handle returned from pl_cam_open.
[out]	frame	Pointer to the most recent frame.
[out]	frame_info	Frame info struct pointer.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_exp_setup_cont, pl_exp_start_cont, pl_exp_check_cont_status, pl_exp_stop_cont, pl_exp_get_oldest_frame_ex, pl_exp_check_cont_status_ex, pl_cam_register_callback_ex2, pl_create_frame_info_struct, pl_release_frame_info_struct

Note: If the camera in use is not able to return the latest frame for the current operating mode, this function will fail. For example, some cameras cannot return the latest frame in CIRC_NO_OVERWRITE mode. Use the parameter ID PARAM_CIRC_BUFFER with pl_get_param to check to see if the system can perform circular buffer operations. Variable pointed to by frame_info must be created with pl_create_frame_info_struct.

◆ pl_exp_get_oldest_frame()

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.

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.

Parameters

[in]	hcam	Camera handle returned from pl_cam_open.
[out]	frame	Pointer to the oldest unretrieved frame.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_exp_setup_cont, pl_exp_start_cont, pl_exp_check_cont_status, pl_exp_unlock_oldest_frame, pl_exp_stop_cont, pl_exp_get_oldest_frame_ex

Note: If the camera in use is not able to return the oldest frame for the current operating mode, this function will fail. For example, some cameras cannot return the oldest frame in CIRC_OVERWRITE mode. Use the parameter ID PARAM_CIRC_BUFFER with pl_get_param to check to see if the system can perform circular buffer operations.

◆ pl_exp_get_oldest_frame_ex()

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

Parameters

[in]	hcam	Camera handle returned from pl_cam_open.
[out]	frame	Pointer to the oldest unretrieved frame.
[out]	frame_info	Frame info struct pointer.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_exp_setup_cont, pl_exp_start_cont, pl_exp_check_cont_status, pl_exp_unlock_oldest_frame, pl_exp_stop_cont, pl_exp_check_cont_status_ex, pl_cam_register_callback_ex2, pl_create_frame_info_struct, pl_release_frame_info_struct

Note: If the camera in use is not able to return the oldest frame for the current operating mode, this function will fail. For example, some cameras cannot return the oldest frame in CIRC_OVERWRITE mode. Use the parameter ID PARAM_CIRC_BUFFER with pl_get_param to check to see if the system can perform circular buffer operations. Variable pointed to by frame_info must be created with pl_create_frame_info_struct.

◆ pl_exp_setup_cont()

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_exp_start_cont, pl_exp_check_cont_status, pl_exp_get_oldest_frame, pl_exp_get_latest_frame, pl_exp_unlock_oldest_frame, pl_exp_stop_cont

Note: Use the parameter ID PARAM_CIRC_BUFFER with pl_get_param to see if the system can perform circular buffer operations. The circular buffer is passed to pl_exp_start_cont. The buffer is allocated by your application.

◆ pl_exp_setup_seq()

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_exp_abort, pl_exp_check_status, pl_exp_start_seq, pl_exp_finish_seq

Note: This function uploads new settings to the camera. After receiving the settings, the camera merely waits in an idle state. The pl_exp_abort command may be used to place the camera into some other state, such as continuous clearing, but this will not alter or affect the uploaded settings. Essentially, the camera is still holding the exposure sequence and waiting to start, while it clears the sensor charge. Also please note that PVCAM internally checks whether configuration needs to be sent to the camera. If there is no difference in the camera configuration from the previous "setup" and other acquisition parameters have not changed meanwhile, the PVCAM will not resend the configuration. This may lead to shorter execution times of this function and faster start of the subsequent acquisition.

◆ pl_exp_start_cont()

rs_bool PV_DECL pl_exp_start_cont	(	int16	hcam,
		void *	pixel_stream,
		uns32	size
	)

Begins continuous readout into circular buffer.

This function will initiate a continuous readout from the camera into a circular buffer.

Parameters

[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`).

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_exp_setup_cont, pl_exp_check_cont_status, pl_exp_get_oldest_frame, pl_exp_get_latest_frame, pl_exp_unlock_oldest_frame, pl_exp_stop_cont

Note: If pixel_stream points to a buffer that is not an integer-multiple of the frame size for the exposure, this function will return PV_FAIL and set an appropriate error code in pl_error_code. For example, a buffer size of 1000 bytes with a frame size of 250 bytes is OK, but a buffer size of 900 bytes would cause a failure. Use the parameter ID PARAM_CIRC_BUFFER with pl_get_param to check to see if the system can perform circular buffer operations.

◆ pl_exp_start_seq()

rs_bool PV_DECL pl_exp_start_seq	(	int16	hcam,
		void *	pixel_stream
	)

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.

Parameters

[in]	hcam	Camera handle returned from pl_cam_open.
[out]	pixel_stream	Buffer to hold image(s).

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_exp_check_status, pl_exp_setup_seq, pl_exp_finish_seq

◆ pl_exp_stop_cont()

rs_bool PV_DECL pl_exp_stop_cont	(	int16	hcam,
		int16	cam_state
	)

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.

Parameters

[in]	hcam	Camera handle returned from pl_cam_open.
[out]	cam_state	State to set the camera in (CCS_NO_CHANGE,...).

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_exp_setup_cont, pl_exp_start_cont, pl_exp_check_cont_status, pl_exp_get_oldest_frame, pl_exp_get_latest_frame, pl_exp_unlock_oldest_frame

Note: Use the parameter ID PARAM_CIRC_BUFFER with pl_get_param to check to see if the system can perform circular buffer operations.

◆ pl_exp_trigger()

rs_bool PV_DECL pl_exp_trigger	(	int16	hcam,
		uns32 *	flags,
		uns32	value
	)

Sends a software trigger to the device.

In order to use the software trigger, following preconditions must be met:

Acquisition has been configured via a call to pl_exp_setup_seq or pl_exp_setup_cont using one of the software triggering modes (
See also
PL_EXPOSURE_MODES).
Acquisition has been started via pl_exp_start_seq or pl_exp_start_cont.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

Remarks: In current implementation the input flags should be set to 0. On output, the flags will contain one of the values defined in PL_SW_TRIG_STATUSES enumeration.

See also: pl_exp_setup_seq, pl_exp_start_seq, pl_exp_setup_cont, pl_exp_start_cont, pl_exp_check_cont_status, pl_exp_get_oldest_frame, pl_exp_get_latest_frame, pl_exp_unlock_oldest_frame, pl_exp_abort

◆ pl_exp_unlock_oldest_frame()

rs_bool PV_DECL pl_exp_unlock_oldest_frame ( int16 hcam )

Makes oldest frame in circular buffer overwritable.

This function allows PVCAM to overwrite the oldest frame in the circular buffer.

Parameters

[in] hcam Camera handle returned from pl_cam_open.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_exp_setup_cont, pl_exp_start_cont, pl_exp_check_cont_status, pl_exp_get_oldest_frame, pl_exp_unlock_oldest_frame, pl_exp_stop_cont

Note: Failure to call this function after using the frame will cause the continuous acquisition progress to halt eventually, because the frame cannot be overwritten when it is locked. Use the parameter ID PARAM_CIRC_BUFFER with pl_get_param to check to see if the system can perform circular buffer operations.

◆ pl_get_enum_param()

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_get_param, pl_set_param, pl_enum_str_length

Note: The user should call the pl_get_param function with the attribute ATTR_TYPE, to verify that the parameter ID is an enumerated data type before calling the pl_get_enum_param. The user should also call the pl_get_param function with the attribute ATTR_COUNT to determine how many valid enumerated values the parameter ID has. Example: Suppose there is a parameter for camera readout speed. This parameter can be set to 1MHz, 5MHz or 10MHz with the appropriate values 1, 5 and 10. If the readout speed is currently set to 5MHz, a call to pl_get_param with ATTR_CURRENT returns a value of 5. A call to pl_get_enum_param for the readout speed parameter at index 1 (the second item) returns the enumerated type 5MHz with the value equal to 5 and the desc would contain "5MHz".

◆ pl_get_param()

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_set_param, pl_get_enum_param

Note: The data type of param_value is documented in pvcam.h for each param_id.

◆ pl_io_clear_script_control()

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.

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.

Parameters

[in] hcam Camera handle returned from pl_cam_open.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_io_script_control

◆ pl_io_script_control()

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.

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_io_clear_script_control

◆ pl_md_create_frame_struct()

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.

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.

Parameters

[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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

◆ pl_md_create_frame_struct_cont()

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.

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

◆ pl_md_frame_decode()

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.

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

◆ pl_md_frame_recompose()

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

◆ pl_md_read_extended()

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

◆ pl_md_release_frame_struct()

rs_bool PV_DECL pl_md_release_frame_struct ( md_frame * pFrame )

Releases the md_frame struct.

Parameters

[in] pFrame A pointer to the previously allocated structure.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

◆ pl_pp_reset()

rs_bool PV_DECL pl_pp_reset ( int16 hcam )

This function will reset all post-processing modules to their default values.

Parameters

[in] hcam Camera handle returned from pl_cam_open.

Warning: Fails if post-processing modules are not available in the current camera or if hcam is not the handle of an open camera.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: PARAM_PP_FEAT_NAME, PARAM_PP_PARAM_INDEX, PARAM_PP_PARAM_NAME, PARAM_PP_PARAM, PARAM_PP_FEAT_ID, PARAM_PP_PARAM_ID

◆ pl_pvcam_get_ver()

rs_bool PV_DECL pl_pvcam_get_ver ( uns16 * pvcam_version )

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.

Parameters

[out] pvcam_version Version number of PVCAM installer.

Returns: PV_OK for success, PV_FAIL for failure. Failure sets pl_error_code.

See also: PARAM_DD_VERSION

◆ pl_pvcam_init()

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

Note: If this call fails, pl_error_code contains the code that lists the reason for failure.

See also: pl_pvcam_uninit, pl_cam_open, pl_error_code

◆ pl_pvcam_uninit()

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.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_pvcam_init, pl_cam_close, pl_error_code

Warning: If the hardware is involved in acquiring data, the system may not be able to disconnect immediately.

◆ pl_release_frame_info_struct()

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.

Parameters

[in] frame_to_delete Frame info struct to be released.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_create_frame_info_struct, pl_exp_get_latest_frame_ex, pl_exp_get_oldest_frame_ex, pl_exp_check_cont_status_ex, pl_cam_register_callback_ex2, pl_cam_register_callback_ex3

◆ pl_release_smart_stream_struct()

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.

Parameters

[in] array Struct to be released.

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_create_smart_stream_struct

◆ pl_set_param()

rs_bool PV_DECL pl_set_param	(	int16	hcam,
		uns32	param_id,
		void *	param_value
	)

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.

Parameters

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

Returns: PV_OK for success, PV_FAIL for a failure. Failure sets pl_error_code.

See also: pl_get_param, pl_get_enum_param

Note: The data type of param_value is documented in pvcam.h for each param_id. It can be retrieved using the pl_get_param function, using the ATTR_TYPE attribute. The user should call the pl_get_param function with the attribute ATTR_ACCESS, to verify that the parameter ID is writable (settable) before calling the pl_set_param function.

Functions

Detailed Description

Function Documentation

◆ pl_cam_close()

◆ pl_cam_deregister_callback()

◆ pl_cam_get_name()

◆ pl_cam_get_total()

◆ pl_cam_open()

◆ pl_cam_register_callback_ex3()

Example of Callback function:

◆ pl_create_frame_info_struct()

◆ pl_create_smart_stream_struct()

◆ pl_enum_str_length()

◆ pl_error_code()

◆ pl_error_message()

◆ pl_exp_abort()

◆ pl_exp_check_cont_status()

◆ pl_exp_check_cont_status_ex()

◆ pl_exp_check_status()

◆ pl_exp_finish_seq()

◆ pl_exp_get_latest_frame()

◆ pl_exp_get_latest_frame_ex()

◆ pl_exp_get_oldest_frame()

◆ pl_exp_get_oldest_frame_ex()

◆ pl_exp_setup_cont()

◆ pl_exp_setup_seq()

◆ pl_exp_start_cont()

◆ pl_exp_start_seq()

◆ pl_exp_stop_cont()

◆ pl_exp_trigger()

◆ pl_exp_unlock_oldest_frame()

◆ pl_get_enum_param()

◆ pl_get_param()

◆ pl_io_clear_script_control()

◆ pl_io_script_control()

◆ pl_md_create_frame_struct()

◆ pl_md_create_frame_struct_cont()

◆ pl_md_frame_decode()

◆ pl_md_frame_recompose()

◆ pl_md_read_extended()

◆ pl_md_release_frame_struct()

◆ pl_pp_reset()

◆ pl_pvcam_get_ver()

◆ pl_pvcam_init()

◆ pl_pvcam_uninit()

◆ pl_release_frame_info_struct()

◆ pl_release_smart_stream_struct()

◆ pl_set_param()