How-To: Installing and Using Framecap

Set Up and Test

  1. Unzip the archive.

  2. Plug in a webcam.

  3. Double-click the program called framecap.exe to launch framecap. You should get a window with two rectangles. The rectangle on the right will be black, but the one on the left should show a preview video from the webcam.

  4. Open a DOS window and navigate to the directory containing framecap.

  5. Execute fgDLLUser.exe from the DOS commandline. Two things should happen. fgDLLUser should print a message every half second saying it's captured a frame. You should see these captured frames in the right window of framecap.

  6. Use ctl-c to terminate fgDLLUser.

If steps 1-5 succeed, framecap works on your system.

 

Determining Capture Rate

You can check the throughput rate of your system with the program fgClientStats.

Do steps 1-4 above. Then launch Task Manager and open the CPU-usage tab. Run fgClientStats.exe from the DOS commandline. This program captures 1000 frames then tells you the average capture rate. It will take a minute or so to complete. While it runs, read off CPU usage to see what percent it uses. When it finishes, read off your system's frame rate from the DOS window.

If CPU was less than 90% or so, framecap is able to keep up with your video feed. Either the camera or your data input port is the limiting factor for how many frames you can capture per second, not framecap.

If CPU is up near 100%, framecap may not be keeping up with your video input. And there's certainly not much processing power left over. However, that's not necessarily a problem. framecap only captures frames when asked, so if you're happy with significantly less than the maximum frame rate, framecap may still work for you. But if you need to capture and process every frame that comes in, you may want to use a hardware framegrabber, faster CPU, or both.

 

Evaluating CPU Overhead

After fgClientStats finishes, you can use Task Manger again to get a rough idea of the CPU overhead of framecap when it's not capturing frames.

To minimize CPU overhead during use, toggle off the preview and capture views. (You can toggle these on and off from the View menu.) Toggle off the preview and then read off CPU usage to get a baseline for CPU overhead. This is roughly the CPU cost of using framecap rather than a hardware framegrabber.

 

Using FrameCap

The easiest way to use framecap is through fgClient.dll. This dll handles all the communication details and just gives you frame data. The dll has four functions: 

int getWidth();
int getHeight();
int getFrameSize();
int getFrame(BYTE * pBuf, int lBuf);

The first two functions return the width and height of individual frames. getFrameSize() returns the size, in bytes, of the buffer needed for captured frames. getFrame() captures a frame.

To capture frames,

  1. Load fgClient.dll.

  2. Call getFrameSize() to find the number of bytes needed for the capture buffer.

  3. Allocate an array, of type BYTE, for the capture buffer.

  4. Call getFrame() each time you want to capture a new frame, passing it the capture buffer and the buffer length for each frame to be captured.

For an example of how to use the dll, see the C source code for fgDLLUser, included in the framecap download.

If you don't want to use this dll, you can write your own client interface to framecap. You may find the header file fgcomm.h useful for doing that.

 

Data Format

The format for frame data is a packed byte array. There are three bytes per pixel. The first byte is the blue value, second is green, third is red. Pixels are ordered row by row, starting at the bottom of the image. The following illustrates how a captured frame can be expanded into an RGB matrix: 

unsigned int rgb[WIDTH][HEIGHT][3];

for(int iY=0; iY<HEIGHT; iY++) {
  for(int iX=0; iX<WIDTH; iX++) {
    int iPx  = iX + iY*WIDTH;  // pixels are arranged row by row
    int iBuf = 3*iPx;          // each pixel uses 3 bytes

    rgb[iX][iY][2] = (unsigned int)pBuf[iBuf];     // blue value
    rgb[iX][iY][1] = (unsigned int)pBuf[iBuf + 1]; // green value
    rgb[iX][iY][0] = (unsigned int)pBuf[iBuf + 2]; // red value
  }
}

 

Features and Limitations

Selecting an input device.
When framecap starts, the compatible video input devices connected to your PC are listed under the Device menu. Framecap connects to the first device in this list at startup. You can change the video input source by selecting from the Device menu.

Framecap doesn't currently detect when devices are added or removed after it starts. So, if you plug in a second webcam after starting framecap, you'll need to restart the program to capture from it. Also, if you remove an input device while framecap is running, it won't remove that input from the Device menu until it's been restarted. I didn't include the ability to respond to device connections at runtime because I didn't need it. I only have one webcam, so I also don't have a good way to test it myself even if I were to add it. If you want this capability and are willing to help out by testing, please let me know.

Changing driver settings.
You can change video driver settings from the Options menu. One caution with this. Your driver's options may allow you to change image size. This type of change affects the size requirement for the capture buffer, and there's currently no mechanism for alterting the client that such a change has occured. So, unless you add some method for detecting and handling this sort of change in your client code, be sure you only change frame sizes when your client isn't running. (This caution applies also when changing the video input source.)

Toggling preview and capture display.
By default, both the incoming video stream and the captured frames are displayed. These displays are useful for testing and debugging, but they do consume CPU cycles. For best performance, toggle these displays off when you don't need them. You can toggle the preview and capture displays from the View menu.

Number of instances.
Currently, only one instance of framecap is allowed to run at a time. The dll also limits its client count to one.

 
Home | Framecap