cvsCamCtrl Library

1. Overview#

cvsCamCtrl is a virtual frame grabber library provided by CREVIS. This document is a programmer's guide organized based on the attached cvsCamCtrl.h header, covering the API, constants, structures, enumerations, feature metadata query functions, and module-based extended register access functions.

1.1 Document Basis#

• Header-first principle: Function signatures, types, default values, and enum/struct definitions are based primarily on the declarations in the attached cvsCamCtrl.h.

A typical basic usage sequence is as follows.

ST_InitSystem();
ST_UpdateDevice();            // or ST_UpdateDeviceWithTimeout()
ST_OpenDevice(...);
ST_InitBuffer(...);

/* Continuous acquisition */
ST_AcqStart(hDevice);
ST_GrabImage(...);           // or ST_GrabImageAsync(...)
ST_AcqStop(hDevice);

/* Single-shot acquisition */
ST_SingleGrabImage(...);

ST_FreeBuffer(...);
ST_CloseDevice(hDevice);
ST_FreeSystem();

1.2 Header Revision History#

2. Definitions and Constants#

This section describes event IDs, error codes, device information constants, XML versions, visibility levels, module identification macros, and bit fields used to compose color conversion codes.

2.1 Event Definitions#

Events are divided into Grab events and device events. Grab events occur during the image acquisition flow, while device events occur when the device state or interface state changes.

2.1.1 Grab Events#

2.1.2 Device Events#

Some events are supported only on specific interfaces. Based on the header comments, interface scope is distinguished by GEV, U3V, or CXP-related attributes.

2.2 Error Code Definitions#

In general, 0 indicates success and negative values indicate errors.

2.3 Device Information Definitions#

Device information constants are used to specify the type of information to query in ST_GetEnumDeviceInfo().

2.4 XML Versions#

2.5 Parameter Visibility#

2.6 Module Identification Macros#

The header also defines macros for module identification. In module-based extended APIs, the separate CvsModuleType enumeration is typically used.

2.7 Color Conversion Bit-Field Definitions#

ConvertColor values are composed by combining the bit-field constants below.

3. Structure Definitions#

3.1 CVS_IMAGE Structure#

This structure stores the basic properties of image data.

Definition

typedef struct _cvsImage
{
	int32_t width;    /**< The image width in pixels. */
	int32_t height;    /**< The image height in pixels. */
	int32_t step;    /**< The number of bytes per image row. */
	int32_t channels;    /**< The number of channels per pixel. */
	void* pImage;    /**< Pointer to the image memory. */
} CVS_IMAGE;

Fields

3.2 CVS_BUFFER Structure#

This structure stores the grab result buffer and metadata.

Definition

typedef struct _cvsBuffer
{
	bool isAllocated;    /**< Indicates whether the buffer memory is allocated. */
	uint64_t blockID;    /**< The block ID of the buffer. */
	uint64_t timestamp;    /**< The timestamp of the buffer. */
	uint32_t size;    /**< The size of the buffer in bytes. */
	CVS_IMAGE image;    /**< The image data contained in the buffer. */
} CVS_BUFFER;

Fields

3.3 CVS_EVENT Structure#

This structure stores the ID, timestamp, and data pointer of a device event.

Definition

typedef struct _cvsEvent
{
	int id;    /**< The event ID. */
	uint64_t timestamp;    /**< The event timestamp. */
	const void* data;    /**< Pointer to the event data. */
	uint32_t dataLength;    /**< The length of the event data in bytes. */
} CVS_EVENT;

Fields

3.4 CVS_FEATURE Structure#

This is a summary structure used when enumerating the feature list.

Definition

typedef struct _cvsFeature
{
	char name[256];    /**< The feature name. */
	char category[256];    /**< The parent category name. */
	CvsFeatureType type;    /**< The feature type. */
} CVS_FEATURE;

Fields

3.5 CVS_FEATURE_INFO Structure#

This metadata structure is commonly used across all feature types.

Definition

typedef struct _cvsFeatureInfo
{
	char name[256];    /**< The feature name. */
	char displayName[256];    /**< The display name of the feature. */
	char toolTip[512];    /**< The tooltip text of the feature. */
	char description[512];    /**< The description of the feature. */
	CvsAccessMode accessMode;    /**< The access mode of the feature. */
	bool isReadable;    /**< Indicates whether the feature is readable. */
	bool isWritable;    /**< Indicates whether the feature is writable. */
	CvsVisibility visibility;    /**< The visibility level of the feature. */
} CVS_FEATURE_INFO;

Fields

3.6 CVS_FEATURE_INTEGER_INFO Structure#

This structure contains the current value and range information of an integer feature.

Definition

typedef struct _cvsFeatureIntegerInfo
{
	CVS_FEATURE_INFO common;    /**< Common feature information. */
	int64_t value;    /**< The current value of the integer feature. */
	int64_t min;    /**< The minimum value of the integer feature. */
	int64_t max;    /**< The maximum value of the integer feature. */
	int64_t inc;    /**< The increment value of the integer feature. */
	CvsRepresentation representation;    /**< The representation of the integer feature. */
	char unit[64];    /**< The unit of the integer feature. */
} CVS_FEATURE_INTEGER_INFO;

Fields

3.7 CVS_FEATURE_FLOAT_INFO Structure#

This structure contains the current value and range information of a floating-point feature.

Definition

typedef struct _cvsFeatureFloatInfo
{
	CVS_FEATURE_INFO common;    /**< Common feature information. */
	double value;    /**< The current value of the float feature. */
	double min;    /**< The minimum value of the float feature. */
	double max;    /**< The maximum value of the float feature. */
	CvsRepresentation representation;    /**< The representation of the float feature. */
	char unit[64];    /**< The unit of the float feature. */
} CVS_FEATURE_FLOAT_INFO;

Fields

3.8 CVS_FEATURE_BOOLEAN_INFO Structure#

This structure contains the current value of a Boolean feature.

Definition

typedef struct _cvsFeatureBooleanInfo
{
	CVS_FEATURE_INFO common;    /**< Common feature information. */
	bool value;    /**< The current value of the boolean feature. */
} CVS_FEATURE_BOOLEAN_INFO;

Fields

3.9 CVS_FEATURE_STRING_INFO Structure#

This structure contains the current value of a string feature.

Definition

typedef struct _cvsFeatureStringInfo
{
	CVS_FEATURE_INFO common;    /**< Common feature information. */
	char value[512];    /**< The current value of the string feature. */
} CVS_FEATURE_STRING_INFO;

Fields

3.10 CVS_FEATURE_ENUMERATION_INFO Structure#

This structure contains the current string/integer value and the number of entries of an enumeration feature.

Definition

typedef struct _cvsFeatureEnumerationInfo
{
	CVS_FEATURE_INFO common;    /**< Common feature information. */
	char currentValue[256];    /**< The current string value of the enumeration feature. */
	int64_t currentIntValue;    /**< The current integer value of the enumeration feature. */
	int32_t entryCount;    /**< The number of available enumeration entries. */
} CVS_FEATURE_ENUMERATION_INFO;

Fields

3.11 CVS_FEATURE_ENUM_ENTRY_INFO Structure#

This structure contains detailed metadata for an individual enumeration entry.

Definition

