This page describes the use of the Virtual Video C Library to communicate with the Camera Server and PTZ Server in the Virtual Video mod. Before reading the following documentation, users should review the architecture of the Virtual Video Tool described here, and may also wish to view the documentation for the underlying network protocol for a better understanding of how the library is implemented.

The C Library is based on the Windows Sockets 2 API, and is distributed as a single static lib file VVClient.lib and header file VVClient.h. To use the library, your application should specify #include "VVClient.h" and link to both VVClient.lib and ws2_32.lib (the Windows Sockets 2 static library). The Virtual Video C library can be downloaded here. Included in this package is the source code (in the samples directory) for a simple Camera/PTZ client that you can use as a basis for building your own clients.

The C Library functions are divided into three major groups: initialization and uninitialization of the library (functions prefixed with VV), communication with the Camera Server (functions prefixed with Cam) and communication with the PTZ Server (functions prefixed with PTZ). Each client connection to the Camera Server is represented by a VVCamera structure. All Cam* functions take a pointer to the VVCamera structure representing the camera to which the command is applied. Similarly, each client connection to the PTZ Server is represented by a VVPTZStatus structure. All PTZ* functions take a pointer to the VVPTZStatus structure representing the controller to which the command is applied.

To implement an actively controlled PTZ camera, call CamSetType on a connected camera, passing VV_TRUE to the ptzControl parameter and a unique integer identifier to the ptzID parameter. Then, call PTZSetID on a controller client, passing the same identifier in the ptzID parameter. Subsequent motion commands sent by the PTZ client will be applied to the camera with the matching identifier. Note that applications involving static cameras are not required to call any of the PTZ* library functions.

A minimal client application would call the following sequence of functions:

• Initialize the Windows Sockets 2 library with VVInitialize.
• Instantiate a new VVCamera structure and connect to the default camera (camID = 0) on the Camera Server by calling CamConnect. This function also fills out the VVCamera structure with the default camera settings retrieved from the server. If implementing active control, instantiate a new VVPTZStatus structure and connect to the default controller (ptzID = 0) on the PTZ Server by calling PTZConnect.
• Create a new camera by calling CamSetID and passing a unique non-zero identifier to the camID parameter. CamSetID fills out the VVCamera structure with the new camera settings retrieved from the server. Note that this step is not necessary if you only intend to use one camera, ie. the default camera (camID = 0).
• Change the appropriate default settings by calling CamSetType, CamSetIntrinsicParameters and CamSetExtrinsicParameters, passing the VVCamera structure instantiated above. If active control is required, the call to CamSetType should specify VV_TRUE for ptzControl and a ptzID corresponding to an existing controller (eg. the default controller, ptzID = 0).
• In the main processing loop, retrieve new frames by calling CamGetLatestFrame, and send PTZ commands to the camera by calling VVPTZSetStatus. The latest frame can be read from the image field of the VVCamera structure.
• Before exiting the application, disconnect from the servers by calling CamDisconnect and PTZDisconnect, passing the VVCamera and VVPTZStatus structures instantiated above.
• Uninitialize the Windows Sockets 2 library with VVUninitialize.

The following C code excerpt implements the above minimal behaviour:

VVCamera camera;
VVPTZStatus ptzStatus;
const VVCAMID camID = 1;
const VVPTZID ptzID = 0;

VVInitialize();
CamConnect(&camera, "hostname");
PTZConnect(&ptzStatus, "hostname");

CamSetID(&camera, camID);
CamSetType(&camera, VV_STDCAM, VV_TRUE, ptzID, NULL);
CamSetIntrinsicParameters(&camera, ...);
CamSetExtrinsicParameters(&camera, ...);

while (...)
{
   CamGetLatestFrame(&camera, VV_TRUE);
   ... do some processing on camera.image
   PTZSetStatus(&ptzStatus, ...);
}

PTZDisconnect(&ptzStatus);
CamDisconnect(&camera);
VVUninitialize();

The following sections detail the structures and functions implemented by the C Library.

Socket Wrapper Functions:

• VVInitialize
• VVUninitialize

Camera Server Structures and Functions:

• VVCamera structure
• VVGtCent/VVGtBbox/VVGtTarget structure
• CamConnect
• CamDisconnect
• CamGetID
• CamSetID
• CamGetType
• CamSetType
• CamGetIntrinsicParameters
• CamSetIntrinsicParameters
• CamGetExtrinsicParameters
• CamSetExtrinsicParameters
• CamGetLatestFrame

PTZ Server Structures and Functions:

• VVPTZStatus structure
• PTZConnect
• PTZDisconnect
• PTZGetID
• PTZSetID
• PTZGetStatus
• PTZSetStatus
• PTZGetAutoScan
• PTZSetAutoScan