The Frame Buffer
Some digital-video devices support video-digitizer hardware. The digitalvideo device class creates an abstract model of this hardware as a "frame buffer" and a "lock mask." The frame buffer is a region of device memory that can hold a single full-screen image. You can determine the size of the frame buffer with the where frame max command.
The lock mask is an array with one bit for each pixel of the frame buffer. You can modify the lock mask with the freeze and unfreeze commands. These commands let you specify rectangular regions where the lock mask bits should be turned on or off. A sequence of such commands can yield arbitrarily complex patterns of locked bits. Devices that do not have hardware support for a lock mask should reject commands that specify a rectangle on a freeze or unfreeze command. (You can use capability can lock to determine if a device supports a lock mask.)
The following illustration shows the model used for digital-video devices:
In the digital-video model, the frame buffer is off screen. You specify what is displayed with the put source and put destination commands. The put source command specifies a source rectangle in the frame buffer. The put destination command specifies a destination rectangle relative to the client window. For display, the device scales the visual content of the source rectangle to fit the destination rectangle. By default, the source rectangle is the entire image in the frame buffer, and the destination rectangle is the entire client area of the current window. That is, if you have never used a put command, the device scales the entire image to fit in the current window.
The put command also lets you control how the device places the digitized information into the frame buffer. The put video rectangle specifies the region of the external input's active scan area used when the device digitizes the image. The video rectangle defaults to the entire external input (that is, full screen). The put frame rectangle specifies the region within the frame buffer where the device places the digitized image. This rectangle defaults to the full size of the frame buffer. If you use the default regions for both the video and frame rectangles, the digitizer stores the full-screen video in the full-screen frame buffer. Full-size video and frame rectangles are commonly used when the hardware can resize images while copying from the frame buffer to the destination rectangle. (Devices that can resize images return true to the capability can stretch command.)
The hardware might also support stretching while digitizing. (These devices return true for the capability can stretch input command.) When using such hardware, an application might use the put frame rectangle to have the hardware scale the image to the right size as it places the image in the frame buffer.
Some devices might be incapable of supporting an abstract frame buffer for each device-driver instance. These devices should treat the digitizer hardware as a resource that is typically only accessed by a single device-driver instance. Multiple instances can access a common frame buffer, but only by specifying the shareable flag with the open command.
The frame buffer concept originated in support of the overlay device class. Hence, its description uses the assumption that pixels stored in the frame buffer come from the external input. However, the concept of a frame buffer and a lock mask is also useful during playback of motion video and images. Therefore, video playback supports commands such as put, freeze, and unfreeze.