AVICap You can easily incorporate video capture capabilities into your application by using the AVICap window class. AVICap provides applications with a simple, message-based interface to access video and waveform-audio acquisition hardware and to control the process of streaming video capture to disk. AVICap supports streaming video capture and single-frame capture in real-time. In addition, AVICap provides control of video sources that are Media Control Interface (MCI) devices so the user can control (through an application) the start and stop positions of a video source, and augment the capture operation to include step frame capture. The windows you create by using the AVICap window class can perform the following tasks: - Capture audio and video streams to an audo-video interleaved (AVI) file - Connect and disconnect video and audio input devices dynamically - View a live incoming video signal by using the overlay or preview methods - Specify a file to use when capturing and copy the contents of the capture file to another file - Set the capture rate - Display dialog boxes that control the video source and format - Create, save, and load palettes - Copy images and palettes to the clipboard - Capture and save a single image as a device-independent bitmap (DIB) Video capture digitizes a stream of video and audio data, and stores it on a hard disk or some other type of persistent storage device. This section describes how to add a simple form of video capture to an application using three statements of code. It also describes how to end or abort a capture session by sending messages to the capture window. An AVICap capture window handles the details of streaming audio and video capture to AVI files. This frees your application from involvement in the AVI file format, video and audio buffer management, and the low-level access of video and audio device drivers. AVICap provides a flexible interface for applications. You can add video capture to your application, using only the following lines of code: hWndC = capCreateCaptureWindow ( "My Own Capture Window", WS_CHILD | WS_VISIBLE , 0, 0, 160, 120, hwndParent, nID); SendMessage (hWndC, WM_CAP_DRIVER_CONNECT, 0 /* wIndex */, 0L); SendMessage (hWndC, WM_CAP_SEQUENCE, 0, 0L); A macro interface is also available that provides an alternative to using the SendMessage function and improves the readability of an application. The following example uses the macro interface to add video capture to an application. hWndC = capCreateCaptureWindow ( "My Own Capture Window", WS_CHILD | WS_VISIBLE , 0, 0, 160, 120, hwndParent, nID); capDriverConnect (hWndC, 0); capCaptureSequence (hWndC); After your application creates a capture window of the AVICap window class and connects it to a video driver, the capture window is ready to capture data. At this point, your application can simply send the WM_CAP_SEQUENCE message (or the capCaptureSequence macro) to begin capturing. Using default settings, WM_CAP_SEQUENCE initiates the capture of video and audio input to a file named CAPTURE.AVI. Capture continues until one of the following events occurs: - The user presses the ESC key or a mouse button - Your application stops or aborts capture operation - The disk becomes full In an application, you can stop streaming captured data to a file by sending the WM_CAP_STOP (or the capCaptureStop macro) message to a capture window. You can also abort the capture operation by sending the WM_CAP_ABORT message (or the capCaptureAbort macro) to a capture window. By modifying one or more of the capture parameters defined in the CAPTUREPARMS structure, you can perform the following tasks: - Change the frame capture rate - Specify keyboard or mouse control for ending a capture session - Specify a duration for a capture session typedef struct { DWORD dwRequestMicroSecPerFrame; BOOL fMakeUserHitOKToCapture; UINT wPercentDropForError; BOOL fYield; DWORD dwIndexSize; UINT wChunkGranularity; BOOL fUsingDOSMemory; UINT wNumVideoRequested; BOOL fCaptureAudio; UINT wNumAudioRequested; UINT vKeyAbort; BOOL fAbortLeftMouse; BOOL fAbortRightMouse; BOOL fLimitEnabled; UINT wTimeLimit; BOOL fMCIControl; BOOL fStepMCIDevice; DWORD dwMCIStartTime; DWORD dwMCIStopTime; BOOL fStepCaptureAt2x; UINT wStepCaptureAverageFrames; DWORD dwAudioBufferSize; BOOL fDisableWriteCache; UINT AVStreamMaster; } CAPTUREPARMS; The capture rate is the number of frames that are captured each second of a capture session. You can retrieve the current capture rate by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). The current capture rate is stored in the dwRequestMicroSecPerFrame member of the CAPTUREPARMS structure. You can set the capture rate by specifying the number of microseconds between successive frames as the value of this member, then sending the updated CAPTUREPARMS structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro). The default value of dwRequestMicroSecPerFrame is 66667, which corresponds to 15 frames per second. You can allow the user to abort a capture session by pressing a key or keystroke combination from the keyboard, or by pressing the right or left mouse button. If the user aborts a real-time capture session, the contents of the capture file are discarded. If the user aborts a step-frame capture session, the contents of the capture file up to the point of aborting the capture are saved. You can retrieve the settings for aborting a capture session by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). The current keystroke setting is stored in the vKeyAbort member of the CAPTUREPARMS structure; the current mouse settings are stored in the fAbortLeftMouse and fAbortRightMouse members. You can set a new key or keystroke combination by specifying the keycode or keycode combination (as in a CTRL or SHIFT key combination) as the value of vKeyAbort, or set the left or right mouse button as the abort key by specifying the fAbortLeftMouse or fAbortRightMouse member. After you set these members, send the updated CAPTUREPARMS structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro). The default value of vKeyAbort is VK_ESCAPE. You must call the RegisterHotKey function before specifying a keystroke that can abort a capture session. The default values of fAbortLeftMouse and fAbortRightMouse are TRUE. You can limit the duration of a capture operation by using the fLimitEnabled and wTimeLimit members of the CAPTUREPARMS structure. The fLimitEnabled member indicates whether the capture operation is to be timed, while wTimeLimit specifies the maximum duration of the capture operation. You can retrieve the values for fLimitEnabled and wTimeLimit by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). You can enable a timer for the capture operation by specifying TRUE as the value of fLimitEnabled, or you can set the duration of the capture operation by specifying a value, in seconds, for wTimeLimit. After you set these members, send the updated CAPTUREPARMS structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro). The default value of fLimitEnabled is FALSE. Capture windows are conceptually similar to standard controls (such as buttons, list boxes, or scroll bars). Typically, capture windows use the WS_CHILD and WS_VISIBLE window styles. You can create a capture window of the AVICap window class by using the capCreateCaptureWindow function. HWND VFWAPI capCreateCaptureWindow ( LPCSTR lpszWindowName, DWORD dwStyle, int x, int y, int nWidth, int nHeight, HWND hWnd, int nID ); This function returns a window handle that identifies the capture window and is used by an application to send subsequent messages to the window. You can create one or more capture windows in an application and connect each capture window to a different capture device. You can dynamically connect or disconnect a capture window to a capture driver. You can connect or associate a capture window with a capture driver by using the WM_CAP_DRIVER_CONNECT message (or the capDriverConnect macro) BOOL capDriverConnect ( hwnd, iIndex ); After a capture window and capture driver are connected, you can send device-specific messages to the capture driver associated with a capture window. If you have more than one capture device installed on a system, you can connect a capture window to a particular video capture device driver by specifying an integer for the wParam parameter of the WM_CAP_DRIVER_CONNECT message. The integer is an index that identifies a video capture driver listed in the registry or in the [drivers] section of the SYSTEM.INI file. Use zero for the first index entry. You can retrieve the name and version of an installed capture driver by using the the capGetDriverDescription function. Your application can use this function to enumerate the installed capture devices and drivers, so the user can select a capture device to connect to a capture window. You can retrieve the name of the capture device driver connected to a capture window by using the WM_CAP_DRIVER_GET_NAME message (or the capDriverGetName macro). To retrieve the version of an installed capture driver, use the WM_CAP_DRIVER_GET_VERSION message (or the capDriverGetVersion macro). You can disconnect a capture window from a capture driver by using the WM_CAP_DRIVER_DISCONNECT message (or the capDriverDisconnect macro). When an capture window is destroyed, any connected video capture device drivers are automatically disconnected. Some system-level messages, such as WM_PALETTECHANGED and WM_QUERYNEWPALETTE, are sent only to top-level and overlapped windows. If a capture window is a child window, its parent must forward these messages. Similarly, if the parent window changes size, it might need to send notification messages to the capture window. Conversely, if the dimensions of the captured video change, the capture window might need to send notification messages to the parent window. The simplest way to manage this is to always keep the capture window dimensions equal to the size of the captured video stream, notifying the parent whenever these dimensions change. You can retrieve the current status of a capture window by using the WM_CAP_GET_STATUS message (or the capGetStatus macro). This message retrieves a copy of the CAPSTATUS structure with the current values of its members: typedef struct { UINT uiImageWidth; UINT uiImageHeight; BOOL fLiveWindow; BOOL fOverlayWindow; BOOL fScale; POINT ptScroll; BOOL fUsingDefaultPalette; BOOL fAudioHardware; BOOL fCapFileExists; DWORD dwCurrentVideoFrame; DWORD dwCurrentVideoFramesDropped; DWORD dwCurrentWaveSamples; DWORD dwCurrentTimeElapsedMS; HPALETTE hPalCurrent; BOOL fCapturingNow; DWORD dwReturn; UINT wNumVideoAllocated; UINT wNumAudioAllocated; } CAPSTATUS; The CAPSTATUS structure contains information regarding the dimensions of the image, scroll position, and whether overlay or preview of the image is enabled. Because the information represented in CAPSTATUS is dynamic, your application should refresh the contents of the structure whenever the size or format of the captured video stream might have changed (such as after displaying the video format of the capture driver). Changing the dimensions of the capture window has no effect on the dimensions of the actual captured video stream. The format dialog box displayed by the video capture device driver controls the dimensions of the captured video stream. A capture driver and the underlying hardware can dictate several aspects of video capture, including acceptable video sources, display options, formats, and compression options. An audio driver specifies the audio format and an optional compression option used with captured audio data. You can retrieve the hardware capabilities of the currently connected capture driver by using the WM_CAP_DRIVER_GET_CAPS message (or the capDriverGetCaps macro). This message returns the capabilities of the capture driver and underlying hardware in the CAPDRIVERCAPS structure. Each capture driver can provide up to four dialog boxes to control aspects of the video digitization and capture process, and to define compression attributes used in reducing the size of the video data. The contents of these dialog boxes are defined by the video capture driver. The Video Source dialog box controls the selection of video input channels and parameters affecting the video image being digitized in the frame buffer. This dialog box enumerates the types of signals that connect the video source to the capture card (typically SVHS and composite inputs), and provides controls to change hue, contrast, or saturation. If the dialog box is supported by a video capture driver, you can display and update it by using the WM_CAP_DLG_VIDEOSOURCE message (or the capDlgVideoSource macro). The Video Format dialog box controls selection of the digitized video frame dimensions and image-depth, and compression options of the captured video. If the dialog box is supported by a video capture driver, you can display and update it by using the WM_CAP_DLG_VIDEOFORMAT message (or the capDlgVideoFormat macro). The Video Display dialog box controls the appearance of the video on the monitor during capture. The controls in this dialog box have no effect on the digitized video data, but they might affect the presentation of the digitized signal. For example, capture devices that support overlay might allow altering hue and saturation, key color, or alignment of the overlay. If the dialog box is supported by a video capture driver, you can display and update it by using the WM_CAP_DLG_VIDEODISPLAY message (or the capDlgVideoDisplay macro). The Video Compression dialog box controls the post-capture video compression attributes. If the dialog box is supported by a video capture driver, you can display and update it by using the WM_CAP_DLG_VIDEOCOMPRESSION message (or the capDlgVideoCompression macro). A capture driver can implement two methods for viewing an incoming video stream: preview mode and overlay mode. If a capture driver implements both methods, the user can choose which method to use. Preview mode transfers digitized frames from the capture hardware to system memory and then displays the digitized frames in the capture window by using graphics device interface (GDI) functions. Applications might decrease the preview rate when the parent window loses focus, and increase the preview rate when the parent window gains focus. This action improves general system responsiveness because the preview operation is processor intensive. There are three messages to control the preview operation. - Use the WM_CAP_SET_PREVIEW message to enable or disable preview mode by sending the (or the capPreview macro) to a capture window. - Use the WM_CAP_SET_PREVIEWRATE message (or the capPreviewRate macro) to set the rate at which frames are displayed in preview mode - Use the WM_CAP_SET_SCALE message (or the capPreviewScale macro) to enable or disable scaling of the preview video. When preview and scaling are both enabled, the captured video frame is stretched to the dimensions of the capture window. Enabling preview mode automatically disables overlay mode. Overlay mode is a hardware function that displays the contents of the capture buffer on the monitor without using CPU resources. You can enable and disable overlay mode by sending the WM_CAP_SET_OVERLAY message (or the capOverlay macro) to a capture window. Enabling overlay mode automatically disables preview mode. You can also set the scroll position of the video frame within the client area of the capture window for preview mode or overlay mode by sending the WM_CAP_SET_SCROLL message (or the capSetScrollPos macro) to a capture window. You can retrieve the structure that specifies the video format or the size of that structure by sending the WM_CAP_GET_VIDEOFORMAT message (or the capGetVideoFormat and capGetVideoFormatSize macros) to a capture window. You can set the format of captured video data by sending the WM_CAP_SET_VIDEOFORMAT message (or the capSetVideoFormat macro) to a capture window. The CAPTUREPARMS structure contains the control parameters for streaming video capture. This structure controls several aspects of the capture process, and allows you to perform the following tasks: - Specify the frame rate. - Specify the number of allocated video buffers. - Disable and enable audio capture. - Specify the time interval for the capture. - Specify whether an MCI device (VCR or videodisc) is used during capture. - Specify keyboard or mouse control for ending streaming. - Specify the type of video averaging applied during capture. You can retrieve the current capture settings within the CAPTUREPARMS structure by sending the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro) to a capture window. You can set one or more current capture settings by updating the appropriate members of the CAPTUREPARMS structure and then sending the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro) and CAPTUREPARMS to a capture window. You can retrieve the current capture format for audio data or the size of the audio format structure by sending the WM_CAP_GET_AUDIOFORMAT message (or the capGetAudioFormat and capGetAudioFormatSize macros) to a capture window. The default audio capture format is mono, 8-bit, 11 kHz PCM (Pulse Code Modulation). When you retrieve the format by using WM_CAP_GET_AUDIOFORMAT, always use the WAVEFORMATEX structure. You can set the capture format for audio data by sending the WM_CAP_SET_AUDIOFORMAT message (or the capSetAudioFormat macro) to a capture window. When setting the audio format, you can pass a pointer to a WAVEFORMAT, WAVEFORMATEX, or PCMWAVEFORMAT structure, depending on the specified audio format. AVICap, by default, routes video and audio stream data from a capture window to a file named CAPTURE.AVI in the root directory of the current drive. You can specify an alternate filename by sending the WM_CAP_FILE_SET_CAPTURE_FILE message (or the capFileSetCaptureFile macro) to a capture window. This message specifies the filename; it does not create, allocate, or open the file. You can retrieve the current capture filename by sending the WM_CAP_FILE_GET_CAPTURE_FILE message (or the capFileGetCaptureFile macro) to a capture window. If the user wants to save captured data, the application should save the contents of the capture file to another file by using the WM_CAP_FILE_SAVEAS message (or the capFileSaveAs macro). This message does not change the name or contents of the capture file. Your application must specify a name for the new file because the capture file retains its original filename. Typically, a capture file is preallocated for the largest capture segment anticipated, and only a portion of it might be used to capture data. This message copies only the portion of the capture file containing the capture data. Preallocating disk space for the capture file builds a file of a specified size on the disk before the start of a capture operation. Preallocating a capture file reduces the processing required while capture is in progress and results in fewer dropped frames. You can preallocate a capture file by using the WM_CAP_FILE_ALLOCATE message (or the capFileAlloc macro). Typically, your application should preallocate enough disk space to contain the largest capture file anticipated. Preallocating disk space does not restrict the size of the captured file. The file size is automatically enlarged if the captured data exceeds the allocated space. Subsequent write operations to the capture file reuse the portions of disk space allocated for the file, preserving the size and fragmentation of the file. You can also improve capture performance by defragmenting the capture file. To defragment the file, use a defragmentation utility such as Disk Defragmenter. If you use a defragmented capture file and later enlarge it, you should defragment the enlarged file. Enlarging a defragmented capture file can fragment the expanded portion of the file and reduce performance in the capture operation. You might also improve performance by using an uncompressed disk for video capture. Compressing data during capture can limit capture throughput to the disk. An application can reserve a permanent capture file to eliminate the time required to preallocate and defragment a file each time it is started. Because a capture file can require considerable disk space, and preallocating a capture file removes all data from an existing capture file, an application should let the user decide if the file is permanent or temporary. Each AVI file uses an index of a specified size to locate video and audio data chunks within the file. An entry in the index locates one video frame or waveform-audio buffer. Consequently, the value of the index size indirectly sets the upper limit on the number of frames that can be captured in a file. You can retrieve the current index size by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). The current index size is stored in the dwIndexSize member of the CAPTUREPARMS structure. You can specify a new index size as the value of dwIndexSize and then send the updated CAPTUREPARMS structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro). The default index size is 34,952 entries (allowing 32K frames and a proportional number of audio buffers). The chunk granularity is a logical block size for an AVI file that is used for writing and retrieving audio and video data chunks. When writing audio and video chunks to disk, AVICap adds filler chunks (RIFF "JUNK" chunks) as necessary to fill each logical block of data. You can retrieve the current chunk granularity setting by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). The current chunk granularity is stored in the wChunkGranularity member of the CAPTUREPARMS structure. You can specify a new chunk granularity as the value of wChunkGranularity and then send the updated CAPTUREPARMS structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro). You can also specify zero for this member to set the chunk granularity to the sector size of the disk. The buffers used with video capture reside in the memory heap. The number of buffers used in a capture operation can vary and depend on the value of the wNumVideoRequested member of the CAPTUREPARMS structure and available system memory. You can retrieve the current value of requested video buffers by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). The current requested number of video buffers is stored in the wNumVideoRequested member of the CAPTUREPARMS structure. You can request the placement and number of buffers by updating this member, and then sending the updated CAPTUREPARMS structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro). You can control the audio portion of a capture operation in three ways: - Include or exclude audio from the capture operation. - Request a specific number of audio buffers. - Request that audio buffers be a specific size. You can retrieve the settings for audio buffers by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). The fCaptureAudio member of the CAPTUREPARMS structure specifies whether audio is included or excluded from the capture operation. The current requested number of audio buffers is stored in the wNumAudioRequested member, and the current audio buffer size is stored in the dwAudioBufferSize member. You can specify whether to include audio capture, specify the size and number of audio buffers by updating these members, and send the updated CAPTUREPARMS structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro). By default, audio is included in the capture operation, and four audio buffers are allocated. The default value of fCaptureAudio is TRUE. The default buffer size (the value of dwAudioBufferSize) can contain 0.5 seconds of audio data or 10K, whichever is greater. If you want to individually specify the frames to capture in a video stream, you can control the sequence by using the WM_CAP_SINGLE_FRAME_OPEN, WM_CAP_SINGLE_FRAME, and WM_CAP_SINGLE_FRAME_CLOSE messages (or the capCaptureSingleFrameOpen, capCaptureSingleFrame, and capCaptureSingleFrameClose macros). Typically, these messages are used to create animation by appending individual frames to the capture file. WM_CAP_SINGLE_FRAME_OPEN opens a file for a manually driven capture operation. WM_CAP_SINGLE_FRAME captures an individual frame and appends it to the capture file. WM_CAP_SINGLE_FRAME_CLOSE closes the file used for manual frame capture. (Note: This capture method does not support simultaneous audio capture with video capture). If you want to capture a single frame as a still image, you can use the WM_CAP_GRAB_FRAME_NOSTOP or WM_CAP_GRAB_FRAME message (or the capGrabFrameNoStop or capGrabFrame macro) to capture the digitized image in an internal frame buffer. You can freeze the display on the captured image by using WM_CAP_GRAB_FRAME. Otherwise, use WM_CAP_GRAB_FRAME_NOSTOP. Once captured, you can copy the image for use by other applications. You can copy an image from the frame buffer to the clipboard by using the WM_CAP_EDIT_COPY message (or the capEditCopy macro). You can also copy the image from the frame buffer to a device-independent bitmap (DIB) by using the WM_CAP_FILE_SAVEDIB message (or the capFileSaveDIB macro). Your application can also use the two single-frame capture messages to edit a sequence frame by frame, or to create a time-lapse photography sequence. You can use capture services without writing the data to a disk file by using the WM_CAP_SEQUENCE_NOFILE message (or the capCaptureSequenceNoFile macro). This message is useful only in conjunction with callback functions that allow your application to use the video and audio data directly. For example, videoconferencing applications might use this message to obtain streaming video frames. The callback functions would transfer the captured images to the remote computer. MCI devices augment the capture operation in real-time capture and step-frame capture. You can specify the MCI device, such as a videodisc or video-cassette recorder (VCR), acting as the video source for your capture operation by using the WM_CAP_SET_MCI_DEVICE message (or the capSetMCIDeviceName macro) and specifying the name of the device. You can also retrieve the device name currently set by using the WM_CAP_GET_MCI_DEVICE message (or the capGetMCIDeviceName macro). In real-time capture, the capture window synchronizes the capture operation and compensates for delays associated with positioning the MCI video source and initializing the resources (such as capture buffers) required for capturing data. The capture window expects a valid MCI video device to be installed in the system for capturing data this way. Specifications for controlling an MCI device are stored in the members of the CAPTUREPARMS structure. MCI-compatible video sources include VCRs and laserdiscs. If the fMCIControl member of this structure is set to TRUE, the capture window coordinates MCI operation. The capture window uses the parameters specified in the dwMCIStartTime and dwMCIStopTime members to obtain the starting and stopping positions, in milliseconds, of the sequence. If the value of fMCIControl is FALSE, the video source is not treated as an MCI device and the contents of dwMCIStartTime and dwMCIStopTime are ignored. You can use Media Player to quickly verify that an MCI video device is properly connected to the system. Playing a device with Media Player verifies that the MCI configuration for the device is correct. If an image appears on the video display, the video source is connected properly to the capture hardware. In step-frame capture, the capture window synchronizes the capture operation and compensates for the delays associated with positioning the MCI video source and initializing the resources required for capturing data. In addition, the capture window ensures that no frames are dropped; it steps through the video frames individually, ensuring that the frame is captured and stored before capturing the next frame in the video stream. Specifications for controlling step-frame capture are stored in the members of the CAPTUREPARMS structure. Step-frame capture uses the following members in addition to the members used for real-time capture: fStepMCIDevice, fStepCaptureAt2x, and wStepCaptureAverageFrames. If the fStepMCIDevice member is set to TRUE, the capture window coordinates step-frame capture. The capture window uses the parameters specified in the dwMCIStartTime and dwMCIStopTime members for the starting and stopping positions, in milliseconds, of the sequence. The capture window uses fStepCaptureAt2x to determine if the capture hardware should capture video frames at twice the normal resolution and uses wStepCaptureAverageFrames to specify the number of times each frame in the capture operation is sampled. If fStepMCIDevice is FALSE, real-time capture is used instead of step-frame capture and the contents of fStepCaptureAt2x, and wStepCaptureAverageFrames are ignored. If a step-frame capture is specified and fStepCaptureAt2x is set to TRUE, the capture hardware captures at twice the specified resolution. (The resolutions of both the height and width are doubled.) The software interpolates the pixels in the higher resolution image to produce the image at the specified resolution. This form of averaging can improve the edge definition of images in a frame. You can enable this option if the hardware does not support hardware-based decimation and you are capturing in the RGB format. Note: If your hardware supports hardware-based decimation, it can capture samples at a higher rate than specified and use these additional samples to obtain color definitions that are more consistent with the original image. The additional samples are discarded after they are used, and the hardware passes samples to the capture driver at the specified rate. If a step-frame capture is specified, the wStepCaptureAverageFrames member specifies the number of times a frame is sampled when creating a frame based on the average sample. This averaging technique reduces the random digitization noise appearing in a frame. A typical value for the number of averages is 5. For more information about MCI, see MCI. One way to measure video quality is to limit the number of captured frames dropped during the capture operation. When streaming capture has finished, the quality value is compared with the ratio of dropped frames to total frames. If the percentage of dropped frames is greater than the value of the wPercentDropForError member of the CAPTUREPARMS structure, AVICap sends an error message to the error callback function if it is installed. You can retrieve the current limit of dropped frames (expressed as a percentage) by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). You can set a new limit by specifying a percentage as the value of the wPercentDropForError member of the CAPTUREPARMS structure, and then sending the updated structure to the capture window by using the WM_CAP_SET_SEQUENCE_SETUP message (or the capCaptureSetSetup macro). The default value of wPercentDropForError is 10 percent. You can retrieve the current value of the user-initiated capture flag by using the WM_CAP_GET_SEQUENCE_SETUP message (or the capCaptureGetSetup macro). The value of the flag is stored in the fMakeUserHitOKToCapture member of the CAPTUREPARMS structure. You can provide the user with precise control over when to start a capture session by setting this member to TRUE. AVICap displays a dialog box after allocating all video and audio buffers for a capture session. This lets the user eliminate capture delays because of software initialization. If your application uses a small number of video buffers, this dialog box is probably unnecessary. The default value is FALSE. Initially, if the video capture format requires a palette, the capture window uses the palette supplied by the capture driver. This palette might consist of gray-scale values for black-and-white reproduction, or a broad selection of color values. You can retrieve an existing palette to replace the default palette by using the WM_CAP_PAL_PASTE or WM_CAP_PAL_OPEN message (or the capPalettePaste or capPaletteOpen macro). Alternatively, you can create a custom palette to replace the default palette by using the WM_CAP_PAL_AUTOCREATE or WM_CAP_PAL_MANUALCREATE message (or the capPaletteAuto or capPaletteManual macro). After you replace the default palette, the capture window and driver use the replacement palette until you create or open another palette. The WM_CAP_PAL_AUTOCREATE or WM_CAP_PAL_MANUALCREATE message creates an optimized palette based on the current video input. This custom palette gives a video sequence the best color fidelity because it is based on colors that exist in the sequence. The capture window creates a three-dimensional histogram of the colors it samples. It reduces the number of colors by examining the absolute error between adjacent colors and consolidating those with the smallest error value. When sending WM_CAP_PAL_AUTOCREATE, you must specify the number of frames for AVICap to sample, and specify the size of the color palette. When specifying the number of frames, include enough frames to ensure that all colors in the sequence are sampled. You can sample the current frame by using WM_CAP_PAL_MANUALCREATE. By using this message with several manually selected frames, you can create a palette that contains the colors you want to appear in the palette. A palette can contain up to 256 colors. If you merge palettes or if the video sequence is to be displayed simultaneously with other video or images, you should use a smaller color selection so that colors from each image or video clip can coexist. You save a new palette by using the WM_CAP_PAL_SAVE message (or the capPaletteSave macro) and later retrieve it by using the WM_CAP_PAL_OPEN message. You can save a palette for post-processing of the palette or for use in another application. You can paste a palette from the clipboard into the capture window by using the WM_CAP_PAL_PASTE message. The capture window passes the palette to the capture driver. Other applications can copy palettes to the clipboard. You can also copy a palette to the clipboard by using the WM_CAP_EDIT_COPY message (or the capEditCopy macro). This message copies the video frame buffer, including the palette, onto the clipboard. You can insert information chunks, such as text or custom data, in an AVI file by using the WM_CAP_FILE_SET_INFOCHUNK message (or the capFileSetInfoChunk macro). You can also use this message to clear information chunks from an AVI file. You can associate data with a capture window by using the WM_CAP_GET_USER_DATA and WM_CAP_SET_USER_DATA messages (or the capGetUserData and capSetUserData macros). You can retrieve a LONG data value by using the WM_CAP_GET_USER_DATA message and set a LONG data value by using the WM_CAP_SET_USER_DATA message. Your application can register callback functions with a capture window to have it notify your application when the status changes, when errors occur, when video frame and audio buffers become available, and to yield during streaming capture. The following messages set the callback function. Message Description WM_CAP_SET_CALLBACK_CAPCONTROL Specifies the callback function in the application called to give precise control over capture start and end. You can also use the capSetCallbackOnCapControl macro to send this message. WM_CAP_SET_CALLBACK_ERROR Specifies the callback function in the application called when an error occurs. You can also use the capSetCallbackOnError macro to send this message. WM_CAP_SET_CALLBACK_FRAME Specifies the callback function in the application called when preview frames are captured. You can also use the capSetCallbackOnFrame macro to send this message. WM_CAP_SET_CALLBACK_STATUS Specifies the callback function in the application called when the status changes. You can also use the capSetCallbackOnStatus macro to send this message. WM_CAP_SET_CALLBACK_VIDEOSTREAM Specifies the callback function in the application called during streaming capture when a new video buffer becomes available. You can also use the capSetCallbackOnVideoStream macro to send this message. WM_CAP_SET_CALLBACK_WAVESTREAM Specifies the callback function in the application called during streaming capture when a new audio buffer becomes available. You can also use the capSetCallbackOnWaveStream macro to send this message. WM_CAP_SET_CALLBACK_YIELD Specifies the callback function in the application called when yielding during streaming capture. You can also use the capSetCallbackOnYield macro to send this message. The following topics describe the different callback functions, the notifications sent to the functions, and their uses.