VCam SDK v3.1 document

1. Introduction

VCam SDK is a SDK of e2eSoft VCam software, which allows you to use virtual camera function in your application.

Files in SDK package:
~~~~~~~~~~~~~

[Doc] folder - Document.
[driver] folder - Files needed for virtual camera driver.
VCamCOM.dllVCamSDK COM object, which defines the IVCamSDK interface.
VCamCOM.tlbVCamCOM object type library.
VCamCOMTest.exe - Demo program to show how to use VCam COM object.
VCamCOMTest.zip - VCamCOMTest.exe's source code, VC++ 2008 project.
VCamCOMTestCSharp.exe - C# Demo program to show how to use VCam COM object.
VCamCOMTestCSharp.zip - VCamCOMTestCSharp.exe's source code, C# project.
VCamFilter.ax - A directshow renderer filter (VCam Renderer), which can redirect its input to virtual camera driver and also defines the IVCamRenderConfig interface.
VCamFilter.tlb - VCamFilter type library.
VCamFilterTest.exe - Demo program to show how to use VCam Renderer filter and IVCamRenderConfig interface.
VCamFilterTest.zip - VCamFilterTest.exe's source code, VC++ 2008 project (to build it, you need to install the latest Platform SDK, which includes DirectShow SDK, or use the following package).
BaseClasses.zip - DirectShow SDK needed to build VCamFilterTest project.
install.bat/install64.bat - Install VCam driver and all components (install64.bat is for 64bits OS).
uninstall.bat/uninstall64.bat - Uninstall VCam driver and all components (uninstall64.bat is for 64bits OS).
devcon.exe - A command-line version of Device Manager. DevCon enables, disables, installs, configures, and removes devices on the local computer and displays detailed information about devices on local and remote computers.
devcon64.exe - 64bits version of devcon.exe.

Distribution need:
~~~~~~~~~~~
[driver] folder and all files in it
devcon.exe or devcon64.exe (used to install/uninstall/restart the driver)
VCamFilter.ax (need to be registered on target system)
VCamCOM.dll (need to be registered on target system. This file is optional, if you only use VCamFilter, then you don’t need to distribute this file to final user)

 

2. Getting started

1. Install virtual camera driver and register all components - run install.bat (install64.bat on 64bits OS);

2. OK, run VCamCOMTest.exe and play a video file in it, then use other application to see e2eSoft VCam (WDM) video output;

3. Decompress VCamCOMTest.zip and open the VC++ 2008 project in it to see how we use VCamCOM object (IVCamSDK).

4. Run VCamFilterTest.exe and play a video file in it, then use other application to see e2eSoft VCam (WDM) video output;

5. Decompress VCamFilterTest.zip and open the VC++ 2008 project in it to see how it works (focus on class CVCamSDKImpl).

6. If you're using other programming languages such as C#, VB, Delphi... you can check the C# demo: VCamCOMTestCSharp.exe/.zip.

3. How it works

3.1 Using DirectShow filter

1. Play a video file in graphedit using default Video Renderer:

2: Play a video file in graphedit using VCam Renderer:

3. VCam Renderer will redirect its input to Virtual Camera output:

From this we can know it's very easy to play a video file to Virtual Camera, and you can also play a video capture device, a video stream, a VCD/DVD and .... to Virtual Camera by DirectShow filter.

You can also use IVCamRenderConfig interface to interact with virtual camera driver directly.

3.2 Using VCam COM object

For people who are not familiar with DirectShow, we provide VCam COM object (IVCamSDK interface) to make things easier. Using IVCamSDK, you can play a video file, play a video device, play a buffer, perform screen capture, etc.

 

4. How to use

Part I - Virtual Camera Name
By default, VCam's device name is "e2eSoft VCam (WDM)", and capture filter's name is "e2eSoft VCam". You can change this by replacing the strings in VCam_WDM.inf file under [driver] folder:
VCam_WDM.DeviceDesc="e2eSoft VCam"
VCam_WDM.FriendlyName="e2eSoft VCam (WDM)"

[Attention]
The driver's digital certification will be invalid if you changed the .INF file, you need to sign the driver by youself in such a case.

Part II - Driver install / uninstall / Enable / Disable
VCam SDK provide two EXE files (devcon.exe and devcon64.exe) to install/uninstall its driver, it can be easily integrated with your application.

