Framegrab adds two classes to PHP. FrameGrabDevice represents a video capture device and FrameGrabImage an image captured with a FrameGrabDevice.

You can create a new FrameGrabDevice for the default video capture device as follows:

	$device = new FrameGrabDevice();

The extension will iterate through available video devices until it finds one that supports video capture. A FrameGrabDeviceException will be thrown either if no video devices are available or if the available video devices do not support video capture.

You can supply an argument to the constructor (see below) if you want to initialise a specific video device. In this case the FrameGrabDeviceException will be thrown if that specific device does not exist or does not support video capture.

	$device = new FrameGrabDevice('/dev/video1');

Once you have a device you can then grab an image using the grab() method. The method takes no arguments and returns a FrameGrabImage object or false on error. As the FrameGrabImage constructor is a protected method you cannot create objects directly using new.

Once you have the image you can either save the image to the file in PNG format or have it returned as a string in PNG format using the writeAsPNG() and toStringAsPNG() methods respectively. The former takes a filename as the sole argument and returns false on error. The latter takes no arguments and returns either the PNG data as a string or false on error.

The two objects also support a number of properties. The code below demonstrates the extension in use. It returns an image captured from the default video device as a PNG. The image has capture device and image meta data embedded in it visible in the top left corner of the image.

<?php
 
try {
	// Get the default frame grabber device.  Throws an exception if a device
	// cannot be found.
	$device = new FrameGrabDevice();
 
	// Grab am image.
	$fgimage = $device->grab();
	if ($fgimage) {
		// Create a GD image from a frame grab image
		$gdimage = imagecreatefromstring($fgimage->toStringAsPNG());
 
		// Output data about the image on to the image
		$font  = 1;
		$black = imagecolorallocate($gdimage, 0, 0, 0);
		$fh    = imagefontheight($font);
		$x     = 10;
		$y     = 10;
		imagestring($gdimage, $font, $x, $y, "Device: ".$device->device, $black);
		$y += $fh;
		imagestring($gdimage, $font, $x, $y, "Card: ".$device->card, $black);
		$y += $fh;
		imagestring($gdimage, $font, $x, $y, "Width: ".$fgimage->width, $black);
		$y += $fh;
		imagestring($gdimage, $font, $x, $y, "Height: ".$fgimage->height, $black);
		$y += $fh;
		imagestring($gdimage, $font, $x, $y, "Format: ".$fgimage->format, $black);
		$y += $fh;
		imagestring($gdimage, $font, $x, $y, "Bytes per line: ".$fgimage->bytes_per_line, $black);
 
		// Output the image
		header('Content-Type: image/png');
		imagepng($gdimage);
		imagedestroy($gdimage);
	}
} catch (Exception $e) {
	// Handle the FrameGrabDevice exception here.
}
 
?>

The extension is available at the PECL site.