# VCam SDK Help

## INTRODUCTION

VCam SDK is a SDK of e2eSoft VCam software, which allows you to add virtual camera feature to your application.

### Files list:

- [doc] - This document.
- [driver] - VCam driver files (for Windows versions earlier than Win10 v1703).
- [driver_win10] - VCam driver files (only for Windows 10 or higher ).
- [x64] - Files for 64bits applications.
- AMCap.exe - Test application to view webcam video.
- devcon.exe - A command-line version of Device Manager, which enables, disables, installs, configures, and removes devices on the local computer.
- VCamRenderer.ax - A directshow renderer filter which can redirect its input video to VCam driver and also defines the IVCamRenderer interface which includes all SDK functions.
- VCamDemo.exe - VC++ demo application to show how to use VCam SDK in C++.
- VCamDemoCS.exe - C# demo application to show how to use VCam SDK in C#.
- DirectShowLib-2005.dll - DirectShow.NET, used by C# demo application.
- VCamDemos.zip - Source code for demo applications.
- install.bat - Install VCam driver and all components.
- uninstall.bat - Uninstall VCam driver and all components.

### Distribution files

- [driver] - For Windows versions earlier than 10.
- [driver_win10] - For Windows 10 or higher.
- devcon.exe - Used to install/uninstall the driver, please use x64\devcon.exe on 64bits OS.
- VCamRenderer.ax - Register on target system, please use x64\VCamRenderer.ax for 64bits applications or .NET applications running on 64bits OS.

## GETTING STARTED

1. Install VCam driver and register filter - run install.bat as administrator;
2. Run VCamDemo.exe and play a video file in it, then use other applications (for example AMCap.exe) to see the video of webcam named "Virtual Camera";
3. Run VCamDemoCS.exe and play a video file in it, then use other applications (for example AMCap.exe) to see the video of webcam named "Virtual Camera";
4. Extract VCamDemos.zip file and open the VC++, C# demo projects to see how to use it.

NOTE: You should install some video codecs if the video files can't be played, for example LAVFilters.

## HOW IT WORKS

### Using DirectShow

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

2: Play a video file with VCam Renderer filter in graphedit - just like using the default one:

3. The video was sent to Virtual Camera:

From this we can see that it's very easy to play a video file to VCam using directshow, and you can also play a video capture device, a video stream, an image file or any other video sources to VCam with directshow easily.

### Using IVCamRenderer COM interface

Besides directshow, you can also use the IVCamRenderer COM interface to send video frames directly to VCam driver and do more. Please check the demo applications for details.

## USAGE

### Driver install/uninstall/enable/disable/restart

VCam SDK uses devcon.exe to install/uninstall the driver, it can be easily integrated with your applications.

- Install command: devcon.exe install driver\VCamSDK.inf VCamSDKDevice
- Uninstall command: devcon.exe uninstall VCamSDKDevice
- Enable command: devcon.exe enable VCamSDKDevice
- Disable command: devcon.exe disable VCamSDKDevice
- Restart command: devcon.exe restart VCamSDKDevice

NOTE: You need to run these commands as administrator.
Please use x64\devcon.exe for 64bits OS.

### Install multiple instances of VCam

Calling install command multiple times to install multiple VCam instances, and they will have the same name at first (you can change their names later).
The SDK will use the first VCam instance by default, and you can call SetCurrentDevice to choose which one to be used.

Uninstall: calling unistall command once will remove all VCam instances.

### VCam Renderer filter

You can use it as a normal directshow video renderer, or change VCam settings using its COM interface: IVCamRenderer.
Please use x64\VCamRenderer.ax if your applications is 64bits, or .NET applications running on 64bits OS.
An easy way to make things right is to register 32bits VCamRenderer.ax on 32bits OS, and both 32bits and 64bits VCamRenderer.ax on 64bits OS.

### IVCamRenderer COM interface

For C++ developers, add the following line to your projects:
#import "VCamRenderer.tlb" no_namespace, raw_interfaces_only exclude("UINT_PTR")
and add the "VCamRenderer_i.c" file in VCamDemo project for the CLSIDs.

For C# developers, add the wrapper class "VCamRenderer.cs" file in VCamDemoCS project to your projects.

For other programming languages, please refer the C++/C# demo projects.

It's highly recommended to study the demo projects to learn how to use it.

#### FUNCTIONS:

- HRESULT SetCurrentDevice([in] BSTR friendly_name);
  Choose which VCam to be used if there're multiple instances installed.