Install driver command: devcon.exe install driver\VCam_WDM.inf VCam_WDM
Uninstall driver command:
devcon.exe uninstall VCam_WDM
Enable the driver: devcon.exe enable VCam_WDM
Disable the driver: devcon.exe disable VCam_WDM
Restart the driver: devcon.exe restart VCam_WDM
Please replace devcon.exe with devcon64.exe when you're on 64bits OS.

NOTE: You need to restart the driver some times, for example, changing its default video size, FPS, etc. And if there’re some applications using VCam, you need to reboot your PC to take effect as well.

- How to install multi-VCam on one PC?

The default directshow device name of VCam SDK is "e2eSoft VCam (WDM)", You can add a webcam named "Cam01" by following steps:

1. Copy the "driver" folder (include the files in it) to another folder - "Cam01Driver", and enter this folder;
2. Rename all the files from "VCam_WDM.*" to "Cam01.*" (include sub folders);
3. Edit "Cam01.inf", replace "VCAM_WDM" with "CAM01" (case sensitive), and "VCam_WDM" with "Cam01" (not case sensitive);
4. Change device description and name: "e2eSoft VCam" to "Cam01 webcam", "e2eSoft VCam (WDM)" to "Cam01", then save it;

5. Under the parent folder of "Cam01Driver", run "devcon.exe install Cam01Driver\Cam01.inf Cam01" to install the dirver;
5. Now check the device manager to see whether there's a new webcam device added - which is "Cam01 webcam";
6. The VCamRenderer filter will find the first VCam deivce to use by default, and you can use "SetVCamDeviceName(_bstr_t("Cam01"))" to make it using the new webcam we just installed (For test, you can also set this in VCamRenderer filter's property page).

Part III - VCam COM object

Please check VCamCOMTest project’s source code to see how to use VCamSDK interface: IVCamSDK.
Because it’s a COM object, you can use it in other languages such as VB, Delphi, C#, etc.

 

Part IV - IVCamSDK interface
This interface is provided in an automation compatible .tlb file. To add it, you will have to import this file into your project.

For C++ developers, add the following lines to your projects
#import "VCamCOM.tlb" no_namespace, raw_interfaces_only exclude("UINT_PTR")

For the CLSIDs, add the following lines:
const CLSID CLSID_VCamSDK = {0x61E348C4,0xCEA8,0x48B6,{0xA7,0xAE,0x87,0xB6,0xD0,0x45,0x90,0xAE}};
const IID    IID_IVCamSDK = {0x7DA47CCB,0x2362,0x48AA,{0x98,0x96,0x52,0x0C,0xBE,0x44,0xEF,0xF7}};

Functions of IVCamSDK:

HRESULT SetLicenseCode([in] BSTR pRegStr);
Set license code of VCam SDK, if it's a valid license, the water mark (unregistered e2eSoft VCam) on output video will be removed.

HRESULT PlayVideoFile([in] BSTR fileName);
Play a video file to VCam, its video will be VCam’s video.

PROPERTY [get/put] ULONG CurrentVideoPosition;
Get or set current playing video file position, time unit is ms.

PROPERTY [get] ULONG CurrentVideoDuration;
Get current playing video file’s duration.

HRESULT PlayVideoDevice([in] long idx);
Play a video device to VCam, its video will be VCam’s video. Here idx is the index of video devices in system,

PROPERTY [get] VARIANT_BOOL IsPlaying;
Is VCam playing a video file or video device?

HRESULT StopPlay();
Stop video file / video device playing.

HRESULT PlayBuffer(in] unsigned char* rgb24Buffer, in] unsigned long width, in] unsigned long height);
Send a video frame to VCam driver, driver will use it as VCam current output. The format of rgb24Buffer is RGB24, here the buffer length must >= (width*24+31)/32*4*height.

HRESULT PlayBufferEx(in] VARIANT rgb24Buffer, in] unsigned long width, in] unsigned long height);
Just like PlayBuffer, but support automation, you should use this in C#/VB/Delphi instead of PlayBuffer, rgb24Buffer is a BYTE array, whose size must >= (width*24+31)/32*4*height.

HRESULT CaptureScreen(in] long x, in] long y, in] unsigned long width, in] unsigned long height);
Begin screen capturing, from point [x, y], with size: width x height.

