cvsCamCtrl Library

1. 개요#

cvsCamCtrl는 CREVIS에서 제공하는 가상 프레임그래버 라이브러리입니다. 본 문서는 첨부된 cvsCamCtrl.h 헤더를 기준으로 API, 상수, 구조체, 열거형, Feature 메타데이터 조회 기능, 모듈 기반 확장 레지스터 접근 기능까지 포함하여 정리한 프로그래머 가이드입니다.

1.1 문서 기준#

• 헤더 우선 원칙: 함수 시그니처, 타입, 기본값, enum/struct 정의는 첨부된 cvsCamCtrl.h 선언을 우선 기준으로 삼았습니다.

대표적인 기본 사용 순서는 다음과 같습니다.

ST_InitSystem();
ST_UpdateDevice();            // 또는 ST_UpdateDeviceWithTimeout()
ST_OpenDevice(...);
ST_InitBuffer(...);

/* 연속 취득 */
ST_AcqStart(hDevice);
ST_GrabImage(...);           // 또는 ST_GrabImageAsync(...)
ST_AcqStop(hDevice);

/* 단발 취득 */
ST_SingleGrabImage(...);

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

1.2 헤더 리비전 이력#

2. 정의 및 상수#

이 섹션에서는 이벤트 ID, 오류 코드, 장치 정보 상수, XML 버전, 가시성 수준, 모듈 식별 매크로, 색상 변환 코드 조합용 비트 필드를 설명합니다.

2.1 이벤트 정의#

이벤트는 Grab 이벤트와 장치 이벤트로 구분됩니다. Grab 이벤트는 이미지 획득 흐름에서 발생하고, 장치 이벤트는 장치 상태나 인터페이스 상태 변화에서 발생합니다.

2.1.1 Grab 이벤트#

2.1.2 장치 이벤트#

일부 이벤트는 특정 인터페이스에서만 지원됩니다. 헤더 주석 기준 인터페이스 범위는 GEV, U3V 또는 CXP 관련 속성으로 구분됩니다.

2.2 오류 코드 정의#

일반적으로 0은 정상, 음수 값은 오류를 의미합니다.

2.3 장치 정보 정의#

장치 정보 상수는 ST_GetEnumDeviceInfo()에서 조회할 정보 종류를 지정할 때 사용합니다.

2.4 XML 버전#

2.5 파라미터 가시성#

2.6 모듈 식별 매크로#

헤더에는 모듈 식별용 매크로도 함께 정의되어 있습니다. 모듈 기반 확장 API에서는 별도의 CvsModuleType 열거형을 주로 사용합니다.

2.7 색상 변환 비트 필드 정의#

ConvertColor 값은 아래 비트 필드 상수들을 조합하여 구성됩니다.

3. 구조체 정의#

3.1 CVS_IMAGE 구조체#

이미지 데이터의 기본 속성을 저장하는 구조체입니다.

정의

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;

필드

3.2 CVS_BUFFER 구조체#

Grab 결과 버퍼와 메타데이터를 저장하는 구조체입니다.

정의

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;

필드

3.3 CVS_EVENT 구조체#

장치 이벤트의 ID, 시각, 데이터 포인터를 저장하는 구조체입니다.

정의

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;

필드

3.4 CVS_FEATURE 구조체#

Feature 목록을 열거할 때 사용하는 요약 구조체입니다.

정의

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

필드

3.5 CVS_FEATURE_INFO 구조체#

모든 Feature 타입에서 공통으로 사용하는 메타데이터 구조체입니다.

정의

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;

필드

3.6 CVS_FEATURE_INTEGER_INFO 구조체#

정수형 Feature의 현재값과 범위 정보를 담는 구조체입니다.

정의

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;

필드

3.7 CVS_FEATURE_FLOAT_INFO 구조체#

실수형 Feature의 현재값과 범위 정보를 담는 구조체입니다.

정의

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;

필드

3.8 CVS_FEATURE_BOOLEAN_INFO 구조체#

불리언 Feature의 현재값을 담는 구조체입니다.

정의

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

필드

3.9 CVS_FEATURE_STRING_INFO 구조체#

문자열 Feature의 현재값을 담는 구조체입니다.

정의

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

필드

3.10 CVS_FEATURE_ENUMERATION_INFO 구조체#

열거형 Feature의 현재 문자열/정수값과 항목 개수를 담는 구조체입니다.

정의

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;

필드

3.11 CVS_FEATURE_ENUM_ENTRY_INFO 구조체#