typedef struct _cvsFeatureEnumEntryInfo
{
	int32_t intValue;    /**< The integer value of the enumeration entry. */
	char stringValue[256];    /**< The string value of the enumeration entry. */
	char displayName[256];    /**< The display name of the enumeration entry. */
	char description[512];    /**< The description of the enumeration entry. */
	CvsAccessMode accessMode;    /**< The access mode of the enumeration entry. */
	CvsVisibility visibility;    /**< The visibility level of the enumeration entry. */
} CVS_FEATURE_ENUM_ENTRY_INFO;

Fields

3.12 CVS_FEATURE_COMMAND_INFO Structure#

This structure contains common metadata for a command feature.

Definition

typedef struct _cvsFeatureCommandInfo
{
	CVS_FEATURE_INFO common;    /**< Common feature information. */
} CVS_FEATURE_COMMAND_INFO;

Fields

4. Enumeration Definitions#

4.1 Color Conversion (enum ConvertColor)#

ST_CvtColor() uses these color conversion codes. The values are bit fields composed of source pixel format, bit depth, packing mode, output color space, and filter information.

The color conversion codes can be grouped as follows.

4.1.1 Basic RGB/BGR Conversion

4.1.2 Bayer 8-bit

4.1.3 Bayer 8-bit + 3x3

4.1.4 Bayer 10-bit

4.1.5 Bayer 10-bit + 3x3

4.1.6 Bayer 10-bit Packed

4.1.7 Bayer 10-bit Packed + 3x3

4.1.8 Bayer 12-bit

4.1.9 Bayer 12-bit + 3x3

4.1.10 Bayer 12-bit Packed

4.1.11 Bayer 12-bit Packed + 3x3

4.1.12 YUV Conversion

4.1.13 Mono Bit Reduction

4.2 Module Types (enum CvsModuleType)#

This enumeration is used to specify the target module in the extended register/feature API.

4.3 Feature Types (enum CvsFeatureType)#

This enumeration indicates the data type of a feature node.

4.4 Access Permissions (enum CvsAccessType)#

This enumeration defines the access permissions used when opening a device.

4.5 Access Modes (enum CvsAccessMode)#

This enumeration indicates the readable/writable state of a feature.

4.6 Visibility (enum CvsVisibility)#

This enumeration indicates the UI visibility level of a feature.

4.7 Representation (enum CvsRepresentation)#

This enumeration indicates how numeric/logical values are displayed in the UI.

5. Functions#

This section describes the entire API, including callbacks, system management, device connection, grab operations, register control, feature queries, file I/O, and buffer management.

The examples below are minimal usage examples in C++. hDevice refers to a valid handle obtained after ST_OpenDevice() succeeds, and the example node names (Width, ExposureTime, PixelFormat, DeviceUserID, etc.) may vary depending on the actual device XML/GenICam feature configuration. For string query functions, check the actual buffer size first using a two-pass approach when necessary.

5.1 Callback Function Definitions#

These are the callback function types provided by the library.

5.1.1 GrabCallback#

This callback function type is invoked when a Grab event occurs.

Type

typedef void (WINAPI* GrabCallback)(int32_t eventID, const CVS_BUFFER* pBuffer, void* pUserDefine);

Parameters

Return Value

• None (void)

Example

void WINAPI OnGrab(int32_t eventID, const CVS_BUFFER* pBuffer, void* pUserDefine)
{
    if (eventID == EVENT_NEW_IMAGE && pBuffer != nullptr)
    {
        printf("frame: %d x %d, blockID=%llu\n",
               pBuffer->image.width,
               pBuffer->image.height,
               (unsigned long long)pBuffer->blockID);
    }
}

5.1.2 EventCallback#

This callback function type is invoked when a device event occurs.

Type

typedef void (WINAPI* EventCallback)(const CVS_EVENT* pEvent, void* pUserDefine);

Parameters

Return Value

• None (void)

Example

void WINAPI OnDeviceEvent(const CVS_EVENT* pEvent, void* pUserDefine)
{
    if (pEvent == nullptr)
        return;

    printf("eventID=%d, timestamp=%llu, payload=%u bytes\n",
           pEvent->id,
           (unsigned long long)pEvent->timestamp,
           pEvent->dataLength);
}

5.2 System Management#

These functions are related to system initialization, release, and initialization state checking.

5.2.1 ST_InitSystem#

Initializes the system.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_InitSystem();

Parameters

None

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

CVS_ERROR err = ST_InitSystem();
if (err != MCAM_ERR_OK)
{
    printf("ST_InitSystem failed: %d\n", err);
}

5.2.2 ST_FreeSystem#

Releases system resources.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_FreeSystem();

Parameters

None

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

CVS_ERROR err = ST_FreeSystem();
if (err != MCAM_ERR_OK)
{
    printf("ST_FreeSystem failed: %d\n", err);
}

5.2.3 ST_IsInitSystem#

Checks whether the system has been initialized.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_IsInitSystem(bool* pFlag);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

bool initialized = false;
CVS_ERROR err = ST_IsInitSystem(&initialized);
if (err == MCAM_ERR_OK)
{
    printf("initialized = %s\n", initialized ? "true" : "false");
}

5.3 Device Discovery and Information Query#

These functions are related to device discovery, enumeration, interface queries, and basic information queries.

5.3.1 ST_GetAvailableCameraNum#

Queries the number of available cameras.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetAvailableCameraNum(uint32_t* pNum);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

// Prerequisite: Call ST_UpdateDevice() or ST_UpdateDeviceWithTimeout() first.
uint32_t cameraCount = 0;
CVS_ERROR err = ST_GetAvailableCameraNum(&cameraCount);
if (err == MCAM_ERR_OK)
{
    printf("cameraCount = %u\n", cameraCount);
}

5.3.2 ST_UpdateDevice#

Refreshes the device list.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_UpdateDevice();

Parameters

None

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Notes

• Starting from revision 1.1.2, ST_UpdateDevice() and ST_UpdateDeviceWithTimeout() were separated.

Example

CVS_ERROR err = ST_UpdateDevice();
if (err != MCAM_ERR_OK)
{
    printf("ST_UpdateDevice failed: %d\n", err);
}

5.3.3 ST_UpdateDeviceWithTimeout#

Refreshes the device list with a specified timeout.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_UpdateDeviceWithTimeout(uint32_t uTimeout);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

uint32_t timeoutMs = 3000;
CVS_ERROR err = ST_UpdateDeviceWithTimeout(timeoutMs);
if (err != MCAM_ERR_OK)
{
    printf("ST_UpdateDeviceWithTimeout failed: %d\n", err);
}

5.3.4 ST_GetEnumDeviceID#

Queries the device ID of the specified enumeration index.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetEnumDeviceID(uint32_t EnumNum, char* pDeviceID, uint32_t* pSize);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

uint32_t enumIndex = 0;
char deviceID[256] = {};
uint32_t size = sizeof(deviceID);

CVS_ERROR err = ST_GetEnumDeviceID(enumIndex, deviceID, &size);
if (err == MCAM_ERR_OK)
{
    printf("deviceID = %s\n", deviceID);
}

5.3.5 ST_GetEnumDeviceInfo#