HRESULT StopCaptureScreen();
Stop screen capture.

HRESULT ChangeDefaultFPS([in] unsigned long fps);
Set VCam default output video frame rate (1 ~ 30).

HRESULT ChangeDefaultVideoSize([in] unsigned char sizeType);
Set VCam default output video size type (standard ones, 0 ~ 15), the valid types (standard ones) are:
0 : 128 x 96
1 : 176 x 144
2 : 320 x 240 <default>
3 : 352 x 240
4 : 352 x 288
5 : 640 x 480
6 : 720 x 480
7 : 720 x 576
8 : 800 x 600
9 : 1024 x 768
10 : 1280 x 960
11 : 1280 x 1024
12 : 1366 x 768
13 : 1440 x 900
14 : 1600 x 1200
15 : 1920 x 1080

HRESULT SetVCamDeviceName([in] BSTR pDevName);
If you have installed several VCam on your system, use this function to select the one which you want to output video to.

HRESULT AddOverlay([in] VARIANT pRgb32Buffer, [in] ULONG width, [in] ULONG height, [in] LONG px, [in] LONG py, [in] ULONG whichOne);
Add an image overlay to current VCam video.
pRgb32Buffer: overlay image buffer, in RGB32 format (with alpha channel), size is [width x height], if it's NULL, this overlay (whichOne) will be removed;
px, py: overlay position, [0, 0] is left-top point;
whichOne: VCam support 5 image overlay (0~4).

HRESULT AddText(BSTR olText, BSTR ftName, [in] LONG ftSize, [in] LONG ftStyle, [in] LONG ftColor, [in] LONG bkColor, [in] LONG px, [in] LONG py, [in] LONG bkType, [in] LONG whichOne);
Add a text overlay to current VCam video.
olText: text to be overlayed;
ftName: font face name;
ftSize: font size;
ftStyle: 0, reserved for later use.
ftColor: text color;
bkColor: text background color;
px, py: overlay position, [0, 0] is left-top point;
bkType: 0 - transparent, 1 - use outline color, 2 - use background color, 3 - use a text band (for text scrolling);
whichOne: VCam support 5 text overlay (0~4).
Remarks:
If olText is NULL, this overlay (whichOne) will be removed.

HRESULT SetCustomSize([in] VARIANT_BOOL useCustomSize, [in] ULONG width, [in] ULONG height);
Set VCam custom size information.
useCustomSize: 1 means VCam will use [width * height] as its default video size, 0 means VCam will not use custom video size as its default video size (just use standard ones).
width, height range: [128 x 96] to [2048 x 1536].

PROPERTY [get/put] VARIANT_BOOL OnlyOneVideoSize;
Get or set whether VCam only supports one output video format.

Part V - VCam Renderer Filter

You can use it as a normal video renderer filter, and configure it or VCam driver through it using its interface: IVCamRenderConfig.

 

Part VI - IVCamRenderConfig interface
This interface is provided in an automation compatible .tlb file. To add it, you will have to import this file into your project.

For C++ developers, add the following lines to your projects
#import "VCamFilter.tlb" no_namespace, raw_interfaces_only exclude("UINT_PTR")

For the CLSIDs, add the following lines:
const CLSID CLSID_VCamRenderer = {0x8B9C4F32, 0x044E, 0x491c, {0x89, 0x3E, 0x36, 0x2C, 0xB8, 0xA6, 0x79, 0xD5}};
const IID IID_IVCamRenderConfig = {0xcc51ba60, 0x7659, 0x4970, {0xb3, 0x21, 0x7d, 0x44, 0x2b, 0xc2, 0x3e, 0x51}};

Functions of IVCamRendererConfig:

HRESULT SetLicenseCode([in] BYTE *pRegStr);
Set license code of VCam SDK, if it's a valid license, the water mark (unregistered e2eSoft VCam) on output video will be removed.

HRESULT GetCurrentVCamSize([out] long *width, [out] long *height);
Get current VCam output video size, it should be the last output video size VCam has been used.

HRESULT GetDefaultVCamSize([out] long *szType);
Get VCam default output video size type (0 ~ 15), the valid types (standard ones) are:
0 : 128 x 96
1 : 176 x 144
2 : 320 x 240 <default>
3 : 352 x 240

4 : 352 x 288
5 : 640 x 480