개별 열거형 항목의 상세 메타데이터를 담는 구조체입니다.

정의

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;

필드

3.12 CVS_FEATURE_COMMAND_INFO 구조체#

명령형 Feature의 공통 메타데이터를 담는 구조체입니다.

정의

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

필드

4. 열거형 정의#

4.1 색상 변환 (enum ConvertColor)#

ST_CvtColor()에서 사용하는 색상 변환 코드입니다. 값은 소스 픽셀 형식, 비트 수, 패킹 방식, 출력 색 공간, 필터 정보를 조합한 비트 필드로 구성됩니다.

색상 변환 코드는 아래와 같이 그룹별로 정리할 수 있습니다.

4.1.1 기본 RGB/BGR 변환

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 변환

4.1.13 Mono 비트 축소

4.2 모듈 타입 (enum CvsModuleType)#

확장 레지스터/Feature API에서 접근 대상 모듈을 지정할 때 사용하는 열거형입니다.

4.3 Feature 타입 (enum CvsFeatureType)#

Feature 노드의 데이터 타입을 나타내는 열거형입니다.

4.4 액세스 권한 (enum CvsAccessType)#

장치를 열 때 사용하는 액세스 권한을 정의하는 열거형입니다.

4.5 액세스 모드 (enum CvsAccessMode)#

Feature의 읽기/쓰기 가능 상태를 나타내는 열거형입니다.

4.6 가시성 (enum CvsVisibility)#

Feature의 UI 노출 수준을 나타내는 열거형입니다.

4.7 표현 방식 (enum CvsRepresentation)#

숫자/논리값을 UI에서 어떻게 표시할지 나타내는 열거형입니다.

5. 함수#

이 섹션에서는 콜백, 시스템 관리, 장치 연결, Grab, 레지스터 제어, Feature 조회, 파일 입출력, 버퍼 관리까지 전체 API를 설명합니다.

아래 예제는 C++ 기준의 최소 사용 예입니다. hDevice는 ST_OpenDevice() 성공 후 얻은 유효한 핸들을 의미하며, 예제의 노드 이름(Width, ExposureTime, PixelFormat, DeviceUserID 등)은 실제 장치 XML/GenICam feature 구성에 따라 달라질 수 있습니다. 문자열 조회 함수는 필요 시 2-pass 방식으로 실제 버퍼 크기를 먼저 확인하십시오.

5.1 콜백 함수 정의#

라이브러리에서 제공하는 콜백 함수 형식입니다.

5.1.1 GrabCallback#

Grab 이벤트가 발생할 때 호출되는 콜백 함수 형식입니다.

형식

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

매개변수

반환값

• 없음 (void)

예제

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#

장치 이벤트가 발생할 때 호출되는 콜백 함수 형식입니다.

형식

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

매개변수

반환값

• 없음 (void)

예제

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 시스템 관리#

시스템 초기화와 해제, 초기화 상태 확인 관련 함수입니다.

5.2.1 ST_InitSystem#

시스템을 초기화합니다.

시그니처

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_InitSystem();

매개변수

없음

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

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

5.2.2 ST_FreeSystem#

시스템 리소스를 해제합니다.

시그니처

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_FreeSystem();

매개변수

없음

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

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

5.2.3 ST_IsInitSystem#

시스템이 초기화되었는지 확인합니다.

시그니처

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_IsInitSystem(bool* pFlag);

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

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

5.3 장치 검색 및 정보 조회#

장치 검색, 열거, 인터페이스 및 기본 정보 조회 관련 함수입니다.

5.3.1 ST_GetAvailableCameraNum#

사용 가능한 카메라 개수를 조회합니다.

시그니처

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetAvailableCameraNum(uint32_t* pNum);

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

// 전제: ST_UpdateDevice() 또는 ST_UpdateDeviceWithTimeout()를 먼저 호출합니다.
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#

장치 목록을 갱신합니다.

시그니처

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_UpdateDevice();

매개변수

없음

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

비고

• 1.1.2 리비전부터 ST_UpdateDevice()와 ST_UpdateDeviceWithTimeout()가 분리되었습니다.

예제

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

5.3.3 ST_UpdateDeviceWithTimeout#

타임아웃을 지정하여 장치 목록을 갱신합니다.

시그니처

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_UpdateDeviceWithTimeout(uint32_t uTimeout);

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

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#

지정한 열거 인덱스의 장치 ID를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

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#