Queries the device information of the specified enumeration index.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetEnumDeviceInfo(uint32_t EnumNum, int32_t DeviceInfoCmd, char* pDeviceInfo, uint32_t* pSize);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

uint32_t enumIndex = 0;
char modelName[256] = {};
uint32_t size = sizeof(modelName);

CVS_ERROR err = ST_GetEnumDeviceInfo(
    enumIndex,
    MCAM_DEVICEINFO_MODEL_NAME,
    modelName,
    &size
);

if (err == MCAM_ERR_OK)
{
    printf("modelName = %s\n", modelName);
}

5.3.6 ST_GetEnumInterface#

Queries the interface of the specified enumeration index.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetEnumInterface(uint32_t EnumNum, char* pInterface, uint32_t* pSize);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

uint32_t enumIndex = 0;
char interfaceName[64] = {};
uint32_t size = sizeof(interfaceName);

CVS_ERROR err = ST_GetEnumInterface(enumIndex, interfaceName, &size);
if (err == MCAM_ERR_OK)
{
    printf("interface = %s\n", interfaceName);
}

5.4 Device Connection and Control#

These functions are related to device connection, open-state checking, and interface queries.

5.4.1 ST_IsConnectable#

Checks whether the device is connectable.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_IsConnectable(uint32_t EnumNum, bool* pFlag);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

uint32_t enumIndex = 0;
bool connectable = false;

CVS_ERROR err = ST_IsConnectable(enumIndex, &connectable);
if (err == MCAM_ERR_OK)
{
    printf("connectable = %s\n", connectable ? "true" : "false");
}

5.4.2 ST_OpenDevice#

Opens the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_OpenDevice(uint32_t EnumNum, int32_t* hDevice, bool isDetailedLog = false);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

uint32_t enumIndex = 0;
int32_t hDevice = 0;

CVS_ERROR err = ST_OpenDevice(enumIndex, &hDevice, false);
if (err == MCAM_ERR_OK)
{
    printf("hDevice = %d\n", hDevice);
}

5.4.3 ST_OpenDeviceMulticast#

Opens the device in multicast mode.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_OpenDeviceMulticast(uint32_t EnumNum, int32_t* hDevice, CvsAccessType AccessType, const char* IPAddress, uint32_t DataPort, bool isDetailedLog = false);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Notes

• IPAddress is used as the multicast group address or the destination IP address.
• If DataPort is 0, the library may select an appropriate port.
• Based on the header comments, AccessControl permission can be held by only one control node.
• In a multicast environment, network equipment may require IGMP Snooping to be configured.

Example

uint32_t enumIndex = 0;
int32_t hDevice = 0;

CVS_ERROR err = ST_OpenDeviceMulticast(
    enumIndex,
    &hDevice,
    AccessReadOnly,
    "239.192.1.1",
    1042,
    false
);

if (err == MCAM_ERR_OK)
{
    printf("multicast open success, hDevice = %d\n", hDevice);
}

5.4.4 ST_IsOpenDevice#

Checks whether the device is open.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_IsOpenDevice(int32_t hDevice, bool* pFlag);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
bool isOpen = false;

CVS_ERROR err = ST_IsOpenDevice(hDevice, &isOpen);
if (err == MCAM_ERR_OK)
{
    printf("isOpen = %s\n", isOpen ? "true" : "false");
}

5.4.5 ST_CloseDevice#

Closes the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_CloseDevice(int32_t hDevice);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_ERROR err = ST_CloseDevice(hDevice);
if (err != MCAM_ERR_OK)
{
    printf("ST_CloseDevice failed: %d\n", err);
}

5.4.6 ST_GetInterface#

Queries the device interface.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetInterface(int32_t hDevice, char* pInterface, uint32_t* pSize);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
char interfaceName[64] = {};
uint32_t size = sizeof(interfaceName);

CVS_ERROR err = ST_GetInterface(hDevice, interfaceName, &size);
if (err == MCAM_ERR_OK)
{
    printf("interface = %s\n", interfaceName);
}

5.5 Image Acquisition and Configuration#

These functions are related to starting/stopping image acquisition and configuring Grab behavior.

5.5.1 ST_AcqStart#

Starts acquisition on the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_AcqStart(int32_t hDevice);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
// Prerequisite: If necessary, initialize the buffer with ST_InitBuffer() and register callbacks first.
CVS_ERROR err = ST_AcqStart(hDevice);
if (err != MCAM_ERR_OK)
{
    printf("ST_AcqStart failed: %d\n", err);
}

5.5.2 ST_AcqStop#

Stops acquisition on the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_AcqStop(int32_t hDevice);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
// Prerequisite: Acquisition has been started with ST_AcqStart().
CVS_ERROR err = ST_AcqStop(hDevice);
if (err != MCAM_ERR_OK)
{
    printf("ST_AcqStop failed: %d\n", err);
}

5.5.3 ST_DoAbortGrab#

Aborts an ongoing Grab on the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_DoAbortGrab(int32_t hDevice);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
// Prerequisite: A Grab is pending or acquisition is in progress.
CVS_ERROR err = ST_DoAbortGrab(hDevice);
if (err != MCAM_ERR_OK)
{
    printf("ST_DoAbortGrab failed: %d\n", err);
}

5.5.4 ST_SetGrabTimeout#

Sets the device Grab timeout.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetGrabTimeout(int32_t hDevice, uint32_t Timeout);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
uint32_t timeoutMs = 2000;

CVS_ERROR err = ST_SetGrabTimeout(hDevice, timeoutMs);
if (err != MCAM_ERR_OK)
{
    printf("ST_SetGrabTimeout failed: %d\n", err);
}

5.5.5 ST_GetGrabTimeout#

Queries the device Grab timeout.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetGrabTimeout(int32_t hDevice, uint32_t* pTimeout);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
uint32_t timeoutMs = 0;

CVS_ERROR err = ST_GetGrabTimeout(hDevice, &timeoutMs);
if (err == MCAM_ERR_OK)
{
    printf("grab timeout = %u ms\n", timeoutMs);
}

5.5.6 ST_SetBufferCount#

Sets the number of internal device buffers.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetBufferCount(int32_t hDevice, uint32_t BufferCount);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
uint32_t bufferCount = 8;

CVS_ERROR err = ST_SetBufferCount(hDevice, bufferCount);
if (err != MCAM_ERR_OK)
{
    printf("ST_SetBufferCount failed: %d\n", err);
}

5.5.7 ST_GetBufferCount#

Queries the number of internal device buffers.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetBufferCount(int32_t hDevice, uint32_t* pBufferCount);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
uint32_t bufferCount = 0;

CVS_ERROR err = ST_GetBufferCount(hDevice, &bufferCount);
if (err == MCAM_ERR_OK)
{
    printf("bufferCount = %u\n", bufferCount);
}

5.6 Image Processing and Status Check#

These functions are related to checking image acquisition results and querying statistics.

5.6.1 ST_GrabImage#

Grabs an image from the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GrabImage(int32_t hDevice, CVS_BUFFER* pBuffer);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Notes

• Use this while ST_AcqStart() is active.
• It is safer to initialize the buffer first with ST_InitBuffer() before calling this.

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_BUFFER buffer = {};

