A Video Capture Control for Visual Basic 3.0
|
|
| CAPWNDX.VBX | |
|
A Video Capture Control for Visual Basic 3.0 | |
|
|
This document is derived from that in the July 1996 CD-ROM edition of the Microsoft Developer Network ( MSDN ) Library. It has been formatted to make it look presentable, and usable, as a web page, with dead-end links and references removed; I apologise if there are any formatting, or other, errors I haven't spotted, but, as you will probably be able to tell, putting this all together has been a major task. Any errors in the documentation regarding the operation of the Control are those which are present in the original from Microsoft, of which I am unaware, and can do nothing about.
|
|
IndexCAPWNDX.VBX
Audio Control Capture Control Single Frame Capture Control Background Capture Specifying the Capture file Selecting the Capture Driver Capturing from MCI Devices Copying a Frame onto the Clipboard Overlay Control Palette Control Preview Video Configuring Video Capture Attributes Obtaining Status and Error Information Autosizing the Displayed Video Control Position properties Visual Basic Control property Events
AudioChannels AudioRate AutoSize BorderStyle CanOverlay Capture CaptureAbort CaptureAudio CaptureDOSMem CaptureFile CaptureFileSize CaptureHitOK CaptureLimit CaptureSave CaptureStop CaptureUseLimit Connect DriverName DriverNum DriverVersion EditCopy Error Error Event ErrorNum Height Left MCIDeviceEnable MCIDeviceName MCIStartMS MCIStepCapture MCIStopMS Name Overlay PalCreate PalCreateManual PalNumColors PalNumFrames PalOpen PalSave Preview PreviewRate SingleFrame SingleFrameClose SingleFrameOpen Status Status Event Top VideoCompressionDlg VideoDisplayDlg VideoFormatDlg VideoRate VideoSourceDlg Visible Width Yield
CAPWNDX supports four forms of video capture: streaming video capture, streaming video capture with MCI control, step video capture with MCI control, and single-frame capture. Streaming video capture acquires data when your application starts recording. You can use any video source supported by your video-capture hardware for streaming capture. The two other forms of video capture control MCI devices to acquire the data at a specified time interval from the prerecorded media ( such as a videodisc or videotape ). Streaming video capture positions the MCI device and acquires the data nonstop over the specified time period. Step capture with MCI control positions the MCI device and acquires the data frame-by-frame over the specified time period. Capturing data frame-by-frame lets the hardware and software control the pace of video capture. This eliminates dropped frames when the video-capture rate is greater than the capture system can support in real time. Single-frame capture lets an application capture a single frame at a time.
CAPWNDX uses AVICAP.DLL to access the AVICap window class when creating a capture window. Most of the AVICap window capabilities are available through CAPWNDX.
Use the CaptureDOSMem property to designate the memory ( memory under the one megabyte boundary or extended memory ) used during capture. The memory used can influence the capture rate.
Use the CaptureHitOK property if you need to start capturing at a specific instant. Data capture does not actually start immediately after setting the Capture property. The delay occurs as the capture software initializes and allocates the memory used by the capture buffers.
The CaptureUseLimit property determines if capturing stops after a specified number of seconds, or if it stops when you press the ESC key or a mouse button. If the property is set to True, the CaptureLimit property specifies the number of seconds allocated for data capture.
The VideoRate property specifies the frame rate used when capturing video. If you specify a rate higher than the system can sustain, it inserts dummy frames into the video stream.
Because of the time involved in creating a defragmented capture file, you might want to reserve this file for capturing data. You can then use the CaptureSave property to copy the contents of the capture file to a file with a new name. Copying captured data to a new file lets you reuse the preallocated, and possibly defragmented, capture file for a subsequent capture. This property copies only the data from the capture file, so the copied file might end up being smaller than the capture file. Thus, you can keep your capture file very large, preallocated, and defragmented, and copy each capture to a fresh file.
To determine name and version of a driver, set the DriverNum property to a driver number. The DriverName and DriverVersion properties are then automatically set to text strings describing that driver. If the text strings are empty, a driver is not available. Your application can also use the DriverNum property to check if a driver is not available. This property is set to -1 if a driver is not available.
You can extract a palette from selected frames with the PalCreateManual property. Every time you set this property to True, the palette of the current frame is added to the accumulated histogram of palettes representing the palettes you have captured. Setting PalCreateManual to False lets CAPWNDX custom control create an optimized palette from the histogram.
The dialog boxes displayed are dependent on the capture driver and display format used. You might have to properly set the options in one or all of the dialog boxes before you can successfully capture data.
Audio Control Capture Control Single Frame Capture Control Background Capture Specifying the Capture Files Selecting and Connecting the Capture Driver Capturing from MCI devices Copying a Frame onto the Clipboard Overlay Control Palette Control Preview Video Obtaining status and error information Displaying video-capture dialog boxes Autosizing of the displayed video Window-position properties Visual Basic control property Events [form.][ctlname.]AudioBits[=bits%]
The parameter bits% corresponds to the quantization or bit depth used for audio capture. This is typically 8 or 16 for 8-bit or 16-bit audio. Capture might not work if you set this to a value not supported by your audio hardware. The default value is 8.
Data Type: Integer [form.][ctlname.]AudioChannels[=channel%]
The parameter channel% corresponds to the number of channels used for audio capture. This is 1 for mono or 2 for stereo. Capture might not work if you set this to a value not supported by your audio hardware. The default value is 1.
Data Type: Integer [form.][ctlname.]AudioRate[=rate%]
The parameter rate% corresponds to the sample rate used for audio capture. Typically, this is set to 11025, 22050, or 44100 for 11K, 22K, and 44K sampling rates. Capture might not work if you set this to a value not supported by your audio hardware. The default value is 11025.
Data Type: Integer
[form.][ctlname.]AutoSize[={True | False}]
The AutoSize property settings are False and True.
False: The control is set by the user and the video is stretched to the size of the control. The size of the image captured is specified in the format dialog box.
True: The control is the size of the video image captured. The video size is usually set by the Format dialog box displayed by using the VideoFormatDlg property. Default Setting
Data Type: Integer ( Boolean )
[form.][ctlname.]BorderStyle[={True | False}]
The BorderStyle property settings are False and True.
False: Inhibits display of a border around the control.
Data Type: Integer ( Boolean ) [form.][ctlname.]CanOverlay
The CanOverlay property returns the following settings:
False: Indicates driver does not support overlay.
Data Type: Integer ( Boolean )
[form.][ctlname.]Capture[={True | False}]
The Capture property settings are False and True.
False: Inhibits capturing. Default Setting
True: Starts capturing data. Other properties can be set to give you control over the capture, or you can just use the defaults.
Data Type: Integer ( Boolean ) [form.][ctlname.]CaptureAbort={True | False}
Use this property to stop background video capture enabled by the Yield property. If using MCIStepCapture, no audio will be captured. The CaptureAbort property settings are False and True.
False: Enables data capture. Default Setting
Data Type: Integer ( Boolean )
[form.][ctlname.]CaptureAudio[={True | False}]
The CaptureAudio property settings are False and True.
False: Inhibits capturing of audio data.
Data Type: Integer ( Boolean )
[form.][ctlname.]CaptureDOSMem[={True | False}]
Set the CaptureDOSMem property to True if you want to use memory under the 1-megabyte boundary for the capture buffers. Keeping the capture buffers in this memory usually provides the highest performance for capturing to disk. ( The limited memory under 1 megabyte cannot hold a large enough capture sequence to make it practical to capture to this memory. ) If possible, free lower memory so it can be used for capture buffers. To free lower memory, avoid loading unnecessary device drivers, such as network drivers, or memory-resident applications. Device drivers and memory-resident applications that you must have loaded should be loaded into high memory.
Set the CaptureDOSMem property to False if you want to use extended memory for the capture buffers. If extended memory can hold your entire sequence, this method of capture provides the highest performance. However, once extended memory is full, CAPWNDX starts copying the data to the disk capture file which decreases the capture rate. Capturing to disk using extended memory is usually a slower process than capturing to disk using memory under the 1 megabyte boundary.
The CaptureDOSMem property settings are False and True.
False: If False, the VBX uses extended memory for capturing. Use this option if your sequence will fit into memory and transferring data to disk interferes with the capture rate.
True: Enables use of memory below the 1 megabyte boundary. If True, the VBX captures into fast MS-DOS memory, and writes it to the disk. Use this option if disk transfers do not interfere with the data capture rate desired. Default Setting
Data Type: Integer ( Boolean ) [form.][ctlname.]CaptureFile[=name$]
The parameter name$ is the name of the file. The default name is \CAPTURE.AVI. Data Type: String
[form.][ctlname.]CaptureFileSize[=filesize%]
The parameter filesize% corresponds to the size of the capture file in kilobytes. For example, 5000 is used for a 5-megabyte file. Preallocating a capture file large enough to hold the movie being captured will improve the capture throughput to disk. Defragmenting the file before you start capturing data and using an uncompressed disk will also increase the data throughput to disk ( that is, it lets your application capture data at the highest frame rate or largest image size possible ).
Data Type: Integer
[form.][ctlname.]CaptureHitOK[={True | False}]
Set this value to True if you need to start capturing at a specific instant, because capture does not actually start immediately after setting the Capture property. The CaptureHitOK property settings are False and True.
False: Starts capturing data after setting the Capture property to True. Default Setting Data Type: Integer ( Boolean )
[form.][ctlname.]CaptureLimit=seconds%
The parameter seconds% corresponds to the number of seconds allocated for data capture.
Data Type: Integer [form.][ctlname.]CaptureSave=name$
The parameter name$ is the name of the new file. Copying captured data to a new file lets you reuse the preallocated, and possibly defragmented, capture file for a subsequent capture. Reusing the capture file eliminates the time required for preallocating and defragmenting a new file. This property copies only the data from the capture file, so the copied file might end up being smaller than the capture file. Thus, you can keep your capture file very large, preallocated, and defragmented, and copy each capture to a fresh file.
Data Type: String [form.][ctlname.]CaptureStop={True | False}
When used with MCIStepCapture, CaptureStop lets the driver capture the audio associated with the video sequence captured. The CaptureStop property settings are False and True.
False: Enables data capture. Default Setting
True: Stops background video capture. For MCI step capture, audio will then be captured if enabled.
Data Type: Integer ( Boolean )
[form.][ctlname.]CaptureUseLimit[={True | False}]
The CaptureUseLimit property settings are False and True.
False: Stops capture when the ESC key or mouse button is pressed. Default Setting
True: Stops capture after a specified number of seconds set with the CaptureLimit property.
Data Type: Integer ( Boolean )
[form.][ctlname.]Connect[={True | False}]
Once you have specified a driver by setting the DriverNum property, you set this property to True to connect to that driver. You can then start capturing data. If the connection fails, the property value returns False. Starting Capture automatically makes this connection for you. The Connect property settings are False and True.
False: Indicates a driver connection failed.
Data Type: Integer ( Boolean )
[form.][ctlname.]DriverName If a driver does not exist, this property returns an empty string.
Data Type: String [form.][ctlname.]DriverNum[=driver%]
The parameter driver% specifies a driver number. The driver number corresponds to the indexes of the msvideo keywords found in the [drivers] section of the SYSTEM.INI file. Zero represents the first driver. MCIWNDX sets the DriverNum property to -1 if the parameter is invalid.
To determine the name of a driver, set this property to a driver number. The DriverName and DriverVersion properties are then automatically set to text strings describing that driver. If the text strings are empty, a driver is not available.
Data Type: Integer
[form.][ctlname.]DriverVersion
This property returns the version of the capture driver in a string format. If a driver does not exist, it returns an empty string.
Data Type: String
[form.][ctlname.]EditCopy={True | False}
The EditCopy property settings are False and True.
False: Inhibits copying the current frame onto the Clipboard. Default Setting Data Type: Integer ( Boolean )
[form.][ctlname.]Error
If an error has not occurred, this property returns an empty string. Data Type: String
Sub CapWnd_Error ()
Check the Error property for a text string indicating the error. Your error function will be called whenever an error occurs so you can display the error.
[form.][ctlname.]ErrorNum
If an error has not occurred, this property returns zero. Data Type: Integer
[form.][ctlname.]Height=[height%]
The value returned is the control height in twips.
The minimum value for this property is one. With Visual Basic version 2.0, setting it to zero terminates the application if an on-error statement is not used.
Data Type: Integer [form.][ctlname.]Left=[left%]
The left% value returned is the control position in twips. Data Type: Integer
[form.][ctlname.]MCIDeviceEnable[={True | False}]
The MCIDeviceEnable property settings are False and True.
False: Inhibits use of an MCI device for video capture. Default Setting Data Type: Integer ( Boolean )
[form.][ctlname.]MCIDeviceName[=name$]
The parameter name$ is the name of the MCI device ( for example videodisc, videodisc1, or vcr ).
Data Type: String
[form.][ctlname.]MCIStartMS[=time&]
The parameter time& is the starting time of the MCI sequence in milliseconds. Data Type: Long
[form.][ctlname.]MCIStepCapture[={True | False}]
When this property is set to True, capture does not occur in real time. The driver steps the MCI device to capture each frame. Capturing data this way lets the computer finish any time-intensive tasks associated with a frame before it captures the next frame. Step capture does not change the playback rate of the video sequence. Step capture can improve playback quality because it eliminates dropping frames during capture but requires more time to capture the data. Audio is not captured simultaneously with video. The capture operation captures audio after video is captured. The MCIStepCapture property settings are False and True.
False: Prevents the driver from slowing the capture sequence to process captured video.
True: Lets the driver capture data frame by frame and delay the capture process if necessary.
Data Type: Integer ( Boolean )
[form.][ctlname.]MCIStopMS[=time&]
The parameter time& corresponds to the end of the MCI sequence in milliseconds. Data Type: Long
[form.][ctlname.]Name=stringexpression$
The parameter stringexpression$ specifies the name of the control. Use this name as the [ctrlname] when specifying a control. This property is available only at design time.
Data Type: String
[form.][ctlname.]Overlay[={True | False}]
Use the CanOverlay property to determine if a device supports overlay.
The Overlay property settings are False and True.
False: Inhibits video overlay capabilities. Default Setting Data Type: Integer ( Boolean )
[form.][ctlname.]PalCreate={True | False}
Unless you specify a palette, captured 8-bit ( palettized ) images use default palettes. Typically, these are black-and-white or dithered palettes. This property creates a palette with the colors optimized for the video you are capturing. To create a palette, set this property to True. This examines the incoming video and makes an optimal palette based on the values specified for the PalNumColors and PalNumFrames properties. The PalCreate property settings are False and True.
False: Inhibits creating a palette.
Data Type: Integer ( Boolean )
[form.][ctlname.]PalCreateManual={True | False}
Each time PalCreateManual is set True, the palette of the current frame is added to an accumulated total of the histogram of color values. When set False, CAPWNDX creates an optimized palette from the color values in the histogram and CAPWNDX clears the histogram. The number of colors in the palette is set with the PalNumColors property. CAPWNDX uses the resulting palette to replace the palette associated with the video-capture driver. Unless you specify a palette, captured 8-bit ( palettized ) images use default palettes. Typically, these are black-and-white or dithered palettes. The PalCreateManual property settings are False and True.
False: If PalCreateManual has not been previously set True, inhibits creating a palette. If PalCreateManual has been set True, creates a palette from the accumulated total of the color histogram.
True: Add the current frame palette to the histogram. Set PalCreateManual to True for each frame palette you want added to the histogram.
Data Type: Integer ( Boolean )
[form.][ctlname.]PalNumColors[=colors%]
The parameter colors% corresponds to the number of colors in the palette. Values can range from 2 to 256. The default is 256.
You will most likely want to use 256 colors, because this is the highest number of colors an application playing your movie can use, and this will create an identity palette. If you will be showing images from several captured movies at the same time, you might want to use a smaller number of colors to create a palette for capturing each movie. During playback, if the total number of palette entries used by all movies shown simultaneously is less than 256, you can avoid palette contention.
Data Type: Integer
[form.][ctlname.]PalNumFrames
[=frames%]
The parameter frames% corresponds to the number of frames examined. If your video changes scenes often, you might want to specify a value large enough to include the entire sequence you will be capturing. If colors used throughout the video are consistent, you only need to examine a few frames to determine the color palette required to support the movie. The default value is 20.
Data Type: Integer [form.][ctlname.]PalOpen=name$
The parameter name$ specifies the name of the palette file used as the palette source.
Data Type: String [form.][ctlname.]PalSave=name$
The parameter name$ specifies the name of the palette file used to save the palette. Data Type: String
[form.][ctlname.]Preview[={True | False}]
Preview mode uses the frame rate specified by the PreviewRate property. Setting Preview to True disables the overlay mode. The Preview property settings are False and True.
False: Disables preview mode. Default Setting
Data Type: Integer ( Boolean )
[form.][ctlname.]PreviewRate[=rate%]
The parameter rate% corresponds to the frame rate. The units are frames per second. The default value is 15.
Data Type: Integer
[form.][ctlname.]SingleFrame={True | False}
Use the SingleFrameOpen property to prepare the system for the single-frame capture mode. Use the SingleFrameClose property to terminate the single-frame capture mode. Until single-frame capture is terminated with the SingleFrameClose property, each time SingleFrame is set True, a frame is captured and appended to the current capture file. The SingleFrame property settings are False and True.
False: Inhibits single-frame capture. Default Setting
Data Type: Integer ( Boolean ) [form.][ctlname.]SingleFrameClose={True | False}
Use the SingleFrameOpen property to prepare the system for the single-frame capture mode, and use the SingleFrame property to capture a single frame. The SingleFrameClose property settings are False and True.
False: Indicates single-frame capture mode is controlled by SingleFrameOpen. Default Setting Data Type: Integer ( Boolean )
[form.][ctlname.]SingleFrameOpen={True | False}
Use the SingleFrame property to capture a single frame and use the SingleFrameClose property to end the single-frame capture mode. The SingleFrameOpen property settings are False and True.
False: Inhibits single-frame capture. Default Setting Data Type: Integer ( Boolean )
[form.][ctlname.]Status Data Type: String
Sub CapWnd_Status ()
Check the Status property for a text string indicating the new status. Your status function will be called whenever the status changes so you can display the new status.
[form.][ctlname.]Top[=top%]
The top% value returned is the control position in twips. Data Type: Integer
[form.][ctlname.]VideoCompressionDlg={True | False}
The dialog box displayed is dependent on the data format. You might have to properly set the options in one or all of the video-capture dialog boxes before you can successfully capture data. The VideoCompressionDlg property settings are False and True.
False: Inhibits display of the dialog box. Default Setting
Enabling video compression can limit the streaming capture rate for your system. Your system must be able to compress a captured frame before it must capture the next frame to avoid dropping frames.
Data Type: Integer ( Boolean )
[form.][ctlname.]VideoDisplayDlg={True | False}
The dialog box displayed is dependent on the capture driver used, and a driver might not have this dialog box. You might have to properly set the options in one or all of the video capture dialog boxes before you can successfully capture data. The VideoDisplayDlg property settings are False and True.
False: Inhibits display of the dialog box. Default Setting Data Type: Integer ( Boolean )
[form.][ctlname.]VideoFormatDlg={True | False}
The dialog box displayed is dependent on the capture driver used, and a driver might not have this dialog box. You might have to properly set the options in one or all of the video capture dialog boxes before you can successfully capture data. The VideoFormatDlg property settings are False and True.
False: Inhibits display of the dialog box. Default Setting Data Type: Integer ( Boolean )
[form.][ctlname.]VideoRate[=rate%]
The parameter rate% corresponds to the frame rate. Video tape runs at
30 frames per second ( for NTSC, 25 frames per second for PAL )
so to get every frame you specify 30 ( or 25 ) frames per second. However, this probably exceeds the computer’s capability when capturing data or playing back a movie in real time. Thus, you will probably use a lower value. A fast 80486 processor running at 33 MHz should be able to handle 160-by-120 images at 15 frames per second. The larger the image you are capturing ( set using the VideoFormatDlg property ) the lower the frame rate you need to use. The default value is 15.
Data Type: Integer
[form.][ctlname.]VideoSourceDlg={True | False}
The dialog box displayed is dependent on the capture driver used, and a driver might not have this dialog box. You might have to properly set the options in one or all of the video capture dialog boxes before you can successfully capture data. The VideoSourceDlg property settings are False and True.
False: Inhibits display of the dialog box. Default Setting Data Type: Integer ( Boolean )
[form.][ctlname.]Visible[={True | False}]
The Visible property settings are False and True.
False: The control is invisible.
Data Type: Integer ( Boolean ) [form.][ctlname.]Width[=width%]
The width% value returned is the control width in twips.
The minimum value for this property is one. With Visual Basic version 2.0, setting it to zero terminates the application if an on-error statement is not used.
Data Type: Integer
[form.][ctlname.]Yield[={True | False}]
If this property is True, your application and all other Windows applications execute during capture. Avoid creating reentrant conditions when this property is set True. The Yield property settings are False and True.
False: Video capture is a foreground task. Default Setting Data Type: Integer ( Boolean )
The following example, extracted from a Visual Basic capture application, initializes many of the properties defined for CAPWNDX.
| ||||||||||||||
|
|
First published sometime before Thursday the 21st of December, 2000
Last upload was on Tuesday the 23rd of September, 2003 at 19:25:58 |
