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.17350.20200621

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
MEDIASUBTYPE_RGB24 (always RGB24)
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 cameras?

A: Yes, but it's something tricky. The toupcam.ax generally open the "first" camera connected to the computer. If you want to open multiple cameras simultaneously, we advise you to use the native C API. If you truely want to open multiple cameras 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: camera model name */
const wchar_t* __stdcall DshowGetModelName(unsigned index);

/* 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)) /* query 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.