지정한 열거 인덱스의 장치 정보를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

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#

지정한 열거 인덱스의 인터페이스를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

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 장치 연결 및 제어#

장치 연결, 오픈 상태 확인, 인터페이스 조회 관련 함수입니다.

5.4.1 ST_IsConnectable#

장치가 연결 가능한 상태인지 확인합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

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#

장치를 엽니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

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#

멀티캐스트 모드로 장치를 엽니다.

시그니처

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);

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

비고

• IPAddress는 멀티캐스트 그룹 주소 또는 대상 IP 주소로 사용됩니다.
• DataPort가 0이면 라이브러리가 적절한 포트를 선택할 수 있습니다.
• 헤더 주석 기준으로 AccessControl 권한은 하나의 제어 노드만 가질 수 있습니다.
• 멀티캐스트 환경에서는 네트워크 장비의 IGMP Snooping 설정이 필요할 수 있습니다.

예제

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#

장치가 열려 있는지 확인합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치를 닫습니다.

시그니처

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_CloseDevice(int32_t hDevice);

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
CVS_ERROR err = ST_CloseDevice(hDevice);
if (err != MCAM_ERR_OK)
{
    printf("ST_CloseDevice failed: %d\n", err);
}

5.4.6 ST_GetInterface#

장치의 인터페이스를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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 이미지 획득 및 설정#

이미지 획득 시작/중지와 Grab 동작 설정 관련 함수입니다.

5.5.1 ST_AcqStart#

장치에서 Acquisition을 시작합니다.

시그니처

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_AcqStart(int32_t hDevice);

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
// 전제: 필요하다면 ST_InitBuffer()와 콜백 등록을 먼저 수행합니다.
CVS_ERROR err = ST_AcqStart(hDevice);
if (err != MCAM_ERR_OK)
{
    printf("ST_AcqStart failed: %d\n", err);
}

5.5.2 ST_AcqStop#

장치에서 Acquisition을 중지합니다.

시그니처

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_AcqStop(int32_t hDevice);

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
// 전제: 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#

장치에서 진행 중인 Grab을 중단합니다.

시그니처

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_DoAbortGrab(int32_t hDevice);

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
// 전제: Grab 대기 중이거나 취득 중인 상태입니다.
CVS_ERROR err = ST_DoAbortGrab(hDevice);
if (err != MCAM_ERR_OK)
{
    printf("ST_DoAbortGrab failed: %d\n", err);
}

5.5.4 ST_SetGrabTimeout#

장치의 Grab 타임아웃을 설정합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치의 Grab 타임아웃을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치의 내부 버퍼 개수를 설정합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치의 내부 버퍼 개수를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
uint32_t bufferCount = 0;

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

5.6 이미지 처리 및 상태 확인#

이미지 취득 결과 확인과 통계 조회 관련 함수입니다.

5.6.1 ST_GrabImage#

장치에서 이미지를 Grab합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

비고

• ST_AcqStart()가 시작된 상태에서 사용하십시오.
• ST_InitBuffer()로 버퍼를 먼저 초기화한 뒤 호출하는 것이 안전합니다.

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치에서 이미지를 비동기로 Grab합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

비고

• 비동기 Grab 지원은 1.0.7 이후 추가되었습니다.
• 1.1.1에서 ST_GrabImageAsync()의 파라미터와 동작이 조정되었습니다.

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치에서 단일 이미지를 Grab합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

비고

• 연속 획득을 시작하지 않고 단발성으로 이미지를 취득할 때 사용합니다.

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치에서 이미지가 사용 가능한지 확인합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

비고

• 출력 타입은 uint32_t*이며, 일반적으로 0이 아닌 값이면 사용 가능 상태로 해석합니다.

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
// 전제: 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#

장치의 Grab 개수와 오류 개수를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치의 프레임 속도를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치의 대역폭을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치의 마지막 오류 코드를 조회합니다.

시그니처

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_GetLastError(int32_t hDevice);

매개변수

반환값

• 장치의 마지막 오류 코드 (MCAM_ERR_*)

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
// 예시: 일부러 잘못된 노드명을 사용해 오류를 발생시킨 뒤 마지막 오류를 확인합니다.
(void)ST_SetIntReg(hDevice, "InvalidNodeName", 1);

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

5.6.9 ST_GetLastErrorDescription#

장치의 마지막 오류 설명 문자열을 조회합니다.

시그니처

CVS_IMPORT_EXPORT const char* WINAPI ST_GetLastErrorDescription(int32_t hDevice);

