Interface reference

This chapter is for applications that build their own DirectShow graphs, or that drive the camera programmatically. When the filter is only used as a capture device configured through its property pages, none of this is needed.

The declarations are in IGenicamControl.h and Guids.h, delivered with the licensed package. All the methods return an HRESULT. Feature names are ANSI strings (LPCSTR), the SFNC node names of the camera; paths, serials and other strings are wide (LPCWSTR / LPWSTR), and the caller provides the buffers of the Get... methods, with their size in characters.

CLSIDs

Filter entry	Constant	CLSID
Datastead GenICam Vision Source (1)	`CLSID_DtstdGenicamSource` (= `CLSID_DtstdGenicamCam1`)	`{E2C7B101-3F4A-4C8E-9B21-7A6C5D4E5F01}`
Datastead GenICam Vision Source 2	`CLSID_DtstdGenicamCam2`	`{E2C7B101-3F4A-4C8E-9B21-7A6C5D4E5F03}`
Datastead GenICam Vision Source 3	`CLSID_DtstdGenicamCam3`	`{E2C7B101-3F4A-4C8E-9B21-7A6C5D4E5F04}`
Datastead GenICam Vision Source 4	`CLSID_DtstdGenicamCam4`	`{E2C7B101-3F4A-4C8E-9B21-7A6C5D4E5F05}`

One CLSID per registered capture entry (see Multiple cameras). The filter is also enumerated in the CLSID_VideoInputDeviceCategory category, like any capture device.

Interface IIDs

Interface	Constant	IID
`IGenicamControl`	`IID_IGenicamControl`	`{E2C7B102-3F4A-4C8E-9B21-7A6C5D4E5F02}`
`IGenicamControl2`	`IID_IGenicamControl2`	`{E2C7B10E-3F4A-4C8E-9B21-7A6C5D4E5F0E}`

IGenicamControl2 derives from IGenicamControl: querying IID_IGenicamControl2 gives access to both sets of methods. The filter also implements the standard IAMStreamConfig, IAMCameraControl, IAMVideoProcAmp, IKsPropertySet and ISpecifyPropertyPages.

Types

GenicamPixelFormat

Value		Delivered as
`GC_PIXFMT_AUTO`	0	the filter decides (default)
`GC_PIXFMT_MONO8`	1	`MEDIASUBTYPE_Y800`
`GC_PIXFMT_BGR8`	2	`MEDIASUBTYPE_RGB24`, debayered on board
`GC_PIXFMT_BAYERRG8`	3	`MEDIASUBTYPE_RGGB`, raw Bayer, debayered by the host
`GC_PIXFMT_YUV422_8`	4	`MEDIASUBTYPE_UYVY`

GenicamStats

Field	Type
`FramesDelivered`	`long long`	frames delivered to the graph
`FramesDropped`	`long long`	frames dropped by the queue (host slower than the camera)
`FramesIncomplete`	`long long`	incomplete buffers received from the camera
`FramesErrors`	`long long`	grab errors
`LastFrameId`	`long long`	id of the last frame received
`CurrentFrameRate`	`double`	measured frame rate

GenicamFeatureNodeInfo

One entry of the feature-tree snapshot of IGenicamControl2.

Field	Type
`name`	`char[64]`	SFNC node name, to use with the feature accessors
`displayName`	`char[96]`	human-readable name from the camera XML
`category`	`char[128]`	path in the tree, e.g. `Acquisition Control/...`
`type`	`int`	0 Integer, 1 Float, 2 Boolean, 3 Enumeration, 4 Command, 5 String
`access`	`int`	bit 0 readable, bit 1 writable (0 = not available)
`visibility`	`int`	0 Beginner, 1 Expert, 2 Guru

IGenicamControl

GenTL producer (.cti) selection

Method
`SetGenTLProducerPath(LPCWSTR pPath)`	points the filter at a transport layer: a single `.cti` file, a folder containing `.cti` files, or a `;`-separated list. `NULL` or empty restores the default (`GENICAM_GENTL64_PATH`). Persisted under `HKCU`. Must be called before the camera selection and the streaming
`GetGenTLProducerPath(LPWSTR pPath, int maxChars)`	returns the current path
`EnumerateGenTLProducers(int* pCount)`	enumerates the `.cti` producers visible on the current search path
`GetGenTLProducerInfo(int index, LPWSTR pPath, int maxChars)`	path of the producer `index`

Camera enumeration and selection

Method
`EnumerateCameras(int* pCount)`	enumerates the cameras reachable through the selected producer(s)
`GetCameraInfo(int index, LPWSTR pSerial, int serialMaxChars, LPWSTR pModel, int modelMaxChars, LPWSTR pInterface, int ifaceMaxChars)`	serial number, model and interface (transport) of the camera `index`
`SelectCameraBySerial(LPCWSTR pSerial)`	selects the camera to open, by serial number
`SelectCameraByIndex(int index)`	selects the camera to open, by enumeration index

Format and ROI (before streaming)

Method
`SetPixelFormatPreference(GenicamPixelFormat fmt)`	preferred pixel format; the fallback order is handled by the filter
`GetPixelFormatPreference(int* pFmt)`	returns the persisted preference, available before the camera is opened
`SetROI(int offsetX, int offsetY, int width, int height)`	region of interest, in sensor pixels
`SetBinning(int binningH, int binningV)`	horizontal and vertical binning factors

