HALCON Reference Manual 10.0.2

set_framegrabber_callbackset_framegrabber_callbackset_framegrabber_callbackSetFramegrabberCallbackSetFramegrabberCallback (Operator)

Name

set_framegrabber_callbackset_framegrabber_callbackset_framegrabber_callbackSetFramegrabberCallbackSetFramegrabberCallback — Register a callback function for an image acquisition device.

Signature

set_framegrabber_callback( : : AcqHandle, CallbackType, CallbackFunction, UserContext : )

The operator set_framegrabber_callbackset_framegrabber_callbackset_framegrabber_callbackSetFramegrabberCallbackSetFramegrabberCallback registers a callback function for the image acquisition device specified by AcqHandleAcqHandleAcqHandleAcqHandleacqHandle. The parameter CallbackFunctionCallbackFunctionCallbackFunctionCallbackFunctioncallbackFunction contains a pointer to the function to register, while CallbackTypeCallbackTypeCallbackTypeCallbackTypecallbackType specifies to which function of the underlying API the callback should be connected.

'exception':: The image acquisition has raised an exception.
'exposure_end':: The exposure of the next image has been finished.
'exposure_start':: The exposure of the next image has been started.
'transfer_end':: A new image is ready to be fetched by grab_image_asyncgrab_image_asyncgrab_image_asyncGrabImageAsyncGrabImageAsync.

Depending on the functionality of the underlying API, additional values for CallbackTypeCallbackTypeCallbackTypeCallbackTypecallbackType are possible. All actually supported callback types of a specific image acquisition device can be queried by calling get_framegrabber_paramget_framegrabber_paramget_framegrabber_paramGetFramegrabberParamGetFramegrabberParam with the parameter 'available_callback_types'. For more details see the documentation of the specific image acquisition interface.

Once the callback is registered, on every occurrence of the underlying event (e.g., the notification that the exposure has finished) the specified callback function CallbackFunctionCallbackFunctionCallbackFunctionCallbackFunctioncallbackFunction will be called. If CallbackFunctionCallbackFunctionCallbackFunctionCallbackFunctioncallbackFunction is set to NULL, the corresponding callback will be unregistered.

On Windows systems, the signature of the callback function is the following:

Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext)

On Linux/UNIX systems the signature of the callback function is the following:

Herror *HAcqCallback(void *AcqHandle, void *Context, void *UserContext)

The first parameter of the callback function contains the handle to the image acquisition device passed in AcqHandleAcqHandleAcqHandleAcqHandleacqHandle, the second one provides a pointer to interface-specific context data, and the third parameter is a user-specific pointer that is specified in UserContextUserContextUserContextUserContextuserContext.

Parallelization

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Processed without parallelization.

Parameters

AcqHandleAcqHandleAcqHandleAcqHandleacqHandle (input_control) framegrabber → (integer)

Handle of the acquisition device to be used.

CallbackTypeCallbackTypeCallbackTypeCallbackTypecallbackType (input_control) string → (string)

Callback type.

Default value: 'transfer_end' "transfer_end" "transfer_end" "transfer_end" "transfer_end"

Suggested values: 'exception'"exception""exception""exception""exception", 'exposure_end'"exposure_end""exposure_end""exposure_end""exposure_end", 'exposure_start'"exposure_start""exposure_start""exposure_start""exposure_start", 'transfer_end'"transfer_end""transfer_end""transfer_end""transfer_end"

CallbackFunctionCallbackFunctionCallbackFunctionCallbackFunctioncallbackFunction (input_control) pointer → (integer)

Pointer to the callback function to be set.

UserContextUserContextUserContextUserContextuserContext (input_control) pointer → (integer)

Pointer to user-specific context data.

Result

If the image acquisition device is open and the specified callback was registered successfully, the operator set_framegrabber_callbackset_framegrabber_callbackset_framegrabber_callbackSetFramegrabberCallbackSetFramegrabberCallback returns the value 2 (H_MSG_TRUE). Otherwise an exception is raised.