매개변수

반환값

• 마지막 오류에 대한 설명 문자열

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
// 예시: 마지막 오류 문자열을 바로 조회합니다.
(void)ST_SetIntReg(hDevice, "InvalidNodeName", 1);

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

5.7 로그 및 설정 관리#

상세 로그 활성화 상태를 제어하는 함수입니다.

5.7.1 ST_SetDetailedLog#

장치의 상세 로그 활성화 여부를 설정합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치의 상세 로그 활성화 여부를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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 레지스터 제어#

기본 레지스터 값을 읽고 쓰는 함수입니다.

5.8.1 ST_SetIntReg#

정수형 레지스터 값을 설정합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
// 노드 이름은 실제 장치 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#

정수형 레지스터 값을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

실수형 레지스터 값을 설정합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

실수형 레지스터 값을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

불리언 레지스터 값을 설정합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

불리언 레지스터 값을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

열거형 레지스터 값을 설정합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

열거형 레지스터 값을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

문자열 레지스터 값을 설정합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

비고

• 선언상 입력 인수 타입은 char*입니다. 호출 코드 작성 시 헤더 선언을 그대로 따르십시오.

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

문자열 레지스터 값을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

명령 레지스터를 실행합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
// 예시 노드는 장치에 따라 다를 수 있습니다.
CVS_ERROR err = ST_SetCmdReg(hDevice, "UserSetLoad");
if (err != MCAM_ERR_OK)
{
    printf("ST_SetCmdReg failed: %d\n", err);
}

5.9 레지스터 정보 조회#

레지스터 범위와 열거형 항목 정보를 조회하는 함수입니다.

5.9.1 ST_GetIntRegRange#

정수형 레지스터의 범위를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

실수형 레지스터의 범위를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

열거형 레지스터 항목 개수를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

열거형 항목의 정수값을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

열거형 항목의 문자열 값을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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 파라미터 읽기 및 쓰기#

주소 기반 파라미터 읽기/쓰기 함수입니다.

5.10.1 ST_ReadParam#

장치에서 파라미터를 읽습니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
// 주소와 길이는 실제 장치 매뉴얼에 맞게 지정합니다.
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#

장치에 파라미터를 씁니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
// 주소와 데이터 형식은 실제 장치 매뉴얼에 맞게 지정합니다.
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 확장 레지스터 및 파라미터 제어#

모듈 기반 확장 레지스터/파라미터 접근 함수입니다.

5.11.1 ST_SetIntRegEx#

지정한 모듈의 정수형 레지스터 값을 설정합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 정수형 레지스터 값을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 실수형 레지스터 값을 설정합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 실수형 레지스터 값을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 불리언 레지스터 값을 설정합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 불리언 레지스터 값을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 열거형 레지스터 값을 설정합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 열거형 레지스터 값을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 문자열 레지스터 값을 설정합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 문자열 레지스터 값을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 명령 레지스터를 실행합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;

// 예시 노드는 장치 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#

지정한 모듈의 정수형 레지스터 범위를 조회합니다.

시그니처

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);

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 실수형 레지스터 범위를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 열거형 레지스터 항목 개수를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 열거형 항목 정수값을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 열거형 항목 문자열 값을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈에서 파라미터를 읽습니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
// 주소와 길이는 실제 모듈의 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#

지정한 모듈에 파라미터를 씁니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
CvsModuleType moduleType = ModuleRemoteDevice;
// 주소와 데이터 형식은 실제 모듈의 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 및 메타데이터 조회#

Feature 목록, 상세 메타데이터, Feature 의존 관계를 조회하는 함수입니다.

5.12.1 ST_GetFeatureSize#

지정한 모듈의 Feature 개수를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

비고

• moduleType에는 CvsModuleType 값을 사용합니다. 일반적인 카메라 파라미터 조회는 ModuleRemoteDevice가 자주 사용됩니다.

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 모듈의 Feature 목록에서 항목을 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

비고

• Feature 목록을 순회할 때는 먼저 ST_GetFeatureSize()로 총 개수를 확인한 뒤 인덱스를 증가시키는 방식이 일반적입니다.

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

정수형 Feature의 상세 정보를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

실수형 Feature의 상세 정보를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

불리언 Feature의 상세 정보를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

문자열 Feature의 상세 정보를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

열거형 Feature의 상세 정보를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

명령형 Feature의 상세 정보를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

열거형 Feature 항목의 상세 정보를 조회합니다.