Acquisition parameters (modifiable during streaming)

Method
`SetExposureTime(double microseconds)` / `GetExposureTime(double* pMicroseconds)`	exposure time
`SetGain(double dB)` / `GetGain(double* pDB)`	gain
`SetAcquisitionFrameRate(double fps)` / `GetAcquisitionFrameRate(double* pFps)`	frame rate limit (`AcquisitionFrameRate`, with its enable)
`SetAutoExposure(BOOL bEnabled)`	continuous auto exposure
`SetAutoGain(BOOL bEnabled)`	continuous auto gain
`SetAutoWhiteBalance(BOOL bEnabled)`	continuous auto white balance
`GetFloatRange(LPCSTR pName, double* pMin, double* pMax)`	`[min..max]` range of a float node, e.g. `"AcquisitionFrameRate"` or `"ExposureTime"`; `E_FAIL` if the camera is not open or the node does not exist

Triggering

Method
`SetTriggerMode(int mode)`	0 free run, 1 software trigger, 2 hardware trigger (external input line)
`SoftwareTrigger()`	fires one frame in software trigger mode

Generic GenICam feature access

Method
`SetFeatureInt(LPCSTR pName, long long value)` / `GetFeatureInt(LPCSTR pName, long long* pValue)`	integer node
`SetFeatureFloat(LPCSTR pName, double value)` / `GetFeatureFloat(LPCSTR pName, double* pValue)`	float node
`SetFeatureBool(LPCSTR pName, BOOL value)` / `GetFeatureBool(LPCSTR pName, BOOL* pValue)`	boolean node
`SetFeatureEnum(LPCSTR pName, LPCSTR pValue)` / `GetFeatureEnum(LPCSTR pName, LPSTR pValue, int maxChars)`	enumeration node, by entry name
`RunCommand(LPCSTR pName)`	executes a command node

User sets

Method
`SaveUserSet(int index)`	saves the current camera settings into the camera's user set 0..3
`LoadUserSet(int index)`	loads the user set 0..3, or the factory Default set with -1

Statistics

Method
`GetStats(GenicamStats* pStats)`	acquisition counters, see GenicamStats
`ResetStats()`	clears the counters

Licensing

Method
`GetLicenseInfo(BOOL* pLicensed, LPWSTR pLicensee, int maxChars)`	`*pLicensed` is `TRUE` when a valid license key has been accepted (always `FALSE` in the evaluation version); `pLicensee` receives the licensee name, or a short status text when not licensed

Persisted settings

Method
`ResetToDefaults()`	resets every persisted setting to its default, except the selected producer and the selected device (the Reset to defaults button of the Device page)

IGenicamControl2

Derives from IGenicamControl and adds the dynamic browsing of the camera's feature tree. Values are read and written as text, which works uniformly for every node type; the typed accessors of IGenicamControl remain available.

Method
`RefreshFeatureTree(int* pCount)`	rebuilds the feature-tree snapshot from the camera's node map and returns the node count; `E_FAIL` if the camera is not open. Call it after the camera is open, and again when the pixel format or the streaming state changes (the access modes are dynamic)
`GetFeatureNodeInfo(int index, GenicamFeatureNodeInfo* pInfo)`	one entry of the snapshot, 0-based
`GetFeatureValueString(LPCSTR pName, LPSTR pBuf, int maxChars)`	current value of any feature, as text
`SetFeatureValueString(LPCSTR pName, LPCSTR pValue)`	writes any feature from text (validated by the camera against the node); `AcquisitionFrameRate` goes through the robust frame-rate path. With `pName = NULL`, `pValue` is the license key
`GetFeatureEnumEntryList(LPCSTR pName, LPSTR pBuf, int maxChars, int* pCount)`	entries of an enumeration node, as a double-null-terminated list (`"entry1\0entry2\0...\0\0"`); `*pCount` receives the entry count
`GetFeatureRangeString(LPCSTR pName, LPSTR pBuf, int maxChars)`	human-readable range or constraint of the feature (`range 0..4095 step 1`, `range 0.1..2 (dB)`, ...), empty when not applicable

Media subtypes

Subtype	GUID
`MEDIASUBTYPE_RGB24`	standard	BGR8
`MEDIASUBTYPE_UYVY`	standard	YCbCr422_8
`MEDIASUBTYPE_Y800`	`{30303859-0000-0010-8000-00AA00389B71}`	Mono8 (FOURCC `Y800`)
`MEDIASUBTYPE_RGGB`	`{42474752-0000-0010-8000-00AA00389B71}`	raw Bayer (FOURCC `RGGB`)

Registry

Key (`HKCU`, or `HKLM` for the producer path)	Value
`Software\Datastead\DtstdGenicam`	`GenTLProducerPath` (`REG_SZ`)	selected `.cti`, see GenTL producer (.cti)
`Software\Datastead\DtstdGenicam`	`CameraCount` (`REG_DWORD`)	number of registered capture entries
`Software\Datastead\DtstdGenicam\Cam<N>`		persisted page settings of the entry N, cleared by `ResetToDefaults`