if (ST_InitBuffer(hDevice, &buffer, 0) == MCAM_ERR_OK &&
    ST_AcqStart(hDevice) == MCAM_ERR_OK)
{
    CVS_ERROR err = ST_GrabImage(hDevice, &buffer);
    if (err == MCAM_ERR_OK)
    {
        printf("grabbed: %d x %d\n", buffer.image.width, buffer.image.height);
    }

    ST_AcqStop(hDevice);
    ST_FreeBuffer(&buffer);
}

5.6.2 ST_GrabImageAsync#

Grabs an image asynchronously from the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GrabImageAsync(int32_t hDevice, CVS_BUFFER* pBuffer);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Notes

• Asynchronous Grab support was added after version 1.0.7.
• In version 1.1.1, the parameters and behavior of ST_GrabImageAsync() were adjusted.

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_BUFFER buffer = {};

if (ST_InitBuffer(hDevice, &buffer, 0) == MCAM_ERR_OK &&
    ST_AcqStart(hDevice) == MCAM_ERR_OK)
{
    CVS_ERROR err = ST_GrabImageAsync(hDevice, &buffer);
    if (err == MCAM_ERR_OK)
    {
        printf("async image ready: %d x %d\n", buffer.image.width, buffer.image.height);
    }

    ST_AcqStop(hDevice);
    ST_FreeBuffer(&buffer);
}

5.6.3 ST_SingleGrabImage#

Grabs a single image from the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SingleGrabImage(int32_t hDevice, CVS_BUFFER* pBuffer);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Notes

• Use this to acquire a single image without starting continuous acquisition.

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_BUFFER buffer = {};

if (ST_InitBuffer(hDevice, &buffer, 0) == MCAM_ERR_OK)
{
    CVS_ERROR err = ST_SingleGrabImage(hDevice, &buffer);
    if (err == MCAM_ERR_OK)
    {
        printf("single shot: %d x %d\n", buffer.image.width, buffer.image.height);
    }

    ST_FreeBuffer(&buffer);
}

5.6.4 ST_GetImageAvailable#

Checks whether an image is available from the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetImageAvailable(int32_t hDevice, uint32_t* pFlag);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Notes

• The output type is uint32_t*, and in general, a non-zero value indicates that an image is available.

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
// Prerequisite: This is a polling situation after ST_AcqStart().
uint32_t available = 0;

CVS_ERROR err = ST_GetImageAvailable(hDevice, &available);
if (err == MCAM_ERR_OK)
{
    printf("image available = %u\n", available);
}

5.6.5 ST_GetGrabCount#

Queries the Grab count and error count of the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetGrabCount(int32_t hDevice, uint64_t* Count, uint64_t* ErrorCount);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
uint64_t count = 0;
uint64_t errorCount = 0;

CVS_ERROR err = ST_GetGrabCount(hDevice, &count, &errorCount);
if (err == MCAM_ERR_OK)
{
    printf("grabCount=%llu, errorCount=%llu\n",
           (unsigned long long)count,
           (unsigned long long)errorCount);
}

5.6.6 ST_GetFrameRate#

Queries the device frame rate.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetFrameRate(int32_t hDevice, double* FrameRate);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
double frameRate = 0.0;

CVS_ERROR err = ST_GetFrameRate(hDevice, &frameRate);
if (err == MCAM_ERR_OK)
{
    printf("frameRate = %.3f fps\n", frameRate);
}

5.6.7 ST_GetBandwidth#

Queries the device bandwidth.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetBandwidth(int32_t hDevice, double* Bandwidth);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
double bandwidth = 0.0;

CVS_ERROR err = ST_GetBandwidth(hDevice, &bandwidth);
if (err == MCAM_ERR_OK)
{
    printf("bandwidth = %.3f\n", bandwidth);
}

5.6.8 ST_GetLastError#

Queries the device's last error code.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetLastError(int32_t hDevice);

Parameters

Return Value

• The device's last error code (MCAM_ERR_*)

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
// Example: Deliberately use an invalid node name to trigger an error, then check the last error.
(void)ST_SetIntReg(hDevice, "InvalidNodeName", 1);

CVS_ERROR lastError = ST_GetLastError(hDevice);
printf("lastError = %d\n", lastError);

5.6.9 ST_GetLastErrorDescription#

Queries the description string for the device's last error.

Signature

CVS_IMPORT_EXPORT const char* WINAPI ST_GetLastErrorDescription(int32_t hDevice);

Parameters

Return Value

• Description string for the last error

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
// Example: Query the last error string directly.
(void)ST_SetIntReg(hDevice, "InvalidNodeName", 1);

const char* description = ST_GetLastErrorDescription(hDevice);
printf("lastErrorDescription = %s\n", description != nullptr ? description : "(null)");

5.7 Log and Configuration Management#

These functions control whether detailed logging is enabled.

5.7.1 ST_SetDetailedLog#

Sets whether detailed logging is enabled for the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetDetailedLog(int32_t hDevice, bool Flag);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_ERROR err = ST_SetDetailedLog(hDevice, true);
if (err != MCAM_ERR_OK)
{
    printf("ST_SetDetailedLog failed: %d\n", err);
}

5.7.2 ST_GetDetailedLog#

Queries whether detailed logging is enabled for the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetDetailedLog(int32_t hDevice, bool* pFlag);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
bool enabled = false;

CVS_ERROR err = ST_GetDetailedLog(hDevice, &enabled);
if (err == MCAM_ERR_OK)
{
    printf("detailedLog = %s\n", enabled ? "true" : "false");
}

5.8 Register Control#

These functions read and write basic register values.

5.8.1 ST_SetIntReg#

Sets an integer register value.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetIntReg(int32_t hDevice, const char* NodeName, int64_t val);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
// Change the node name to match the actual device XML.
CVS_ERROR err = ST_SetIntReg(hDevice, "Width", 1920);
if (err != MCAM_ERR_OK)
{
    printf("ST_SetIntReg failed: %d\n", err);
}

5.8.2 ST_GetIntReg#

Queries an integer register value.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetIntReg(int32_t hDevice, const char* NodeName, int64_t* pVal);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
int64_t value = 0;

CVS_ERROR err = ST_GetIntReg(hDevice, "Width", &value);
if (err == MCAM_ERR_OK)
{
    printf("Width = %lld\n", (long long)value);
}

5.8.3 ST_SetFloatReg#

Sets a floating-point register value.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetFloatReg(int32_t hDevice, const char* NodeName, double fVal);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_ERROR err = ST_SetFloatReg(hDevice, "ExposureTime", 5000.0);
if (err != MCAM_ERR_OK)
{
    printf("ST_SetFloatReg failed: %d\n", err);
}

5.8.4 ST_GetFloatReg#

Queries a floating-point register value.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetFloatReg(int32_t hDevice, const char* NodeName, double* pFval);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
double value = 0.0;

CVS_ERROR err = ST_GetFloatReg(hDevice, "ExposureTime", &value);
if (err == MCAM_ERR_OK)
{
    printf("ExposureTime = %.3f\n", value);
}

5.8.5 ST_SetBoolReg#

Sets a Boolean register value.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetBoolReg(int32_t hDevice, const char* NodeName, bool bVal);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_ERROR err = ST_SetBoolReg(hDevice, "GammaEnable", true);
if (err != MCAM_ERR_OK)
{
    printf("ST_SetBoolReg failed: %d\n", err);
}

