FAQ for toupcam directshow sdk

NOTICE: This Q&A below is only for directshow sdk.

Q: What's the version of this sdk?

A: 1.0.13010.20180926

Q: What's in toupcam directshow sdk?

A: For normal directshow application development, pure directshow programming is sufficient. For advanced directshow application development (such as camera control GUI customization), COM interfaces in toupcam_dshow.h are available. A how-to-use C++ source code sample demodshow.zip is shipped within toupcamsdk.zip as well. There is also a sample program source code amcap.zip (provided by Microsoft) in the samples directory.

Q: The toupcam camera gets found on device enumeration even when it is not connected to PC. If the camera is not connected it should not be enumerated. Is this a bug?

A: No, this is not a bug, it is inherent. If you want to avoid this, you may use the native C API.

Q: The media type of the output pin is always RGB24 even the bitdepth is greater than 8 or for mono cameras. Is this a bug?

A: No, this is not a bug, it is by design. The output media subtype is always MEDIASUBTYPE_RGB24 even the bitdepth is greater than 8 or for mono cameras. After all, there is not MEDIASUBTYPE_RGB48 in directshow.

Q: How about the samples?

A: 1. demodshow: everything about directshow is in dshow.h and dshow.cpp. This sample uses mfc for the UI.

2. amcap: a sample comes from Microsoft.

Q: Where can I find the learning materials about DirectShow?

A: Microsoft's MSDN is the most complete reference of DirectShow. You can access it at http://msdn.microsoft.com/en-us/library/dd375454%28v=VS.85%29.aspx

Q: Which interfaces does toupcam support?

Filter interfaces IBaseFilter
ISpecifyPropertyPages
IAMFilterMiscFlags
IAMVideoControl (Still capture capable models)
IAMVideoProcAmp
IVideoProcAmp
ICameraControl
IAMCameraControl
IToupcam (see toupcam_dshow.h)
IToupcamSerialNumber
IToupcamStillImage (Still capture capable models)
IToupcamSerialNumber
IToupcamVersion
IToupcamST4
Output pin interfaces
Preview or Still
IPin
IQualityControl
IAMStreamConfig
IKsPropertySet
ISpecifyPropertyPages
IAMVideoProcAmp
IVideoProcAmp
ICameraControl
IAMCameraControl
IToupcam (see toupcam_dshow.h)
IToupcamSerialNumber
IToupcamStillImage (Still capture capable models)
IToupcamSerialNumber
IToupcamVersion
IToupcamST4
Output Pin Media Types MEDIATYPE_Video (always RGB24)
MEDIASUBTYPE_NULL
FORMAT_VideoInfo

Q: What are the valid ranges of parameters?

A:

Category Functions Range or function to get the range Default
Video Resolution put_Size
get_Size
put_eSize
get_eSize
get_ResolutionNumber
get_Resolution
model specific
Exposure get_AutoExpoTarget
put_AutoExpoTarget
10~230 120
get_AutoExpoEnable
put_AutoExpoEnable
TRUE or FALSE TRUE
get_ExpoTime
put_ExpoTime
get_ExpTimeRange model specific
get_ExpoAGain
put_ExpoAGain
get_ExpoAGainRange model specific
White Balance get_TempTint
put_TempTint
Temp: 2000~15000
Tint: 200~2500
Temp = 6503
Tint = 1000
Color get_Hue
put_Hue
-180~180 0
get_Saturation
put_Saturation
0~255 128
get_Brightness
put_Brightness
-64~64 0
get_Contrast
put_Contrast
-100~100 0
get_Gamma
put_Gamma
20~180 100
get_LevelRange
put_LevelRange
0~255 Low = 0
High = 255
get_MonoMode S_OK: mono mode
S_FALSE: color mode
model specific
Vignetting get_VignetEnable
put_VignetEnable
TRUE or FALSE FALSE
get_VignetMidPointInt
put_VignetMidPointInt
0~100 50
get_VignetAmountInt
put_VignetAmountInt
-100~100 0
Misc get_VFlip
put_VFlip
TRUE or FALSE FALSE
get_HZ
put_HZ
enum: 0, 1, 2
0 -> 60HZ AC
1 -> 50Hz AC
2 -> DC
DC
get_Chrome
put_Chrome
TRUE or FALSE FALSE
get_Speed
put_Speed
get_MaxSpeed model specific
Still Image put_StillSize
get_StillSize
put_eStillSize
get_eStillSize
get_StillResolutionNumber
get_StillResolution
model specific

