Image and Frame Handling Functions

The eSDK API provides the following image and frame handling functions:

• EVT_CameraQueueFrame – Place an image buffer into the frame queue
• EVT_CameraGetFrame – Get a frame from the camera
• EVT_FrameConvert – Convert a frame using the provided parameters
• EVT_AllocateFrameBuffer – Allocate memory for the image
• EVT_ReleaseFrameBuffer – Release memory allocated with EVT_AllocateFrameBuffer
• EVT_FrameSave – Save image to file in the selected format

For information about other types of eSDK API functions, see the eSDK API Functons Overview.

‍

‍EVT_CameraQueueFrame

Description: Places an image buffer into the frame queue.

Prototype:

EVT_ERROR EVT_CameraQueueFrame(
   CEmergentCamera* camera,
   CEmergentFrame* frame
);

‍

‍Parameters:

• camera: Camera handle.
• frame: Camera image frame to queue.

Return Values:

• EVT_SUCCESS
• EVT_ERROR_INVAL
• EVT_GENERAL_ERROR

Usage Example:

EVT_CameraQueueFrame(camera, &frame);

‍

EVT_CameraGetFrame

Description: Retrieves a frame from the camera. Blocks the calling thread until the frame is received.

Prototype:

EVT_ERROR EVT_CameraGetFrame(
   CEmergentCamera* camera,
   CEmergentFrame* frame,
   int milliseconds
);

‍

Parameters:

• camera: Camera handle.
• frame: Image frame from the camera.
• milliseconds: Time to wait in milliseconds. Use EVT_INFINITE to block indefinitely.

Return Values:

• EVT_SUCCESS
• EVT_ERROR_INVAL
• EVT_ERROR_AGAIN
• EVT_ERROR_INTR
• EVT_ERROR_NOMEM
• EVT_GENERAL_ERROR

Usage Example:

EVT_CameraGetFrame(camera, &frame, EVT_INFINITE);

‍

EVT_FrameConvert

Description: Converts a frame using the provided parameters.

Prototype:

EVT_ERROR EVT_FrameConvert(
   CEmergentFrame* frameSrc,
   CEmergentFrame* frameDst,
   int convertBitDepth,
   int convertColor
);

‍

Parameters:

• frameSrc: Image frame to convert.
• frameDst: Image frame result.
• convertBitDepth: Defines conversion of bits per pixel. Can be one of the following:
  • EVT_CONVERT_NONE
  • EVT_CONVERT_8BIT
• convertColor: Defines color conversion. Can be one of the following:
  • EVT_COLOR_CONVERT_NONE
  • EVT_COLOR_CONVERT_NEARESTNEIGHBOR_RGB
  • EVT_COLOR_CONVERT_NEARESTNEIGHBOR_BGR
  • EVT_COLOR_CONVERT_BILINEAR_RGB
  • EVT_COLOR_CONVERT_BILINEAR_BGR
  • EVT_COLOR_CONVERT_TO_RGB
  • EVT_COLOR_CONVERT_TO_BGR

Return Values:

• EVT_SUCCESS
• EVT_GENERAL_ERROR

Usage Example:

EVT_FrameConvert(&frameSrc, &frameDst, EVT_CONVERT_8BIT, EVT_COLOR_CONVERT_TO_RGB);

‍

EVT_AllocateFrameBuffer

Description: Allocates memory for the image.

Prototype:

EVT_ERROR EVT_AllocateFrameBuffer(
   CEmergentCamera* camera,
   CEmergentFrame* frame,
   int buffer_type
);

‍

Parameters:

• camera: Camera handle.
• frame: Image frame object.
• buffer_type: Can be one of the following:
  • EVT_FRAME_BUFFER_DEFAULT
  • EVT_FRAME_BUFFER_ZERO_COPY

Return Values:

• EVT_SUCCESS
• EVT_ERROR_NOT_SUPPORTED
• EVT_ERROR_INVAL
• EVT_ERROR_NOMEM
• EVT_GENERAL_ERROR

Usage Example:

EVT_AllocateFrameBuffer(camera, &frame, EVT_FRAME_BUFFER_ZERO_COPY);

Note: Use EVT_FRAME_BUFFER_ZERO_COPY for high-efficiency image data transfer. For other operations like frame conversion, use EVT_FRAME_BUFFER_DEFAULT.

EVT_ReleaseFrameBuffer

Description: Releases memory previously allocated with EVT_AllocateFrameBuffer.

Prototype:

EVT_ERROR EVT_ReleaseFrameBuffer(
   CEmergentCamera* camera,
   CEmergentFrame* frame
);

‍

Parameters:

• camera: Camera handle.
• frame: Image frame from the camera.

Return Values:

• EVT_SUCCESS
• EVT_GENERAL_ERROR

Usage Example:

EVT_ReleaseFrameBuffer(camera, &frame);

‍

EVT_FrameSave

Description: Saves an image to a file in the selected format.

Prototype:

EVT_ERROR EVT_FrameSave(
   CEmergentFrame* frame,
   char* filename,
   int filetype,
   int align
);

‍

Parameters:

• frame: Image frame to save to a file.
• filename: File name for the saved file.
• filetype: Format to save the image. Can be one of the following:
  • EVT_FILETYPE_RAW
  • EVT_FILETYPE_BMP
  • EVT_FILETYPE_TIF
• align: Alignment setting for pixel data (e.g., EVT_ALIGN_LEFT).

Return Values:

• EVT_SUCCESS
• EVT_ERROR_INVAL
• EVT_ERROR_IO
• EVT_GENERAL_ERROR

Usage Example:

EVT_FrameSave(&frame, "image.tif", EVT_FILETYPE_TIF, EVT_ALIGN_LEFT);