5.8.6 ST_GetBoolReg#

Queries a Boolean register value.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetBoolReg(int32_t hDevice, const char* NodeName, bool* pBval);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
bool value = false;

CVS_ERROR err = ST_GetBoolReg(hDevice, "GammaEnable", &value);
if (err == MCAM_ERR_OK)
{
    printf("GammaEnable = %s\n", value ? "true" : "false");
}

5.8.7 ST_SetEnumReg#

Sets an enumeration register value.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetEnumReg(int32_t hDevice, const char* NodeName, const char* val);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_ERROR err = ST_SetEnumReg(hDevice, "PixelFormat", "Mono8");
if (err != MCAM_ERR_OK)
{
    printf("ST_SetEnumReg failed: %d\n", err);
}

5.8.8 ST_GetEnumReg#

Queries an enumeration register value.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetEnumReg(int32_t hDevice, const char* NodeName, char* pInfo, uint32_t* pSize);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
char value[256] = {};
uint32_t size = sizeof(value);

CVS_ERROR err = ST_GetEnumReg(hDevice, "PixelFormat", value, &size);
if (err == MCAM_ERR_OK)
{
    printf("PixelFormat = %s\n", value);
}

5.8.9 ST_SetStrReg#

Sets a string register value.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetStrReg(int32_t hDevice, const char* NodeName, char* val);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Notes

• In the declaration, the input argument type is char*. Follow the header declaration as-is when writing calling code.

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
char userId[] = "LineA_Camera01";

CVS_ERROR err = ST_SetStrReg(hDevice, "DeviceUserID", userId);
if (err != MCAM_ERR_OK)
{
    printf("ST_SetStrReg failed: %d\n", err);
}

5.8.10 ST_GetStrReg#

Queries a string register value.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetStrReg(int32_t hDevice, const char* NodeName, char* pInfo, uint32_t* pSize);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
char value[512] = {};
uint32_t size = sizeof(value);

CVS_ERROR err = ST_GetStrReg(hDevice, "DeviceUserID", value, &size);
if (err == MCAM_ERR_OK)
{
    printf("DeviceUserID = %s\n", value);
}

5.8.11 ST_SetCmdReg#

Executes a command register.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetCmdReg(int32_t hDevice, const char* NodeName);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
// Example node names may vary depending on the device.
CVS_ERROR err = ST_SetCmdReg(hDevice, "UserSetLoad");
if (err != MCAM_ERR_OK)
{
    printf("ST_SetCmdReg failed: %d\n", err);
}

5.9 Register Information Query#

These functions query register ranges and enumeration entry information.

5.9.1 ST_GetIntRegRange#

Queries the range of an integer register.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetIntRegRange(int32_t hDevice, const char* NodeName, int64_t* pMin, int64_t* pMax, int64_t* pInc);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
int64_t minValue = 0;
int64_t maxValue = 0;
int64_t increment = 0;

CVS_ERROR err = ST_GetIntRegRange(hDevice, "Width", &minValue, &maxValue, &increment);
if (err == MCAM_ERR_OK)
{
    printf("Width range: min=%lld, max=%lld, inc=%lld\n",
           (long long)minValue,
           (long long)maxValue,
           (long long)increment);
}

5.9.2 ST_GetFloatRegRange#

Queries the range of a floating-point register.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetFloatRegRange(int32_t hDevice, const char* NodeName, double* pMin, double* pMax);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
double minValue = 0.0;
double maxValue = 0.0;

CVS_ERROR err = ST_GetFloatRegRange(hDevice, "ExposureTime", &minValue, &maxValue);
if (err == MCAM_ERR_OK)
{
    printf("ExposureTime range: min=%.3f, max=%.3f\n", minValue, maxValue);
}

5.9.3 ST_GetEnumEntrySize#

Queries the number of enumeration register entries.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetEnumEntrySize(int32_t hDevice, const char* NodeName, int32_t* pVal);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
int32_t entryCount = 0;

CVS_ERROR err = ST_GetEnumEntrySize(hDevice, "PixelFormat", &entryCount);
if (err == MCAM_ERR_OK)
{
    printf("PixelFormat entryCount = %d\n", entryCount);
}

5.9.4 ST_GetEnumEntryIntValue#

Queries the integer value of an enumeration entry.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetEnumEntryIntValue(int32_t hDevice, const char* NodeName, int32_t EntryIdx, int32_t* pVal);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
int32_t intValue = 0;

CVS_ERROR err = ST_GetEnumEntryIntValue(hDevice, "PixelFormat", 0, &intValue);
if (err == MCAM_ERR_OK)
{
    printf("entry[0].intValue = %d\n", intValue);
}

5.9.5 ST_GetEnumEntryValue#

Queries the string value of an enumeration entry.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetEnumEntryValue(int32_t hDevice, const char* NodeName, int32_t EntryIdx, char* pInfo, uint32_t* pSize);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
char value[256] = {};
uint32_t size = sizeof(value);

CVS_ERROR err = ST_GetEnumEntryValue(hDevice, "PixelFormat", 0, value, &size);
if (err == MCAM_ERR_OK)
{
    printf("entry[0].value = %s\n", value);
}

5.10 Parameter Read and Write#

These are address-based parameter read/write functions.

5.10.1 ST_ReadParam#

Reads parameters from the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_ReadParam(int32_t hDevice, unsigned char* pBuffer, int64_t Address, int64_t Length);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
// Set the address and length according to the actual device manual.
unsigned char buffer[16] = {};
int64_t address = 0x1000;
int64_t length = sizeof(buffer);

CVS_ERROR err = ST_ReadParam(hDevice, buffer, address, length);
if (err == MCAM_ERR_OK)
{
    printf("read %lld bytes from 0x%llX\n",
           (long long)length,
           (long long)address);
}

5.10.2 ST_WriteParam#

Writes parameters to the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_WriteParam(int32_t hDevice, const unsigned char* pBuffer, int64_t Address, int64_t Length);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
// Set the address and data format according to the actual device manual.
unsigned char buffer[4] = {0x01, 0x02, 0x03, 0x04};
int64_t address = 0x1000;
int64_t length = sizeof(buffer);

CVS_ERROR err = ST_WriteParam(hDevice, buffer, address, length);
if (err != MCAM_ERR_OK)
{
    printf("ST_WriteParam failed: %d\n", err);
}

5.11 Extended Register and Parameter Control#

These are module-based extended register/parameter access functions.

5.11.1 ST_SetIntRegEx#

Sets the integer register value of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetIntRegEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, int64_t val);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;

CVS_ERROR err = ST_SetIntRegEx(hDevice, moduleType, "Width", 1920);
if (err != MCAM_ERR_OK)
{
    printf("ST_SetIntRegEx failed: %d\n", err);
}

5.11.2 ST_GetIntRegEx#

Queries the integer register value of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetIntRegEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, int64_t* pVal);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
int64_t value = 0;

CVS_ERROR err = ST_GetIntRegEx(hDevice, moduleType, "Width", &value);
if (err == MCAM_ERR_OK)
{
    printf("Width = %lld\n", (long long)value);
}

5.11.3 ST_SetFloatRegEx#

