Please enable JavaScript to view this site.

IDS Software Suite 4.96.1

Windows_Logo
Linux_Logo

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.

hint_info

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.

Global event IDs

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)

Device-spcific event IDs

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

is_EnableMessage()

Example

// 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)
}

© 2022 IDS Imaging Development Systems GmbH