6 : 720 x 480
7 : 720 x 576
8 : 800 x 600
9 : 1024 x 768
10 : 1280 x 960
11 : 1280 x 1024
12 : 1366 x 768
13 : 1440 x 900
14 : 1600 x 1200
15 : 1920 x 1080

HRESULT GetDefaultFPS([out] long *fps);
Get VCam default output video frame rate, which is 25 by default.

HRESULT GetCustomSize([out] long *use_custom_size, [out] long *width, [out] long *height);
Get VCam custom size information.
use_custom_size: 1 means VCam is using [width * height] as its default video size, 0 means VCam is not using custom video size (using standard ones).

HRESULT GetOnlyOneSize([out] long *only_one_size) ;
Check whether VCam only supports one output video format (only_one_size 1 means yes, 0 means no).

HRESULT GetResizeParam([out] long *interlaced, [out] long *keep_aspect);
Get resize parameters currently used in VCam Renderer filter.

HRESULT SetDefaultVCamSize([in] long szType);
Set VCam default output video size type (standard ones, 0 ~ 15).

HRESULT SetDefaultFPS([in] long fps);
Set VCam default output video frame rate (1 ~ 30).

HRESULT SetCustomSize([in] long use_custom_size, [in] long width, [in] long height);
Set VCam custom size information.
use_custom_size: 1 means VCam will use [width * height] as its default video size, 0 means VCam will not use custom video size as its default video size (just use standard ones).
width, height range: [128 x 96] to [2048 x 1536].

HRESULT SetOnlyOneSize([in] long only_one_size) ;
Set whether VCam only supports one output video format (only_one_size 1 means yes, 0 means no).

HRESULT SendFrameToDriverEx([in] BYTE *pBits, [in] long width, [in] long height);
Send a video frame to VCam driver, driver will use it as VCam current output. The format of pBits is RGB24, size: width * height. pBits size must >= (width*24+31)/32*4*height.

HRESULT SetResizeParam([in] long interlaced, [in] long keep_aspect);
VCam renderer will resize its input video to VCam driver needed.
interlaced: 1 means input video is interlaced and the renderer will de-interlace it, do nothing if 0.
keep_aspect: 1 means keep aspect when resizing, 0 means stretch input video to VCam video size.

HRESULT SetVCamDeviceName(BSTR devName);
If there're several VCam devices installed, you can use this function to select the one which you want to output video to.

HRESULT AddOverlay([in] VARIANT pRgb32Buffer, [in] ULONG width, [in] ULONG height, [in] LONG px, [in] LONG py, [in] ULONG whichOne);
Add an image overlay to current VCam video.
pRgb32Buffer: overlay image buffer, in RGB32 format (with alpha channel), size is [width x height], if it's NULL, this overlay (whichOne) will be removed;
px, py: overlay position, [0, 0] is left-top point;
whichOne: VCam support 5 image overlay (0~4).

HRESULT AddText(BSTR olText, BSTR ftName, [in] LONG ftSize, [in] LONG ftStyle, [in] LONG ftColor, [in] LONG bkColor, [in] LONG px, [in] LONG py, [in] LONG bkType, [in] LONG whichOne);
Add a text overlay to current VCam video.
olText: text to be overlayed;
ftName: font face name;
ftSize: font size;
ftStyle: 0, reserved for later use.
ftColor: text color;
bkColor: text background color;
px, py: overlay position, [0, 0] is left-top point;
bkType: 0 - transparent, 1 - use outline color, 2 - use background color, 3 - use a text band (for text scrolling);
whichOne: VCam support 5 text overlay (0~4).
Remarks:
If olText is NULL, this overlay (whichOne) will be removed.

 

5. Build sample application

To build sample application VCamFilterTest, you need platform SDK. If you don't have it, you can use the BaseClasses project in the SDK package (BaseClasses.zip), extract it to a folder and add this folder to VC include path, then build this project, it will generate the LIB file "strmbase.lib", which is needed to link with sample application.

 

6. License

You can try VCam SDK freely without any limitation, except that there's a water mark in the virtual camera output video, you may purchase VCam SDK to remove it.

Please contact us if you want to buy it or have any advice, question, etc.

Our website: www.e2esoft.cn
Mail: vcam@e2esoft.cn

e2eSoft.cn
All right reserved