Sets the floating-point register value of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetFloatRegEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, double fVal);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;

CVS_ERROR err = ST_SetFloatRegEx(hDevice, moduleType, "ExposureTime", 5000.0);
if (err != MCAM_ERR_OK)
{
    printf("ST_SetFloatRegEx failed: %d\n", err);
}

5.11.4 ST_GetFloatRegEx#

Queries the floating-point register value of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetFloatRegEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, double* pFval);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
double value = 0.0;

CVS_ERROR err = ST_GetFloatRegEx(hDevice, moduleType, "ExposureTime", &value);
if (err == MCAM_ERR_OK)
{
    printf("ExposureTime = %.3f\n", value);
}

5.11.5 ST_SetBoolRegEx#

Sets the Boolean register value of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetBoolRegEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, bool bVal);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;

CVS_ERROR err = ST_SetBoolRegEx(hDevice, moduleType, "GammaEnable", true);
if (err != MCAM_ERR_OK)
{
    printf("ST_SetBoolRegEx failed: %d\n", err);
}

5.11.6 ST_GetBoolRegEx#

Queries the Boolean register value of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetBoolRegEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, bool* pBval);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
bool value = false;

CVS_ERROR err = ST_GetBoolRegEx(hDevice, moduleType, "GammaEnable", &value);
if (err == MCAM_ERR_OK)
{
    printf("GammaEnable = %s\n", value ? "true" : "false");
}

5.11.7 ST_SetEnumRegEx#

Sets the enumeration register value of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetEnumRegEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, const char* val);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;

CVS_ERROR err = ST_SetEnumRegEx(hDevice, moduleType, "PixelFormat", "Mono8");
if (err != MCAM_ERR_OK)
{
    printf("ST_SetEnumRegEx failed: %d\n", err);
}

5.11.8 ST_GetEnumRegEx#

Queries the enumeration register value of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetEnumRegEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, char* pInfo, uint32_t* pSize);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
char value[256] = {};
uint32_t size = sizeof(value);

CVS_ERROR err = ST_GetEnumRegEx(hDevice, moduleType, "PixelFormat", value, &size);
if (err == MCAM_ERR_OK)
{
    printf("PixelFormat = %s\n", value);
}

5.11.9 ST_SetStrRegEx#

Sets the string register value of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetStrRegEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, const char* val);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;

CVS_ERROR err = ST_SetStrRegEx(hDevice, moduleType, "DeviceUserID", "LineA_Camera01");
if (err != MCAM_ERR_OK)
{
    printf("ST_SetStrRegEx failed: %d\n", err);
}

5.11.10 ST_GetStrRegEx#

Queries the string register value of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetStrRegEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, char* pInfo, uint32_t* pSize);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
char value[512] = {};
uint32_t size = sizeof(value);

CVS_ERROR err = ST_GetStrRegEx(hDevice, moduleType, "DeviceUserID", value, &size);
if (err == MCAM_ERR_OK)
{
    printf("DeviceUserID = %s\n", value);
}

5.11.11 ST_SetCmdRegEx#

Executes the command register of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_SetCmdRegEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;

// Example node names may vary depending on the device XML.
CVS_ERROR err = ST_SetCmdRegEx(hDevice, moduleType, "UserSetLoad");
if (err != MCAM_ERR_OK)
{
    printf("ST_SetCmdRegEx failed: %d\n", err);
}

5.11.12 ST_GetIntRegRangeEx#

Queries the integer register range of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetIntRegRangeEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, int64_t* pMin, int64_t* pMax, int64_t* pInc);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
int64_t minValue = 0;
int64_t maxValue = 0;
int64_t increment = 0;

CVS_ERROR err = ST_GetIntRegRangeEx(hDevice, moduleType, "Width", &minValue, &maxValue, &increment);
if (err == MCAM_ERR_OK)
{
    printf("Width range: min=%lld, max=%lld, inc=%lld\n",
           (long long)minValue,
           (long long)maxValue,
           (long long)increment);
}

5.11.13 ST_GetFloatRegRangeEx#

Queries the floating-point register range of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetFloatRegRangeEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, double* pMin, double* pMax);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
double minValue = 0.0;
double maxValue = 0.0;

CVS_ERROR err = ST_GetFloatRegRangeEx(hDevice, moduleType, "ExposureTime", &minValue, &maxValue);
if (err == MCAM_ERR_OK)
{
    printf("ExposureTime range: min=%.3f, max=%.3f\n", minValue, maxValue);
}

5.11.14 ST_GetEnumEntrySizeEx#

Queries the number of enumeration register entries of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetEnumEntrySizeEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, int32_t* pVal);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
int32_t entryCount = 0;

CVS_ERROR err = ST_GetEnumEntrySizeEx(hDevice, moduleType, "PixelFormat", &entryCount);
if (err == MCAM_ERR_OK)
{
    printf("PixelFormat entryCount = %d\n", entryCount);
}

5.11.15 ST_GetEnumEntryIntValueEx#

Queries the enumeration entry integer value of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetEnumEntryIntValueEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, int32_t EntryIdx, int32_t* pVal);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
int32_t intValue = 0;

CVS_ERROR err = ST_GetEnumEntryIntValueEx(hDevice, moduleType, "PixelFormat", 0, &intValue);
if (err == MCAM_ERR_OK)
{
    printf("entry[0].intValue = %d\n", intValue);
}

5.11.16 ST_GetEnumEntryValueEx#

Queries the enumeration entry string value of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetEnumEntryValueEx(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, int32_t EntryIdx, char* pInfo, uint32_t* pSize);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
char value[256] = {};
uint32_t size = sizeof(value);

CVS_ERROR err = ST_GetEnumEntryValueEx(hDevice, moduleType, "PixelFormat", 0, value, &size);
if (err == MCAM_ERR_OK)
{
    printf("entry[0].value = %s\n", value);
}

5.11.17 ST_ReadParamEx#

Reads parameters from the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_ReadParamEx(int32_t hDevice, CvsModuleType moduleType, unsigned char* pBuffer, int64_t Address, int64_t Length);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
// Set the address and length according to the actual module register map.
unsigned char buffer[16] = {};
int64_t address = 0x1000;
int64_t length = sizeof(buffer);

CVS_ERROR err = ST_ReadParamEx(hDevice, moduleType, buffer, address, length);
if (err == MCAM_ERR_OK)
{
    printf("read %lld bytes from module %d, address 0x%llX\n",
           (long long)length,
           (int)moduleType,
           (long long)address);
}

5.11.18 ST_WriteParamEx#

Writes parameters to the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_WriteParamEx(int32_t hDevice, CvsModuleType moduleType, const unsigned char* pBuffer, int64_t Address, int64_t Length);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
// Set the address and data format according to the actual module register map.
unsigned char buffer[4] = {0x01, 0x02, 0x03, 0x04};
int64_t address = 0x1000;
int64_t length = sizeof(buffer);

CVS_ERROR err = ST_WriteParamEx(hDevice, moduleType, buffer, address, length);
if (err != MCAM_ERR_OK)
{
    printf("ST_WriteParamEx failed: %d\n", err);
}

5.12 Feature and Metadata Query#

These functions query the feature list, detailed metadata, and feature dependency relationships.

5.12.1 ST_GetFeatureSize#