NOTE: Exposure time unit is microsecond.

Q: How to know whether the camera supports still capture via SDK?

A: Query the IToupcamStillImage interface.

Q: How to get the actual frame rate with this SDK?

A: Code example can be found in TDshowContext::get_framerate function in dshow.h and dshow.cpp of the demodshow sample project.

Q: How to get the camera's unique id?

A: Use the IToupcamSerialNumber interface. Code example can be found in the demodshow sample project.

Q: Can this SDK used with .net applications?

A: Yes, of course. This SDK is DirectShow based and can be easily integrated into your .net applications. See http://directshownet.sourceforge.net/ for more details.

Q: How to use the ROI?

There are two cases according to that the camera filter is connected or not connected.
(1) Before the camera filter is connected: firstly, use put_eSize or put_Size to set the resolution, then use put_Roi to set the ROI.
(2) After the camera filter is connected: call put_Roi to set the offset can be supported. The width and height can NOT be changed.

DShow ROI is supported since 20180824.

Q: Does directshow sdk support multiple camera instance?

A: Yes, but it's something tricky. The toupcam.ax generally open the "first" camera connected to the computer. If you want open multiple instance simultaneously, we advise you to use the native API. If you truely want to open multiple instance simultaneously in directshow, please use DshowEnumCamera and DshowOpenCamera which are defined as below:

/* return value: the number of connected camera */
unsigned __stdcall DshowEnumCamera();

/* return value: the camera directshow COM object, which can be used to QueryInterface(IID_IBaseFilter, ...). When failed, NULL is returned */
/* use DshowOpenCamera(0) to open the first camera, use DshowOpenCamera(1) to open the second camera, etc */
IUnknown* __stdcall DshowOpenCamera(unsigned index);

Please see USE_DSHOWOPENCAMERA in files dshow.h and dshow.cpp of the demodshow sample project. Use InitToupcamAx() to get the function pointers.
typedef unsigned  (__stdcall *PFUN_DSHOWENUMCAMERA)();
typedef const wchar_t* (__stdcall *PFUN_DSHOWGETMODELNAME)(unsigned index);
typedef IUnknown* (__stdcall *PFUN_DSHOWOPENCAMERA)(unsigned index);
PFUN_DSHOWENUMCAMERA g_pDshowEnumCamera = NULL;
PFUN_DSHOWGETMODELNAME g_pDshowGetModelName = NULL;
PFUN_DSHOWOPENCAMERA g_pDshowOpenCamera = NULL;
HMODULE g_hModuleToupcamAx = NULL;

void InitToupcamAx()
{
    if (g_hModuleToupcamAx)
        return;
		
    HKEY hKey = NULL;
    /* {EA6387A5-60C7-41D3-B058-8D90580A7BE1} is the clsid of toupcam dshow object */
    if (ERROR_SUCCESS == RegOpenKeyExW(HKEY_CLASSES_ROOT, L"CLSID\\{EA6387A5-60C7-41D3-B058-8D90580A7BE1}\\InprocServer32", 0, KEY_READ, &hKey))
    {
        wchar_t axPath[MAX_PATH + 1] = { 0 };
        DWORD cbData = MAX_PATH * sizeof(wchar_t);
        if (ERROR_SUCCESS == RegQueryValueExW(hKey, NULL, NULL, NULL, (PBYTE)axPath, &cbData))
        {
            /* get the full path of toupcam.ax */
            g_hModuleToupcamAx = LoadLibraryW(axPath);
            if (g_hModuleToupcamAx)
            {
                g_pDshowEnumCamera = (PFUN_DSHOWENUMCAMERA)GetProcAddress(g_hModuleToupcamAx, "DshowEnumCamera");
                g_pDshowGetModelName = (PFUN_DSHOWGETMODELNAME)GetProcAddress(g_hModuleToupcamAx, "DshowGetModelName");
                g_pDshowOpenCamera = (PFUN_DSHOWOPENCAMERA)GetProcAddress(g_hModuleToupcamAx, "DshowOpenCamera");
            }
        }
        RegCloseKey(hKey);
    }
}

After you get the the function pointers, you can use them to open the cameras, such as: g_pDshowEnumCamera(0), g_pDshowEnumCamera(1), g_pDshowEnumCamera(2), etc.