- HRESULT SetOutputFormat([in] long width, [in] long height, [in] long fps, [in] long format, [in] long one_size_only);
  Set VCam output video size (even, width*height >= 320x240), and frame rate (negative number means using the source frame rate);
  format: 1 - RGB24; 2 - YUY2; others - RGB and YUY2;
  one_size_only: 0 - output 320x240, 640x480 and [width] x [height]; others - [width] x [height] only.
- HRESULT GetOutputFormat([out] long *width, [out] long *height, [out] long *fps, [out] long* format, [out] long* one_size_only);
  Get VCam output video size (640x480 by default), and frame rate (25 by default).
- HRESULT SetFillMode([in] long fill_mode);
  Set video resize method (0: Aspect fit, 1: Aspect fill, 2: Stretch), used when input frame size differes from VCam output size.
- HRESULT GetFillMode([out] long *fill_mode);
  Get current video resize method (see above).
- HRESULT SetMirror([in] long mirror);
  Mirror the output video (0: no mirror, others: mirror), non-persistent.
- HRESULT SetFlip([in] long flip);
  Vertical flip the output video (0: no flip, others: flip), non-persistent.
- HRESULT SetRotateRight([in] long rotate);
  Rotate the input video 90° (0: no rotate, others: rotate), non-persistent.
- HRESULT SendFrame([in] const unsigned char* i_rgb24_pixels, [in] long i_width, [in] long i_height, [in] long i_stride);
  Send a RGB24 format video frame to driver.
  Driver will use (i_width*24+31)/32*4 as stride if i_stride was set to 0.
  Set a negative i_height if the video is vertical flipped.
  Set i_rgb24_pixels, i_width or i_height to 0 will clear device output and show the idle image.
- HRESULT SendFrame32([in] const unsigned char* i_rgb32_pixels, [in] long i_width, [in] long i_height, [in] long i_stride);
  Same as SendFrame, but with RGB32 format.
  Driver will use i_width*4 as stride if i_stride was set to 0.
  Set a negative i_height if the video is vertical flipped.
- HRESULT SendFrameYUY2([in] const unsigned char* i_yuy2, [in] long i_width, [in] long i_height, [in] long i_stride);
  Same as SendFrame, but with YUY2 format.
  Driver will use i_width*2 as stride if i_stride was set to 0.
- HRESULT SendFrameNV12([in] const unsigned char* i_nv12, [in] long i_width, [in] long i_height, [in] long i_stride);
  Same as SendFrame, but with NV12 format.
  Driver will use i_width as stride if i_stride was set to 0.
- HRESULT SendFrameEx([in] VARIANT i_rgb24_array, [in] long i_width, [in] long i_height);
  Send a RGB24 format video buffer to driver, with a VARIANT SAFEARRAY as parameter.
- HRESULT CaptureScreen([in] long i_x, [in] long i_y, [in] long i_width, [in] long i_height);
  Capture region of screen and set it as VCam output.
- HRESULT SetConnectionNotificationEvent([in] __int64 i_handle);
  Set an auto-reset event handle to driver, and it will be signaled when other applications open or close VCam device.
- HRESULT GetConnectedCount([out] long * o_count);
  Get the count of applications using VCam (No matter playing or not).
- HRESULT IsOpened();
  Check whether the device is being used by other applications, returns S_OK means being used.
- HRESULT Snapshot([in] BSTR filename);
  Save the next video frame (to be sent to driver) to a bitmap file, asynchronously.
- HRESULT SetIdleFileName([in] BSTR file_name);
  Set a 24bits bitmap file as VCam default idle image, which will be displayed when nothing is being played.
  Call it with NULL parameter or an empty string will reset it to the default one.
  The image will be resized (aspect fit) only if it's bigger than VCam output size.
- HRESULT SetFriendlyName([in] BSTR friendly_name);
  The device's name is "Virtual Camera" by default, and you can use it to set a different name.
  The best way to rename is to modify the driver's .INF file, but you'll have to sign the driver with a Kernel-Mode Code Signing Certificates.
- HRESULT SetLicenseCode([in] BSTR license_code);
  You can set license code here if you've purchased VCam SDK. The water mark (TRIAL) will be removed with a valid license, and call it with a wrong one will show the watermark again.
  You only need to call it once for one PC.

## LICENSE AGREEMENT

We own all the intellectual property rights of the VCam SDK and ensure that it does not contain any viruses or spyware.
Products that use the licensed VCam SDK are free to distribute without any restrictions.
The license code can only be used in your or your company's products.
It is forbidden to spread or resell the license code.
You will get the maximum punishment within the bounds of the law if you violate this rule.

Please contact us if you want to buy it or have any questions.

Our website: www.e2esoft.com

© e2eSoft, all rights reserved.