Queries the number of features in the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetFeatureSize(int32_t hDevice, CvsModuleType moduleType, uint32_t* pFeatureSize);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Notes

• Use CvsModuleType values for moduleType. ModuleRemoteDevice is commonly used for general camera parameter queries.

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
uint32_t featureCount = 0;

CVS_ERROR err = ST_GetFeatureSize(hDevice, moduleType, &featureCount);
if (err == MCAM_ERR_OK)
{
    printf("featureCount = %u\n", featureCount);
}

5.12.2 ST_GetFeatureList#

Queries an item from the feature list of the specified module.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetFeatureList(int32_t hDevice, CvsModuleType moduleType, int32_t index, CVS_FEATURE* pFeatureList);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Notes

• When iterating through the feature list, the usual approach is to check the total count first with ST_GetFeatureSize() and then increment the index.

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
CVS_FEATURE feature = {};

CVS_ERROR err = ST_GetFeatureList(hDevice, moduleType, 0, &feature);
if (err == MCAM_ERR_OK)
{
    printf("name=%s, category=%s, type=%d\n",
           feature.name,
           feature.category,
           (int)feature.type);
}

5.12.3 ST_GetIntFeatureInfo#

Queries detailed information about an integer feature.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetIntFeatureInfo(int32_t hDevice, CvsModuleType moduleType, const char* FeatureName, CVS_FEATURE_INTEGER_INFO* pInfo);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
CVS_FEATURE_INTEGER_INFO info = {};

CVS_ERROR err = ST_GetIntFeatureInfo(hDevice, moduleType, "Width", &info);
if (err == MCAM_ERR_OK)
{
    printf("Width: value=%lld, min=%lld, max=%lld, inc=%lld, unit=%s\n",
           (long long)info.value,
           (long long)info.min,
           (long long)info.max,
           (long long)info.inc,
           info.unit);
}

5.12.4 ST_GetFloatFeatureInfo#

Queries detailed information about a floating-point feature.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetFloatFeatureInfo(int32_t hDevice, CvsModuleType moduleType, const char* FeatureName, CVS_FEATURE_FLOAT_INFO* pInfo);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
CVS_FEATURE_FLOAT_INFO info = {};

CVS_ERROR err = ST_GetFloatFeatureInfo(hDevice, moduleType, "ExposureTime", &info);
if (err == MCAM_ERR_OK)
{
    printf("ExposureTime: value=%.3f, min=%.3f, max=%.3f, unit=%s\n",
           info.value,
           info.min,
           info.max,
           info.unit);
}

5.12.5 ST_GetBoolFeatureInfo#

Queries detailed information about a Boolean feature.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetBoolFeatureInfo(int32_t hDevice, CvsModuleType moduleType, const char* FeatureName, CVS_FEATURE_BOOLEAN_INFO* pInfo);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
CVS_FEATURE_BOOLEAN_INFO info = {};

CVS_ERROR err = ST_GetBoolFeatureInfo(hDevice, moduleType, "GammaEnable", &info);
if (err == MCAM_ERR_OK)
{
    printf("GammaEnable: value=%s, readable=%s, writable=%s\n",
           info.value ? "true" : "false",
           info.common.isReadable ? "true" : "false",
           info.common.isWritable ? "true" : "false");
}

5.12.6 ST_GetStrFeatureInfo#

Queries detailed information about a string feature.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetStrFeatureInfo(int32_t hDevice, CvsModuleType moduleType, const char* FeatureName, CVS_FEATURE_STRING_INFO* pInfo);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
CVS_FEATURE_STRING_INFO info = {};

CVS_ERROR err = ST_GetStrFeatureInfo(hDevice, moduleType, "DeviceUserID", &info);
if (err == MCAM_ERR_OK)
{
    printf("DeviceUserID: value=%s, displayName=%s\n",
           info.value,
           info.common.displayName);
}

5.12.7 ST_GetEnumFeatureInfo#

Queries detailed information about an enumeration feature.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetEnumFeatureInfo(int32_t hDevice, CvsModuleType moduleType, const char* FeatureName, CVS_FEATURE_ENUMERATION_INFO* pInfo);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
CVS_FEATURE_ENUMERATION_INFO info = {};

CVS_ERROR err = ST_GetEnumFeatureInfo(hDevice, moduleType, "PixelFormat", &info);
if (err == MCAM_ERR_OK)
{
    printf("PixelFormat: currentValue=%s, currentIntValue=%lld, entryCount=%d\n",
           info.currentValue,
           (long long)info.currentIntValue,
           info.entryCount);
}

5.12.8 ST_GetCommandFeatureInfo#

Queries detailed information about a command feature.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetCommandFeatureInfo(int32_t hDevice, CvsModuleType moduleType, const char* FeatureName, CVS_FEATURE_COMMAND_INFO* pInfo);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
CVS_FEATURE_COMMAND_INFO info = {};

CVS_ERROR err = ST_GetCommandFeatureInfo(hDevice, moduleType, "UserSetLoad", &info);
if (err == MCAM_ERR_OK)
{
    printf("command displayName=%s, accessMode=%d\n",
           info.common.displayName,
           (int)info.common.accessMode);
}

5.12.9 ST_GetEnumEntryInfo#

Queries detailed information about an enumeration feature entry.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetEnumEntryInfo(int32_t hDevice, CvsModuleType moduleType, const char* FeatureName, int32_t EntryIdx, CVS_FEATURE_ENUM_ENTRY_INFO* pInfo);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
CVS_FEATURE_ENUM_ENTRY_INFO info = {};

CVS_ERROR err = ST_GetEnumEntryInfo(hDevice, moduleType, "PixelFormat", 0, &info);
if (err == MCAM_ERR_OK)
{
    printf("entry[0]: value=%s, intValue=%d, displayName=%s\n",
           info.stringValue,
           info.intValue,
           info.displayName);
}

5.12.10 ST_GetDependingFeatureCount#

Queries the number of features that depend on the specified feature node.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetDependingFeatureCount(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, uint32_t* pCount);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
uint32_t count = 0;

CVS_ERROR err = ST_GetDependingFeatureCount(hDevice, moduleType, "TriggerMode", &count);
if (err == MCAM_ERR_OK)
{
    printf("depending feature count = %u\n", count);
}

5.12.11 ST_GetDependingFeatureName#

Queries the name of a feature that depends on the specified feature node by index.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetDependingFeatureName(int32_t hDevice, CvsModuleType moduleType, const char* NodeName, int32_t index, char* pInfo, uint32_t* pSize);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
char featureName[256] = {};
uint32_t size = sizeof(featureName);

CVS_ERROR err = ST_GetDependingFeatureName(hDevice, moduleType, "TriggerMode", 0, featureName, &size);
if (err == MCAM_ERR_OK)
{
    printf("depending feature[0] = %s\n", featureName);
}

5.13 Image Color Conversion#

This function performs image color-space conversion.

5.13.1 ST_CvtColor#

Converts an image from one color space to another.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_CvtColor(CVS_BUFFER pSrc, CVS_BUFFER* pDest, int32_t code);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Notes

• The source and destination buffer memory must remain valid during the call.
• It is recommended to prepare the destination buffer with channel count and size appropriate for the conversion result format.

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
// Example: Converting BayerRG 8-bit input to BGR
CVS_BUFFER src = {};
CVS_BUFFER dst = {};

