USB 2.0 USB 3.x GigE |
USB 2.0 USB 3.x GigE |
Syntax
INT is_ImageFormat (HIDS hCam, UINT nCommand, void *pParam, UINT nSizeOfParam)
Description
Using is_ImageFormat(), you can query a list of possible image sizes (profiles) and set a new profile. This is useful for sensors that do not support a free selection of the area of interest or image format. Using the AOI, binning/subsampling or scaling functions, the driver sets the selected image size to achieve the best possible image quality. The aim here is to achieve the lowest possible data rate with a maximum field of view. For a complete list of available image profiles see Camera and sensor data.
The nCommand input parameter is used to select the function mode. The pParam input parameter depends on the selected function mode. If you select functions for setting or returning a value, pParam contains a pointer to a variable of the UINT type. The size of the memory area to which pParam refers is specified in the nSizeOfParam input parameter.
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 IMAGE_FORMAT_LIST list
UINT |
nSizeOfListEntry |
Must be preset with the size of a list entry in bytes |
UINT |
nNumListElements |
Must be preset with the number of list entries (from IMGFRMT_CMD_GET_NUM_ENTRIES) |
UINT |
nReserved[4] |
Reserved |
IMAGE_FORMAT_INFO |
FormatInfo[0] |
First entry in the list. After having been filled by IMGFRMT_CMD_GET_LIST, the list contains additional entries FormatInfo[1]…FormatInfo[nNumListElements-1]. |
Contents of the list entry IMAGE_FORMAT_INFO
INT |
nFormatID |
Format ID of the specified profile |
UINT |
nWidth |
Width of the area of interest |
UINT |
nHeight |
Height of the area of interest |
INT |
nX0 |
Start point of the area of interest (X) |
INT |
nY0 |
Start point of the area of interest (Y) |
UINT |
nSupportedCaptureModes |
Image capture modes supported for this format (see table below) |
UINT |
nBinningMode |
Binning mode used |
UINT |
nSubsamplingMode |
Subsampling mode used |
IS_CHAR |
strFormatName[64] |
Description of the format |
double |
dSensorScalerFactor |
Scaling factor used (only sensors that support scaling). |
UINT |
nReserved[24] |
Reserved |
Possible values for CAPTUREMODE
CAPTMODE_SINGLE |
Freerun mode, single frame (freerun snap) |
CAPTMODE_FREERUN |
Freerun mode, continuous (freerun live) |
CAPTMODE_TRIGGER_SOFT_SINGLE |
Software triggered mode, single frame |
CAPTMODE_TRIGGER_SOFT_CONTINUOUS |
Software triggered mode, continuous |
CAPTMODE_TRIGGER_HW_SINGLE |
Hardware triggered mode, single frame |
CAPTMODE_TRIGGER_HW_CONTINUOUS |
Hardware triggered mode, continuous |
For further information on the image capture modes, see also in the Basics: Operating modes chapter.
Return values
IS_CANT_ADD_TO_SEQUENCE |
The image memory is already included in the sequence and cannot be added again. |
IS_BAD_STRUCTURE_SIZE |
An internal structure has an incorrect size. |
IS_CANT_COMMUNICATE_WITH_DRIVER |
Communication with the driver failed because no driver has been loaded. |
IS_CANT_OPEN_DEVICE |
An attempt to initialize or select the camera failed (no camera connected or initialization error). |
IS_CAPTURE_RUNNING |
A capturing operation is in progress and must be terminated first. |
IS_DR_CANNOT_CREATE_SURFACE |
The image surface or overlay surface could not be created. |
IS_DR_CANNOT_CREATE_TEXTURE |
The texture could not be created. |
IS_DR_CANNOT_CREATE_VERTEX_BUFFER |
The vertex buffer could not be created. |
IS_DR_DEVICE_OUT_OF_MEMORY |
Not enough graphics memory available. |
IS_DR_LIBRARY_NOT_FOUND |
The DirectRenderer library could not be found. |
IS_INVALID_BUFFER_SIZE |
The image memory has an inappropriate size to store the image in the desired format. |
IS_INVALID_CAMERA_TYPE |
The camera type defined in the .ini file does not match the current camera model. |
IS_INVALID_CAPTURE_MODE |
The function can not be executed in the current camera operating mode (free run, trigger or standby). |
IS_INVALID_CAMERA_HANDLE |
Invalid camera handle |
IS_INVALID_MEMORY_POINTER |
Invalid pointer or invalid memory ID |
IS_INVALID_MODE |
Camera is in standby mode, function not allowed |
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_INVALID_PIXEL_CLOCK |
This setting is not available for the currently set pixel clock frequency. |
IS_IO_REQUEST_FAILED |
An IO request from the uEye driver failed. Possibly the versions of the ueye_api.dll (API) and the driver file (ueye_usb.sys or ueye_eth.sys) do not match. |
IS_NO_ACTIVE_IMG_MEM |
No active image memory available. You must set the memory to active using the is_SetImageMem() function or create a sequence using the is_AddToSequence() function. |
IS_NO_SUCCESS |
General error message |
IS_NOT_CALIBRATED |
The camera does not contain any calibration data. |
IS_NOT_SUPPORTED |
The camera model used here does not support this function or setting. |
IS_NULL_POINTER |
Invalid array |
IS_OUT_OF_MEMORY |
No memory could be allocated. |
IS_SEQUENCE_BUF_ALREADY_LOCKED |
The memory could not be locked. The pointer to the buffer is invalid. |
IS_SUCCESS |
Function executed successfully |
IS_TIMED_OUT |
A timeout occurred. An image capturing process could not be terminated within the allowable period. |
IS_TRIGGER_ACTIVATED |
The function cannot be used because the camera is waiting for a trigger signal. |
Related functions
HIDS hCam;
char strCamFileName[256];
int nRet;
// Get number of available formats and size of list
UINT count;
UINT bytesNeeded = sizeof(IMAGE_FORMAT_LIST);
nRet = is_ImageFormat(hCam, IMGFRMT_CMD_GET_NUM_ENTRIES, &count, sizeof(count));
bytesNeeded += (count - 1) * sizeof(IMAGE_FORMAT_INFO);
void* ptr = malloc(bytesNeeded);
// Create and fill list
IMAGE_FORMAT_LIST* pformatList = (IMAGE_FORMAT_LIST*) ptr;
pformatList->nSizeOfListEntry = sizeof(IMAGE_FORMAT_INFO);
pformatList->nNumListElements = count;
nRet = is_ImageFormat(hCam, IMGFRMT_CMD_GET_LIST, pformatList, bytesNeeded);
// Prepare for creating image buffers
char* pMem = NULL;
int memID = 0;
// Set each format and then capture an image
IMAGE_FORMAT_INFO formatInfo;
for (int i = 0; i < count; i++)
{
formatInfo = pformatList->FormatInfo[i];
int width = formatInfo.nWidth;
int height = formatInfo.nHeight;
// Allocate image mem for current format, set format
nRet = is_AllocImageMem(hCam, width, height, 24, &pMem, &memID);
nRet = is_SetImageMem(hCam, pMem, memID);
nRet = is_ImageFormat(hCam, IMGFRMT_CMD_SET_FORMAT, &formatInfo.nFormatID, sizeof(formatInfo.nFormatID));
// Capture image
nRet = is_FreezeVideo(hCam, IS_WAIT);
}