시그니처

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);

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 Feature 노드에 종속되는 Feature 개수를 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

지정한 Feature 노드에 종속되는 Feature 이름을 인덱스로 조회합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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 이미지 색상 변환#

이미지 색 공간 변환 함수입니다.

5.13.1 ST_CvtColor#

이미지를 한 색 공간에서 다른 색 공간으로 변환합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

비고

• 원본 버퍼와 대상 버퍼의 메모리 수명은 호출 중 유효해야 합니다.
• 대상 버퍼는 변환 결과 형식에 맞는 채널 수와 크기로 준비하는 것이 좋습니다.

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
// 예시: BayerRG 8-bit 입력을 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 및 JSON 파일 관리#

장치 설정을 XML/JSON 파일로 가져오거나 내보내는 함수입니다.

5.14.1 ST_ImportXML#

XML 파일에서 설정을 가져옵니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

카메라 설정을 XML 파일로 내보냅니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

비고

• 기본값은 Version = XML_VERSION_1_1, Visibility = VISIBILITY_GURU입니다.

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치용 JSON 설정 파일을 가져옵니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치 설정을 JSON 파일로 내보냅니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

비고

• 기본값은 Visibility = VISIBILITY_GURU입니다.

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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 이벤트 및 콜백 관리#

Grab 이벤트 및 장치 이벤트 콜백 등록/해제 함수입니다.

5.15.1 ST_RegisterGrabCallback#

Grab 이벤트 콜백 함수를 등록합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

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 = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

Grab 이벤트 콜백 함수를 해제합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치 이벤트 콜백 함수를 등록합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

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 = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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#

장치 이벤트 콜백 함수를 해제합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
CVS_ERROR err = ST_UnregisterEventCallback(hDevice, EVENT_DEVICE_DISCONNECT);
if (err != MCAM_ERR_OK)
{
    printf("ST_UnregisterEventCallback failed: %d\n", err);
}

5.16 버퍼 관리#

CVS_BUFFER 메모리 준비와 해제를 위한 함수입니다.

5.16.1 ST_InitBuffer#

CVS_BUFFER 구조체를 초기화합니다.

시그니처

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

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

비고

• channels = 0이면 카메라 설정에 맞춰 채널 수가 자동 결정되도록 설계되었습니다.
• 이미지 획득 전에 버퍼를 먼저 준비하는 용도로 사용합니다.

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 0;
CVS_BUFFER buffer = {};

// channels 예시: 0(자동/원본 기준), 1(Gray), 3(BGR/RGB 용도)
CVS_ERROR err = ST_InitBuffer(hDevice, &buffer, 3);
if (err == MCAM_ERR_OK)
{
    printf("buffer initialized\n");
}

5.16.2 ST_FreeBuffer#

CVS_BUFFER 구조체를 해제합니다.

시그니처

CVS_IMPORT_EXPORT CVS_ERROR WINAPI ST_FreeBuffer(CVS_BUFFER* pBuffer);

매개변수

반환값

• MCAM_ERR_OK: 성공
• 그 외: 오류 코드

비고

• 해제한 버퍼를 다시 사용하려면 ST_InitBuffer()를 다시 호출하십시오.

예제

int32_t hDevice = /* ST_OpenDevice() 성공 후 얻은 핸들 */ 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. 주의사항#

• 본 문서는 첨부된 헤더 선언을 기준으로 정리되었습니다. 실제 동작 세부사항은 배포된 DLL/SDK 버전에 따라 달라질 수 있습니다.
• 일부 이벤트와 장치 정보는 인터페이스(GEV, U3V, CXP)에 따라 제공 여부가 달라질 수 있습니다.
• 문자열/버퍼 인수는 호출 전에 충분한 크기의 메모리를 확보하고, pSize 계열 인수는 버퍼 크기와 실제 반환 크기를 함께 처리하도록 작성하는 것이 좋습니다.
• ST_GrabImage(), ST_GrabImageAsync(), ST_SingleGrabImage(), ST_CvtColor() 사용 시 버퍼의 초기화와 메모리 해제 순서를 명확히 관리하십시오.
• Feature 및 모듈 기반 API는 CvsModuleType 값과 대상 노드 이름이 정확해야 정상 동작합니다.

7. 라이선스 및 저작권#

본 라이브러리는 ©2000 - 2026 CREVIS CO., LTD.의 소유 입니다.

무단 복제 및 재배포는 제한될 수 있으니 라이선스 정책을 준수하십시오.