if (ST_InitBuffer(hDevice, &src, 0) == MCAM_ERR_OK &&
    ST_InitBuffer(hDevice, &dst, 3) == MCAM_ERR_OK &&
    ST_SingleGrabImage(hDevice, &src) == MCAM_ERR_OK)
{
    CVS_ERROR err = ST_CvtColor(src, &dst, CVP_BayerRG2BGR);
    if (err == MCAM_ERR_OK)
    {
        printf("converted image: %d x %d, channels=%d\n",
               dst.image.width,
               dst.image.height,
               dst.image.channels);
    }

    ST_FreeBuffer(&src);
    ST_FreeBuffer(&dst);
}

5.14 XML and JSON File Management#

These functions import or export device settings as XML/JSON files.

5.14.1 ST_ImportXML#

Imports settings from an XML file.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_ImportXML(int32_t hDevice, const char* FileName);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_ERROR err = ST_ImportXML(hDevice, "camera_config.xml");
if (err != MCAM_ERR_OK)
{
    printf("ST_ImportXML failed: %d\n", err);
}

5.14.2 ST_ExportXML#

Exports camera settings to an XML file.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_ExportXML(int32_t hDevice, const char* FileName, int Version = XML_VERSION_1_1, int Visibility = VISIBILITY_GURU);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Notes

• The default values are Version = XML_VERSION_1_1 and Visibility = VISIBILITY_GURU.

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_ERROR err = ST_ExportXML(
    hDevice,
    "camera_export.xml",
    XML_VERSION_1_1,
    VISIBILITY_GURU
);

if (err != MCAM_ERR_OK)
{
    printf("ST_ExportXML failed: %d\n", err);
}

5.14.3 ST_ImportJson#

Imports a JSON configuration file for the device.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_ImportJson(int32_t hDevice, const char* FileName);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_ERROR err = ST_ImportJson(hDevice, "camera_config.json");
if (err != MCAM_ERR_OK)
{
    printf("ST_ImportJson failed: %d\n", err);
}

5.14.4 ST_ExportJson#

Exports device settings to a JSON file.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_ExportJson(int32_t hDevice, const char* FileName, int Visibility = VISIBILITY_GURU);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Notes

• The default value is Visibility = VISIBILITY_GURU.

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_ERROR err = ST_ExportJson(hDevice, "camera_export.json", VISIBILITY_GURU);
if (err != MCAM_ERR_OK)
{
    printf("ST_ExportJson failed: %d\n", err);
}

5.15 Event and Callback Management#

These functions register/unregister Grab event and device event callbacks.

5.15.1 ST_RegisterGrabCallback#

Registers a Grab event callback function.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_RegisterGrabCallback(int32_t hDevice, int32_t Event, GrabCallback grabCallback, void* UserData);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

void WINAPI OnGrab(int32_t eventID, const CVS_BUFFER* pBuffer, void* pUserDefine)
{
    if (eventID == EVENT_NEW_IMAGE && pBuffer != nullptr)
    {
        printf("new image: %d x %d\n", pBuffer->image.width, pBuffer->image.height);
    }
}

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_ERROR err = ST_RegisterGrabCallback(hDevice, EVENT_NEW_IMAGE, OnGrab, nullptr);
if (err != MCAM_ERR_OK)
{
    printf("ST_RegisterGrabCallback failed: %d\n", err);
}

5.15.2 ST_UnregisterGrabCallback#

Unregisters a Grab event callback function.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_UnregisterGrabCallback(int32_t hDevice, int32_t Event);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_ERROR err = ST_UnregisterGrabCallback(hDevice, EVENT_NEW_IMAGE);
if (err != MCAM_ERR_OK)
{
    printf("ST_UnregisterGrabCallback failed: %d\n", err);
}

5.15.3 ST_RegisterEventCallback#

Registers a device event callback function.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_RegisterEventCallback(int32_t hDevice, int32_t Event, EventCallback eventCallback, void* UserData);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

void WINAPI OnDeviceEvent(const CVS_EVENT* pEvent, void* pUserDefine)
{
    if (pEvent != nullptr)
    {
        printf("event id=%d, timestamp=%llu\n",
               pEvent->id,
               (unsigned long long)pEvent->timestamp);
    }
}

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_ERROR err = ST_RegisterEventCallback(hDevice, EVENT_DEVICE_DISCONNECT, OnDeviceEvent, nullptr);
if (err != MCAM_ERR_OK)
{
    printf("ST_RegisterEventCallback failed: %d\n", err);
}

5.15.4 ST_UnregisterEventCallback#

Unregisters a device event callback function.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_UnregisterEventCallback(int32_t hDevice, int32_t Event);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_ERROR err = ST_UnregisterEventCallback(hDevice, EVENT_DEVICE_DISCONNECT);
if (err != MCAM_ERR_OK)
{
    printf("ST_UnregisterEventCallback failed: %d\n", err);
}

5.16 Buffer Management#

These functions prepare and release CVS_BUFFER memory.

5.16.1 ST_InitBuffer#

Initializes a CVS_BUFFER structure.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_InitBuffer(int32_t hDevice, CVS_BUFFER* pBuffer, int32_t channels = 0);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Notes

• When channels = 0, the channel count is designed to be determined automatically according to the camera settings.
• Use this to prepare a buffer before image acquisition.

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_BUFFER buffer = {};

// channels examples: 0 (auto/based on source), 1 (Gray), 3 (for BGR/RGB)
CVS_ERROR err = ST_InitBuffer(hDevice, &buffer, 3);
if (err == MCAM_ERR_OK)
{
    printf("buffer initialized\n");
}

5.16.2 ST_FreeBuffer#

Releases a CVS_BUFFER structure.

Signature

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_FreeBuffer(CVS_BUFFER* pBuffer);

Parameters

Return Value

• MCAM_ERR_OK: Success
• Otherwise: Error code

Notes

• To reuse a released buffer, call ST_InitBuffer() again.

Example

int32_t hDevice = /* Handle obtained after ST_OpenDevice() succeeds */ 0;
CVS_BUFFER buffer = {};

if (ST_InitBuffer(hDevice, &buffer, 0) == MCAM_ERR_OK)
{
    CVS_ERROR err = ST_FreeBuffer(&buffer);
    if (err != MCAM_ERR_OK)
    {
        printf("ST_FreeBuffer failed: %d\n", err);
    }
}

6. Notes#

• This document is organized based on the attached header declarations. Actual behavior details may vary depending on the distributed DLL/SDK version.
• Some events and device information may or may not be available depending on the interface (GEV, U3V, CXP).
• For string/buffer arguments, allocate sufficiently large memory before the call, and for pSize-type arguments, handle both the buffer size and the actual returned size.
• When using ST_GrabImage(), ST_GrabImageAsync(), ST_SingleGrabImage(), and ST_CvtColor(), manage the order of buffer initialization and memory release carefully.
• Feature and module-based APIs operate correctly only when the CvsModuleType value and target node name are accurate.

7. License and Copyright#

This library is the property of ©2000 - 2026 CREVIS CO., LTD.

Unauthorized copying and redistribution may be restricted. Please comply with the license policy.