IDS Software Suite 4.96.1
 |
 |
|---|---|
USB 2.0 USB 3.x GigE |
USB 2.0 USB 3.x GigE |
Syntax
INT is_Event(HIDS hCam, UINT nCommand, void *pParam, UINT nSizeOfParam)
Description
Using is_Event(), event objects are registered, managed and waited for their signaling.
|
Event handling for images If you use the event handling to signal new images from the camera, it may occur under high system load that the event-based application does not receive a signal for every image. This is because the event concept does not provide that several events of the same type are stored. If due to system load more than one image is signaled before the application is ready (e.g. WaitForSingleObject), you have no option to capture these missed events. |
Input parameters
hCam |
Camera handle |
pParam |
Pointer to a function parameter, whose function depends on nCommand. |
nSizeOfParam |
Size (in bytes) of the memory area to which pParam refers. |
Contents of the IS_INIT_EVENT structure
UINT |
nEvent |
ID of the event object that is being initialized. |
BOOL |
bManualReset |
Flag for the behaviour after signalling: •TRUE: an event object is registered which must be manually reset to the "not signalled" state by the user using the IS_EVENT_CMD_RESET command. •FALSE: an event object is registered, which is automatically reset to the "not signalled" state by the system after signalling. |
BOOL |
bInitialState |
Flag for the state of the event object after initialization and registration: •TRUE: an event object is registered that is in the "signaled" state. •FALSE: an event object is registered that is in the " not signaled" state. |
Contents of the IS_WAIT_EVENT structure
UINT |
nEvent |
ID of the event object to be waited for. |
|---|---|---|
UINT |
nTimeoutMilliseconds |
Timeout in milliseconds •Timeout ≠ 0: The function waits until the specified event object is signalled or until the specified timeout period has expired. •Timeout = 0: The function returns immediately. •Timeout = INFINITE (i.e. maximum value for a UINT): The function does not return until the event object is signalled. |
UINT |
nSignaled |
If the function returns with IS_SUCCESS, the parameter contains the ID of the signaled event object. |
UINT |
nSetCount |
If the function returns with IS_SUCCESS, the parameter contains the number of signalings of the event object defined by nSignaled since the last query with the IS_EVENT_CMD_WAIT command. |
Contents of the IS_WAIT_EVENTS structure
UINT* |
pEvents |
Pointer (array) to the IDs of the event objects to be waited for. |
UINT |
nCount |
Number of event objects to which the pEvents pointer refers. |
BOOL |
bWaitAll |
Flag for the behavior of the function return when signaling: •TRUE: The function returns when all specified event objects are signalled or until the specified timeout (nTimeoutMilliseconds) has expired. •FALSE: The function returns when at least one of the specified event objects signals or when the specified timeout (nTimeoutMilliseconds) has expired. |
UINT |
nTimeoutMilliseconds |
Timeout in milliseconds •Timeout ≠ 0: The function waits until an event object is signaled or all event objects are signaled (see bWaitAll) or until the specified timeout period has expired. •Timeout = 0: The function returns immediately. •Timeout = INFINITE (i.e. maximum value for a UINT): The function returns if an event object is signaled or all event objects are signaled (see bWaitAll). |
UINT |
nSignaled |
If the function returns with IS_SUCCESS, the parameter contains depending on the bWaitAll parameter: •bWaitAll = TRUE: an undefined value •bWaitAll = FALSE: the ID of the signaled event object |
UINT |
nSetCount |
If the function returns with IS_SUCCESS, the parameter contains the number of signalings of the event object defined by nSignaled since the last query with the IS_EVENT_CMD_WAIT command. |
IS_SET_EVENT_NEW_DEVICE |
A camera was newly connected. This is independent of the device handle (hCam is ignored). |
IS_SET_EVENT_NEW_DEVICE_ETH |
A GigE camera was newly connected. This is independent of the device handle (hCam is ignored). |
IS_SET_EVENT_NEW_DEVICE_USB |
An USB camera was newly connected. This is independent of the device handle (hCam is ignored). |
IS_SET_EVENT_REMOVAL |
A camera was removed. This is independent of the device handle (hCam is ignored). |
IS_SET_EVENT_REMOVAL_ETH |
A GigE camera was removed. This is independent of the device handle (hCam is ignored). |
IS_SET_EVENT_REMOVAL_USB |
An USB camera was removed. This is independent of the device handle (hCam is ignored). |
IS_SET_EVENT_STATUS_CHANGED |
Linux only: The availability of a camera has changed, e.g. an available camera was opened. This is independent of the device handle (hCam is ignored). |
IS_SET_EVENT_STATUS_CHANGED_ETH |
Linux only: The availability of a GigE camera has changed, e.g. an available camera was opened. This is independent of the device handle (hCam is ignored). |
IS_SET_EVENT_STATUS_CHANGED_USB |
Linux only: The availability of an USB camera has changed, e.g. an available camera was opened. This is independent of the device handle (hCam is ignored). |
IS_SET_EVENT_USER_DEFINED_BEGIN … IS_SET_EVENT_USER_DEFINED_END |
User-defined events: these events are at the free disposal of the user (see example) |
IS_SET_EVENT_AUTOBRIGHTNESS_FINISHED |
The automatic brightness control in the run-once mode is completed. |
IS_SET_EVENT_AUTOFOCUS_FINISHED |
Automatic focus control is finished (see is_Focus()). |
IS_SET_EVENT_CAMERA_MEMORY |
In the camera memory mode an image acquisition iteration is finished (see is_ImageBuffer()). |
IS_SET_EVENT_CAPTURE_STATUS |
There is an information about image capturing available. This information can be requested by is_CaptureStatus(). Note that this event replaces the former IS_SET_EVENT_TRANSFER_FAILED from previous versions. |
IS_SET_EVENT_CONNECTIONSPEED_CHANGED |
The connection speed of a USB 3.x camera has been reduced to USB 2.0 speed or has been increased. |
IS_SET_EVENT_DEVICE_PLUGGED_IN |
Requirement: the camera is operated in trusted pairing mode (see is_Configuration()). An already paired GigE uEye camera was reconnected to the network. |
IS_SET_EVENT_DEVICE_UNPLUGGED |
Requirement: the camera is operated in trusted pairing mode (see is_Configuration()). A paired GigE uEye camera was disconnected from the network. |
IS_SET_EVENT_DEVICE_RECONNECTED |
A camera initialized with is_InitCamera() and disconnected afterwards was reconnected. |
IS_SET_EVENT_END_OF_EXPOSURE |
The exposure is finished. This event is triggered after the sensor exposure time has expired. The time between the exposure end and the software event signal is typically < 1 ms. The event is triggered before the IS_SET_EVENT_FIRST_PACKET_RECEIVED event, as image transfer to the PC is not yet complete when the IS_SET_EVENT_END_OF_EXPOSURE event is transmitted. The event has the restrictions that it is only supported in trigger mode and only by global shutter models of the following camera families (see is_DeviceFeature()): •GigE uEye CP Rev. 2 •GigE uEye FA •GigE uEye SE Rev. 4 •USB 3 uEye CP Rev. 2 (not for models with Sony sensors / UI-3590CP Rev. 2) •USB 3 uEye CP •USB 3 uEye LE •uEye LE USB 3.1 Gen 1 (not for UI-359xLE Rev. 2) •uEye SE USB 3.1 Gen 1 (not for models with Sony sensors) |
IS_SET_EVENT_EXTTRIG |
An image which was captured following the arrival of a trigger has been transferred completely. This is the earliest possible moment for a new capturing process. The image must then be post-processed by the driver and will be available after the IS_SET_EVENT_FRAME processing event. |
IS_SET_EVENT_FIRST_PACKET_RECEIVED |
The first data packet of the image was transferred to the PC. |
IS_SET_EVENT_FRAME |
A new image is available. |
IS_SET_EVENT_FRAME_RECEIVED |
This event is signaled when a new image has arrived in the API before the post-processing is performed. |
IS_SET_EVENT_FRAME_SKIPPED |
The event is signaled when an image was discarded (see is_CaptureConfiguration()). |
IS_SET_EVENT_OVERLAY_DATA_LOST |
Direct3D/OpenGL mode: Because of a re-programming the parameters of the overlay are invalid. The overlay must be draw new. |
IS_SET_EVENT_PMC_IMAGE_PARAMS_CHANGED |
Multicast mode: The master has changed camera parameters which affect the data format like image size or color format. The client must reconfigure the virtual camera. |
IS_SET_EVENT_REMOVE |
A camera initialized with is_InitCamera() was removed. |
IS_SET_EVENT_SEQ |
The sequence is completed (see is_AddToSequence() / Event/message handling). |
IS_SET_EVENT_STEAL |
An image extracted from the overlay is available (see is_DirectRenderer()). |
IS_SET_EVENT_TEMPERATURE_STATUS |
USB 3 uEye CP Rev. 2/GigE uEye CP Rev. 2/GigE uEye FA/GigE uEye SE Rev. 4 only: The temperature state of the camera has changed, see Querying the temperature state |
IS_SET_EVENT_WB_FINISHED |
The automatic white balance control is completed (see Automatic image control). |
Return values
IS_ACCESS_VIOLATION |
An access violation has occurred. |
IS_INVALID_PARAMETER |
One of the submitted parameters is outside the valid range or is not supported for this sensor or is not available in this mode. |
IS_NO_SUCCESS |
General error message |
IS_OUT_OF_MEMORY |
No memory could be allocated. |
IS_SUCCESS |
Function executed successfully |
IS_TIMED_OUT |
A timeout occurred. An image capturing process could not be terminated within the allowable period. The specified timeout time has expired without an event object being signaled. |
Related functions
// to read fluently
#define IS_SET_EVENT_THREAD_STOP IS_SET_EVENT_USER_DEFINED_BEGIN
// init camera ...
// init / enable
IS_INIT_EVENT init_events[] = {{IS_SET_EVENT_FRAME, TRUE, FALSE}, {IS_SET_EVENT_THREAD_STOP, TRUE, FALSE}};
INT ret = is_Event(cam, IS_EVENT_CMD_INIT, init_events, sizeof(init_events));
if (IS_SUCCESS == ret)
{
UINT events[] = {IS_SET_EVENT_FRAME, IS_SET_EVENT_THREAD_STOP};
ret = is_Event(cam, IS_EVENT_CMD_ENABLE, events, sizeof(events));
// start thread and run installed event_handler (here: thread_proc) ...
...
// ... do something in main thread ...
...
// ... signal 'stop thread' ...
is_Event(cam, IS_EVENT_CMD_SET, &events[1], sizeof(UINT));
// ... wait for thread termination!!!
...
is_Event(cam, IS_EVENT_CMD_DISABLE, events, sizeof(events))
is_Event(cam, IS_EVENT_CMD_EXIT, events, sizeof(events));
}
void thread_proc(HIDS cam)
{
// wait / reset
UINT events[] = {IS_SET_EVENT_FRAME, IS_SET_EVENT_THREAD_STOP};
IS_WAIT_EVENTS wait_events = {events, 2, FALSE, 1000, 0, 0};
do
{
INT ret = is_Event(cam, IS_EVENT_CMD_WAIT, &wait_events, sizeof(wait_events));
if ((IS_SUCCESS == ret) && (IS_SET_EVENT_FRAME == wait_events.nSignaled))
{
// for example: show frame
// ...
// ... reset event, because 'bManualReset = TRUE'
is_Event(cam, IS_EVENT_CMD_RESET, &events[0], sizeof(UINT));
}
else if (IS_TIMED_OUT == ret)
{
// do something ...
}
}
while (IS_SET_EVENT_THREAD_STOP != wait_events.nSignaled)
}
